@motionstudies/core 0.1.0-alpha.0

package/domain/lakes.d.ts

@@ -0,0 +1,21 @@
+import type { BoundaryCoordinate } from './boundary.ts';
+export interface MapWaterBody {
+    readonly id: string;
+    readonly name: string;
+    readonly areaSquareKilometres: number;
+    readonly polygons: readonly (readonly (readonly BoundaryCoordinate[])[])[];
+}
+export interface MapWaterBodies {
+    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 minimumAreaSquareKilometres: number;
+    };
+    readonly lakes: readonly MapWaterBody[];
+}

package/domain/lakes.js

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

package/domain/map-reference.d.ts

@@ -0,0 +1,20 @@
+import type { BoundaryCoordinate } from './boundary.ts';
+export interface MapReferencePath {
+    readonly id: string;
+    readonly name: string;
+    readonly color?: string;
+    readonly paths: readonly (readonly BoundaryCoordinate[])[];
+}
+export interface MapReferencePaths {
+    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 references: readonly MapReferencePath[];
+}

package/domain/map-reference.js

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

package/domain/network-day.d.ts

@@ -0,0 +1,4 @@
+import type { NetworkDayChunk, NetworkDayChunkDescriptor, NetworkDayManifest, NetworkSnapshot } from './network.ts';
+export declare function dayChunkForTime(manifest: NetworkDayManifest, time: number): NetworkDayChunkDescriptor;
+export declare function adjacentDayChunks(manifest: NetworkDayManifest, current: NetworkDayChunkDescriptor): readonly NetworkDayChunkDescriptor[];
+export declare function networkSnapshotForDayChunk(manifest: NetworkDayManifest, chunk?: NetworkDayChunk): NetworkSnapshot;

package/domain/network-day.js

