@motionstudies/web 0.1.0-alpha.12 → 0.1.0-alpha.13

package/README.md

@@ -25,6 +25,14 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Timetable patterns, station calls and observation windows
+
+`@motionstudies/core/domain/network-patterns` provides a transport-neutral repeated-schedule codec. `@motionstudies/web/use-pattern-network-day` lazily decodes current/adjacent chunks after verifying byte length and SHA-256; it exposes retry and drops old-source state when the manifest URL changes. Supply stable options and a stable asset resolver. Format/category options support existing edition wire contracts.
+
+`@motionstudies/core/domain/station-calls` supplies station calls, independent source status, namespaced source combination and upcoming-call filtering. Source IDs, repeated visits and acquired windows survive combination. Consumers supply interchange IDs and passenger restrictions; matching display names do not collapse services.
+
+`@motionstudies/data/observation-windows` compiles bounded acquired records into hashed windows with explicit time semantics, conflict policy and acquisition-gap reporting. It preserves supplied record IDs, values and source references. It uses elapsed UTC seconds, including 23/25-hour study days, and performs no acquisition or inference. See [contracts, limits and parity evidence](../docs/ALLCHANGE-FOUNDATIONS.md).
+
 ## Now and browser location
 
 `useNowClock` from `@motionstudies/web/use-now-clock` follows the wall clock on each animation frame, so returning from a suspended tab catches up immediately. Call `start()` from a Now button, set the consumer's playback rate to 1, and render its `time` while `active`. With `NationalNetworkScene`, pass `isPlaying={false}` while this external clock owns time. Call `stop()` before pausing, seeking or changing speed, and retain the last clock time for ordinary playback. Clear moving vehicle selections on entry to keep the camera still; panning and zooming remain available.
@@ -217,3 +225,7 @@ The renderer now shares active GPU upload ranges, paused frame reuse, label and
 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.
+
+### Railway preparation
+
+`@motionstudies/data/rail-wtt`, `rail-journeys`, `rail-public-calls`, `rail-routing` and `rail-geometry` expose typed offline railway preparation. XLSX reading, dated source-column audits, UID/date joins, public-call anchors and connected OSM paths preserve source evidence. Editions supply regional identities, calendar exceptions and clipping policy. Node 24+ and `unzip` are required; no Python runtime is shipped. See `docs/SHARED-RAIL-READERS.md` in the source repository for calendar limits and parity evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -87,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",
@@ -162,7 +167,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.12"
+    "@motionstudies/core": "0.1.0-alpha.13"
   },
   "peerDependencies": {
     "react": "^19.2.8",

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