@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/temporal/playback.js

@@ -0,0 +1,80 @@
+import { toIso, toMs } from './tracks.js';
+export class Playback {
+    options;
+    atMs;
+    startMs;
+    endMs;
+    speed;
+    playing = false;
+    lastReal = 0;
+    generation = 0;
+    frame;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.startMs = toMs(options.range.start);
+        this.endMs = toMs(options.range.end);
+        if (!(this.endMs > this.startMs))
+            throw new Error('playback range end must be after start');
+        this.atMs = clamp(options.at ? toMs(options.at) : this.startMs, this.startMs, this.endMs);
+        this.speed = options.speed ?? 1;
+        this.now = options.now ?? (() => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+        this.frame =
+            options.frame ??
+                (typeof requestAnimationFrame === 'function' ? (cb) => void requestAnimationFrame(cb) : (cb) => void setTimeout(() => cb(this.now()), 50));
+    }
+    get time() {
+        return toIso(this.atMs);
+    }
+    get isPlaying() {
+        return this.playing;
+    }
+    get rate() {
+        return this.speed;
+    }
+    get range() {
+        return { start: toIso(this.startMs), end: toIso(this.endMs) };
+    }
+    play() {
+        if (this.playing)
+            return;
+        if (this.atMs >= this.endMs)
+            this.atMs = this.startMs; // play again from the start
+        this.playing = true;
+        this.lastReal = this.now();
+        const gen = ++this.generation;
+        const tick = (nowMs) => {
+            if (!this.playing || gen !== this.generation)
+                return;
+            const elapsed = Math.max(0, nowMs - this.lastReal);
+            this.lastReal = nowMs;
+            this.atMs = Math.min(this.endMs, this.atMs + elapsed * this.speed);
+            this.options.onTime(this.time);
+            if (this.atMs >= this.endMs) {
+                this.playing = false;
+                this.options.onEnd?.();
+                return;
+            }
+            this.frame(tick);
+        };
+        this.frame(tick);
+    }
+    pause() {
+        this.playing = false;
+        this.generation++;
+    }
+    seek(at) {
+        this.atMs = clamp(toMs(at), this.startMs, this.endMs);
+        this.lastReal = this.now();
+        this.options.onTime(this.time);
+    }
+    setSpeed(speed) {
+        if (!(speed > 0))
+            throw new Error('speed must be > 0');
+        this.speed = speed;
+    }
+    dispose() {
+        this.pause();
+    }
+}
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));

package/vendor/map-engine/temporal/tracks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Temporal model (doc 07): state of a moving object at time T, and trails over a window.
+ * Pure functions over Track data — no data access, no rendering.
+ */
+import type { Position, Track, TrackPoint, ValidationResult } from '../core/types.js';
+export declare const toMs: (iso: string) => number;
+export declare const toIso: (ms: number) => string;
+/** Validates untrusted track data; points must have valid timestamps and positions. Never throws. */
+export declare function validateTrack(value: unknown): ValidationResult;
+/** Sorted by time, duplicates (same timestamp) collapsed to the last one. */
+export declare function normalizeTrack(track: Track): Track;
+/** Bearing in degrees clockwise from north, from `a` to `b`. */
+export declare function bearing(a: Position, b: Position): number;
+export interface StateAt {
+    position: Position;
+    heading?: number;
+    /** m/s, from the data or derived from neighbouring points. */
+    speed?: number;
+    /** True after the last observation: the last known position is held (a parked object stays where it was). */
+    held?: boolean;
+}
+/**
+ * Where the object was at `ms`: linear interpolation between the surrounding points. After the last observation
+ * the last known position is held (`held: true`). Null before the first observation: it was not there yet.
+ */
+export declare function stateAt(track: Track, ms: number): StateAt | null;
+/**
+ * Positions between `fromMs` and `toMs` (inclusive), with interpolated end points so a trail ends exactly
+ * where the object is at `toMs`. Empty when the object has no observations in or around the window.
+ */
+export declare function trailBetween(track: Track, fromMs: number, toMsValue: number): Position[];
+/** Appends a newer point (live trail growth) and drops points older than `keepFromMs`. Older points are ignored. */
+export declare function appendPoint(track: Track, point: TrackPoint, keepFromMs: number): Track;

package/vendor/map-engine/temporal/tracks.js

