feat(Throw): add ceiling flight projection app

[kyleve]

Posted by an AI agent on kve's behalf.

Summary

• User-facing: Add Throw, an iPhone and iPad app that projects live aircraft onto a ceiling or on-device preview.
• User-facing: Provide geographic Map and altitude-aware True Sky projection modes with shared calibration controls.
• User-facing: Support adsb.lol, local readsb, ADS-B Exchange Personal through RapidAPI, and Flightradar24.
• User-facing: Add offline geography, regional Map centers, aircraft silhouettes, airline accents, route labels, motion prediction, and ambient flight-activity cues.
• User-facing: Support external-display scenes, full-screen fallback, Preview, quiet hours, location refresh, onboarding, and source diagnostics.
• User-facing: Introduce Projection Views. Air & Space is enabled. Transit, Stars, and Satellites remain visible as planned work.
• Internal: Add typed ThrowCore and ThrowUI boundaries for sources, layers, experiences, frames, credentials, preferences, and runtime ownership.
• Internal: Harden View preparation, lifecycle generations, source selection, and actor updates against stale or reordered work.
• Developer: Add deterministic data generators, attribution, architecture rules, snapshot coverage, and ./Throw/install.

Why

Throw needs one reliable path from aircraft data to a restrained projector surface. Every controller and output scene must share one runtime.

The projection also needs geographic context without online map tiles. Bundled data keeps Map rendering private, deterministic, and available offline.

Product behavior

Projection and output

• Map uses great-circle distance and bearing around a selected regional center. A dim observer ring preserves the actual location.
• True Sky uses WGS84 ECEF and ENU geometry to derive aircraft azimuth and elevation.
• Calibration controls true bearing, rotation, flips, and a safe inset. The projector remains responsible for focus and keystone.
• Preview, full-screen output, and external displays use the same opaque-black ProjectionSurface.
• Quiet standby keeps the output black and stops polling. Output demand controls the idle timer and foreground feed lifecycle.

Aircraft and geography

• Source selection is explicit. Throw never mixes provider frames or changes providers automatically after an error.
• Flight labels show route and flight metadata when the source provides it or optional ADSBDB enrichment resolves it.
• Aircraft without a known route remain visible at reduced prominence. Ground aircraft stay hidden unless Map settings include them.
• Six silhouette families, airline color dots, subtle fades, correction easing, and dead reckoning keep updates readable without dashboard chrome.
• Local arrival and departure estimates use routes, motion, altitude, nearby airports, and open runway geometry.
• Map shows contextual runway anchors. True Sky keeps aircraft cues but omits geographic and airport lines.
• Offline geography includes generalized global features and detailed United States boundaries and primary roads.
• The Geography layer has a separate low-intensity control and remains absent from True Sky and quiet output.

Projection Views

• Air & Space contains Geography, Flights, and the planned Stars and Satellites layers.
• One playlist controls all outputs. Each configured View owns a validated dwell duration and health state.
• The coordinator prepares a target before a switch, fades to black, exchanges the complete frame, and fades back in.
• Automatic rotation remains dormant while Air & Space is the only configured View. Transit provider work is deferred.

Privacy and credentials

• Cloud sources receive a center rounded to 0.1 degrees. Throw applies exact local filtering after each response.
• Local receiver URLs, observer coordinates, aircraft identities, callsigns, response bodies, and credentials stay out of logs.
• Paid-provider credentials use device-only Keychain storage. Preferences store only typed credential references and non-secret settings.
• Aircraft snapshots, routes, motion history, and usage estimates remain memory-only.

Architecture

