@motionstudies/web 0.1.0-alpha.5 → 0.1.0-alpha.7

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'
@@ -25,6 +25,16 @@ 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`.
 
+## 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).
@@ -73,3 +83,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/components/AirportBoard.d.ts

@@ -0,0 +1,27 @@
+import { type AirportHeroCardProps } from './AirportHeroCard.tsx';
+declare const defaults: {
+    study: string;
+    now: string;
+    checking: string;
+    unavailable: string;
+    returnToStudy: string;
+    loading: string;
+    updated: string;
+    stale: string;
+    localTime: string;
+    scheduled: string;
+    revised: string;
+    note: string;
+};
+export interface AirportBoardProps {
+    readonly studyCard: AirportHeroCardProps;
+    readonly live: {
+        readonly baseUrl: string;
+        readonly edition: string;
+        readonly airport: string;
+    };
+    readonly labels?: Partial<typeof defaults>;
+}
+/** Optional live enhancement. Keeps the study clock and recorded flight selection separate. */
+export declare function AirportBoard({ studyCard, live, labels }: AirportBoardProps): import("react").JSX.Element;
+export {};

package/components/AirportBoard.js

@@ -0,0 +1,28 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { AirportHeroCard } from './AirportHeroCard.js';
+import { useAirportFeed } from '../use-airport-feed.js';
+import { useNowClock } from '../use-now-clock.js';
+const defaults = {
+    study: 'Study', now: 'Now', checking: 'Checking live availability…', unavailable: 'Live updates unavailable.',
+    returnToStudy: 'Return to study', loading: 'Loading current airport board…', updated: 'Retrieved', stale: 'Updates delayed',
+    localTime: 'Local time', scheduled: 'Scheduled', revised: 'Revised', note: 'AeroDataBox · Scheduled or revised times as supplied. Revisions may be estimated or actual. All times local. Coverage may be incomplete.',
+};
+/** Optional live enhancement. Keeps the study clock and recorded flight selection separate. */
+export function AirportBoard({ studyCard, live, labels }) {
+    const copy = { ...defaults, ...labels };
+    const clock = useNowClock((instant) => Math.floor(instant.getTime() / 1000));
+    const feed = useAirportFeed(live.baseUrl, live.edition, live.airport, clock.active);
+    const [selected, setSelected] = useState();
+    const response = feed.response, snapshot = response?.snapshot;
+    const now = clock.time ?? snapshot?.fetchedAt ?? 0;
+    const usable = snapshot && snapshot.expiresAt > now && ['fresh', 'stale'].includes(response.status);
+    const stale = usable && (response?.status === 'stale' || now >= snapshot.freshUntil);
+    const timeZone = snapshot?.airport.timeZone ?? 'UTC';
+    const formatter = new Intl.DateTimeFormat(undefined, { timeZone, hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+    const formatTime = (time) => formatter.format(new Date(time * 1000));
+    const dateLabel = new Intl.DateTimeFormat(undefined, { timeZone, day: '2-digit', month: 'short', year: 'numeric' }).format(new Date(now * 1000));
+    function stop() { clock.stop(); setSelected(undefined); }
+    const selectedFlight = usable ? [...snapshot.departures, ...snapshot.arrivals].find((flight) => flight.id === selected) : undefined;
+    return _jsxs("div", { className: "ms-airport-board", children: [_jsxs("div", { className: "ms-airport-board__modes", role: "group", "aria-label": `${copy.study} / ${copy.now}`, children: [_jsx("button", { type: "button", "aria-pressed": !clock.active, onClick: stop, children: copy.study }), _jsx("button", { type: "button", "aria-pressed": clock.active, disabled: !clock.active && !feed.available, onClick: clock.start, children: copy.now }), !clock.active && _jsx("span", { children: feed.checking ? copy.checking : !feed.available ? copy.unavailable : null })] }), _jsx("div", { hidden: clock.active, children: _jsx(AirportHeroCard, { ...studyCard }) }), clock.active && _jsx(_Fragment, { children: usable ? _jsxs(_Fragment, { children: [_jsx(AirportHeroCard, { airport: snapshot.airport, study: { time: now, windowStart: snapshot.windowStart, windowEnd: snapshot.windowEnd }, departures: snapshot.departures.map((f) => ({ ...f, time: f.revisedTime ?? f.scheduledTime, stand: f.gate })), arrivals: snapshot.arrivals.map((f) => ({ ...f, time: f.revisedTime ?? f.scheduledTime, stand: f.gate })), formatTime: formatTime, dateLabel: dateLabel, labels: { ...studyCard.labels, studyTime: copy.localTime }, maxRows: studyCard.maxRows, horizon: studyCard.horizon, selectedFlightId: selected, onSelectFlight: setSelected, note: _jsxs(_Fragment, { children: [_jsxs("span", { role: "status", children: [stale ? `${copy.stale} · ` : '', copy.updated, " ", formatTime(snapshot.fetchedAt), " \u00B7 "] }), copy.note] }) }, snapshot.airport.iata), selectedFlight && _jsxs("p", { className: "ms-airport-board__detail", children: [selectedFlight.service, " \u00B7 ", selectedFlight.place ?? '—', " \u00B7 ", selectedFlight.status ?? '—', selectedFlight.scheduledTime !== undefined && _jsxs(_Fragment, { children: [" \u00B7 ", copy.scheduled, " ", formatTime(selectedFlight.scheduledTime)] }), selectedFlight.revisedTime !== undefined && _jsxs(_Fragment, { children: [" \u00B7 ", copy.revised, " ", formatTime(selectedFlight.revisedTime)] })] })] }) : _jsxs("div", { className: "ms-airport-board__unavailable", role: "status", children: [_jsx("p", { children: feed.loading || feed.checking ? copy.loading : copy.unavailable }), _jsx("button", { type: "button", onClick: stop, children: copy.returnToStudy })] }) })] });
+}

package/components/AirportHeroCard.js

@@ -1,4 +1,4 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useState } from 'react';
 import { formatServiceTime } from '@motionstudies/core/domain/network';
 import { movementBoardWindow, movementsForBoard } from '@motionstudies/core/domain/movement-board';
@@ -20,12 +20,12 @@ export function AirportHeroCard({ airport, departures, arrivals, note, study, ho
     const entries = movementsForBoard(direction === 'departures' ? departures : arrivals, window, maxRows);
     const rows = entries.map((entry) => ({ id: entry.id, tone: entry.tone,
         cells: { time: formatTime(entry.time), service: entry.service, place: entry.place, stand: entry.stand, status: entry.status } }));
-    return _jsxs("section", { className: `ms-airport-hero ${className}`, "aria-labelledby": titleId, children: [_jsxs("div", { className: "ms-airport-hero__masthead", children: [_jsxs("span", { className: "ms-airport-hero__eyebrow", children: [_jsx("span", { "aria-hidden": "true", children: "\u2197" }), " ", copy.airport, " / ", airport.city] }), _jsxs("span", { className: "ms-airport-hero__clock", children: [dateLabel && _jsxs(_Fragment, { children: [dateLabel, " \u00B7 "] }), copy.studyTime, " ", Number.isFinite(study.time) ? formatTime(study.time) : '—'] })] }), _jsxs("div", { className: "ms-airport-hero__identity", children: [_jsx("strong", { className: "ms-airport-hero__code", children: airport.iata }), _jsx("h2", { id: titleId, children: airport.name }), _jsx("span", { className: "ms-airport-hero__runway", "aria-hidden": "true" })] }), _jsx("div", { className: "ms-airport-hero__directions", role: "group", "aria-label": `${copy.departures} / ${copy.arrivals}`, children: ['departures', 'arrivals'].map((value) => _jsxs("button", { type: "button", "aria-pressed": direction === value, "aria-controls": boardId, onClick: () => setDirection(value), children: [_jsx("span", { "aria-hidden": "true", children: value === 'departures' ? '↗' : '↘' }), " ", copy[value]] }, value)) }), _jsx("p", { className: "ms-airport-hero__window", children: window ? `${copy.boardWindow} ${formatTime(window.start)}–${formatTime(window.end)}` : copy.outsideWindow }), _jsx("div", { id: boardId, children: error ? _jsxs("div", { className: "ms-airport-hero__message", role: "status", children: [error, onRetry && _jsx("button", { type: "button", onClick: onRetry, children: copy.retry })] })
+    return _jsxs("section", { className: `ms-airport-hero ${className}`, "aria-labelledby": titleId, children: [_jsxs("div", { className: "ms-airport-hero__masthead", children: [_jsxs("span", { className: "ms-airport-hero__eyebrow", children: [_jsx("span", { "aria-hidden": "true", children: "\u2197" }), " ", copy.airport, " / ", airport.city] }), dateLabel && _jsx("span", { className: "ms-airport-hero__date", children: dateLabel })] }), _jsxs("div", { className: "ms-airport-hero__identity", children: [_jsx("strong", { className: "ms-airport-hero__code", children: airport.iata }), _jsx("h2", { id: titleId, children: airport.name }), _jsxs("div", { className: "ms-airport-hero__clock", children: [_jsx("span", { className: "ms-airport-hero__clock-label", children: copy.studyTime }), ' ', _jsx("strong", { className: "ms-airport-hero__clock-value", children: Number.isFinite(study.time) ? formatTime(study.time) : '—' })] })] }), _jsxs("div", { className: "ms-airport-hero__board-header", children: [_jsx("div", { className: "ms-airport-hero__directions", role: "group", "aria-label": `${copy.departures} / ${copy.arrivals}`, children: ['departures', 'arrivals'].map((value) => _jsxs("button", { type: "button", "aria-pressed": direction === value, "aria-controls": boardId, onClick: () => setDirection(value), children: [_jsx("span", { "aria-hidden": "true", children: value === 'departures' ? '↗' : '↘' }), " ", copy[value]] }, value)) }), _jsx("p", { className: "ms-airport-hero__window", children: window ? `${copy.boardWindow} ${formatTime(window.start)}–${formatTime(window.end)}` : copy.outsideWindow })] }), _jsx("div", { id: boardId, children: error ? _jsxs("div", { className: "ms-airport-hero__message", role: "status", children: [error, onRetry && _jsx("button", { type: "button", onClick: onRetry, children: copy.retry })] })
                     : _jsx(SplitFlapBoard, { label: `${airport.iata} ${copy[direction]}`, columns: [
                             { key: 'time', label: copy.time, characters: 5 },
                             { key: 'service', label: copy.service, characters: 7 },
-                            { key: 'place', label: direction === 'departures' ? copy.destination : copy.origin, characters: 16 },
+                            { key: 'place', label: direction === 'departures' ? copy.destination : copy.origin, characters: 18 },
                             { key: 'stand', label: copy.stand, characters: 3 },
-                            { key: 'status', label: copy.status, characters: 10 },
+                            { key: 'status', label: copy.status, characters: 11 },
                         ], rows: rows, loading: loading, loadingMessage: copy.loading, loadingRows: rows.length || Math.min(maxRows, 5), emptyMessage: direction === 'departures' ? copy.emptyDepartures : copy.emptyArrivals, selectionColumn: "service", onSelectRow: onSelectFlight, selectedRowId: selectedFlightId }) }), _jsx("div", { className: "ms-airport-hero__note", children: note })] });
 }

package/components/airport-hero-card.css

@@ -1,21 +1,42 @@
 @import './split-flap-board.css';
 
-.ms-airport-hero { --airport-accent: #edc96b; color: #f0ecdd; background: linear-gradient(125deg, #292d27, #191d19 65%); border: 1px solid #4b4d40; border-radius: 12px; padding: clamp(16px, 3vw, 30px); box-shadow: 0 20px 60px #0003; font-family: ui-sans-serif, system-ui, sans-serif; min-width: 0; }
-.ms-airport-hero__masthead { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 8px; }
+.ms-airport-hero { --airport-accent: #edc96b; container-type: inline-size; color: #f0ecdd; background: linear-gradient(125deg, #292d27, #191d19 65%); border: 1px solid #4b4d40; border-radius: 12px; padding: clamp(16px, 3vw, 30px); box-shadow: 0 20px 60px #0003; font-family: ui-sans-serif, system-ui, sans-serif; min-width: 0; }
+.ms-airport-hero__masthead { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 8px 16px; }
 .ms-airport-hero__eyebrow { color: var(--airport-accent); text-transform: uppercase; font-size: 10px; letter-spacing: .18em; }
 .ms-airport-hero__eyebrow > span { font-size: 18px; margin-right: 6px; }
-.ms-airport-hero__clock { color: #bebfac; font: 12px/1.5 ui-monospace, monospace; }
-.ms-airport-hero__window { color: #bebfac; font: 11px/1.5 ui-monospace, monospace; margin: 0 0 12px; }
-.ms-airport-hero__identity { display: flex; align-items: center; flex-wrap: wrap; gap: 12px 24px; padding: 22px 0 26px; }
-.ms-airport-hero__code { color: var(--airport-accent); font-size: clamp(54px, 8vw, 88px); font-weight: 650; line-height: .95; letter-spacing: -.065em; }
-.ms-airport-hero__identity h2 { flex: 1; min-width: 140px; max-width: 300px; color: #f0ecdd; font: 400 clamp(20px, 3vw, 27px)/1.15 ui-sans-serif, system-ui, sans-serif; letter-spacing: -.025em; margin: 0; overflow-wrap: anywhere; }
-.ms-airport-hero__runway { margin-left: auto; width: 54px; height: 62px; border-inline: 1px solid #797c6166; transform: skewY(-20deg); background: repeating-linear-gradient(to bottom, #b5b79266 0 8px, transparent 8px 16px) center / 2px 100% no-repeat; }
-.ms-airport-hero__directions { display: flex; gap: 22px; border-bottom: 1px solid #4b4d40; margin-bottom: 16px; }
-.ms-airport-hero__directions button { padding: 10px 0 12px; margin-bottom: -1px; border: 0; border-bottom: 2px solid transparent; border-radius: 0; background: transparent; color: #b8baaa; font: 500 13px/1.4 ui-sans-serif, system-ui, sans-serif; cursor: pointer; }
+.ms-airport-hero__date { color: #bebfac; font: 11px/1.5 ui-monospace, monospace; letter-spacing: .06em; }
+.ms-airport-hero__identity { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: 18px 24px; padding: 18px 0 20px; }
+.ms-airport-hero__code { color: var(--airport-accent); font-size: clamp(54px, 10cqi, 82px); font-weight: 650; line-height: .95; letter-spacing: -.065em; }
+.ms-airport-hero__identity h2 { max-width: 300px; color: #f0ecdd; font: 400 clamp(20px, 3.3cqi, 27px)/1.15 ui-sans-serif, system-ui, sans-serif; letter-spacing: -.025em; margin: 0; overflow-wrap: anywhere; }
+.ms-airport-hero__clock { padding-left: 24px; border-left: 1px solid #797c6155; text-align: right; }
+.ms-airport-hero__clock-label { display: block; color: #bebfac; font-size: 10px; line-height: 1.5; letter-spacing: .12em; text-transform: uppercase; }
+.ms-airport-hero__clock-value { display: block; margin-top: 4px; color: #f0ecdd; font: 400 42px/1.1 ui-monospace, monospace; font-variant-numeric: tabular-nums; letter-spacing: -.06em; white-space: nowrap; }
+.ms-airport-hero__board-header { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 0 20px; border-bottom: 1px solid #4b4d40; margin-bottom: 14px; }
+.ms-airport-hero__directions { display: flex; gap: 22px; }
+.ms-airport-hero__directions button { min-height: 44px; padding: 10px 0 12px; margin-bottom: -1px; border: 0; border-bottom: 2px solid transparent; border-radius: 0; background: transparent; color: #b8baaa; font: 500 13px/1.4 ui-sans-serif, system-ui, sans-serif; cursor: pointer; }
 .ms-airport-hero__directions button[aria-pressed='true'] { color: var(--airport-accent); border-bottom-color: var(--airport-accent); }
 .ms-airport-hero__directions button:hover { color: #f0ecdd; }
+.ms-airport-hero__window { color: #bebfac; font: 11px/1.5 ui-monospace, monospace; font-variant-numeric: tabular-nums; margin: 8px 0; }
 .ms-airport-hero button:focus-visible { outline: 2px solid var(--airport-accent); outline-offset: 4px; }
+.ms-airport-hero .ms-flap { font-size: 17px; }
+.ms-airport-hero .ms-split-flap-board__table th { color: #c4c3b0; font-size: 11px; letter-spacing: .12em; padding-bottom: 5px; }
 .ms-airport-hero__message { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; padding: 30px 0; margin: 0; font-size: 14px; color: #c5c7b6; }
 .ms-airport-hero__message button { background: #30352a; border: 1px solid #666b50; border-radius: 4px; color: var(--airport-accent); padding: 6px 12px; font: inherit; cursor: pointer; }
 .ms-airport-hero__note { color: #b8baaa; font-size: 11px; line-height: 1.6; margin-top: 14px; }
-@media (max-width: 480px) { .ms-airport-hero__runway { display: none; } .ms-airport-hero__directions { gap: 18px; } }
+@container (max-width: 600px) {
+  .ms-airport-hero__identity { grid-template-columns: auto minmax(0, 1fr); gap: 16px; }
+  .ms-airport-hero__clock { grid-column: 1 / -1; display: flex; align-items: baseline; justify-content: space-between; gap: 12px; padding: 12px 0 0; border-left: 0; border-top: 1px solid #797c6155; text-align: left; }
+  .ms-airport-hero__clock-value { margin-top: 0; font-size: 32px; }
+}
+@container (max-width: 440px) {
+  .ms-airport-hero__board-header { gap: 4px; }
+  .ms-airport-hero__directions { width: 100%; gap: 20px; }
+  .ms-airport-hero__window { margin: 6px 0 10px; }
+}
+.ms-airport-board__modes { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin-bottom: 12px; color: #b8baaa; font: 12px/1.5 ui-sans-serif, system-ui, sans-serif; }
+.ms-airport-board__modes button, .ms-airport-board__unavailable button { min-height: 44px; padding: 8px 16px; border: 1px solid #4b4d40; border-radius: 6px; color: #f0ecdd; background: #1d211c; font: inherit; cursor: pointer; }
+.ms-airport-board__modes button[aria-pressed='true'] { border-color: #edc96b; color: #edc96b; }
+.ms-airport-board__modes button:disabled { opacity: .5; cursor: default; }
+.ms-airport-board__modes button:focus-visible, .ms-airport-board__unavailable button:focus-visible { outline: 2px solid #edc96b; outline-offset: 3px; }
+.ms-airport-board__unavailable { padding: 28px; border: 1px solid #4b4d40; border-radius: 12px; color: #f0ecdd; background: #1d211c; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
+.ms-airport-board__detail { color: #b8baaa; font: 13px/1.6 ui-sans-serif, system-ui, sans-serif; overflow-wrap: anywhere; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -20,6 +20,16 @@
     "tag": "next"
   },
   "exports": {
+    "./use-now-clock": {
+      "types": "./use-now-clock.d.ts",
+      "import": "./use-now-clock.js",
+      "default": "./use-now-clock.js"
+    },
+    "./use-browser-location": {
+      "types": "./use-browser-location.d.ts",
+      "import": "./use-browser-location.js",
+      "default": "./use-browser-location.js"
+    },
     "./components/SplitFlapBoard": {
       "types": "./components/SplitFlapBoard.d.ts",
       "import": "./components/SplitFlapBoard.js",
@@ -89,6 +99,16 @@
       "types": "./components/ButtonTooltips.d.ts",
       "import": "./components/ButtonTooltips.js",
       "default": "./components/ButtonTooltips.js"
+    },
+    "./use-airport-feed": {
+      "types": "./use-airport-feed.d.ts",
+      "import": "./use-airport-feed.js",
+      "default": "./use-airport-feed.js"
+    },
+    "./components/AirportBoard": {
+      "types": "./components/AirportBoard.d.ts",
+      "import": "./components/AirportBoard.js",
+      "default": "./components/AirportBoard.js"
     }
   },
   "files": [
@@ -104,7 +124,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.5"
+    "@motionstudies/core": "0.1.0-alpha.7"
   },
   "peerDependencies": {
     "react": "^19.2.8",

package/use-airport-feed.d.ts

@@ -0,0 +1,9 @@
+import { type AirportFeedResponse } from '@motionstudies/core/domain/live-airport';
+export interface AirportFeedState {
+    readonly available: boolean;
+    readonly checking: boolean;
+    readonly loading: boolean;
+    readonly response?: AirportFeedResponse;
+}
+/** Fetch capabilities without paid work; poll boards only while Now is selected. */
+export declare function useAirportFeed(baseUrl: string, edition: string, airport: string, enabled: boolean): AirportFeedState;

package/use-airport-feed.js

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react';
+import { isAirportFeedResponse } from '@motionstudies/core/domain/live-airport';
+/** Fetch capabilities without paid work; poll boards only while Now is selected. */
+export function useAirportFeed(baseUrl, edition, airport, enabled) {
+    const source = `${baseUrl.replace(/\/$/, '')}/api/airports/v1/${encodeURIComponent(edition)}`;
+    const identity = `${source}/${airport}/${enabled}`;
+    const empty = { available: false, checking: true, loading: false };
+    const [stored, setStored] = useState({ ...empty, identity });
+    const state = stored.identity === identity ? stored : empty;
+    useEffect(() => {
+        const controller = new AbortController();
+        let timer, failures = 0;
+        const update = (patch) => {
+            if (!controller.signal.aborted)
+                setStored((old) => ({ ...(old.identity === identity ? old : empty), ...patch, identity }));
+        };
+        update(empty);
+        const tick = async () => {
+            let delay = 60_000;
+            if (document.hidden) {
+                timer = window.setTimeout(() => void tick(), delay);
+                return;
+            }
+            try {
+                const options = { cache: 'no-store', signal: AbortSignal.any([controller.signal, AbortSignal.timeout(20_000)]) };
+                const capabilitiesResponse = await fetch(`${source}/capabilities`, options);
+                if (!capabilitiesResponse.ok)
+                    throw new Error('Capabilities unavailable');
+                const capabilities = await capabilitiesResponse.json();
+                if (capabilities.version !== 1 || typeof capabilities.enabled !== 'boolean' || !Array.isArray(capabilities.airports))
+                    throw new Error('Invalid capabilities');
+                const available = capabilities.enabled && capabilities.airports.includes(airport);
+                update({ available, checking: false });
+                if (!available) {
+                    update({ loading: false, response: { version: 1, status: 'disabled', reason: 'disabled', retryAfterSeconds: 60 } });
+                }
+                else if (enabled) {
+                    update({ loading: true });
+                    const r = await fetch(`${source}/${encodeURIComponent(airport)}/board`, options);
+                    const response = await r.json();
+                    if (!isAirportFeedResponse(response))
+                        throw new Error('Invalid board');
+                    if (response.snapshot && (response.snapshot.airport.iata !== airport || response.snapshot.fetchedAt > Date.now() / 1000 + 60))
+                        throw new Error('Mismatched board');
+                    update({ response, loading: false, available: response.status !== 'disabled' });
+                    // Check capabilities every minute even when the upstream circuit is paused.
+                }
+                failures = 0;
+            }
+            catch {
+                failures += 1;
+                delay = Math.min(300_000, 30_000 * 2 ** Math.min(failures, 4));
+                if (!controller.signal.aborted)
+                    setStored((old) => {
+                        const snapshot = old.identity === identity ? old.response?.snapshot : undefined;
+                        return { identity, available: old.identity === identity && old.available, checking: false, loading: false,
+                            response: { version: 1, status: snapshot && snapshot.expiresAt > Date.now() / 1000 ? 'stale' : 'unavailable', reason: 'provider', retryAfterSeconds: delay / 1000,
+                                ...(snapshot && snapshot.expiresAt > Date.now() / 1000 ? { snapshot } : {}) } };
+                    });
+            }
+            finally {
+                if (!controller.signal.aborted)
+                    timer = window.setTimeout(() => void tick(), delay);
+            }
+        };
+        void tick();
+        return () => { controller.abort(); window.clearTimeout(timer); };
+        // empty is deliberately reconstructed only when the source effect restarts.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [identity, source, airport, enabled]);
+    return state;
+}

package/use-browser-location.d.ts

@@ -0,0 +1,13 @@
+export interface BrowserLocation {
+    readonly longitude: number;
+    readonly latitude: number;
+    readonly accuracy: number;
+}
+export type BrowserLocationStatus = 'idle' | 'locating' | 'ready' | 'denied' | 'timeout' | 'unavailable';
+/** One explicit request, kept in memory. Clearing or unmounting ignores late replies. */
+export declare function useBrowserLocation(): {
+    location: BrowserLocation | undefined;
+    status: BrowserLocationStatus;
+    locate: () => void;
+    clear: () => void;
+};

package/use-browser-location.js

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** One explicit request, kept in memory. Clearing or unmounting ignores late replies. */
+export function useBrowserLocation() {
+    const [location, setLocation] = useState();
+    const [status, setStatus] = useState('idle');
+    const request = useRef(0);
+    useEffect(() => () => { request.current += 1; }, []);
+    const clear = useCallback(() => {
+        request.current += 1;
+        setLocation(undefined);
+        setStatus('idle');
+    }, []);
+    const locate = useCallback(() => {
+        const id = ++request.current;
+        setLocation(undefined);
+        if (!navigator.geolocation) {
+            setStatus('unavailable');
+            return;
+        }
+        setStatus('locating');
+        navigator.geolocation.getCurrentPosition(({ coords }) => {
+            if (request.current !== id)
+                return;
+            if (!Number.isFinite(coords.longitude) || !Number.isFinite(coords.latitude) ||
+                Math.abs(coords.longitude) > 180 || Math.abs(coords.latitude) > 90 ||
+                !Number.isFinite(coords.accuracy) || coords.accuracy < 0) {
+                setStatus('unavailable');
+                return;
+            }
+            setLocation({ longitude: coords.longitude, latitude: coords.latitude, accuracy: coords.accuracy });
+            setStatus('ready');
+        }, (error) => {
+            if (request.current !== id)
+                return;
+            setStatus(error.code === 1 ? 'denied' : error.code === 3 ? 'timeout' : 'unavailable');
+        }, { enableHighAccuracy: false, maximumAge: 0, timeout: 10_000 });
+    }, []);
+    return { location, status, locate, clear };
+}

package/use-now-clock.d.ts

@@ -0,0 +1,11 @@
+/** The consumer maps an instant into its own service date, timezone and data window.
+ * The consumer may explicitly choose a representative timetable for the present.
+ * Return null when its data cannot meaningfully represent that instant.
+ */
+export declare function useNowClock(resolveTime: (instant: Date) => number | null): {
+    active: boolean;
+    time: number | null;
+    unavailable: boolean;
+    start: () => void;
+    stop: () => void;
+};

package/use-now-clock.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+/** The consumer maps an instant into its own service date, timezone and data window.
+ * The consumer may explicitly choose a representative timetable for the present.
+ * Return null when its data cannot meaningfully represent that instant.
+ */
+export function useNowClock(resolveTime) {
+    const [active, setActive] = useState(false);
+    const [time, setTime] = useState(null);
+    const [unavailable, setUnavailable] = useState(false);
+    const running = useRef(false);
+    const resolver = useRef(resolveTime);
+    useLayoutEffect(() => { resolver.current = resolveTime; }, [resolveTime]);
+    const update = useCallback(() => {
+        const next = resolver.current(new Date());
+        if (next === null || !Number.isFinite(next)) {
+            running.current = false;
+            setActive(false);
+            setUnavailable(true);
+            return false;
+        }
+        setTime(next);
+        return true;
+    }, []);
+    const start = useCallback(() => {
+        setUnavailable(false);
+        running.current = update();
+        setActive(running.current);
+    }, [update]);
+    const stop = useCallback(() => {
+        running.current = false;
+        setActive(false);
+    }, []);
+    useEffect(() => {
+        if (!active)
+            return;
+        let frame;
+        const tick = () => {
+            if (running.current && update())
+                frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [active, update]);
+    return { active, time, unavailable, start, stop };
+}