BTraitsObserver: protocol-driven unified trait observation

AGENTS.md

@@ -1,28 +1,35 @@
 # AGENTS.md — Repository Shape
 
-Broadway is a SwiftUI iOS + Mac Catalyst design system managed by **Tuist**. The Xcode project is not checked in — it is generated from `Project.swift`.
+Broadway is a SwiftUI iOS + Mac Catalyst design system: **Swift Package Manager** supplies the shared libraries (`Package.swift`), and **Tuist** generates the Xcode workspace from `Project.swift` for the catalog app, test host, and unit test bundles that link those packages.
 
 ## Directory Layout
 
 ```
-BroadwayCatalog/          # Catalog app (Sources/, Resources/, Tests/)
-BroadwayUI/               # Reusable UI component framework (Sources/, Tests/)
-BroadwayCore/             # Foundational utilities framework (Sources/, Tests/)
-BroadwayTestHost/         # Minimal test host app (Sources/)
-BroadwayTesting/          # Shared test utilities framework (Sources/)
-Project.swift             # Tuist project manifest
-Tuist.swift               # Tuist global configuration
-ide                       # Dev script (installs hooks, runs tuist generate)
-swiftformat               # Run SwiftFormat (--lint to check only)
-sync-agents               # Generate CLAUDE.md + .claude/skills from AGENTS.md
+/
+├── .githooks/              # Git hooks (pre-commit SwiftFormat lint)
+├── BroadwayCatalog/        # Catalog app (Sources/, Resources/, Tests/)
+├── BroadwayUI/             # UI framework (Sources/, Tests/)
+├── BroadwayCore/           # Core framework (Sources/, Tests/)
+├── BroadwayTestHost/       # Minimal test host app (Sources/)
+├── BroadwayTesting/        # Shared test utilities (Sources/)
+├── Plans/                  # Archived implementation plans
+├── Package.swift           # SPM: BroadwayCore, BroadwayUI, BroadwayTesting libraries
+├── Project.swift           # Tuist: apps, test host, and xctest targets using the local package
+├── Tuist.swift             # Tuist global configuration
+├── ide                     # Dev script (installs hooks, runs tuist generate)
+├── swiftformat             # Run SwiftFormat (--lint to check only)
+└── sync-agents             # Generate CLAUDE.md + .claude/skills from AGENTS.md
 ```
 
+Key root files: `Package.swift` (library products), `Project.swift` (Tuist manifest), `Tuist.swift` (Tuist config), `.mise.toml` (tool versions), `.swiftformat` (style config), `ide` and `swiftformat` (dev scripts).
+
 ## Build System
 
-- **Tuist 4+** generates the Xcode project from `Project.swift`. The `.xcodeproj` and `Derived/` are git-ignored.
+- **Swift Package Manager** (`Package.swift`) defines the **BroadwayCore**, **BroadwayUI**, and **BroadwayTesting** libraries (iOS 26 + Mac Catalyst). Library sources live under each module’s `Sources/` tree as today.
+- **Tuist 4+** generates the Xcode workspace from `Project.swift`, wires a **local package** dependency (`.relativeToRoot(".")`), and defines **BroadwayCatalog**, **BroadwayTestHost**, **BroadwayCoreTests**, **BroadwayUITests**, and **BroadwayCatalogTests**. The `.xcodeproj` / `.xcworkspace` and `Derived/` are git-ignored.
 - Tuist and SwiftFormat are version-pinned via **mise** in `.mise.toml`. Run `mise install` to install them.
 - Run `./ide` to generate the project (or `./ide -i` to run `mise exec -- tuist install` first).
-- Run `mise exec -- tuist test` to execute all tests, or `mise exec -- tuist test <SchemeName>` for a specific target.
+- Run `mise exec -- tuist test` to execute all tests (scheme **Broadway-Workspace**), or `mise exec -- tuist test <SchemeName>` for a subset. Example schemes: **BroadwayCoreTests**, **BroadwayUITests**, **BroadwayCatalog**. There is no longer a generated **BroadwayCore** scheme (the core library is built as part of the Swift package).
 
 ## Formatting
 
@@ -41,11 +48,16 @@ sync-agents               # Generate CLAUDE.md + .claude/skills from AGENTS.md
 ## Dependency Graph
 
 ```
-BroadwayCatalog (app) --> BroadwayUI (framework) --> BroadwayCore (framework)
-BroadwayTestHost (app) --> BroadwayUI --> BroadwayCore
-BroadwayTesting (framework) --> BroadwayCore
+Package.swift:
+  BroadwayUI (library) --> BroadwayCore (library)
+  BroadwayTesting (library) --> BroadwayCore (library)
 
-All framework test targets use BroadwayTestHost and depend on BroadwayTesting.
+Project.swift (Tuist):
+  BroadwayCatalog (app) --> package product BroadwayUI
+  BroadwayCatalogTests --> BroadwayCatalog, package BroadwayTesting
+  BroadwayCoreTests --> package BroadwayCore, package BroadwayTesting, BroadwayTestHost
+  BroadwayUITests --> package BroadwayUI, package BroadwayTesting, BroadwayTestHost
+  BroadwayTestHost (app) --> (no framework deps)
 ```
 
 ## Key Conventions
