@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/core/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public contracts of the Map Engine.
+ *
+ * Coordinates are semantic: `{ latitude, longitude }` in WGS84 (EPSG:4326).
+ * GeoJSON's `[longitude, latitude]` order exists only in `spatial/geojson.ts`.
+ */
+export {};

package/vendor/map-engine/data/annotations.d.ts

@@ -0,0 +1,3 @@
+import type { AnnotationProvider, RealtimeProvider, WritableSpatialProvider } from './contracts.js';
+/** An AnnotationProvider over a writable provider: each annotation is an object of `ontologyType`. */
+export declare function annotationsOnProvider(provider: WritableSpatialProvider & Partial<RealtimeProvider>, ontologyType: string): AnnotationProvider;

package/vendor/map-engine/data/annotations.js

@@ -0,0 +1,63 @@
+const KINDS = ['point', 'line', 'polygon', 'rectangle', 'circle', 'measurement', 'label', 'note'];
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const json = (v) => {
+    if (typeof v !== 'string' || !v)
+        return undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** An AnnotationProvider over a writable provider: each annotation is an object of `ontologyType`. */
+export function annotationsOnProvider(provider, ontologyType) {
+    const toAnnotation = (o) => {
+        const p = o.properties ?? {};
+        const kind = KINDS.includes(p.kind) ? p.kind : 'note';
+        const style = json(p.style);
+        const metadata = json(p.metadata);
+        return {
+            id: o.objectId,
+            kind,
+            geometry: o.geometry,
+            ...(str(p.label) ? { label: str(p.label) } : {}),
+            ...(str(p.note) ? { note: str(p.note) } : {}),
+            ...(str(p.author) ? { author: str(p.author) } : {}),
+            ...(str(p.createdAt) ? { createdAt: str(p.createdAt) } : {}),
+            ...(str(p.updatedAt) ? { updatedAt: str(p.updatedAt) } : {}),
+            ...(style ? { style } : {}),
+            ...(metadata ? { metadata } : {}),
+        };
+    };
+    const store = {
+        async list(signal) {
+            return (await provider.query({ ontologyType }, signal)).map(toAnnotation);
+        },
+        async save(a) {
+            await provider.upsert({
+                objectId: a.id,
+                geometry: a.geometry,
+                properties: {
+                    kind: a.kind,
+                    label: a.label ?? '',
+                    note: a.note ?? '',
+                    ...(a.author ? { author: a.author } : {}),
+                    ...(a.createdAt ? { createdAt: a.createdAt } : {}),
+                    ...(a.updatedAt ? { updatedAt: a.updatedAt } : {}),
+                    // Nested values travel as JSON text: providers keep flat properties.
+                    ...(a.style ? { style: JSON.stringify(a.style) } : {}),
+                    ...(a.metadata ? { metadata: JSON.stringify(a.metadata) } : {}),
+                },
+                ...(a.updatedAt || a.createdAt ? { observedAt: a.updatedAt ?? a.createdAt } : {}),
+            }, { ontologyType });
+        },
+        async remove(id) {
+            await provider.remove(id);
+        },
+    };
+    if (typeof provider.subscribe === 'function') {
+        store.subscribe = (onChange) => provider.subscribe({ ontologyType }, (patch) => onChange({ ...(patch.upserted ? { upserted: patch.upserted.map(toAnnotation) } : {}), ...(patch.removed ? { removed: patch.removed } : {}) }));
+    }
+    return store;
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Data contracts (ADR-005, ADR-018). The engine asks for capabilities, never for a database.
+ *
+ * Security (Decision 8): providers return data that is ALREADY authorized for the current user.
+ * The browser engine is not a security boundary; anything it filters is visibility, not access control.
+ */
+import type { AltitudeReference, Annotation, BoundingBox, Geometry, GeometryFamily, Position, SpatialObject, SpatialQuery, TimeRange, Track, Unsubscribe } from '../core/types.js';
+export interface DataCapabilities {
+    supportsSpatialQuery: boolean;
+    supportsHistoricalQuery: boolean;
+    supportsRealtime: boolean;
+    supportsWrite: boolean;
+}
+export interface SpatialDataProvider {
+    readonly capabilities: DataCapabilities;
+    /** Objects matching every field of the query. Must honour `signal` (reject with an AbortError). */
+    query(query: SpatialQuery, signal?: AbortSignal): Promise<SpatialObject[]>;
+    getCurrentState(objectIds: string[], signal?: AbortSignal): Promise<SpatialObject[]>;
+}
+/** A provider that also accepts writes (used by io-maps authoring and by mocks). Read-only providers stay read-only. */
+export interface WritableSpatialProvider extends SpatialDataProvider {
+    upsert(object: SpatialObject, meta?: {
+        ontologyType?: string;
+    }): Promise<void>;
+    remove(objectId: string): Promise<void>;
+}
+export declare function isWritableProvider(p: SpatialDataProvider): p is WritableSpatialProvider;
+/** Incremental change from a realtime source. */
+export interface SpatialPatch {
+    upserted?: SpatialObject[];
+    removed?: string[];
+}
+/** Snapshot + stream (ADR-015): callers take a snapshot with `query`, then apply these patches. No RxJS (Decision 12). */
+export interface RealtimeProvider {
+    subscribe(query: SpatialQuery, onPatch: (patch: SpatialPatch) => void, onError?: (error: Error) => void): Unsubscribe;
+}
+/** How an Ontology type projects into space. Resolved by the Ontology side; the engine only consumes it. */
+export interface SpatialBinding {
+    ontologyType: string;
+    geometryProperty: string;
+    geometryType: Geometry['type'];
+    capabilities: DataCapabilities;
+}
+export interface MissingCapability {
+    ontologyType: string;
+    missing: 'spatial';
+    reason: string;
+}
+export interface OntologySpatialResolver {
+    resolve(ontologyType: string, signal?: AbortSignal): Promise<SpatialBinding | MissingCapability>;
+}
+export declare function isMissingCapability(v: SpatialBinding | MissingCapability): v is MissingCapability;
+/**
+ * Historical positions (doc 07, doc 11 TrackProvider). Returns tracks of objects matching the query whose
+ * positions fall inside `query.bounds` during `range` — including objects no longer present now.
+ */
+export interface TrackProvider {
+    getTracks(query: SpatialQuery, range: TimeRange, signal?: AbortSignal): Promise<Track[]>;
+}
+/** What a property holds across a dataset, so an application can build pickers and rules without hard-coding names. */
+export interface PropertySchema {
+    name: string;
+    type: 'number' | 'string' | 'boolean' | 'mixed';
+    /** Objects that have a non-null value. */
+    count: number;
+    /** Distinct values (all types). */
+    distinct: number;
+    min?: number;
+    max?: number;
+    /** Up to a handful of distinct values, most common first (strings and booleans; small numeric sets too). */
+    values?: Array<string | number | boolean>;
+}
+/** One kind of spatial object a provider can serve: its type, geometry and property schema. */
+export interface DatasetInfo {
+    ontologyType: string;
+    label?: string;
+    /** Where it comes from, for display ("Plant telemetry", "Imported file"). */
+    source?: string;
+    /** The single geometry type, or 'Mixed' when objects differ (e.g. Polygon and MultiPolygon). */
+    geometryType: Geometry['type'] | 'Mixed';
+    /** Point, line or area — what kind of layer can draw it. 'mixed' only when the families differ. */
+    geometryFamily: GeometryFamily | 'mixed';
+    count: number;
+    properties: PropertySchema[];
+    bounds?: BoundingBox;
+    /** Position history is available (replay, trails). */
+    hasHistory: boolean;
+    /** Changes stream live. */
+    live: boolean;
+    /** Units of properties that have one (e.g. { speed: 'm/s' }), for display. */
+    units?: Record<string, string>;
+    /** When the source last had data for this dataset (epoch ms) — lets an app tell stale data from live data. */
+    lastDataAt?: number;
+    /** Positions carry `altitude`, measured from this reference — so an app can draw them at height correctly. */
+    altitude?: {
+        reference: AltitudeReference;
+    };
+}
+/**
+ * Ground heights (doc 3D plan, ADR-028): metres above mean sea level under each position, null where unknown.
+ * A terrain service, or the renderer's own terrain when it has one.
+ */
+export interface ElevationProvider {
+    sample(positions: Position[], signal?: AbortSignal): Promise<Array<number | null>>;
+}
+/** Optional: providers that can describe what they hold. Applications use it to discover data instead of hard-coding it. */
+export interface DatasetCatalog {
+    listDatasets(signal?: AbortSignal): Promise<DatasetInfo[]>;
+}
+export declare function hasCatalog(p: object): p is DatasetCatalog;
+/** A relation between two objects (UNS neighbours, lineage…). The engine draws it; it never infers one. */
+export interface Link {
+    id: string;
+    fromId: string;
+    toId: string;
+    type?: string;
+    properties?: Record<string, unknown>;
+}
+/** Links touching any of `objectIds`, of the given types (all when omitted). Authorized data only. */
+export interface LinkProvider {
+    getLinks(objectIds: string[], types: string[] | undefined, signal?: AbortSignal): Promise<Link[]>;
+}
+/**
+ * One entry of the event journal (doc 29 §7): what an object was from `at` on. `object` is its full state then
+ * (or, for `removed`, absent). Sources may add their own `kind`s; the engine only needs created/updated/removed/
+ * snapshot to rebuild the map at a time.
+ */
+export interface JournalEntry {
+    /** ISO 8601. */
+    at: string;
+    objectId: string;
+    kind: 'snapshot' | 'created' | 'updated' | 'removed' | (string & {});
+    object?: SpatialObject;
+    /** What changed, for display (e.g. { status: ['ok', 'alarm'] }). */
+    changes?: Record<string, [unknown, unknown]>;
+    source?: string;
+}
+/**
+ * The event journal behind replay of whole objects (doc 29 §7–8, doc 28 G5). For a query and a range it returns,
+ * per object, its state as of `range.start` (kind `snapshot`) followed by every change inside the range, oldest
+ * first. The engine rebuilds the map at any time in the range from that; it never stores history itself.
+ */
+export interface JournalProvider {
+    getJournal(query: SpatialQuery, range: TimeRange, signal?: AbortSignal): Promise<JournalEntry[]>;
+}
+/** Where annotations live (doc 28 G10): shared with others when the provider stores them, e.g. as UNS nodes. */
+export interface AnnotationProvider {
+    list(signal?: AbortSignal): Promise<Annotation[]>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    /** Changes made elsewhere (other users), if the store can stream them. */
+    subscribe?(onChange: (change: {
+        upserted?: Annotation[];
+        removed?: string[];
+    }) => void): Unsubscribe;
+}
+/**
+ * Who is looking (doc 28 G13). The engine never decides access; it hands this to every provider that accepts it
+ * (`setAuth`), reloads, and shows what comes back: missing objects are absent, removed properties are listed in
+ * `object.redacted`, and a refused layer (an ACCESS_DENIED error) gets the status 'denied'.
+ */
+export interface AuthContext {
+    userId?: string;
+    /** Opaque to the engine; providers send it to their server. */
+    token?: string;
+    roles?: string[];
+    attributes?: Record<string, unknown>;
+}
+export interface AuthAware {
+    setAuth(auth: AuthContext | null): void;
+}
+export declare function isAuthAware(p: unknown): p is AuthAware;

package/vendor/map-engine/data/contracts.js

@@ -0,0 +1,12 @@
+export function isWritableProvider(p) {
+    return p.capabilities.supportsWrite && typeof p.upsert === 'function';
+}
+export function isMissingCapability(v) {
+    return v.missing !== undefined;
+}
+export function hasCatalog(p) {
+    return typeof p.listDatasets === 'function';
+}
+export function isAuthAware(p) {
+    return typeof p === 'object' && p !== null && typeof p.setAuth === 'function';
+}

package/vendor/map-engine/data/index.d.ts

@@ -0,0 +1,4 @@
+export { hasCatalog, isAuthAware, isMissingCapability, isWritableProvider } from './contracts.js';
+export { annotationsOnProvider } from './annotations.js';
+export { describeProperties } from './schema.js';
+export type { AnnotationProvider, AuthAware, AuthContext, JournalEntry, JournalProvider, Link, LinkProvider, DataCapabilities, DatasetCatalog, DatasetInfo, ElevationProvider, MissingCapability, OntologySpatialResolver, PropertySchema, RealtimeProvider, SpatialBinding, SpatialDataProvider, SpatialPatch, TrackProvider, WritableSpatialProvider, } from './contracts.js';

package/vendor/map-engine/data/index.js

@@ -0,0 +1,3 @@
+export { hasCatalog, isAuthAware, isMissingCapability, isWritableProvider } from './contracts.js';
+export { annotationsOnProvider } from './annotations.js';
+export { describeProperties } from './schema.js';

package/vendor/map-engine/data/schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Property schema inference: what each property holds across a set of objects. Pure; used by providers that
+ * describe their datasets and by applications for imported data.
+ */
+import type { SpatialObject } from '../core/types.js';
+import type { PropertySchema } from './contracts.js';
+export declare function describeProperties(objects: SpatialObject[], maxValues?: number): PropertySchema[];

package/vendor/map-engine/data/schema.js

@@ -0,0 +1,40 @@
+export function describeProperties(objects, maxValues = 12) {
+    const stats = new Map();
+    for (const o of objects) {
+        for (const [name, v] of Object.entries(o.properties ?? {})) {
+            if (v === null || v === undefined || v === '')
+                continue;
+            let s = stats.get(name);
+            if (!s)
+                stats.set(name, (s = { types: new Set(), counts: new Map(), count: 0, min: Infinity, max: -Infinity }));
+            s.count++;
+            const t = typeof v;
+            if (t === 'number' && Number.isFinite(v)) {
+                s.types.add('number');
+                s.min = Math.min(s.min, v);
+                s.max = Math.max(s.max, v);
+            }
+            else if (t === 'string' || t === 'boolean')
+                s.types.add(t);
+            else {
+                s.types.add('mixed');
+                continue;
+            }
+            s.counts.set(v, (s.counts.get(v) ?? 0) + 1);
+        }
+    }
+    return [...stats.entries()]
+        .map(([name, s]) => {
+        const type = (s.types.size === 1 ? [...s.types][0] : 'mixed');
+        const out = { name, type, count: s.count, distinct: s.counts.size };
+        if (type === 'number') {
+            out.min = s.min;
+            out.max = s.max;
+        }
+        if (type !== 'number' || s.counts.size <= maxValues) {
+            out.values = [...s.counts.entries()].sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0]))).slice(0, maxValues).map(([v]) => v);
+        }
+        return out;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

package/vendor/map-engine/geofence/evaluator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Geofence evaluation (doc 15): geometry + rule + object + state transition → generic spatial events.
+ * Pure and stateful per evaluator; no data access, no rendering, no domain events.
+ */
+import type { Geofence, GeofenceEvent, Position, SpatialObject, ValidationResult } from '../core/types.js';
+export interface Reading {
+    objectId: string;
+    position: Position;
+    /** ISO 8601 observation time. */
+    timestamp: string;
+    layerId?: string;
+    properties?: Record<string, unknown>;
+}
+export declare function validateGeofence(value: unknown): ValidationResult;
+export declare function watches(g: Geofence, r: Reading): boolean;
+export declare class GeofenceEvaluator {
+    private fences;
+    private readonly state;
+    constructor(geofences?: Geofence[]);
+    /** Replaces the geofences. State is kept for unchanged ones and dropped for removed or changed ones. */
+    setGeofences(geofences: Geofence[]): void;
+    geofences(): Geofence[];
+    /**
+     * One reading → zero or more events. The first reading for an object sets its state silently (no "enter"
+     * storm when a map opens). Readings older than the last one for that object are ignored.
+     */
+    observe(r: Reading): GeofenceEvent[];
+    /** Objects currently inside each geofence (settled state). */
+    occupancy(): Record<string, string[]>;
+    reset(): void;
+    /** Inside test with hysteresis: once inside, an object leaves only when farther than the margin outside. */
+    private isInside;
+}
+/** Readings from point objects (e.g. a layer's current data). */
+export declare function readingsFrom(objects: SpatialObject[], layerId: string, fallbackTimestamp: string): Reading[];

package/vendor/map-engine/geofence/evaluator.js

@@ -0,0 +1,172 @@
+import { deepEqual } from '../core/equal.js';
+import { validateGeometry } from '../spatial/geometry.js';
+import { distanceToGeometryMeters, within } from '../spatial/operations.js';
+import { matchesCondition, validateConditions } from '../spatial/query.js';
+export function validateGeofence(value) {
+    if (typeof value !== 'object' || value === null)
+        return { valid: false, reason: 'geofence is not an object' };
+    const g = value;
+    if (typeof g.id !== 'string' || !g.id)
+        return { valid: false, reason: 'geofence.id is required' };
+    if (!g.geometry || !['Polygon', 'MultiPolygon', 'Circle'].includes(g.geometry.type))
+        return { valid: false, reason: `geofence ${g.id}: geometry must be an area (Polygon, MultiPolygon or Circle)` };
+    const v = validateGeometry(g.geometry);
+    if (!v.valid)
+        return { valid: false, reason: `geofence ${g.id}: ${v.reason}` };
+    if (typeof g.enabled !== 'boolean')
+        return { valid: false, reason: `geofence ${g.id}: enabled must be a boolean` };
+    if (g.hysteresisMeters !== undefined && !(g.hysteresisMeters >= 0))
+        return { valid: false, reason: `geofence ${g.id}: hysteresisMeters must be >= 0` };
+    if (g.debounceSamples !== undefined && !(Number.isInteger(g.debounceSamples) && g.debounceSamples >= 1))
+        return { valid: false, reason: `geofence ${g.id}: debounceSamples must be a whole number >= 1` };
+    if (g.dwellSeconds !== undefined && !(g.dwellSeconds > 0))
+        return { valid: false, reason: `geofence ${g.id}: dwellSeconds must be > 0` };
+    for (const k of ['minAltitude', 'maxAltitude']) {
+        if (g[k] !== undefined && !(typeof g[k] === 'number' && Number.isFinite(g[k])))
+            return { valid: false, reason: `geofence ${g.id}: ${k} must be a number of metres` };
+    }
+    if (g.minAltitude !== undefined && g.maxAltitude !== undefined && !(g.minAltitude < g.maxAltitude))
+        return { valid: false, reason: `geofence ${g.id}: minAltitude must be below maxAltitude` };
+    if (g.watch?.where !== undefined) {
+        const w = validateConditions(g.watch.where, `geofence ${g.id}: watch.where`);
+        if (!w.valid)
+            return w;
+    }
+    return { valid: true };
+}
+export function watches(g, r) {
+    const w = g.watch;
+    if (!w)
+        return true;
+    if (w.layerIds && (!r.layerId || !w.layerIds.includes(r.layerId)))
+        return false;
+    if (w.objectIds && !w.objectIds.includes(r.objectId))
+        return false;
+    if (w.filter && !Object.entries(w.filter).every(([k, v]) => deepEqual(r.properties?.[k], v)))
+        return false;
+    if (w.where && !w.where.every((c) => matchesCondition(r.properties?.[c.property], c)))
+        return false;
+    return true;
+}
+export class GeofenceEvaluator {
+    fences = new Map();
+    state = new Map();
+    constructor(geofences = []) {
+        this.setGeofences(geofences);
+    }
+    /** Replaces the geofences. State is kept for unchanged ones and dropped for removed or changed ones. */
+    setGeofences(geofences) {
+        const next = new Map(geofences.map((g) => [g.id, structuredClone(g)]));
+        for (const key of [...this.state.keys()]) {
+            const id = key.slice(0, key.indexOf('\u0000'));
+            const before = this.fences.get(id);
+            const after = next.get(id);
+            if (!after || !before || !deepEqual(before.geometry, after.geometry) || before.hysteresisMeters !== after.hysteresisMeters || before.minAltitude !== after.minAltitude || before.maxAltitude !== after.maxAltitude)
+                this.state.delete(key);
+        }
+        this.fences = next;
+    }
+    geofences() {
+        return [...this.fences.values()].map((g) => structuredClone(g));
+    }
+    /**
+     * One reading → zero or more events. The first reading for an object sets its state silently (no "enter"
+     * storm when a map opens). Readings older than the last one for that object are ignored.
+     */
+    observe(r) {
+        const ms = Date.parse(r.timestamp);
+        if (!Number.isFinite(ms))
+            return [];
+        const events = [];
+        for (const g of this.fences.values()) {
+            if (!g.enabled || !watches(g, r))
+                continue;
+            const key = `${g.id}\u0000${r.objectId}`;
+            let s = this.state.get(key);
+            if (!s) {
+                s = { inside: undefined, pending: undefined, pendingCount: 0, enteredAtMs: undefined, dwellEmitted: false, lastMs: -Infinity };
+                this.state.set(key, s);
+            }
+            if (ms < s.lastMs)
+                continue; // out of order: the newer state already counted
+            s.lastMs = ms;
+            const raw = this.isInside(g, r.position, s.inside === true);
+            if (s.inside === undefined) {
+                s.inside = raw;
+                s.enteredAtMs = raw ? ms : undefined;
+                continue;
+            }
+            if (raw !== s.inside) {
+                s.pendingCount = s.pending === raw ? s.pendingCount + 1 : 1;
+                s.pending = raw;
+                if (s.pendingCount >= (g.debounceSamples ?? 1)) {
+                    s.inside = raw;
+                    s.pending = undefined;
+                    s.pendingCount = 0;
+                    s.enteredAtMs = raw ? ms : undefined;
+                    s.dwellEmitted = false;
+                    events.push({ geofenceId: g.id, objectId: r.objectId, type: raw ? 'enter' : 'exit', timestamp: r.timestamp, position: r.position });
+                }
+            }
+            else {
+                s.pending = undefined;
+                s.pendingCount = 0;
+            }
+            if (s.inside && g.dwellSeconds !== undefined && !s.dwellEmitted && s.enteredAtMs !== undefined && ms - s.enteredAtMs >= g.dwellSeconds * 1000) {
+                s.dwellEmitted = true;
+                events.push({ geofenceId: g.id, objectId: r.objectId, type: 'dwell', timestamp: r.timestamp, position: r.position });
+            }
+        }
+        return events;
+    }
+    /** Objects currently inside each geofence (settled state). */
+    occupancy() {
+        const out = {};
+        for (const g of this.fences.values())
+            out[g.id] = [];
+        for (const [key, s] of this.state) {
+            if (!s.inside)
+                continue;
+            const sep = key.indexOf('\u0000');
+            const id = key.slice(0, sep);
+            if (out[id])
+                out[id].push(key.slice(sep + 1));
+        }
+        for (const id of Object.keys(out))
+            out[id].sort();
+        return out;
+    }
+    reset() {
+        this.state.clear();
+    }
+    /** Inside test with hysteresis: once inside, an object leaves only when farther than the margin outside. */
+    isInside(g, p, wasInside) {
+        const margin = g.hysteresisMeters ?? 0;
+        // A volume: the altitude band first (cheap), with the same exit margin vertically.
+        if (g.minAltitude !== undefined || g.maxAltitude !== undefined) {
+            if (p.altitude === undefined)
+                return false;
+            const slack = wasInside ? margin : 0;
+            if (g.minAltitude !== undefined && p.altitude < g.minAltitude - slack)
+                return false;
+            if (g.maxAltitude !== undefined && p.altitude > g.maxAltitude + slack)
+                return false;
+        }
+        const point = { type: 'Point', coordinates: p };
+        if (within(point, g.geometry))
+            return true;
+        return wasInside && margin > 0 && distanceToGeometryMeters(p, g.geometry) <= margin;
+    }
+}
+/** Readings from point objects (e.g. a layer's current data). */
+export function readingsFrom(objects, layerId, fallbackTimestamp) {
+    return objects
+        .filter((o) => o.geometry.type === 'Point')
+        .map((o) => ({
+        objectId: o.objectId,
+        position: o.geometry.coordinates,
+        timestamp: o.observedAt ?? fallbackTimestamp,
+        layerId,
+        ...(o.properties ? { properties: o.properties } : {}),
+    }));
+}

package/vendor/map-engine/geofence/history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Geofence events over history (doc 15: "historical/replay evaluation must use the state at the relevant time").
+ * Merges every track's readings in time order and runs a fresh evaluator over them.
+ */
+import type { Geofence, GeofenceEvent, Track } from '../core/types.js';
+export declare function evaluateTracks(geofences: Geofence[], tracks: Array<{
+    track: Track;
+    layerId?: string;
+}>): GeofenceEvent[];

package/vendor/map-engine/geofence/history.js

@@ -0,0 +1,19 @@
+import { GeofenceEvaluator } from './evaluator.js';
+export function evaluateTracks(geofences, tracks) {
+    const readings = [];
+    for (const { track, layerId } of tracks) {
+        for (const p of track.points) {
+            readings.push({
+                objectId: track.objectId,
+                position: { latitude: p.latitude, longitude: p.longitude },
+                timestamp: p.timestamp,
+                ms: Date.parse(p.timestamp),
+                ...(layerId ? { layerId } : {}),
+                ...(track.properties ? { properties: track.properties } : {}),
+            });
+        }
+    }
+    readings.sort((a, b) => a.ms - b.ms || a.objectId.localeCompare(b.objectId));
+    const evaluator = new GeofenceEvaluator(geofences);
+    return readings.flatMap((r) => evaluator.observe(r));
+}

package/vendor/map-engine/geofence/index.d.ts

@@ -0,0 +1,2 @@
+export { GeofenceEvaluator, readingsFrom, validateGeofence, watches, type Reading } from './evaluator.js';
+export { evaluateTracks } from './history.js';

package/vendor/map-engine/geofence/index.js

@@ -0,0 +1,2 @@
+export { GeofenceEvaluator, readingsFrom, validateGeofence, watches } from './evaluator.js';
+export { evaluateTracks } from './history.js';

package/vendor/map-engine/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @faclon-labs/map-engine — public API.
+ *
+ * Entry points:
+ *   "."          runtime, contracts, spatial API (this file)
+ *   "./testing"  mock provider, test renderer, fixtures
+ *   "./maplibre" (Phase 1B) MapLibre renderer adapter
+ *   "./react"    (Phase 1C) React bindings
+ */
+export type * from './core/types.js';
+export { MapEngineError, type MapEngineErrorCode, type MapEngineErrorSource } from './core/errors.js';
+export { COMMAND_TYPES, COMMAND_VERSION, commandProblem, type CommandResult, type MapCommand, type MapCommandType } from './core/commands.js';
+export { AGE, ALTERNATIVES, CONFIDENCE, ageOf, isValidAt, presentObject, scaled, scaleValue, type AgeState } from './present/index.js';
+export { decorationObjects, decorationOwner, footprintOf, formatDistance } from './present/index.js';
+export { createPostMessageBridge, connectToMap, mapWebMcpTools, type PostMessageBridgeOptions, type WebMcpTool } from './commands/index.js';
+export { type Measurement } from './spatial/index.js';
+export { spatial, RBushSpatialIndex, type SpatialIndex, matchesCondition, matchesQuery, rankByRelation, validateConditions, judgeSight, pathSamples, type SightResult, type SightProfilePoint, objectsFromGeoJSON, objectsFromRows, guessCoordinateColumns, type ImportResult } from './spatial/index.js';
+export { computeBounds, zoomToFit, validateViewport, MAX_ZOOM, MIN_ZOOM } from './viewport/index.js';
+export { validateLayer } from './layers/index.js';
+export { annotationsOnProvider, describeProperties, hasCatalog, isAuthAware, isMissingCapability, isWritableProvider } from './data/index.js';
+export type { AnnotationProvider, AuthAware, AuthContext, JournalEntry, JournalProvider, Link, LinkProvider, DataCapabilities, DatasetCatalog, DatasetInfo, ElevationProvider, PropertySchema, MissingCapability, OntologySpatialResolver, RealtimeProvider, SpatialBinding, SpatialDataProvider, SpatialPatch, TrackProvider, WritableSpatialProvider, } from './data/index.js';
+export { appendPoint, bearing, groupJournal, journalStateAt, normalizeTrack, Playback, stateAt, trailBetween, validateTrack, type PlaybackOptions, type StateAt } from './temporal/index.js';
+export type { MapClickEvent, PickEvent, Renderer, RendererCapabilities, RendererOptions } from './render/index.js';
+export { createMapRuntime } from './runtime/index.js';
+export { offlineViolations, isLocalUrl } from './runtime/index.js';
+export type { DrawingState, DrawKind, FlyToOptions, LayerFilter, LineOfSightOptions, MapRuntime, MapRuntimeDeps, MapRuntimeEvents, MapRuntimeOptions, ObjectInspection, ResolvedReference, RuntimeState } from './runtime/index.js';
+export { GeofenceEvaluator, evaluateTracks, validateGeofence } from './geofence/index.js';

package/vendor/map-engine/index.js

@@ -0,0 +1,14 @@
+export { MapEngineError } from './core/errors.js';
+export { COMMAND_TYPES, COMMAND_VERSION, commandProblem } from './core/commands.js';
+export { AGE, ALTERNATIVES, CONFIDENCE, ageOf, isValidAt, presentObject, scaled, scaleValue } from './present/index.js';
+export { decorationObjects, decorationOwner, footprintOf, formatDistance } from './present/index.js';
+export { createPostMessageBridge, connectToMap, mapWebMcpTools } from './commands/index.js';
+export {} from './spatial/index.js';
+export { spatial, RBushSpatialIndex, matchesCondition, matchesQuery, rankByRelation, validateConditions, judgeSight, pathSamples, objectsFromGeoJSON, objectsFromRows, guessCoordinateColumns } from './spatial/index.js';
+export { computeBounds, zoomToFit, validateViewport, MAX_ZOOM, MIN_ZOOM } from './viewport/index.js';
+export { validateLayer } from './layers/index.js';
+export { annotationsOnProvider, describeProperties, hasCatalog, isAuthAware, isMissingCapability, isWritableProvider } from './data/index.js';
+export { appendPoint, bearing, groupJournal, journalStateAt, normalizeTrack, Playback, stateAt, trailBetween, validateTrack } from './temporal/index.js';
+export { createMapRuntime } from './runtime/index.js';
+export { offlineViolations, isLocalUrl } from './runtime/index.js';
+export { GeofenceEvaluator, evaluateTracks, validateGeofence } from './geofence/index.js';

package/vendor/map-engine/layers/index.d.ts

@@ -0,0 +1 @@
+export { drawable, GEOMETRY_FOR, SOURCE_GEOMETRY_FOR, LayerRegistry, layerNeeds, layerQuery, tokenFor, validateLayer, volumeOf, type QueryHints, type ResolvedVolume } from './layers.js';

package/vendor/map-engine/layers/index.js

@@ -0,0 +1 @@
+export { drawable, GEOMETRY_FOR, SOURCE_GEOMETRY_FOR, LayerRegistry, layerNeeds, layerQuery, tokenFor, validateLayer, volumeOf } from './layers.js';