@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/testing/test-renderer.js

@@ -0,0 +1,153 @@
+/**
+ * A headless Renderer that records what it is told and lets tests play user input back.
+ * Its `objects` map is what a real renderer would be drawing: render() plus every update() applied.
+ */
+export class TestRenderer {
+    initialized = false;
+    destroyed = false;
+    options;
+    renders = [];
+    patches = [];
+    viewportsSet = [];
+    objects = new Map();
+    layers = [];
+    size;
+    /** When true, setViewport echoes back through onViewportChange, like MapLibre's moveend. */
+    echoViewport;
+    failInitialize = null;
+    listeners = {
+        viewport: new Set(),
+        pick: new Set(),
+        click: new Set(),
+        hover: new Set(),
+        error: new Set(),
+    };
+    capabilities;
+    /** Projections and terrains set after initialize (null = terrain off). */
+    projections = [];
+    terrains = [];
+    ground;
+    constructor(options = {}) {
+        this.size = options.size ?? { width: 800, height: 600 };
+        this.echoViewport = options.echoViewport ?? false;
+        this.capabilities = { ...(options.capabilities ?? {}), ...(options.ground ? { elevation: true } : {}) };
+        this.ground = options.ground;
+        if (options.setBasemap !== false) {
+            // Like a real style swap: the engine's layers and objects are gone until the next render().
+            this.setBasemap = async (basemap) => {
+                this.basemaps.push(structuredClone(basemap));
+                this.objects.clear();
+                this.layers = [];
+            };
+        }
+    }
+    initializeCount = 0;
+    /** Basemaps swapped in with setBasemap(). */
+    basemaps = [];
+    /** Present unless constructed with `setBasemap: false` (then the runtime has to remount to change basemap). */
+    setBasemap;
+    async initialize(_container, options) {
+        if (this.failInitialize)
+            throw this.failInitialize;
+        this.initializeCount++;
+        this.options = structuredClone(options);
+        this.initialized = true;
+        this.destroyed = false;
+        this.objects.clear();
+        this.layers = [];
+    }
+    setViewport(viewport) {
+        this.viewportsSet.push(structuredClone(viewport));
+        if (this.echoViewport)
+            this.simulateViewportChange(viewport);
+    }
+    render(scene) {
+        this.renders.push(structuredClone(scene));
+        this.objects.clear();
+        for (const o of scene.objects)
+            this.objects.set(o.key, structuredClone(o));
+        this.layers = structuredClone(scene.layers);
+    }
+    update(patch) {
+        this.patches.push(structuredClone(patch));
+        for (const k of patch.removed ?? [])
+            this.objects.delete(k);
+        for (const o of [...(patch.added ?? []), ...(patch.updated ?? [])])
+            this.objects.set(o.key, structuredClone(o));
+        if (patch.layers)
+            this.layers = structuredClone(patch.layers);
+    }
+    resizeCount = 0;
+    resize() {
+        this.resizeCount++;
+    }
+    getSize() {
+        return this.size;
+    }
+    /** Test projection: the last viewport set, 1 degree = 1000 px from the centre (not a real projection). */
+    project(position) {
+        const v = this.viewportsSet.at(-1) ?? this.options?.viewport;
+        if (!v)
+            return null;
+        return { x: this.size.width / 2 + (position.longitude - v.center.longitude) * 1000, y: this.size.height / 2 - (position.latitude - v.center.latitude) * 1000 };
+    }
+    setProjection(projection) {
+        this.projections.push(projection);
+    }
+    setTerrain(terrain) {
+        this.terrains.push(terrain ? structuredClone(terrain) : null);
+    }
+    /** Heights from the `ground` function given to the constructor (a test terrain). */
+    async sampleElevation(positions) {
+        return positions.map((p) => this.ground?.(p) ?? null);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.initialized = false;
+        for (const set of Object.values(this.listeners))
+            set.clear();
+    }
+    onViewportChange(l) {
+        return this.add(this.listeners.viewport, l);
+    }
+    onPick(l) {
+        return this.add(this.listeners.pick, l);
+    }
+    onMapClick(l) {
+        return this.add(this.listeners.click, l);
+    }
+    onHover(l) {
+        return this.add(this.listeners.hover, l);
+    }
+    onError(l) {
+        return this.add(this.listeners.error, l);
+    }
+    // --- simulated user input
+    simulateViewportChange(v) {
+        for (const l of this.listeners.viewport)
+            l(structuredClone(v));
+    }
+    simulatePick(objectId, layerId, position = { latitude: 0, longitude: 0 }) {
+        for (const l of this.listeners.pick)
+            l({ objectId, layerId, position });
+    }
+    simulateMapClick(position) {
+        for (const l of this.listeners.click)
+            l({ position });
+    }
+    simulateHover(e) {
+        for (const l of this.listeners.hover)
+            l(e);
+    }
+    simulateError(e) {
+        for (const l of this.listeners.error)
+            l(e);
+    }
+    listenerCount() {
+        return Object.values(this.listeners).reduce((n, s) => n + s.size, 0);
+    }
+    add(set, l) {
+        set.add(l);
+        return () => set.delete(l);
+    }
+}

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

