@motionstudies/web 0.1.0-alpha.2 → 0.1.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -20,6 +20,28 @@
     "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",
+      "default": "./components/SplitFlapBoard.js"
+    },
+    "./components/AirportHeroCard": {
+      "types": "./components/AirportHeroCard.d.ts",
+      "import": "./components/AirportHeroCard.js",
+      "default": "./components/AirportHeroCard.js"
+    },
+    "./split-flap-board.css": "./components/split-flap-board.css",
+    "./airport-hero-card.css": "./components/airport-hero-card.css",
     "./components/MobilePicker": {
       "types": "./components/MobilePicker.d.ts",
       "import": "./components/MobilePicker.js",
@@ -65,6 +87,11 @@
       "import": "./use-progressive-network-day.js",
       "default": "./use-progressive-network-day.js"
     },
+    "./use-pattern-network-day": {
+      "types": "./use-pattern-network-day.d.ts",
+      "import": "./use-pattern-network-day.js",
+      "default": "./use-pattern-network-day.js"
+    },
     "./use-progressive-road-study": {
       "types": "./use-progressive-road-study.d.ts",
       "import": "./use-progressive-road-study.js",
@@ -77,7 +104,57 @@
       "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"
+    },
+    "./components/DotMatrixBoard": {
+      "types": "./components/DotMatrixBoard.d.ts",
+      "import": "./components/DotMatrixBoard.js",
+      "default": "./components/DotMatrixBoard.js"
+    },
+    "./dot-matrix-board.css": "./components/dot-matrix-board.css",
+    "./components/BusStopHeroCard": {
+      "types": "./components/BusStopHeroCard.d.ts",
+      "import": "./components/BusStopHeroCard.js",
+      "default": "./components/BusStopHeroCard.js"
+    },
+    "./components/VehicleHeroCard": {
+      "types": "./components/VehicleHeroCard.d.ts",
+      "import": "./components/VehicleHeroCard.js",
+      "default": "./components/VehicleHeroCard.js"
+    },
+    "./vehicle-hero-card.css": "./components/vehicle-hero-card.css",
+    "./components/RailStationHeroCard": {
+      "types": "./components/RailStationHeroCard.d.ts",
+      "import": "./components/RailStationHeroCard.js",
+      "default": "./components/RailStationHeroCard.js"
+    },
+    "./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"
+    },
+    "./components/NetworkVehicleHeroCard": {
+      "types": "./components/NetworkVehicleHeroCard.d.ts",
+      "import": "./components/NetworkVehicleHeroCard.js",
+      "default": "./components/NetworkVehicleHeroCard.js"
+    },
+    "./study-layout.css": "./study-layout.css",
+    "./fonts.css": "./fonts.css"
   },
   "files": [
     "**/*.js",
@@ -85,6 +162,8 @@
     "**/*.d.ts",
     "**/*.d.mts",
     "**/*.css",
+    "**/*.woff2",
+    "**/*-OFL.txt",
     "README.md",
     "LICENSE"
   ],