• The app delegate creates one ThrowRuntime and one shared ThrowSession for every controller and output scene.
• ThrowCore owns typed domain values, providers, polling, projection math, prediction, preferences, credentials, schedules, and bundled data.
• ThrowUI owns onboarding, settings, calibration, focused runtime actors, projection preparation, and the shared renderer.
• AirAndSpaceRuntime owns one aircraft poller, semantic Flights frames, route enrichment, and consecutive-sample motion state.
• ProjectionExperienceCoordinator owns selection, prewarming, rotation, readiness deadlines, and per-experience health.
• Coordinator commands use one ordered async stream. Concurrent callers cannot overwrite an unhandled command.
• Prepared frames carry an activation generation. A switch accepts only the exact activation that produced the prepared frame.
• Lifecycle generations reject superseded Air & Space work after every actor suspension point.
• Rendered visible counts update the runtime directly and only for the generation that produced the rendered frame.
• Monotonic playlist revisions reject configuration tasks that reach the coordinator out of logical order.
• Aircraft source selection is one enum. Its cases carry only the configuration and credential role that the source supports.
• Layer IDs, mark IDs, line-style IDs, and layer payload kinds are closed types. Unsupported combinations fail at compile time.
• Type erasure exists only at the layer catalog boundary. Production callers cannot construct raw erased layer frames.
• Projected frames contain ordered mark and line layers. Static geography uses a bounded cache outside the 30 Hz mark path.
• Version-two preferences separate global, playlist, and Air & Space state while preserving version-one installs and Keychain identifiers.
• Bumper rules enforce runtime construction, session construction, live dependency ownership, and the layer-erasure boundary.

Design decisions

• Throw uses compile-time View and layer catalogs. It does not add runtime plugins or an AnyView boundary.
• Offline geography replaces Apple Maps and map tiles. It sends no observer location to a map provider.
• The selected Map center is independent from the observer and persists by coarse observer region.
• FR24 antimeridian polls use two atomic requests. Polar bounds use conservative spherical caps and outward edge rounding.
• Activity cues are ambient estimates. They do not claim exact touchdown or liftoff timing.

Compatibility

• Throw uses a separate persistence domain. This change does not modify Where data, backups, or CloudKit data.
• Version-one Throw preferences migrate to one configured Air & Space View without repeating onboarding.
• Existing RapidAPI and FR24 Keychain identifiers remain unchanged.
• Invalid preferences enter setup repair. Missing credentials never trigger provider fallback.

Review focus

• Review shared runtime ownership across controller, full-screen, Preview, and external-display scenes.
• Review source cancellation, lifecycle generations, playlist revisions, readiness deadlines, and frame exchange at black.
• Review Map, ECEF, ENU, antimeridian, polar, calibration, prediction, and correction geometry.
• Review provider decoding, request accounting, credential handling, redacted logging, and failure classification.
• Review generated geography, airport, runway, aircraft-type, attribution, and provenance resources.
• Review the compile-time layer and source invariants and their architecture tripwires.

Rollout and follow-ups

• This PR targets a personal beta.
• Throw/TODOs.md tracks remaining projector, Apple TV, provider, dense-traffic, quiet-hours, and overnight acceptance work.
• Revalidate the iOS 27 scene-accessory path against the GM SDK before release.
• Recheck provider prices, quotas, endpoints, and terms before release.
• Public distribution requires the applicable provider authorization and credential architecture.

Testing

• ./ide --no-open — passed.
• ./test ThrowUITests — 101 tests passed.
• ./test ThrowCoreTests — 235 tests passed.
• ./test --everything --review — 2,328 iOS unit tests and all 58 shared snapshot suites passed.
• ./test SnapshotKitTestingTests --only 'SnapshotKitTestingTests/SnapshotReferenceDiffTests' — 11 tests passed.
• Throw snapshot review — all 73 captures match their reviewed references byte for byte.
• Architecture validation — passed with the new Throw ownership and erasure rules.
• ./swiftformat --lint, ./sf-symbols --lint, ./xcstrings --lint, ./shellcheck, and ./attribution --check — passed.
• git diff --check — passed.

[kyleve]

Posted by an AI agent on kve’s behalf.

Review focus: this registration path compiles against the installed iOS 27 beta SDK, but the final UISceneAccessory lifecycle contract still needs GM-SDK and physical connect/disconnect plus controller-window recreation validation. That release gate is recorded in Throw/TODOs.md.