@motionstudies/data 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -4,8 +4,8 @@ Shared packages for the Motion Studies transport instrument. The source workspac
 
 - `@motionstudies/core`: transport contracts, indexing, interpolation and visual theme contracts; no browser or Node dependencies.
 - `@motionstudies/three`: `NationalNetworkScene`, `HubPulseScene`, `StationFlowScene`, camera framing and label-mode contracts. React, React Three Fiber and Three.js are peers; rendering internals are not public subpaths.
-- `@motionstudies/web`: picker, button tooltips, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Fonts and edition layouts belong to consumers.
-- `@motionstudies/data`: Node-only GTFS readers, network chunking, merging and station ranking. ZIP reading requires `unzip` on the host. Source selection, provenance overrides and compilation commands belong to each edition.
+- `@motionstudies/web`: picker, button tooltips, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Import `fonts.css` for the self-hosted Inter and DM Mono faces those stylesheets name, licensed under the SIL Open Font License 1.1; other typefaces and edition layouts belong to consumers.
+- `@motionstudies/data`: Node-only GTFS readers, ADS-B heatmap compilation, air endpoint enrichment, network chunking, merging and station ranking. ZIP reading requires `unzip` on the host. Source selection, provenance overrides and compilation commands belong to each edition.
 
 ```tsx
 import { MobilePicker } from '@motionstudies/web/components/MobilePicker'
@@ -25,8 +25,253 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Timetable patterns, station calls and observation windows
+
+`@motionstudies/core/domain/network-patterns` provides a transport-neutral repeated-schedule codec. `@motionstudies/web/use-pattern-network-day` lazily decodes current/adjacent chunks after verifying byte length and SHA-256; it exposes retry and drops old-source state when the manifest URL changes. Supply stable options and a stable asset resolver. Format/category options support existing edition wire contracts.
+
+`@motionstudies/core/domain/station-calls` supplies station calls, independent source status, namespaced source combination and upcoming-call filtering. Source IDs, repeated visits and acquired windows survive combination. Consumers supply interchange IDs and passenger restrictions; matching display names do not collapse services.
+
+`@motionstudies/data/observation-windows` compiles bounded acquired records into hashed windows with explicit time semantics, conflict policy and acquisition-gap reporting. It preserves supplied record IDs, values and source references. It uses elapsed UTC seconds, including 23/25-hour study days, and performs no acquisition or inference. See [contracts, limits and parity evidence](../docs/ALLCHANGE-FOUNDATIONS.md).
+
+## Now and browser location
+
+`useNowClock` from `@motionstudies/web/use-now-clock` follows the wall clock on each animation frame, so returning from a suspended tab catches up immediately. Call `start()` from a Now button, set the consumer's playback rate to 1, and render its `time` while `active`. With `NationalNetworkScene`, pass `isPlaying={false}` while this external clock owns time. Call `stop()` before pausing, seeking or changing speed, and retain the last clock time for ordinary playback. Clear moving vehicle selections on entry to keep the camera still; panning and zooming remain available.
+
+Supply a resolver `(instant: Date) => number | null` that maps the instant into the edition's service-time coordinates. The edition owns timezone, service date, daylight-saving rules and source coverage. Now is appropriate when the data gives a meaningful sense of this place at this time; exact live vehicle positions are not required. An edition may explicitly map the current local clock onto a suitable representative weekday or seasonal timetable, with a quiet label such as “Typical weekday · realtime pace”. Historical or modelled sources need that same meaningful relationship to the present; merely having timestamps is insufficient. Return null outside the chosen data's coverage: the hook stops, retains the last valid time and exposes `unavailable`. Do not silently relabel a recording as live or wrap a partial study window. Timetable and observed-data labels remain the consumer's responsibility; 1× playback does not imply a live vehicle feed.
+
+`useBrowserLocation` from `@motionstudies/web/use-browser-location` requests a single position only when `locate()` is called. It exposes `location`, `status` and `clear()`; it neither stores nor sends coordinates. Render localized messages for denied, timeout and unavailable states. Clearing or unmounting discards late responses. A secure browser context and user permission are required.
+
+Pass an in-coverage position as `NationalNetworkScene`'s `userLocation` for a steady glowing dot. Use the existing `focus-location` camera command once after locating, with `[longitude, latitude]` and a suitable `distanceScale`. Validate coverage in the consumer and preserve the view when the user is outside it. Show the reported `accuracy` in accessible text; the dot is an approximate position. The marker hides in diagram layouts. The lab's **Now** specimen uses a clearly labelled synthetic UTC timetable and covers clock, permission and out-of-coverage behavior. Public editions still require independent adoption and releases.
+
+## Selection labels
+
+`NationalNetworkScene` gives the selected station first label priority, followed by the selected route's terminal stops (including branches), then intermediate stops. Selected services use their own endpoints. Priority precedes retained labels and ordinary rank/tier admission; clearing selection restores edition ranking. This is built in for every consumer, including geographic and diagram layouts. Supply complete enabled infrastructure as `referenceSnapshot` to preserve endpoints through timetable gaps; its stop indexes need not match the active snapshot. See the [edition behaviour contract](https://github.com/emmettl/motionstudies/blob/main/docs/EDITIONS.md#selection-and-station-labels).
+
 ## Button help
 
 `mountMotionStudy` installs one shared tooltip surface. Independent consumers such as the lab can render `ButtonTooltips` from `@motionstudies/web/components/ButtonTooltips` once instead. Put concise, action-oriented help in each button’s `data-tooltip`; icon buttons fall back to their `aria-label`. An empty `data-tooltip` opts out. Avoid native `title` attributes on these buttons, which can also appear during touch interaction.
 
 Help appears after a short mouse hover or on keyboard focus when the primary pointer is fine and supports hover. Touch input suppresses it, including on hybrid devices. Escape, activation, scrolling and blur dismiss it. The tooltip stays inside the viewport, can itself be hovered, and temporarily extends `aria-describedby` without replacing existing descriptions. Copy and translations stay in the edition; rendering and input handling stay in this package. The Controls specimen and packed-consumer tests exercise this contract.
+
+## Airport heroes and split-flap boards
+
+`AirportHeroCard` provides an airport identity header and switchable departure/arrival boards. `SplitFlapBoard` is the underlying transport-neutral widget, also suitable for rail stations. Both use scoped package styles, semantic tables, full accessible cell values, keyboard-operable selection, contained horizontal scrolling and reduced-motion support. Only changed characters remount for the flap animation.
+
+```tsx
+import { AirportHeroCard } from '@motionstudies/web/components/AirportHeroCard'
+import '@motionstudies/web/airport-hero-card.css'
+
+<AirportHeroCard
+  key={airport.id}
+  airport={airport}
+  departures={departures}
+  arrivals={arrivals}
+  study={{ time, windowStart: metadata.windowStart, windowEnd: metadata.windowEnd }}
+  dateLabel={metadata.serviceDate}
+  note="Observed study · inferred directions; times are observations."
+  onSelectFlight={selectAirTrack}
+  selectedFlightId={selectedAirTrackId}
+/>
+```
+
+Entries have a stable `id`, a `service` label, and optional numeric `time`, `place`, `stand`, `status` and `tone` (`neutral`, `accent` or `warning`). Movement times and `study.time`, `windowStart`, and `windowEnd` must use the same study-relative seconds and service date. Do not parse display strings or normalize numeric times at midnight: an event after 24:00 retains its value above 86,400. `formatTime` optionally controls display formatting; the default uses the study's `formatServiceTime` helper. The header clock is derived directly from `study.time`, with no independent wall clock.
+
+The card sorts movements chronologically and shows up to eight rows per direction inside the intersection of the study bounds and a rolling window: ten minutes behind the playback clock and sixty minutes ahead, with inclusive endpoints. Override this with `horizon={{ lookBehindSeconds: 600, lookAheadSeconds: 3600 }}` and `maxRows`. Playback, backward seeking, changed study bounds and updated movement times all recalculate the rows. An out-of-study or invalid clock shows no movements; rows with missing or non-finite times are excluded because they cannot be placed in the window. Other unknown fields render as a dash. Labels include `studyTime`, `boardWindow` and `outsideWindow` for localization. Filtering does not infer operational statuses or clear the consumer's map selection when a row leaves the window.
+
+Consumers still own time coordinates, source interpretation and data loading. Supply movements for the displayed horizon, not just aircraft active at the current second, and use the selected study's bounds rather than an individual progressive chunk's bounds. Do not turn an approach-envelope association into a confirmed departure/arrival: unclassified tracks should remain outside these direction lists. Current `AirTrack` data does not supply scheduled times, routes or gates; leave those fields absent, use observation times only when clearly labelled, and explain any inference in the required `note`.
+
+Pass `labels` for edition translations, `loading`, or a localized `error` and `onRetry` for data states. The selected direction is local to each card; key the card by airport ID to reset it on selection changes. The Airports lab specimen exercises synthetic timetables, playback, scrubbing, study-window changes, incomplete observations, French labels, long destinations, updates and recovery. Edition adoption happens through their independently pinned package releases; adding this export does not update deployed studies.
+
+For a custom rail or transport board, import `SplitFlapBoard` from `@motionstudies/web/components/SplitFlapBoard` and `@motionstudies/web/split-flap-board.css`. Supply `columns` (`key`, `label`, `characters`) and `rows` (`id`, `cells`, optional `tone`). Cell text longer than its flap count is visually ellipsized, with the full value retained for assistive technology and hover. `onSelectRow`, `selectedRowId` and `selectionColumn` optionally make one cell per row selectable.
+
+For bus stops and local transport, `DotMatrixBoard` accepts the same rows, selection callbacks, loading state and empty/loading messages. It uses an amber 5 × 7 LED alphabet and its own scoped stylesheet; the flip-board stylesheet is not required. Consumers can switch components without remapping their data.
+
+```tsx
+import { DotMatrixBoard } from '@motionstudies/web/components/DotMatrixBoard'
+import '@motionstudies/web/dot-matrix-board.css'
+
+<DotMatrixBoard
+  label="Bus departures"
+  columns={[
+    { key: 'route', label: 'Route', characters: 4, minCharacters: 4 },
+    { key: 'destination', label: 'Destination', characters: 24 },
+    { key: 'time', label: 'Due', characters: 6, minCharacters: 6, align: 'right' },
+  ]}
+  rows={[{ id: 'bus-71', cells: { route: '71', destination: 'City Centre', time: '2 min' } }]}
+  lineCount="auto"
+  style={{ height: 360 }}
+/>
+```
+
+`lineCount` defaults to six display slots and accepts 1–30 (values outside that range are clamped; non-finite values use six). Fixed counts keep all slots and scale their contents to the available height, so dense boards need taller containers to remain readable. `"auto"` observes the actual container and fits 1–30 rows at a target `minRowHeight` of 34px. The default board height is 320px; use `style`, `className`, or `height: '100%'` inside a parent with a defined height. Unused slots stay blank; rows beyond the visible slots are omitted, without pagination or changes to consumer selection.
+
+For dot-matrix columns, `characters` is a width weight, while `minCharacters` reserves space before the remaining width is distributed. At very narrow widths all columns scale down. Long cell values are visually ellipsized, with their full original text available to assistive technology and on hover. Characters outside the bitmap alphabet (including accented names and non-Latin scripts) use SVG text as a visual fallback. `--matrix-ink` and `--matrix-unlit` customize the LEDs. Updates are immediate, with no flashing or scrolling animation. The **Bus boards** lab specimen exercises both presentations, height/width resizing, row counts, selection, long names, loading and empty states using synthetic timetable data.
+
+`variant="uk-rail"` gives the matrix a square black enclosure, mixed-case amber lettering, matrix column headings and horizontal display bands. Optional `heading` and `headingColumnSpan` replace the visual labels across the leading columns while preserving the individual accessible column headers. `footerLabel` and `clockLabel` add a matrix footer; the consumer owns clock formatting and updates. No live clock or pagination is inferred. `DotMatrixRow.note` adds a detail line and an accessible description on the selection button. Details consume one display slot and stay with their departure: if only one slot remains, the next departure with a detail waits until there is room for both. A one-line board still shows its first departure, retaining its full note for assistive technology.
+
+## Rail, bus and airport hero cards
+
+Hero cards have separate transport-specific APIs and visual identities, with shared display components underneath:
+
+| Card | Identity | Departure fields | Default display |
+| --- | --- | --- | --- |
+| `RailStationHeroCard` | Station name, optional code and locality | Scheduled time, destination, platform, expected time/status, via/service note | UK rail matrix |
+| `BusStopHeroCard` | Stop name, optional stop code and locality | Route, destination, due estimate, optional via | Bus dot matrix |
+| `AirportHeroCard` | IATA code, airport name and city | Flight, time, destination/origin, gate, remarks, direction tabs | Split flap |
+
+Import the new cards from `@motionstudies/web/components/RailStationHeroCard` or `@motionstudies/web/components/BusStopHeroCard`, plus `@motionstudies/web/transport-hero-cards.css` (which includes both board styles). Airport imports and study-window behavior remain as documented above.
+
+```tsx
+<RailStationHeroCard
+  station={{ name: 'Bristol Temple Meads', code: 'BRI', locality: 'Bristol' }}
+  departures={[{
+    id: 'train-1', time: '17:15', destination: 'Portsmouth Harbour',
+    platform: '9', expected: '17:22', via: 'Eastleigh',
+  }]}
+  lineCount="auto"
+  boardHeight={400}
+  clockLabel="16:49:26"
+  footerLabel="Study timetable"
+  note="Synthetic timetable. Example times, not a live service."
+/>
+
+<BusStopHeroCard
+  stop={{ name: 'Anchor Road', code: 'A1', locality: 'Bristol' }}
+  departures={[{ id: 'bus-1', route: '71', destination: 'City Centre', due: '2 min' }]}
+  lineCount={6}
+  note="Synthetic timetable. Example estimates, not a live service."
+/>
+```
+
+Rail and bus consumers supply already ordered and formatted departures, including their own filtering, timezones and freshness. Missing times, platforms and statuses stay unknown rather than becoming “On time”. Both cards accept `presentation` (`'uk-rail'`, `'dot-matrix'`, `'split-flap'`), `lineCount`, `boardHeight` in pixels, `minRowHeight`, `loading`, `error`, `onRetry`, localized `labels`, and controlled `onSelectDeparture`/`selectedDepartureId`. A required `note` explains the source. The matrix fits its container; the split-flap alternative contains scrolling and places any service details in an Information column. Fixed line counts represent physical matrix lines; in split-flap mode they limit departure rows. The **Transport heroes** lab compares all three cards, switches the new cards' presentations, and exercises details, row fitting, updates, long names and failure states.
+
+The rail card additionally accepts `presentation="sbb"`: a blue-and-white typographic departure board with service badges, scheduled time, destination/via information and prominent track numbers. This layout follows the information hierarchy in [SBB's general display guide](https://www.sbb.ch/en/travel-information/stations/services-station/station-customer-information/general-display-board.html). It uses ordinary text, including accented and non-Latin names. `RailDeparture.service` supplies a train label such as `IC 1`; optional `serviceCategory` (`'intercity'`, `'international'`, `'regional'`, `'suburban'`) selects the badge treatment. `platformSector` supplies a separate sector label when known. Expected times or disruption messages appear below the scheduled time; absence of a message does not manufacture an “On time” assertion.
+
+For this layout, `lineCount` counts departures with their inline detail, and `"auto"` fits rows using a default target height of 64px. Dense fixed counts reduce type size; long values remain in the accessible text and hover titles. Labels stay consumer-owned, including the added `service` column label. The lab's **SBB departure board** option selects a synthetic Zürich HB example with German, French, Italian and English labels. Both new board styles are included in `transport-hero-cards.css`.
+
+At compact widths the SBB layout stacks the service badge under the time, preserving destination space and the separate track column. Rail and bus hero padding follows the card width rather than the viewport. The lab includes a 240–980px width slider and Compact/Mobile/Panel/Wide presets, plus a 180–640px board-height control. The size regression suite covers seven card widths, four board heights, fixed and automatic line counts, long destinations, selection during updates, mobile viewports and loading/error states in Chromium and WebKit. Prefer `lineCount="auto"` for small panels; high fixed line counts deliberately trade text size for density.
+
+```tsx
+<RailStationHeroCard
+  presentation="sbb"
+  station={{ name: 'Zürich HB' }}
+  labels={{ station: 'Bahnhof', departures: 'Abfahrt', service: 'Zug', time: 'Zeit', destination: 'Nach', platform: 'Gleis' }}
+  departures={[{ id: 'example-1', service: 'IC 1', serviceCategory: 'intercity',
+    time: '09:02', destination: 'Genève-Aéroport', via: 'Bern · Lausanne', platform: '32', platformSector: 'ABCD' }]}
+  lineCount="auto"
+  boardHeight={430}
+  note="Synthetic timetable · Example data."
+/>
+```
+
+The shared board also accepts `loading`, a localized `loadingMessage`, and `loadingRows` (default five). While loading, its decorative rows cycle through staggered letters and digits; they are hidden from assistive technology and cannot be selected. A single status message announces loading. When data arrives, characters flip through a short sequence and settle into their actual values; later changes animate only the changed characters. These CSS animations have no JavaScript timers and stop looping when loading ends or the board is removed. Reduced-motion users get static blank loading flaps and immediate final text. `AirportHeroCard` uses this shared loading treatment automatically. Use **Reload board** in the Airports lab to preview the complete loading-to-ready transition.
+
+Empty messages also appear on the flaps, in the widest column (the destination/origin column in airport cards), with the other columns blank. Longer localized messages wrap across display rows instead of being truncated. They settle with the same animation as flight details, and one hidden status announces the complete message to assistive technology. This also applies when the study clock moves into a window with no movements.
+
+Rail and other transport consumers can share the same time filtering through `movementBoardWindow(study, horizon)` and `movementsForBoard(entries, window, maxRows)` from `@motionstudies/core/domain/movement-board`. Format the returned numeric times when mapping them into `SplitFlapBoard` cells. The lab's rail board follows the same study clock and horizon as its airport card.
+
+`@motionstudies/data/air-endpoints` provides offline `enrichAirEndpoints` for existing air manifests, chunks and opening snapshots. Supply cached same-date global ADSB.lol heatmaps, an OurAirports CSV and the service date's local UTC offset. It associates only unambiguous low-altitude endpoints near a reference airport; cruise-only traces and uncertain routes stay unknown. Optional `AirEndpoint` origin/destination fields carry airport identity, observed boundary time and `observed-endpoint` evidence. `airportBoardMovements` maps full manifest entries to board rows without confusing playback chunk boundaries with flight endpoints. Input hashes and source/licence attribution are recorded in fixture metadata. These fields describe inferred observations, never flight schedules, gates or live status.
+
+## Vehicle hero cards
+
+`VehicleHeroCard` shows one vehicle's destination, next stop and remaining calling points. Import it from `@motionstudies/web/components/VehicleHeroCard` with `@motionstudies/web/vehicle-hero-card.css`. The **Vehicle heroes** lab compares `uk-bus` (amber onboard display), `uk-rail` (dark rail display), `yellow-bus` (yellow next-stop panel) and `sbb` (blue next-stop panel with a red service badge). These are presentation studies, not official operator components.
+
+```tsx
+<VehicleHeroCard
+  presentation="sbb"
+  vehicle={{ service: 'IC 1', operator: 'SBB CFF FFS', destination: 'Genève-Aéroport' }}
+  stops={[
+    { id: 'bern', name: 'Bern', time: '10:28', platform: '6' },
+    { id: 'fribourg', name: 'Fribourg/Freiburg', time: '10:56' },
+  ]}
+  note="Synthetic journey · Example calls and times."
+  onSelectStop={selectStation}
+  selectedStopId={selectedStationId}
+/>
+```
+
+Consumers supply remaining `stops` in journey order and update them with playback, seeking or observations; the card has no independent clock. The first supplied call is the next stop. Optional `time`, `platform` and `detail` are consumer-formatted; absent values stay absent. `vehicle.destination` is optional and shows an explicit unavailable label when missing. The final supplied stop is never inferred to be the destination: set `isDestination` only when confirmed, especially when data is progressively chunked. Empty calls mean no upcoming stops are available, without asserting that the vehicle has arrived.
+
+The required `note` explains provenance. Optional `status`, `statusTone`, `clockLabel`, localized `labels`, `loading`, `error` and `onRetry` follow the consumer's data; the component never manufactures an on-time status. Loading and errors hide the calling points. Stop selection is controlled through stable call IDs and does not alter playback or clear when a call leaves the list. All supplied calls are shown, with wrapping names and container-based compact layouts. The lab exercises advance/rewind, unknown destinations/times, localization, disruption, recovery and narrow widths. Edition adoption requires its own package upgrade and data adapter.
+
+## Feed observability
+
+`@motionstudies/data/feed-observability` validates versioned feed registries, operational events and health reports. `@motionstudies/data/recorder-observability` projects a recorder status snapshot into that shared contract, rechecking freshness against the observer's clock and omitting private paths, PIDs and raw errors. Both are pure functions with no acquisition, storage or notification side effects. The source repository's `docs/FEED-OBSERVABILITY.md` describes the read-only CLI, example registry, states and evidence limits. Registry daily schedules remain declarative; explicit dated evidence plans and incident history are available through the Node adapters below.
+
+`@motionstudies/data/recorder-evidence` reads explicit dated local journal/close-out and release targets, verifies their hashes and identities, and assesses missing expected outputs against deadlines. `@motionstudies/data/feed-incidents` persists debounced incident transitions with replay protection, atomic checksummed state, bounded retention and fail-closed capacity limits. These two modules require Node. See `docs/FEED-INCIDENTS.md` for CLI opt-in flags and operational limits; neither module installs a scheduler or sends notifications.
+
+`@motionstudies/data/release` checks versioned release handoffs in Node or a browser: safe file descriptors (`{ path, sha256, bytes }`), every descriptor in a manifest whatever its layout, kind and schema, and fetched bytes through Web Crypto. `@motionstudies/data/release-files` opens a release directory in Node, optionally pinned to its manifest digest, reads only described files without escaping the directory, and verifies a whole release within a byte budget. Format meaning stays with each format's reader. See the source repository's `docs/RELEASE-CONTRACT.md`.
+
+## Optional live airport feed
+
+`AirportBoard` from `@motionstudies/web/components/AirportBoard` adds Study/Now controls around an existing `AirportHeroCard` configuration. Pass `studyCard` with the usual card props and `live={{ baseUrl, edition, airport }}` for the shared service. Import `airport-hero-card.css`. `labels` localizes the wrapper's control and availability messages. The lower-level `useAirportFeed` hook and core `domain/live-airport` contract are also public exports.
+
+Live timestamps are Unix seconds and use the airport's timezone for display, independently of recorded service time. The wrapper does not pass live flight IDs to the recorded scene's selection callback. The recorded card remains mounted while hidden; the edition still owns playback and can pause its study when appropriate. Only Now mode fetches flight boards; checking capabilities does not query the paid provider. Stale results carry their retrieval time and disappear when expired. Source data never falls back to synthetic or recorded flights under a live label.
+
+See [service architecture and operations](../docs/LIVE-AIRPORTS.md). The Worker is deployed separately; npm publication and edition adoption remain explicit release steps.
+
+## Shared recorded air compilation
+
+`@motionstudies/data/adsb-heatmap` consolidates the offline heatmap pipeline previously copied between editions. `ingestAdsbHeatmaps` reads cached gzip slices, decodes observations, filters transport-scale tracks, splits flights, and writes either an opening snapshot or an indexed day with overlapping chunks. Source hashes, chunk hashes and ODbL attribution accompany the output. It makes no network requests.
+
+The same `decodeAdsbHeatmap` now powers `enrichAirEndpoints`; endpoint inference retains full coordinate precision, while playback compilation retains the existing five-decimal coordinates. `transportAirTracks` and `chunkAirSnapshot` are also available for consumers that assemble their own pipeline. All functions have public TypeScript declarations and work in the packed Node package.
+
+Editions supply geographic bounds, service date, explicit UTC offset, optional timezone, input files and output paths. Flight IDs and chunk overlap retain the existing contracts. The default splits known callsign changes and gaps over 30 minutes. Set `splitTracks: false` only when reproducing a legacy opening snapshot with one ID per aircraft. See [adoption and compatibility](../docs/AIR-DATA.md).
+
+## Shared edition controllers and performance
+
+`positionForTrain` now indexes chronological stop times with binary search and retains sequential behavior for unordered observations. Stop arrays are immutable: replace the array when a timetable changes. Arrival/departure boundaries, dwell, cancellation and backward seeking retain the existing contract.
+
+`countableVehicleTrains(network, stations, selection)` and `createActiveTimetableVehicleCounter(trains, options)` from `@motionstudies/core/domain/vehicle-counts` separate station/route/category membership from clock updates. Build the selector and counter with `useMemo` when data or selection changes, then call the counter at the displayed time. It includes both interval endpoints and excludes cancellations and inverted intervals. Missing stations yield no matches. By default it counts timetable intervals even if a journey lacks enough stops to position; `{ requirePositionable: true }` excludes journeys with fewer than two stops. This distinction is explicit so an edition can retain its established metric.
+
+The renderer now shares active GPU upload ranges, paused frame reuse, label and trail frame budgets, cached text comparators and batched hub lines. Custom layers can import the low-level helpers from `@motionstudies/three/render-performance`. Recreate frame trackers when their geometry/data/selection inputs change; `batchHubLines` takes ownership of two-vertex source line resources. Edition-specific worker transfer, picking and cartographic adapters remain consumer-owned.
+
+`useJsonAsset<T>(url, enabled, parse?, optional?)` from `@motionstudies/web/use-json-asset` loads a single asset lazily and exposes `data`, `loading`, `error`, `unavailable`, and `retry`. Keep the parser stable and perform edition-specific schema/source compatibility checks there. Successful data remains cached while disabled; consumers decide whether to display it. Changing the URL or parser immediately discards prior-source state, and disabling/unmounting cancels requests. `retry()` discards cached state and requests again when enabled. Optional HTTP 404 responses are unavailable; other failures are errors. No source fallback or freshness policy is inferred.
+
+`useTransitionValue(target, { durationMs, easing, steps })` from `@motionstudies/web/use-transition-value` animates a numeric value, returning `value` and `transitioning`. It reverses from the current frame, cancels on teardown, and settles immediately when reduced motion becomes active. `smoothTransition` is the default easing; `cosineTransition` and stepped progress support existing edition rhythms. Keep custom easing functions stable. Camera actions and lazy layout loading stay in the edition.
+
+Edition chunk scripts can call `runNetworkChunkCli()` from `@motionstudies/data/network-chunk-cli`. It accepts the existing `--input`, `--manifest`, `--opening`, `--chunk-hours`, `--opening-start`, `--opening-end`, and `--focus` arguments. Source acquisition, provenance, output paths and command invocation remain edition-owned.
+
+For timetable-backed vehicle selections, `NetworkVehicleHeroCard` from `@motionstudies/web/components/NetworkVehicleHeroCard` accepts `snapshot`, `train`, playback `time`, a required source `note` and the vehicle card's presentation/state/label options. Import `vehicle-hero-card.css`. It resolves the selected train ID against the current snapshot, retaining destination identity but showing no stale calls when that ID is absent. Calls stay in journey order, use stable journey/call IDs and follow backward seeking. During dwell the heading becomes `atStopLabel` (default “At stop”) and the time is the departure; otherwise it is the upcoming arrival. Times are formatted with `formatServiceTime` by default, without normalizing after midnight or adding delay twice. Use `showTimes={false}` for frequency-modelled journeys, and explain the model in `note`. The core `vehicleCalls` helper is also exported from `@motionstudies/core/domain/vehicle-calls` for custom adapters. Selection callback IDs refer to calls, not station indexes.
+
+### Railway preparation
+
+`@motionstudies/data/rail-wtt`, `rail-journeys`, `rail-public-calls`, `rail-routing` and `rail-geometry` expose typed offline railway preparation. XLSX reading, dated source-column audits, UID/date joins, public-call anchors and connected OSM paths preserve source evidence. Editions supply regional identities, calendar exceptions and clipping policy. Node 24+ and `unzip` are required; no Python runtime is shipped. See `docs/SHARED-RAIL-READERS.md` in the source repository for calendar limits and parity evidence.
+
+`mountMotionStudy({ id, theme }, application)` requires presentation identity only; a full `MotionStudyEdition` remains accepted. Applications own their data catalogue and loading lifecycle.
+
+For independent airport infrastructure, `mapStyle.airports.visible` hides the mounted group without rebuilding GPU resources, and `showLabels` controls its labels separately. Both default to `true`. Set these from the edition's layout and label controls; airport abbreviations equal to their IATA code are rendered once.
+
+## Compression at rest in the source store
+
+`capture` and `importCapture` accept `compression: 'gzip'`. The object is stored as `objects/<sha256>.gz` when gzip saves at least ten percent, otherwise raw; the record keeps the raw content hash and byte count as identity and adds `storedBytes` and `encoding`. `readCapture` and the new `readObject(store, hash, expectedBytes)` follow either form, verify the raw hash after expansion, and refuse output beyond the recorded size. `compactObjects(store, { minimumSaving })` compresses existing raw objects in place, verifying each before removing the raw file; records are not rewritten, since reads do not depend on them. Already-compressed sources such as ZIP archives stay raw. Use `storedBytes` for storage accounting and `bytes` for provenance.
+
+## Estimated fields, gridded series, field paths and daylight
+
+These transport-neutral modules came from Zugunruhe's radar-field studies and serve any work that renders a continuous surface between scattered instruments, a gridded weather product, illustrative flow, or the sun's position: modelled electricity demand between substations, rain radar, model wind, or a terminator crossing a national field. They are pure functions with no dependencies. See [the shared-field record](../docs/SHARED-FIELDS.md) for provenance and adoption.
+
+`@motionstudies/core/domain/supported-field` estimates values between stations. `fieldNeighbours` weights stations by a Gaussian kernel with a smooth taper to a finite reach; `estimateField` blends station samples and reports `support`, a fade from the nearest station that supplied a value, and `vectorSupport` for the nearest complete vector. All kilometre scales are `FieldSupportOptions`; `DEFAULT_FIELD_SUPPORT` retains Zugunruhe's 90 km scale, 240 km reach and 120–240 km support fade. Null station values are excluded rather than treated as zero; vector components blend as east/north components, never as bearings. `createFieldGrid` precomputes neighbours for a regular grid whose rows run south to north, `sampleFieldGrid` packs value, east, north and support per cell and level with NaN for unavailable channels, and `sampleFieldGridAt` reads it bilinearly, returning null beside any missing corner. The `movement` flag withholds cells without a complete vector and limits their support to the nearest vector, for path integration.
+
+Render support as opacity or reach, not as confidence in the underlying measurement: it says how far the nearest evidence is, nothing about that evidence's accuracy. The kernel scale is a claim about resolution and belongs in the study's provenance.
+
+`@motionstudies/core/domain/published-day` reads a published day of the national layer as the recording host compiles it: `openPublishedDay` takes a transport (`fetchTransport` over a base URL, or any pair of text and bytes readers) and returns the manifest and index up front, then slices, members and packs on demand and cached per file; `partFor` resolves an operator and vehicle to the pack part that holds it; `sliceNameAt` and `cellOf` reproduce the compiler's slice and cell rules exactly, so a position lands in the cell the compiler put it in; `positionAt` interpolates along a track only inside a tolerated gap, and `journeyAt` finds the run in force at an instant. Before a composition is built on a day, `checkDayManifest` reports any disagreement between the manifest's hours, slice count, file list and totals, and `reconcileSlice` reports any cell whose distinct-vehicle count differs from its members or that appears in only one of the two files; both return an empty list when consistent. A trimmed fixture fails the manifest check by design. Packs are gunzipped with the platform's `DecompressionStream` unless an inflater is supplied.
+
+`@motionstudies/core/domain/gridded-series` reads a regular latitude/longitude grid of variables at listed instants. `bracketTime` finds the adjacent frames; `sampleGriddedSeries` interpolates bilinearly in space and linearly in time; `meanGriddedSeries` returns an area-weighted mean, with an optional valid range. A missing sample with any weight makes the reading unavailable instead of bridging the gap. Values keep the source's units; the consumer converts percentages or applies its own scale.
+
+`@motionstudies/core/domain/field-paths` integrates illustrative paths through an estimated velocity field. `advanceFieldPath` takes an explicit midpoint step in metres per second, with `secondsPerStep` converting one unit of study time, and refuses to start from, pass through or land on unsupported field. `mixFieldMovement` blends two readings; `visibleTrailSegments` returns the last `trail` steps of a track at a study time with a fade at either end, identical when scrubbing back. Paths are neither observed trajectories nor individual movers and must be labelled as illustration.
+
+`@motionstudies/core/domain/daylight` computes `solarPosition` (altitude and azimuth in degrees, azimuth clockwise from north) from the Astronomy Answers low-precision algorithm, matching SunCalc to a thousandth of a degree without a dependency. `daylightAt` adds a unit `direction` towards the sun in a scene frame with +x east, +y up and +z south, and smooth `twilight`, `warmth` and `daylight` envelopes from `DaylightEnvelopes` (defaults: twilight −18° to −1°, warmth rising −12° to −1° and falling 3° to 15°, daylight −1° to 12°). The envelopes are artistic responses to sun altitude and encode no weather or sky observation. Sample several longitudes to place a terminator across a national field.
+
+The lab's **Fields** specimen renders a synthetic archipelago of seven instruments with a mid-study gap and one vectorless instrument, an invented cover series as haze, integrated trails, and a terminator crossing with the study clock. Brightness is the estimate and opacity is support; clicking reads the estimate, cover and sun altitude at a place.
+
+## Recorded power days
+
+`@motionstudies/core/domain/power-day` exports `readPowerDay`, `powerPeriod`, `unitPower`, `plannedPower`, `sumPower` and `fuelMixAt`, plus their data types. A complete civil day declares its timezone, UTC bounds, half-hour intervals, MWh settlement quantities and MW plans/aggregates. Missing values remain null; signed quantities remain signed. Interval energy becomes average power only through the explicit interval duration. Declarations are interpolated only within one unambiguous segment; fuel samples expire after five minutes. Callers choose aggregate membership and receive a missing-contributor count. The reader validates source links, settlement run labels, identities, placement coordinates and safe evidence-artifact paths without fetching data. Source adapters, placement policy and the composition stay outside core. See [power ownership](../docs/POWER.md#ownership-and-handoff).
+
+## Activity timeline
+
+`@motionstudies/core/timeline` supplies validated interval geometry, lookup, time mapping and service-time formatting. `@motionstudies/web/components/StudyTimeline` renders a controlled activity chart and scrubber; import `@motionstudies/web/study-timeline.css`. Pass `bins: {start, end, value}[]`, the time window, current `time` and `onSeek`. A `null` value means missing evidence; zero is a measured zero. `variant="bars"` (default) or `"line"` shares the same time axis. `maximum` optionally fixes the scale for comparisons. Playback and loading remain consumer-owned. See [the full contract](https://github.com/emmettl/motionstudies/blob/main/docs/STUDY-TIMELINE.md) and the Timeline lab specimen.
+
+Canvas editions can import `PausedVehicleFrame` from `@motionstudies/core/render-frame` without loading Three.js. The existing Three.js entry point re-exports the same class. Record only a frame actually submitted; change its visibility revision (or replace the tracker) when data, projection, size or selection changes. Time changes invalidate even while paused.
+
+Plain playback bars can use `@motionstudies/web/components/TimelineScrubber` with `@motionstudies/web/timeline-scrubber.css`: the same visible rail and 44px interaction area as `StudyTimeline`, without activity bins. Pass the time window, time, seek callback and accessible time label.

package/adsb-heatmap.d.mts

@@ -0,0 +1,56 @@
+import type { AirSnapshot, AirTrack } from '@motionstudies/core/domain/air'
+import type { AirDayManifest, AirDayChunk, AirDayChunkDescriptor } from '@motionstudies/core/domain/air-day'
+
+export interface HeatmapWindow {
+  serviceDate: string
+  /** Explicit offset for this recording; the caller owns DST and source date selection. */
+  utcOffsetHours: number
+  windowStart: number
+  windowEnd: number
+  bounds?: readonly [west: number, south: number, east: number, north: number]
+  /** Numeric 24-bit ICAO addresses; omit to decode all aircraft. */
+  addresses?: ReadonlySet<number>
+}
+export type HeatmapSample = [time: number, longitude: number, latitude: number, altitudeFeet: number, speedKnots: number, callsign: string | undefined]
+export interface HeatmapRecord {
+  id: string
+  callsign: string
+  samples: readonly HeatmapSample[]
+}
+export interface HeatmapSource {
+  name: string
+  sha256: string
+  sourceUrl: string
+}
+export type HeatmapMetadata = AirSnapshot['metadata'] & {
+  timezone?: string
+  utcOffsetHours: number
+  sourceFiles: readonly HeatmapSource[]
+}
+export type HeatmapSnapshot = Omit<AirSnapshot, 'metadata'> & { readonly metadata: HeatmapMetadata }
+export type AirChunkIntegrity = AirDayChunkDescriptor & { readonly bytes: number; readonly sha256: string }
+export type ChunkedAirManifest = Omit<AirDayManifest, 'chunks'> & { readonly chunks: readonly AirChunkIntegrity[] }
+export type HeatmapManifest = Omit<ChunkedAirManifest, 'metadata'> & { readonly metadata: HeatmapMetadata }
+
+/** Uncompressed binary input; returns the number of accepted observations. Does not round coordinates. An absent callsign is undefined; an explicitly cleared one is empty. */
+export function decodeAdsbHeatmap(bytes: Uint8Array, options: HeatmapWindow, onSample: (address: number, sample: HeatmapSample) => void): number
+/** Does not mutate the input records. Legacy unsplit snapshots can opt out of flight segmentation. */
+export function transportAirTracks(records: Iterable<HeatmapRecord>, options?: { splitTracks?: boolean }): AirTrack[]
+export function chunkAirSnapshot(snapshot: AirSnapshot, options: {
+  chunkSeconds: number
+  stem: string
+  overlapBefore?: number
+  overlapAfter?: number
+}): { manifest: ChunkedAirManifest; chunks: { descriptor: AirChunkIntegrity; payload: AirDayChunk }[] }
+export interface HeatmapIngestOptions extends HeatmapWindow {
+  inputs: readonly string[]
+  output: string
+  bounds: readonly [west: number, south: number, east: number, north: number]
+  timezone?: string
+  chunkHours?: number
+  /** Defaults true; use false only to preserve a legacy single-track-per-aircraft snapshot. */
+  splitTracks?: boolean
+}
+export function ingestAdsbHeatmaps(options: HeatmapIngestOptions & { chunkHours: number }): Promise<HeatmapManifest>
+export function ingestAdsbHeatmaps(options: HeatmapIngestOptions & { chunkHours?: undefined }): Promise<HeatmapSnapshot>
+export function ingestAdsbHeatmaps(options: HeatmapIngestOptions): Promise<HeatmapSnapshot | HeatmapManifest>

package/adsb-heatmap.mjs

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto'
+import { readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+
+const MAGIC = 0x0e7f7c9d
+const CALLSIGN_MARKER = 0x40000000
+const NON_ICAO_MARKER = 0x01000000
+
+function serviceDayStart(options) {
+  const { serviceDate, utcOffsetHours, windowStart, windowEnd } = options
+  const midnight = Date.parse(`${serviceDate}T00:00:00Z`)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(serviceDate) || !Number.isFinite(midnight) || new Date(midnight).toISOString().slice(0, 10) !== serviceDate) {
+    throw new Error('A valid serviceDate (YYYY-MM-DD) is required')
+  }
+  if (!Number.isFinite(utcOffsetHours) || Math.abs(utcOffsetHours) > 14) throw new Error('A valid local UTC offset is required')
+  if (!Number.isFinite(windowStart) || !Number.isFinite(windowEnd) || windowStart >= windowEnd) throw new Error('A finite, increasing study window is required')
+  if (options.bounds) {
+    const [west, south, east, north] = options.bounds
+    if (options.bounds.length !== 4 || !options.bounds.every(Number.isFinite) || west < -180 || east > 180 || south < -90 || north > 90 || west >= east || south >= north) {
+      throw new Error('bounds must be [west, south, east, north] in geographic degrees')
+    }
+  }
+  return midnight - utcOffsetHours * 3600000
+}
+
+/** Decode an uncompressed readsb heatmap slice. Times remain service-local seconds, including after midnight. */
+export function decodeAdsbHeatmap(bytes, options, onSample) {
+  const dayStart = serviceDayStart(options)
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+  if (buffer.length % 16 !== 0) throw new Error('Truncated heatmap record')
+  const [west, south, east, north] = options.bounds ?? [-180, -90, 180, 90]
+  const callsigns = new Map()
+  let time
+  let count = 0
+  for (let offset = 0; offset < buffer.length; offset += 16) {
+    const address = buffer.readUInt32LE(offset), encodedLatitude = buffer.readInt32LE(offset + 4)
+    if (address === MAGIC) {
+      const milliseconds = Number((BigInt(encodedLatitude) << 32n) | BigInt(buffer.readUInt32LE(offset + 8)))
+      time = Math.round((milliseconds - dayStart) / 1000)
+      continue
+    }
+    const id = address & 0xffffff
+    if ((address & NON_ICAO_MARKER) !== 0 || (options.addresses && !options.addresses.has(id))) continue
+    // Negative latitude also sets this bit in two's complement; it is still a position.
+    if (encodedLatitude >= 0 && (encodedLatitude & CALLSIGN_MARKER) !== 0) {
+      callsigns.set(id, buffer.subarray(offset + 8, offset + 16).toString('ascii').replaceAll('\0', '').trim().toUpperCase())
+      continue
+    }
+    if (time === undefined || time < options.windowStart || time > options.windowEnd) continue
+    const latitude = encodedLatitude / 1e6, longitude = buffer.readInt32LE(offset + 8) / 1e6
+    if (longitude < west || longitude > east || latitude < south || latitude > north) continue
+    const altitude = buffer.readInt16LE(offset + 12), speed = buffer.readInt16LE(offset + 14)
+    if (altitude < 0 || speed < 0) continue
+    onSample(id, [time, longitude, latitude, altitude * 25, speed / 10, callsigns.get(id)])
+    count++
+  }
+  return count
+}
+
+function round(value, digits) {
+  const scale = 10 ** digits
+  return Math.round(value * scale) / scale
+}
+
+function transportScaleTrack(record) {
+  const samples = [...record.samples]
+    .sort((first, second) => first[0] - second[0])
+    .filter((sample, index, all) => index === 0 || sample[0] !== all[index - 1][0])
+    .map((sample) => sample.slice(0, 5))
+  if (samples.length < 4) return undefined
+  const maximumSpeed = samples.reduce((maximum, sample) => Math.max(maximum, sample[4]), 0)
+  const maximumAltitude = samples.reduce((maximum, sample) => Math.max(maximum, sample[3]), 0)
+  const airlineCallsign = /^[A-Z]{2,4}\d[A-Z0-9]*$/.test(record.callsign)
+  if (maximumSpeed < 120 || maximumAltitude < 1_500) return undefined
+  if (!airlineCallsign && (maximumSpeed < 250 || maximumAltitude < 10_000)) return undefined
+  return {
+    id: record.id,
+    callsign: record.callsign || record.id.toUpperCase(),
+    start: samples[0][0],
+    end: samples.at(-1)[0],
+    samples,
+  }
+}
+
+function transportScaleTracks(record) {
+  const ordered = [...record.samples]
+    .sort((first, second) => first[0] - second[0])
+    .filter((sample, index, all) => index === 0 || sample[0] !== all[index - 1][0])
+  const segments = []
+  let current = []
+  let currentCallsign = ''
+
+  for (const sample of ordered) {
+    const callsign = sample[5]
+    const previous = current.at(-1)
+    const callsignChanged = callsign && currentCallsign && callsign !== currentCallsign
+    const longGap = previous && sample[0] - previous[0] > 30 * 60
+    if (current.length && (callsignChanged || longGap)) {
+      segments.push({ callsign: currentCallsign, samples: current })
+      current = []
+      currentCallsign = ''
+    }
+    if (callsign) currentCallsign = callsign
+    current.push(sample)
+  }
+  if (current.length) segments.push({ callsign: currentCallsign, samples: current })
+
+  return segments
+    .map((segment) => {
+      const base = transportScaleTrack({
+        id: record.id,
+        callsign: segment.callsign || record.callsign,
+        samples: segment.samples,
+      })
+      if (!base) return undefined
+      return {
+        ...base,
+        id: `${record.id}-${base.start}`,
+        icaoAddress: record.id,
+      }
+    })
+    .filter(Boolean)
+}
+
+
+/** Stable ordering and IDs; split on a known callsign change or an observation gap over 30 minutes. */
+export function transportAirTracks(records, { splitTracks = true } = {}) {
+  return [...records].flatMap(record => splitTracks
+    ? transportScaleTracks(record)
+    : [transportScaleTrack(record)].filter(Boolean))
+    .sort((first, second) => first.id.localeCompare(second.id))
+}
+
+/** Produce playback chunks with the same 180s trail and 45s interpolation overlap used by the editions. */
+export function chunkAirSnapshot(snapshot, { chunkSeconds, stem, overlapBefore = 180, overlapAfter = 45 }) {
+  if (!Number.isInteger(chunkSeconds) || chunkSeconds <= 0) throw new Error('chunkSeconds must be a positive integer')
+  if (![overlapBefore, overlapAfter].every(value => Number.isFinite(value) && value >= 0)) throw new Error('Chunk overlap must be non-negative')
+  if (!/^[a-zA-Z0-9_-]+$/.test(stem)) throw new Error('A simple chunk filename stem is required')
+  const { windowStart: start, windowEnd: end } = snapshot.metadata
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end) throw new Error('A finite, increasing study window is required')
+  const chunks = []
+  for (let windowStart = start; windowStart < end; windowStart += chunkSeconds) {
+    const windowEnd = Math.min(end, windowStart + chunkSeconds)
+    const id = String(Math.floor(windowStart / chunkSeconds)).padStart(2, '0')
+    const tracks = snapshot.tracks.flatMap(track => {
+      const samples = track.samples.filter(sample => sample[0] >= windowStart - overlapBefore && sample[0] <= windowEnd + overlapAfter)
+      return samples.length < 2 ? [] : [{ ...track, start: samples[0][0], end: samples.at(-1)[0], samples }]
+    })
+    const payload = { windowStart, windowEnd, tracks }
+    const serialized = `${JSON.stringify(payload)}\n`
+    chunks.push({ descriptor: {
+      id, windowStart, windowEnd, path: `${stem}-${id}.json`, trackCount: tracks.length,
+      sampleCount: tracks.reduce((sum, track) => sum + track.samples.length, 0),
+      bytes: Buffer.byteLength(serialized), sha256: createHash('sha256').update(serialized).digest('hex'),
+    }, payload })
+  }
+  const aircraft = snapshot.tracks.map(({ samples: _samples, ...track }) => ({
+    ...track, icaoAddress: track.icaoAddress ?? track.id,
+    chunkIds: chunks.filter(({ descriptor }) => track.end >= descriptor.windowStart && track.start <= descriptor.windowEnd)
+      .map(({ descriptor }) => descriptor.id),
+  }))
+  return { manifest: {
+    metadata: snapshot.metadata, bounds: snapshot.bounds, trackCount: snapshot.tracks.length,
+    sampleCount: snapshot.tracks.reduce((sum, track) => sum + track.samples.length, 0),
+    aircraft, chunks: chunks.map(chunk => chunk.descriptor),
+  }, chunks }
+}
+
+function sourceUrl(date) {
+  return `https://github.com/adsblol/globe_history_${date.slice(0, 4)}/releases/tag/v${date.replaceAll('-', '.')}-planes-readsb-prod-0`
+}
+
+/** Compile cached gzip heatmaps. The caller owns source selection, timezone and output location; no network calls. */
+export async function ingestAdsbHeatmaps(options) {
+  serviceDayStart(options)
+  if (!options.bounds) throw new Error('Study bounds are required')
+  if (!options.inputs?.length) throw new Error('At least one cached heatmap input is required')
+  if (options.chunkHours !== undefined && (!Number.isInteger(options.chunkHours) || options.chunkHours < 1)) throw new Error('chunkHours must be a positive integer')
+  if (!options.output?.endsWith('.json')) throw new Error('An output .json path is required')
+  if (options.timezone) new Intl.DateTimeFormat('en', { timeZone: options.timezone })
+  const records = new Map(), sourceFiles = []
+  // Preserve caller ordering for deterministic first-observation wins when input slices overlap.
+  for (const input of options.inputs) {
+    const raw = await readFile(input), name = basename(input)
+    const date = /^\d{4}-\d{2}-\d{2}/.exec(name)?.[0] ?? options.serviceDate
+    sourceFiles.push({ name, sha256: createHash('sha256').update(raw).digest('hex'), sourceUrl: sourceUrl(date) })
+    decodeAdsbHeatmap(gunzipSync(raw), options, (address, sample) => {
+      const id = address.toString(16).padStart(6, '0')
+      const record = records.get(id) ?? { id, callsign: '', samples: [] }
+      record.callsign = sample[5] || record.callsign
+      record.samples.push([sample[0], round(sample[1], 5), round(sample[2], 5), sample[3], round(sample[4], 1), record.callsign])
+      records.set(id, record)
+    })
+  }
+  const tracks = transportAirTracks(records.values(), { splitTracks: options.splitTracks ?? true })
+  const [minLongitude, minLatitude, maxLongitude, maxLatitude] = options.bounds
+  const snapshot = {
+    metadata: {
+      publisher: 'ADSB.lol', ...(options.timezone ? { timezone: options.timezone } : {}),
+      utcOffsetHours: options.utcOffsetHours, sourceFiles,
+      serviceDate: options.serviceDate, windowStart: options.windowStart, windowEnd: options.windowEnd,
+      sourceUrl: sourceUrl(options.serviceDate), license: 'ODbL 1.0',
+      licenseUrl: 'https://opendatacommons.org/licenses/odbl/1-0/',
+      model: 'Observed ADS-B / MLAT heatmap positions replayed at 10-second resolution',
+      note: 'Ground, non-ICAO, low-speed and low-altitude signals are excluded; altitude is rendered with explicit vertical compression.',
+      sampleIntervalSeconds: 10,
+    },
+    bounds: { minLongitude, minLatitude, maxLongitude, maxLatitude }, tracks,
+  }
+  if (options.chunkHours !== undefined) {
+    const { manifest, chunks } = chunkAirSnapshot(snapshot, {
+      chunkSeconds: options.chunkHours * 3600, stem: basename(options.output, '.json').replace(/-manifest$/, ''),
+    })
+    for (const { descriptor, payload } of chunks) {
+      await writeFile(join(dirname(options.output), descriptor.path), `${JSON.stringify(payload)}\n`)
+    }
+    await writeFile(options.output, `${JSON.stringify(manifest)}\n`)
+    return manifest
+  }
+  await writeFile(options.output, `${JSON.stringify(snapshot)}\n`)
+  return snapshot
+}

package/air-endpoints.d.mts

@@ -0,0 +1,7 @@
+import type { AirContinent, AirContinentSource } from '@motionstudies/core/air-continents'
+import type { AirEndpoint, AirSample } from '@motionstudies/core/domain/air'
+export interface EndpointAirport { icao: string; iata: string; name: string; city: string; longitude: number; latitude: number; elevation: number; continent?: AirContinent; continentSource?: AirContinentSource }
+export interface AirContinentOverride { airportIdent: string; continent: AirContinent; reason: string }
+export function parseAirports(csv: string, options?: { continentOverrides?: readonly AirContinentOverride[] }): EndpointAirport[]
+export function inferAirEndpoints(samples: readonly AirSample[], airports: readonly EndpointAirport[]): { origin?: AirEndpoint; destination?: AirEndpoint }
+export function enrichAirEndpoints(options: { manifestPath: string; snapshotPaths?: string[]; heatmapDirectory: string; airportCsvPath: string; utcOffsetHours: number }): Promise<{ tracks: number; origins: number; destinations: number }>