@motionstudies/web 0.1.0-alpha.3 → 0.1.0-alpha.30

package/fonts.css

@@ -0,0 +1,105 @@
+/* Generated by scripts/vendor-web-fonts.mjs; do not edit. Inter and DM Mono are licensed under the SIL Open Font License 1.1: see fonts/Inter-OFL.txt and fonts/DM-Mono-OFL.txt. */
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 300;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-ext-300.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 300;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-300.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-ext-400.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-400.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-ext-500.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'DM Mono';
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url('./fonts/dm-mono-latin-500.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-cyrillic-ext-400-600.woff2') format('woff2');
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-cyrillic-400-600.woff2') format('woff2');
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-greek-ext-400-600.woff2') format('woff2');
+  unicode-range: U+1F00-1FFF;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-greek-400-600.woff2') format('woff2');
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-vietnamese-400-600.woff2') format('woff2');
+  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-latin-ext-400-600.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: url('./fonts/inter-latin-400-600.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

package/mount-motion-study.d.ts

@@ -1,3 +1,8 @@
 import { type ReactNode } from 'react';
-import type { MotionStudyEdition } from '@motionstudies/core/edition';
-export declare function mountMotionStudy(edition: MotionStudyEdition, application: ReactNode): void;
+import type { VisualTheme } from '@motionstudies/core/theme';
+/** Mounting needs presentation identity only; data catalogues belong to the application. */
+export interface MotionStudyMountOptions {
+    readonly id: string;
+    readonly theme: VisualTheme;
+}
+export declare function mountMotionStudy(edition: MotionStudyMountOptions, application: ReactNode): void;

package/mount-motion-study.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { ButtonTooltips } from './components/ButtonTooltips.js';
+import { LazyButtonTooltips } from './components/LazyButtonTooltips.js';
 import { applyVisualTheme } from './visual-theme.js';
 export function mountMotionStudy(edition, application) {
     const root = document.getElementById('root');
@@ -10,5 +10,5 @@ export function mountMotionStudy(edition, application) {
     document.documentElement.classList.add('motion-study');
     document.documentElement.dataset.edition = edition.id;
     applyVisualTheme(edition.theme);
-    createRoot(root).render(_jsxs(StrictMode, { children: [application, _jsx(ButtonTooltips, {})] }));
+    createRoot(root).render(_jsxs(StrictMode, { children: [application, _jsx(LazyButtonTooltips, {})] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.30",
   "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,69 @@
       "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",
+    "./components/StudyTimeline": {
+      "types": "./components/StudyTimeline.d.ts",
+      "import": "./components/StudyTimeline.js",
+      "default": "./components/StudyTimeline.js"
+    },
+    "./study-timeline.css": "./components/study-timeline.css",
+    "./components/TimelineScrubber": {
+      "types": "./components/TimelineScrubber.d.ts",
+      "import": "./components/TimelineScrubber.js",
+      "default": "./components/TimelineScrubber.js"
+    },
+    "./timeline-scrubber.css": "./components/timeline-scrubber.css"
   },
   "files": [
     "**/*.js",
@@ -85,6 +174,8 @@
     "**/*.d.ts",
     "**/*.d.mts",
     "**/*.css",
+    "**/*.woff2",
+    "**/*-OFL.txt",
     "README.md",
     "LICENSE"
   ],
@@ -92,7 +183,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.3"
+    "@motionstudies/core": "0.1.0-alpha.30"
   },
   "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;
+};