@motionstudies/core 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -5,7 +5,7 @@ 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/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'
@@ -76,6 +76,86 @@ Pass `labels` for edition translations, `loading`, or a localized `error` and `o
 
 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.
@@ -83,3 +163,19 @@ Empty messages also appear on the flaps, in the widest column (the destination/o
 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.
+
+## 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).

package/domain/live-airport.d.ts

@@ -0,0 +1,42 @@
+/** Live boards use Unix seconds throughout, independent of an edition's recorded service day. */
+export interface LiveAirportMovement {
+    readonly id: string;
+    readonly service: string;
+    readonly scheduledTime?: number;
+    /** Provider revision: may be estimated or actual; do not relabel as confirmed. */
+    readonly revisedTime?: number;
+    readonly place?: string;
+    readonly gate?: string;
+    readonly status?: string;
+    readonly tone?: 'neutral' | 'accent' | 'warning';
+}
+export interface LiveAirportSnapshot {
+    readonly airport: {
+        readonly iata: string;
+        readonly name: string;
+        readonly city: string;
+        readonly timeZone: string;
+    };
+    readonly fetchedAt: number;
+    readonly freshUntil: number;
+    readonly expiresAt: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly departures: readonly LiveAirportMovement[];
+    readonly arrivals: readonly LiveAirportMovement[];
+}
+export type AirportFeedReason = 'disabled' | 'not-configured' | 'subscription' | 'budget' | 'provider' | 'rate-limit';
+export interface AirportFeedResponse {
+    readonly version: 1;
+    readonly status: 'fresh' | 'stale' | 'unavailable' | 'disabled';
+    readonly reason?: AirportFeedReason;
+    readonly retryAfterSeconds: number;
+    readonly snapshot?: LiveAirportSnapshot;
+}
+export interface AirportFeedCapabilities {
+    readonly version: 1;
+    readonly enabled: boolean;
+    readonly airports: readonly string[];
+}
+/** Validate the network boundary before publishing data to a card. */
+export declare function isAirportFeedResponse(value: unknown): value is AirportFeedResponse;

package/domain/live-airport.js

@@ -0,0 +1,32 @@
+const record = (value) => !!value && typeof value === 'object';
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+function movement(value) {
+    return record(value) && typeof value.id === 'string' && typeof value.service === 'string'
+        && ['scheduledTime', 'revisedTime'].every((key) => value[key] === undefined || finite(value[key]))
+        && ['place', 'gate', 'status'].every((key) => value[key] === undefined || typeof value[key] === 'string')
+        && (value.tone === undefined || ['neutral', 'accent', 'warning'].includes(String(value.tone)));
+}
+/** Validate the network boundary before publishing data to a card. */
+export function isAirportFeedResponse(value) {
+    if (!record(value) || value.version !== 1 || !['fresh', 'stale', 'unavailable', 'disabled'].includes(String(value.status))
+        || !finite(value.retryAfterSeconds) || value.retryAfterSeconds < 0)
+        return false;
+    if (value.status === 'disabled' || value.status === 'unavailable')
+        return value.snapshot === undefined;
+    const s = value.snapshot;
+    try {
+        if (!record(s) || !record(s.airport) || typeof s.airport.timeZone !== 'string')
+            return false;
+        new Intl.DateTimeFormat('en', { timeZone: s.airport.timeZone }).format(0);
+    }
+    catch {
+        return false;
+    }
+    return record(s) && record(s.airport)
+        && ['iata', 'name', 'city', 'timeZone'].every((key) => typeof s.airport[key] === 'string')
+        && ['fetchedAt', 'freshUntil', 'expiresAt', 'windowStart', 'windowEnd'].every((key) => finite(s[key]))
+        && Number(s.fetchedAt) <= Number(s.freshUntil) && Number(s.freshUntil) <= Number(s.expiresAt)
+        && Number(s.windowStart) < Number(s.windowEnd)
+        && Array.isArray(s.departures) && s.departures.every(movement)
+        && Array.isArray(s.arrivals) && s.arrivals.every(movement);
+}

package/domain/station-departures.d.ts

@@ -0,0 +1,15 @@
+import type { NetworkSnapshot, ServiceCategory } from './network.ts';
+export interface StationDeparture {
+    readonly id: string;
+    readonly trainId: string;
+    /** Time from the supplied snapshot: realtime-adjusted snapshots contain adjusted times. */
+    readonly time: number;
+    readonly service: string;
+    readonly category: ServiceCategory;
+    readonly destination: string;
+    readonly platform?: string;
+    readonly via: readonly string[];
+    readonly status: 'scheduled' | 'adjusted' | 'cancelled';
+}
+/** Resolve the station against this snapshot, retaining repeat calls but excluding terminators. */
+export declare function stationDepartures(snapshot: NetworkSnapshot, stationName: string): readonly StationDeparture[];

package/domain/station-departures.js

@@ -0,0 +1,25 @@
+/** Resolve the station against this snapshot, retaining repeat calls but excluding terminators. */
+export function stationDepartures(snapshot, stationName) {
+    const stopIndexes = new Set();
+    snapshot.stops.forEach((stop, index) => { if (stop[2] === stationName)
+        stopIndexes.add(index); });
+    if (!stopIndexes.size)
+        return [];
+    const departures = [];
+    for (const train of snapshot.trains) {
+        train.stops.forEach(([stopIndex, , departure], callIndex) => {
+            if (!stopIndexes.has(stopIndex) || !Number.isFinite(departure) || callIndex === train.stops.length - 1)
+                return;
+            const onward = train.stops.slice(callIndex + 1).map(([index]) => snapshot.stops[index]?.[2]).filter((name) => Boolean(name));
+            if (!onward.length)
+                return;
+            const destination = train.headsign.trim() || onward.at(-1);
+            departures.push({ id: `${train.id}:${callIndex}`, trainId: train.id, time: departure,
+                service: train.route || train.shortName, category: train.category, destination,
+                platform: snapshot.stops[stopIndex]?.[3]?.trim() || undefined,
+                via: [...new Set(onward.slice(0, -1).filter((name) => name !== stationName && name !== destination))].slice(0, 3),
+                status: train.realtime?.status ?? 'scheduled' });
+        });
+    }
+    return departures.sort((a, b) => a.time - b.time || a.id.localeCompare(b.id));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -144,6 +144,16 @@
       "types": "./domain/train-time-index.d.ts",
       "import": "./domain/train-time-index.js",
       "default": "./domain/train-time-index.js"
+    },
+    "./domain/live-airport": {
+      "types": "./domain/live-airport.d.ts",
+      "import": "./domain/live-airport.js",
+      "default": "./domain/live-airport.js"
+    },
+    "./domain/station-departures": {
+      "types": "./domain/station-departures.d.ts",
+      "import": "./domain/station-departures.js",
+      "default": "./domain/station-departures.js"
     }
   },
   "files": [