@@ -0,0 +1 @@
+export { computeBounds, normalizeViewport, validateViewport, zoomToFit, MAX_MERCATOR_LATITUDE, MAX_PITCH, MAX_ZOOM, MIN_ZOOM, TILE_SIZE } from './viewport.js';

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

@@ -0,0 +1 @@
+export { computeBounds, normalizeViewport, validateViewport, zoomToFit, MAX_MERCATOR_LATITUDE, MAX_PITCH, MAX_ZOOM, MIN_ZOOM, TILE_SIZE } from './viewport.js';

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

@@ -0,0 +1,19 @@
+import type { BoundingBox, MapViewport, Padding, Size, ValidationResult } from '../core/types.js';
+/** Web Mercator cannot show the poles; MapLibre uses the same limit. */
+export declare const MAX_MERCATOR_LATITUDE = 85.051129;
+export declare const MIN_ZOOM = 0;
+export declare const MAX_ZOOM = 24;
+export declare const MAX_PITCH = 85;
+/** MapLibre's tile size, so headless bounds match what the renderer shows. */
+export declare const TILE_SIZE = 512;
+export declare function validateViewport(value: unknown): ValidationResult;
+/** Clamps latitude to the Mercator range and bearing to [0, 360). Call after validateViewport. */
+export declare function normalizeViewport(v: MapViewport): MapViewport;
+/**
+ * Visible bounds of a viewport on a container of `size` pixels.
+ * Accounts for bearing; ignores pitch (pitched views report their real bounds through the renderer).
+ * MVP does not wrap the antimeridian: longitudes are clamped to [-180, 180].
+ */
+export declare function computeBounds(viewport: MapViewport, size: Size, tileSize?: number): BoundingBox;
+/** The zoom at which `bounds` fits in `size` pixels, with `padding` pixels on each side. Bearing 0. */
+export declare function zoomToFit(bounds: BoundingBox, size: Size, padding?: Padding, tileSize?: number): MapViewport;

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

