@motionstudies/core 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -164,6 +164,28 @@ Rail and other transport consumers can share the same time filtering through `mo
 
 `@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.
+
 ## 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.
@@ -193,3 +215,5 @@ The renderer now shares active GPU upload ranges, paused frame reuse, label and
 `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.

package/domain/aggregate-road.d.ts

@@ -0,0 +1,48 @@
+/** Counts are vehicle passages at a detector or a provider-defined link, not vehicle identities. */
+export type AggregateRoadInterval = {
+    readonly kind: 'provider-slot';
+    readonly serviceDate: string;
+    readonly index: number;
+    readonly endingLabel: string;
+} | {
+    readonly kind: 'utc';
+    readonly from: string;
+    readonly to: string;
+};
+export interface AggregateRoadSample {
+    readonly interval: AggregateRoadInterval;
+    readonly vehicleCount: number | null;
+    readonly averageSpeed: {
+        readonly value: number;
+        readonly unit: 'mph' | 'km/h';
+    } | null;
+    readonly sourceRecordIds: readonly string[];
+}
+export interface AggregateRoadSeries {
+    readonly id: string;
+    readonly provider: string;
+    readonly dataset: string;
+    readonly siteId: string;
+    readonly modelVersion?: string;
+    readonly samples: readonly AggregateRoadSample[];
+}
+/** Geometry association is independent of measurements; a candidate is not a verified link. */
+export interface AggregateRoadSection {
+    readonly id: string;
+    readonly seriesId: string;
+    readonly path: readonly (readonly [longitude: number, latitude: number])[];
+    readonly association: {
+        readonly kind: 'illustrative';
+        readonly method: string;
+        readonly maximumDistanceMetres: number;
+    } | {
+        readonly kind: 'provider-link';
+        readonly linkId: string;
+        readonly modelVersion: string;
+    };
+}
+export declare function aggregateRoadValue(sample: AggregateRoadSample | undefined, metric: 'vehicleCount' | 'averageSpeed'): number | null;
+/** Compile once per immutable series. Conflicting or duplicate slots remain unavailable.
+ * No interpolation, nearest-slot fallback or conversion between provider and UTC clocks.
+ */
+export declare function indexAggregateRoadSlots(series: AggregateRoadSeries, serviceDate: string): ReadonlyMap<number, AggregateRoadSample>;

package/domain/aggregate-road.js

@@ -0,0 +1,22 @@
+export function aggregateRoadValue(sample, metric) {
+    const value = metric === 'vehicleCount' ? sample?.vehicleCount : sample?.averageSpeed?.value;
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && (metric !== 'vehicleCount' || Number.isInteger(value)) ? value : null;
+}
+/** Compile once per immutable series. Conflicting or duplicate slots remain unavailable.
+ * No interpolation, nearest-slot fallback or conversion between provider and UTC clocks.
+ */
+export function indexAggregateRoadSlots(series, serviceDate) {
+    const result = new Map(), conflicts = new Set();
+    for (const sample of series.samples) {
+        const interval = sample.interval;
+        if (interval.kind !== 'provider-slot' || interval.serviceDate !== serviceDate || !Number.isSafeInteger(interval.index) || interval.index < 0)
+            continue;
+        if (result.has(interval.index)) {
+            result.delete(interval.index);
+            conflicts.add(interval.index);
+        }
+        else if (!conflicts.has(interval.index))
+            result.set(interval.index, sample);
+    }
+    return result;
+}

package/domain/vehicle-calls.d.ts

@@ -0,0 +1,11 @@
+import type { NetworkSnapshot, NetworkTrain } from './network.ts';
+export interface VehicleCall {
+    readonly id: string;
+    readonly name: string;
+    readonly time: number;
+    readonly platform?: string;
+    readonly atStop: boolean;
+    readonly isDestination: boolean;
+}
+/** Remaining calls from this snapshot's train. Times may already include realtime adjustments. */
+export declare function vehicleCalls(snapshot: NetworkSnapshot, train: NetworkTrain, time: number): readonly VehicleCall[];

package/domain/vehicle-calls.js

@@ -0,0 +1,14 @@
+/** Remaining calls from this snapshot's train. Times may already include realtime adjustments. */
+export function vehicleCalls(snapshot, train, time) {
+    if (!Number.isFinite(time) || train.realtime?.status === 'cancelled')
+        return [];
+    return train.stops.flatMap(([index, arrival, departure], callIndex) => {
+        const stop = snapshot.stops[index];
+        if (!stop || !Number.isFinite(arrival) || !Number.isFinite(departure) || departure < arrival || departure < time)
+            return [];
+        const atStop = arrival <= time && time <= departure;
+        return [{ id: `${train.id}:${callIndex}`, name: stop[2], time: atStop ? departure : arrival,
+                platform: stop[3]?.trim() || undefined, atStop,
+                isDestination: callIndex === train.stops.length - 1 && Boolean(train.headsign.trim()) && stop[2].trim() === train.headsign.trim() }];
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -159,6 +159,16 @@
       "types": "./domain/vehicle-counts.d.ts",
       "import": "./domain/vehicle-counts.js",
       "default": "./domain/vehicle-counts.js"
+    },
+    "./domain/aggregate-road": {
+      "types": "./domain/aggregate-road.d.ts",
+      "import": "./domain/aggregate-road.js",
+      "default": "./domain/aggregate-road.js"
+    },
+    "./domain/vehicle-calls": {
+      "types": "./domain/vehicle-calls.d.ts",
+      "import": "./domain/vehicle-calls.js",
+      "default": "./domain/vehicle-calls.js"
     }
   },
   "files": [