@motionstudies/web 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -126,7 +126,17 @@
       "import": "./components/RailStationHeroCard.js",
       "default": "./components/RailStationHeroCard.js"
     },
-    "./transport-hero-cards.css": "./components/transport-hero-cards.css"
+    "./transport-hero-cards.css": "./components/transport-hero-cards.css",
+    "./use-json-asset": {
+      "types": "./use-json-asset.d.ts",
+      "import": "./use-json-asset.js",
+      "default": "./use-json-asset.js"
+    },
+    "./use-transition-value": {
+      "types": "./use-transition-value.d.ts",
+      "import": "./use-transition-value.js",
+      "default": "./use-transition-value.js"
+    }
   },
   "files": [
     "**/*.js",
@@ -141,7 +151,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.8"
+    "@motionstudies/core": "0.1.0-alpha.9"
   },
   "peerDependencies": {
     "react": "^19.2.8",

package/use-json-asset.d.ts

@@ -0,0 +1,9 @@
+/** A single optional asset, cached until its URL/parser changes or retry is called.
+ * Keep parse stable. Source compatibility and schema checks belong in that parser. */
+export declare function useJsonAsset<T>(url: string | undefined, enabled?: boolean, parse?: (value: unknown) => T, optional?: boolean): {
+    data: T | undefined;
+    error: boolean;
+    unavailable: boolean;
+    loading: boolean;
+    retry: () => void;
+};

package/use-json-asset.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useState } from 'react';
+const identity = (value) => value;
+/** A single optional asset, cached until its URL/parser changes or retry is called.
+ * Keep parse stable. Source compatibility and schema checks belong in that parser. */
+export function useJsonAsset(url, enabled = true, parse = identity, optional = false) {
+    const [attempt, setAttempt] = useState(0);
+    const [stored, setStored] = useState({ url, parse, attempt });
+    const state = stored.url === url && stored.parse === parse && stored.attempt === attempt
+        ? stored : { url, parse, attempt };
+    if (stored !== state)
+        setStored(state);
+    const { data, error, unavailable } = state;
+    useEffect(() => {
+        if (!enabled || !url || data !== undefined || unavailable)
+            return;
+        const controller = new AbortController();
+        const save = (result) => {
+            if (!controller.signal.aborted)
+                setStored(current => current.url === url && current.parse === parse && current.attempt === attempt
+                    ? { ...current, ...result } : current);
+        };
+        void (async () => {
+            try {
+                const response = await fetch(url, { signal: controller.signal });
+                if (optional && response.status === 404) {
+                    save({ unavailable: true, error: false });
+                    return;
+                }
+                if (!response.ok)
+                    throw new Error(`Asset returned ${response.status}`);
+                const next = parse(await response.json());
+                if (next === undefined)
+                    throw new Error('Asset parser returned no data');
+                save({ data: next, error: false });
+            }
+            catch {
+                save({ error: true });
+            }
+        })();
+        return () => controller.abort();
+    }, [url, enabled, parse, optional, attempt, data, unavailable]);
+    const retry = useCallback(() => setAttempt(value => value + 1), []);
+    return { data, error: Boolean(error), unavailable: Boolean(unavailable),
+        loading: Boolean(enabled && url && data === undefined && !error && !unavailable), retry };
+}

package/use-transition-value.d.ts

@@ -0,0 +1,12 @@
+export declare const smoothTransition: (progress: number) => number;
+export declare const cosineTransition: (progress: number) => number;
+/** Animate a scalar from its current value; interruptions reverse from the last frame.
+ * Reduced-motion changes settle immediately, including during an active transition. */
+export declare function useTransitionValue(target: number, { durationMs, easing, steps, }?: {
+    readonly durationMs?: number;
+    readonly easing?: (progress: number) => number;
+    readonly steps?: number;
+}): {
+    value: number;
+    transitioning: boolean;
+};

package/use-transition-value.js

@@ -0,0 +1,46 @@
+import { useEffect, useRef, useState } from 'react';
+export const smoothTransition = (progress) => progress * progress * (3 - 2 * progress);
+export const cosineTransition = (progress) => 0.5 - Math.cos(progress * Math.PI) / 2;
+/** Animate a scalar from its current value; interruptions reverse from the last frame.
+ * Reduced-motion changes settle immediately, including during an active transition. */
+export function useTransitionValue(target, { durationMs = 1600, easing = smoothTransition, steps, } = {}) {
+    const current = useRef(target);
+    const [value, setValue] = useState(target);
+    const [transitioning, setTransitioning] = useState(false);
+    useEffect(() => {
+        const from = current.current;
+        const motion = matchMedia('(prefers-reduced-motion: reduce)');
+        let frame = 0;
+        const finish = () => {
+            cancelAnimationFrame(frame);
+            current.current = target;
+            setValue(target);
+            setTransitioning(false);
+        };
+        if (!Number.isFinite(target) || !Number.isFinite(from))
+            return;
+        if (motion.matches || from === target || !(durationMs > 0) || !Number.isFinite(durationMs)) {
+            finish();
+            return;
+        }
+        const started = performance.now();
+        setTransitioning(true);
+        const tick = (now) => {
+            const progress = Math.min(1, (now - started) / durationMs);
+            const eased = easing(progress);
+            const fraction = steps && Number.isFinite(steps) && steps > 0 ? Math.round(eased * steps) / steps : eased;
+            current.current = from + (target - from) * fraction;
+            setValue(current.current);
+            if (progress < 1)
+                frame = requestAnimationFrame(tick);
+            else
+                finish();
+        };
+        frame = requestAnimationFrame(tick);
+        const changed = () => { if (motion.matches)
+            finish(); };
+        motion.addEventListener('change', changed);
+        return () => { cancelAnimationFrame(frame); motion.removeEventListener('change', changed); };
+    }, [target, durationMs, easing, steps]);
+    return { value, transitioning };
+}