@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/realtime/apply.js

@@ -0,0 +1,155 @@
+/**
+ * Realtime (doc 14, §39–40, §62): how one frame of incremental changes is applied. Pure functions over the data
+ * the runtime hands in — no scene, no renderer, no events of its own — so the rules (coalescing, stale and
+ * out-of-order updates, clock skew, leaving the view, incremental index updates, trail growth) are testable alone.
+ */
+import { MapEngineError } from '../core/errors.js';
+import { layerQuery } from '../layers/layers.js';
+import { validateGeometry } from '../spatial/geometry.js';
+import { matchesQuery } from '../spatial/query.js';
+import { appendPoint, toIso, toMs } from '../temporal/tracks.js';
+/**
+ * Is `next` older than what is held? A held time beyond `trustUntil` (clock skew) cannot order anything: a real
+ * update must not be refused because a source once stamped the future.
+ */
+export function isOlder(next, prev, trustUntil) {
+    if (!next.observedAt || !prev.observedAt)
+        return false;
+    const a = Date.parse(next.observedAt);
+    const b = Date.parse(prev.observedAt);
+    if (!Number.isFinite(a) || !Number.isFinite(b) || b > trustUntil)
+        return false;
+    return a < b;
+}
+/** Applies one frame of stream events. Many events for one object collapse into its newest state. */
+export function applyFrame(batch, ctx) {
+    const touched = new Map();
+    const working = (layerId) => {
+        let m = touched.get(layerId);
+        if (!m)
+            touched.set(layerId, (m = new Map(ctx.current(layerId).map((o) => [o.objectId, o]))));
+        return m;
+    };
+    const changes = new Map();
+    const changeOf = (layerId) => {
+        let c = changes.get(layerId);
+        if (!c)
+            changes.set(layerId, (c = { upserted: new Map(), removed: new Set() }));
+        return c;
+    };
+    const leave = (layerId, id) => {
+        const c = changeOf(layerId);
+        c.upserted.delete(id);
+        c.removed.add(id);
+    };
+    const trails = new Set();
+    const fresh = [];
+    for (const { layerIds, patch, trail } of batch) {
+        if (trail) {
+            for (const layerId of layerIds)
+                if (ctx.trail(layerId, patch))
+                    trails.add(layerId);
+            continue;
+        }
+        for (const layerId of layerIds) {
+            const layer = ctx.layer(layerId);
+            if (!layer || !layer.visible)
+                continue;
+            const objects = working(layerId);
+            const query = layerQuery(layer, ctx.bounds);
+            for (const id of patch.removed ?? []) {
+                if (objects.delete(id)) {
+                    ctx.counters.applied++;
+                    leave(layerId, id);
+                }
+            }
+            for (const o of patch.upserted ?? []) {
+                if (!o || typeof o.objectId !== 'string' || !validateGeometry(o.geometry).valid) {
+                    ctx.warn(new MapEngineError('INVALID_GEOMETRY', `realtime: invalid object skipped`, { layerId, objectId: o?.objectId }));
+                    continue;
+                }
+                const prev = objects.get(o.objectId);
+                ctx.saw(o, layerId);
+                if (prev && isOlder(o, prev, ctx.trustUntil)) {
+                    ctx.counters.stale++; // out-of-order or stale: the newer state wins
+                    continue;
+                }
+                // Geofences see every fresh reading, including the one that takes an object out of view.
+                if (o.geometry.type === 'Point')
+                    fresh.push({ layerId, object: o });
+                if (!matchesQuery(o, query)) {
+                    // Moved out of view or no longer matches the layer: it leaves the layer.
+                    if (objects.delete(o.objectId)) {
+                        ctx.counters.outOfView++;
+                        leave(layerId, o.objectId);
+                    }
+                    continue;
+                }
+                objects.set(o.objectId, o);
+                const c = changeOf(layerId);
+                c.removed.delete(o.objectId);
+                c.upserted.set(o.objectId, o);
+                ctx.counters.applied++;
+            }
+        }
+    }
+    return { touched, changes, fresh, trails };
+}
+/**
+ * Applies one frame's changes to the client index instead of rebuilding it. The index holds each object once
+ * however many layers show it, so an object leaves only when no other layer still shows it.
+ *
+ * `displayed` is what every layer shows; `touched` holds the frame's new state for the layers it changed;
+ * `skip` names layers kept out of the index (trails).
+ */
+export function patchIndex(index, changes, touched, displayed, skip) {
+    const ids = new Map();
+    const shownElsewhere = (layerId, id) => {
+        for (const [other, list] of displayed) {
+            if (other === layerId || skip(other))
+                continue;
+            const t = touched.get(other);
+            if (t) {
+                if (t.has(id))
+                    return true;
+                continue;
+            }
+            let set = ids.get(other);
+            if (!set)
+                ids.set(other, (set = new Set(list.map((o) => o.objectId))));
+            if (set.has(id))
+                return true;
+        }
+        return false;
+    };
+    for (const [layerId, c] of changes) {
+        if (skip(layerId))
+            continue;
+        for (const id of c.removed)
+            if (!shownElsewhere(layerId, id))
+                index.remove(id);
+        for (const o of c.upserted.values())
+            index.insert(o);
+    }
+}
+/**
+ * Grows trails from live point updates and drops points older than `keepFrom`. Returns how many points were added
+ * and whether anything changed (a removal changes a trail without adding points).
+ */
+export function growTrails(tracks, patch, keepFrom, now) {
+    let changed = false;
+    let added = 0;
+    for (const id of patch.removed ?? [])
+        changed = tracks.delete(id) || changed;
+    for (const o of patch.upserted ?? []) {
+        if (!o || o.geometry?.type !== 'Point' || !validateGeometry(o.geometry).valid)
+            continue;
+        const ts = o.observedAt && Number.isFinite(toMs(o.observedAt)) ? o.observedAt : toIso(now);
+        const p = o.geometry.coordinates;
+        const heading = typeof o.properties?.heading === 'number' ? { heading: o.properties.heading } : {};
+        tracks.set(o.objectId, appendPoint(tracks.get(o.objectId) ?? { objectId: o.objectId, points: [] }, { timestamp: ts, latitude: p.latitude, longitude: p.longitude, ...heading }, keepFrom));
+        added++;
+        changed = true;
+    }
+    return { changed, added };
+}

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