@@ -0,0 +1,119 @@
+import { validatePosition } from '../spatial/geometry.js';
+import { distanceMeters } from '../spatial/operations.js';
+export const toMs = (iso) => Date.parse(iso);
+export const toIso = (ms) => new Date(ms).toISOString();
+/** Validates untrusted track data; points must have valid timestamps and positions. Never throws. */
+export function validateTrack(value) {
+    if (typeof value !== 'object' || value === null)
+        return { valid: false, reason: 'track is not an object' };
+    const t = value;
+    if (typeof t.objectId !== 'string' || !t.objectId)
+        return { valid: false, reason: 'track.objectId is required' };
+    if (!Array.isArray(t.points))
+        return { valid: false, reason: `track ${t.objectId}: points is not an array` };
+    for (const [i, p] of t.points.entries()) {
+        if (!p || !Number.isFinite(toMs(p.timestamp)))
+            return { valid: false, reason: `track ${t.objectId}: point ${i} has no valid timestamp` };
+        const v = validatePosition(p, `track ${t.objectId} point ${i}`);
+        if (!v.valid)
+            return v;
+    }
+    return { valid: true };
+}
+/** Sorted by time, duplicates (same timestamp) collapsed to the last one. */
+export function normalizeTrack(track) {
+    const byTime = new Map();
+    for (const p of track.points)
+        byTime.set(toMs(p.timestamp), p);
+    return { ...track, points: [...byTime.entries()].sort((a, b) => a[0] - b[0]).map(([, p]) => p) };
+}
+/** Bearing in degrees clockwise from north, from `a` to `b`. */
+export function bearing(a, b) {
+    const φ1 = (a.latitude * Math.PI) / 180;
+    const φ2 = (b.latitude * Math.PI) / 180;
+    const Δλ = ((b.longitude - a.longitude) * Math.PI) / 180;
+    const y = Math.sin(Δλ) * Math.cos(φ2);
+    const x = Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
+    return ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
+}
+/** Index of the last point at or before `ms` (binary search); -1 when `ms` is before the track. */
+function indexAtOrBefore(points, ms) {
+    let lo = 0;
+    let hi = points.length - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (toMs(points[mid].timestamp) <= ms) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return ans;
+}
+/**
+ * Where the object was at `ms`: linear interpolation between the surrounding points. After the last observation
+ * the last known position is held (`held: true`). Null before the first observation: it was not there yet.
+ */
+export function stateAt(track, ms) {
+    const pts = track.points;
+    if (!pts.length)
+        return null;
+    const i = indexAtOrBefore(pts, ms);
+    if (i < 0)
+        return null;
+    const a = pts[i];
+    const ta = toMs(a.timestamp);
+    if (i === pts.length - 1) {
+        const s = withMotion({ latitude: a.latitude, longitude: a.longitude }, a, pts[i - 1], undefined);
+        if (ms === ta)
+            return s;
+        const { speed: _speed, ...rest } = s; // not moving while held
+        return { ...rest, held: true };
+    }
+    const b = pts[i + 1];
+    const tb = toMs(b.timestamp);
+    const f = tb > ta ? (ms - ta) / (tb - ta) : 0;
+    const position = { latitude: a.latitude + (b.latitude - a.latitude) * f, longitude: a.longitude + (b.longitude - a.longitude) * f };
+    const heading = a.heading !== undefined && b.heading !== undefined ? interpolateAngle(a.heading, b.heading, f) : bearingOrUndefined(a, b);
+    const speed = a.speed !== undefined && b.speed !== undefined ? a.speed + (b.speed - a.speed) * f : tb > ta ? distanceMeters(a, b) / ((tb - ta) / 1000) : undefined;
+    return { position, ...(heading !== undefined ? { heading } : {}), ...(speed !== undefined ? { speed } : {}) };
+}
+function withMotion(position, p, prev, next) {
+    const heading = p.heading ?? (prev ? bearingOrUndefined(prev, p) : next ? bearingOrUndefined(p, next) : undefined);
+    return { position, ...(heading !== undefined ? { heading } : {}), ...(p.speed !== undefined ? { speed: p.speed } : {}) };
+}
+function bearingOrUndefined(a, b) {
+    return a.latitude === b.latitude && a.longitude === b.longitude ? undefined : bearing(a, b);
+}
+function interpolateAngle(a, b, f) {
+    const d = ((b - a + 540) % 360) - 180;
+    return (a + d * f + 360) % 360;
+}
+/**
+ * Positions between `fromMs` and `toMs` (inclusive), with interpolated end points so a trail ends exactly
+ * where the object is at `toMs`. Empty when the object has no observations in or around the window.
+ */
+export function trailBetween(track, fromMs, toMsValue) {
+    const out = [];
+    const start = stateAt(track, fromMs);
+    if (start)
+        out.push(start.position);
+    for (const p of track.points) {
+        const t = toMs(p.timestamp);
+        if (t > fromMs && t < toMsValue)
+            out.push({ latitude: p.latitude, longitude: p.longitude });
+    }
+    const end = stateAt(track, toMsValue);
+    if (end)
+        out.push(end.position);
+    // Collapse repeated positions (held or stationary), so a parked object has no zero-length trail.
+    return out.filter((p, i) => i === 0 || p.latitude !== out[i - 1].latitude || p.longitude !== out[i - 1].longitude);
+}
+/** Appends a newer point (live trail growth) and drops points older than `keepFromMs`. Older points are ignored. */
+export function appendPoint(track, point, keepFromMs) {
+    const last = track.points[track.points.length - 1];
+    const points = last && toMs(point.timestamp) <= toMs(last.timestamp) ? track.points : [...track.points, point];
+    return { ...track, points: points.filter((p) => toMs(p.timestamp) >= keepFromMs) };
+}

