@motionstudies/core 0.1.0-alpha.3 → 0.1.0-alpha.31

package/domain/aggregate-road.js

@@ -0,0 +1,22 @@
+export function aggregateRoadValue(sample, metric) {
+    const value = metric === 'vehicleCount' ? sample?.vehicleCount : sample?.averageSpeed?.value;
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && (metric !== 'vehicleCount' || Number.isInteger(value)) ? value : null;
+}
+/** Compile once per immutable series. Conflicting or duplicate slots remain unavailable.
+ * No interpolation, nearest-slot fallback or conversion between provider and UTC clocks.
+ */
+export function indexAggregateRoadSlots(series, serviceDate) {
+    const result = new Map(), conflicts = new Set();
+    for (const sample of series.samples) {
+        const interval = sample.interval;
+        if (interval.kind !== 'provider-slot' || interval.serviceDate !== serviceDate || !Number.isSafeInteger(interval.index) || interval.index < 0)
+            continue;
+        if (result.has(interval.index)) {
+            result.delete(interval.index);
+            conflicts.add(interval.index);
+        }
+        else if (!conflicts.has(interval.index))
+            result.set(interval.index, sample);
+    }
+    return result;
+}

package/domain/air-day.d.ts

@@ -1,4 +1,4 @@
-import type { AirSnapshot, AirTrack } from './air.ts';
+import type { AirEndpoint, AirSnapshot, AirTrack } from './air.ts';
 export interface AirDayAircraft {
     readonly id: string;
     readonly icaoAddress: string;
@@ -6,6 +6,8 @@ export interface AirDayAircraft {
     readonly start: number;
     readonly end: number;
     readonly airportIds?: readonly string[];
+    readonly origin?: AirEndpoint;
+    readonly destination?: AirEndpoint;
     readonly chunkIds: readonly string[];
 }
 export interface AirDayChunkDescriptor {

package/domain/air.d.ts

@@ -1,3 +1,4 @@
+import type { AirContinent, AirContinentSource } from '../air-continents.ts';
 export type AirSample = readonly [
     time: number,
     longitude: number,
@@ -5,6 +6,18 @@ export type AirSample = readonly [
     altitudeFeet: number,
     groundSpeedKnots: number
 ];
+export interface AirEndpoint {
+    readonly icao: string;
+    readonly iata: string;
+    readonly name: string;
+    readonly city: string;
+    /** Study-local seconds at the observed approach/departure boundary; not a scheduled time. */
+    readonly time: number;
+    readonly evidence: 'observed-endpoint';
+    /** Airport geography, separate from the inferred route evidence. Absent in older releases. */
+    readonly continent?: AirContinent;
+    readonly continentSource?: AirContinentSource;
+}
 export interface AirTrack {
     readonly id: string;
     readonly icaoAddress?: string;
@@ -12,6 +25,8 @@ export interface AirTrack {
     readonly start: number;
     readonly end: number;
     readonly airportIds?: readonly string[];
+    readonly origin?: AirEndpoint;
+    readonly destination?: AirEndpoint;
     readonly samples: readonly AirSample[];
 }
 export interface AirSnapshot {

package/domain/airport.d.ts

@@ -1,4 +1,5 @@
 import type { AirTrack } from './air.ts';
+import type { AirSearchTrack } from '../air-search.ts';
 export interface StudyAirport {
     readonly id: string;
     readonly name: string;
@@ -15,3 +16,18 @@ 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>;
+/** Board events come from full-flight endpoint evidence, not truncated playback chunks. */
+export declare function airportBoardMovements(aircraft: readonly AirSearchTrack[], airport: StudyAirport): {
+    departures: {
+        id: string;
+        time: number;
+        service: string;
+        place?: string;
+    }[];
+    arrivals: {
+        id: string;
+        time: number;
+        service: string;
+        place?: string;
+    }[];
+};

package/domain/airport.js

@@ -39,3 +39,26 @@ export function airportAirTrackIds(tracks, airport) {
         .filter((track) => airTrackServesAirport(track, airport))
         .map((track) => track.id));
 }
+/** Board events come from full-flight endpoint evidence, not truncated playback chunks. */
+export function airportBoardMovements(aircraft, airport) {
+    const departures = [];
+    const arrivals = [];
+    const seen = new Set();
+    for (const track of aircraft) {
+        for (const direction of ['origin', 'destination']) {
+            const endpoint = track[direction];
+            if (!endpoint || endpoint.icao !== airport.icao || !Number.isFinite(endpoint.time))
+                continue;
+            const key = `${track.icaoAddress ?? track.id}:${direction}:${endpoint.time}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const other = direction === 'origin' ? track.destination : track.origin;
+            const row = { id: track.id, time: endpoint.time, service: track.callsign,
+                place: other ? `${other.city || other.name} ${other.iata || other.icao}` : undefined };
+            const rows = direction === 'origin' ? departures : arrivals;
+            rows.push(row);
+        }
+    }
+    return { departures, arrivals };
+}

package/domain/daylight.d.ts

@@ -0,0 +1,32 @@
+/** Sun position and smooth lighting envelopes for a place and instant. The position follows the
+ * low-precision solar algorithm published by Astronomy Answers (as popularised by SunCalc), good
+ * to a fraction of a degree: enough to light a scene and place a terminator, not for astronomy.
+ * The envelopes are artistic colour responses to sun altitude; they encode no weather or sky observation.
+ */
+export interface SolarPosition {
+    /** Degrees above the horizon; negative below. */
+    readonly altitude: number;
+    /** Degrees clockwise from north. */
+    readonly azimuth: number;
+}
+/** Sun-altitude thresholds in degrees. Each envelope rises smoothly between its bounds; warmth also falls again between its last two. */
+export interface DaylightEnvelopes {
+    readonly twilight: readonly [from: number, to: number];
+    readonly warmth: readonly [from: number, to: number, fallFrom: number, fallTo: number];
+    readonly daylight: readonly [from: number, to: number];
+}
+export declare const DEFAULT_DAYLIGHT_ENVELOPES: DaylightEnvelopes;
+export interface Daylight extends SolarPosition {
+    /** Unit vector towards the sun in a scene frame with +x east, +y up and +z south. */
+    readonly direction: readonly [number, number, number];
+    /** 0 in full night, 1 once the sun nears the horizon. */
+    readonly twilight: number;
+    /** Peaks around sunrise and sunset, 0 at night and in full day. */
+    readonly warmth: number;
+    /** 0 below the horizon, 1 once the sun is well up. */
+    readonly daylight: number;
+}
+/** Sun altitude and azimuth for an instant, or null for an invalid instant or place. */
+export declare function solarPosition(time: number | string | Date, latitude: number, longitude: number): SolarPosition | null;
+/** Sun direction and lighting envelopes for a place and instant, or null for an invalid instant or place. */
+export declare function daylightAt(time: number | string | Date, latitude: number, longitude: number, envelopes?: DaylightEnvelopes): Daylight | null;

package/domain/daylight.js

@@ -0,0 +1,32 @@
+export const DEFAULT_DAYLIGHT_ENVELOPES = { twilight: [-18, -1], warmth: [-12, -1, 3, 15], daylight: [-1, 12] };
+const rad = Math.PI / 180, dayMs = 86_400_000, J1970 = 2440588, J2000 = 2451545, obliquity = rad * 23.4397;
+const smooth = (a, b, value) => { const t = Math.max(0, Math.min(1, (value - a) / (b - a))); return t * t * (3 - 2 * t); };
+const instant = (time) => typeof time === 'number' ? time : time instanceof Date ? time.getTime() : Date.parse(time);
+/** Sun altitude and azimuth for an instant, or null for an invalid instant or place. */
+export function solarPosition(time, latitude, longitude) {
+    const ms = instant(time);
+    if (!Number.isFinite(ms) || !Number.isFinite(latitude) || !Number.isFinite(longitude))
+        return null;
+    const days = ms / dayMs - .5 + J1970 - J2000, phi = rad * latitude;
+    const anomaly = rad * (357.5291 + .98560028 * days);
+    const eclipticLongitude = anomaly + rad * (1.9148 * Math.sin(anomaly) + .02 * Math.sin(2 * anomaly) + .0003 * Math.sin(3 * anomaly)) + rad * 102.9372 + Math.PI;
+    const declination = Math.asin(Math.sin(obliquity) * Math.sin(eclipticLongitude));
+    const rightAscension = Math.atan2(Math.sin(eclipticLongitude) * Math.cos(obliquity), Math.cos(eclipticLongitude));
+    const hourAngle = rad * (280.16 + 360.9856235 * days) + rad * longitude - rightAscension;
+    const altitude = Math.asin(Math.sin(phi) * Math.sin(declination) + Math.cos(phi) * Math.cos(declination) * Math.cos(hourAngle));
+    const fromSouth = Math.atan2(Math.sin(hourAngle), Math.cos(hourAngle) * Math.sin(phi) - Math.tan(declination) * Math.cos(phi));
+    return { altitude: altitude / rad, azimuth: ((fromSouth / rad + 180) % 360 + 360) % 360 };
+}
+/** Sun direction and lighting envelopes for a place and instant, or null for an invalid instant or place. */
+export function daylightAt(time, latitude, longitude, envelopes = DEFAULT_DAYLIGHT_ENVELOPES) {
+    const position = solarPosition(time, latitude, longitude);
+    if (!position)
+        return null;
+    const altitude = position.altitude * rad, fromSouth = (position.azimuth - 180) * rad;
+    const [tw0, tw1] = envelopes.twilight, [w0, w1, w2, w3] = envelopes.warmth, [d0, d1] = envelopes.daylight;
+    return { ...position,
+        direction: [-Math.sin(fromSouth) * Math.cos(altitude), Math.sin(altitude), Math.cos(fromSouth) * Math.cos(altitude)],
+        twilight: smooth(tw0, tw1, position.altitude),
+        warmth: smooth(w0, w1, position.altitude) * (1 - smooth(w2, w3, position.altitude)),
+        daylight: smooth(d0, d1, position.altitude) };
+}

package/domain/field-paths.d.ts

@@ -0,0 +1,35 @@
+/** Paths integrated through an estimated velocity field. They illustrate the field; they are not
+ * observed trajectories of anything. Integration refuses to start from, pass through or land on
+ * unsupported field, so a trail ends at a gap instead of crossing it.
+ */
+export interface FieldPoint {
+    readonly latitude: number;
+    readonly longitude: number;
+}
+export interface FieldMovement {
+    readonly value: number;
+    readonly vector: readonly [east: number, north: number];
+    readonly support: number;
+}
+/** Reads the field at a place and study time; null or undefined where it is unavailable. */
+export type FieldMovementSample = (point: FieldPoint, time: number) => FieldMovement | null | undefined;
+export interface FieldTrack {
+    /** Study time of the first point. */
+    readonly start: number;
+    readonly level: number;
+    /** One point per unit step: latitude, longitude and any further channels to interpolate. */
+    readonly points: readonly (readonly number[])[];
+}
+export interface TrailSegment {
+    readonly a: readonly number[];
+    readonly b: readonly number[];
+    readonly tail: number;
+    readonly fade: number;
+    readonly level: number;
+}
+/** Linear blend of two readings. Either side unavailable makes the blend unavailable except at its exact ends. */
+export declare function mixFieldMovement(a: FieldMovement | null | undefined, b: FieldMovement | null | undefined, fraction: number): FieldMovement | null;
+/** Explicit midpoint step. Vectors are metres per second; `secondsPerStep` converts one unit of study time. */
+export declare function advanceFieldPath(point: FieldPoint, time: number, step: number, sample: FieldMovementSample, secondsPerStep?: number): (FieldPoint & FieldMovement) | null;
+/** The part of a track visible at a study time: the last `trail` steps, with a fade at either end of the track. Scrubbing back restores identical segments. */
+export declare function visibleTrailSegments(track: FieldTrack, index: number, trail?: number): TrailSegment[];

package/domain/field-paths.js

@@ -0,0 +1,43 @@
+const rad = Math.PI / 180, kmPerDegree = 6371.0088 * rad;
+const smooth = (t) => { t = Math.max(0, Math.min(1, t)); return t * t * (3 - 2 * t); };
+/** Linear blend of two readings. Either side unavailable makes the blend unavailable except at its exact ends. */
+export function mixFieldMovement(a, b, fraction) {
+    if (fraction === 0)
+        return a ?? null;
+    if (fraction === 1)
+        return b ?? null;
+    if (!a || !b)
+        return null;
+    const mix = (x, y) => x * (1 - fraction) + y * fraction;
+    return { value: mix(a.value, b.value), vector: [mix(a.vector[0], b.vector[0]), mix(a.vector[1], b.vector[1])], support: mix(a.support, b.support) };
+}
+const displace = (p, v, seconds) => ({
+    latitude: p.latitude + v.vector[1] * seconds / 1000 / kmPerDegree,
+    longitude: p.longitude + v.vector[0] * seconds / 1000 / (kmPerDegree * Math.cos(p.latitude * rad)),
+});
+/** Explicit midpoint step. Vectors are metres per second; `secondsPerStep` converts one unit of study time. */
+export function advanceFieldPath(point, time, step, sample, secondsPerStep = 300) {
+    const a = sample(point, time);
+    if (!a || a.support <= 0)
+        return null;
+    const mid = displace(point, a, step * secondsPerStep / 2), b = sample(mid, time + step / 2);
+    if (!b || b.support <= 0)
+        return null;
+    const next = displace(point, b, step * secondsPerStep), value = sample(next, time + step);
+    return value && value.support > 0 ? { ...next, ...value } : null;
+}
+/** The part of a track visible at a study time: the last `trail` steps, with a fade at either end of the track. Scrubbing back restores identical segments. */
+export function visibleTrailSegments(track, index, trail = 15) {
+    const end = track.start + track.points.length - 1;
+    if (index <= track.start || index >= end)
+        return [];
+    const fade = smooth((index - track.start) / 2) * smooth((end - index) / 3), segments = [];
+    for (let i = Math.max(0, Math.floor(index - trail - track.start)); i < track.points.length - 1; i++) {
+        const t = track.start + i, a = Math.max(t, index - trail), b = Math.min(t + 1, index);
+        if (b <= a)
+            continue;
+        const p = track.points[i], q = track.points[i + 1], at = (f) => p.map((v, k) => v * (1 - f) + q[k] * f);
+        segments.push({ a: at(a - t), b: at(b - t), tail: Math.max(0, 1 - (index - (a + b) / 2) / trail), fade, level: track.level });
+    }
+    return segments;
+}

package/domain/gridded-series.d.ts

@@ -0,0 +1,30 @@
+/** A regular latitude/longitude grid of one or more variables at listed instants, such as cloud
+ * cover, rainfall or a model wind component. Values keep the source's own units; null marks a
+ * missing sample. Readings interpolate bilinearly in space and linearly in time, and a missing
+ * sample with any weight makes the whole reading unavailable rather than bridging the gap.
+ */
+export interface GriddedSeriesGrid {
+    readonly west: number;
+    readonly south: number;
+    readonly step: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface GriddedSeries<K extends string = string> {
+    /** ISO instants in ascending order. */
+    readonly times: readonly string[];
+    readonly grid: GriddedSeriesGrid;
+    /** One frame per instant; rows run south to north. */
+    readonly frames: readonly Readonly<Partial<Record<K, readonly (number | null)[]>>>[];
+}
+export interface TimeBracket {
+    readonly a: number;
+    readonly b: number;
+    readonly fraction: number;
+}
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export declare function bracketTime(times: readonly string[], time: string | number): TimeBracket | null;
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export declare function sampleGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, latitude: number, longitude: number, time: string | number): number | null;
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export declare function meanGriddedSeries<K extends string>(series: GriddedSeries<K>, key: K, time: string | number, range?: readonly [number, number]): number | null;

package/domain/gridded-series.js

@@ -0,0 +1,61 @@
+/** The adjacent frames around an instant. Exact instants bracket themselves; instants outside the series are null. */
+export function bracketTime(times, time) {
+    const value = typeof time === 'number' ? time : Date.parse(time);
+    if (!times.length || !Number.isFinite(value) || value < Date.parse(times[0]) || value > Date.parse(times[times.length - 1]))
+        return null;
+    for (let i = 0; i < times.length; i++) {
+        const stamp = Date.parse(times[i]);
+        if (value === stamp)
+            return { a: i, b: i, fraction: 0 };
+        if (stamp > value)
+            return { a: i - 1, b: i, fraction: (value - Date.parse(times[i - 1])) / (stamp - Date.parse(times[i - 1])) };
+    }
+    return null;
+}
+const valid = (sample, range) => typeof sample === 'number' && Number.isFinite(sample) && (!range || (sample >= range[0] && sample <= range[1]));
+/** One variable at a place and instant, or null outside the grid, outside the times, or beside a missing sample. */
+export function sampleGriddedSeries(series, key, latitude, longitude, time) {
+    const bracket = bracketTime(series.times, time), { west, south, step, width, height } = series.grid, x = (longitude - west) / step, y = (latitude - south) / step;
+    if (!bracket || !(x >= 0 && y >= 0 && x <= width - 1 && y <= height - 1))
+        return null;
+    const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0;
+    let value = 0;
+    for (const [t, wt] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+        for (const [ix, wx] of [[x0, 1 - fx], [Math.min(x0 + 1, width - 1), fx]])
+            for (const [iy, wy] of [[y0, 1 - fy], [Math.min(y0 + 1, height - 1), fy]]) {
+                const weight = wt * wx * wy;
+                if (weight === 0)
+                    continue;
+                const sample = series.frames[t]?.[key]?.[iy * width + ix];
+                if (!valid(sample))
+                    return null;
+                value += sample * weight;
+            }
+    }
+    return value;
+}
+/** Area-weighted mean of one variable over the whole grid at an instant. Any missing or out-of-range weighted sample makes the mean unavailable. */
+export function meanGriddedSeries(series, key, time, range) {
+    const bracket = bracketTime(series.times, time);
+    if (!bracket)
+        return null;
+    const { south, step, width, height } = series.grid;
+    let sum = 0, weight = 0;
+    for (let y = 0; y < height; y++) {
+        const area = Math.cos((south + y * step) * Math.PI / 180);
+        for (let x = 0; x < width; x++) {
+            let value = 0;
+            for (const [frame, w] of [[bracket.a, 1 - bracket.fraction], [bracket.b, bracket.fraction]]) {
+                if (w === 0)
+                    continue;
+                const sample = series.frames[frame]?.[key]?.[y * width + x];
+                if (!valid(sample, range))
+                    return null;
+                value += sample * w;
+            }
+            sum += value * area;
+            weight += area;
+        }
+    }
+    return weight ? sum / weight : null;
+}

package/domain/live-airport.d.ts

@@ -0,0 +1,42 @@
+/** Live boards use Unix seconds throughout, independent of an edition's recorded service day. */
+export interface LiveAirportMovement {
+    readonly id: string;
+    readonly service: string;
+    readonly scheduledTime?: number;
+    /** Provider revision: may be estimated or actual; do not relabel as confirmed. */
+    readonly revisedTime?: number;
+    readonly place?: string;
+    readonly gate?: string;
+    readonly status?: string;
+    readonly tone?: 'neutral' | 'accent' | 'warning';
+}
+export interface LiveAirportSnapshot {
+    readonly airport: {
+        readonly iata: string;
+        readonly name: string;
+        readonly city: string;
+        readonly timeZone: string;
+    };
+    readonly fetchedAt: number;
+    readonly freshUntil: number;
+    readonly expiresAt: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly departures: readonly LiveAirportMovement[];
+    readonly arrivals: readonly LiveAirportMovement[];
+}
+export type AirportFeedReason = 'disabled' | 'not-configured' | 'subscription' | 'budget' | 'provider' | 'rate-limit';
+export interface AirportFeedResponse {
+    readonly version: 1;
+    readonly status: 'fresh' | 'stale' | 'unavailable' | 'disabled';
+    readonly reason?: AirportFeedReason;
+    readonly retryAfterSeconds: number;
+    readonly snapshot?: LiveAirportSnapshot;
+}
+export interface AirportFeedCapabilities {
+    readonly version: 1;
+    readonly enabled: boolean;
+    readonly airports: readonly string[];
+}
+/** Validate the network boundary before publishing data to a card. */
+export declare function isAirportFeedResponse(value: unknown): value is AirportFeedResponse;

package/domain/live-airport.js

@@ -0,0 +1,32 @@
+const record = (value) => !!value && typeof value === 'object';
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+function movement(value) {
+    return record(value) && typeof value.id === 'string' && typeof value.service === 'string'
+        && ['scheduledTime', 'revisedTime'].every((key) => value[key] === undefined || finite(value[key]))
+        && ['place', 'gate', 'status'].every((key) => value[key] === undefined || typeof value[key] === 'string')
+        && (value.tone === undefined || ['neutral', 'accent', 'warning'].includes(String(value.tone)));
+}
+/** Validate the network boundary before publishing data to a card. */
+export function isAirportFeedResponse(value) {
+    if (!record(value) || value.version !== 1 || !['fresh', 'stale', 'unavailable', 'disabled'].includes(String(value.status))
+        || !finite(value.retryAfterSeconds) || value.retryAfterSeconds < 0)
+        return false;
+    if (value.status === 'disabled' || value.status === 'unavailable')
+        return value.snapshot === undefined;
+    const s = value.snapshot;
+    try {
+        if (!record(s) || !record(s.airport) || typeof s.airport.timeZone !== 'string')
+            return false;
+        new Intl.DateTimeFormat('en', { timeZone: s.airport.timeZone }).format(0);
+    }
+    catch {
+        return false;
+    }
+    return record(s) && record(s.airport)
+        && ['iata', 'name', 'city', 'timeZone'].every((key) => typeof s.airport[key] === 'string')
+        && ['fetchedAt', 'freshUntil', 'expiresAt', 'windowStart', 'windowEnd'].every((key) => finite(s[key]))
+        && Number(s.fetchedAt) <= Number(s.freshUntil) && Number(s.freshUntil) <= Number(s.expiresAt)
+        && Number(s.windowStart) < Number(s.windowEnd)
+        && Array.isArray(s.departures) && s.departures.every(movement)
+        && Array.isArray(s.arrivals) && s.arrivals.every(movement);
+}

package/domain/movement-board.d.ts

@@ -0,0 +1,21 @@
+/** All values use the study's time coordinate, in seconds (including times beyond midnight). */
+export interface MovementBoardStudy {
+    readonly time: number;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+}
+export interface MovementBoardHorizon {
+    readonly lookBehindSeconds?: number;
+    readonly lookAheadSeconds?: number;
+}
+export interface MovementBoardWindow {
+    readonly start: number;
+    readonly end: number;
+}
+/** Keep recent movements briefly, then show the next hour, clipped to the selected study. */
+export declare function movementBoardWindow(study: MovementBoardStudy, { lookBehindSeconds, lookAheadSeconds }?: MovementBoardHorizon): MovementBoardWindow | undefined;
+/** Unknown times cannot be placed in a time-windowed board. Never mutate the caller's rows. */
+export declare function movementsForBoard<T extends {
+    readonly id: string;
+    readonly time?: number;
+}>(movements: readonly T[], window: MovementBoardWindow | undefined, maxRows?: number): readonly T[];

package/domain/movement-board.js

@@ -0,0 +1,23 @@
+/** Keep recent movements briefly, then show the next hour, clipped to the selected study. */
+export function movementBoardWindow(study, { lookBehindSeconds = 600, lookAheadSeconds = 3600 } = {}) {
+    const { time, windowStart, windowEnd } = study;
+    if (![time, windowStart, windowEnd, lookBehindSeconds, lookAheadSeconds].every(Number.isFinite)
+        || windowStart > windowEnd || time < windowStart || time > windowEnd
+        || lookBehindSeconds < 0 || lookAheadSeconds < 0)
+        return undefined;
+    return {
+        start: Math.max(windowStart, time - lookBehindSeconds),
+        end: Math.min(windowEnd, time + lookAheadSeconds),
+    };
+}
+/** Unknown times cannot be placed in a time-windowed board. Never mutate the caller's rows. */
+export function movementsForBoard(movements, window, maxRows = 8) {
+    if (!window || ![window.start, window.end, maxRows].every(Number.isFinite)
+        || window.start > window.end || maxRows < 1)
+        return [];
+    return movements
+        .filter((entry) => entry.time !== undefined && Number.isFinite(entry.time)
+        && entry.time >= window.start && entry.time <= window.end)
+        .sort((first, second) => first.time - second.time || (first.id < second.id ? -1 : first.id > second.id ? 1 : 0))
+        .slice(0, Math.floor(maxRows));
+}

package/domain/network-patterns.d.ts

@@ -0,0 +1,19 @@
+import type { NetworkDayChunk, NetworkTrain, ServiceCategory } from './network.ts';
+export declare const NETWORK_PATTERN_FORMAT = "network-patterns-v1";
+export type NetworkPattern = Omit<NetworkTrain, 'id' | 'start'>;
+export interface PatternNetworkChunk {
+    readonly format: string;
+    readonly windowStart: number;
+    readonly windowEnd: number;
+    readonly patterns: readonly NetworkPattern[];
+    readonly journeys: readonly (readonly [id: string, start: number, pattern: number])[];
+}
+export interface PatternChunkOptions {
+    /** A consumer may retain a previously published wire-format tag. */
+    readonly format?: string;
+    readonly categories?: readonly ServiceCategory[];
+}
+/** Deduplicate relative schedules on disk; identities and absolute calls survive decoding. */
+export declare function encodeNetworkPatterns(chunk: NetworkDayChunk, options?: PatternChunkOptions): PatternNetworkChunk;
+export declare function validateNetworkPatterns(value: unknown, options?: PatternChunkOptions): asserts value is PatternNetworkChunk;
+export declare function decodeNetworkPatterns(value: unknown, options?: PatternChunkOptions): NetworkDayChunk;

package/domain/network-patterns.js

@@ -0,0 +1,73 @@
+export const NETWORK_PATTERN_FORMAT = 'network-patterns-v1';
+/** Deduplicate relative schedules on disk; identities and absolute calls survive decoding. */
+export function encodeNetworkPatterns(chunk, options = {}) {
+    const patterns = [], indexes = new Map();
+    const journeys = chunk.trains.map(({ id, start, ...train }) => {
+        const pattern = { ...train, end: train.end - start,
+            stops: train.stops.map(([stop, arrival, departure]) => [stop, arrival - start, departure - start]),
+        };
+        const key = JSON.stringify(pattern);
+        let index = indexes.get(key);
+        if (index === undefined) {
+            index = patterns.length;
+            indexes.set(key, index);
+            patterns.push(pattern);
+        }
+        return [id, start, index];
+    });
+    const result = { format: options.format ?? NETWORK_PATTERN_FORMAT, windowStart: chunk.windowStart,
+        windowEnd: chunk.windowEnd, patterns, journeys };
+    validateNetworkPatterns(result, options);
+    return result;
+}
+export function validateNetworkPatterns(value, options = {}) {
+    const chunk = value;
+    if (!chunk || chunk.format !== (options.format ?? NETWORK_PATTERN_FORMAT) ||
+        !Number.isFinite(chunk.windowStart) || !Number.isFinite(chunk.windowEnd) || chunk.windowEnd <= chunk.windowStart ||
+        !Array.isArray(chunk.patterns) || !Array.isArray(chunk.journeys))
+        throw new Error('Invalid network pattern chunk');
+    for (const pattern of chunk.patterns) {
+        if (!pattern || !Number.isFinite(pattern.end) || pattern.end < 0 ||
+            typeof pattern.route !== 'string' || typeof pattern.headsign !== 'string' || typeof pattern.shortName !== 'string' ||
+            typeof pattern.category !== 'string' || (options.categories && !options.categories.includes(pattern.category)) ||
+            !Array.isArray(pattern.stops) || pattern.stops.length < 2)
+            throw new Error('Invalid network pattern');
+        let previous = -Infinity;
+        for (const stop of pattern.stops) {
+            if (!Array.isArray(stop) || stop.length !== 3)
+                throw new Error('Invalid pattern stop');
+            const [index, arrival, departure] = stop;
+            if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(arrival) || !Number.isFinite(departure) ||
+                departure < arrival || arrival < previous)
+                throw new Error('Invalid pattern stop timing');
+            previous = departure;
+        }
+        if (pattern.end < previous)
+            throw new Error('Pattern ends before its final call');
+        if (pattern.pathSegments && (!Array.isArray(pattern.pathSegments) || pattern.pathSegments.length !== pattern.stops.length - 1 ||
+            pattern.pathSegments.some((index) => index !== null && (!Number.isSafeInteger(index) || index < 0))))
+            throw new Error('Invalid pattern paths');
+    }
+    const ids = new Set();
+    for (const journey of chunk.journeys) {
+        if (!Array.isArray(journey) || journey.length !== 3)
+            throw new Error('Invalid pattern journey');
+        const [id, start, index] = journey;
+        if (typeof id !== 'string' || !id || ids.has(id) || !Number.isFinite(start) || !Number.isSafeInteger(index) || index < 0 ||
+            !chunk.patterns[index] || !Number.isFinite(start + chunk.patterns[index].end) ||
+            chunk.patterns[index].stops.some((stop) => !Number.isFinite(start + stop[1]) || !Number.isFinite(start + stop[2])))
+            throw new Error('Invalid pattern journey identity or time');
+        ids.add(id);
+    }
+}
+export function decodeNetworkPatterns(value, options = {}) {
+    validateNetworkPatterns(value, options);
+    return { windowStart: value.windowStart, windowEnd: value.windowEnd,
+        trains: value.journeys.map(([id, start, index]) => {
+            const pattern = value.patterns[index];
+            return { ...pattern, id, start, end: start + pattern.end,
+                stops: pattern.stops.map(([stop, arrival, departure]) => [stop, start + arrival, start + departure]),
+            };
+        }),
+    };
+}

package/domain/network.js

@@ -69,7 +69,7 @@ export function buildStationIndex(snapshot) {
         routes: [...record.routes.values()].sort((first, second) => first.name.localeCompare(second.name, 'de-CH')),
     }));
 }
-export function positionForTrain(train, time) {
+function linearPositionForTrain(train, time) {
     if (train.realtime?.status === 'cancelled' ||
         time < train.start ||
         time > train.end ||
@@ -98,6 +98,42 @@ export function positionForTrain(train, time) {
     const last = train.stops.at(-1);
     return { fromStop: last[0], toStop: last[0], progress: 0 };
 }
+// Timetables are immutable. A replacement stop array (including realtime edits)
+// gets its own validation; old schedules can be garbage collected.
+const chronologicalSchedules = new WeakMap();
+export function positionForTrain(train, time) {
+    if (train.realtime?.status === 'cancelled' || time < train.start || time > train.end || train.stops.length < 2)
+        return;
+    const stops = train.stops;
+    let chronological = chronologicalSchedules.get(stops);
+    if (chronological === undefined) {
+        chronological = stops.every((stop, index) => Number.isFinite(stop[1]) && Number.isFinite(stop[2]) &&
+            stop[2] >= stop[1] && (index === 0 || stop[1] >= stops[index - 1][2]));
+        chronologicalSchedules.set(stops, chronological);
+    }
+    // Preserve sequential semantics for unordered observations and non-finite clocks.
+    if (!chronological || !Number.isFinite(time))
+        return linearPositionForTrain(train, time);
+    let lower = 0;
+    let upper = stops.length;
+    while (lower < upper) {
+        const middle = (lower + upper) >>> 1;
+        if (stops[middle][2] < time)
+            lower = middle + 1;
+        else
+            upper = middle;
+    }
+    const next = stops[Math.min(lower, stops.length - 1)];
+    if (lower === 0 || lower === stops.length || time > next[1]) {
+        return { fromStop: next[0], toStop: next[0], progress: 0 };
+    }
+    const previous = stops[lower - 1];
+    return {
+        fromStop: previous[0], toStop: next[0],
+        progress: Math.min(1, Math.max(0, (time - previous[2]) / Math.max(1, next[1] - previous[2]))),
+        segmentIndex: lower - 1,
+    };
+}
 export function formatServiceTime(totalSeconds) {
     const normalized = ((Math.round(totalSeconds) % 86400) + 86400) % 86400;
     const hours = Math.floor(normalized / 3600);