@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/runtime/runtime.js

@@ -0,0 +1,2105 @@
+/**
+ * MapRuntime: the orchestrator.
+ *
+ *   config → layers → (viewport bounds) → provider.query → validate → index → scene → renderer
+ *   renderer events → viewport / selection / hover / map clicks → patches → renderer
+ *
+ * It does not know any database (only provider contracts), any renderer technology (only the Renderer
+ * contract), or any domain. It is not a security boundary: providers return authorized data.
+ */
+import { Emitter } from '../core/emitter.js';
+import { deepEqual } from '../core/equal.js';
+import { MapEngineError, isAbortError } from '../core/errors.js';
+import { commandProblem } from '../core/commands.js';
+import { isAuthAware, isMissingCapability } from '../data/contracts.js';
+import { ageOf, effectiveLayer, nextAgeChangeMs, presentObject } from '../present/present.js';
+import { decorationLayers, decorationObjects, decorationOwner } from '../present/decorations.js';
+import { measure as measureGeometry } from '../spatial/measure.js';
+import { labelPoint } from '../spatial/operations.js';
+import { validateConditions } from '../spatial/query.js';
+import { groupJournal, journalStateAt } from '../temporal/journal.js';
+import { ANNOTATION_LAYERS, HIGHLIGHT_COLOR, PROPOSAL_LAYERS, SELECTABLE_OVERLAYS, annotationObjects, highlightLayers, highlightObjects, proposalObjects } from './overlays.js';
+import { allowedOrigins, offlineViolations } from './offline.js';
+import { normalizeTrack, stateAt, toIso, toMs, trailBetween, validateTrack } from '../temporal/tracks.js';
+import { GeofenceEvaluator, readingsFrom, validateGeofence, watches } from '../geofence/evaluator.js';
+import { evaluateTracks } from '../geofence/history.js';
+import { autoFinishes, draftObjects, DRAFT_LAYERS, drawnGeometry, minPoints } from './drawing.js';
+import { within } from '../spatial/operations.js';
+import { geometryFamily } from '../core/geometry-family.js';
+import { DERIVED_TYPES, GEOMETRY_FOR, LayerRegistry, layerNeeds, layerQuery, SOURCE_GEOMETRY_FOR } from '../layers/layers.js';
+import { SceneManager, isEmptyPatch, mergePatches } from '../scene/scene.js';
+import { SelectionState } from '../selection/selection.js';
+import { RBushSpatialIndex } from '../spatial/spatial-index.js';
+import { geometryBounds, unionBounds, validateGeometry, validatePosition } from '../spatial/geometry.js';
+import { judgeSight, pathSamples } from '../spatial/line-of-sight.js';
+import { matchesQuery, rankByRelation } from '../spatial/query.js';
+import { computeBounds, normalizeViewport, validateViewport, zoomToFit } from '../viewport/viewport.js';
+import { planQueries } from '../query/planner.js';
+import { applyFrame, growTrails, patchIndex } from '../realtime/apply.js';
+const ANNOTATION_KINDS = ['point', 'line', 'polygon', 'rectangle', 'circle', 'measurement', 'label', 'note'];
+const isDerived = (l) => !!l && DERIVED_TYPES.includes(l.visualization.type);
+/** A provider refused this user (doc 28 G13): an ACCESS_DENIED engine error, a `code` of the same name, or HTTP 403. */
+function isDenied(e) {
+    const x = e;
+    return !!x && (x.code === 'ACCESS_DENIED' || x.status === 403);
+}
+/** Where a link meets an object: the point itself, or a point on a line or inside an area. */
+const endPosition = (o) => (o.geometry.type === 'Point' ? o.geometry.coordinates : labelPoint(o.geometry));
+const DEFAULT_SIZE = { width: 1024, height: 768 };
+/** Which parts of a layer changed, as dotted paths an audit log can show (source.filter, visualization, visible…). */
+function changedFields(before, after) {
+    if (!before)
+        return [];
+    const out = [];
+    for (const key of ['visible', 'zIndex', 'visualization', 'interaction'])
+        if (!deepEqual(before[key], after[key]))
+            out.push(key);
+    for (const key of new Set([...Object.keys(before.source), ...Object.keys(after.source)])) {
+        if (!deepEqual(before.source[key], after.source[key]))
+            out.push(`source.${key}`);
+    }
+    return out;
+}
+/** Whether a drawing can finish now, and if not because the shape is invalid, why. */
+function drawingCheck(kind, points) {
+    if (points.length < minPoints(kind))
+        return { canFinish: false };
+    const geometry = drawnGeometry(kind, points);
+    if (!geometry)
+        return { canFinish: false };
+    const check = validateGeometry(geometry);
+    return check.valid ? { canFinish: true } : { canFinish: false, problem: check.reason };
+}
+const FILTER_FIELDS = ['filter', 'where', 'spatialQuery', 'objectIds'];
+function filterOf(source) {
+    const out = {};
+    for (const f of FILTER_FIELDS)
+        if (source[f] !== undefined)
+            out[f] = structuredClone(source[f]);
+    return out;
+}
+class Runtime {
+    deps;
+    emitter = new Emitter();
+    layers;
+    scene;
+    selection;
+    index;
+    /** Last validated result per layer, so style or visualization changes re-filter without a new query. */
+    layerData = new Map();
+    viewport;
+    current = 'idle';
+    mounted = false;
+    /** A mount() is waiting for the renderer. */
+    mounting = false;
+    /** Bumped by unmount()/destroy(): a mount() that started before it is stale and must not finish. */
+    mountGen = 0;
+    container = null;
+    basemap;
+    renderer;
+    projection;
+    terrain;
+    tilesets;
+    /** Missing capabilities already reported for the current renderer ("layerId:capability" or "map:capability"). */
+    reportedNeeds = new Set();
+    rendererSubs = [];
+    selectable = true;
+    timer = null;
+    inflight = null;
+    controller = null;
+    debounceMs;
+    fallbackSize;
+    frame;
+    reconnectMs;
+    skewToleranceMs;
+    /** Objects already reported for clock skew (one warning each). */
+    skewed = new Set();
+    bindings = new Map();
+    subscriptions = [];
+    pending = [];
+    time = { mode: 'live' };
+    /** Track layers: trail data per layer and object. */
+    trailData = new Map();
+    /** Replay: tracks per point layer and object, for the whole replay range. */
+    replayTracks = new Map();
+    /** What the scene shows per layer (live data, or replay state at T). The client index follows it. */
+    displayed = new Map();
+    replayQueued = false;
+    warnedNoHistory = false;
+    now;
+    geofence = new GeofenceEvaluator();
+    drawing = null;
+    geofenceLog = [];
+    replayEvents = [];
+    frameQueued = false;
+    reconnectTimer = null;
+    /** Link layers: the links last loaded per layer, drawn between their ends' current positions (doc 28 G4). */
+    linkData = new Map();
+    /** Replay: journal entries per layer, by object, to rebuild whole objects at a time (doc 29 §8). */
+    journalData = new Map();
+    /** Fires when the next object changes age state or enters/leaves its validity window (doc 28 G1). */
+    ageTimer = null;
+    ageSoon = null;
+    layerStatus = new Map();
+    auth;
+    highlighted = null;
+    highlightTimer = null;
+    proposals = new Map();
+    annotationStore = new Map();
+    annotationSub = null;
+    annotationsVisible = true;
+    /** One-time warnings already given (by key). */
+    warned = new Set();
+    offline;
+    idSeq = 0;
+    stats = {
+        loads: 0,
+        providerCalls: 0,
+        lastLoadMs: 0,
+        lastPlan: null,
+        realtime: { subscriptions: 0, received: 0, applied: 0, stale: 0, outOfView: 0, frames: 0, reconnects: 0 },
+        temporal: { trackFetches: 0, tracksLoaded: 0, replayFrames: 0, trailPointsAppended: 0 },
+        geofence: { geofences: 0, liveEvents: 0, replayEvents: 0 },
+    };
+    constructor(config, deps, options = {}) {
+        this.deps = deps;
+        const v = validateViewport(config.viewport);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_VIEWPORT', v.reason);
+        this.viewport = normalizeViewport(config.viewport);
+        this.basemap = structuredClone(config.basemap);
+        this.renderer = deps.renderer;
+        this.projection = config.projection ?? 'mercator';
+        if (config.projection !== undefined && config.projection !== 'mercator' && config.projection !== 'globe')
+            throw new MapEngineError('INVALID_LAYER', `projection must be mercator or globe`);
+        if (config.terrain) {
+            const t = validateTerrain(config.terrain);
+            if (!t.valid)
+                throw new MapEngineError('INVALID_LAYER', t.reason);
+        }
+        this.terrain = config.terrain ? structuredClone(config.terrain) : null;
+        const ts = validateTilesets(config.tilesets ?? []);
+        if (!ts.valid)
+            throw new MapEngineError('INVALID_LAYER', ts.reason);
+        this.tilesets = structuredClone(config.tilesets ?? []);
+        this.offline = config.offline;
+        this.assertOffline({ basemap: config.basemap, terrain: config.terrain ?? null, tilesets: config.tilesets ?? [], layers: config.layers });
+        this.auth = deps.auth ? structuredClone(deps.auth) : null;
+        this.handAuth();
+        this.debounceMs = options.debounceMs ?? 150;
+        this.fallbackSize = options.fallbackSize ?? DEFAULT_SIZE;
+        this.layers = new LayerRegistry(config.layers);
+        this.scene = new SceneManager(this.viewport);
+        this.scene.setLayers(this.sceneLayers());
+        this.selection = new SelectionState(options.now);
+        this.index = deps.spatialIndex ?? new RBushSpatialIndex();
+        this.frame =
+            options.frame ?? (typeof requestAnimationFrame === 'function' ? (cb) => void requestAnimationFrame(() => cb()) : (cb) => void setTimeout(cb, 16));
+        this.reconnectMs = options.reconnectMs ?? 1000;
+        this.skewToleranceMs = options.clockSkewToleranceMs ?? 60_000;
+        this.now = options.now ?? Date.now;
+    }
+    get state() {
+        return this.current;
+    }
+    on(event, listener) {
+        return this.emitter.on(event, listener);
+    }
+    async mount(container) {
+        this.assertAlive();
+        if (this.mounted || this.mounting)
+            throw new MapEngineError('ALREADY_MOUNTED', 'runtime is already mounted; unmount or destroy it first');
+        const r = this.renderer;
+        const gen = ++this.mountGen;
+        this.mounting = true;
+        this.container = container;
+        try {
+            const offline = allowedOrigins(this.offline);
+            await r.initialize(container, { basemap: this.basemap, viewport: this.viewport, projection: this.projection, ...(this.terrain ? { terrain: this.terrain } : {}), ...(this.tilesets.length ? { tilesets: this.tilesets } : {}), ...(offline ? { offline: { allowedOrigins: offline } } : {}) });
+        }
+        catch (cause) {
+            if (gen !== this.mountGen)
+                return; // unmounted or destroyed meanwhile: nothing to report
+            this.mounting = false;
+            throw new MapEngineError('RENDERER_ERROR', 'renderer failed to initialize', undefined, { cause });
+        }
+        if (gen !== this.mountGen)
+            return; // unmount()/destroy() already released the renderer
+        this.mounting = false;
+        if (this.current === 'destroyed') {
+            r.destroy();
+            return;
+        }
+        this.mounted = true;
+        this.checkNeeds();
+        this.rendererSubs = [
+            r.onViewportChange((v) => this.onRendererViewport(v)),
+            r.onPick((e) => this.onPick(e)),
+            r.onMapClick((e) => {
+                if (this.drawing)
+                    return this.addDrawingPoint(e.position);
+                this.emitter.emit('mapClick', e);
+                this.emitter.emit('click', { position: e.position, hit: null });
+            }),
+            r.onHover((e) => this.onHover(e)),
+            ...(r.onCameraMove ? [r.onCameraMove(() => this.emitter.emit('move', null))] : []),
+            r.onError((e) => this.emitter.emit('error', new MapEngineError('RENDERER_ERROR', e.message, undefined, { cause: e }))),
+        ];
+        this.scene.setViewport(this.withBounds(this.viewport));
+        r.render(this.scene.getState());
+        this.emitter.emit('viewport', this.getViewport()); // first camera, so readouts don't start empty
+        void this.loadAnnotations();
+        await this.refresh();
+    }
+    unmount() {
+        if (this.current === 'destroyed' || (!this.mounted && !this.mounting))
+            return;
+        this.release();
+        this.setState('idle');
+    }
+    isMounted() {
+        return this.mounted;
+    }
+    async setBasemap(basemap) {
+        this.assertAlive();
+        if (deepEqual(basemap, this.basemap))
+            return;
+        this.assertOffline({ basemap });
+        this.basemap = structuredClone(basemap);
+        if (this.mounting) {
+            // The renderer is starting with the old basemap: start it again with the new one.
+            const container = this.container;
+            this.unmount();
+            return this.mount(container);
+        }
+        if (!this.mounted)
+            return; // the next mount uses it
+        const r = this.renderer;
+        const gen = this.mountGen;
+        if (r.setBasemap) {
+            try {
+                await r.setBasemap(basemap);
+            }
+            catch (cause) {
+                if (gen !== this.mountGen)
+                    return;
+                throw new MapEngineError('RENDERER_ERROR', 'basemap could not be changed', undefined, { cause });
+            }
+            if (gen !== this.mountGen || !this.mounted)
+                return;
+            r.render(this.scene.getState());
+            return;
+        }
+        const container = this.container;
+        this.unmount();
+        await this.mount(container);
+    }
+    async setRenderer(renderer) {
+        this.assertAlive();
+        if (renderer === this.renderer)
+            return;
+        const container = this.container;
+        const wasShown = this.mounted || this.mounting;
+        if (wasShown)
+            this.unmount();
+        this.renderer = renderer;
+        this.reportedNeeds.clear();
+        if (wasShown && container)
+            await this.mount(container);
+    }
+    setProjection(projection) {
+        this.assertAlive();
+        if (projection !== 'mercator' && projection !== 'globe')
+            throw new MapEngineError('INVALID_LAYER', `projection must be mercator or globe`);
+        if (projection === this.projection)
+            return;
+        this.projection = projection;
+        if (this.mounted) {
+            this.renderer.setProjection?.(projection);
+            this.checkNeeds();
+        }
+    }
+    setTerrain(terrain) {
+        this.assertAlive();
+        if (terrain) {
+            const t = validateTerrain(terrain);
+            if (!t.valid)
+                throw new MapEngineError('INVALID_LAYER', t.reason);
+            this.assertOffline({ terrain });
+        }
+        if (deepEqual(terrain, this.terrain))
+            return;
+        this.terrain = terrain ? structuredClone(terrain) : null;
+        if (this.mounted) {
+            this.renderer.setTerrain?.(this.terrain);
+            this.checkNeeds();
+        }
+    }
+    setTilesets(tilesets) {
+        this.assertAlive();
+        const v = validateTilesets(tilesets);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_LAYER', v.reason);
+        this.assertOffline({ tilesets });
+        if (deepEqual(tilesets, this.tilesets))
+            return;
+        this.tilesets = structuredClone(tilesets);
+        if (this.mounted) {
+            this.renderer.setTilesets?.(this.tilesets);
+            this.checkNeeds();
+        }
+    }
+    async sampleElevation(positions, signal) {
+        this.assertAlive();
+        for (const [i, p] of positions.entries()) {
+            const v = validatePosition(p, `positions[${i}]`);
+            if (!v.valid)
+                throw new MapEngineError('INVALID_GEOMETRY', v.reason);
+        }
+        if (this.deps.elevation)
+            return this.deps.elevation.sample(positions, signal);
+        if (this.mounted && this.renderer.capabilities?.elevation && this.renderer.sampleElevation)
+            return this.renderer.sampleElevation(positions);
+        throw new MapEngineError('MISSING_CAPABILITY', 'ground heights need deps.elevation or a renderer with terrain (capability: elevation)');
+    }
+    async lineOfSight(from, to, options = {}) {
+        this.assertAlive();
+        const samples = pathSamples(from, to, Math.max(8, Math.min(1024, options.samples ?? 128)));
+        const ground = await this.sampleElevation(samples, options.signal);
+        const fromHeight = from.altitude ?? (ground[0] ?? 0) + (options.fromHeightAboveGround ?? 2);
+        const toHeight = to.altitude ?? (ground[ground.length - 1] ?? 0) + (options.toHeightAboveGround ?? 2);
+        return judgeSight(samples, ground, fromHeight, toHeight);
+    }
+    /**
+     * Compares what the map asks for with what the renderer can draw (ADR-026..028) and reports each gap once per
+     * renderer, instead of leaving a layer silently empty. The objects still load (lists and queries see them).
+     */
+    checkNeeds() {
+        if (!this.mounted)
+            return;
+        const caps = this.renderer.capabilities ?? {};
+        const report = (key, capability, what, details) => {
+            if (caps[capability] || this.reportedNeeds.has(key))
+                return;
+            this.reportedNeeds.add(key);
+            this.emitter.emit('warning', new MapEngineError('MISSING_CAPABILITY', `${what} needs the renderer capability "${capability}", which the current renderer does not have`, { ...details, capability }));
+        };
+        if (this.projection === 'globe')
+            report('map:globe', 'globe', 'projection: globe', {});
+        if (this.terrain)
+            report('map:terrain', 'terrain', 'terrain', {});
+        if (this.tilesets.some((t) => t.show !== false))
+            report('map:tiles3d', 'tiles3d', '3D Tiles scenery', {});
+        for (const layer of this.layers.list()) {
+            if (!layer.visible)
+                continue;
+            for (const need of layerNeeds(layer))
+                report(`${layer.id}:${need}`, need, `layer ${layer.id} (${layer.visualization.type}${layer.visualization.elevation ? ', elevation' : ''})`, { layerId: layer.id });
+        }
+    }
+    /** Stops everything that needs the renderer or the network; keeps the map's state. */
+    release() {
+        this.mountGen++;
+        const hadRenderer = this.mounted || this.mounting;
+        this.mounting = false;
+        this.cancelScheduled();
+        this.controller?.abort();
+        this.unsubscribeRealtime();
+        if (this.reconnectTimer !== null)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.pending = [];
+        for (const t of [this.ageTimer, this.ageSoon])
+            if (t !== null)
+                clearTimeout(t);
+        this.ageTimer = null;
+        this.ageSoon = null;
+        this.annotationSub?.();
+        this.annotationSub = null;
+        for (const off of this.rendererSubs)
+            off();
+        this.rendererSubs = [];
+        if (hadRenderer) {
+            try {
+                this.renderer.destroy();
+            }
+            catch {
+                // Releasing must always complete.
+            }
+        }
+        this.mounted = false;
+    }
+    destroy() {
+        if (this.current === 'destroyed')
+            return;
+        this.release();
+        this.container = null;
+        this.index.clear();
+        this.layerData.clear();
+        this.displayed.clear();
+        this.trailData.clear();
+        this.replayTracks.clear();
+        this.journalData.clear();
+        this.linkData.clear();
+        if (this.highlightTimer !== null)
+            clearTimeout(this.highlightTimer);
+        this.setState('destroyed');
+        this.emitter.clear();
+    }
+    // ---------------------------------------------------------------- viewport
+    getViewport() {
+        return structuredClone(this.withBounds(this.viewport));
+    }
+    project(position) {
+        if (this.current === 'destroyed' || this.current === 'idle')
+            return null;
+        return this.renderer.project?.(position) ?? null;
+    }
+    resize() {
+        this.assertAlive();
+        if (this.mounted)
+            this.renderer.resize();
+    }
+    setViewport(viewport, options) {
+        this.assertAlive();
+        const v = validateViewport(viewport);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_VIEWPORT', v.reason);
+        const next = normalizeViewport({ ...viewport });
+        delete next.bounds; // bounds are derived, never trusted from callers
+        this.viewport = next;
+        this.scene.setViewport(this.withBounds(next));
+        if (this.mounted)
+            this.renderer.setViewport(next, options);
+        this.emitter.emit('viewport', this.getViewport());
+        this.schedule();
+    }
+    fitBounds(bounds, options) {
+        const fit = zoomToFit(bounds, this.size(), options?.padding ?? 0);
+        this.setViewport({ ...fit, bearing: 0, pitch: 0 }, { animate: options?.animate ?? false });
+    }
+    async flyTo(to, options) {
+        this.assertAlive();
+        const animate = options?.animate ?? true;
+        let geometry;
+        if (typeof to === 'string') {
+            const loaded = this.lookup(to);
+            const object = loaded ?? (await this.deps.provider.getCurrentState([to])).find((o) => o?.objectId === to);
+            if (this.current === 'destroyed' || !object || !validateGeometry(object.geometry).valid)
+                return false;
+            geometry = object.geometry;
+        }
+        else {
+            const p = validatePosition(to, 'flyTo position');
+            if (!p.valid)
+                throw new MapEngineError('INVALID_VIEWPORT', p.reason);
+            geometry = { type: 'Point', coordinates: to };
+        }
+        if (geometry.type === 'Point') {
+            this.setViewport({ ...this.viewport, center: geometry.coordinates, zoom: options?.zoom ?? Math.max(this.viewport.zoom, 15) }, { animate });
+            return true;
+        }
+        const fit = zoomToFit(geometryBounds(geometry), this.size(), options?.padding ?? 40);
+        this.setViewport({ ...fit, zoom: Math.min(fit.zoom, options?.zoom ?? 18), bearing: this.viewport.bearing ?? 0, pitch: this.viewport.pitch ?? 0 }, { animate });
+        return true;
+    }
+    onRendererViewport(v) {
+        if (this.current === 'destroyed')
+            return;
+        const check = validateViewport(v);
+        if (!check.valid) {
+            this.emitter.emit('warning', new MapEngineError('INVALID_VIEWPORT', `renderer reported ${check.reason}`));
+            return;
+        }
+        const next = normalizeViewport(v);
+        if (sameCamera(next, this.viewport)) {
+            if (!next.bounds || deepEqual(next.bounds, this.viewport.bounds))
+                return;
+            // Same camera, new visible area. First bounds after our own setViewport: adopt (a load is already
+            // scheduled). Otherwise the container was resized: the data boundary changed, so load again.
+            const resized = this.viewport.bounds !== undefined;
+            this.viewport = next;
+            this.scene.setViewport(next);
+            if (resized) {
+                this.emitter.emit('viewport', this.getViewport());
+                this.schedule();
+            }
+            return;
+        }
+        this.viewport = next;
+        this.scene.setViewport(this.withBounds(next));
+        this.emitter.emit('viewport', this.getViewport());
+        this.schedule();
+    }
+    // ---------------------------------------------------------------- layers
+    getLayers() {
+        return this.layers.list();
+    }
+    addLayer(layer) {
+        this.assertAlive();
+        this.assertOffline({ layers: [layer] });
+        this.layers.add(layer);
+        this.applyLayers();
+        this.checkNeeds();
+        if (layer.visible)
+            this.schedule();
+        this.emitter.emit('layerChanged', { action: 'added', layerId: layer.id });
+    }
+    updateLayer(id, patch) {
+        this.assertAlive();
+        const before = this.layers.get(id);
+        if (before)
+            this.assertOffline({ layers: [{ ...before, ...patch, id }] });
+        const after = this.layers.update(id, patch);
+        const sourceChanged = !deepEqual(before?.source, after.source);
+        const becameVisible = !before?.visible && after.visible;
+        if (sourceChanged)
+            this.layerData.delete(id);
+        this.applyLayers();
+        this.checkNeeds();
+        if (after.visible && (sourceChanged || becameVisible))
+            this.schedule();
+        const fields = changedFields(before, after);
+        if (fields.length)
+            this.emitter.emit('layerChanged', { action: 'updated', layerId: id, fields });
+        if (before && FILTER_FIELDS.some((f) => fields.includes(`source.${f}`))) {
+            this.emitter.emit('filterChanged', { layerId: id, before: filterOf(before.source), after: filterOf(after.source) });
+        }
+    }
+    removeLayer(id) {
+        this.assertAlive();
+        this.layers.remove(id);
+        this.layerData.delete(id);
+        this.displayed.delete(id);
+        this.linkData.delete(id);
+        this.layerStatus.delete(id);
+        this.applyLayers();
+        this.rebuildIndex();
+        this.emitter.emit('layerChanged', { action: 'removed', layerId: id });
+    }
+    setLayerVisibility(id, visible) {
+        this.updateLayer(id, { visible });
+    }
+    setLayerZIndex(id, zIndex) {
+        this.updateLayer(id, { zIndex });
+    }
+    /**
+     * What the scene draws: the application's layers as renderers get them (effectiveLayer), each visible layer's
+     * decorations, the engine overlays (annotations, proposals, highlight) and, while drawing, the draft.
+     */
+    sceneLayers() {
+        const out = [];
+        for (const l of this.layers.list()) {
+            out.push(effectiveLayer(l));
+            if (l.visible)
+                out.push(...decorationLayers(l));
+        }
+        // Overlays only while they have something to show: a plain map carries no empty engine layers.
+        if (this.annotationStore.size)
+            out.push(...(this.annotationsVisible ? ANNOTATION_LAYERS : ANNOTATION_LAYERS.map((l) => ({ ...l, visible: false }))));
+        if (this.proposals.size)
+            out.push(...PROPOSAL_LAYERS);
+        if (this.highlighted)
+            out.push(...highlightLayers(this.highlighted.color ?? HIGHLIGHT_COLOR));
+        if (this.drawing)
+            out.push(...DRAFT_LAYERS);
+        return out;
+    }
+    /** Pushes layer definitions to the scene and re-applies cached data (style/visualization changes need no query). */
+    applyLayers() {
+        const patches = [this.scene.setLayers(this.sceneLayers())];
+        for (const layer of this.layers.visible()) {
+            if (layer.visualization.type === 'link') {
+                patches.push(this.linkPatch(layer));
+                continue;
+            }
+            const data = this.displayed.get(layer.id) ?? this.layerData.get(layer.id);
+            if (data)
+                patches.push(this.show(layer, data));
+        }
+        patches.push(this.overlayPatch());
+        if (this.drawing)
+            for (const [layerId, objects] of Object.entries(draftObjects(this.drawing)))
+                patches.push(this.scene.setLayerObjects(layerId, objects));
+        this.push(mergePatches(...patches));
+        this.scheduleAge();
+    }
+    /** The map's time for presentation: the clock when live, the replay time in replay. */
+    presentNow() {
+        return this.time.mode === 'replay' ? toMs(this.time.at) : this.now();
+    }
+    /** Shows a layer's objects as they look at the map's time (doc 28 G1–G2), with the layer's decorations. */
+    show(layer, objects) {
+        const now = this.presentNow();
+        const shown = [];
+        for (const o of objects) {
+            const p = presentObject(layer, o, now);
+            if (p)
+                shown.push(p);
+        }
+        const patches = [this.scene.setLayerObjects(layer.id, shown)];
+        for (const [id, list] of Object.entries(decorationObjects(layer, shown)))
+            patches.push(this.scene.setLayerObjects(id, list));
+        return mergePatches(...patches);
+    }
+    showId(layerId, objects) {
+        const layer = this.layers.get(layerId);
+        return layer ? this.show(layer, objects) : this.scene.setLayerObjects(layerId, objects);
+    }
+    /** Live changes of some objects: only those are presented again; decorations follow the whole layer. */
+    showChanges(layer, upserted, removed, all) {
+        const now = this.presentNow();
+        const up = [];
+        const gone = [...removed];
+        for (const o of upserted) {
+            const p = presentObject(layer, o, now);
+            if (p)
+                up.push(p);
+            else
+                gone.push(o.objectId);
+        }
+        const patches = [this.scene.patchLayerObjects(layer.id, up, gone)];
+        if (decorationLayers(layer).length) {
+            const shown = all.map((o) => presentObject(layer, o, now)).filter((o) => o !== null);
+            for (const [id, list] of Object.entries(decorationObjects(layer, shown)))
+                patches.push(this.scene.setLayerObjects(id, list));
+        }
+        return mergePatches(...patches);
+    }
+    /** Overlays changed: their layers come or go with them, then their objects. */
+    refreshOverlays() {
+        this.push(mergePatches(this.scene.setLayers(this.sceneLayers()), this.overlayPatch()));
+    }
+    /** The engine overlays' objects: annotations, proposals, and the halo of highlighted objects where they are now. */
+    overlayPatch() {
+        const groups = { ...annotationObjects(this.annotationStore.values()), ...proposalObjects(this.proposals.values()), ...highlightObjects(this.highlighted, (id) => this.index.get(id)) };
+        return mergePatches(...Object.entries(groups).map(([id, list]) => this.scene.setLayerObjects(id, list)));
+    }
+    /**
+     * Redraws objects whose age state changes, or that enter or leave their validity window, exactly when that
+     * happens (live only; replay presents at the replay time on every frame).
+     */
+    scheduleAge() {
+        if (this.ageTimer !== null)
+            clearTimeout(this.ageTimer);
+        this.ageTimer = null;
+        if (this.time.mode !== 'live' || !this.mounted || this.current === 'destroyed')
+            return;
+        const now = this.now();
+        let next = Number.POSITIVE_INFINITY;
+        for (const layer of this.layers.visible()) {
+            const list = this.displayed.get(layer.id);
+            if (!list || isDerived(layer))
+                continue;
+            const age = layer.visualization.age;
+            for (const o of list) {
+                const a = nextAgeChangeMs(o, age, now);
+                if (a !== null && a < next)
+                    next = a;
+                for (const t of [o.validFrom, o.validUntil]) {
+                    if (!t)
+                        continue;
+                    const d = Date.parse(t) - now;
+                    if (d > 0 && d < next)
+                        next = d;
+                }
+            }
+        }
+        if (!Number.isFinite(next))
+            return;
+        this.ageTimer = setTimeout(() => {
+            this.ageTimer = null;
+            if (this.current === 'destroyed' || this.time.mode !== 'live')
+                return;
+            const patches = [];
+            for (const layer of this.layers.visible()) {
+                const list = this.displayed.get(layer.id);
+                if (list && !isDerived(layer))
+                    patches.push(this.show(layer, list));
+            }
+            this.push(mergePatches(...patches));
+            this.scheduleAge();
+        }, Math.min(Math.max(next + 5, 50), 2_147_000_000));
+    }
+    /** Live frames come many times a second: the age schedule is recomputed at most a few times a second. */
+    scheduleAgeSoon() {
+        if (this.ageSoon !== null)
+            return;
+        this.ageSoon = setTimeout(() => {
+            this.ageSoon = null;
+            this.scheduleAge();
+        }, 300);
+    }
+    // ---------------------------------------------------------------- drawing (doc §37)
+    startDrawing(kind) {
+        this.assertAlive();
+        this.drawing = { kind, points: [], canFinish: false };
+        this.applyLayers();
+        this.emitter.emit('drawing', structuredClone(this.drawing));
+    }
+    addDrawingPoint(position) {
+        this.assertAlive();
+        if (!this.drawing)
+            return;
+        const check = validatePosition(position);
+        if (!check.valid)
+            throw new MapEngineError('INVALID_GEOMETRY', check.reason);
+        const points = [...this.drawing.points, { latitude: position.latitude, longitude: position.longitude }];
+        this.drawing = { kind: this.drawing.kind, points, ...drawingCheck(this.drawing.kind, points) };
+        if (autoFinishes(this.drawing.kind, points.length)) {
+            if (this.finishDrawing())
+                return;
+            // A degenerate shape (zero-size rectangle or circle): drop the last click and keep drawing.
+            this.drawing = { ...this.drawing, points: points.slice(0, -1), canFinish: false };
+        }
+        this.updateDraft();
+    }
+    undoDrawingPoint() {
+        if (!this.drawing || !this.drawing.points.length)
+            return;
+        const points = this.drawing.points.slice(0, -1);
+        this.drawing = { kind: this.drawing.kind, points, ...drawingCheck(this.drawing.kind, points) };
+        this.updateDraft();
+    }
+    finishDrawing() {
+        if (!this.drawing)
+            return null;
+        const { kind, points } = this.drawing;
+        const geometry = drawnGeometry(kind, points);
+        if (!geometry)
+            return null;
+        const check = validateGeometry(geometry);
+        if (!check.valid) {
+            // Drawing continues: the user can undo the point that made the shape invalid.
+            this.emitter.emit('warning', new MapEngineError('INVALID_GEOMETRY', `drawn ${kind}: ${check.reason}`));
+            return null;
+        }
+        this.drawing = null;
+        this.applyLayers();
+        this.emitter.emit('drawing', null);
+        this.emitter.emit('geometryDrawn', { kind, geometry: structuredClone(geometry) });
+        return geometry;
+    }
+    cancelDrawing() {
+        if (!this.drawing)
+            return;
+        this.drawing = null;
+        this.applyLayers();
+        this.emitter.emit('drawing', null);
+    }
+    getDrawing() {
+        return this.drawing ? structuredClone(this.drawing) : null;
+    }
+    updateDraft() {
+        if (!this.drawing)
+            return;
+        const patches = Object.entries(draftObjects(this.drawing)).map(([layerId, objects]) => this.scene.setLayerObjects(layerId, objects));
+        this.push(mergePatches(...patches));
+        this.emitter.emit('drawing', structuredClone(this.drawing));
+    }
+    // ---------------------------------------------------------------- selection + hover
+    getSelection() {
+        return this.selection.get();
+    }
+    selectObject(objectId, source = 'api') {
+        this.assertAlive();
+        if (this.selection.set([objectId], source))
+            this.afterSelection();
+    }
+    clearSelection(source = 'api') {
+        this.assertAlive();
+        if (this.selection.clear(source))
+            this.afterSelection();
+    }
+    setSelection(selection) {
+        this.assertAlive();
+        if (this.selection.set(selection.objectIds, selection.source, selection.primaryObjectId))
+            this.afterSelection();
+    }
+    afterSelection() {
+        const ctx = this.selection.get();
+        this.push(this.scene.setSelection(ctx));
+        this.emitter.emit('selection', ctx);
+    }
+    setSelectable(enabled) {
+        this.selectable = enabled;
+    }
+    onPick(e) {
+        if (this.current === 'destroyed')
+            return;
+        // While drawing, a click on an object is a point of the drawing, never a selection.
+        if (this.drawing)
+            return void (e.position && this.addDrawingPoint(e.position));
+        // A decoration (error area, ring, footprint, alternative) stands for its object.
+        const owner = decorationOwner(e.layerId, e.objectId);
+        const layerId = owner?.layerId ?? e.layerId;
+        const objectId = owner?.objectId ?? e.objectId;
+        if (e.position)
+            this.emitter.emit('click', { position: e.position, hit: { objectId, layerId } });
+        if (!this.selectable)
+            return;
+        if (SELECTABLE_OVERLAYS.has(layerId))
+            return this.selectObject(objectId, 'map');
+        const layer = this.layers.get(layerId);
+        if (!layer || layer.interaction?.selectable === false)
+            return;
+        this.selectObject(objectId, 'map');
+    }
+    onHover(e) {
+        if (this.current === 'destroyed')
+            return;
+        let hit = e;
+        if (e) {
+            const owner = decorationOwner(e.layerId, e.objectId);
+            hit = owner ? { ...e, ...owner } : e;
+            const layer = this.layers.get(hit.layerId);
+            if (!SELECTABLE_OVERLAYS.has(hit.layerId) && (!layer || layer.interaction?.hoverable === false))
+                return;
+        }
+        this.push(this.scene.setHover(hit ? hit.objectId : null));
+        this.emitter.emit('hover', hit);
+    }
+    // ---------------------------------------------------------------- data
+    getScene() {
+        return this.scene.getState();
+    }
+    getObject(objectId) {
+        const o = this.lookup(objectId);
+        return o ? structuredClone(o) : undefined;
+    }
+    inspect(objectId, source = 'api') {
+        const o = this.lookup(objectId);
+        if (!o)
+            return undefined;
+        const layerIds = [...this.displayed.entries()].filter(([, list]) => list.some((x) => x.objectId === objectId)).map(([id]) => id);
+        this.emitter.emit('objectInspected', { objectId, source, layerIds });
+        const ageing = layerIds.map((id) => this.layers.get(id)?.visualization.age).find((a) => a);
+        const age = ageOf(o, ageing, this.presentNow());
+        return { object: structuredClone(o), layerIds, selected: this.selection.get().objectIds.includes(objectId), time: this.getTime(), ...(age ? { age } : {}) };
+    }
+    queryLoaded(query) {
+        const candidates = query.bounds ? this.index.search(query.bounds) : this.index.all();
+        return rankByRelation(candidates.filter((o) => matchesQuery(o, query)), query).map((o) => structuredClone(o));
+    }
+    async query(query, signal) {
+        this.assertAlive();
+        const started = this.now();
+        try {
+            const raw = await this.deps.provider.query(structuredClone(query), signal);
+            // Untrusted input: keep only well-formed objects (doc §64).
+            const objects = raw.filter((o) => o && typeof o.objectId === 'string' && validateGeometry(o.geometry).valid);
+            this.emitter.emit('spatialQuery', { query: structuredClone(query), count: objects.length, durationMs: this.now() - started });
+            return objects;
+        }
+        catch (e) {
+            if (isAbortError(e))
+                throw e;
+            const error = new MapEngineError('PROVIDER_ERROR', `spatial query failed: ${errorMessage(e)}`, undefined, { cause: e });
+            this.emitter.emit('spatialQuery', { query: structuredClone(query), count: 0, durationMs: this.now() - started, error: error.message });
+            throw error;
+        }
+    }
+    getStats() {
+        return structuredClone(this.stats);
+    }
+    async whenIdle() {
+        while (this.timer !== null || this.inflight) {
+            if (this.inflight)
+                await this.inflight;
+            else
+                await new Promise((r) => setTimeout(r, this.debounceMs + 1));
+        }
+    }
+    refresh() {
+        this.assertAlive();
+        if (!this.mounted)
+            return Promise.reject(new MapEngineError('NOT_MOUNTED', 'mount the runtime before loading data'));
+        this.cancelScheduled();
+        this.controller?.abort(); // a newer request supersedes the older one
+        const controller = new AbortController();
+        this.controller = controller;
+        const run = this.load(controller.signal).finally(() => {
+            if (this.inflight === run)
+                this.inflight = null;
+        });
+        this.inflight = run;
+        return run;
+    }
+    /** Ontology first (doc 12): a type without spatial capability is reported, never guessed (doc 20). Cached per type. */
+    resolveBinding(ontologyType) {
+        let p = this.bindings.get(ontologyType);
+        if (!p) {
+            p = this.deps.ontology.resolve(ontologyType).then((r) => isMissingCapability(r)
+                ? { error: new MapEngineError('MISSING_CAPABILITY', `${ontologyType}: ${r.reason}`, { ontologyType }) }
+                : r, (e) => {
+                this.bindings.delete(ontologyType); // retry next load
+                return { error: new MapEngineError('PROVIDER_ERROR', `ontology lookup for ${ontologyType} failed: ${errorMessage(e)}`, { ontologyType }, { cause: e }) };
+            });
+            this.bindings.set(ontologyType, p);
+        }
+        return p;
+    }
+    /** What every provider query carries besides its filters (doc §13): the zoom, and the range while replaying. */
+    queryHints() {
+        return { zoom: this.viewport.zoom, ...(this.time.mode === 'replay' ? { time: { ...this.time.range } } : {}) };
+    }
+    async load(signal) {
+        const started = Date.now();
+        let visible = this.layers.visible();
+        this.unsubscribeRealtime();
+        if (!visible.length) {
+            this.setState('ready');
+            return;
+        }
+        this.setState('loading');
+        const patches = [];
+        let failed = 0;
+        for (const l of visible)
+            if (!this.layerStatus.has(l.id))
+                this.setStatus(l.id, 'loading');
+        if (this.deps.ontology) {
+            const resolved = await Promise.all(visible.map((l) => (l.source.ontologyType ? this.resolveBinding(l.source.ontologyType) : Promise.resolve(null))));
+            if (signal.aborted || this.current === 'destroyed')
+                return;
+            visible = visible.filter((layer, i) => {
+                const r = resolved[i];
+                if (!r)
+                    return true;
+                if ('error' in r) {
+                    failed++;
+                    this.emitter.emit('error', new MapEngineError(r.error.code, `layer ${layer.id}: ${r.error.message}`, { ...r.error.details, layerId: layer.id }));
+                    this.setStatus(layer.id, r.error.code === 'MISSING_CAPABILITY' ? 'missing-capability' : 'error', r.error.message);
+                    this.layerData.delete(layer.id);
+                    this.displayed.delete(layer.id);
+                    patches.push(this.showId(layer.id, []));
+                    return false;
+                }
+                if (geometryFamily(r.geometryType) !== geometryFamily(SOURCE_GEOMETRY_FOR[layer.visualization.type])) {
+                    this.emitter.emit('warning', new MapEngineError('INVALID_LAYER', `layer ${layer.id} draws ${layer.visualization.type} but ${r.ontologyType} is a ${r.geometryType}`, { layerId: layer.id }));
+                }
+                return true;
+            });
+        }
+        const bounds = this.withBounds(this.viewport).bounds;
+        // Track layers get their data from the history provider and link layers from the link provider, not from
+        // object queries.
+        const trackLayers = visible.filter((l) => l.visualization.type === 'track');
+        const linkLayers = visible.filter((l) => l.visualization.type === 'link');
+        visible = visible.filter((l) => !isDerived(l));
+        const plan = planQueries(visible, bounds, this.deps.provider.capabilities, this.queryHints());
+        this.stats.lastPlan = { calls: plan.calls.length, layers: plan.layers, deduplicated: plan.deduplicated, pushedDown: plan.pushedDown };
+        this.stats.providerCalls += plan.calls.length;
+        const results = await Promise.allSettled(plan.calls.map((c) => this.deps.provider.query(c.query, signal)));
+        if (signal.aborted || this.current === 'destroyed')
+            return;
+        results.forEach((res, i) => {
+            const call = plan.calls[i];
+            if (res.status === 'rejected') {
+                if (isAbortError(res.reason))
+                    return;
+                for (const layerId of call.layerIds) {
+                    if (isDenied(res.reason)) {
+                        // Refused for this user: an expected state, not a failure. The layer shows nothing and says why.
+                        this.denied(layerId, errorMessage(res.reason));
+                        this.layerData.delete(layerId);
+                        this.displayed.delete(layerId);
+                        patches.push(this.showId(layerId, []));
+                        continue;
+                    }
+                    failed++;
+                    this.setStatus(layerId, 'error', errorMessage(res.reason));
+                    this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `layer ${layerId}: ${errorMessage(res.reason)}`, { layerId }, { cause: res.reason }));
+                }
+                return; // keep those layers' last good objects
+            }
+            const valid = this.validated(res.value, call.layerIds.join(','));
+            for (const layerId of call.layerIds) {
+                const layer = this.layers.get(layerId);
+                // Exact client check of the layer's own query: needed when spatial parts were not pushed down,
+                // and harmless (cheap) when they were.
+                const q = layerQuery(layer, bounds);
+                const objects = rankByRelation(valid.filter((o) => matchesQuery(o, q)), q);
+                this.layerData.set(layerId, objects);
+                this.setStatus(layerId, 'ok');
+                if (this.time.mode === 'live') {
+                    this.displayed.set(layerId, objects);
+                    patches.push(this.showId(layerId, objects));
+                }
+            }
+        });
+        // Live objects do not wait for trails: history can be far slower than the latest values.
+        if (this.time.mode === 'live' && trackLayers.length && patches.length) {
+            this.rebuildIndex();
+            this.push(mergePatches(...patches.splice(0)));
+        }
+        failed += await this.loadHistory(trackLayers, visible, bounds, signal);
+        if (signal.aborted || this.current === 'destroyed')
+            return;
+        failed += await this.loadJournal(visible, bounds, signal);
+        if (signal.aborted || this.current === 'destroyed')
+            return;
+        if (this.time.mode === 'replay') {
+            patches.push(this.replayPatch());
+            this.computeReplayEvents();
+        }
+        else {
+            for (const l of trackLayers)
+                patches.push(this.trailPatch(l));
+            this.observeGeofences(visible.flatMap((l) => readingsFrom(this.layerData.get(l.id) ?? [], l.id, toIso(this.now()))));
+        }
+        this.rebuildIndex();
+        // Links join objects that are on the map, so they load once those are known.
+        failed += await this.loadLinks(linkLayers, signal);
+        if (signal.aborted || this.current === 'destroyed')
+            return;
+        for (const l of linkLayers)
+            patches.push(this.linkPatch(l));
+        patches.push(this.overlayPatch());
+        this.push(mergePatches(...patches));
+        this.scheduleAge();
+        this.stats.loads++;
+        this.stats.lastLoadMs = Date.now() - started;
+        this.setState(failed > 0 && failed >= this.layers.visible().length ? 'error' : 'ready');
+        // Live only: replay shows the past, so the stream waits until the map is live again.
+        if (this.time.mode === 'live') {
+            this.subscribeRealtime(plan, results.map((r) => r.status === 'fulfilled'));
+            this.subscribeTrails(trackLayers, bounds);
+        }
+    }
+    // ---------------------------------------------------------------- time (doc 07)
+    setTime(setting) {
+        this.assertAlive();
+        if (setting.mode === 'live') {
+            if (this.time.mode === 'live')
+                return;
+            this.time = { mode: 'live' };
+            this.replayTracks.clear();
+            this.journalData.clear();
+            this.emitter.emit('time', this.getTime());
+            if (this.mounted)
+                this.refresh().catch((e) => this.emitter.emit('error', toEngineError(e)));
+            return;
+        }
+        const at = toMs(setting.at);
+        if (!Number.isFinite(at))
+            throw new MapEngineError('INVALID_LAYER', `replay time "${setting.at}" is not a valid ISO timestamp`);
+        const current = this.time.mode === 'replay' ? this.time.range : undefined;
+        const range = setting.range ?? (current && toMs(current.start) <= at && at <= toMs(current.end) ? current : { start: toIso(at - 2 * 3600_000), end: toIso(at) });
+        if (!(toMs(range.end) > toMs(range.start)) || at < toMs(range.start) || at > toMs(range.end)) {
+            throw new MapEngineError('INVALID_LAYER', 'replay time must lie inside its range, and the range must end after it starts');
+        }
+        const needsLoad = this.time.mode === 'live' || !current || current.start !== range.start || current.end !== range.end;
+        this.time = { mode: 'replay', at: toIso(at), range };
+        this.emitter.emit('time', this.getTime());
+        if (!this.mounted)
+            return;
+        if (needsLoad) {
+            this.unsubscribeRealtime();
+            this.refresh().catch((e) => this.emitter.emit('error', toEngineError(e)));
+        }
+        else
+            this.scheduleReplay();
+    }
+    getTime() {
+        return structuredClone(this.time);
+    }
+    // ---------------------------------------------------------------- geofencing (doc 15)
+    setGeofences(geofences) {
+        this.assertAlive();
+        const ids = new Set();
+        for (const g of geofences) {
+            const v = validateGeofence(g);
+            if (!v.valid)
+                throw new MapEngineError('INVALID_GEOFENCE', v.reason, { geofenceId: g?.id });
+            if (ids.has(g.id))
+                throw new MapEngineError('INVALID_GEOFENCE', `geofence ${g.id} appears twice`, { geofenceId: g.id });
+            ids.add(g.id);
+        }
+        const previous = new Map(this.geofence.geofences().map((g) => [g.id, g]));
+        this.geofence.setGeofences(geofences);
+        this.stats.geofence.geofences = geofences.length;
+        const changes = [];
+        for (const g of geofences) {
+            const old = previous.get(g.id);
+            if (!old)
+                changes.push({ action: 'created', geofenceId: g.id });
+            else if (!deepEqual(old, g))
+                changes.push({ action: 'updated', geofenceId: g.id });
+        }
+        for (const id of previous.keys())
+            if (!ids.has(id))
+                changes.push({ action: 'removed', geofenceId: id });
+        if (this.time.mode === 'replay')
+            this.computeReplayEvents();
+        else {
+            // New or changed geofences start from where objects are now, silently (no "enter" storm).
+            const readings = [...this.displayed.entries()].flatMap(([layerId, objects]) => this.layers.get(layerId)?.visualization.type === 'track' ? [] : readingsFrom(objects, layerId, toIso(this.now())));
+            this.observeGeofences(readings);
+        }
+        this.emitter.emit('geofences', this.geofence.geofences());
+        for (const c of changes)
+            this.emitter.emit('geofenceChanged', c);
+    }
+    getGeofences() {
+        return this.geofence.geofences();
+    }
+    getGeofenceEvents(limit = 200) {
+        if (this.time.mode === 'replay') {
+            const at = toMs(this.time.at);
+            return this.replayEvents.filter((e) => toMs(e.timestamp) <= at).reverse().slice(0, limit).map((e) => structuredClone(e));
+        }
+        return this.geofenceLog.slice(0, limit).map((e) => structuredClone(e));
+    }
+    getGeofenceOccupancy() {
+        if (this.time.mode !== 'replay')
+            return this.geofence.occupancy();
+        // At the replay time: plain inside test on the replayed positions.
+        const out = {};
+        for (const g of this.geofence.geofences()) {
+            if (!g.enabled)
+                continue;
+            const inside = new Set();
+            for (const [layerId, objects] of this.displayed) {
+                if (this.layers.get(layerId)?.visualization.type === 'track')
+                    continue;
+                for (const r of readingsFrom(objects, layerId, this.time.at)) {
+                    if (watches(g, r) && within({ type: 'Point', coordinates: r.position }, g.geometry))
+                        inside.add(r.objectId);
+                }
+            }
+            out[g.id] = [...inside].sort();
+        }
+        return out;
+    }
+    observeGeofences(readings) {
+        for (const r of readings) {
+            for (const e of this.geofence.observe(r)) {
+                this.geofenceLog.unshift(e);
+                this.stats.geofence.liveEvents++;
+                this.emitter.emit('geofence', e);
+            }
+        }
+        if (this.geofenceLog.length > 500)
+            this.geofenceLog.length = 500;
+    }
+    computeReplayEvents() {
+        const tracks = [...this.replayTracks.entries()].flatMap(([layerId, m]) => [...m.values()].map((track) => ({ track, layerId })));
+        this.replayEvents = evaluateTracks(this.geofence.geofences(), tracks);
+        this.stats.geofence.replayEvents = this.replayEvents.length;
+    }
+    /** Fetches trails (track layers) and, in replay, the tracks of point layers. Returns the number of failed layers. */
+    async loadHistory(trackLayers, dataLayers, bounds, signal) {
+        const history = this.deps.history;
+        const replay = this.time.mode === 'replay' ? this.time : null;
+        const pointLayers = replay ? dataLayers.filter((l) => GEOMETRY_FOR[l.visualization.type] === 'Point') : [];
+        if (!trackLayers.length && !pointLayers.length)
+            return 0;
+        if (!history) {
+            if (!this.warnedNoHistory && trackLayers.length) {
+                this.warnedNoHistory = true;
+                this.emitter.emit('warning', new MapEngineError('MISSING_CAPABILITY', 'track layers and replay need a history provider (deps.history)'));
+            }
+            return 0;
+        }
+        const nowMs = this.now();
+        const jobs = [
+            ...trackLayers.map((layer) => {
+                const windowMs = (layer.visualization.track?.windowMinutes ?? 30) * 60_000;
+                const range = replay ? replay.range : { start: toIso(nowMs - windowMs), end: toIso(nowMs) };
+                return { layer, range, store: this.trailData };
+            }),
+            ...pointLayers.map((layer) => ({ layer, range: replay.range, store: this.replayTracks })),
+        ];
+        this.stats.temporal.trackFetches += jobs.length;
+        const results = await Promise.allSettled(jobs.map((j) => history.getTracks({ ...layerQuery(j.layer, bounds, { zoom: this.viewport.zoom }), geometryType: 'Point' }, j.range, signal)));
+        if (signal.aborted)
+            return 0;
+        let failed = 0;
+        results.forEach((res, i) => {
+            const { layer, store } = jobs[i];
+            if (res.status === 'rejected') {
+                if (isAbortError(res.reason))
+                    return;
+                if (isDenied(res.reason))
+                    return this.denied(layer.id, errorMessage(res.reason));
+                failed++;
+                if (layer.visualization.type === 'track')
+                    this.setStatus(layer.id, 'error', errorMessage(res.reason));
+                this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `layer ${layer.id} history: ${errorMessage(res.reason)}`, { layerId: layer.id }, { cause: res.reason }));
+                return;
+            }
+            const tracks = new Map();
+            for (const t of res.value) {
+                const v = validateTrack(t);
+                if (!v.valid) {
+                    this.emitter.emit('warning', new MapEngineError('INVALID_GEOMETRY', v.reason, { layerId: layer.id }));
+                    continue;
+                }
+                tracks.set(t.objectId, normalizeTrack(t));
+            }
+            this.stats.temporal.tracksLoaded += tracks.size;
+            store.set(layer.id, tracks);
+            if (layer.visualization.type === 'track')
+                this.setStatus(layer.id, 'ok');
+        });
+        return failed;
+    }
+    /** Trail objects (LineStrings) for a track layer, ending now (live) or at the replay time. */
+    trailObjects(layer) {
+        const tracks = this.trailData.get(layer.id);
+        if (!tracks)
+            return [];
+        const replayAt = this.time.mode === 'replay' ? toMs(this.time.at) : null;
+        const windowMs = (layer.visualization.track?.windowMinutes ?? 30) * 60_000;
+        const out = [];
+        for (const t of tracks.values()) {
+            // Live trails end at now or at the newest point if a device clock runs slightly ahead of ours.
+            const last = t.points.length ? toMs(t.points[t.points.length - 1].timestamp) : 0;
+            const end = replayAt ?? Math.max(this.now(), last);
+            const coords = trailBetween(t, end - windowMs, end);
+            if (coords.length < 2)
+                continue;
+            out.push({ objectId: t.objectId, geometry: { type: 'LineString', coordinates: coords }, properties: { points: coords.length }, observedAt: toIso(end) });
+        }
+        return out;
+    }
+    trailPatch(layer) {
+        const objects = this.trailObjects(layer);
+        this.displayed.set(layer.id, objects);
+        return this.scene.setLayerObjects(layer.id, objects);
+    }
+    /**
+     * The world at the replay time (doc 29 §8). With a journal, every object is what its last journal entry before
+     * that time says (created later or removed before: not there). With tracks, point objects move along them.
+     * Objects neither says anything about are treated as static and stay as they are now. Objects with a track but
+     * no observation at that time are hidden. Replay sets `properties.heading` and `properties.speed` from the track
+     * so icons can rotate.
+     */
+    replayPatch() {
+        if (this.time.mode !== 'replay')
+            return {};
+        const atMs = toMs(this.time.at);
+        const bounds = this.withBounds(this.viewport).bounds;
+        const patches = [];
+        for (const layer of this.layers.visible()) {
+            if (layer.visualization.type === 'track') {
+                patches.push(this.trailPatch(layer));
+                continue;
+            }
+            if (isDerived(layer))
+                continue;
+            const tracks = GEOMETRY_FOR[layer.visualization.type] === 'Point' ? this.replayTracks.get(layer.id) : undefined;
+            const journal = this.journalData.get(layer.id);
+            if (!tracks && !journal)
+                continue;
+            const current = new Map((this.layerData.get(layer.id) ?? []).map((o) => [o.objectId, o]));
+            const ids = new Set([...current.keys(), ...(tracks?.keys() ?? []), ...(journal?.keys() ?? [])]);
+            const q = layerQuery(layer, bounds);
+            const objects = [];
+            for (const id of ids) {
+                const said = journal ? journalStateAt(journal.get(id), atMs) : undefined;
+                if (said === null)
+                    continue; // not there at that time
+                let o = said ? { ...said, objectId: id } : current.get(id);
+                const track = tracks?.get(id);
+                if (track) {
+                    const s = stateAt(track, atMs);
+                    if (s) {
+                        o = {
+                            ...(o ?? { objectId: id }),
+                            objectId: id,
+                            geometry: { type: 'Point', coordinates: s.position },
+                            properties: { ...(o?.properties ?? track.properties ?? {}), ...(s.heading !== undefined ? { heading: s.heading } : {}), ...(s.speed !== undefined ? { speed: s.speed } : {}) },
+                            observedAt: toIso(atMs),
+                        };
+                    }
+                    else if (said === undefined)
+                        continue; // a moving object with no position at that time
+                }
+                if (o && validateGeometry(o.geometry).valid && matchesQuery(o, { ...q, objectIds: undefined }))
+                    objects.push(o);
+            }
+            const ranked = rankByRelation(objects, q);
+            this.displayed.set(layer.id, ranked);
+            patches.push(this.show(layer, ranked));
+        }
+        return mergePatches(...patches);
+    }
+    /** After the index follows the objects: links between them and the highlight halo move with them. */
+    followPatch() {
+        const patches = [];
+        for (const layer of this.layers.visible())
+            if (layer.visualization.type === 'link')
+                patches.push(this.linkPatch(layer));
+        if (this.highlighted)
+            patches.push(this.overlayPatch());
+        return mergePatches(...patches);
+    }
+    /** Replay only: the journal of each data layer for the range, grouped by object (doc 29 §7). */
+    async loadJournal(layers, bounds, signal) {
+        this.journalData.clear();
+        if (this.time.mode !== 'replay' || !layers.length)
+            return 0;
+        const journal = this.deps.journal;
+        if (!journal) {
+            this.warnOnce('journal', 'replay rebuilds positions only: whole objects at a time (status, readings, appearing and disappearing) need an event journal (deps.journal)');
+            return 0;
+        }
+        const range = this.time.range;
+        const results = await Promise.allSettled(layers.map((l) => journal.getJournal(layerQuery(l, bounds, { zoom: this.viewport.zoom }), range, signal)));
+        if (signal.aborted)
+            return 0;
+        let failed = 0;
+        results.forEach((res, i) => {
+            const layer = layers[i];
+            if (res.status === 'rejected') {
+                if (isAbortError(res.reason))
+                    return;
+                if (isDenied(res.reason))
+                    return this.denied(layer.id, errorMessage(res.reason));
+                failed++;
+                this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `layer ${layer.id} journal: ${errorMessage(res.reason)}`, { layerId: layer.id }, { cause: res.reason }));
+                return;
+            }
+            const valid = res.value.filter((e) => !e.object || validateGeometry(e.object.geometry).valid);
+            this.journalData.set(layer.id, groupJournal(valid));
+        });
+        return failed;
+    }
+    /** Links touching the objects each link layer joins (doc 28 G4). Returns the number of failed layers. */
+    async loadLinks(linkLayers, signal) {
+        if (!linkLayers.length)
+            return 0;
+        const links = this.deps.links;
+        if (!links) {
+            for (const l of linkLayers)
+                this.setStatus(l.id, 'missing-capability', 'link layers need a link provider (deps.links)');
+            this.warnOnce('links', 'link layers need a link provider (deps.links)');
+            return 0;
+        }
+        let failed = 0;
+        await Promise.all(linkLayers.map(async (layer) => {
+            const ends = this.linkEnds(layer);
+            if (!ends.length) {
+                this.linkData.set(layer.id, []);
+                this.setStatus(layer.id, 'ok');
+                return;
+            }
+            try {
+                const list = await links.getLinks(ends, layer.visualization.link?.types, signal);
+                this.linkData.set(layer.id, list.filter((k) => k && typeof k.id === 'string' && typeof k.fromId === 'string' && typeof k.toId === 'string'));
+                this.setStatus(layer.id, 'ok');
+            }
+            catch (e) {
+                if (isAbortError(e))
+                    return;
+                if (isDenied(e))
+                    return this.denied(layer.id, errorMessage(e));
+                failed++;
+                this.setStatus(layer.id, 'error', errorMessage(e));
+                this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `layer ${layer.id} links: ${errorMessage(e)}`, { layerId: layer.id }, { cause: e }));
+            }
+        }));
+        return failed;
+    }
+    /** The objects on the map a link layer joins: its source's objectIds, or the objects of its source's type. */
+    linkEnds(layer) {
+        const s = layer.source;
+        if (s.objectIds)
+            return [...s.objectIds];
+        const out = new Set();
+        for (const [layerId, list] of this.displayed) {
+            const l = this.layers.get(layerId);
+            if (!l || isDerived(l) || (s.ontologyType !== undefined && l.source.ontologyType !== s.ontologyType))
+                continue;
+            for (const o of list)
+                out.add(o.objectId);
+        }
+        return [...out];
+    }
+    /** A link layer's lines between where its ends are now; a link with an end not on the map is not drawn. */
+    linkPatch(layer) {
+        const objects = [];
+        for (const k of this.linkData.get(layer.id) ?? []) {
+            const a = this.index.get(k.fromId);
+            const b = this.index.get(k.toId);
+            if (!a || !b)
+                continue;
+            objects.push({ objectId: k.id, geometry: { type: 'LineString', coordinates: [endPosition(a), endPosition(b)] }, properties: { ...k.properties, type: k.type ?? '', fromId: k.fromId, toId: k.toId } });
+        }
+        this.displayed.set(layer.id, objects);
+        return this.show(layer, objects);
+    }
+    /** Scrubbing: many time changes → one re-interpolation per frame. */
+    scheduleReplay() {
+        if (this.replayQueued)
+            return;
+        this.replayQueued = true;
+        this.frame(() => {
+            this.replayQueued = false;
+            if (this.current === 'destroyed' || this.time.mode !== 'replay')
+                return;
+            this.stats.temporal.replayFrames++;
+            const patch = this.replayPatch();
+            this.rebuildIndex();
+            this.push(mergePatches(patch, this.followPatch()));
+        });
+    }
+    /** Live trails: track layers listen to point updates of their objects and grow (and trim) their trails. */
+    subscribeTrails(trackLayers, bounds) {
+        const rt = this.deps.realtime;
+        if (!rt || !this.deps.history)
+            return;
+        for (const layer of trackLayers) {
+            const off = rt.subscribe({ ...layerQuery(layer, bounds, { zoom: this.viewport.zoom }), geometryType: 'Point' }, (patch) => this.enqueue([layer.id], patch, true), (e) => this.onRealtimeError(e));
+            this.subscriptions.push(off);
+        }
+        this.stats.realtime.subscriptions = this.subscriptions.length;
+    }
+    // ---------------------------------------------------------------- realtime (snapshot + stream)
+    subscribeRealtime(plan, loaded) {
+        const rt = this.deps.realtime;
+        if (!rt)
+            return;
+        plan.calls.forEach((call, i) => {
+            if (!loaded[i])
+                return; // no snapshot, no stream
+            const off = rt.subscribe(call.query, (patch) => this.enqueue(call.layerIds, patch), (e) => this.onRealtimeError(e));
+            this.subscriptions.push(off);
+        });
+        this.stats.realtime.subscriptions = this.subscriptions.length;
+    }
+    unsubscribeRealtime() {
+        for (const off of this.subscriptions) {
+            try {
+                off();
+            }
+            catch {
+                // Unsubscribing must not fail a load.
+            }
+        }
+        this.subscriptions = [];
+        this.stats.realtime.subscriptions = 0;
+    }
+    onRealtimeError(error) {
+        if (this.current === 'destroyed')
+            return;
+        this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `realtime: ${error.message}`, undefined, { cause: error }));
+        this.unsubscribeRealtime();
+        if (this.reconnectTimer !== null)
+            return;
+        // Reconnect = fresh snapshot, then stream again (ADR-015).
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.current === 'destroyed' || !this.mounted)
+                return;
+            this.stats.realtime.reconnects++;
+            this.refresh().catch((e) => this.emitter.emit('error', toEngineError(e)));
+        }, this.reconnectMs);
+    }
+    /** Many events → one frame (doc 14 backpressure). */
+    enqueue(layerIds, patch, trail = false) {
+        if (this.current === 'destroyed' || this.time.mode !== 'live')
+            return;
+        this.stats.realtime.received += (patch.upserted?.length ?? 0) + (patch.removed?.length ?? 0);
+        this.pending.push({ layerIds, patch, trail });
+        if (this.frameQueued)
+            return;
+        this.frameQueued = true;
+        this.frame(() => this.flush());
+    }
+    flush() {
+        this.frameQueued = false;
+        if (this.current === 'destroyed' || !this.pending.length)
+            return;
+        const batch = this.pending;
+        this.pending = [];
+        this.stats.realtime.frames++;
+        const bounds = this.withBounds(this.viewport).bounds;
+        const { touched, changes, fresh, trails } = applyFrame(batch, {
+            layer: (id) => this.layers.get(id),
+            current: (id) => this.layerData.get(id) ?? [],
+            bounds,
+            trustUntil: this.now() + this.skewToleranceMs,
+            counters: this.stats.realtime,
+            warn: (w) => this.emitter.emit('warning', w),
+            saw: (o, layerId) => this.checkSkew(o, layerId),
+            trail: (layerId, patch) => this.appendTrail(layerId, patch),
+        });
+        const liveReadings = fresh.flatMap(({ layerId, object }) => readingsFrom([object], layerId, toIso(this.now())));
+        const patches = [];
+        let fullIndex = false;
+        for (const [layerId, objects] of touched) {
+            const layer = this.layers.get(layerId);
+            const ranked = layer?.source.spatialQuery?.relation === 'nearest';
+            if (ranked || !layer) {
+                // Rankings (nearest) are re-applied after live changes: one move can change who is in. Limitation: an
+                // object ranked out is dropped until the next snapshot, even if a closer one later moves away.
+                const list = layer ? rankByRelation([...objects.values()], layerQuery(layer, bounds)) : [...objects.values()];
+                this.layerData.set(layerId, list);
+                this.displayed.set(layerId, list);
+                patches.push(this.showId(layerId, list));
+                fullIndex = true;
+                continue;
+            }
+            const list = [...objects.values()];
+            this.layerData.set(layerId, list);
+            this.displayed.set(layerId, list);
+            const c = changes.get(layerId);
+            if (c)
+                patches.push(this.showChanges(layer, c.upserted.values(), c.removed, list));
+        }
+        for (const layerId of trails) {
+            const layer = this.layers.get(layerId);
+            if (layer && layer.visible)
+                patches.push(this.trailPatch(layer));
+        }
+        if (fullIndex)
+            this.rebuildIndex();
+        else {
+            // Once per frame, not per object (layers.get copies the layer).
+            const derived = new Set(this.layers.list().filter(isDerived).map((l) => l.id));
+            patchIndex(this.index, changes, touched, this.displayed, (id) => derived.has(id));
+        }
+        patches.push(this.followPatch());
+        this.push(mergePatches(...patches));
+        this.observeGeofences(liveReadings);
+        this.scheduleAgeSoon();
+    }
+    /** Grows trails from live point updates; drops points older than the layer's window. Returns true if changed. */
+    appendTrail(layerId, patch) {
+        const layer = this.layers.get(layerId);
+        if (!layer || !layer.visible)
+            return false;
+        let tracks = this.trailData.get(layerId);
+        if (!tracks)
+            this.trailData.set(layerId, (tracks = new Map()));
+        const keepFrom = this.now() - (layer.visualization.track?.windowMinutes ?? 30) * 60_000;
+        const { changed, added } = growTrails(tracks, patch, keepFrom, this.now());
+        this.stats.temporal.trailPointsAppended += added;
+        return changed;
+    }
+    /** Untrusted provider data: drop invalid geometry and duplicate ids, report each as a warning. */
+    validated(objects, layerId) {
+        const seen = new Set();
+        const out = [];
+        for (const o of objects) {
+            if (!o || typeof o.objectId !== 'string' || o.objectId === '') {
+                this.emitter.emit('warning', new MapEngineError('INVALID_GEOMETRY', `layer ${layerId}: object without objectId skipped`, { layerId }));
+                continue;
+            }
+            const v = validateGeometry(o.geometry);
+            if (!v.valid) {
+                this.emitter.emit('warning', new MapEngineError('INVALID_GEOMETRY', `${o.objectId}: ${v.reason}`, { layerId, objectId: o.objectId }));
+                continue;
+            }
+            if (seen.has(o.objectId))
+                continue;
+            seen.add(o.objectId);
+            this.checkSkew(o, layerId);
+            out.push(o);
+        }
+        return out;
+    }
+    /** Reports, once per object, an observation time ahead of this clock beyond the tolerance (doc 14). */
+    checkSkew(o, layerId) {
+        if (!o.observedAt || this.skewed.has(o.objectId))
+            return;
+        const ahead = Date.parse(o.observedAt) - this.now();
+        if (!(ahead > this.skewToleranceMs))
+            return;
+        this.skewed.add(o.objectId);
+        this.emitter.emit('warning', new MapEngineError('CLOCK_SKEW', `${o.objectId}: observedAt ${o.observedAt} is ${Math.round(ahead / 1000)} s ahead of this clock`, { layerId, objectId: o.objectId, observedAt: o.observedAt, aheadMs: ahead }));
+    }
+    rebuildIndex() {
+        this.index.clear();
+        for (const [layerId, objects] of this.displayed) {
+            const layer = this.layers.get(layerId);
+            // Trails share their object's id and links are drawn between objects: derived, not objects. Keep them out.
+            if (!layer || isDerived(layer))
+                continue;
+            for (const o of objects)
+                this.index.insert(o);
+        }
+    }
+    // ---------------------------------------------------------------- measuring and references (doc 28 G8, G9)
+    measure(geometry) {
+        const v = validateGeometry(geometry);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_GEOMETRY', v.reason);
+        return measureGeometry(geometry);
+    }
+    async resolveReference(objectId) {
+        this.assertAlive();
+        const o = this.lookup(objectId);
+        // Shown = drawn by an application layer (an engine halo or decoration does not count).
+        const drawn = this.scene.getState().objects.some((so) => so.object.objectId === objectId && !so.layerId.startsWith('__'));
+        if (o)
+            return { status: drawn || this.annotationStore.has(objectId) || this.proposals.has(objectId) ? 'shown' : 'loaded', object: structuredClone(o) };
+        try {
+            const found = (await this.deps.provider.getCurrentState([objectId])).find((x) => x?.objectId === objectId);
+            if (found && validateGeometry(found.geometry).valid)
+                return { status: 'available', object: found };
+        }
+        catch {
+            // A failed lookup and a missing object read the same to the person: not available to them.
+        }
+        return { status: 'unavailable' };
+    }
+    /** A loaded object, an annotation or a proposal, by id. */
+    lookup(id) {
+        const o = this.index.get(id);
+        if (o)
+            return o;
+        const a = this.annotationStore.get(id);
+        if (a)
+            return { objectId: a.id, geometry: a.geometry, properties: { label: a.label ?? '', note: a.note ?? '', kind: a.kind, ...(a.author ? { author: a.author } : {}) } };
+        const p = this.proposals.get(id);
+        if (p)
+            return { objectId: p.id, geometry: p.geometry, properties: { label: p.label ?? '', note: p.note ?? '', origin: p.origin } };
+        return undefined;
+    }
+    // ---------------------------------------------------------------- identity and access (doc 28 G13)
+    getLayerStatus(layerId) {
+        return this.layerStatus.get(layerId);
+    }
+    setStatus(layerId, status, reason) {
+        if (this.layerStatus.get(layerId) === status)
+            return;
+        this.layerStatus.set(layerId, status);
+        this.emitter.emit('layerStatus', { layerId, status, ...(reason ? { reason } : {}) });
+    }
+    /** A layer refused for this user: its status says so, with one warning, and it is not counted as a failure. */
+    denied(layerId, reason) {
+        if (this.layerStatus.get(layerId) !== 'denied')
+            this.emitter.emit('warning', new MapEngineError('ACCESS_DENIED', `layer ${layerId}: ${reason}`, { layerId }));
+        this.setStatus(layerId, 'denied', reason);
+    }
+    setAuth(auth) {
+        this.assertAlive();
+        if (deepEqual(auth, this.auth))
+            return;
+        this.auth = auth ? structuredClone(auth) : null;
+        this.handAuth();
+        // What the user may see changed: everything is asked again with the new identity.
+        this.bindings.clear();
+        this.layerStatus.clear();
+        if (this.mounted) {
+            void this.loadAnnotations();
+            this.refresh().catch((e) => this.emitter.emit('error', toEngineError(e)));
+        }
+    }
+    /** Hands the identity to every provider that accepts it (the engine itself never decides access). */
+    handAuth() {
+        const d = this.deps;
+        for (const p of new Set([d.provider, d.realtime, d.history, d.ontology, d.elevation, d.links, d.journal, d.annotations]))
+            if (isAuthAware(p))
+                p.setAuth(this.auth ? structuredClone(this.auth) : null);
+    }
+    // ---------------------------------------------------------------- offline profile (doc 28 G14)
+    assertOffline(parts) {
+        const bad = offlineViolations(this.offline, parts);
+        if (!bad.length)
+            return;
+        throw new MapEngineError('OFFLINE_VIOLATION', `offline profile: ${bad.map((b) => `${b.where} = ${b.url}`).join('; ')} would leave the site`, { violations: bad });
+    }
+    // ---------------------------------------------------------------- highlight and proposals (doc 28 G7)
+    highlight(objectIds, options = {}) {
+        this.assertAlive();
+        if (!Array.isArray(objectIds) || !objectIds.every((x) => typeof x === 'string' && x))
+            throw new MapEngineError('INVALID_COMMAND', 'highlight needs object ids');
+        if (this.highlightTimer !== null)
+            clearTimeout(this.highlightTimer);
+        this.highlightTimer = null;
+        const until = options.durationMs ? toIso(this.now() + options.durationMs) : undefined;
+        this.highlighted = { objectIds: [...new Set(objectIds)], ...(options.color ? { color: options.color } : {}), ...(until ? { until } : {}), ...(options.origin ? { origin: options.origin } : {}) };
+        if (options.durationMs)
+            this.highlightTimer = setTimeout(() => this.clearHighlight(), options.durationMs);
+        this.refreshOverlays();
+        this.emitter.emit('highlight', this.getHighlight());
+    }
+    clearHighlight() {
+        if (this.highlightTimer !== null)
+            clearTimeout(this.highlightTimer);
+        this.highlightTimer = null;
+        if (!this.highlighted || this.current === 'destroyed')
+            return;
+        this.highlighted = null;
+        this.refreshOverlays();
+        this.emitter.emit('highlight', null);
+    }
+    getHighlight() {
+        return this.highlighted ? structuredClone(this.highlighted) : null;
+    }
+    newId(prefix) {
+        return `${prefix}-${this.now().toString(36)}-${(++this.idSeq).toString(36)}`;
+    }
+    propose(input) {
+        this.assertAlive();
+        const v = validateGeometry(input?.geometry);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_GEOMETRY', `proposal: ${v.reason}`);
+        const proposal = {
+            id: input.id ?? this.newId('proposal'),
+            geometry: structuredClone(input.geometry),
+            ...(input.label ? { label: input.label } : {}),
+            ...(input.note ? { note: input.note } : {}),
+            origin: input.origin ?? 'user',
+            createdAt: toIso(this.now()),
+        };
+        this.proposals.set(proposal.id, proposal);
+        this.refreshOverlays();
+        this.emitter.emit('proposal', { action: 'proposed', proposal: structuredClone(proposal) });
+        return structuredClone(proposal);
+    }
+    async acceptProposal(id, options = {}) {
+        this.assertAlive();
+        const p = this.proposals.get(id);
+        if (!p)
+            throw new MapEngineError('INVALID_COMMAND', `no proposal ${id}`);
+        const kind = p.geometry.type === 'Point' || p.geometry.type === 'MultiPoint' ? 'point' : p.geometry.type === 'Circle' ? 'circle' : p.geometry.type.includes('Line') ? 'line' : 'polygon';
+        const by = options.by ?? 'user';
+        const annotation = await this.addAnnotation({ kind, geometry: p.geometry, ...((options.label ?? p.label) ? { label: options.label ?? p.label } : {}), ...(p.note ? { note: p.note } : {}), author: by, metadata: { proposedBy: p.origin, proposalId: p.id } }, by);
+        this.proposals.delete(id);
+        this.refreshOverlays();
+        this.emitter.emit('proposal', { action: 'accepted', proposal: structuredClone(p), by, annotationId: annotation.id });
+        return annotation;
+    }
+    rejectProposal(id, options = {}) {
+        this.assertAlive();
+        const p = this.proposals.get(id);
+        if (!p)
+            return;
+        this.proposals.delete(id);
+        this.refreshOverlays();
+        this.emitter.emit('proposal', { action: 'rejected', proposal: structuredClone(p), by: options.by ?? 'user', ...(options.reason ? { reason: options.reason } : {}) });
+    }
+    getProposals() {
+        return [...this.proposals.values()].map((p) => structuredClone(p));
+    }
+    clearProposals(origin) {
+        const gone = [...this.proposals.values()].filter((p) => origin === undefined || p.origin === origin);
+        if (!gone.length)
+            return;
+        for (const p of gone)
+            this.proposals.delete(p.id);
+        this.refreshOverlays();
+        for (const p of gone)
+            this.emitter.emit('proposal', { action: 'cleared', proposal: structuredClone(p) });
+    }
+    // ---------------------------------------------------------------- annotations (doc 29 §5, doc 28 G10)
+    /** Annotations kept by deps.annotations, and changes others make to them. */
+    async loadAnnotations() {
+        const store = this.deps.annotations;
+        if (!store)
+            return;
+        this.annotationSub?.();
+        this.annotationSub = null;
+        try {
+            const list = await store.list();
+            if (this.current === 'destroyed')
+                return;
+            this.annotationStore.clear();
+            for (const a of list)
+                if (a && typeof a.id === 'string' && validateGeometry(a.geometry).valid)
+                    this.annotationStore.set(a.id, structuredClone(a));
+            this.refreshOverlays();
+        }
+        catch (e) {
+            if (isDenied(e))
+                this.warnOnce('annotations-denied', `annotations: ${errorMessage(e)}`, 'ACCESS_DENIED');
+            else
+                this.emitter.emit('error', new MapEngineError('PROVIDER_ERROR', `annotations: ${errorMessage(e)}`, undefined, { cause: e }));
+        }
+        if (store.subscribe && this.mounted) {
+            this.annotationSub = store.subscribe((change) => {
+                if (this.current === 'destroyed')
+                    return;
+                for (const a of change.upserted ?? [])
+                    if (a && validateGeometry(a.geometry).valid)
+                        this.annotationStore.set(a.id, structuredClone(a));
+                for (const id of change.removed ?? [])
+                    this.annotationStore.delete(id);
+                this.refreshOverlays();
+            });
+        }
+    }
+    checkAnnotation(a) {
+        if (!ANNOTATION_KINDS.includes(a.kind))
+            throw new MapEngineError('INVALID_GEOMETRY', `annotation kind must be one of ${ANNOTATION_KINDS.join(', ')}`);
+        const v = validateGeometry(a.geometry);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_GEOMETRY', `annotation: ${v.reason}`);
+    }
+    /** Saves through deps.annotations; without one the annotation stays in this runtime (reported once). */
+    async persist(a) {
+        const store = this.deps.annotations;
+        if (!store) {
+            this.warnOnce('annotations', 'annotations are kept in this map only: sharing them needs an annotation store (deps.annotations)', 'MISSING_CAPABILITY');
+            return;
+        }
+        try {
+            await store.save(structuredClone(a));
+        }
+        catch (e) {
+            throw new MapEngineError(isDenied(e) ? 'ACCESS_DENIED' : 'PROVIDER_ERROR', `annotation ${a.id} could not be saved: ${errorMessage(e)}`, { annotationId: a.id }, { cause: e });
+        }
+    }
+    async addAnnotation(input, origin = 'user') {
+        this.assertAlive();
+        this.checkAnnotation(input);
+        const a = { ...structuredClone(input), id: input.id ?? this.newId('annotation'), createdAt: toIso(this.now()) };
+        await this.persist(a);
+        if (this.current === 'destroyed')
+            return structuredClone(a);
+        this.annotationStore.set(a.id, a);
+        this.refreshOverlays();
+        this.emitter.emit('annotation', { action: 'created', id: a.id, annotation: structuredClone(a), origin });
+        return structuredClone(a);
+    }
+    async updateAnnotation(id, patch, origin = 'user') {
+        this.assertAlive();
+        const cur = this.annotationStore.get(id);
+        if (!cur)
+            throw new MapEngineError('INVALID_COMMAND', `no annotation ${id}`);
+        const next = { ...cur, ...structuredClone(patch), id, updatedAt: toIso(this.now()) };
+        this.checkAnnotation(next);
+        await this.persist(next);
+        this.annotationStore.set(id, next);
+        this.refreshOverlays();
+        this.emitter.emit('annotation', { action: 'updated', id, annotation: structuredClone(next), origin });
+        return structuredClone(next);
+    }
+    async removeAnnotation(id, origin = 'user') {
+        this.assertAlive();
+        if (!this.annotationStore.has(id))
+            return;
+        if (this.deps.annotations) {
+            try {
+                await this.deps.annotations.remove(id);
+            }
+            catch (e) {
+                throw new MapEngineError(isDenied(e) ? 'ACCESS_DENIED' : 'PROVIDER_ERROR', `annotation ${id} could not be removed: ${errorMessage(e)}`, { annotationId: id }, { cause: e });
+            }
+        }
+        this.annotationStore.delete(id);
+        if (this.selection.get().objectIds.includes(id))
+            this.clearSelection('api');
+        this.refreshOverlays();
+        this.emitter.emit('annotation', { action: 'removed', id, origin });
+    }
+    setAnnotationsVisible(visible) {
+        this.assertAlive();
+        if (visible === this.annotationsVisible)
+            return;
+        this.annotationsVisible = visible;
+        this.refreshOverlays();
+    }
+    getAnnotations() {
+        return [...this.annotationStore.values()].sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? '')).map((a) => structuredClone(a));
+    }
+    // ---------------------------------------------------------------- commands (doc 28 G6)
+    async execute(commands, options = {}) {
+        this.assertAlive();
+        const list = Array.isArray(commands) ? commands : [commands];
+        const origin = options.origin ?? 'user';
+        const finish = (result) => {
+            this.emitter.emit('command', { commands: structuredClone(list), origin, result });
+            return result;
+        };
+        // The whole list is checked before anything runs: refused whole, never half-applied.
+        for (const [i, c] of list.entries()) {
+            const problem = commandProblem(c) ?? this.commandReferenceProblem(c);
+            if (problem)
+                return finish({ ok: false, applied: 0, error: { index: i, reason: problem } });
+        }
+        const results = {};
+        for (const [i, c] of list.entries()) {
+            try {
+                const r = await this.runCommand(c, origin);
+                if (r !== undefined)
+                    results[i] = r;
+            }
+            catch (e) {
+                return finish({ ok: false, applied: i, error: { index: i, reason: errorMessage(e) }, ...(Object.keys(results).length ? { results } : {}) });
+            }
+        }
+        return finish({ ok: true, applied: list.length, ...(Object.keys(results).length ? { results } : {}) });
+    }
+    /** What only the runtime can check before running: layers exist, conditions and geometries are valid. */
+    commandReferenceProblem(c) {
+        switch (c.type) {
+            case 'showLayer':
+            case 'hideLayer':
+                return this.layers.has(c.layerId) ? null : `unknown layer "${c.layerId}"`;
+            case 'setFilter': {
+                if (!this.layers.has(c.layerId))
+                    return `unknown layer "${c.layerId}"`;
+                if (!c.where.length)
+                    return null;
+                const v = validateConditions(c.where, 'where');
+                return v.valid ? null : v.reason;
+            }
+            case 'fitTo':
+                if (c.bounds) {
+                    const b = c.bounds;
+                    const ok = [b.west, b.south, b.east, b.north].every((n) => typeof n === 'number' && Number.isFinite(n)) && b.west <= b.east && b.south <= b.north;
+                    return ok ? null : 'bounds must have west <= east and south <= north';
+                }
+                return null;
+            case 'drawProposal': {
+                const v = validateGeometry(c.geometry);
+                return v.valid ? null : v.reason;
+            }
+            default:
+                return null;
+        }
+    }
+    /** One command, through the runtime's public methods only: the command set adds no behaviour of its own. */
+    async runCommand(c, origin) {
+        switch (c.type) {
+            case 'showLayer':
+                return this.setLayerVisibility(c.layerId, true);
+            case 'hideLayer':
+                return this.setLayerVisibility(c.layerId, false);
+            case 'setFilter': {
+                const { where: _w, ...rest } = this.layers.get(c.layerId).source;
+                return this.updateLayer(c.layerId, { source: c.where.length ? { ...rest, where: c.where } : rest });
+            }
+            case 'flyTo': {
+                const ok = await this.flyTo(c.objectId ?? c.position, c.zoom !== undefined ? { zoom: c.zoom } : undefined);
+                if (!ok)
+                    throw new Error(`object ${c.objectId} is not available`);
+                return undefined;
+            }
+            case 'fitTo': {
+                let bounds = c.bounds;
+                if (!bounds) {
+                    const missing = c.objectIds.filter((id) => !this.lookup(id));
+                    const fetched = missing.length ? await this.deps.provider.getCurrentState(missing) : [];
+                    const geoms = [...c.objectIds.map((id) => this.lookup(id)).filter((o) => !!o), ...fetched.filter((o) => o && validateGeometry(o.geometry).valid)].map((o) => geometryBounds(o.geometry));
+                    bounds = unionBounds(geoms);
+                    if (!bounds)
+                        throw new Error('none of these objects is available');
+                }
+                return this.fitBounds(bounds, { padding: 40, animate: true });
+            }
+            case 'select':
+                return c.objectIds.length ? this.setSelection({ objectIds: c.objectIds, source: origin }) : this.clearSelection(origin);
+            case 'clearSelection':
+                return this.clearSelection(origin);
+            case 'highlight':
+                return this.highlight(c.objectIds, { ...(c.durationMs ? { durationMs: c.durationMs } : {}), ...(c.color ? { color: c.color } : {}), origin });
+            case 'clearHighlight':
+                return this.clearHighlight();
+            case 'openInspector':
+                return void this.emitter.emit('inspectRequested', { objectId: c.objectId, origin });
+            case 'setTime':
+                return this.setTime(c.at === 'live' ? { mode: 'live' } : { mode: 'replay', at: c.at });
+            case 'play':
+                return void this.emitter.emit('playbackRequested', { action: 'play', ...(c.speed ? { speed: c.speed } : {}), origin });
+            case 'pause':
+                return void this.emitter.emit('playbackRequested', { action: 'pause', origin });
+            case 'drawProposal':
+                return this.propose({ geometry: c.geometry, ...(c.label ? { label: c.label } : {}), ...(c.note ? { note: c.note } : {}), ...(c.id ? { id: c.id } : {}), origin }).id;
+            case 'clearProposals':
+                return this.clearProposals();
+        }
+    }
+    async getJournal(query, range, signal) {
+        this.assertAlive();
+        if (!this.deps.journal)
+            throw new MapEngineError('MISSING_CAPABILITY', 'the event journal needs a journal provider (deps.journal)');
+        return this.deps.journal.getJournal(structuredClone(query), { ...range }, signal);
+    }
+    warnOnce(key, message, code = 'MISSING_CAPABILITY') {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        this.emitter.emit('warning', new MapEngineError(code, message));
+    }
+    // ---------------------------------------------------------------- plumbing
+    push(patch) {
+        if (isEmptyPatch(patch))
+            return;
+        if (this.mounted)
+            this.renderer.update(patch);
+        this.emitter.emit('scene', patch);
+    }
+    schedule() {
+        if (!this.mounted || this.current === 'destroyed')
+            return;
+        this.cancelScheduled();
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.refresh().catch((e) => this.emitter.emit('error', toEngineError(e)));
+        }, this.debounceMs);
+    }
+    cancelScheduled() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    size() {
+        const s = this.mounted ? this.renderer.getSize() : { width: 0, height: 0 };
+        return s.width > 0 && s.height > 0 ? s : this.fallbackSize;
+    }
+    /** Renderer-reported bounds win; otherwise compute from Web Mercator. */
+    withBounds(v) {
+        return v.bounds ? v : { ...v, bounds: computeBounds(v, this.size()) };
+    }
+    setState(s) {
+        if (this.current === s)
+            return;
+        this.current = s;
+        this.emitter.emit('state', s);
+    }
+    assertAlive() {
+        if (this.current === 'destroyed')
+            throw new MapEngineError('DESTROYED', 'runtime has been destroyed');
+    }
+}
+/** Camera equality with tolerance for float noise from the renderer; bounds are ignored. */
+/** Tilesets: unique ids and a URL each. */
+function validateTilesets(list) {
+    if (!Array.isArray(list))
+        return { valid: false, reason: 'tilesets must be an array' };
+    const ids = new Set();
+    for (const t of list) {
+        if (!t || typeof t.id !== 'string' || !t.id)
+            return { valid: false, reason: 'every tileset needs an id' };
+        if (ids.has(t.id))
+            return { valid: false, reason: `tileset ${t.id} appears twice` };
+        ids.add(t.id);
+        if (typeof t.url !== 'string' || !t.url)
+            return { valid: false, reason: `tileset ${t.id}: url is required` };
+        if (t.maximumScreenSpaceError !== undefined && !(t.maximumScreenSpaceError > 0))
+            return { valid: false, reason: `tileset ${t.id}: maximumScreenSpaceError must be > 0` };
+    }
+    return { valid: true };
+}
+/** Terrain config: a DEM tile URL and sane numbers (the engine runs no terrain service, §25). */
+function validateTerrain(t) {
+    if (!t || typeof t.tileUrl !== 'string' || !t.tileUrl.includes('{z}'))
+        return { valid: false, reason: 'terrain.tileUrl must be a {z}/{x}/{y} URL of elevation tiles' };
+    if (t.encoding !== undefined && t.encoding !== 'terrarium' && t.encoding !== 'mapbox')
+        return { valid: false, reason: 'terrain.encoding must be terrarium or mapbox' };
+    if (t.exaggeration !== undefined && !(typeof t.exaggeration === 'number' && t.exaggeration > 0))
+        return { valid: false, reason: 'terrain.exaggeration must be > 0' };
+    return { valid: true };
+}
+function sameCamera(a, b) {
+    const eps = 1e-9;
+    return (Math.abs(a.center.latitude - b.center.latitude) < eps &&
+        Math.abs(a.center.longitude - b.center.longitude) < eps &&
+        Math.abs(a.zoom - b.zoom) < eps &&
+        Math.abs((a.bearing ?? 0) - (b.bearing ?? 0)) < eps &&
+        Math.abs((a.pitch ?? 0) - (b.pitch ?? 0)) < eps);
+}
+/** True when `next` was observed before `prev` (both timestamps known). Equal timestamps apply (idempotent). */
+const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+const toEngineError = (e) => (e instanceof MapEngineError ? e : new MapEngineError('PROVIDER_ERROR', errorMessage(e), undefined, { cause: e }));
+export function createMapRuntime(config, deps, options) {
+    return new Runtime(config, deps, options);
+}