@@ -0,0 +1,102 @@
+import { validatePosition } from '../spatial/geometry.js';
+/** Web Mercator cannot show the poles; MapLibre uses the same limit. */
+export const MAX_MERCATOR_LATITUDE = 85.051129;
+export const MIN_ZOOM = 0;
+export const MAX_ZOOM = 24;
+export const MAX_PITCH = 85;
+/** MapLibre's tile size, so headless bounds match what the renderer shows. */
+export const TILE_SIZE = 512;
+export function validateViewport(value) {
+    if (typeof value !== 'object' || value === null)
+        return { valid: false, reason: 'viewport is not an object' };
+    const v = value;
+    const c = validatePosition(v.center, 'viewport.center');
+    if (!c.valid)
+        return c;
+    if (typeof v.zoom !== 'number' || !Number.isFinite(v.zoom))
+        return { valid: false, reason: 'viewport.zoom is not a finite number' };
+    if (v.zoom < MIN_ZOOM || v.zoom > MAX_ZOOM)
+        return { valid: false, reason: `viewport.zoom ${v.zoom} is outside [${MIN_ZOOM}, ${MAX_ZOOM}]` };
+    if (v.bearing !== undefined && !Number.isFinite(v.bearing))
+        return { valid: false, reason: 'viewport.bearing is not finite' };
+    if (v.pitch !== undefined && (!Number.isFinite(v.pitch) || v.pitch < 0 || v.pitch > MAX_PITCH)) {
+        return { valid: false, reason: `viewport.pitch must be within [0, ${MAX_PITCH}]` };
+    }
+    return { valid: true };
+}
+/** Clamps latitude to the Mercator range and bearing to [0, 360). Call after validateViewport. */
+export function normalizeViewport(v) {
+    const out = {
+        center: {
+            latitude: Math.max(-MAX_MERCATOR_LATITUDE, Math.min(MAX_MERCATOR_LATITUDE, v.center.latitude)),
+            longitude: v.center.longitude,
+        },
+        zoom: v.zoom,
+    };
+    if (v.bearing !== undefined)
+        out.bearing = ((v.bearing % 360) + 360) % 360;
+    if (v.pitch !== undefined)
+        out.pitch = v.pitch;
+    if (v.bounds)
+        out.bounds = v.bounds;
+    return out;
+}
+function project(p, worldSize) {
+    const lat = (Math.max(-MAX_MERCATOR_LATITUDE, Math.min(MAX_MERCATOR_LATITUDE, p.latitude)) * Math.PI) / 180;
+    return {
+        x: ((p.longitude + 180) / 360) * worldSize,
+        y: ((1 - Math.log(Math.tan(Math.PI / 4 + lat / 2)) / Math.PI) / 2) * worldSize,
+    };
+}
+function unproject(x, y, worldSize) {
+    const longitude = (x / worldSize) * 360 - 180;
+    const n = Math.PI - (2 * Math.PI * y) / worldSize;
+    const latitude = (180 / Math.PI) * Math.atan(Math.sinh(n));
+    return { latitude, longitude };
+}
+/**
+ * Visible bounds of a viewport on a container of `size` pixels.
+ * Accounts for bearing; ignores pitch (pitched views report their real bounds through the renderer).
+ * MVP does not wrap the antimeridian: longitudes are clamped to [-180, 180].
+ */
+export function computeBounds(viewport, size, tileSize = TILE_SIZE) {
+    const worldSize = tileSize * Math.pow(2, viewport.zoom);
+    const c = project(viewport.center, worldSize);
+    const theta = ((viewport.bearing ?? 0) * Math.PI) / 180;
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const hw = size.width / 2;
+    const hh = size.height / 2;
+    let west = Infinity;
+    let east = -Infinity;
+    let south = Infinity;
+    let north = -Infinity;
+    for (const [dx, dy] of [[-hw, -hh], [hw, -hh], [hw, hh], [-hw, hh]]) {
+        const p = unproject(c.x + dx * cos - dy * sin, c.y + dx * sin + dy * cos, worldSize);
+        west = Math.min(west, p.longitude);
+        east = Math.max(east, p.longitude);
+        south = Math.min(south, p.latitude);
+        north = Math.max(north, p.latitude);
+    }
+    return {
+        west: Math.max(-180, west),
+        east: Math.min(180, east),
+        south: Math.max(-MAX_MERCATOR_LATITUDE, south),
+        north: Math.min(MAX_MERCATOR_LATITUDE, north),
+    };
+}
+/** The zoom at which `bounds` fits in `size` pixels, with `padding` pixels on each side. Bearing 0. */
+export function zoomToFit(bounds, size, padding = 0, tileSize = TILE_SIZE) {
+    const pad = typeof padding === 'number' ? { top: padding, right: padding, bottom: padding, left: padding } : padding;
+    const w = Math.max(1, size.width - pad.left - pad.right);
+    const h = Math.max(1, size.height - pad.top - pad.bottom);
+    const a = project({ latitude: bounds.north, longitude: bounds.west }, 1);
+    const b = project({ latitude: bounds.south, longitude: bounds.east }, 1);
+    const spanX = Math.max(1e-12, Math.abs(b.x - a.x));
+    const spanY = Math.max(1e-12, Math.abs(b.y - a.y));
+    const zoom = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, Math.log2(Math.min(w / (spanX * tileSize), h / (spanY * tileSize)))));
+    // The bounds sit in the middle of the clear area, not of the container: shift the camera by half the imbalance.
+    const worldPx = tileSize * 2 ** zoom;
+    const center = unproject((a.x + b.x) / 2 - (pad.left - pad.right) / 2 / worldPx, (a.y + b.y) / 2 - (pad.top - pad.bottom) / 2 / worldPx, 1);
+    return { center, zoom };
+}