@@ -54,4 +66,5 @@ All framework test targets use BroadwayTestHost and depend on BroadwayTesting.
 - **Swift Testing** (`import Testing`) is used for unit tests, not XCTest.
 - Source files use `<Target>/Sources/**` globs; test files use `<Target>/Tests/**`.
 - Info.plist is auto-generated by Tuist via `infoPlist: .extendingDefault(with:)`.
-- New targets or dependencies: edit `Project.swift`.
+- New **library** code or package products: edit `Package.swift` (and folder layout under each module).
+- New **app**, **test host**, or **xctest bundle** targets: edit `Project.swift`.

BroadwayCatalog/Tests/BroadwayCatalogTests.swift

@@ -1,10 +1,4 @@
 @testable import BroadwayCatalog
 import Testing
 
-struct BroadwayCatalogTests {
-    @Test("App launches with ContentView")
-    func contentViewExists() {
-        let view = ContentView()
-        #expect(view != nil)
-    }
-}
+struct BroadwayCatalogTests {}

BroadwayCore/Sources/BContext+UITraits.swift

@@ -7,8 +7,8 @@ import UIKit
 
 /// Bridges ``BContext`` into UIKit's trait system so that it propagates
 /// automatically through the view-controller and view hierarchy.
-struct BContextTrait: UITraitDefinition {
-    static let defaultValue = BContext()
+public struct BContextTrait: UITraitDefinition {
+    public static let defaultValue = BContext()
 }
 
 extension UITraitCollection {

BroadwayCore/Sources/BContext.swift

@@ -12,26 +12,48 @@ import Foundation
 /// ``BStylesheets`` cache. Updating `traits` or `themes` replaces the
 /// stylesheet cache so subsequent lookups produce fresh instances.
 public struct BContext: Equatable, Sendable {
-    public init(traits: BTraits = .init(), themes: BThemes = .init()) {
-        self.traits = traits
+    public init(
+        traits: BTraits,
+        overrides: BTraits.Overrides = .init(),
+        themes: BThemes = .init(),
+    ) {
+        baseTraits = traits
+        traitOverrides = overrides
         self.themes = themes
-        stylesheets = BStylesheets(config: .init(traits: traits, themes: themes))
+        stylesheets = BStylesheets(
+            traits: baseTraits.merging(with: traitOverrides),
+            themes: themes,
+        )
+    }
+
+    init() {
+        self.init(traits: BTraits())
+    }
+
+    public var traitOverrides: BTraits.Overrides {
+        didSet {
+            stylesheets.updateTraits(traits)
+        }
     }
 
-    /// The current trait values (accessibility, size class, etc.).
     public var traits: BTraits {
+        baseTraits.merging(with: traitOverrides)
+    }
+
+    /// The current trait values (accessibility, size class, etc.).
+    public var baseTraits: BTraits {
         didSet {
-            stylesheets.traits = traits
+            stylesheets.updateTraits(traits)
         }
     }
 
     /// The current theme values.
     @CopyOnWrite public var themes: BThemes {
         didSet {
-            stylesheets.themes = themes
+            stylesheets.updateThemes(themes)
         }
     }
 
     /// Lazily-populated stylesheet cache, scoped to the current traits and themes.
-    @CopyOnWrite public private(set) var stylesheets: BStylesheets
+    @EquatableIgnored @CopyOnWrite public private(set) var stylesheets: BStylesheets
 }

BroadwayCore/Sources/BStylesheets.swift

@@ -12,31 +12,25 @@ import Foundation
 /// first access and cached for subsequent lookups with the same key.
 public struct BStylesheets: Equatable, @unchecked Sendable {
     /// The current trait values (accessibility, size class, etc.).
-    public var traits: BTraits {
-        get { config.traits }
-        set { config.traits = newValue }
-    }
+    private var traits: BTraits
 
     /// The current theme values.
-    public var themes: BThemes {
-        get { config.themes }
-        set { config.themes = newValue }
-    }
-
-    /// The inputs that determine stylesheet identity. Two `BStylesheets`
-    /// values are equal when their configurations match, regardless of
-    /// how much of the cache has been lazily populated.
-    var config: Config
+    private var themes: BThemes
 
-    struct Config: Equatable {
-        var traits: BTraits
-        var themes: BThemes
+    init(traits: BTraits, themes: BThemes) {
+        self.traits = traits
+        self.themes = themes
     }
 
-    // MARK: Equatable
+    /// Keeps the resolver’s trait key in sync with ``BContext/traits``.
+    /// `package` matches the monorepo `-package-name Broadway` set in Tuist (SE-0386).
+    package mutating func updateTraits(_ newTraits: BTraits) {
+        traits = newTraits
+    }
 
-    public static func == (lhs: Self, rhs: Self) -> Bool {
-        lhs.config == rhs.config
+    /// Keeps the resolver’s theme key in sync with ``BContext/themes``.
+    package mutating func updateThemes(_ newThemes: BThemes) {
+        themes = newThemes
     }
 
     // MARK: Lookup
@@ -47,26 +41,30 @@ public struct BStylesheets: Equatable, @unchecked Sendable {
     ///   a dependency cycle, or ``StylesheetError/creationFailed(type:underlying:)``
     ///   if the stylesheet's initializer throws.
     public func get<Stylesheet: BStylesheet>(_: Stylesheet.Type) throws(StylesheetError) -> Stylesheet {
-        let key = Key(stylesheet: .init(Stylesheet.self), traits: traits, themes: themes)
+        let key = Key(
+            stylesheet: .init(Stylesheet.self),
+            traits: traits,
+            themes: themes,
+        )
 
         guard let value = cache[key], let value = value.base as? Stylesheet else {
             let id = TypeIdentifier(Stylesheet.self)
 
-            let creating = _creating._unsafeUnderlyingValue
+            let creating = _creating.wrappedValue._unsafeUnderlyingValue
 
             if let cycleStart = creating.firstIndex(of: id) {
                 let path = creating[cycleStart...].map(\.debugDescription) + [id.debugDescription]
                 throw .cyclicDependency(path: path)
             }
 
-            _creating._unsafeUnderlyingValue.append(id)
-            defer { _creating._unsafeUnderlyingValue.removeLast() }
+            _creating.wrappedValue._unsafeUnderlyingValue.append(id)
+            defer { _creating.wrappedValue._unsafeUnderlyingValue.removeLast() }
 
             let context = SlicingContext(themes: themes, stylesheets: self)
 
             do {
                 let new = try Stylesheet(context: context)
-                _cache._unsafeUnderlyingValue[key] = AnyEquatable(new)
+                _cache.wrappedValue._unsafeUnderlyingValue[key] = AnyEquatable(new)
                 return new
             } catch let error as StylesheetError {
                 throw error
@@ -88,9 +86,9 @@ public struct BStylesheets: Equatable, @unchecked Sendable {
     // MARK: Cache
 
     // TODO: Eventually we should clear this out on memory warnings for sheets not accessed within 10(?) min
-    @CopyOnWrite private var cache: [Key: AnyEquatable] = [:]
+    @EquatableIgnored @CopyOnWrite private var cache: [Key: AnyEquatable] = [:]
 
-    @CopyOnWrite private var creating: [TypeIdentifier] = []
+    @EquatableIgnored @CopyOnWrite private var creating: [TypeIdentifier] = []
 
     /// Cache key combining the stylesheet type with the traits and themes
     /// that were active at creation time.

BroadwayCore/Sources/EquatableIgnored.swift

@@ -20,7 +20,7 @@ import Foundation
 /// }
 /// ```
 /// In this example, `cache` will never affect the equality of two `Example` instances.
-@propertyWrapper public struct EquatableIgnored<Value>: Equatable {
+@propertyWrapper public struct EquatableIgnored<Value>: Equatable, Hashable, @unchecked Sendable {
     public var wrappedValue: Value
 
     public init(wrappedValue: Value) {
@@ -30,4 +30,6 @@ import Foundation
     public static func == (_: Self, _: Self) -> Bool {
         true
     }
+
+    public func hash(into _: inout Hasher) {}
 }

BroadwayCore/Sources/Traits/BTraits+Overrides.swift

@@ -0,0 +1,46 @@
+//
+//  BTraits+Overrides.swift
+//  BroadwayCore
+//
+//  Created by Kyle Van Essen on 3/31/26.
+//
+
+import Foundation
+
+extension BTraits {
+    /// Allows overriding traits with specific values.
+    public struct Overrides: Equatable, Hashable, @unchecked Sendable {
+        public init() {}
+
+        // MARK: Subscript
+
+        /// Gets or sets the trait for the given type. Returns `nil`  if no value has been set.
+        public subscript<Value: BTraitsValue>(_: Value.Type) -> Value? {
+            get {
+                let id = TypeIdentifier(Value.self)
+
+                guard let value = storage[id], let value = value.base as? Value else {
+                    return nil
+                }
+
+                return value
+            }
+
+            set {
+                let id = TypeIdentifier(Value.self)
+
+                if let newValue {
+                    storage[id] = AnyHashable(newValue)
+                } else {
+                    storage[id] = nil
+                }
+            }
+        }
+
+        @CopyOnWrite private var storage: [TypeIdentifier: AnyHashable] = [:]
+
+        var values: [TypeIdentifier: AnyHashable] {
+            storage
+        }
+    }
+}