@@ -0,0 +1,21 @@
+export function dayChunkForTime(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 adjacentDayChunks(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 networkSnapshotForDayChunk(manifest, chunk) {
+    return {
+        metadata: manifest.metadata,
+        bounds: manifest.bounds,
+        stops: manifest.stops,
+        edges: manifest.edges,
+        paths: manifest.paths,
+        edgePaths: manifest.edgePaths,
+        trains: chunk?.trains ?? [],
+    };
+}

package/domain/network-layers.d.ts

@@ -0,0 +1,7 @@
+import type { NetworkSnapshot } from './network.ts';
+/**
+ * Combines independently loaded data layers without changing their source IDs.
+ * This is intentionally a runtime composition: each source artifact retains an
+ * independent payload budget and can remain outside the opening request graph.
+ */
+export declare function mergeNetworkLayers(snapshots: readonly NetworkSnapshot[]): NetworkSnapshot;

package/domain/network-layers.js

@@ -0,0 +1,131 @@
+function mergeInterchangeComplexes(snapshots) {
+    const studies = snapshots.flatMap(({ metadata }) => metadata.interchangeStudy ? [metadata.interchangeStudy] : []);
+    if (!studies.length)
+        return undefined;
+    const complexes = new Map();
+    for (const study of studies) {
+        for (const complex of study.complexes) {
+            const existing = complexes.get(complex.id);
+            if (!existing) {
+                complexes.set(complex.id, complex);
+                continue;
+            }
+            const links = new Map([...existing.links, ...complex.links].map((link) => [
+                `${link.fromStopId}:${link.toStopId}:${link.minimumTransferSeconds}`,
+                link,
+            ]));
+            complexes.set(complex.id, {
+                ...existing,
+                stopIds: [...new Set([...existing.stopIds, ...complex.stopIds])],
+                links: [...links.values()],
+            });
+        }
+    }
+    return {
+        model: studies.map(({ model }) => model).join(' '),
+        complexes: [...complexes.values()],
+    };
+}
+/**
+ * Combines independently loaded data layers without changing their source IDs.
+ * This is intentionally a runtime composition: each source artifact retains an
+ * independent payload budget and can remain outside the opening request graph.
+ */
+export function mergeNetworkLayers(snapshots) {
+    const primary = snapshots[0];
+    if (!primary)
+        throw new Error('At least one network layer is required');
+    for (const snapshot of snapshots.slice(1)) {
+        if (snapshot.metadata.serviceDate !== primary.metadata.serviceDate ||
+            snapshot.metadata.windowStart !== primary.metadata.windowStart ||
+            snapshot.metadata.windowEnd !== primary.metadata.windowEnd) {
+            throw new Error('Network layers must share a service date and study window');
+        }
+    }
+    const stops = [];
+    const stopIndexByIdentity = new Map();
+    const paths = [];
+    const pathIndexByCoordinates = new Map();
+    const edges = [];
+    const edgePaths = [];
+    const trains = [];
+    const trainIds = new Set();
+    for (const snapshot of snapshots) {
+        const stopRemap = snapshot.stops.map((stop) => {
+            const identity = stop[4] ?? `${stop[0]}:${stop[1]}:${stop[2]}`;
+            const existing = stopIndexByIdentity.get(identity);
+            if (existing !== undefined)
+                return existing;
+            const index = stops.length;
+            stops.push(stop);
+            stopIndexByIdentity.set(identity, index);
+            return index;
+        });
+        const pathRemap = (snapshot.paths ?? []).map((path) => {
+            const identity = JSON.stringify(path);
+            const existing = pathIndexByCoordinates.get(identity);
+            if (existing !== undefined)
+                return existing;
+            const index = paths.length;
+            paths.push(path);
+            pathIndexByCoordinates.set(identity, index);
+            return index;
+        });
+        snapshot.edges.forEach(([from, to], edgeIndex) => {
+            edges.push([stopRemap[from], stopRemap[to]]);
+            const sourcePathIndex = snapshot.edgePaths?.[edgeIndex];
+            edgePaths.push(sourcePathIndex === null || sourcePathIndex === undefined
+                ? null
+                : (pathRemap[sourcePathIndex] ?? null));
+        });
+        for (const train of snapshot.trains) {
+            if (trainIds.has(train.id))
+                continue;
+            trainIds.add(train.id);
+            trains.push({
+                ...train,
+                stops: train.stops.map(([stopIndex, arrival, departure]) => [
+                    stopRemap[stopIndex],
+                    arrival,
+                    departure,
+                ]),
+                pathSegments: train.pathSegments?.map((pathIndex) => pathIndex === null ? null : (pathRemap[pathIndex] ?? null)),
+            });
+        }
+    }
+    const geometry = primary.metadata.geometry
+        ? {
+            ...primary.metadata.geometry,
+            model: `Runtime composition of ${snapshots.length} independently loaded geometry layers`,
+            matchedSegments: edgePaths.filter((pathIndex) => pathIndex !== null).length,
+            totalSegments: edges.length,
+            resolvedStops: stops.length,
+            totalStops: stops.length,
+        }
+        : undefined;
+    return {
+        metadata: {
+            ...primary.metadata,
+            feedVersion: snapshots.map(({ metadata }) => metadata.feedVersion).join('+'),
+            model: snapshots.map(({ metadata }) => metadata.model).join(' + '),
+            note: `${snapshots.length} independently loaded network layers composed in the browser.`,
+            modes: [...new Set(snapshots.flatMap(({ metadata }) => metadata.modes ?? []))],
+            localRouteIds: [
+                ...new Set(snapshots.flatMap(({ metadata }) => metadata.localRouteIds ?? [])),
+            ],
+            interchangeStudy: mergeInterchangeComplexes(snapshots),
+            geometry,
+        },
+        bounds: {
+            minLongitude: Math.min(...snapshots.map(({ bounds }) => bounds.minLongitude)),
+            minLatitude: Math.min(...snapshots.map(({ bounds }) => bounds.minLatitude)),
+            maxLongitude: Math.max(...snapshots.map(({ bounds }) => bounds.maxLongitude)),
+            maxLatitude: Math.max(...snapshots.map(({ bounds }) => bounds.maxLatitude)),
+        },
+        stops,
+        edges,
+        paths,
+        edgePaths,
+        trains,
+    };
+}

package/domain/network.d.ts

@@ -0,0 +1,173 @@
+export type NetworkStop = readonly [
+    longitude: number,
+    latitude: number,
+    name: string,
+    platformCode?: string,
+    sourceId?: string,
+    labelRank?: number
+];
+export type NetworkEdge = readonly [from: number, to: number];
+export type NetworkPathPoint = readonly [longitude: number, latitude: number];
+export type NetworkPath = readonly NetworkPathPoint[];
+export type TrainStop = readonly [stopIndex: number, arrival: number, departure: number];
+export type ServiceCategory = 'international' | 'intercity' | 'interregio' | 'regional-express' | 's-bahn' | 'regional' | 'tram' | 'metro' | 'bus' | 'ferry' | 'cableway' | 'funicular' | 'other';
+export interface NetworkTrain {
+    readonly id: string;
+    readonly route: string;
+    readonly headsign: string;
+    readonly shortName: string;
+    readonly category: ServiceCategory;
+    readonly mode?: string;
+    readonly servicePattern?: 'local' | 'express';
+    readonly start: number;
+    readonly end: number;
+    readonly stops: readonly TrainStop[];
+    readonly pathSegments?: readonly (number | null)[];
+    readonly realtime?: RealtimeTrainState;
+    readonly operations?: ObservedTrainState;
+}
+export interface ObservedTrainState {
+    readonly kind: 'prediction-derived';
+    readonly observedAt: string;
+    readonly vehicleId: string;
+}
+export interface RealtimeTrainState {
+    readonly status: 'adjusted' | 'cancelled';
+    readonly delaySeconds: number;
+    readonly skippedStops: number;
+    readonly generatedAt: string;
+}
+export interface NetworkSnapshot {
+    readonly metadata: {
+        readonly publisher: string;
+        readonly feedVersion: string;
+        readonly serviceDate: string;
+        readonly windowStart: number;
+        readonly windowEnd: number;
+        readonly focusTime: number;
+        readonly sourceUrl: string;
+        readonly sourceSha256?: string;
+        readonly retrievedAt?: string;
+        readonly license?: string;
+        readonly licenseUrl?: string;
+        readonly model: string;
+        readonly note: string;
+        readonly modes?: readonly string[];
+        readonly labelHierarchy?: {
+            readonly model: string;
+            readonly stationCount: number;
+        };
+        readonly localAgencyIds?: readonly string[];
+        readonly localRouteIds?: readonly string[];
+        readonly servicePatternStudy?: {
+            readonly model: string;
+            readonly localTrips: number;
+            readonly expressTrips: number;
+            readonly passEvents: readonly ServicePatternPassEvent[];
+        };
+        readonly interchangeStudy?: {
+            readonly model: string;
+            readonly complexes: readonly InterchangeComplex[];
+        };
+        readonly geometry?: {
+            readonly publisher: string;
+            readonly feedVersion: string;
+            readonly sourceUrl: string;
+            readonly sourceSha256?: string;
+            readonly productUrl?: string;
+            readonly model: string;
+            readonly matchedSegments: number;
+            readonly totalSegments: number;
+            readonly resolvedStops?: number;
+            readonly totalStops?: number;
+            readonly simplificationToleranceMetres?: number;
+        };
+    };
+    readonly bounds: {
+        readonly minLongitude: number;
+        readonly minLatitude: number;
+        readonly maxLongitude: number;
+        readonly maxLatitude: number;
+    };
+    readonly stops: readonly NetworkStop[];
+    readonly edges: readonly NetworkEdge[];
+    readonly paths?: readonly NetworkPath[];
+    readonly edgePaths?: readonly (number | null)[];
+    readonly trains: readonly NetworkTrain[];
+}
+export interface InterchangeLink {
+    readonly fromStopId: string;
+    readonly toStopId: string;
+    readonly minimumTransferSeconds: number;
+}
+export interface InterchangeComplex {
+    readonly id: string;
+    readonly name: string;
+    readonly longitude: number;
+    readonly latitude: number;
+    readonly stopIds: readonly string[];
+    readonly links: readonly InterchangeLink[];
+}
+export interface ServicePatternPassEvent {
+    readonly id: string;
+    readonly localTrainId: string;
+    readonly expressTrainId: string;
+    readonly fromStopId: string;
+    readonly toStopId: string;
+    readonly time: number;
+    readonly startDeltaSeconds: number;
+    readonly endDeltaSeconds: number;
+}
+export interface NetworkDayChunkDescriptor {
+    readonly id: string;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly path: string;
+    readonly tripCount: number;
+    readonly bytes?: number;
+    readonly sha256?: string;
+}
+export interface NetworkDayManifest {
+    readonly metadata: NetworkSnapshot['metadata'];
+    readonly bounds: NetworkSnapshot['bounds'];
+    readonly stops: NetworkSnapshot['stops'];
+    readonly edges: NetworkSnapshot['edges'];
+    readonly paths?: NetworkSnapshot['paths'];
+    readonly edgePaths?: NetworkSnapshot['edgePaths'];
+    readonly tripCount: number;
+    readonly chunks: readonly NetworkDayChunkDescriptor[];
+}
+export interface NetworkDayChunk {
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly trains: readonly NetworkTrain[];
+}
+export interface StationRoute {
+    readonly name: string;
+    readonly category: ServiceCategory;
+}
+export interface StationIndexEntry {
+    readonly name: string;
+    readonly labelRank?: number;
+    readonly stopIndexes: readonly number[];
+    readonly trainIds: readonly string[];
+    readonly routes: readonly StationRoute[];
+}
+export interface NetworkRouteIndexEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly category: ServiceCategory;
+    readonly trainIds: readonly string[];
+    readonly stopIndexes: readonly number[];
+    readonly headsigns: readonly string[];
+}
+export declare function buildRouteIndex(snapshot: NetworkSnapshot): readonly NetworkRouteIndexEntry[];
+export declare function buildStationIndex(snapshot: NetworkSnapshot): readonly StationIndexEntry[];
+export interface TrainPosition {
+    readonly fromStop: number;
+    readonly toStop: number;
+    readonly progress: number;
+    readonly segmentIndex?: number;
+}
+export declare function positionForTrain(train: NetworkTrain, time: number): TrainPosition | undefined;
+export declare function formatServiceTime(totalSeconds: number): string;

package/domain/network.js

@@ -0,0 +1,106 @@
+export function buildRouteIndex(snapshot) {
+    const records = new Map();
+    for (const train of snapshot.trains) {
+        const id = `${train.category}:${train.route}`;
+        const record = records.get(id) ?? {
+            name: train.route,
+            category: train.category,
+            trainIds: new Set(),
+            stopIndexes: new Set(),
+            headsigns: new Set(),
+        };
+        record.trainIds.add(train.id);
+        train.stops.forEach(([stopIndex]) => record.stopIndexes.add(stopIndex));
+        if (train.headsign)
+            record.headsigns.add(train.headsign);
+        records.set(id, record);
+    }
+    return [...records.entries()]
+        .map(([id, record]) => ({
+        id,
+        name: record.name,
+        category: record.category,
+        trainIds: [...record.trainIds],
+        stopIndexes: [...record.stopIndexes],
+        headsigns: [...record.headsigns].sort((first, second) => first.localeCompare(second, 'de-CH')),
+    }))
+        .sort((first, second) => first.category.localeCompare(second.category, 'en') ||
+        first.name.localeCompare(second.name, 'de-CH', { numeric: true }));
+}
+export function buildStationIndex(snapshot) {
+    const records = new Map();
+    snapshot.stops.forEach((stop, index) => {
+        const record = records.get(stop[2]) ?? {
+            stopIndexes: [],
+            trainIds: new Set(),
+            routes: new Map(),
+            labelRank: stop[5],
+        };
+        record.stopIndexes.push(index);
+        if (stop[5] !== undefined) {
+            record.labelRank = Math.min(record.labelRank ?? Number.POSITIVE_INFINITY, stop[5]);
+        }
+        records.set(stop[2], record);
+    });
+    for (const train of snapshot.trains) {
+        const visitedNames = new Set();
+        for (const [stopIndex] of train.stops) {
+            const name = snapshot.stops[stopIndex]?.[2];
+            if (!name || visitedNames.has(name))
+                continue;
+            visitedNames.add(name);
+            const record = records.get(name);
+            if (!record)
+                continue;
+            record.trainIds.add(train.id);
+            record.routes.set(`${train.category}:${train.route}`, {
+                name: train.route,
+                category: train.category,
+            });
+        }
+    }
+    return [...records.entries()]
+        .filter(([, record]) => record.trainIds.size > 0)
+        .map(([name, record]) => ({
+        name,
+        labelRank: record.labelRank,
+        stopIndexes: record.stopIndexes,
+        trainIds: [...record.trainIds],
+        routes: [...record.routes.values()].sort((first, second) => first.name.localeCompare(second.name, 'de-CH')),
+    }));
+}
+export function positionForTrain(train, time) {
+    if (train.realtime?.status === 'cancelled' ||
+        time < train.start ||
+        time > train.end ||
+        train.stops.length < 2) {
+        return undefined;
+    }
+    for (let index = 1; index < train.stops.length; index += 1) {
+        const previous = train.stops[index - 1];
+        const next = train.stops[index];
+        if (time <= previous[2]) {
+            return { fromStop: previous[0], toStop: previous[0], progress: 0 };
+        }
+        if (time <= next[1]) {
+            const duration = Math.max(1, next[1] - previous[2]);
+            return {
+                fromStop: previous[0],
+                toStop: next[0],
+                progress: Math.min(1, Math.max(0, (time - previous[2]) / duration)),
+                segmentIndex: index - 1,
+            };
+        }
+        if (time <= next[2]) {
+            return { fromStop: next[0], toStop: next[0], progress: 0 };
+        }
+    }
+    const last = train.stops.at(-1);
+    return { fromStop: last[0], toStop: last[0], progress: 0 };
+}
+export function formatServiceTime(totalSeconds) {
+    const normalized = ((Math.round(totalSeconds) % 86400) + 86400) % 86400;
+    const hours = Math.floor(normalized / 3600);
+    const minutes = Math.floor((normalized % 3600) / 60);
+    return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}`;
+}

package/domain/operations.d.ts

@@ -0,0 +1,85 @@
+export interface ObservedStopPrediction {
+    readonly stopId: string;
+    readonly stopName: string;
+    readonly platformName?: string;
+    readonly expectedArrival: string;
+    readonly secondsToStop: number;
+}
+export interface ObservedTransitVehicle {
+    readonly id: string;
+    readonly lineId: string;
+    readonly lineName: string;
+    readonly modeName?: string;
+    readonly destinationStopId?: string;
+    readonly destinationName?: string;
+    readonly direction?: string;
+    readonly currentLocation?: string;
+    readonly towards?: string;
+    readonly observedAt: string;
+    readonly predictions: readonly ObservedStopPrediction[];
+}
+export interface ObservedLineStatus {
+    readonly lineId: string;
+    readonly lineName: string;
+    readonly severity: number;
+    readonly severityDescription: string;
+    readonly reason?: string;
+}
+export interface TransitOperationsSnapshot {
+    readonly metadata: {
+        readonly kind: 'observed-operations';
+        readonly publisher: string;
+        readonly sourceUrl: string;
+        readonly collectedAt: string;
+        readonly scheduledAt: string;
+        readonly lineIds: readonly string[];
+        readonly model: string;
+    };
+    readonly vehicles: readonly ObservedTransitVehicle[];
+    readonly lineStatuses: readonly ObservedLineStatus[];
+}
+export interface TransitOperationsDayFrame {
+    readonly time: number;
+    readonly observedAt: string;
+    readonly vehicles: readonly ObservedTransitVehicle[];
+    readonly lineStatuses: readonly ObservedLineStatus[];
+}
+export interface TransitOperationsDayChunk {
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly frames: readonly TransitOperationsDayFrame[];
+}
+export interface TransitOperationsDayChunkDescriptor {
+    readonly id: string;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly path: string;
+    readonly frameCount: number;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+export interface TransitOperationsDayManifest {
+    readonly metadata: {
+        readonly kind: 'observed-operations-day';
+        readonly publisher: string;
+        readonly serviceDate: string;
+        readonly timezone: string;
+        readonly sourceUrl: string;
+        readonly model: string;
+        readonly note: string;
+        readonly sampleIntervalSeconds: number;
+        readonly completeMinutes: number;
+        readonly longestGapSeconds: number;
+        readonly lineIds: readonly string[];
+    };
+    readonly chunks: readonly TransitOperationsDayChunkDescriptor[];
+}
+export interface ObservedNetworkProjection {
+    readonly snapshot: import('./network.ts').NetworkSnapshot;
+    readonly serviceTime: number;
+    readonly matchedVehicleCount: number;
+    readonly unmatchedVehicleCount: number;
+}
+export declare function operationsServiceTime(snapshot: TransitOperationsSnapshot, timeZone: string): number;
+export declare function operationsAgeSeconds(snapshot: TransitOperationsSnapshot, now?: number): number;
+export declare function projectOperationsOntoNetwork(reference: import('./network.ts').NetworkSnapshot, operations: TransitOperationsSnapshot, serviceTime: number): ObservedNetworkProjection;