@motionstudies/core 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -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.
@@ -99,3 +179,17 @@ See [service architecture and operations](../docs/LIVE-AIRPORTS.md). The Worker
 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.

package/domain/network.js

@@ -69,7 +69,7 @@ export function buildStationIndex(snapshot) {
         routes: [...record.routes.values()].sort((first, second) => first.name.localeCompare(second.name, 'de-CH')),
     }));
 }
-export function positionForTrain(train, time) {
+function linearPositionForTrain(train, time) {
     if (train.realtime?.status === 'cancelled' ||
         time < train.start ||
         time > train.end ||
@@ -98,6 +98,42 @@ export function positionForTrain(train, time) {
     const last = train.stops.at(-1);
     return { fromStop: last[0], toStop: last[0], progress: 0 };
 }
+// Timetables are immutable. A replacement stop array (including realtime edits)
+// gets its own validation; old schedules can be garbage collected.
+const chronologicalSchedules = new WeakMap();
+export function positionForTrain(train, time) {
+    if (train.realtime?.status === 'cancelled' || time < train.start || time > train.end || train.stops.length < 2)
+        return;
+    const stops = train.stops;
+    let chronological = chronologicalSchedules.get(stops);
+    if (chronological === undefined) {
+        chronological = stops.every((stop, index) => Number.isFinite(stop[1]) && Number.isFinite(stop[2]) &&
+            stop[2] >= stop[1] && (index === 0 || stop[1] >= stops[index - 1][2]));
+        chronologicalSchedules.set(stops, chronological);
+    }
+    // Preserve sequential semantics for unordered observations and non-finite clocks.
+    if (!chronological || !Number.isFinite(time))
+        return linearPositionForTrain(train, time);
+    let lower = 0;
+    let upper = stops.length;
+    while (lower < upper) {
+        const middle = (lower + upper) >>> 1;
+        if (stops[middle][2] < time)
+            lower = middle + 1;
+        else
+            upper = middle;
+    }
+    const next = stops[Math.min(lower, stops.length - 1)];
+    if (lower === 0 || lower === stops.length || time > next[1]) {
+        return { fromStop: next[0], toStop: next[0], progress: 0 };
+    }
+    const previous = stops[lower - 1];
+    return {
+        fromStop: previous[0], toStop: next[0],
+        progress: Math.min(1, Math.max(0, (time - previous[2]) / Math.max(1, next[1] - previous[2]))),
+        segmentIndex: lower - 1,
+    };
+}
 export function formatServiceTime(totalSeconds) {
     const normalized = ((Math.round(totalSeconds) % 86400) + 86400) % 86400;
     const hours = Math.floor(normalized / 3600);

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/domain/vehicle-counts.d.ts

@@ -0,0 +1,13 @@
+import type { NetworkSnapshot, NetworkTrain, ServiceCategory, StationIndexEntry } from './network.ts';
+export declare function countableVehicleTrains(network: NetworkSnapshot | undefined, stations: readonly StationIndexEntry[], selection: {
+    category?: ServiceCategory;
+    station?: Pick<StationIndexEntry, 'name'>;
+    route?: {
+        name: string;
+        category: ServiceCategory;
+    };
+}): readonly NetworkTrain[];
+/** Build once per immutable selection; clock updates need only two binary searches. */
+export declare function createActiveTimetableVehicleCounter(trains: readonly NetworkTrain[], options?: {
+    readonly requirePositionable?: boolean;
+}): (time: number) => number;

package/domain/vehicle-counts.js

@@ -0,0 +1,33 @@
+export function countableVehicleTrains(network, stations, selection) {
+    const stationTrainIds = selection.station
+        ? new Set(stations.find(station => station.name === selection.station?.name)?.trainIds ?? [])
+        : undefined;
+    return network?.trains.filter(train => (!selection.category || train.category === selection.category) &&
+        (!stationTrainIds || stationTrainIds.has(train.id)) &&
+        (!selection.route || (train.route === selection.route.name && train.category === selection.route.category))) ?? [];
+}
+/** Build once per immutable selection; clock updates need only two binary searches. */
+export function createActiveTimetableVehicleCounter(trains, options = {}) {
+    const starts = [], ends = [];
+    for (const train of trains) {
+        if (train.realtime?.status === 'cancelled' || (options.requirePositionable && train.stops.length < 2) || !(train.start <= train.end))
+            continue;
+        starts.push(train.start);
+        ends.push(train.end);
+    }
+    starts.sort((a, b) => a - b);
+    ends.sort((a, b) => a - b);
+    const before = (values, time, inclusive) => {
+        let low = 0, high = values.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (values[middle] < time || inclusive && values[middle] === time)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return low;
+    };
+    // Include both departure and arrival instants, including zero-length trips.
+    return time => Number.isNaN(time) ? 0 : before(starts, time, true) - before(ends, time, false);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -149,6 +149,16 @@
       "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"
+    },
+    "./domain/vehicle-counts": {
+      "types": "./domain/vehicle-counts.d.ts",
+      "import": "./domain/vehicle-counts.js",
+      "default": "./domain/vehicle-counts.js"
     }
   },
   "files": [