@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/react/MapView.js

@@ -0,0 +1,270 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * React integration (doc 19, §48). React owns the container; the engine owns everything spatial.
+ * No GIS logic here (Decision: React is the integration layer only).
+ *
+ * Two ways to use it:
+ * - `<MapView config provider createRenderer …>`: MapView creates the runtime (once per provider, realtime,
+ *   ontology and history) and destroys it on unmount. `config.layers` changes are applied through the runtime API,
+ *   `config.basemap` changes through setBasemap() — neither remounts.
+ * - `<MapView map={runtime}>`: a runtime made outside React (shared, headless-first, or kept across views). MapView
+ *   only mounts it into its container and unmounts it again; the owner destroys it.
+ *
+ * `config.viewport` is the initial camera; move the camera with `runtime.setViewport` / `fitBounds` / `flyTo`.
+ * `selection` makes selection controlled: the application owns it and pushes it in.
+ */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { deepEqual } from '../core/equal.js';
+import { MapEngineError } from '../core/errors.js';
+import { createMapRuntime } from '../runtime/runtime.js';
+import { MapContext } from './context.js';
+import { MapStore } from './store.js';
+const ownedOf = (p) => (p.map === undefined ? p : null);
+/**
+ * The map element needs a positioned box. It is set by a zero-specificity rule, not inline, so an application class
+ * such as `absolute inset-0` or `size-full` wins (an inline `position: relative` silently gave zero height).
+ */
+const BASE_STYLE_ID = 'map-engine-base';
+function ensureBaseStyle() {
+    if (typeof document === 'undefined' || document.getElementById(BASE_STYLE_ID))
+        return;
+    const el = document.createElement('style');
+    el.id = BASE_STYLE_ID;
+    el.textContent = ':where([data-map-engine]){position:relative;overflow:hidden}';
+    document.head.appendChild(el);
+}
+function syncLayers(runtime, prev, next) {
+    const before = new Map(prev.map((l) => [l.id, l]));
+    const after = new Map(next.map((l) => [l.id, l]));
+    for (const id of before.keys())
+        if (!after.has(id))
+            runtime.removeLayer(id);
+    for (const [id, layer] of after) {
+        const old = before.get(id);
+        if (!old)
+            runtime.addLayer(layer);
+        else if (!deepEqual(old, layer)) {
+            const { id: _id, ...patch } = layer;
+            runtime.updateLayer(id, patch);
+        }
+    }
+}
+const toEngineError = (e) => e instanceof MapEngineError ? e : new MapEngineError('RENDERER_ERROR', e instanceof Error ? e.message : String(e), undefined, { cause: e });
+export function MapView(props) {
+    ensureBaseStyle();
+    const containerRef = useRef(null);
+    const [runtime, setRuntime] = useState(null);
+    const store = useMemo(() => new MapStore(), []);
+    const latest = useRef(props);
+    useLayoutEffect(() => {
+        latest.current = props;
+    });
+    const own = ownedOf(props);
+    const appliedLayers = useRef(own?.config.layers ?? []);
+    const appliedBasemap = useRef(own?.config.basemap);
+    // Create (or adopt) the runtime and mount it. StrictMode's double effect mounts, releases, then mounts again —
+    // safe, because destroy()/unmount() cancel a mount still in flight.
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el)
+            return;
+        const p = latest.current;
+        const o = ownedOf(p);
+        const rt = o
+            ? createMapRuntime(o.config, {
+                renderer: o.createRenderer(),
+                provider: o.provider,
+                ...(o.realtime ? { realtime: o.realtime } : {}),
+                ...(o.ontology ? { ontology: o.ontology } : {}),
+                ...(o.history ? { history: o.history } : {}),
+                ...(o.links ? { links: o.links } : {}),
+                ...(o.journal ? { journal: o.journal } : {}),
+                ...(o.annotations ? { annotations: o.annotations } : {}),
+                ...(o.auth ? { auth: o.auth } : {}),
+            }, o.runtimeOptions)
+            : p.map;
+        if (o) {
+            appliedLayers.current = o.config.layers;
+            appliedBasemap.current = o.config.basemap;
+        }
+        let live = true;
+        store.set({ state: rt.state, selection: rt.getSelection(), viewport: rt.getViewport(), time: rt.getTime() });
+        const offs = [
+            rt.on('state', (state) => store.set({ state })),
+            rt.on('selection', (selection) => {
+                store.set({ selection });
+                latest.current.onSelect?.(selection);
+            }),
+            rt.on('viewport', (viewport) => {
+                store.set({ viewport });
+                latest.current.onViewportChange?.(viewport);
+            }),
+            rt.on('mapClick', (e) => latest.current.onMapClick?.(e.position)),
+            rt.on('click', (e) => latest.current.onClick?.(e)),
+            rt.on('hover', (h) => latest.current.onHover?.(h)),
+            rt.on('error', (e) => latest.current.onError?.(e)),
+            rt.on('warning', (w) => latest.current.onWarning?.(w)),
+            rt.on('time', (time) => store.set({ time })),
+            rt.on('geofence', (e) => latest.current.onGeofence?.(e)),
+        ];
+        try {
+            if (p.geofences)
+                rt.setGeofences(p.geofences);
+            if (p.time && p.time.mode === 'replay')
+                rt.setTime(p.time);
+            const controlled = p.selection;
+            if (controlled)
+                rt.setSelection({ objectIds: controlled.objectIds, source: controlled.source ?? 'app', ...(controlled.primaryObjectId ? { primaryObjectId: controlled.primaryObjectId } : {}) });
+        }
+        catch (e) {
+            p.onError?.(toEngineError(e));
+        }
+        setRuntime(rt);
+        rt.mount(el).then(() => live && rt.isMounted() && latest.current.onReady?.(rt), (e) => live && latest.current.onError?.(toEngineError(e)));
+        let observer;
+        if (typeof ResizeObserver !== 'undefined') {
+            let first = true;
+            observer = new ResizeObserver(() => {
+                if (first)
+                    return void (first = false); // the initial observation is not a resize
+                if (rt.isMounted())
+                    rt.resize();
+            });
+            observer.observe(el);
+        }
+        return () => {
+            live = false;
+            observer?.disconnect();
+            for (const off of offs)
+                off();
+            if (o)
+                rt.destroy();
+            else
+                rt.unmount(); // not ours: release the container, keep the runtime
+            store.set({ state: o ? 'destroyed' : 'idle', selection: undefined, viewport: undefined, time: { mode: 'live' } });
+            setRuntime((cur) => (cur === rt ? null : cur));
+        };
+        // `createRenderer`, callbacks and `config` are read from `latest` on creation on purpose.
+    }, [props.map, own?.provider, own?.realtime, own?.ontology, own?.history, own?.links, own?.journal, own?.annotations, store]);
+    // Owned: a new identity is handed to the providers in place (the map reloads what this user may see).
+    const authKey = own ? JSON.stringify(own.auth ?? null) : '';
+    useEffect(() => {
+        const o = ownedOf(latest.current);
+        if (!runtime || runtime.state === 'destroyed' || !o || o.auth === undefined)
+            return;
+        runtime.setAuth(o.auth);
+        // authKey stands for the identity
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [runtime, authKey]);
+    // Owned: basemap changes swap the basemap in place (camera, layers, selection and time stay).
+    const basemapKey = own ? JSON.stringify(own.config.basemap) : '';
+    useEffect(() => {
+        const o = ownedOf(latest.current);
+        if (!runtime || runtime.state === 'destroyed' || !o || deepEqual(appliedBasemap.current, o.config.basemap))
+            return;
+        appliedBasemap.current = o.config.basemap;
+        runtime.setBasemap(o.config.basemap).catch((e) => latest.current.onError?.(toEngineError(e)));
+        // basemapKey stands for config.basemap
+    }, [runtime, basemapKey]);
+    // Owned: projection and terrain changes apply in place too (ADR-026).
+    const projection = own?.config.projection ?? 'mercator';
+    useEffect(() => {
+        if (!runtime || runtime.state === 'destroyed' || !ownedOf(latest.current))
+            return;
+        try {
+            runtime.setProjection(projection);
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+    }, [runtime, projection]);
+    const terrainKey = own ? JSON.stringify(own.config.terrain ?? null) : '';
+    useEffect(() => {
+        const o = ownedOf(latest.current);
+        if (!runtime || runtime.state === 'destroyed' || !o)
+            return;
+        try {
+            runtime.setTerrain(o.config.terrain ?? null);
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+        // terrainKey stands for config.terrain
+    }, [runtime, terrainKey]);
+    const tilesetsKey = own ? JSON.stringify(own.config.tilesets ?? []) : '';
+    useEffect(() => {
+        const o = ownedOf(latest.current);
+        if (!runtime || runtime.state === 'destroyed' || !o)
+            return;
+        try {
+            runtime.setTilesets(o.config.tilesets ?? []);
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+        // tilesetsKey stands for config.tilesets
+    }, [runtime, tilesetsKey]);
+    // Owned: apply layer changes without recreating the map.
+    const layersKey = own ? JSON.stringify(own.config.layers) : '';
+    useEffect(() => {
+        const o = ownedOf(latest.current);
+        if (!runtime || runtime.state === 'destroyed' || !o)
+            return;
+        try {
+            syncLayers(runtime, appliedLayers.current, o.config.layers);
+            appliedLayers.current = o.config.layers;
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+        // layersKey stands for config.layers
+    }, [runtime, layersKey]);
+    // Controlled selection.
+    const sel = props.selection;
+    const selectionKey = sel ? JSON.stringify([sel.objectIds, sel.primaryObjectId ?? null]) : null;
+    useEffect(() => {
+        if (!runtime || runtime.state === 'destroyed' || !sel)
+            return;
+        runtime.setSelection({ objectIds: sel.objectIds, source: sel.source ?? 'app', ...(sel.primaryObjectId ? { primaryObjectId: sel.primaryObjectId } : {}) });
+        // selectionKey stands for props.selection
+    }, [runtime, selectionKey]);
+    // Application-owned time: pushed into the runtime whenever it changes. A runtime we do not own keeps its own
+    // time unless the prop is given.
+    const timeKey = JSON.stringify(props.time ?? null);
+    useEffect(() => {
+        if (!runtime || runtime.state === 'destroyed')
+            return;
+        if (props.time === undefined && !own)
+            return;
+        try {
+            runtime.setTime(props.time ?? { mode: 'live' });
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+        // timeKey stands for props.time
+    }, [runtime, timeKey]);
+    const geofencesKey = JSON.stringify(props.geofences ?? null);
+    useEffect(() => {
+        if (!runtime || runtime.state === 'destroyed')
+            return;
+        if (props.geofences === undefined && !own)
+            return;
+        try {
+            runtime.setGeofences(props.geofences ?? []);
+        }
+        catch (e) {
+            latest.current.onError?.(toEngineError(e));
+        }
+        // geofencesKey stands for props.geofences
+    }, [runtime, geofencesKey]);
+    useEffect(() => {
+        if (!runtime || runtime.state === 'destroyed')
+            return;
+        if (props.selectable === undefined && !own)
+            return;
+        runtime.setSelectable(props.selectable ?? true);
+    }, [runtime, props.selectable]);
+    const ctx = useMemo(() => ({ runtime, store }), [runtime, store]);
+    return (_jsx(MapContext.Provider, { value: ctx, children: _jsxs("div", { className: props.className, style: props.style, "data-map-engine": "", children: [_jsx("div", { ref: containerRef, style: { position: 'absolute', inset: 0 } }), props.children] }) }));
+}

package/vendor/map-engine/react/context.d.ts

@@ -0,0 +1,39 @@
+import type { GeofenceEvent, MapViewport, Position, SelectionContext, TimeState } from '../core/types.js';
+import type { MapRuntime, RuntimeState } from '../runtime/runtime.js';
+import type { MapStore } from './store.js';
+export interface MapContextValue {
+    runtime: MapRuntime | null;
+    store: MapStore;
+}
+export declare const MapContext: import("react").Context<MapContextValue | null>;
+/** The runtime behind the nearest <MapView>, or null before it is created. Use it to call engine APIs. */
+export declare function useMapRuntime(): MapRuntime | null;
+export declare function useSelection(): SelectionContext | undefined;
+export declare function useViewport(): MapViewport | undefined;
+export declare function useMapState(): RuntimeState;
+/** What time the map shows: live, or a replay time and range. */
+export declare function useMapTime(): TimeState;
+export interface GeofenceView {
+    /** Newest first. Live: what happened this session. Replay: what happened in the range up to the replay time. */
+    events: GeofenceEvent[];
+    /** Object ids inside each geofence now (live) or at the replay time. */
+    occupancy: Record<string, string[]>;
+}
+/**
+ * Geofence events and occupancy, kept current as objects move, geofences change, or time changes. Inside <MapView>
+ * it uses that map; panels outside the map pass the runtime (from `onReady`) instead.
+ */
+export declare function useGeofences(options?: {
+    limit?: number;
+    runtime?: MapRuntime | null;
+}): GeofenceView;
+/**
+ * Where a position is on screen (pixels from the map's top-left), kept current while the camera moves — for
+ * popups and other overlays pinned to an object. Null when there is no position or no map yet.
+ */
+export declare function useProjected(position: Position | null | undefined, options?: {
+    runtime?: MapRuntime | null;
+}): {
+    x: number;
+    y: number;
+} | null;

package/vendor/map-engine/react/context.js

@@ -0,0 +1,94 @@
+import { createContext, useContext, useEffect, useState, useSyncExternalStore } from 'react';
+export const MapContext = createContext(null);
+function useMapContext(hook) {
+    const ctx = useContext(MapContext);
+    if (!ctx)
+        throw new Error(`${hook} must be used inside <MapView>`);
+    return ctx;
+}
+/** The runtime behind the nearest <MapView>, or null before it is created. Use it to call engine APIs. */
+export function useMapRuntime() {
+    return useMapContext('useMapRuntime').runtime;
+}
+export function useSelection() {
+    const { store } = useMapContext('useSelection');
+    return useSyncExternalStore(store.subscribe, () => store.get().selection, () => undefined);
+}
+export function useViewport() {
+    const { store } = useMapContext('useViewport');
+    return useSyncExternalStore(store.subscribe, () => store.get().viewport, () => undefined);
+}
+export function useMapState() {
+    const { store } = useMapContext('useMapState');
+    return useSyncExternalStore(store.subscribe, () => store.get().state, () => 'idle');
+}
+const LIVE = { mode: 'live' };
+/** What time the map shows: live, or a replay time and range. */
+export function useMapTime() {
+    const { store } = useMapContext('useMapTime');
+    return useSyncExternalStore(store.subscribe, () => store.get().time, () => LIVE);
+}
+const EMPTY = { events: [], occupancy: {} };
+/**
+ * Geofence events and occupancy, kept current as objects move, geofences change, or time changes. Inside <MapView>
+ * it uses that map; panels outside the map pass the runtime (from `onReady`) instead.
+ */
+export function useGeofences(options = {}) {
+    const ctx = useContext(MapContext);
+    const runtime = options.runtime !== undefined ? options.runtime : ctx ? ctx.runtime : undefined;
+    if (runtime === undefined)
+        throw new Error('useGeofences must be used inside <MapView> or be given a runtime');
+    const limit = options.limit ?? 100;
+    const [view, setView] = useState(EMPTY);
+    useEffect(() => {
+        if (!runtime)
+            return setView(EMPTY);
+        let key = '';
+        const read = () => {
+            if (runtime.state === 'destroyed')
+                return;
+            const next = { events: runtime.getGeofenceEvents(limit), occupancy: runtime.getGeofenceOccupancy() };
+            const k = JSON.stringify(next);
+            if (k !== key) {
+                key = k;
+                setView(next);
+            }
+        };
+        read();
+        const offs = [runtime.on('geofence', read), runtime.on('geofences', read), runtime.on('time', read), runtime.on('scene', read), runtime.on('state', read)];
+        return () => offs.forEach((off) => off());
+    }, [runtime, limit]);
+    return view;
+}
+/**
+ * Where a position is on screen (pixels from the map's top-left), kept current while the camera moves — for
+ * popups and other overlays pinned to an object. Null when there is no position or no map yet.
+ */
+export function useProjected(position, options = {}) {
+    const ctx = useContext(MapContext);
+    const runtime = options.runtime !== undefined ? options.runtime : (ctx?.runtime ?? null);
+    const lat = position?.latitude;
+    const lon = position?.longitude;
+    const [point, setPoint] = useState(null);
+    useEffect(() => {
+        if (!runtime || lat === undefined || lon === undefined)
+            return setPoint(null);
+        let frame = 0;
+        const read = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => {
+                if (runtime.state === 'destroyed')
+                    return;
+                const p = runtime.project({ latitude: lat, longitude: lon });
+                setPoint((cur) => (cur && p && Math.abs(cur.x - p.x) < 0.5 && Math.abs(cur.y - p.y) < 0.5 ? cur : p));
+            });
+        };
+        read();
+        const offs = [runtime.on('move', read), runtime.on('viewport', read), runtime.on('state', read)];
+        return () => {
+            cancelAnimationFrame(frame);
+            offs.forEach((off) => off());
+        };
+    }, [runtime, lat, lon]);
+    return point;
+}

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

@@ -0,0 +1,2 @@
+export { MapView, type MapViewCommonProps, type MapViewOwnedProps, type MapViewProps, type MapViewRuntimeProps } from './MapView.js';
+export { useGeofences, useProjected, useMapRuntime, useMapState, useMapTime, useSelection, useViewport, type GeofenceView } from './context.js';

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

@@ -0,0 +1,2 @@
+export { MapView } from './MapView.js';
+export { useGeofences, useProjected, useMapRuntime, useMapState, useMapTime, useSelection, useViewport } from './context.js';

package/vendor/map-engine/react/store.d.ts

@@ -0,0 +1,19 @@
+import type { MapViewport, SelectionContext, TimeState } from '../core/types.js';
+import type { RuntimeState } from '../runtime/runtime.js';
+export interface MapSnapshot {
+    state: RuntimeState;
+    selection: SelectionContext | undefined;
+    viewport: MapViewport | undefined;
+    time: TimeState;
+}
+/**
+ * Per-MapView external store. Slices are replaced (never mutated) only when they change, so
+ * `useSyncExternalStore` selectors stay stable and components re-render only for what they read.
+ */
+export declare class MapStore {
+    private snapshot;
+    private readonly listeners;
+    readonly subscribe: (listener: () => void) => (() => void);
+    readonly get: () => MapSnapshot;
+    set(patch: Partial<MapSnapshot>): void;
+}

package/vendor/map-engine/react/store.js

@@ -0,0 +1,18 @@
+/**
+ * Per-MapView external store. Slices are replaced (never mutated) only when they change, so
+ * `useSyncExternalStore` selectors stay stable and components re-render only for what they read.
+ */
+export class MapStore {
+    snapshot = { state: 'idle', selection: undefined, viewport: undefined, time: { mode: 'live' } };
+    listeners = new Set();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    get = () => this.snapshot;
+    set(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const l of [...this.listeners])
+            l();
+    }
+}

package/vendor/map-engine/realtime/apply.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Realtime (doc 14, §39–40, §62): how one frame of incremental changes is applied. Pure functions over the data
+ * the runtime hands in — no scene, no renderer, no events of its own — so the rules (coalescing, stale and
+ * out-of-order updates, clock skew, leaving the view, incremental index updates, trail growth) are testable alone.
+ */
+import { MapEngineError } from '../core/errors.js';
+import type { BoundingBox, MapLayer, SpatialObject, Track } from '../core/types.js';
+import type { SpatialPatch } from '../data/contracts.js';
+import type { SpatialIndex } from '../spatial/spatial-index.js';
+/** One stream event waiting for the next frame. `trail` events grow track layers instead of moving objects. */
+export interface PendingPatch {
+    layerIds: string[];
+    patch: SpatialPatch;
+    trail?: boolean;
+}
+/** What one frame changed in one layer, so the scene and the index touch only those objects. */
+export interface LayerChanges {
+    upserted: Map<string, SpatialObject>;
+    removed: Set<string>;
+}
+export interface ApplyContext {
+    layer(layerId: string): MapLayer | undefined;
+    /** The objects the layer holds now. */
+    current(layerId: string): SpatialObject[];
+    /** The viewport data boundary: an object that moves out of it leaves the layer. */
+    bounds: BoundingBox;
+    /** Held times after this are clock skew and cannot order updates (doc 14). */
+    trustUntil: number;
+    counters: {
+        applied: number;
+        stale: number;
+        outOfView: number;
+    };
+    warn(warning: MapEngineError): void;
+    /** Every valid incoming object, before ordering (for clock-skew reporting). */
+    saw(object: SpatialObject, layerId: string): void;
+    /** Grows a track layer from a patch; true when it changed. */
+    trail(layerId: string, patch: SpatialPatch): boolean;
+}
+export interface AppliedFrame {
+    /** Each touched layer's objects after the frame. */
+    touched: Map<string, Map<string, SpatialObject>>;
+    changes: Map<string, LayerChanges>;
+    /** Fresh point readings (including ones that leave the view), for geofencing. */
+    fresh: Array<{
+        layerId: string;
+        object: SpatialObject;
+    }>;
+    /** Track layers that grew. */
+    trails: Set<string>;
+}
+/**
+ * Is `next` older than what is held? A held time beyond `trustUntil` (clock skew) cannot order anything: a real
+ * update must not be refused because a source once stamped the future.
+ */
+export declare function isOlder(next: SpatialObject, prev: SpatialObject, trustUntil: number): boolean;
+/** Applies one frame of stream events. Many events for one object collapse into its newest state. */
+export declare function applyFrame(batch: PendingPatch[], ctx: ApplyContext): AppliedFrame;
+/**
+ * Applies one frame's changes to the client index instead of rebuilding it. The index holds each object once
+ * however many layers show it, so an object leaves only when no other layer still shows it.
+ *
+ * `displayed` is what every layer shows; `touched` holds the frame's new state for the layers it changed;
+ * `skip` names layers kept out of the index (trails).
+ */
+export declare function patchIndex(index: SpatialIndex, changes: Map<string, LayerChanges>, touched: Map<string, Map<string, SpatialObject>>, displayed: Map<string, SpatialObject[]>, skip: (layerId: string) => boolean): void;
+/**
+ * Grows trails from live point updates and drops points older than `keepFrom`. Returns how many points were added
+ * and whether anything changed (a removal changes a trail without adding points).
+ */
+export declare function growTrails(tracks: Map<string, Track>, patch: SpatialPatch, keepFrom: number, now: number): {
+    changed: boolean;
+    added: number;
+};