@@ -92,7 +171,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.2"
+    "@motionstudies/core": "0.1.0-alpha.21"
   },
   "peerDependencies": {
     "react": "^19.2.8",

package/study-layout.css

@@ -0,0 +1,65 @@
+/* Opt-in overlay layout. Clearances describe the edition's surrounding controls. */
+.ms-study-layout {
+  --ms-layout-gap: 12px;
+  --ms-layout-gutter: clamp(16px, 3vw, 48px);
+  --ms-layout-top: 180px;
+  --ms-layout-bottom: 160px;
+  --ms-layout-end: 72px;
+  --ms-layer-panel: 6;
+  --ms-control-size: 36px;
+  --ms-control-radius: 2px;
+  --ms-control-border: var(--line, #c1ccff33);
+  --ms-control-surface: var(--panel, #070716ee);
+  --ms-control-ink: var(--ink, #f8f7ff);
+  --ms-control-accent: var(--cyan, #8dfaff);
+}
+
+.ms-study-layout .ms-study-panel {
+  --ms-panel-top: max(var(--ms-layout-top, 180px), env(safe-area-inset-top));
+  --ms-panel-bottom: max(var(--ms-layout-bottom, 160px), env(safe-area-inset-bottom));
+  --ms-panel-start: max(var(--ms-layout-gutter, 16px), env(safe-area-inset-left));
+  --ms-panel-end: max(var(--ms-layout-end, 72px), env(safe-area-inset-right));
+  position: absolute;
+  z-index: var(--ms-layer-panel, 6);
+  inset-block-start: var(--ms-panel-top);
+  inset-inline-start: var(--ms-panel-start);
+  box-sizing: border-box;
+  inline-size: min(var(--ms-panel-width, 560px), max(0px, calc(100% - var(--ms-panel-start) - var(--ms-panel-end))));
+  max-block-size: max(0px, calc(100% - var(--ms-panel-top) - var(--ms-panel-bottom)));
+  min-inline-size: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  scroll-padding-block: var(--ms-layout-gap, 12px);
+}
+
+[data-ms-chrome='hidden'] .ms-study-panel {
+  visibility: hidden;
+  pointer-events: none;
+}
+
+.ms-control {
+  box-sizing: border-box;
+  min-inline-size: var(--ms-control-size, 36px);
+  min-block-size: var(--ms-control-size, 36px);
+  padding: 6px 10px;
+  border: 1px solid var(--ms-control-border, #c1ccff33);
+  border-radius: var(--ms-control-radius, 2px);
+  background: var(--ms-control-surface, #070716ee);
+  color: var(--ms-control-ink, #f8f7ff);
+  font: inherit;
+  cursor: pointer;
+  touch-action: manipulation;
+}
+.ms-control:focus-visible {
+  outline: 2px solid var(--ms-control-accent, #8dfaff);
+  outline-offset: 2px;
+}
+.ms-control[aria-pressed='true'] { border-color: var(--ms-control-accent, #8dfaff); }
+.ms-control:disabled { opacity: .5; cursor: default; }
+.ms-control-group { display: flex; flex-wrap: wrap; align-items: stretch; gap: 6px; }
+.ms-control-strip { display: flex; max-inline-size: 100%; overflow-x: auto; overscroll-behavior-inline: contain; scroll-padding-inline: 4px; }
+.ms-control-strip > * { flex-shrink: 0; }
+.ms-panel-dismiss { position: sticky; inset-block-start: 0; float: inline-end; z-index: 2; margin: 0 0 8px 8px; }
+@media (pointer: coarse) {
+  .ms-study-layout { --ms-control-size: 44px; }
+}

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-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-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 };
+}

package/use-pattern-network-day.d.ts

@@ -0,0 +1,17 @@
+import type { PatternChunkOptions } from '@motionstudies/core/domain/network-patterns';
+import type { NetworkDayChunk, NetworkDayChunkDescriptor, NetworkDayManifest } from '@motionstudies/core/domain/network';
+import type { DataUrlResolver } from './data-url.ts';
+export interface PatternNetworkManifest extends NetworkDayManifest {
+    readonly format: string;
+}
+export declare function verifiedPatternNetworkChunk(response: Response, descriptor: NetworkDayChunkDescriptor, options?: PatternChunkOptions): Promise<NetworkDayChunk>;
+/** Fetch and decode only the current and adjacent chunks; keep the manifest independent. */
+export declare function usePatternNetworkDay(manifestFile: string, active: boolean, time: number, resolveAssetUrl: DataUrlResolver, options?: PatternChunkOptions): {
+    manifest: PatternNetworkManifest | undefined;
+    chunkReady: boolean;
+    loading: boolean;
+    unavailable: boolean;
+    error: boolean;
+    retry: () => void;
+    network: import("@motionstudies/core/domain/network").NetworkSnapshot | undefined;
+};

package/use-pattern-network-day.js

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+import { adjacentDayChunks, dayChunkForTime, networkSnapshotForDayChunk } from '@motionstudies/core/domain/network-day';
+import { useProgressiveChunks } from './use-progressive-chunks.js';
+export async function verifiedPatternNetworkChunk(response, descriptor, options = {}) {
+    const bytes = await response.arrayBuffer();
+    if (!Number.isSafeInteger(descriptor.bytes) || bytes.byteLength !== descriptor.bytes || !/^[a-f0-9]{64}$/.test(descriptor.sha256 ?? ''))
+        throw new Error('Pattern chunk integrity metadata missing or size mismatch');
+    const hash = [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(byte => byte.toString(16).padStart(2, '0')).join('');
+    if (hash !== descriptor.sha256)
+        throw new Error('Pattern chunk integrity mismatch');
+    const { decodeNetworkPatterns } = await import('@motionstudies/core/domain/network-patterns');
+    const chunk = decodeNetworkPatterns(JSON.parse(new TextDecoder().decode(bytes)), options);
+    if (chunk.windowStart !== descriptor.windowStart || chunk.windowEnd !== descriptor.windowEnd || chunk.trains.length !== descriptor.tripCount)
+        throw new Error('Pattern chunk descriptor mismatch');
+    return chunk;
+}
+/** Fetch and decode only the current and adjacent chunks; keep the manifest independent. */
+export function usePatternNetworkDay(manifestFile, active, time, resolveAssetUrl, options = {}) {
+    const format = options.format ?? 'network-patterns-v1', categories = options.categories;
+    const adapter = useMemo(() => ({
+        chunkForTime: dayChunkForTime, adjacentChunks: adjacentDayChunks, retainAdjacentOnly: true,
+        validateManifest(manifest) {
+            if (manifest.format !== format || !manifest.metadata || !Array.isArray(manifest.stops) || !Array.isArray(manifest.edges))
+                throw new Error('Invalid pattern manifest');
+            const ids = new Set();
+            let previous = -Infinity;
+            for (const chunk of manifest.chunks) {
+                if (!chunk.id || ids.has(chunk.id) || !chunk.path || !Number.isFinite(chunk.windowStart) || !Number.isFinite(chunk.windowEnd) ||
+                    chunk.windowStart < previous || chunk.windowEnd <= chunk.windowStart || !Number.isSafeInteger(chunk.tripCount) || chunk.tripCount < 0 ||
+                    !Number.isSafeInteger(chunk.bytes) || chunk.bytes < 1 || !/^[a-f0-9]{64}$/.test(chunk.sha256 ?? ''))
+                    throw new Error('Invalid pattern descriptor');
+                ids.add(chunk.id);
+                previous = chunk.windowEnd;
+            }
+        },
+        readChunk: (response, descriptor) => verifiedPatternNetworkChunk(response, descriptor, { format, categories }),
+    }), [format, categories]);
+    const { chunk, ...state } = useProgressiveChunks(manifestFile, active, time, resolveAssetUrl, adapter);
+    const network = useMemo(() => state.manifest ? networkSnapshotForDayChunk(state.manifest, chunk) : undefined, [state.manifest, chunk]);
+    return { ...state, network };
+}

package/use-progressive-air-day.d.ts

@@ -6,5 +6,6 @@ export declare function useProgressiveAirDay(manifestFile: string, active: boole
     loading: boolean;
     unavailable: boolean;
     error: boolean;
+    retry: () => void;
     snapshot: import("@motionstudies/core/domain/air").AirSnapshot | undefined;
 };

package/use-progressive-chunks.d.ts

@@ -11,6 +11,8 @@ export interface ProgressiveChunkAdapter<Manifest, Descriptor, Chunk> {
     readonly adjacentChunks: (manifest: Manifest, current: Descriptor) => readonly Descriptor[];
     readonly readChunk: (response: Response, descriptor: Descriptor) => Promise<Chunk>;
     readonly optional?: boolean;
+    readonly validateManifest?: (manifest: Manifest) => void;
+    readonly retainAdjacentOnly?: boolean;
 }
 /** Internal lifecycle shared by the network, aircraft and road loaders. */
 export declare function useProgressiveChunks<Descriptor extends ChunkDescriptor, Manifest extends ChunkManifest<Descriptor>, Chunk>(manifestFile: string, active: boolean, time: number, resolveAssetUrl: DataUrlResolver, adapter: ProgressiveChunkAdapter<Manifest, Descriptor, Chunk>): {
@@ -20,5 +22,6 @@ export declare function useProgressiveChunks<Descriptor extends ChunkDescriptor,
     loading: boolean;
     unavailable: boolean;
     error: boolean;
+    retry: () => void;
 };
 export {};

package/use-progressive-chunks.js

@@ -1,8 +1,13 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 /** Internal lifecycle shared by the network, aircraft and road loaders. */
 export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl, adapter) {
     const key = resolveAssetUrl(manifestFile);
     const [stored, setStored] = useState({ key, chunks: {} });
+    const [attempt, setAttempt] = useState(0);
+    const retry = useCallback(() => {
+        setStored(current => current.key === key ? { ...current, manifestError: false, failedChunk: undefined, unavailable: false } : current);
+        setAttempt(value => value + 1);
+    }, [key]);
     // Reset during render so no effect (or consumer) sees another source's data.
     // Late responses are also rejected below, independently of fetch cancellation.
     const state = stored.key === key ? stored : { key, chunks: {} };
@@ -32,6 +37,7 @@ export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl
                 if (!Array.isArray(next.chunks) || !next.chunks.length) {
                     throw new Error('Day manifest has no chunks');
                 }
+                adapter.validateManifest?.(next);
                 if (!controller.signal.aborted) {
                     setStored((current) => current.key === key
                         ? { ...current, manifest: next, manifestError: false }
@@ -45,7 +51,7 @@ export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl
             }
         })();
         return () => controller.abort();
-    }, [active, adapter, key, manifest, unavailable]);
+    }, [active, adapter, attempt, key, manifest, unavailable]);
     useEffect(() => {
         if (!active || !manifest || !descriptor)
             return;
@@ -66,7 +72,9 @@ export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl
                     const next = await adapter.readChunk(response, candidate);
                     if (!controller.signal.aborted) {
                         setStored((current) => current.key === key
-                            ? { ...current, chunks: { ...current.chunks, [candidate.id]: next },
+                            ? { ...current, chunks: { ...(adapter.retainAdjacentOnly
+                                        ? Object.fromEntries(Object.entries(current.chunks).filter(([id]) => adapter.adjacentChunks(manifest, descriptor).some(item => item.id === id)))
+                                        : current.chunks), [candidate.id]: next },
                                 failedChunk: current.failedChunk === candidate.id ? undefined : current.failedChunk }
                             : current);
                     }
@@ -79,7 +87,7 @@ export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl
             })();
         }
         return () => controller.abort();
-    }, [active, adapter, chunks, descriptor, key, manifest, resolveAssetUrl]);
+    }, [active, adapter, attempt, chunks, descriptor, key, manifest, resolveAssetUrl]);
     return {
         manifest,
         chunk,
@@ -87,5 +95,6 @@ export function useProgressiveChunks(manifestFile, active, time, resolveAssetUrl
         loading: active && !unavailable && !error && (!manifest || !chunkReady),
         unavailable: Boolean(unavailable),
         error,
+        retry,
     };
 }

package/use-progressive-network-day.d.ts

@@ -7,5 +7,6 @@ export declare function useProgressiveNetworkDay(manifestFile: string, active: b
     loading: boolean;
     unavailable: boolean;
     error: boolean;
+    retry: () => void;
     network: import("@motionstudies/core/domain/network").NetworkSnapshot | undefined;
 };

package/use-progressive-road-study.d.ts

@@ -6,5 +6,6 @@ export declare function useProgressiveRoadStudy(manifestFile: string, active: bo
     loading: boolean;
     unavailable: boolean;
     error: boolean;
+    retry: () => void;
     snapshot: import("@motionstudies/core/domain/road-day").NationalRoadStudySnapshot | undefined;
 };

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;
+};