package/vendor/map-engine/testing/annotation-store.d.ts

@@ -0,0 +1,24 @@
+import type { Annotation, Unsubscribe } from '../core/types.js';
+import type { AnnotationProvider, AuthAware, AuthContext } from '../data/contracts.js';
+/** In-memory annotation store for tests and demos; `others()` plays a second user making changes. */
+export declare class MemoryAnnotationStore implements AnnotationProvider, AuthAware {
+    private readonly items;
+    private readonly listeners;
+    readonly saved: Annotation[];
+    auth: AuthContext | null;
+    failNextSave: Error | null;
+    constructor(initial?: Annotation[]);
+    setAuth(auth: AuthContext | null): void;
+    list(): Promise<Annotation[]>;
+    save(a: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    subscribe(onChange: (c: {
+        upserted?: Annotation[];
+        removed?: string[];
+    }) => void): Unsubscribe;
+    /** Another user's change arriving through the stream. */
+    others(change: {
+        upserted?: Annotation[];
+        removed?: string[];
+    }): void;
+}

package/vendor/map-engine/testing/annotation-store.js

@@ -0,0 +1,43 @@
+/** In-memory annotation store for tests and demos; `others()` plays a second user making changes. */
+export class MemoryAnnotationStore {
+    items = new Map();
+    listeners = new Set();
+    saved = [];
+    auth = null;
+    failNextSave = null;
+    constructor(initial = []) {
+        for (const a of initial)
+            this.items.set(a.id, structuredClone(a));
+    }
+    setAuth(auth) {
+        this.auth = auth;
+    }
+    async list() {
+        return [...this.items.values()].map((a) => structuredClone(a));
+    }
+    async save(a) {
+        if (this.failNextSave) {
+            const e = this.failNextSave;
+            this.failNextSave = null;
+            throw e;
+        }
+        this.items.set(a.id, structuredClone(a));
+        this.saved.push(structuredClone(a));
+    }
+    async remove(id) {
+        this.items.delete(id);
+    }
+    subscribe(onChange) {
+        this.listeners.add(onChange);
+        return () => this.listeners.delete(onChange);
+    }
+    /** Another user's change arriving through the stream. */
+    others(change) {
+        for (const a of change.upserted ?? [])
+            this.items.set(a.id, structuredClone(a));
+        for (const id of change.removed ?? [])
+            this.items.delete(id);
+        for (const l of this.listeners)
+            l(structuredClone(change));
+    }
+}

package/vendor/map-engine/testing/contracts.d.ts

@@ -0,0 +1,41 @@
+import type { BoundingBox, TimeRange } from '../core/types.js';
+import { type SpatialDataProvider } from '../data/contracts.js';
+import type { Renderer } from '../render/renderer.js';
+import type { SpatialIndex } from '../spatial/spatial-index.js';
+export interface ContractCheck {
+    name: string;
+    run: () => Promise<void>;
+}
+export declare class ContractViolation extends Error {
+    readonly name = "ContractViolation";
+}
+export interface ProviderContractOptions {
+    /** A fresh provider per check. It may also implement RealtimeProvider, TrackProvider and DatasetCatalog. */
+    create: () => SpatialDataProvider;
+    /** One object the provider is known to hold, and (optionally) its type and one of its property values. */
+    sample: {
+        objectId: string;
+        ontologyType?: string;
+        property?: {
+            name: string;
+            value: unknown;
+        };
+    };
+    /** Bounds that do NOT contain the sample — checked only for providers that claim spatial query support. */
+    outside?: BoundingBox;
+    /** A time range during which the sample has history — checked only for providers with getTracks. */
+    history?: TimeRange;
+}
+/**
+ * The SpatialDataProvider contract (doc §26, ADR-005). Providers may return MORE than a query asks for (the runtime
+ * re-checks every object), but never less: a matching object must not be left out.
+ */
+export declare function providerContract(o: ProviderContractOptions): ContractCheck[];
+export interface RendererContractOptions {
+    create: () => Renderer;
+    container: () => HTMLElement;
+}
+/** The Renderer contract (doc §22, §65): bidirectional, incremental, and fully released by destroy(). */
+export declare function rendererContract(o: RendererContractOptions): ContractCheck[];
+/** The SpatialIndex contract (doc §11): any index (RBush today, others later) answers like a full scan. */
+export declare function spatialIndexContract(create: () => SpatialIndex): ContractCheck[];