feat(Flyover): export a static QA atlas

[kyleve]

Summary

• User-facing: add ./flyover export to generate a portable, network-free Where QA atlas with canvas, list, search, zoom, route playback, deep links, profile switching, and a native-image inspector
• User-facing: add group navigation, an overview map, route emphasis, capture and route filters, responsive layouts, keyboard shortcuts, image scaling, and previous/next review controls
• Internal: add a generic DEBUG-only Flyover export planner and schema-versioned manifest that validates stable identities and capture policies before rendering
• Internal: expose hosted PNG capture through SnapshotKitTesting's existing serialized renderer, including intrinsic, full-content, two-axis, accessibility, readiness, settle, and failure behavior
• Internal: host Where exports in WhereUISnapshotTests with one frozen in-memory WhereFlyoverWorld; production Flyover and app scope behavior remain unchanged
• Repository: require agents to commit and push each coherent verified change unless the user requests local or uncommitted work

Why

Flyover could inspect the native screen catalog only inside the app. This adds a disposable static artifact that reviewers can open from file:// or any static host without reproducing SwiftUI in a browser or reading user data.

The first web shell covered the functional review path but gave little help with a large catalog. The revised shell makes groups, connected routes, capture types, build data, and long-form review controls visible without adding a web dependency.

Product behavior

• Canvas mode uses the manifest geometry, a group navigator, and an overview map. Pointing to or focusing a card emphasizes its incoming and outgoing routes.
• Search matches groups, screens, states, and connected routes. Filters narrow results by group, capture extent, and route state.
• List mode provides the same state and profile selection in a denser catalog.
• The inspector shows capture dimensions and build traits, incoming and outgoing routes, previous/next navigation, Fit and 100% image modes, and device-width full-content scrolling.
• URL hashes preserve view, screen, state, and profile selections. Browser Back and Forward restore them.
• The responsive layout retains the complete review flow on narrow browser windows.

Architecture

• Flyover owns the generic export model, stable web identities, capture policies, profiles, precomputed graph geometry, manifest, image plan, and static shell.
• SnapshotKitTesting owns PNG rendering and dimensions through the same host window, capture lock, readiness hooks, settling, accessibility annotations, and size limits used by reference snapshots.
• WhereUI owns the stable typed-ID mapping, named snapshot variants, synthetic world, catalog, and hosted export entry point.
• The root command validates output safety, stages beside the destination, invokes the filtered hosted test through ./test, validates every asset, then atomically replaces only a marked generated directory.

Review focus

• Stable screen IDs use reflected screen and context type names, while image paths use generated ordinals.
• Snapshot-backed variants reject mixed sizing matrices unless registration supplies an explicit export policy.
• Settle and sizing failures throw through the hosted PNG API, so the command cannot publish a partial or viewport-fallback artifact.
• The static shell intentionally uses manifest.js instead of fetch, which keeps file:// support and avoids all external network requests.
• The merge resolution preserves both the new mandatory architecture checks from main and the Flyover command regression in every normal ./test run.

Compatibility

The feature is DEBUG/test-only. It changes no production data, backup, persistence, or app runtime behavior. The generated artifact is disposable; schemaVersion: 1 is its compatibility boundary.

Testing

• ./test FlyoverTests SnapshotKitTestingTests WhereUITests — 570 tests passed
• ./flyover export --output /tmp/where-flyover-codex --profile phone-light — 50 screens, 108 states, 41 routes, 108 PNGs
• ./flyover export --output /tmp/where-flyover-codex --profile phone-light --profile phone-dark — 50 screens, 108 states, 41 routes, 216 PNGs
• validated all exported PNGs, manifest/image parity, relative paths, two-profile mappings, generated marker, and repository-shell byte equality
• browser validation covered desktop and mobile canvas/list layouts, search and filters, state/profile playback, route navigation, history restoration, and full-content scrolling; no console errors
• bash -n flyover test Shared/Flyover/Tools/Tests/flyover_test.sh
• bash Shared/Flyover/Tools/Tests/flyover_test.sh
• ./flyover --help
• ./swiftformat --lint
• ./test FlyoverTests after merging current main — 15 architecture rule tests and 51 Flyover tests passed; no architecture violations
• ./test --everything — 1,962 unit tests and 47 snapshot tests passed before the UX-only web-shell follow-up; no snapshot references changed

[kyleve]

Review focus: this deliberately changes unsettled and starved captures from recorded test issues followed by image generation into typed throws. assertSnapshots still records the thrown error, while the new hosted PNG caller stops immediately and cannot publish that image. Cancellation now follows the same path through CancellationError.