[kyleve]

Posted by an AI agent on Kyle's behalf.

Summary

Broadway consumes prepared ViewDocument content and composes themed surfaces without transferring layout, input, or accessibility ownership to decorative artwork.

BSurface orders base paint, interior artwork, native content, highlights, and exterior artwork. Its finish applies to the inner surface, allowing material treatment and native zoom-transition sources to exclude overflow.

API and contracts

API	Responsibility
BViewDocumentLayer	Render a prepared document with injected host activity and static-motion policy
BViewDocumentStylesheet	Resolve Dynamic Type scaling, semantic background levels, and accessibility policy from Broadway traits
BSurface	Compose native content with separate interior and exterior paint; preserve interaction and accessibility bounds
BArtworkPlacement / BArtworkLayer	Validate host-relative placement, scale to reserved gutters, clip finite paint bounds, and protect the content center
BSurfaceLayerRole	Distinguish essential surface content from optional ornament
BThemeValue	Represent constant or appearance-specific authored values

The host prepares assets before rendering. Broadway performs no resource loading or networking. Artwork is hidden from accessibility and ignores hit testing. An explicit accessibility content shape prevents exterior paint from enlarging a combined focus rectangle.

Reduce Motion selects the static pose. Increased Contrast and Reduce Transparency hide optional ornaments while preserving essential surfaces. Effective SwiftUI contrast overrides reach the Broadway root without weakening the user's system setting. Native background providers pin mode and contrast while retaining host elevation for sheets and popovers.

CopyOnWrite gains transparent Codable support for large value trees. It preserves the wrapped wire shape and encoder/decoder strategies. BTraits() supplies a deterministic, explicit baseline without reading ambient system traits.

The host supplies native content and the prepared artwork for each plane:

BSurface(shape: shape, finish: EmptyModifier()) {
    basePaint
} interior: {
    interiorArtwork
} content: {
    nativeContent
} highlights: {
    border
} exterior: {
    exteriorArtwork
}

Review focus

Surface contract → Artwork hosting → Trait adaptation → Trait regressions.

Independent review identified two boundaries that needed explicit protection: hidden exterior artwork could still enlarge a combined accessibility frame, and frozen background colors lost host elevation. The final code preserves the native focus shape and uses trait-pinned dynamic background providers. Hosted consumer tests and background-level regressions cover both.

Check composition order, the protected foreground center, finite paint bounds, RTL placement, trait updates, scoped overrides, and unchanged content layout. The consumer must reserve gaps and retain viewport clipping.

Testing

• ./test --all --review --no-generate: BroadwayCore’s 120 tests and BroadwayUI’s 31 tests passed in the full multi-bundle run.
• Consumer integration covers repeated card navigation, sheet presentation, focus bounds, ranking changes, tab/scene activity, native background elevation, and scoped appearance. See feat(WhereUI): unify JSON themes and add illustrated Halloween #462 for the full validation sequence and limits.
• Seven calendar/forecast Increased Contrast references accompany the root trait correction. Where’s separate Elsewhere outline change remains in feat(WhereUI): unify JSON themes and add illustrated Halloween #462.
• On this intermediate branch, ./test --skip-host-tests --only-file <scope-file> --record never --review passed all four existing consumer entry points: CalendarContentViewSnapshotTests/calendarContent(), LocationForecastPanelSnapshotTests/componentThemes(), LocationForecastSummarySnapshotTests/componentThemes(), and MainTabsSnapshotTests/mainTabs() in WhereUISnapshotTests. This verifies the seven contrast references before the Where migration.
• ./swiftformat --lint, architecture configuration/rule tests (29), and architecture lint passed.

Programmatic interaction and snapshot captures do not establish physical-device drag/deceleration or audible VoiceOver behavior.

Stack

2/3, based on ViewDocument #460. This slice adds reusable styling infrastructure; Where #462 activates it and contains full-screen visual examples.