@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/present/decorations.js

@@ -0,0 +1,115 @@
+import { circlePolygon, destination, ellipsePolygon, sectorPolygon } from '../spatial/measure.js';
+import { labelPoint } from '../spatial/operations.js';
+/** Engine layer ids are `__deco~<layerId>~<part>`; the part says what it draws. */
+export const DECO_PREFIX = '__deco~';
+const PARTS = ['footprint', 'uncertainty', 'alt-lines', 'alt-points', 'rings'];
+export const decoLayerId = (layerId, part) => `${DECO_PREFIX}${layerId}~${part}`;
+/** The application layer and object a decoration belongs to (for picking), or null for any other layer. */
+export function decorationOwner(layerId, objectId) {
+    if (!layerId.startsWith(DECO_PREFIX))
+        return null;
+    const rest = layerId.slice(DECO_PREFIX.length);
+    const cut = rest.lastIndexOf('~');
+    if (cut < 0)
+        return null;
+    const tilde = objectId.indexOf('~');
+    return { layerId: rest.slice(0, cut), objectId: tilde < 0 ? objectId : objectId.slice(0, tilde) };
+}
+const UNCERTAIN = '#7A3FD6';
+/** The engine layers a layer's decorations need (none when it has no decoration options). */
+export function decorationLayers(layer) {
+    const vz = layer.visualization;
+    const base = { source: {}, visible: layer.visible, interaction: { selectable: layer.interaction?.selectable !== false, hoverable: false } };
+    const z = (k) => layer.zIndex - 0.001 * k;
+    const out = [];
+    if (vz.footprint) {
+        const c = vz.footprint.color ?? '#0E9AA7';
+        out.push({ ...base, id: decoLayerId(layer.id, 'footprint'), zIndex: z(4), visualization: { type: 'polygon', style: [{ style: { color: c, opacity: 0.14, strokeColor: c, strokeWidth: 1 } }] } });
+    }
+    if (vz.uncertainty) {
+        const c = vz.uncertainty.color ?? UNCERTAIN;
+        out.push({ ...base, id: decoLayerId(layer.id, 'uncertainty'), zIndex: z(3), visualization: { type: 'polygon', style: [{ style: { color: c, opacity: vz.uncertainty.opacity ?? 0.15, strokeColor: c, strokeWidth: 1, dash: [2, 1.5] } }] } });
+        if (vz.uncertainty.alternatives !== false) {
+            out.push({ ...base, id: decoLayerId(layer.id, 'alt-lines'), zIndex: z(2), visualization: { type: 'line', style: [{ style: { color: c, size: 1.5, opacity: 0.8, dash: [2, 2] } }] } });
+            out.push({ ...base, id: decoLayerId(layer.id, 'alt-points'), zIndex: z(1), visualization: { type: 'marker', style: [{ style: { color: '#FFFFFF', size: 5, strokeColor: c, strokeWidth: 2 } }], label: { property: 'label', size: 10 } } });
+        }
+    }
+    if (vz.rings) {
+        const c = vz.rings.color ?? '#475569';
+        out.push({ ...base, id: decoLayerId(layer.id, 'rings'), zIndex: z(5), interaction: { selectable: false, hoverable: false }, visualization: { type: 'line', style: [{ style: { color: c, size: 1, opacity: 0.7, dash: [3, 2] } }], ...(vz.rings.labels !== false ? { label: { property: 'label', size: 10 } } : {}) } });
+    }
+    return out;
+}
+const num = (v) => {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : Number.NaN;
+    return Number.isFinite(n) ? n : undefined;
+};
+export const formatDistance = (m) => (m >= 1000 ? `${Number((m / 1000).toFixed(m % 1000 === 0 ? 0 : 1))} km` : `${Math.round(m)} m`);
+/** The ground area a camera sees (FootprintConfig); null without a heading. */
+export function footprintOf(f, at, props) {
+    const heading = num(props?.[f.headingProperty]);
+    if (heading === undefined)
+        return null;
+    const pitch = num(f.pitchProperty ? props?.[f.pitchProperty] : undefined) ?? f.pitch ?? 30;
+    const hfov = Math.max(1, Math.min(170, num(f.fovProperty ? props?.[f.fovProperty] : undefined) ?? f.fov ?? 40));
+    const vfov = Math.max(1, Math.min(170, f.fovVertical ?? hfov * 0.75));
+    const height = num(f.heightProperty ? props?.[f.heightProperty] : undefined) ?? f.height;
+    const maxR = f.maxRangeMeters ?? 5000;
+    if (!(height !== undefined && height > 0))
+        return sectorPolygon(at, heading - hfov / 2, heading + hfov / 2, 0, maxR);
+    const rad = (d) => (d * Math.PI) / 180;
+    const lower = pitch + vfov / 2; // the ray to the bottom of the picture
+    const upper = pitch - vfov / 2; // the ray to the top
+    const near = lower >= 89.9 ? 0 : Math.min(maxR, height / Math.tan(rad(lower)));
+    const far = upper <= 0.1 ? maxR : Math.min(maxR, height / Math.tan(rad(upper)));
+    if (!(far > near))
+        return null;
+    // Rays to the picture's left and right edges run longer than the centre ray.
+    const side = (d) => d / Math.cos(rad(hfov / 2));
+    const corner = (d, sign) => (d <= 0 ? at : destination(at, heading + (sign * hfov) / 2, side(d)));
+    const pts = [corner(near, -1), corner(near, 1), corner(far, 1), corner(far, -1)];
+    return { type: 'Polygon', coordinates: [[...pts, pts[0]]] };
+}
+/** Decoration objects per engine layer, for a layer's (presented) objects. */
+export function decorationObjects(layer, objects) {
+    const vz = layer.visualization;
+    const out = {};
+    for (const l of decorationLayers(layer))
+        out[l.id] = [];
+    if (!Object.keys(out).length)
+        return out;
+    for (const o of objects) {
+        if (o.geometry.type !== 'Point')
+            continue;
+        const at = o.geometry.coordinates;
+        if (vz.footprint) {
+            const g = footprintOf(vz.footprint, at, o.properties);
+            if (g)
+                out[decoLayerId(layer.id, 'footprint')].push({ objectId: o.objectId, geometry: g });
+        }
+        if (vz.uncertainty) {
+            const u = o.uncertainty;
+            const g = u?.ellipse && u.ellipse.semiMajorMeters > 0 && u.ellipse.semiMinorMeters > 0 ? ellipsePolygon(at, u.ellipse.semiMajorMeters, u.ellipse.semiMinorMeters, u.ellipse.orientationDegrees ?? 0) : u?.radiusMeters && u.radiusMeters > 0 ? circlePolygon(at, u.radiusMeters) : null;
+            if (g)
+                out[decoLayerId(layer.id, 'uncertainty')].push({ objectId: o.objectId, geometry: g });
+            if (vz.uncertainty.alternatives !== false) {
+                (o.alternatives ?? []).forEach((alt, i) => {
+                    const id = `${o.objectId}~${alt.id ?? i}`;
+                    const p = alt.geometry.type === 'Point' ? alt.geometry.coordinates : labelPoint(alt.geometry);
+                    const pct = alt.probability !== undefined ? ` ${Math.round(alt.probability * 100)}%` : '';
+                    out[decoLayerId(layer.id, 'alt-points')].push({ objectId: id, geometry: { type: 'Point', coordinates: p }, properties: { label: `${alt.label ?? 'alternative'}${pct}` } });
+                    out[decoLayerId(layer.id, 'alt-lines')].push({ objectId: id, geometry: { type: 'LineString', coordinates: [at, p] } });
+                    if (alt.geometry.type === 'Polygon')
+                        out[decoLayerId(layer.id, 'alt-lines')].push({ objectId: `${id}~outline`, geometry: { type: 'LineString', coordinates: alt.geometry.coordinates[0] } });
+                });
+            }
+        }
+        if (vz.rings) {
+            vz.rings.distancesMeters.forEach((d, i) => {
+                const ring = circlePolygon(at, d, 72).coordinates[0];
+                out[decoLayerId(layer.id, 'rings')].push({ objectId: `${o.objectId}~r${i}`, geometry: { type: 'LineString', coordinates: ring }, properties: { label: formatDistance(d) } });
+            });
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,2 @@
+export { AGE, ALTERNATIVES, CONFIDENCE, ageOf, effectiveLayer, isValidAt, nextAgeChangeMs, presentObject, scaled, scaleValue, validatePresentation, type AgeState } from './present.js';
+export { DECO_PREFIX, decorationLayers, decorationObjects, decorationOwner, footprintOf, formatDistance } from './decorations.js';

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

@@ -0,0 +1,2 @@
+export { AGE, ALTERNATIVES, CONFIDENCE, ageOf, effectiveLayer, isValidAt, nextAgeChangeMs, presentObject, scaled, scaleValue, validatePresentation } from './present.js';
+export { DECO_PREFIX, decorationLayers, decorationObjects, decorationOwner, footprintOf, formatDistance } from './decorations.js';

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

@@ -0,0 +1,47 @@
+/**
+ * Presentation: what an object looks like to the scene at a time (doc 28 A, doc 29 §1–4). The runtime keeps the
+ * provider's object as it is (index, queries, inspect); the scene gets this view of it:
+ *
+ *   - outside its validity window (`validFrom` … `validUntil`) it is not drawn;
+ *   - `$age` from `observedAt` and the layer's age thresholds (live clock or replay time); it changes exactly when
+ *     the state changes (the runtime schedules that moment), so a map of 10 000 objects is not redrawn every second;
+ *   - `$confidence` from `object.confidence`; `$alternatives` = number of unresolved candidates;
+ *   - `$s:<token>` = the value of each continuous scale (renderers read it before any rule).
+ *
+ * Rules and conditions can use these `$` properties like any other. Nothing here knows a domain.
+ */
+import type { AgeConfig, MapLayer, SpatialObject, StyleScale } from '../core/types.js';
+export declare const AGE = "$age";
+export declare const CONFIDENCE = "$confidence";
+export declare const ALTERNATIVES = "$alternatives";
+/** The per-object value of a continuous scale for a style token: `$s:opacity`, `$s:color`… */
+export declare const scaled: (token: StyleScale["token"]) => string;
+export type AgeState = 'fresh' | 'ageing' | 'stale' | 'lost';
+/** Whether the object's state holds at `nowMs` (no window = always). */
+export declare function isValidAt(o: SpatialObject, nowMs: number): boolean;
+/** Age of an object at `nowMs` under the layer's thresholds; null when it does not age (no config or no time). */
+export declare function ageOf(o: SpatialObject, age: AgeConfig | undefined, nowMs: number): {
+    state: AgeState;
+    seconds: number;
+} | null;
+/** The age state an object will next change to, in ms from now (for the clock tick), or null if it never will. */
+export declare function nextAgeChangeMs(o: SpatialObject, age: AgeConfig | undefined, nowMs: number): number | null;
+/** One scale's value for a property value; undefined when the value is not a number. */
+export declare function scaleValue(scale: StyleScale, raw: unknown): number | string | undefined;
+/**
+ * The scene's view of one object through one layer at `nowMs`; null when it is not drawn now (outside its
+ * validity window, or lost and the layer hides lost objects). The same object is returned when nothing applies.
+ */
+export declare function presentObject(layer: MapLayer, o: SpatialObject, nowMs: number): SpatialObject | null;
+/**
+ * The layer as the renderer gets it: link layers draw as lines; age fading becomes leading rules on `$age`
+ * (rules are per token, so the fade sets opacity — or a dashed outline for areas — and colours fall through).
+ */
+export declare function effectiveLayer(layer: MapLayer): MapLayer;
+/** Validates the presentation options of a layer (age, scales, decorations). */
+export declare function validatePresentation(l: MapLayer): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};

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

@@ -0,0 +1,149 @@
+export const AGE = '$age';
+export const CONFIDENCE = '$confidence';
+export const ALTERNATIVES = '$alternatives';
+/** The per-object value of a continuous scale for a style token: `$s:opacity`, `$s:color`… */
+export const scaled = (token) => `$s:${token}`;
+const ms = (iso) => (iso ? Date.parse(iso) : Number.NaN);
+/** Whether the object's state holds at `nowMs` (no window = always). */
+export function isValidAt(o, nowMs) {
+    const from = ms(o.validFrom);
+    const until = ms(o.validUntil);
+    return !(Number.isFinite(from) && nowMs < from) && !(Number.isFinite(until) && nowMs > until);
+}
+/** Age of an object at `nowMs` under the layer's thresholds; null when it does not age (no config or no time). */
+export function ageOf(o, age, nowMs) {
+    if (!age)
+        return null;
+    const seen = ms(o.observedAt);
+    if (!Number.isFinite(seen))
+        return null;
+    const seconds = Math.max(0, (nowMs - seen) / 1000);
+    const ageing = age.ageingAfterSeconds ?? age.staleAfterSeconds / 2;
+    const state = age.lostAfterSeconds !== undefined && seconds >= age.lostAfterSeconds ? 'lost' : seconds >= age.staleAfterSeconds ? 'stale' : seconds >= ageing ? 'ageing' : 'fresh';
+    return { state, seconds: Math.floor(seconds) };
+}
+/** The age state an object will next change to, in ms from now (for the clock tick), or null if it never will. */
+export function nextAgeChangeMs(o, age, nowMs) {
+    if (!age)
+        return null;
+    const seen = ms(o.observedAt);
+    if (!Number.isFinite(seen))
+        return null;
+    const marks = [age.ageingAfterSeconds ?? age.staleAfterSeconds / 2, age.staleAfterSeconds, age.lostAfterSeconds].filter((x) => x !== undefined);
+    const next = marks.map((s) => seen + s * 1000 - nowMs).filter((d) => d > 0);
+    return next.length ? Math.min(...next) : null;
+}
+const HEX = /^#([0-9a-f]{6})$/i;
+function mixColor(a, b, t) {
+    const pa = HEX.exec(a)?.[1];
+    const pb = HEX.exec(b)?.[1];
+    if (!pa || !pb)
+        return t < 0.5 ? a : b;
+    const ch = (h, i) => parseInt(h.slice(i, i + 2), 16);
+    const out = [0, 2, 4].map((i) => Math.round(ch(pa, i) + (ch(pb, i) - ch(pa, i)) * t).toString(16).padStart(2, '0'));
+    return `#${out.join('').toUpperCase()}`;
+}
+/** One scale's value for a property value; undefined when the value is not a number. */
+export function scaleValue(scale, raw) {
+    const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(n))
+        return undefined;
+    const [d0, d1] = scale.domain;
+    const t = d1 === d0 ? 1 : Math.max(0, Math.min(1, (n - d0) / (d1 - d0)));
+    const [r0, r1] = scale.range;
+    if (typeof r0 === 'string' || typeof r1 === 'string')
+        return mixColor(String(r0), String(r1), t);
+    return r0 + (r1 - r0) * t;
+}
+/**
+ * The scene's view of one object through one layer at `nowMs`; null when it is not drawn now (outside its
+ * validity window, or lost and the layer hides lost objects). The same object is returned when nothing applies.
+ */
+export function presentObject(layer, o, nowMs) {
+    if (!isValidAt(o, nowMs))
+        return null;
+    const vz = layer.visualization;
+    const age = vz.type === 'track' ? null : ageOf(o, vz.age, nowMs);
+    if (age?.state === 'lost' && vz.age?.hideLost)
+        return null;
+    const extra = {};
+    if (age)
+        extra[AGE] = age.state;
+    if (typeof o.confidence === 'number' && Number.isFinite(o.confidence))
+        extra[CONFIDENCE] = o.confidence;
+    if (o.alternatives?.length)
+        extra[ALTERNATIVES] = o.alternatives.length;
+    if (vz.scales?.length) {
+        const props = { ...o.properties, ...extra };
+        for (const s of vz.scales) {
+            const v = scaleValue(s, props[s.property]);
+            if (v !== undefined)
+                extra[scaled(s.token)] = v;
+        }
+    }
+    return Object.keys(extra).length ? { ...o, properties: { ...o.properties, ...extra } } : o;
+}
+const FADE = { ageing: 0.7, stale: 0.4, lost: 0.2 };
+/**
+ * The layer as the renderer gets it: link layers draw as lines; age fading becomes leading rules on `$age`
+ * (rules are per token, so the fade sets opacity — or a dashed outline for areas — and colours fall through).
+ */
+export function effectiveLayer(layer) {
+    const vz = layer.visualization;
+    let out = layer;
+    if (vz.type === 'link')
+        out = { ...out, visualization: { ...vz, type: 'line' } };
+    if (vz.age && vz.age.fade !== false && vz.type !== 'track') {
+        const area = vz.type === 'polygon' || vz.type === 'extrusion' || vz.type === 'image';
+        const fade = Object.keys(FADE).map((state) => ({
+            property: AGE,
+            op: 'eq',
+            value: state,
+            style: area ? { dash: state === 'ageing' ? [3, 2] : [1.5, 2] } : { opacity: FADE[state] },
+        }));
+        out = { ...out, visualization: { ...out.visualization, style: [...fade, ...(vz.style ?? [])] } };
+    }
+    return out;
+}
+/** Validates the presentation options of a layer (age, scales, decorations). */
+export function validatePresentation(l) {
+    const vz = l.visualization;
+    const bad = (reason) => ({ valid: false, reason: `layer ${l.id}: ${reason}` });
+    const pos = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+    if (vz.age) {
+        const a = vz.age;
+        if (!pos(a.staleAfterSeconds))
+            return bad('age.staleAfterSeconds must be > 0');
+        if (a.ageingAfterSeconds !== undefined && !(pos(a.ageingAfterSeconds) && a.ageingAfterSeconds < a.staleAfterSeconds))
+            return bad('age.ageingAfterSeconds must be > 0 and below staleAfterSeconds');
+        if (a.lostAfterSeconds !== undefined && !(pos(a.lostAfterSeconds) && a.lostAfterSeconds > a.staleAfterSeconds))
+            return bad('age.lostAfterSeconds must be above staleAfterSeconds');
+    }
+    for (const [i, s] of (vz.scales ?? []).entries()) {
+        if (typeof s.property !== 'string' || !s.property)
+            return bad(`scales[${i}].property is required`);
+        if (!['opacity', 'size', 'strokeWidth', 'color', 'strokeColor'].includes(s.token))
+            return bad(`scales[${i}].token must be opacity, size, strokeWidth, color or strokeColor`);
+        if (!(Array.isArray(s.domain) && s.domain.length === 2 && s.domain.every((n) => typeof n === 'number' && Number.isFinite(n))))
+            return bad(`scales[${i}].domain must be [min, max] numbers`);
+        const colour = s.token === 'color' || s.token === 'strokeColor';
+        const okRange = Array.isArray(s.range) && s.range.length === 2 && (colour ? s.range.every((c) => typeof c === 'string' && HEX.test(c)) : s.range.every((n) => typeof n === 'number' && Number.isFinite(n)));
+        if (!okRange)
+            return bad(`scales[${i}].range must be ${colour ? 'two #RRGGBB colours' : 'two numbers'}`);
+    }
+    const pointOnly = (k) => vz[k] && !['marker', 'model', 'volume', 'heatmap'].includes(vz.type);
+    for (const k of ['uncertainty', 'rings', 'footprint'])
+        if (pointOnly(k))
+            return bad(`${k} applies to point layers`);
+    if (vz.rings && !(Array.isArray(vz.rings.distancesMeters) && vz.rings.distancesMeters.length > 0 && vz.rings.distancesMeters.every(pos)))
+        return bad('rings.distancesMeters must be distances > 0');
+    if (vz.footprint && (typeof vz.footprint.headingProperty !== 'string' || !vz.footprint.headingProperty))
+        return bad('footprint.headingProperty is required');
+    if (vz.link && vz.type !== 'link')
+        return bad('link options need visualization.type "link"');
+    if (vz.image && vz.type !== 'image')
+        return bad('image options need visualization.type "image"');
+    if (vz.type === 'image' && !vz.image?.url && !vz.image?.urlProperty)
+        return bad('an image layer needs image.url or image.urlProperty');
+    return { valid: true };
+}

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

@@ -0,0 +1 @@
+export { planQueries, type PlannedCall, type QueryPlan } from './planner.js';

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

@@ -0,0 +1 @@
+export { planQueries } from './planner.js';

package/vendor/map-engine/query/planner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Query planner foundation (doc 13). Decides what to push to the provider and what to filter on the client.
+ *
+ * - Identical layer queries share one provider call (and one realtime subscription).
+ * - Spatial predicates and the viewport boundary are pushed down when the provider supports spatial
+ *   queries; otherwise the call carries only the semantic part and the client filters exactly.
+ */
+import type { BoundingBox, MapLayer, SpatialQuery } from '../core/types.js';
+import type { DataCapabilities } from '../data/contracts.js';
+import { type QueryHints } from '../layers/layers.js';
+export interface PlannedCall {
+    key: string;
+    /** What the provider is asked. */
+    query: SpatialQuery;
+    layerIds: string[];
+    /** True when spatial parts were left to the client because the provider cannot evaluate them. */
+    localSpatial: boolean;
+}
+export interface QueryPlan {
+    calls: PlannedCall[];
+    layers: number;
+    /** Layers served by a call another layer already needed. */
+    deduplicated: number;
+    pushedDown: boolean;
+}
+export declare function planQueries(layers: MapLayer[], bounds: BoundingBox | undefined, capabilities: DataCapabilities, hints?: QueryHints): QueryPlan;

package/vendor/map-engine/query/planner.js

@@ -0,0 +1,47 @@
+import { layerQuery } from '../layers/layers.js';
+/** Stable key for equal queries regardless of property order. */
+function keyOf(q) {
+    const sort = (v) => Array.isArray(v) ? v.map(sort) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)).map(([k, x]) => [k, sort(x)])) : v;
+    return JSON.stringify(sort(q));
+}
+export function planQueries(layers, bounds, capabilities, hints) {
+    const calls = new Map();
+    const pushedDown = capabilities.supportsSpatialQuery;
+    for (const layer of layers) {
+        const full = layerQuery(layer, bounds, hints);
+        const query = { ...full };
+        if (!pushedDown) {
+            delete query.spatial;
+            delete query.bounds;
+        }
+        // Layers over one source that draw different geometry types (point / line / area) can share a call;
+        // each layer keeps only its own type on the client. A ranking (nearest) must rank drawable objects
+        // only, so it keeps its geometry type in the key and in the call.
+        const ranked = full.spatial?.relation === 'nearest';
+        const shareable = { ...query };
+        if (!ranked)
+            delete shareable.geometryType;
+        const key = keyOf(shareable);
+        const existing = calls.get(key);
+        if (existing) {
+            existing.layerIds.push(layer.id);
+            if (full.geometryType)
+                existing.geometryTypes.add(full.geometryType);
+        }
+        else {
+            calls.set(key, {
+                key,
+                query: shareable,
+                layerIds: [layer.id],
+                localSpatial: !pushedDown && (full.spatial !== undefined || full.bounds !== undefined),
+                geometryTypes: new Set(full.geometryType ? [full.geometryType] : []),
+            });
+        }
+    }
+    const list = [...calls.values()].map(({ geometryTypes, ...call }) => {
+        // One geometry type for the whole call: let the provider filter it too.
+        const only = geometryTypes.size === 1 ? [...geometryTypes][0] : undefined;
+        return only && !call.query.geometryType ? { ...call, query: { ...call.query, geometryType: only } } : call;
+    });
+    return { calls: list, layers: layers.length, deduplicated: layers.length - list.length, pushedDown };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * React integration (doc 19, §48). React owns the container; the engine owns everything spatial.
+ * No GIS logic here (Decision: React is the integration layer only).
+ *
+ * Two ways to use it:
+ * - `<MapView config provider createRenderer …>`: MapView creates the runtime (once per provider, realtime,
+ *   ontology and history) and destroys it on unmount. `config.layers` changes are applied through the runtime API,
+ *   `config.basemap` changes through setBasemap() — neither remounts.
+ * - `<MapView map={runtime}>`: a runtime made outside React (shared, headless-first, or kept across views). MapView
+ *   only mounts it into its container and unmounts it again; the owner destroys it.
+ *
+ * `config.viewport` is the initial camera; move the camera with `runtime.setViewport` / `fitBounds` / `flyTo`.
+ * `selection` makes selection controlled: the application owns it and pushes it in.
+ */
+import { type CSSProperties, type ReactNode } from 'react';
+import { MapEngineError } from '../core/errors.js';
+import type { Geofence, GeofenceEvent, MapConfig, MapViewport, Position, SelectionContext, TimeSetting } from '../core/types.js';
+import type { AnnotationProvider, AuthContext, JournalProvider, LinkProvider, OntologySpatialResolver, RealtimeProvider, SpatialDataProvider, TrackProvider } from '../data/contracts.js';
+import type { PickEvent, Renderer } from '../render/renderer.js';
+import { type MapRuntime, type MapRuntimeOptions } from '../runtime/runtime.js';
+/** Props for both forms. With `map={runtime}`, time, geofences and selectable are pushed only when given. */
+export interface MapViewCommonProps {
+    /** Application-owned time (ADR-010): live, or replay at a time. Omit for live. */
+    time?: TimeSetting;
+    /** Geofences evaluated on the client for display (doc 15). Authoritative alerts belong to the server. */
+    geofences?: Geofence[];
+    /** Live geofence transitions. In replay, read them with `useGeofences()`. */
+    onGeofence?: (event: GeofenceEvent) => void;
+    /** Controlled selection. Omit for uncontrolled (the map selects on click). */
+    selection?: {
+        objectIds: string[];
+        primaryObjectId?: string;
+        source?: string;
+    };
+    onSelect?: (selection: SelectionContext) => void;
+    onViewportChange?: (viewport: MapViewport) => void;
+    onMapClick?: (position: Position) => void;
+    /** Every click, with what it hit (null on empty map). Use this for tools that need positions over objects. */
+    onClick?: (event: {
+        position: Position;
+        hit: {
+            objectId: string;
+            layerId: string;
+        } | null;
+    }) => void;
+    /** Click-to-select on/off (default on). Turn off while an app tool uses clicks. */
+    selectable?: boolean;
+    onHover?: (hover: PickEvent | null) => void;
+    onError?: (error: MapEngineError) => void;
+    /** Non-fatal problems (a layer without a spatial capability, a mismatched visualization), from the first load on. */
+    onWarning?: (warning: MapEngineError) => void;
+    /** After the first load. */
+    onReady?: (runtime: MapRuntime) => void;
+    className?: string;
+    style?: CSSProperties;
+    /** Overlays (controls, popups). They can use the hooks from this module. */
+    children?: ReactNode;
+}
+/** MapView creates and owns the runtime. */
+export interface MapViewOwnedProps extends MapViewCommonProps {
+    map?: undefined;
+    config: MapConfig;
+    provider: SpatialDataProvider;
+    /** Snapshot + stream: changes arrive without reloading. Often the same object as `provider`. */
+    realtime?: RealtimeProvider;
+    /** Resolves layer ontology types to spatial bindings; missing capabilities are reported, not guessed. */
+    ontology?: OntologySpatialResolver;
+    /** Historical positions for track layers and replay. */
+    history?: TrackProvider;
+    /** Relations between objects, for link layers (doc 28 G4). */
+    links?: LinkProvider;
+    /** The event journal: replay rebuilds whole objects at a time (doc 29 §7–8). */
+    journal?: JournalProvider;
+    /** Where annotations are kept and shared (doc 28 G10). */
+    annotations?: AnnotationProvider;
+    /** Who is looking (doc 28 G13). Changing it hands the new identity to the providers and reloads, in place. */
+    auth?: AuthContext | null;
+    /** Called once per runtime. Keeps this module renderer-agnostic (e.g. `() => new MapLibreRenderer()`). */
+    createRenderer: () => Renderer;
+    runtimeOptions?: MapRuntimeOptions;
+}
+/** MapView shows a runtime it does not own (doc §48: `<MapView map={mapRuntime} />`). */
+export interface MapViewRuntimeProps extends MapViewCommonProps {
+    map: MapRuntime;
+}
+export type MapViewProps = MapViewOwnedProps | MapViewRuntimeProps;
+export declare function MapView(props: MapViewProps): import("react").JSX.Element;