@@ -0,0 +1 @@
+export { applyFrame, growTrails, isOlder, patchIndex, type AppliedFrame, type ApplyContext, type LayerChanges, type PendingPatch } from './apply.js';

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

@@ -0,0 +1 @@
+export { applyFrame, growTrails, isOlder, patchIndex } from './apply.js';

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

@@ -0,0 +1 @@
+export type { MapClickEvent, PickEvent, Renderer, RendererCapabilities, RendererOptions } from './renderer.js';

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

@@ -0,0 +1 @@
+export {};

package/vendor/map-engine/render/offline.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether a URL stays on the site (doc 28 G14): relative URLs, `data:`, `blob:` and `pmtiles://` packs on the
+ * site do; anything else needs one of the allowed origins. Shared by the runtime (config) and renderers (what a
+ * style file points at).
+ */
+export declare function isLocalUrl(url: string, allowed: string[]): boolean;
+/** Every URL a style JSON points at (sources, glyphs, sprite), for the offline check. */
+export declare function styleUrls(style: Record<string, unknown>): string[];

package/vendor/map-engine/render/offline.js

@@ -0,0 +1,47 @@
+/**
+ * Whether a URL stays on the site (doc 28 G14): relative URLs, `data:`, `blob:` and `pmtiles://` packs on the
+ * site do; anything else needs one of the allowed origins. Shared by the runtime (config) and renderers (what a
+ * style file points at).
+ */
+export function isLocalUrl(url, allowed) {
+    if (/^(data:|blob:)/i.test(url))
+        return true;
+    const pm = /^pmtiles:\/\/(.+)$/i.exec(url);
+    if (pm)
+        return isLocalUrl(pm[1], allowed);
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(url) && !url.startsWith('//'))
+        return true; // relative
+    try {
+        const u = new URL(url.startsWith('//') ? `https:${url}` : url);
+        return allowed.some((o) => {
+            try {
+                return new URL(o).origin === u.origin;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** Every URL a style JSON points at (sources, glyphs, sprite), for the offline check. */
+export function styleUrls(style) {
+    const out = [];
+    const add = (u) => typeof u === 'string' && u && out.push(u.replace(/\{[a-z]+\}/gi, '0'));
+    add(style.glyphs);
+    if (Array.isArray(style.sprite))
+        for (const s of style.sprite)
+            add(s?.url);
+    else
+        add(style.sprite);
+    for (const src of Object.values((style.sources ?? {}))) {
+        add(src?.url);
+        for (const t of src?.tiles ?? [])
+            add(t);
+        if (typeof src?.data === 'string')
+            add(src.data);
+    }
+    return out;
+}

package/vendor/map-engine/render/renderer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The renderer boundary (ADR-011, Decision 10). Bidirectional: the engine pushes scenes and patches in;
+ * the renderer reports camera moves, picks, clicks, hover and errors back — always as stable objectIds.
+ * A renderer holds no business logic and never queries data.
+ */
+import type { BasemapConfig, MapConfig, MapViewport, Position, RendererCapabilities, ScenePatch, SceneState, Size, TerrainConfig, TilesetConfig, Unsubscribe } from '../core/types.js';
+export type { RendererCapabilities };
+export interface RendererOptions {
+    basemap: BasemapConfig;
+    viewport: MapViewport;
+    projection?: MapConfig['projection'];
+    terrain?: TerrainConfig;
+    tilesets?: TilesetConfig[];
+    /** The offline profile (doc 28 G14): a renderer refuses anything it fetches that would leave these origins. */
+    offline?: {
+        allowedOrigins: string[];
+    };
+}
+export interface PickEvent {
+    objectId: string;
+    layerId: string;
+    /** Where the pointer was. Renderers provide it for clicks; hover may omit it. */
+    position?: Position;
+}
+export interface MapClickEvent {
+    position: Position;
+}
+/**
+ * Lifecycle (doc §65): initialize → render/update → destroy. destroy() releases everything (GPU context, DOM,
+ * listeners) and cancels an initialize still in flight; initialize() may then be called again — the runtime
+ * unmounts and remounts with the same renderer.
+ */
+export interface Renderer {
+    initialize(container: HTMLElement, options: RendererOptions): Promise<void>;
+    /**
+     * Swaps the basemap and keeps the map (camera, GPU context). Engine layers are gone afterwards: the runtime
+     * calls render() with the full scene once this resolves. Optional; without it the runtime remounts.
+     */
+    setBasemap?(basemap: BasemapConfig): Promise<void>;
+    readonly capabilities?: RendererCapabilities;
+    /** Flat map or globe. Optional; a renderer without it cannot draw a globe (see capabilities). */
+    setProjection?(projection: NonNullable<MapConfig['projection']>): void;
+    /** Turns terrain relief on (a config) or off (null). */
+    setTerrain?(terrain: TerrainConfig | null): void;
+    /** Replaces the 3D Tiles scenery (needs `tiles3d`). */
+    setTilesets?(tilesets: TilesetConfig[]): void;
+    /** Ground heights (metres above sea level) under positions, from the renderer's terrain; null where unknown. */
+    sampleElevation?(positions: Position[]): Promise<Array<number | null>>;
+    setViewport(viewport: MapViewport, options?: {
+        animate?: boolean;
+    }): void;
+    /** Full scene (first draw, or after a reset). */
+    render(scene: SceneState): void;
+    /** Incremental change; must not rebuild the whole scene (ADR-014). */
+    update(patch: ScenePatch): void;
+    resize(): void;
+    /** Drawing surface size in CSS pixels; the engine uses it to compute viewport bounds. */
+    getSize(): Size;
+    destroy(): void;
+    /** Camera settled (user or programmatic). Includes the renderer's real visible bounds. */
+    onViewportChange(listener: (viewport: MapViewport) => void): Unsubscribe;
+    onPick(listener: (event: PickEvent) => void): Unsubscribe;
+    /** Click on the map that did not hit an object. */
+    onMapClick(listener: (event: MapClickEvent) => void): Unsubscribe;
+    onHover(listener: (event: PickEvent | null) => void): Unsubscribe;
+    onError(listener: (error: Error) => void): Unsubscribe;
+    /** Screen pixel of a position inside the map container (for overlays such as popups). Optional. */
+    project?(position: Position): {
+        x: number;
+        y: number;
+    } | null;
+    /** Every camera frame while it moves (pan, zoom, animation), for overlays that follow the map. Optional. */
+    onCameraMove?(listener: () => void): Unsubscribe;
+}

package/vendor/map-engine/render/renderer.js

@@ -0,0 +1 @@
+export {};

package/vendor/map-engine/render/terrarium.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DEM tiles (Terrarium or Mapbox RGB encoding, web-mercator tiles), decoded by the engine itself: Cesium's terrain
+ * comes from the same tiles MapLibre draws (no Cesium Ion, self-hostable like the basemap, §25), and heights are
+ * sampled anywhere, not only where the map happens to have tiles loaded.
+ */
+import type { TerrainConfig } from '../core/types.js';
+/** Heights (metres) packed in one pixel's colour. */
+export declare function decodeHeight(r: number, g: number, b: number, encoding: TerrainConfig['encoding']): number;
+/**
+ * A `size`×`size` RGBA tile resampled to an `out`×`out` heightmap (edges included, as Cesium expects), row by row
+ * from north to south.
+ */
+export declare function heightsFromTile(rgba: Uint8ClampedArray | Uint8Array, size: number, out: number, encoding: TerrainConfig['encoding']): Float32Array;
+/** Fetches a DEM tile and decodes it to an `out`×`out` heightmap. Undefined when the tile is missing. */
+export declare function loadHeights(url: string, out: number, encoding: TerrainConfig['encoding']): Promise<Float32Array | undefined>;
+/** Where a point falls in the web-mercator tile grid at zoom `z`: tile x/y and the fraction (0…1) inside it. */
+export declare function tilePoint(longitude: number, latitude: number, z: number): {
+    x: number;
+    y: number;
+    fx: number;
+    fy: number;
+};
+/** Height at a fraction inside a decoded `size`×`size` tile, between its four nearest pixels. */
+export declare function heightAt(heights: Float32Array, size: number, fx: number, fy: number): number;
+/**
+ * True heights (metres, no exaggeration) from the DEM tiles at one detail level, anywhere on Earth. Tiles are
+ * fetched once per batch and kept (a small cache, oldest dropped). A missing or failed tile gives null: unknown,
+ * never sea level.
+ */
+export declare class DemSampler {
+    private readonly terrain;
+    private readonly zoom;
+    private readonly maxTiles;
+    private readonly load;
+    private readonly tiles;
+    constructor(terrain: TerrainConfig, zoom?: number, maxTiles?: number, load?: (url: string) => Promise<{
+        rgba: Uint8ClampedArray | Uint8Array;
+        size: number;
+    } | undefined>);
+    /** Tiles are shared between calls, so a caller's cancel is checked by the caller, not passed to the fetch. */
+    sample(positions: Array<{
+        longitude: number;
+        latitude: number;
+    }>): Promise<Array<number | null>>;
+    private tile;
+}
+/** The tile URL for x/y/z. */
+export declare const tileUrl: (template: string, x: number, y: number, z: number) => string;

package/vendor/map-engine/render/terrarium.js

@@ -0,0 +1,110 @@
+/** Heights (metres) packed in one pixel's colour. */
+export function decodeHeight(r, g, b, encoding) {
+    return encoding === 'mapbox' ? -10_000 + (r * 65_536 + g * 256 + b) * 0.1 : r * 256 + g + b / 256 - 32_768;
+}
+/**
+ * A `size`×`size` RGBA tile resampled to an `out`×`out` heightmap (edges included, as Cesium expects), row by row
+ * from north to south.
+ */
+export function heightsFromTile(rgba, size, out, encoding) {
+    const heights = new Float32Array(out * out);
+    for (let row = 0; row < out; row++) {
+        const y = Math.round((row / (out - 1)) * (size - 1));
+        for (let col = 0; col < out; col++) {
+            const x = Math.round((col / (out - 1)) * (size - 1));
+            const i = (y * size + x) * 4;
+            heights[row * out + col] = decodeHeight(rgba[i], rgba[i + 1], rgba[i + 2], encoding);
+        }
+    }
+    return heights;
+}
+/** Fetches a DEM tile's pixels (createImageBitmap + canvas). Undefined when the tile is missing. */
+async function loadPixels(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        return undefined;
+    const bitmap = await createImageBitmap(await res.blob());
+    const size = bitmap.width;
+    const canvas = typeof OffscreenCanvas !== 'undefined' ? new OffscreenCanvas(size, size) : Object.assign(document.createElement('canvas'), { width: size, height: size });
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    ctx.drawImage(bitmap, 0, 0);
+    bitmap.close?.();
+    return { rgba: ctx.getImageData(0, 0, size, size).data, size };
+}
+/** Fetches a DEM tile and decodes it to an `out`×`out` heightmap. Undefined when the tile is missing. */
+export async function loadHeights(url, out, encoding) {
+    const px = await loadPixels(url);
+    return px && heightsFromTile(px.rgba, px.size, out, encoding);
+}
+/** Where a point falls in the web-mercator tile grid at zoom `z`: tile x/y and the fraction (0…1) inside it. */
+export function tilePoint(longitude, latitude, z) {
+    const n = 2 ** z;
+    const lat = Math.max(-85.0511, Math.min(85.0511, latitude)) * (Math.PI / 180);
+    const gx = ((((longitude + 180) / 360) % 1) + 1) % 1 * n;
+    const gy = ((1 - Math.log(Math.tan(lat) + 1 / Math.cos(lat)) / Math.PI) / 2) * n;
+    const x = Math.min(n - 1, Math.floor(gx));
+    const y = Math.min(n - 1, Math.max(0, Math.floor(gy)));
+    return { x, y, fx: gx - x, fy: gy - y };
+}
+/** Height at a fraction inside a decoded `size`×`size` tile, between its four nearest pixels. */
+export function heightAt(heights, size, fx, fy) {
+    const px = Math.max(0, Math.min(size - 1, fx * size - 0.5));
+    const py = Math.max(0, Math.min(size - 1, fy * size - 0.5));
+    const x0 = Math.floor(px);
+    const y0 = Math.floor(py);
+    const x1 = Math.min(size - 1, x0 + 1);
+    const y1 = Math.min(size - 1, y0 + 1);
+    const tx = px - x0;
+    const ty = py - y0;
+    const h = (x, y) => heights[y * size + x];
+    return (h(x0, y0) * (1 - tx) + h(x1, y0) * tx) * (1 - ty) + (h(x0, y1) * (1 - tx) + h(x1, y1) * tx) * ty;
+}
+/**
+ * True heights (metres, no exaggeration) from the DEM tiles at one detail level, anywhere on Earth. Tiles are
+ * fetched once per batch and kept (a small cache, oldest dropped). A missing or failed tile gives null: unknown,
+ * never sea level.
+ */
+export class DemSampler {
+    terrain;
+    zoom;
+    maxTiles;
+    load;
+    tiles = new Map();
+    constructor(terrain, zoom = Math.min(14, terrain.maxZoom ?? 14), maxTiles = 64, load = loadPixels) {
+        this.terrain = terrain;
+        this.zoom = zoom;
+        this.maxTiles = maxTiles;
+        this.load = load;
+    }
+    /** Tiles are shared between calls, so a caller's cancel is checked by the caller, not passed to the fetch. */
+    async sample(positions) {
+        const points = positions.map((p) => tilePoint(p.longitude, p.latitude, this.zoom));
+        const tiles = await Promise.all(points.map((t) => this.tile(t.x, t.y)));
+        return points.map((t, i) => {
+            const tile = tiles[i];
+            return tile ? heightAt(tile.heights, tile.size, t.fx, t.fy) : null;
+        });
+    }
+    tile(x, y) {
+        const key = `${x}/${y}`;
+        const known = this.tiles.get(key);
+        if (known) {
+            this.tiles.delete(key); // most recent last
+            this.tiles.set(key, known);
+            return known;
+        }
+        const encoding = this.terrain.encoding;
+        const pending = this.load(tileUrl(this.terrain.tileUrl, x, y, this.zoom)).then((px) => (px ? { heights: heightsFromTile(px.rgba, px.size, px.size, encoding), size: px.size } : null), () => null);
+        // A failure is not kept: the next request tries again.
+        void pending.then((t) => {
+            if (!t && this.tiles.get(key) === pending)
+                this.tiles.delete(key);
+        });
+        this.tiles.set(key, pending);
+        while (this.tiles.size > this.maxTiles)
+            this.tiles.delete(this.tiles.keys().next().value);
+        return pending;
+    }
+}
+/** The tile URL for x/y/z. */
+export const tileUrl = (template, x, y, z) => template.replace('{z}', String(z)).replace('{x}', String(x)).replace('{y}', String(y));

package/vendor/map-engine/runtime/drawing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Drawing (doc §37): clicks become generic geometry. The engine owns the interaction and the draft; the application
+ * receives a Geometry and decides what it means (an annotation, a search area, a geofence).
+ */
+import type { Geometry, MapLayer, Position, SpatialObject } from '../core/types.js';
+export type DrawKind = 'point' | 'line' | 'polygon' | 'rectangle' | 'circle';
+export interface DrawingState {
+    kind: DrawKind;
+    /** Clicked positions so far. Rectangle: two corners. Circle: centre, then a point on the edge. */
+    points: Position[];
+    /** Enough points to finish, and the shape is valid. */
+    canFinish: boolean;
+    /** Why the shape cannot be finished as it is (e.g. a polygon whose edges cross), for the application to show. */
+    problem?: string;
+}
+export declare const minPoints: (kind: DrawKind) => number;
+export declare const autoFinishes: (kind: DrawKind, points: number) => boolean;
+/** The geometry a finished drawing produces, or null if there are not enough points. */
+export declare function drawnGeometry(kind: DrawKind, pts: Position[]): Geometry | null;
+/** Internal scene layers that show the draft. They are never returned by getLayers() and cannot be selected. */
+export declare const DRAFT_LAYER_IDS: {
+    readonly area: "__draft-area";
+    readonly line: "__draft-line";
+    readonly vertices: "__draft-vertices";
+};
+export declare const DRAFT_LAYERS: MapLayer[];
+/** Draft objects per internal layer: the shape so far, its outline, and the clicked vertices. */
+export declare function draftObjects(state: DrawingState | null): Record<string, SpatialObject[]>;

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

@@ -0,0 +1,58 @@
+import { distanceMeters } from '../spatial/operations.js';
+/** Clicks after which a drawing finishes by itself. Lines and polygons finish when the application says so. */
+const AUTO_FINISH = { point: 1, rectangle: 2, circle: 2 };
+const MIN_POINTS = { point: 1, line: 2, polygon: 3, rectangle: 2, circle: 2 };
+export const minPoints = (kind) => MIN_POINTS[kind];
+export const autoFinishes = (kind, points) => AUTO_FINISH[kind] !== undefined && points >= AUTO_FINISH[kind];
+/** The geometry a finished drawing produces, or null if there are not enough points. */
+export function drawnGeometry(kind, pts) {
+    if (pts.length < MIN_POINTS[kind])
+        return null;
+    switch (kind) {
+        case 'point':
+            return { type: 'Point', coordinates: pts[0] };
+        case 'line':
+            return { type: 'LineString', coordinates: [...pts] };
+        case 'polygon':
+            return { type: 'Polygon', coordinates: [[...pts, pts[0]]] };
+        case 'rectangle': {
+            const [a, b] = [pts[0], pts[1]];
+            const s = Math.min(a.latitude, b.latitude);
+            const n = Math.max(a.latitude, b.latitude);
+            const w = Math.min(a.longitude, b.longitude);
+            const e = Math.max(a.longitude, b.longitude);
+            if (s === n || w === e)
+                return null;
+            const sw = { latitude: s, longitude: w };
+            return { type: 'Polygon', coordinates: [[sw, { latitude: s, longitude: e }, { latitude: n, longitude: e }, { latitude: n, longitude: w }, sw]] };
+        }
+        case 'circle': {
+            const radiusMeters = distanceMeters(pts[0], pts[1]);
+            return radiusMeters > 0 ? { type: 'Circle', center: pts[0], radiusMeters } : null;
+        }
+    }
+}
+/** Internal scene layers that show the draft. They are never returned by getLayers() and cannot be selected. */
+export const DRAFT_LAYER_IDS = { area: '__draft-area', line: '__draft-line', vertices: '__draft-vertices' };
+const DRAFT = '#D99A1C';
+const quiet = { selectable: false, hoverable: false };
+export const DRAFT_LAYERS = [
+    { id: DRAFT_LAYER_IDS.area, source: {}, visible: true, zIndex: 10_000, interaction: quiet, visualization: { type: 'polygon', style: [{ style: { color: DRAFT, opacity: 0.15, strokeColor: DRAFT } }] } },
+    { id: DRAFT_LAYER_IDS.line, source: {}, visible: true, zIndex: 10_001, interaction: quiet, visualization: { type: 'line', style: [{ style: { color: DRAFT, size: 2 } }] } },
+    { id: DRAFT_LAYER_IDS.vertices, source: {}, visible: true, zIndex: 10_002, interaction: quiet, visualization: { type: 'marker', style: [{ style: { color: DRAFT, size: 4, strokeColor: '#FFFFFF', strokeWidth: 1.5 } }] } },
+];
+/** Draft objects per internal layer: the shape so far, its outline, and the clicked vertices. */
+export function draftObjects(state) {
+    const out = { [DRAFT_LAYER_IDS.area]: [], [DRAFT_LAYER_IDS.line]: [], [DRAFT_LAYER_IDS.vertices]: [] };
+    if (!state)
+        return out;
+    const pts = state.points;
+    out[DRAFT_LAYER_IDS.vertices] = pts.map((p, i) => ({ objectId: `__draft-v${i}`, geometry: { type: 'Point', coordinates: p } }));
+    const shape = state.kind === 'line' ? null : drawnGeometry(state.kind, pts);
+    if (shape && shape.type !== 'Point')
+        out[DRAFT_LAYER_IDS.area] = [{ objectId: '__draft-shape', geometry: shape }];
+    if ((state.kind === 'line' || state.kind === 'polygon') && pts.length >= 2) {
+        out[DRAFT_LAYER_IDS.line] = [{ objectId: '__draft-path', geometry: { type: 'LineString', coordinates: state.kind === 'polygon' && pts.length >= 3 ? [...pts, pts[0]] : [...pts] } }];
+    }
+    return out;
+}

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

@@ -0,0 +1,5 @@
+export { createMapRuntime } from './runtime.js';
+export type { DrawingState, DrawKind } from './drawing.js';
+export type { FlyToOptions, LayerFilter, LineOfSightOptions, MapRuntime, MapRuntimeDeps, MapRuntimeEvents, MapRuntimeOptions, MapRuntimeStats, ObjectInspection, RuntimeState } from './types.js';
+export type { ResolvedReference } from './types.js';
+export { offlineViolations, isLocalUrl } from './offline.js';

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

@@ -0,0 +1,2 @@
+export { createMapRuntime } from './runtime.js';
+export { offlineViolations, isLocalUrl } from './offline.js';

package/vendor/map-engine/runtime/offline.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The offline profile (doc 28 G14): a map for a disconnected site may only use URLs that stay on the site —
+ * relative ones, or the origins the deployment lists. Every URL in the config is checked when it is set; a
+ * violation is refused loudly (OFFLINE_VIOLATION) instead of failing quietly in the field.
+ */
+import type { BasemapConfig, MapConfig, MapLayer, TerrainConfig, TilesetConfig } from '../core/types.js';
+import { isLocalUrl } from '../render/offline.js';
+export { isLocalUrl };
+export declare const allowedOrigins: (offline: MapConfig["offline"]) => string[] | null;
+/** Every URL a part of the config uses, with where it is, for the error message. */
+export declare function configUrls(parts: {
+    basemap?: BasemapConfig;
+    terrain?: TerrainConfig | null;
+    tilesets?: TilesetConfig[];
+    layers?: MapLayer[];
+}): Array<{
+    where: string;
+    url: string;
+}>;
+/** The URLs that would leave the site, or none (also none when the profile is not offline). */
+export declare function offlineViolations(offline: MapConfig['offline'], parts: Parameters<typeof configUrls>[0]): Array<{
+    where: string;
+    url: string;
+}>;

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

@@ -0,0 +1,37 @@
+import { isLocalUrl } from '../render/offline.js';
+export { isLocalUrl };
+export const allowedOrigins = (offline) => (!offline ? null : offline === true ? [] : offline.allowedOrigins ?? []);
+/** Every URL a part of the config uses, with where it is, for the error message. */
+export function configUrls(parts) {
+    const out = [];
+    const add = (where, url) => typeof url === 'string' && url && out.push({ where, url: url.replace(/\{[xyz]\}/g, '0') });
+    const b = parts.basemap;
+    if (b) {
+        add('basemap.styleUrl', b.styleUrl);
+        add('basemap.tileUrl', b.tileUrl);
+        add('basemap.rasterFallback', b.rasterFallback);
+        add('basemap.font.url', b.font?.url);
+    }
+    if (parts.terrain)
+        add('terrain.tileUrl', parts.terrain.tileUrl);
+    for (const t of parts.tilesets ?? [])
+        add(`tilesets.${t.id}.url`, t.url);
+    for (const l of parts.layers ?? []) {
+        const vz = l.visualization;
+        add(`layers.${l.id}.icon.imageUrl`, vz.icon?.imageUrl);
+        add(`layers.${l.id}.model.url`, vz.model?.url);
+        add(`layers.${l.id}.image.url`, vz.image?.url);
+        for (const [i, r] of (vz.style ?? []).entries()) {
+            add(`layers.${l.id}.style[${i}].imageUrl`, r.style.imageUrl);
+            add(`layers.${l.id}.style[${i}].modelUrl`, r.style.modelUrl);
+        }
+    }
+    return out;
+}
+/** The URLs that would leave the site, or none (also none when the profile is not offline). */
+export function offlineViolations(offline, parts) {
+    const allowed = allowedOrigins(offline);
+    if (!allowed)
+        return [];
+    return configUrls(parts).filter((u) => !isLocalUrl(u.url, allowed));
+}

package/vendor/map-engine/runtime/overlays.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Engine-owned layers on top of the application's (doc 28 G7, G10; doc 29 §5): annotations, proposals and the
+ * highlight. Plain polygons, lines and points styled through rules and per-object `$s:` values, so every renderer
+ * draws them with what it already has. Like the draft layers, they are never returned by getLayers().
+ */
+import type { Annotation, Highlight, MapLayer, Proposal, SpatialObject } from '../core/types.js';
+type Kind = 'areas' | 'lines' | 'points';
+export declare const ANNOTATION_LAYER: (k: Kind) => string;
+export declare const PROPOSAL_LAYER: (k: Kind) => string;
+export declare const HIGHLIGHT_LAYER: (k: Kind) => string;
+export declare const ANNOTATION_COLOR = "#7A3FD6";
+export declare const PROPOSAL_COLOR = "#D97706";
+export declare const HIGHLIGHT_COLOR = "#F59E0B";
+export declare const ANNOTATION_LAYERS: MapLayer[];
+export declare const PROPOSAL_LAYERS: MapLayer[];
+/** A wide translucent halo under nothing but the draft: the objects keep their own look, the halo marks them. */
+export declare function highlightLayers(color: string): MapLayer[];
+/** The engine layer ids that carry objects people can select (annotations, proposals). */
+export declare const SELECTABLE_OVERLAYS: Set<string>;
+export declare const isOverlayLayer: (id: string) => boolean;
+export declare function annotationObjects(list: Iterable<Annotation>): Record<string, SpatialObject[]>;
+export declare function proposalObjects(list: Iterable<Proposal>): Record<string, SpatialObject[]>;
+/** Halo objects for the highlighted ids that are on the map now (they follow their objects). */
+export declare function highlightObjects(h: Highlight | null, lookup: (id: string) => SpatialObject | undefined): Record<string, SpatialObject[]>;
+export {};