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

package/README.md

@@ -179,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/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.8",
+  "version": "0.1.0-alpha.9",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -154,6 +154,11 @@
       "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": [