@motionstudies/core 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motion Studies contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# Motion Studies packages
+
+Shared packages for the Motion Studies transport instrument. The source workspace and compiled distributions expose the same explicit, extensionless module subpaths. The initial release is `0.1.0-alpha.0` under npm’s `next` tag.
+
+- `@motionstudies/core`: transport contracts, indexing, interpolation and visual theme contracts; no browser or Node dependencies.
+- `@motionstudies/three`: `NationalNetworkScene`, `HubPulseScene`, `StationFlowScene`, camera framing and label-mode contracts. React, React Three Fiber and Three.js are peers; rendering internals are not public subpaths.
+- `@motionstudies/web`: picker, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Fonts and edition layouts belong to consumers.
+- `@motionstudies/data`: Node-only GTFS readers, network chunking, merging and station ranking. ZIP reading requires `unzip` on the host. Source selection, provenance overrides and compilation commands belong to each edition.
+
+```tsx
+import { MobilePicker } from '@motionstudies/web/components/MobilePicker'
+import { createDataUrlResolver } from '@motionstudies/web/data-url'
+import { useProgressiveNetworkDay } from '@motionstudies/web/use-progressive-network-day'
+import '@motionstudies/web/tokens.css'
+import '@motionstudies/web/mobile-picker.css'
+
+const resolveData = createDataUrlResolver('/my-edition/data/')
+// Inside a React component:
+// const day = useProgressiveNetworkDay('day.json', enabled, time, resolveData)
+```
+
+Keep the resolver stable across renders. Manifest paths and their chunk paths are relative to the supplied asset root. Changing the resolved manifest URL resets the loader; disabling cancels requests, and re-enabling retries failures. Optional road manifests distinguish a 404 from an error. Observations poll serially; changing their endpoint drops the previous source's state, and disabling/unmounting cancels the request and timer.
+
+Build release candidates with `npm run build:packages`. Distribution manifests and compiled ESM/declarations are written to `.package-dist/`; workspace manifests continue to point at source for fast local iteration. `npm run check:packed` packs and installs those distributions into a separate consumer, builds the lab and validates the public exports. No source aliases or workspace links are used in that consumer.
+
+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`.

package/air-search.d.ts

@@ -0,0 +1,11 @@
+export interface AirSearchTrack {
+    readonly id: string;
+    readonly icaoAddress?: string;
+    readonly callsign: string;
+    readonly start: number;
+    readonly end: number;
+    readonly airportIds?: readonly string[];
+}
+export declare function airTrackSearchText(track: AirSearchTrack): string;
+export declare function airTrackSearchValue(track: AirSearchTrack): string;
+export declare function searchAirTracks<Track extends AirSearchTrack>(tracks: readonly Track[], searchQuery: string, time: number, limit?: number): readonly Track[];

package/air-search.js

@@ -0,0 +1,32 @@
+import { foldSearchText } from './search-text.js';
+export function airTrackSearchText(track) {
+    return foldSearchText(`${track.callsign} ${track.icaoAddress ?? track.id}`);
+}
+export function airTrackSearchValue(track) {
+    return `${track.callsign} · ${(track.icaoAddress ?? track.id).toUpperCase()}`;
+}
+function airTrackMatchRank(track, query) {
+    const callsign = foldSearchText(track.callsign);
+    const id = foldSearchText(track.icaoAddress ?? track.id);
+    if (callsign === query || id === query)
+        return 0;
+    if (callsign.startsWith(query) || id.startsWith(query))
+        return 1;
+    return 2;
+}
+export function searchAirTracks(tracks, searchQuery, time, limit = 8) {
+    const query = foldSearchText(searchQuery);
+    if (!query)
+        return [];
+    return tracks
+        .filter((track) => airTrackSearchText(track).includes(query))
+        .sort((first, second) => {
+        const firstActive = first.start <= time && first.end >= time;
+        const secondActive = second.start <= time && second.end >= time;
+        return (airTrackMatchRank(first, query) - airTrackMatchRank(second, query) ||
+            Number(secondActive) - Number(firstActive) ||
+            first.start - second.start ||
+            first.callsign.localeCompare(second.callsign, 'en', { numeric: true }));
+    })
+        .slice(0, limit);
+}

package/domain/air-day.d.ts

@@ -0,0 +1,34 @@
+import type { AirSnapshot, AirTrack } from './air.ts';
+export interface AirDayAircraft {
+    readonly id: string;
+    readonly icaoAddress: string;
+    readonly callsign: string;
+    readonly start: number;
+    readonly end: number;
+    readonly airportIds?: readonly string[];
+    readonly chunkIds: readonly string[];
+}
+export interface AirDayChunkDescriptor {
+    readonly id: string;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly path: string;
+    readonly trackCount: number;
+    readonly sampleCount: number;
+}
+export interface AirDayChunk {
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly tracks: readonly AirTrack[];
+}
+export interface AirDayManifest {
+    readonly metadata: AirSnapshot['metadata'];
+    readonly bounds: AirSnapshot['bounds'];
+    readonly trackCount: number;
+    readonly sampleCount: number;
+    readonly aircraft: readonly AirDayAircraft[];
+    readonly chunks: readonly AirDayChunkDescriptor[];
+}
+export declare function airDayChunkForTime(manifest: AirDayManifest, time: number): AirDayChunkDescriptor;
+export declare function adjacentAirDayChunks(manifest: AirDayManifest, current: AirDayChunkDescriptor): readonly AirDayChunkDescriptor[];
+export declare function airSnapshotForDayChunk(manifest: AirDayManifest, chunk?: AirDayChunk): AirSnapshot;

package/domain/air-day.js

@@ -0,0 +1,17 @@
+export function airDayChunkForTime(manifest, time) {
+    const last = manifest.chunks.at(-1);
+    const match = manifest.chunks.find((chunk) => time >= chunk.windowStart &&
+        (time < chunk.windowEnd || (chunk === last && time <= chunk.windowEnd)));
+    return match ?? (time < manifest.metadata.windowStart ? manifest.chunks[0] : last);
+}
+export function adjacentAirDayChunks(manifest, current) {
+    const index = manifest.chunks.findIndex((chunk) => chunk.id === current.id);
+    return manifest.chunks.slice(Math.max(0, index - 1), index + 2);
+}
+export function airSnapshotForDayChunk(manifest, chunk) {
+    return {
+        metadata: manifest.metadata,
+        bounds: manifest.bounds,
+        tracks: chunk?.tracks ?? [],
+    };
+}

package/domain/air.d.ts

@@ -0,0 +1,48 @@
+export type AirSample = readonly [
+    time: number,
+    longitude: number,
+    latitude: number,
+    altitudeFeet: number,
+    groundSpeedKnots: number
+];
+export interface AirTrack {
+    readonly id: string;
+    readonly icaoAddress?: string;
+    readonly callsign: string;
+    readonly start: number;
+    readonly end: number;
+    readonly airportIds?: readonly string[];
+    readonly samples: readonly AirSample[];
+}
+export interface AirSnapshot {
+    readonly metadata: {
+        readonly publisher: string;
+        readonly serviceDate: string;
+        readonly windowStart: number;
+        readonly windowEnd: number;
+        readonly sourceUrl: string;
+        readonly license: string;
+        readonly licenseUrl: string;
+        readonly model: string;
+        readonly note: string;
+        readonly sampleIntervalSeconds: number;
+    };
+    readonly bounds: {
+        readonly minLongitude: number;
+        readonly minLatitude: number;
+        readonly maxLongitude: number;
+        readonly maxLatitude: number;
+    };
+    readonly tracks: readonly AirTrack[];
+}
+export interface AirPosition {
+    readonly longitude: number;
+    readonly latitude: number;
+    readonly altitudeFeet: number;
+    readonly groundSpeedKnots: number;
+    readonly headingDegrees: number;
+    readonly verticalRateFeetPerMinute: number;
+}
+export declare function headingBetweenSamples(from: AirSample, to: AirSample): number;
+export declare function positionForAirTrack(track: AirTrack, time: number): AirPosition | undefined;
+export declare function activeAirTracks(snapshot: AirSnapshot, time: number): readonly AirTrack[];

package/domain/air.js

@@ -0,0 +1,83 @@
+const MAX_INTERPOLATION_GAP_SECONDS = 45;
+function sampleBracket(samples, time) {
+    let low = 1;
+    let high = samples.length - 1;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (samples[middle][0] < time)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return [low - 1, low];
+}
+function sampleTangent(samples, index, coordinate, fallback) {
+    const previous = samples[index - 1];
+    const next = samples[index + 1];
+    const current = samples[index];
+    if (previous &&
+        next &&
+        current[0] - previous[0] <= MAX_INTERPOLATION_GAP_SECONDS &&
+        next[0] - current[0] <= MAX_INTERPOLATION_GAP_SECONDS) {
+        return (next[coordinate] - previous[coordinate]) / (next[0] - previous[0]);
+    }
+    return fallback;
+}
+function hermiteValue(from, to, fromTangent, toTangent, duration, progress) {
+    const progressSquared = progress * progress;
+    const progressCubed = progressSquared * progress;
+    return ((2 * progressCubed - 3 * progressSquared + 1) * from +
+        (progressCubed - 2 * progressSquared + progress) * fromTangent * duration +
+        (-2 * progressCubed + 3 * progressSquared) * to +
+        (progressCubed - progressSquared) * toTangent * duration);
+}
+function hermiteDerivative(from, to, fromTangent, toTangent, duration, progress) {
+    const progressSquared = progress * progress;
+    return ((6 * progressSquared - 6 * progress) * from +
+        (3 * progressSquared - 4 * progress + 1) * fromTangent * duration +
+        (-6 * progressSquared + 6 * progress) * to +
+        (3 * progressSquared - 2 * progress) * toTangent * duration);
+}
+export function headingBetweenSamples(from, to) {
+    const latitude = ((from[2] + to[2]) * Math.PI) / 360;
+    const east = (to[1] - from[1]) * Math.cos(latitude);
+    const north = to[2] - from[2];
+    return ((Math.atan2(east, north) * 180) / Math.PI + 360) % 360;
+}
+export function positionForAirTrack(track, time) {
+    if (time < track.start || time > track.end || track.samples.length < 2) {
+        return undefined;
+    }
+    const [lower, upper] = sampleBracket(track.samples, time);
+    const from = track.samples[lower];
+    const to = track.samples[upper];
+    const duration = to[0] - from[0];
+    if (duration <= 0 || duration > MAX_INTERPOLATION_GAP_SECONDS)
+        return undefined;
+    const progress = Math.max(0, Math.min(1, (time - from[0]) / duration));
+    const longitudeRate = (to[1] - from[1]) / duration;
+    const latitudeRate = (to[2] - from[2]) / duration;
+    const fromLongitudeTangent = sampleTangent(track.samples, lower, 1, longitudeRate);
+    const toLongitudeTangent = sampleTangent(track.samples, upper, 1, longitudeRate);
+    const fromLatitudeTangent = sampleTangent(track.samples, lower, 2, latitudeRate);
+    const toLatitudeTangent = sampleTangent(track.samples, upper, 2, latitudeRate);
+    const longitude = hermiteValue(from[1], to[1], fromLongitudeTangent, toLongitudeTangent, duration, progress);
+    const latitude = hermiteValue(from[2], to[2], fromLatitudeTangent, toLatitudeTangent, duration, progress);
+    const longitudeDerivative = hermiteDerivative(from[1], to[1], fromLongitudeTangent, toLongitudeTangent, duration, progress);
+    const latitudeDerivative = hermiteDerivative(from[2], to[2], fromLatitudeTangent, toLatitudeTangent, duration, progress);
+    const east = longitudeDerivative * Math.cos((latitude * Math.PI) / 180);
+    const headingDegrees = Math.abs(east) + Math.abs(latitudeDerivative) > Number.EPSILON
+        ? ((Math.atan2(east, latitudeDerivative) * 180) / Math.PI + 360) % 360
+        : headingBetweenSamples(from, to);
+    return {
+        longitude,
+        latitude,
+        altitudeFeet: from[3] + (to[3] - from[3]) * progress,
+        groundSpeedKnots: from[4] + (to[4] - from[4]) * progress,
+        headingDegrees,
+        verticalRateFeetPerMinute: ((to[3] - from[3]) / duration) * 60,
+    };
+}
+export function activeAirTracks(snapshot, time) {
+    return snapshot.tracks.filter((track) => positionForAirTrack(track, time));
+}

package/domain/airport.d.ts

@@ -0,0 +1,17 @@
+import type { AirTrack } from './air.ts';
+export interface StudyAirport {
+    readonly id: string;
+    readonly name: string;
+    readonly city: string;
+    readonly mapLabel?: string;
+    readonly iata: string;
+    readonly icao: string;
+    readonly longitude: number;
+    readonly latitude: number;
+    readonly approachRadiusKilometres: number;
+    readonly maximumApproachAltitudeFeet: number;
+}
+export declare function airportSearchText(airport: StudyAirport): string;
+export declare function searchAirports(airports: readonly StudyAirport[], searchQuery: string, limit?: number): readonly StudyAirport[];
+export declare function airTrackServesAirport(track: AirTrack, airport: StudyAirport): boolean;
+export declare function airportAirTrackIds(tracks: readonly AirTrack[], airport: StudyAirport): ReadonlySet<string>;

package/domain/airport.js

@@ -0,0 +1,41 @@
+import { foldSearchText } from '../search-text.js';
+export function airportSearchText(airport) {
+    return foldSearchText(`${airport.name} ${airport.city} ${airport.mapLabel ?? ''} ${airport.iata} ${airport.icao}`);
+}
+function airportMatchRank(airport, query) {
+    const codes = [airport.iata, airport.icao].map(foldSearchText);
+    const name = foldSearchText(airport.name);
+    if (codes.includes(query) || name === query)
+        return 0;
+    if (codes.some((code) => code.startsWith(query)) || name.startsWith(query)) {
+        return 1;
+    }
+    return 2;
+}
+export function searchAirports(airports, searchQuery, limit = 5) {
+    const query = foldSearchText(searchQuery);
+    if (!query)
+        return [];
+    return airports
+        .filter((airport) => airportSearchText(airport).includes(query))
+        .sort((first, second) => airportMatchRank(first, query) - airportMatchRank(second, query) ||
+        first.name.localeCompare(second.name, 'en'))
+        .slice(0, limit);
+}
+function coordinateDistanceKilometres(firstLongitude, firstLatitude, secondLongitude, secondLatitude) {
+    const averageLatitude = ((firstLatitude + secondLatitude) * Math.PI) / 360;
+    const east = (secondLongitude - firstLongitude) * 111.32 * Math.cos(averageLatitude);
+    const north = (secondLatitude - firstLatitude) * 111.32;
+    return Math.hypot(east, north);
+}
+export function airTrackServesAirport(track, airport) {
+    if (track.airportIds?.includes(airport.id))
+        return true;
+    return track.samples.some(([, longitude, latitude, altitudeFeet]) => altitudeFeet <= airport.maximumApproachAltitudeFeet &&
+        coordinateDistanceKilometres(longitude, latitude, airport.longitude, airport.latitude) <= airport.approachRadiusKilometres);
+}
+export function airportAirTrackIds(tracks, airport) {
+    return new Set(tracks
+        .filter((track) => airTrackServesAirport(track, airport))
+        .map((track) => track.id));
+}

package/domain/boundary.d.ts

@@ -0,0 +1,14 @@
+export type BoundaryCoordinate = readonly [longitude: number, latitude: number];
+export interface MapBoundary {
+    readonly metadata: {
+        readonly source: string;
+        readonly sourceUrl: string;
+        readonly productUrl: string;
+        readonly edition: string;
+        readonly attribution: string;
+        readonly sourceCrs: string;
+        readonly outputCrs: string;
+        readonly simplificationToleranceMetres: number;
+    };
+    readonly rings: readonly (readonly BoundaryCoordinate[])[];
+}

package/domain/boundary.js

@@ -0,0 +1 @@
+export {};

package/domain/corridor.d.ts

@@ -0,0 +1,64 @@
+export interface CorridorTerrain {
+    readonly columns: number;
+    readonly rows: number;
+    readonly widthMetres: number;
+    readonly depthMetres: number;
+    readonly minElevation: number;
+    readonly maxElevation: number;
+    readonly elevations: readonly number[];
+}
+export interface CorridorRouteStop {
+    readonly name: string;
+    readonly progress: number;
+    readonly departure: number;
+}
+export interface CorridorLake {
+    readonly id: string;
+    readonly name: string;
+    readonly elevation: number;
+    readonly rings: readonly (readonly (readonly [number, number])[])[];
+}
+export interface CorridorTunnel {
+    readonly id: string;
+    readonly name: string;
+    readonly lengthMetres: number;
+    readonly line: string;
+    readonly startProgress: number;
+    readonly endProgress: number;
+}
+export interface CorridorSnapshot {
+    readonly id: string;
+    readonly metadata: {
+        readonly source: string;
+        readonly releaseDate: string;
+        readonly sourceUrl: string;
+        readonly productUrl: string;
+        readonly attribution: string;
+        readonly sourceCrs: string;
+        readonly model: string;
+        readonly railSource: unknown;
+        readonly profileSourceUrl: string;
+        readonly routeSource?: string;
+        readonly routeAttribution?: string;
+        readonly routeProductUrl?: string;
+        readonly tunnelSource?: string;
+        readonly tunnelSourceUrl?: string;
+        readonly tunnelProductUrl?: string;
+    };
+    readonly origin: {
+        readonly easting: number;
+        readonly northing: number;
+    };
+    readonly terrain: CorridorTerrain;
+    readonly route: {
+        readonly service: string;
+        readonly destination: string;
+        readonly operator: string;
+        readonly representativeTrain: string;
+        readonly distanceMetres: number;
+        readonly points: readonly (readonly [number, number, number])[];
+        readonly stops: readonly CorridorRouteStop[];
+        readonly tunnels?: readonly CorridorTunnel[];
+    };
+    readonly lakes: readonly CorridorLake[];
+}

package/domain/corridor.js

@@ -0,0 +1 @@
+export {};

package/domain/hub.d.ts

@@ -0,0 +1,57 @@
+import type { NetworkSnapshot, NetworkStop, ServiceCategory } from './network.ts';
+export interface HubDefinition<HubId extends string = string> {
+    readonly id: HubId;
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly displayName: string;
+    readonly character: string;
+}
+export interface HubCall {
+    readonly id: string;
+    readonly train: {
+        readonly id: string;
+        readonly route: string;
+        readonly headsign: string;
+        readonly shortName: string;
+        readonly category: ServiceCategory;
+    };
+    readonly arrival: number;
+    readonly departure: number;
+    readonly hubStop: NetworkStop;
+    readonly previousStop?: NetworkStop;
+    readonly nextStop?: NetworkStop;
+}
+export type HubFlowOrientation = 'radial' | 'orbital';
+export type HubFlowLens = 'all' | HubFlowOrientation;
+export interface HubFlowSummary {
+    readonly all: number;
+    readonly radial: number;
+    readonly orbital: number;
+}
+export interface HubDaySnapshot<HubId extends string = string> {
+    readonly metadata: NetworkSnapshot['metadata'];
+    readonly hubs: Readonly<Record<HubId, readonly HubCall[]>>;
+}
+export declare const UNASSIGNED_PLATFORM = "\u2014";
+export type StationMotionPhase = 'approaching' | 'dwelling' | 'departing';
+export interface StationMotion {
+    readonly phase: StationMotionPhase;
+    readonly progress: number;
+}
+export declare function platformCodeForCall(call: HubCall): string;
+export declare function platformTrackForCall(call: HubCall): string;
+export declare function platformsForCalls(calls: readonly HubCall[]): readonly string[];
+export declare function stationMotionForCall(call: HubCall, time: number, horizon?: number, cycle?: number): StationMotion | undefined;
+export declare function callsAtHub(snapshot: NetworkSnapshot, hub: HubDefinition): readonly HubCall[];
+export declare function callsNearTime(calls: readonly HubCall[], time: number, horizon?: number, cycle?: number): readonly HubCall[];
+export declare function nextHubCall(calls: readonly HubCall[], time: number): HubCall | undefined;
+/**
+ * Classify a movement by comparing its local path through a hub with the line
+ * from a study centre to that hub. The absolute dot product makes the result
+ * independent of service direction: inbound and outbound calls share a lens.
+ */
+export declare function hubFlowOrientation(call: HubCall, centre: readonly [longitude: number, latitude: number], radialThreshold?: number): HubFlowOrientation;
+export declare function callsForHubFlowLens(calls: readonly HubCall[], lens: HubFlowLens, centre: readonly [longitude: number, latitude: number]): readonly HubCall[];
+export declare function hubFlowSummary(calls: readonly HubCall[], centre: readonly [longitude: number, latitude: number]): HubFlowSummary;
+/** A soft day/night envelope with transitions around 22:00 and 06:30. */
+export declare function hubNightSignalMix(time: number): number;

package/domain/hub.js

@@ -0,0 +1,137 @@
+export const UNASSIGNED_PLATFORM = '—';
+export function platformCodeForCall(call) {
+    return call.hubStop[3]?.trim() || UNASSIGNED_PLATFORM;
+}
+export function platformTrackForCall(call) {
+    const code = platformCodeForCall(call);
+    if (code === UNASSIGNED_PLATFORM || code.includes('/'))
+        return code;
+    return /^\d+/.exec(code)?.[0] ?? code;
+}
+export function platformsForCalls(calls) {
+    return [...new Set(calls.map(platformTrackForCall))].sort((first, second) => {
+        if (first === UNASSIGNED_PLATFORM)
+            return 1;
+        if (second === UNASSIGNED_PLATFORM)
+            return -1;
+        return first.localeCompare(second, 'de-CH', {
+            numeric: true,
+            sensitivity: 'base',
+        });
+    });
+}
+export function stationMotionForCall(call, time, horizon = 6 * 60, cycle = 24 * 3600) {
+    const midpoint = (call.arrival + call.departure) / 2;
+    const cycleOffset = Math.round((time - midpoint) / cycle) * cycle;
+    const arrival = call.arrival + cycleOffset;
+    const departure = call.departure + cycleOffset;
+    if (time < arrival - horizon || time > departure + horizon)
+        return undefined;
+    if (time < arrival) {
+        return {
+            phase: 'approaching',
+            progress: (time - (arrival - horizon)) / horizon,
+        };
+    }
+    if (time <= departure)
+        return { phase: 'dwelling', progress: 1 };
+    return {
+        phase: 'departing',
+        progress: (time - departure) / horizon,
+    };
+}
+export function callsAtHub(snapshot, hub) {
+    const hubNames = new Set([hub.name, ...(hub.aliases ?? [])]);
+    const hubStopIndexes = new Set();
+    snapshot.stops.forEach((stop, index) => {
+        if (hubNames.has(stop[2]))
+            hubStopIndexes.add(index);
+    });
+    const calls = [];
+    for (const train of snapshot.trains) {
+        const callIndex = train.stops.findIndex(([stopIndex]) => hubStopIndexes.has(stopIndex));
+        if (callIndex < 0)
+            continue;
+        const stop = train.stops[callIndex];
+        const hubStop = snapshot.stops[stop[0]];
+        if (!hubStop)
+            continue;
+        calls.push({
+            id: `${train.id}:${stop[0]}`,
+            train,
+            arrival: stop[1],
+            departure: stop[2],
+            hubStop,
+            previousStop: snapshot.stops[train.stops[callIndex - 1]?.[0]],
+            nextStop: snapshot.stops[train.stops[callIndex + 1]?.[0]],
+        });
+    }
+    return calls.sort((first, second) => first.arrival - second.arrival);
+}
+export function callsNearTime(calls, time, horizon = 15 * 60, cycle = 24 * 3600) {
+    return calls.filter((call) => {
+        const midpoint = (call.arrival + call.departure) / 2;
+        const cycleOffset = Math.round((time - midpoint) / cycle) * cycle;
+        return (time >= call.arrival + cycleOffset - horizon &&
+            time <= call.departure + cycleOffset + horizon);
+    });
+}
+export function nextHubCall(calls, time) {
+    return calls.find((call) => call.arrival >= time) ?? calls[0];
+}
+function projectedVector(from, to, latitude) {
+    const longitudeScale = Math.cos((latitude * Math.PI) / 180);
+    return [(to[0] - from[0]) * longitudeScale, to[1] - from[1]];
+}
+/**
+ * Classify a movement by comparing its local path through a hub with the line
+ * from a study centre to that hub. The absolute dot product makes the result
+ * independent of service direction: inbound and outbound calls share a lens.
+ */
+export function hubFlowOrientation(call, centre, radialThreshold = Math.SQRT1_2) {
+    const routeStart = call.previousStop ?? call.hubStop;
+    const routeEnd = call.nextStop ?? call.hubStop;
+    const route = projectedVector(routeStart, routeEnd, call.hubStop[1]);
+    const radial = projectedVector(centre, call.hubStop, call.hubStop[1]);
+    const routeLength = Math.hypot(route[0], route[1]);
+    const radialLength = Math.hypot(radial[0], radial[1]);
+    if (routeLength < 1e-8 || radialLength < 1e-8)
+        return 'radial';
+    const alignment = Math.abs((route[0] * radial[0] + route[1] * radial[1]) /
+        (routeLength * radialLength));
+    return alignment >= radialThreshold ? 'radial' : 'orbital';
+}
+export function callsForHubFlowLens(calls, lens, centre) {
+    if (lens === 'all')
+        return calls;
+    return calls.filter((call) => hubFlowOrientation(call, centre) === lens);
+}
+export function hubFlowSummary(calls, centre) {
+    let radial = 0;
+    for (const call of calls) {
+        if (hubFlowOrientation(call, centre) === 'radial')
+            radial += 1;
+    }
+    return {
+        all: calls.length,
+        radial,
+        orbital: calls.length - radial,
+    };
+}
+/** A soft day/night envelope with transitions around 22:00 and 06:30. */
+export function hubNightSignalMix(time) {
+    const timeOfDay = ((time % 86_400) + 86_400) % 86_400;
+    const eveningStart = 22 * 3_600;
+    const eveningEnd = 23 * 3_600;
+    const morningStart = 5 * 3_600;
+    const morningEnd = 6.5 * 3_600;
+    if (timeOfDay >= eveningStart) {
+        return Math.min(1, (timeOfDay - eveningStart) / (eveningEnd - eveningStart));
+    }
+    if (timeOfDay < morningStart)
+        return 1;
+    if (timeOfDay < morningEnd) {
+        return 1 - (timeOfDay - morningStart) / (morningEnd - morningStart);
+    }
+    return 0;
+}

package/domain/journey.d.ts

@@ -0,0 +1,19 @@
+export interface JourneyStop {
+    readonly name: string;
+    readonly progress: number;
+    readonly departure: string;
+}
+export interface Journey {
+    readonly id: string;
+    readonly service: string;
+    readonly destination: string;
+    readonly operator: string;
+    readonly speedKmh: number;
+    readonly stops: readonly JourneyStop[];
+}
+export interface JourneyPosition {
+    readonly previous: JourneyStop;
+    readonly next: JourneyStop;
+    readonly legProgress: number;
+}
+export declare function positionOnJourney(journey: Journey, progress: number): JourneyPosition;

package/domain/journey.js

@@ -0,0 +1,23 @@
+export function positionOnJourney(journey, progress) {
+    const clamped = Math.min(1, Math.max(0, progress));
+    const nextIndex = journey.stops.findIndex((stop) => stop.progress >= clamped);
+    if (nextIndex <= 0) {
+        return {
+            previous: journey.stops[0],
+            next: journey.stops[1],
+            legProgress: 0,
+        };
+    }
+    if (nextIndex === -1) {
+        const last = journey.stops.at(-1);
+        return { previous: last, next: last, legProgress: 1 };
+    }
+    const previous = journey.stops[nextIndex - 1];
+    const next = journey.stops[nextIndex];
+    const legLength = next.progress - previous.progress;
+    return {
+        previous,
+        next,
+        legProgress: legLength === 0 ? 1 : (clamped - previous.progress) / legLength,
+    };
+}