package/vendor/map-provider-uns/client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The UNS backend over HTTP (uns-backend-server; one per region). Nodes, search, bindings, and the UNS's own
+ * time-series reads — `/timeseries/latest` and `/timeseries/range` take UNS node ids, never device or sensor ids.
+ * The caller's IOSense bearer is forwarded; the UNS authorizes (requirement §29: the browser is not the boundary).
+ */
+export interface UnsNode {
+    id: string;
+    /** Workspace id (`ws_…`). */
+    unsId: string;
+    type: string;
+    name: string;
+    /** Slug path, e.g. `fleet/uav-12/latitude`. */
+    path: string;
+    parentId: string | null;
+    childCount: number;
+    metadata: Record<string, unknown>;
+    tags: string[];
+}
+export interface UnsWorkspace {
+    id: string;
+    name: string;
+}
+export interface UnsLatest {
+    nodeId: string;
+    ok: boolean;
+    value?: number;
+    /** Epoch ms. */
+    time?: number;
+    unit?: string;
+    error?: string;
+}
+export interface UnsRange {
+    nodeId: string;
+    unit?: string;
+    points: Array<{
+        time: number;
+        value: number;
+    }>;
+}
+export interface UnsClientOptions {
+    /** e.g. https://uns-backend-server.us.iosense.io */
+    baseUrl: string;
+    /** The IOSense bearer (without "Bearer "), read on every call so a refreshed session is used at once. */
+    token: () => string | null;
+    fetch?: typeof fetch;
+}
+export declare class UnsHttpError extends Error {
+    readonly status: number;
+    readonly path: string;
+    constructor(status: number, path: string, message: string);
+}
+export declare function toNode(raw: unknown, wsId: string): UnsNode | null;
+export declare class UnsClient {
+    private readonly opts;
+    private readonly f;
+    /** A token handed over by the map engine (setAuth); wins over the session's own while set. */
+    private tokenOverride;
+    constructor(opts: UnsClientOptions);
+    setToken(token: string | null): void;
+    private call;
+    workspaces(signal?: AbortSignal): Promise<UnsWorkspace[]>;
+    children(wsId: string, parentId?: string, signal?: AbortSignal): Promise<UnsNode[]>;
+    search(wsId: string, q: string, opts?: {
+        type?: string;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<UnsNode[]>;
+    node(wsId: string, nodeId: string, signal?: AbortSignal): Promise<UnsNode | null>;
+    /** A node and everything under it, full rows with metadata, root first (one call for a whole branch). */
+    subtree(wsId: string, rootId: string, signal?: AbortSignal): Promise<UnsNode[]>;
+    /** Latest values of tags, by UNS node id. */
+    latest(wsId: string, nodeIds: string[], signal?: AbortSignal): Promise<UnsLatest[]>;
+    /** A tag's points over a window (epoch ms). */
+    range(wsId: string, nodeId: string, startMs: number, endMs: number, signal?: AbortSignal): Promise<UnsRange>;
+}

package/vendor/map-provider-uns/client.js

@@ -0,0 +1,111 @@
+/**
+ * The UNS backend over HTTP (uns-backend-server; one per region). Nodes, search, bindings, and the UNS's own
+ * time-series reads — `/timeseries/latest` and `/timeseries/range` take UNS node ids, never device or sensor ids.
+ * The caller's IOSense bearer is forwarded; the UNS authorizes (requirement §29: the browser is not the boundary).
+ */
+export class UnsHttpError extends Error {
+    status;
+    path;
+    constructor(status, path, message) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = 'UnsHttpError';
+    }
+}
+/** The envelopes differ across endpoints (`items`, `data.items`, `data`, a bare array). */
+function rows(json) {
+    if (Array.isArray(json))
+        return json;
+    const b = json;
+    if (Array.isArray(b?.items))
+        return b.items;
+    if (Array.isArray(b?.nodes))
+        return b.nodes;
+    if (Array.isArray(b?.data))
+        return b.data;
+    const d = b?.data;
+    return Array.isArray(d?.items) ? d.items : [];
+}
+export function toNode(raw, wsId) {
+    const n = raw;
+    if (!n || typeof n.id !== 'string' || typeof n.path !== 'string' || !n.path)
+        return null;
+    return {
+        id: n.id,
+        unsId: n.unsId ?? n.workspaceId ?? wsId,
+        type: typeof n.type === 'string' ? n.type : '',
+        name: n.name || n.path.split('/').pop() || n.id,
+        path: n.path,
+        parentId: n.parentId ?? null,
+        childCount: typeof n.childCount === 'number' ? n.childCount : Array.isArray(n.children) ? n.children.length : 0,
+        metadata: n.metadata && typeof n.metadata === 'object' ? n.metadata : {},
+        tags: Array.isArray(n.tags) ? n.tags.filter((t) => typeof t === 'string') : [],
+    };
+}
+export class UnsClient {
+    opts;
+    f;
+    /** A token handed over by the map engine (setAuth); wins over the session's own while set. */
+    tokenOverride = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.f = opts.fetch ?? ((...a) => fetch(...a));
+    }
+    setToken(token) {
+        this.tokenOverride = token;
+    }
+    async call(path, init) {
+        const token = this.tokenOverride ?? this.opts.token();
+        const res = await this.f(`${this.opts.baseUrl}${path}`, {
+            method: init?.method ?? 'GET',
+            headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(init?.body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+            ...(init?.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+            ...(init?.signal ? { signal: init.signal } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new UnsHttpError(res.status, path, `UNS ${path}: HTTP ${res.status}${text ? ` — ${text.slice(0, 200)}` : ''}`);
+        }
+        return (await res.json());
+    }
+    async workspaces(signal) {
+        const json = await this.call('/workspaces?limit=200', signal ? { signal } : undefined);
+        return rows(json)
+            .map((it) => it.workspace ?? it)
+            .filter((w) => typeof w?.id === 'string' && typeof w?.name === 'string')
+            .map((w) => ({ id: w.id, name: w.name }));
+    }
+    async children(wsId, parentId, signal) {
+        const json = await this.call(`/workspaces/${encodeURIComponent(wsId)}/nodes/skeleton?parent=${encodeURIComponent(parentId ?? 'root')}`, signal ? { signal } : undefined);
+        return rows(json).map((r) => toNode(r, wsId)).filter((n) => n !== null);
+    }
+    async search(wsId, q, opts = {}) {
+        const params = new URLSearchParams({ q, limit: String(opts.limit ?? 200) });
+        if (opts.type)
+            params.set('type', opts.type);
+        const json = await this.call(`/workspaces/${encodeURIComponent(wsId)}/nodes/search?${params}`, opts.signal ? { signal: opts.signal } : undefined);
+        return rows(json).map((r) => toNode(r, wsId)).filter((n) => n !== null);
+    }
+    async node(wsId, nodeId, signal) {
+        const json = await this.call(`/workspaces/${encodeURIComponent(wsId)}/nodes/${encodeURIComponent(nodeId)}`, signal ? { signal } : undefined);
+        return toNode(json.node ?? json.data ?? json, wsId);
+    }
+    /** A node and everything under it, full rows with metadata, root first (one call for a whole branch). */
+    async subtree(wsId, rootId, signal) {
+        const json = await this.call(`/workspaces/${encodeURIComponent(wsId)}/nodes/${encodeURIComponent(rootId)}/subtree`, signal ? { signal } : undefined);
+        return rows(json).map((r) => toNode(r, wsId)).filter((n) => n !== null);
+    }
+    /** Latest values of tags, by UNS node id. */
+    async latest(wsId, nodeIds, signal) {
+        if (!nodeIds.length)
+            return [];
+        const res = await this.call('/timeseries/latest', { method: 'POST', body: { unsId: wsId, nodeIds }, ...(signal ? { signal } : {}) });
+        return res.values ?? [];
+    }
+    /** A tag's points over a window (epoch ms). */
+    async range(wsId, nodeId, startMs, endMs, signal) {
+        const res = await this.call('/timeseries/range', { method: 'POST', body: { unsId: wsId, nodeId, startMs, endMs }, ...(signal ? { signal } : {}) });
+        return { nodeId, ...(res.unit ? { unit: res.unit } : {}), points: Array.isArray(res.points) ? res.points : [] };
+    }
+}

package/vendor/map-provider-uns/index.d.ts

@@ -0,0 +1,2 @@
+export { UnsClient, UnsHttpError, toNode, type UnsClientOptions, type UnsLatest, type UnsNode, type UnsRange, type UnsWorkspace } from './client.js';
+export { UnsSpatialProvider, indexSpatialNodes, pluralLabel, type SpatialNode, type UnsProviderOptions } from './provider.js';

package/vendor/map-provider-uns/index.js

@@ -0,0 +1,2 @@
+export { UnsClient, UnsHttpError, toNode } from './client.js';
+export { UnsSpatialProvider, indexSpatialNodes, pluralLabel } from './provider.js';

package/vendor/map-provider-uns/provider.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The UNS as a Map Engine data source (requirement §26–28, §52). UNS ONLY: nodes come from the workspace tree,
+ * live values from `/timeseries/latest`, history from `/timeseries/range` — always by UNS node id. Legacy device /
+ * sensor identifiers in metadata (deviceId, sensorId, latitudeSensor, …) are deprecated and never used.
+ *
+ * Spatiality is a capability (§9), declared on the node as `metadata.spatial`:
+ *   - `SpatialGeometry` → an area: `spatial.geometry` (GeoJSON, EPSG:4326)
+ *   - `SpatialPoint`    → a point: `spatial.geometry` or `spatial.latitude/longitude`
+ *   - `MovingSpatial`   → a point whose position comes from the node's child tags whose `metadata.spatialRole` is
+ *                          `latitude` / `longitude` (heading, speed, altitude roles enrich it)
+ *   - `SpatialTrack`    → history; served through getTracks() from the moving nodes' position tags
+ * Every other child tag becomes a live property named by its `metadata.semantic` (else its name).
+ *
+ * The visual plane (docs 28/29) from what the UNS states, never guessed: provenance (workspace, node path, times,
+ * version and marking from metadata, a time per property), confidence and an accuracy radius from tags with those
+ * spatialRoles, a validity window from metadata, links from `metadata.links` and the spatial parent/child tree, and
+ * an event journal from each node's tag history.
+ */
+import { MapEngineError } from '../map-engine/index.js';
+import type { AltitudeReference, AuthAware, AuthContext, JournalEntry, JournalProvider, Link, LinkProvider, DataCapabilities, DatasetCatalog, DatasetInfo, Geometry, OntologySpatialResolver, RealtimeProvider, SpatialDataProvider, SpatialObject, SpatialPatch, SpatialQuery, TimeRange, Track, TrackProvider, Unsubscribe } from '../map-engine/index.js';
+import type { UnsClient, UnsNode } from './client.js';
+type Kind = 'area' | 'fixed' | 'moving' | 'point';
+interface TagInfo {
+    id: string;
+    key: string;
+    /** The tag's UNS path, for provenance. */
+    path?: string;
+    unit?: string;
+    role?: string;
+    enumValues?: string[];
+    valueType?: string;
+    /** For heights: what they are measured from, as the UNS states it (metadata.datum). */
+    datum?: string;
+}
+/** A UNS datum as an engine altitude reference (ADR-028); unknown datums give none — never guessed. */
+export declare function referenceOf(datum: string | undefined): AltitudeReference | undefined;
+/** One spatial UNS node and what it takes to draw it. */
+export interface SpatialNode {
+    node: UnsNode;
+    ontologyType: string;
+    kind: Kind;
+    /** Areas and fixed points. */
+    geometry?: Geometry;
+    tags: TagInfo[];
+    latTag?: TagInfo;
+    lngTag?: TagInfo;
+    /** The tag with `spatialRole: altitude`, used only when its datum gives a reference. */
+    altTag?: TagInfo;
+    altitudeReference?: AltitudeReference;
+    /** Static properties from metadata (no legacy identifiers). */
+    props: Record<string, unknown>;
+    /** A time the node itself carries (detections, observations…). */
+    timestamp?: string;
+}
+export interface UnsProviderOptions {
+    client: UnsClient;
+    workspace: string;
+    /** Shown as the datasets' source. */
+    workspaceName?: string;
+    /** How often live values are read for subscribers. Default 3000 ms. */
+    pollMs?: number;
+    /** Re-read the tree after this long. Default 5 min. */
+    discoveryTtlMs?: number;
+    /** Latest values are shared between calls for this long. Default 1500 ms. */
+    latestTtlMs?: number;
+    now?: () => number;
+    /** Timer for polling (tests). */
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+}
+/** "AirPlatform" → "Air platforms", "RFStation" → "RF stations" (acronyms keep their capitals). */
+export declare const pluralLabel: (cls: string) => string;
+/** Builds the spatial index of a workspace from its full node rows. Exported for tests. */
+export declare function indexSpatialNodes(rows: UnsNode[]): SpatialNode[];
+export declare class UnsSpatialProvider implements SpatialDataProvider, RealtimeProvider, TrackProvider, DatasetCatalog, JournalProvider, LinkProvider, AuthAware {
+    private readonly opts;
+    readonly capabilities: DataCapabilities;
+    private nodes;
+    private nodesAt;
+    private latestCache;
+    /** A read in flight, shared by every caller that needs any of its tags (the UNS answers in seconds). */
+    private latestInFlight;
+    private readonly subs;
+    private timer;
+    private readonly now;
+    constructor(opts: UnsProviderOptions);
+    /**
+     * Who is looking (doc 28 G13): the token goes with every UNS call and everything cached is read again, since
+     * another user may see other nodes and values. A refused read (HTTP 403) reaches the map as a denied layer.
+     */
+    setAuth(auth: AuthContext | null): void;
+    /** The spatial nodes of the workspace (cached; re-read after discoveryTtlMs). */
+    discover(signal?: AbortSignal): Promise<SpatialNode[]>;
+    private readTree;
+    /**
+     * Latest values for tags. The UNS answers a batch in seconds, so a cold read fetches EVERY live tag of the
+     * workspace at once (in parallel chunks) and every layer's query is served from that one round; a read already
+     * in flight is shared rather than repeated.
+     */
+    private latest;
+    /** One spatial node as a SpatialObject, with its live values. Null when a moving node has no position yet. */
+    private toObject;
+    private liveTagIds;
+    private select;
+    query(query: SpatialQuery, signal?: AbortSignal): Promise<SpatialObject[]>;
+    getCurrentState(objectIds: string[], signal?: AbortSignal): Promise<SpatialObject[]>;
+    subscribe(query: SpatialQuery, onPatch: (p: SpatialPatch) => void, onError?: (e: Error) => void): Unsubscribe;
+    /** One polling round for every subscriber. Exposed for tests. */
+    poll(): Promise<void>;
+    getTracks(query: SpatialQuery, range: TimeRange, signal?: AbortSignal): Promise<Track[]>;
+    /**
+     * The event journal from the UNS's own history: each node's property tags over the range, merged by time into
+     * a snapshot at the range start and one entry per change. Positions are left to tracks; areas and fixed points
+     * without tags have no history (they are static). A node created inside the range (metadata.createdAt) is not
+     * there before it.
+     */
+    getJournal(query: SpatialQuery, range: TimeRange, signal?: AbortSignal): Promise<JournalEntry[]>;
+    /**
+     * Links the UNS states: `metadata.links` (or `relations`) entries `{ to, type }` naming another node by id or path,
+     * and the tree itself — a spatial node under another spatial node is `part-of` it.
+     */
+    getLinks(objectIds: string[], types: string[] | undefined, signal?: AbortSignal): Promise<Link[]>;
+    listDatasets(signal?: AbortSignal): Promise<DatasetInfo[]>;
+    /** Ontology binding from the declared capabilities (§9, §12): what each class is drawn as. */
+    readonly ontology: OntologySpatialResolver;
+    /** Stops polling. */
+    dispose(): void;
+}
+/** Thrown shape for callers that want a typed failure. */
+export declare const unsError: (message: string, cause?: unknown) => MapEngineError;
+export {};