@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/spatial/measure.js

@@ -0,0 +1,90 @@
+/**
+ * Measurements and generated shapes on the ground (doc 28 G9, doc 29 §14): length, area, bearing, destination,
+ * circles, ellipses and sectors as polygons. Spherical Earth (mean radius); good to well under 1 % at map scales.
+ */
+import { area as turfArea } from '@turf/area';
+import { toGeoJSON } from './geojson.js';
+import { distanceMeters } from './operations.js';
+const R = 6_371_008.8;
+const rad = (d) => (d * Math.PI) / 180;
+const deg = (r) => (r * 180) / Math.PI;
+/** Initial bearing from a to b, degrees clockwise from north [0, 360). */
+export function bearingDegrees(a, b) {
+    const f1 = rad(a.latitude);
+    const f2 = rad(b.latitude);
+    const dl = rad(b.longitude - a.longitude);
+    const y = Math.sin(dl) * Math.cos(f2);
+    const x = Math.cos(f1) * Math.sin(f2) - Math.sin(f1) * Math.cos(f2) * Math.cos(dl);
+    return (deg(Math.atan2(y, x)) + 360) % 360;
+}
+/** The position `meters` away from `from` along `bearing` (degrees clockwise from north). */
+export function destination(from, bearing, meters) {
+    const d = meters / R;
+    const t = rad(bearing);
+    const f1 = rad(from.latitude);
+    const l1 = rad(from.longitude);
+    const f2 = Math.asin(Math.sin(f1) * Math.cos(d) + Math.cos(f1) * Math.sin(d) * Math.cos(t));
+    const l2 = l1 + Math.atan2(Math.sin(t) * Math.sin(d) * Math.cos(f1), Math.cos(d) - Math.sin(f1) * Math.sin(f2));
+    return { latitude: deg(f2), longitude: ((deg(l2) + 540) % 360) - 180 };
+}
+/** Length of a line (or the sum of a multi-line), metres. */
+export function lengthMeters(geometry) {
+    const along = (pts) => pts.slice(1).reduce((sum, p, i) => sum + distanceMeters(pts[i], p), 0);
+    switch (geometry.type) {
+        case 'LineString':
+            return along(geometry.coordinates);
+        case 'MultiLineString':
+            return geometry.coordinates.reduce((s, l) => s + along(l), 0);
+        case 'Polygon':
+            return along(geometry.coordinates[0] ?? []);
+        case 'MultiPolygon':
+            return geometry.coordinates.reduce((s, p) => s + along(p[0] ?? []), 0);
+        case 'Circle':
+            return 2 * Math.PI * geometry.radiusMeters;
+        default:
+            return 0;
+    }
+}
+/** Area of an area geometry, square metres (holes subtracted); 0 for points and lines. */
+export function areaSquareMeters(geometry) {
+    if (geometry.type === 'Circle')
+        return Math.PI * geometry.radiusMeters ** 2;
+    if (geometry.type !== 'Polygon' && geometry.type !== 'MultiPolygon')
+        return 0;
+    return turfArea({ type: 'Feature', geometry: toGeoJSON(geometry), properties: {} });
+}
+export function measure(geometry) {
+    const out = { lengthMeters: lengthMeters(geometry), areaSquareMeters: areaSquareMeters(geometry) };
+    if (geometry.type === 'LineString' && geometry.coordinates.length >= 2) {
+        const pts = geometry.coordinates;
+        out.bearingDegrees = bearingDegrees(pts[0], pts[pts.length - 1]);
+        out.segments = pts.slice(1).map((p, i) => ({ lengthMeters: distanceMeters(pts[i], p), bearingDegrees: bearingDegrees(pts[i], p) }));
+    }
+    return out;
+}
+const ring = (pts) => ({ type: 'Polygon', coordinates: [[...pts, pts[0]]] });
+/** A circle as a polygon of `steps` points. */
+export function circlePolygon(center, radiusMeters, steps = 64) {
+    return ring(Array.from({ length: steps }, (_, i) => destination(center, (i * 360) / steps, radiusMeters)));
+}
+/** An ellipse as a polygon: semi-axes in metres, the major axis `orientation` degrees clockwise from north. */
+export function ellipsePolygon(center, semiMajor, semiMinor, orientation = 0, steps = 64) {
+    const pts = [];
+    for (let i = 0; i < steps; i++) {
+        const t = (i * 2 * Math.PI) / steps;
+        const along = semiMajor * Math.cos(t);
+        const across = semiMinor * Math.sin(t);
+        const r = Math.hypot(along, across);
+        pts.push(destination(center, orientation + deg(Math.atan2(across, along)), r));
+    }
+    return ring(pts);
+}
+/** A sector (pie slice) from `near` to `far` metres between two bearings, as a polygon. */
+export function sectorPolygon(center, fromBearing, toBearing, near, far, steps = 24) {
+    const span = (((toBearing - fromBearing) % 360) + 360) % 360 || 360;
+    const arc = (r, reverse) => {
+        const out = Array.from({ length: steps + 1 }, (_, i) => destination(center, fromBearing + (span * i) / steps, r));
+        return reverse ? out.reverse() : out;
+    };
+    return ring(near > 0 ? [...arc(far, false), ...arc(near, true)] : [center, ...arc(far, false)]);
+}

package/vendor/map-engine/spatial/operations.d.ts

@@ -0,0 +1,21 @@
+import type { BoundingBox, Geometry, Position, SpatialRelation } from '../core/types.js';
+/**
+ * True when every part of `a` lies inside `b` (OGC "within"). Each part of `a` must lie within one part of `b`, which
+ * is exact for valid multi-geometries (their parts do not overlap). Points in a circle use the true distance.
+ */
+export declare function within(a: Geometry, b: Geometry): boolean;
+/** True when `a` contains `b`. Defined as `within(b, a)` so both relations share one implementation. */
+export declare function contains(a: Geometry, b: Geometry): boolean;
+export declare function intersects(a: Geometry, b: Geometry): boolean;
+/** Great-circle distance in metres. */
+export declare function distanceMeters(a: Position, b: Position): number;
+/** Shortest distance in metres from a position to a geometry. Zero when inside an area or on a line. */
+export declare function distanceToGeometryMeters(position: Position, geometry: Geometry): number;
+export declare function intersectsBounds(geometry: Geometry, bounds: BoundingBox): boolean;
+/**
+ * Where one label for a geometry goes (one per object, never one per map tile): a point, the middle point of a
+ * line, a circle's centre, or a point guaranteed inside an area — the largest part of a multipolygon.
+ */
+export declare function labelPoint(geometry: Geometry, placement?: 'center' | 'top'): Position;
+/** Does `geometry` satisfy the relation? Candidate filtering by bounds happens first, exact geometry second. */
+export declare function matchesRelation(geometry: Geometry, relation: SpatialRelation): boolean;

package/vendor/map-engine/spatial/operations.js

@@ -0,0 +1,171 @@
+/**
+ * Spatial relations. Turf is an implementation detail of this file (ADR: no GIS maths from scratch,
+ * and the rest of the engine never imports Turf).
+ */
+import { area as turfArea } from '@turf/area';
+import { booleanIntersects } from '@turf/boolean-intersects';
+import { booleanWithin } from '@turf/boolean-within';
+import { distance as turfDistance } from '@turf/distance';
+import { pointToLineDistance } from '@turf/point-to-line-distance';
+import { lineIntersect } from '@turf/line-intersect';
+import { pointOnFeature } from '@turf/point-on-feature';
+import { pointToPolygonDistance } from '@turf/point-to-polygon-distance';
+import { boundsIntersect, boundsToPolygon, geometryBounds } from './geometry.js';
+import { fromGeoJSON, toFeature, toGeoJSON } from './geojson.js';
+const DIMENSION = { Point: 0, LineString: 1, Polygon: 2 };
+const point = (p) => toFeature({ type: 'Point', coordinates: p });
+/** A geometry as simple parts. A circle becomes its polygon here; tests that can use the true radius do. */
+function parts(g) {
+    switch (g.type) {
+        case 'MultiPoint':
+            return g.coordinates.map((coordinates) => ({ type: 'Point', coordinates }));
+        case 'MultiLineString':
+            return g.coordinates.map((coordinates) => ({ type: 'LineString', coordinates }));
+        case 'MultiPolygon':
+            return g.coordinates.map((coordinates) => ({ type: 'Polygon', coordinates }));
+        case 'Circle': {
+            const poly = toGeoJSON(g);
+            return [{ type: 'Polygon', coordinates: poly.coordinates.map((ring) => ring.map(([longitude, latitude]) => ({ latitude: latitude, longitude: longitude }))) }];
+        }
+        default:
+            return [g];
+    }
+}
+function simpleWithin(a, b) {
+    // A geometry cannot lie within a geometry of lower dimension (Turf throws for these pairs).
+    if (DIMENSION[a.type] > DIMENSION[b.type])
+        return false;
+    if (!boundsIntersect(geometryBounds(a), geometryBounds(b)))
+        return false;
+    if (a.type === 'Point' && b.type === 'Point') {
+        return a.coordinates.latitude === b.coordinates.latitude && a.coordinates.longitude === b.coordinates.longitude;
+    }
+    return booleanWithin(toFeature(a), toFeature(b));
+}
+/**
+ * True when every part of `a` lies inside `b` (OGC "within"). Each part of `a` must lie within one part of `b`, which
+ * is exact for valid multi-geometries (their parts do not overlap). Points in a circle use the true distance.
+ */
+export function within(a, b) {
+    if (b.type === 'Circle' && (a.type === 'Point' || a.type === 'MultiPoint')) {
+        const pts = a.type === 'Point' ? [a.coordinates] : a.coordinates;
+        return pts.every((p) => distanceMeters(p, b.center) <= b.radiusMeters);
+    }
+    if (!boundsIntersect(geometryBounds(a), geometryBounds(b)))
+        return false;
+    const bp = parts(b);
+    return parts(a).every((pa) => bp.some((pb) => simpleWithin(pa, pb)));
+}
+/** True when `a` contains `b`. Defined as `within(b, a)` so both relations share one implementation. */
+export function contains(a, b) {
+    return within(b, a);
+}
+export function intersects(a, b) {
+    if (!boundsIntersect(geometryBounds(a), geometryBounds(b)))
+        return false;
+    if (b.type === 'Circle' && a.type === 'Point')
+        return distanceMeters(a.coordinates, b.center) <= b.radiusMeters;
+    if (a.type === 'Circle' && b.type === 'Point')
+        return distanceMeters(b.coordinates, a.center) <= a.radiusMeters;
+    const bp = parts(b);
+    return parts(a).some((pa) => bp.some((pb) => booleanIntersects(toFeature(pa), toFeature(pb))));
+}
+/** Great-circle distance in metres. */
+export function distanceMeters(a, b) {
+    return turfDistance(point(a), point(b), { units: 'meters' });
+}
+function simpleDistance(position, geometry) {
+    switch (geometry.type) {
+        case 'Point':
+            return distanceMeters(position, geometry.coordinates);
+        case 'LineString':
+            return pointToLineDistance(point(position), toGeoJSON(geometry), { units: 'meters' });
+        case 'Polygon':
+            return Math.max(0, pointToPolygonDistance(point(position), toGeoJSON(geometry), { units: 'meters' }));
+    }
+}
+/** Shortest distance in metres from a position to a geometry. Zero when inside an area or on a line. */
+export function distanceToGeometryMeters(position, geometry) {
+    if (geometry.type === 'Circle')
+        return Math.max(0, distanceMeters(position, geometry.center) - geometry.radiusMeters);
+    return Math.min(...parts(geometry).map((p) => simpleDistance(position, p)));
+}
+export function intersectsBounds(geometry, bounds) {
+    if (!boundsIntersect(geometryBounds(geometry), bounds))
+        return false;
+    // Points whose box meets the bounds are inside them; no exact test needed.
+    if (geometry.type === 'Point')
+        return true;
+    return intersects(geometry, boundsToPolygon(bounds));
+}
+/**
+ * Where one label for a geometry goes (one per object, never one per map tile): a point, the middle point of a
+ * line, a circle's centre, or a point guaranteed inside an area — the largest part of a multipolygon.
+ */
+export function labelPoint(geometry, placement = 'center') {
+    if (placement === 'top' && (geometry.type === 'Polygon' || geometry.type === 'MultiPolygon' || geometry.type === 'Circle')) {
+        const top = topLabelPoint(geometry);
+        if (top)
+            return top;
+    }
+    switch (geometry.type) {
+        case 'Point':
+            return geometry.coordinates;
+        case 'Circle':
+            return geometry.center;
+        case 'MultiPoint':
+            return geometry.coordinates[0];
+        case 'LineString':
+            return geometry.coordinates[Math.floor(geometry.coordinates.length / 2)];
+        case 'MultiLineString': {
+            const longest = geometry.coordinates.reduce((a, b) => (b.length > a.length ? b : a));
+            return longest[Math.floor(longest.length / 2)];
+        }
+        case 'Polygon':
+        case 'MultiPolygon': {
+            const parts = geometry.type === 'Polygon' ? [geometry.coordinates] : geometry.coordinates;
+            const polys = parts.map((coordinates) => toFeature({ type: 'Polygon', coordinates }));
+            const largest = polys.reduce((a, b) => (turfArea(b) > turfArea(a) ? b : a));
+            return fromGeoJSON(pointOnFeature(largest).geometry).coordinates;
+        }
+    }
+}
+/**
+ * A point just inside the top of an area: on a line a little below the northmost point, the middle of the widest
+ * stretch that lies inside the area. Null when no such stretch exists (degenerate shapes).
+ */
+function topLabelPoint(geometry) {
+    const b = geometryBounds(geometry);
+    const lat = b.north - (b.north - b.south) * 0.06;
+    const across = toFeature({ type: 'LineString', coordinates: [{ latitude: lat, longitude: b.west - 1 }, { latitude: lat, longitude: b.east + 1 }] });
+    const area = toFeature(geometry);
+    const crossings = lineIntersect(across, area)
+        .features.map((f) => fromGeoJSON(f.geometry).coordinates.longitude)
+        .sort((x, y) => x - y);
+    let best = null;
+    for (let i = 0; i + 1 < crossings.length; i += 2) {
+        const w = crossings[i];
+        const e = crossings[i + 1];
+        if (!best || e - w > best[1] - best[0])
+            best = [w, e];
+    }
+    return best ? { latitude: lat, longitude: (best[0] + best[1]) / 2 } : null;
+}
+/** Does `geometry` satisfy the relation? Candidate filtering by bounds happens first, exact geometry second. */
+export function matchesRelation(geometry, relation) {
+    switch (relation.relation) {
+        case 'bbox':
+            return intersectsBounds(geometry, relation.bounds);
+        case 'within':
+            return within(geometry, relation.geometry);
+        case 'contains':
+            return contains(geometry, relation.geometry);
+        case 'intersects':
+            return intersects(geometry, relation.geometry);
+        case 'near':
+            return distanceToGeometryMeters(relation.position, geometry) <= relation.distanceMeters;
+        case 'nearest':
+            // Per object, only the distance cap applies; choosing the closest N is a ranking (rankByRelation).
+            return relation.maxDistanceMeters === undefined || distanceToGeometryMeters(relation.position, geometry) <= relation.maxDistanceMeters;
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { PropertyCondition, SpatialObject, SpatialQuery, ValidationResult } from '../core/types.js';
+/** Does a property value satisfy one condition? Numeric operators fail on values that are not numbers. */
+export declare function matchesCondition(value: unknown, c: PropertyCondition): boolean;
+/**
+ * Does an object satisfy the client-checkable parts of a query (ids, properties filter and conditions, bounds,
+ * relation)? `zoom` and `time` are provider hints and never filter here.
+ * `ontologyType` is not checkable here — objects do not carry their type; providers and subscriptions scope it.
+ * Cheap checks first, exact geometry last (candidate → exact, doc 13).
+ */
+export declare function matchesQuery(object: SpatialObject, query: SpatialQuery): boolean;
+/**
+ * Applies the ranking part of a query: for `nearest`, the `count` closest objects, closest first.
+ * Every other query keeps its order. Call after `matchesQuery` filtering.
+ */
+export declare function rankByRelation(objects: SpatialObject[], query: SpatialQuery): SpatialObject[];
+/** Checks property conditions (doc §10): known operator, and a value of the shape the operator needs. */
+export declare function validateConditions(value: unknown, where?: string): ValidationResult;

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

@@ -0,0 +1,88 @@
+import { deepEqual } from '../core/equal.js';
+import { geometryFamily } from '../core/geometry-family.js';
+import { distanceToGeometryMeters, intersectsBounds, matchesRelation } from './operations.js';
+const asNumber = (v) => (typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : Number.NaN);
+/** Does a property value satisfy one condition? Numeric operators fail on values that are not numbers. */
+export function matchesCondition(value, c) {
+    switch (c.op) {
+        case 'exists':
+            return value !== null && value !== undefined;
+        case 'eq':
+            return deepEqual(value, c.value);
+        case 'neq':
+            return !deepEqual(value, c.value);
+        case 'in':
+            return Array.isArray(c.value) && c.value.some((x) => deepEqual(value, x));
+        case 'between': {
+            const n = asNumber(value);
+            return Array.isArray(c.value) && n >= c.value[0] && n <= c.value[1];
+        }
+        case 'gt':
+            return asNumber(value) > c.value;
+        case 'gte':
+            return asNumber(value) >= c.value;
+        case 'lt':
+            return asNumber(value) < c.value;
+        case 'lte':
+            return asNumber(value) <= c.value;
+    }
+}
+/**
+ * Does an object satisfy the client-checkable parts of a query (ids, properties filter and conditions, bounds,
+ * relation)? `zoom` and `time` are provider hints and never filter here.
+ * `ontologyType` is not checkable here — objects do not carry their type; providers and subscriptions scope it.
+ * Cheap checks first, exact geometry last (candidate → exact, doc 13).
+ */
+export function matchesQuery(object, query) {
+    // A geometry type in a query stands for its family: a Point query also returns MultiPoint objects.
+    if (query.geometryType && geometryFamily(object.geometry.type) !== geometryFamily(query.geometryType))
+        return false;
+    if (query.objectIds && !query.objectIds.includes(object.objectId))
+        return false;
+    if (query.filter && !Object.entries(query.filter).every(([k, v]) => deepEqual(object.properties?.[k], v)))
+        return false;
+    if (query.where && !query.where.every((c) => matchesCondition(object.properties?.[c.property], c)))
+        return false;
+    if (query.bounds && !intersectsBounds(object.geometry, query.bounds))
+        return false;
+    if (query.spatial && !matchesRelation(object.geometry, query.spatial))
+        return false;
+    return true;
+}
+/**
+ * Applies the ranking part of a query: for `nearest`, the `count` closest objects, closest first.
+ * Every other query keeps its order. Call after `matchesQuery` filtering.
+ */
+export function rankByRelation(objects, query) {
+    const r = query.spatial;
+    if (!r || r.relation !== 'nearest')
+        return objects;
+    return objects
+        .map((o) => ({ o, d: distanceToGeometryMeters(r.position, o.geometry) }))
+        .sort((a, b) => a.d - b.d || a.o.objectId.localeCompare(b.o.objectId))
+        .slice(0, Math.max(0, Math.floor(r.count)))
+        .map((x) => x.o);
+}
+const CONDITION_OPS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'in'];
+/** Checks property conditions (doc §10): known operator, and a value of the shape the operator needs. */
+export function validateConditions(value, where = 'where') {
+    if (!Array.isArray(value))
+        return { valid: false, reason: `${where} must be an array of conditions` };
+    for (const [i, c] of value.entries()) {
+        const at = `${where}[${i}]`;
+        if (typeof c !== 'object' || c === null)
+            return { valid: false, reason: `${at} is not an object` };
+        const { property, op, value: v } = c;
+        if (typeof property !== 'string' || property === '')
+            return { valid: false, reason: `${at}.property must be a non-empty string` };
+        if (op !== 'exists' && !CONDITION_OPS.includes(op))
+            return { valid: false, reason: `${at}.op "${String(op)}" is not one of exists, ${CONDITION_OPS.join(', ')}` };
+        if (op === 'between' && !(Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number')))
+            return { valid: false, reason: `${at} "between" needs value [min, max]` };
+        if (op === 'in' && !Array.isArray(v))
+            return { valid: false, reason: `${at} "in" needs an array value` };
+        if (['gt', 'gte', 'lt', 'lte'].includes(op) && typeof v !== 'number')
+            return { valid: false, reason: `${at} "${op}" needs a number value` };
+    }
+    return { valid: true };
+}

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

@@ -0,0 +1,24 @@
+import type { BoundingBox, SpatialObject } from '../core/types.js';
+/** Index of objects the client has loaded. It is a lookup structure, not a data store or a security filter. */
+export interface SpatialIndex {
+    /** Inserts or replaces by objectId. */
+    insert(object: SpatialObject): void;
+    remove(objectId: string): void;
+    get(objectId: string): SpatialObject | undefined;
+    /** Candidates whose bounds intersect `bounds`. Exact relation tests are the caller's job. */
+    search(bounds: BoundingBox): SpatialObject[];
+    all(): SpatialObject[];
+    clear(): void;
+    readonly size: number;
+}
+export declare class RBushSpatialIndex implements SpatialIndex {
+    private readonly tree;
+    private readonly byId;
+    insert(object: SpatialObject): void;
+    remove(objectId: string): void;
+    get(objectId: string): SpatialObject | undefined;
+    search(bounds: BoundingBox): SpatialObject[];
+    all(): SpatialObject[];
+    clear(): void;
+    get size(): number;
+}

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

@@ -0,0 +1,36 @@
+import RBush from 'rbush';
+import { geometryBounds } from './geometry.js';
+export class RBushSpatialIndex {
+    tree = new RBush();
+    byId = new Map();
+    insert(object) {
+        this.remove(object.objectId);
+        const b = geometryBounds(object.geometry);
+        const entry = { minX: b.west, minY: b.south, maxX: b.east, maxY: b.north, object };
+        this.tree.insert(entry);
+        this.byId.set(object.objectId, entry);
+    }
+    remove(objectId) {
+        const entry = this.byId.get(objectId);
+        if (!entry)
+            return;
+        this.tree.remove(entry);
+        this.byId.delete(objectId);
+    }
+    get(objectId) {
+        return this.byId.get(objectId)?.object;
+    }
+    search(bounds) {
+        return this.tree.search({ minX: bounds.west, minY: bounds.south, maxX: bounds.east, maxY: bounds.north }).map((e) => e.object);
+    }
+    all() {
+        return [...this.byId.values()].map((e) => e.object);
+    }
+    clear() {
+        this.tree.clear();
+        this.byId.clear();
+    }
+    get size() {
+        return this.byId.size;
+    }
+}

package/vendor/map-engine/spatial/volume-mesh.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Coverage volumes as meshes (phase 3E): a dome (sphere cap from the horizon up) or a wedge (a sector between an
+ * azimuth ± beamWidth/2 and two elevation angles), at unit radius in local metres — x east, y north, z up — so a
+ * renderer scales it by the range and turns it by the azimuth. Closed surfaces (outer shell + side faces), flat
+ * normals, plain triangles. Geometry only: what a sensor can actually see is the data side's concern.
+ */
+export interface VolumeShape {
+    shape: 'dome' | 'wedge';
+    /** Degrees; wedge only. */
+    beamWidth?: number;
+    /** Degrees above the horizon. Defaults 0 and 90. */
+    minElevation?: number;
+    maxElevation?: number;
+}
+export interface VolumeMesh {
+    positions: Float32Array;
+    normals: Float32Array;
+}
+export declare function volumeMesh(v: VolumeShape, segments?: number): VolumeMesh;

package/vendor/map-engine/spatial/volume-mesh.js

@@ -0,0 +1,56 @@
+const rad = (d) => (d * Math.PI) / 180;
+/** A point on the unit sphere at an azimuth (clockwise from north) and elevation. */
+function onSphere(azimuthDeg, elevationDeg) {
+    const az = rad(azimuthDeg);
+    const el = rad(elevationDeg);
+    return [Math.cos(el) * Math.sin(az), Math.cos(el) * Math.cos(az), Math.sin(el)];
+}
+export function volumeMesh(v, segments = 32) {
+    const wedge = v.shape === 'wedge';
+    const half = wedge ? Math.min(180, (v.beamWidth ?? 60) / 2) : 180;
+    const lo = v.minElevation ?? 0;
+    const hi = v.maxElevation ?? 90;
+    const az0 = -half;
+    const az1 = half;
+    const nAz = Math.max(4, Math.round((segments * (az1 - az0)) / 360));
+    const nEl = Math.max(2, Math.round((segments * (hi - lo)) / 180));
+    const pos = [];
+    const nor = [];
+    const tri = (a, b, c) => {
+        const u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+        const w = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+        let n = [u[1] * w[2] - u[2] * w[1], u[2] * w[0] - u[0] * w[2], u[0] * w[1] - u[1] * w[0]];
+        const len = Math.hypot(n[0], n[1], n[2]) || 1;
+        n = n.map((x) => x / len);
+        pos.push(...a, ...b, ...c);
+        nor.push(...n, ...n, ...n);
+    };
+    const O = [0, 0, 0];
+    const at = (i, j) => onSphere(az0 + ((az1 - az0) * i) / nAz, lo + ((hi - lo) * j) / nEl);
+    // Outer shell.
+    for (let i = 0; i < nAz; i++) {
+        for (let j = 0; j < nEl; j++) {
+            const a = at(i, j);
+            const b = at(i + 1, j);
+            const c = at(i + 1, j + 1);
+            const d = at(i, j + 1);
+            tri(a, b, c);
+            tri(a, c, d);
+        }
+    }
+    // Lower and upper cones (fans to the origin), unless they are flat at the horizon or closed at the zenith.
+    if (lo > -90)
+        for (let i = 0; i < nAz; i++)
+            tri(O, at(i + 1, 0), at(i, 0));
+    if (hi < 90)
+        for (let i = 0; i < nAz; i++)
+            tri(O, at(i, nEl), at(i + 1, nEl));
+    // Side faces of a wedge.
+    if (wedge && half < 180) {
+        for (let j = 0; j < nEl; j++) {
+            tri(O, at(0, j), at(0, j + 1));
+            tri(O, at(nAz, j + 1), at(nAz, j));
+        }
+    }
+    return { positions: new Float32Array(pos), normals: new Float32Array(nor) };
+}

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

@@ -0,0 +1,3 @@
+export { appendPoint, bearing, normalizeTrack, stateAt, toIso, toMs, trailBetween, validateTrack, type StateAt } from './tracks.js';
+export { Playback, type PlaybackOptions } from './playback.js';
+export { groupJournal, journalStateAt } from './journal.js';

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

@@ -0,0 +1,3 @@
+export { appendPoint, bearing, normalizeTrack, stateAt, toIso, toMs, trailBetween, validateTrack } from './tracks.js';
+export { Playback } from './playback.js';
+export { groupJournal, journalStateAt } from './journal.js';

package/vendor/map-engine/temporal/journal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rebuilding objects at a time from an event journal (doc 29 §7–8). Pure: entries in, state out. The journal itself
+ * comes from a provider; the engine never stores history.
+ */
+import type { SpatialObject } from '../core/types.js';
+/** The journal kinds the reconstruction understands; any other kind carrying an `object` counts as an update. */
+interface Entry {
+    at: string;
+    objectId: string;
+    kind: string;
+    object?: SpatialObject;
+}
+/** Entries grouped by object, oldest first (stable for equal times). */
+export declare function groupJournal<E extends Entry>(entries: E[]): Map<string, E[]>;
+/**
+ * One object's state at `atMs`: its last entry at or before that time. Absent (null) when it did not exist yet,
+ * or its last entry says it was removed. `undefined` when the journal says nothing about it at all.
+ */
+export declare function journalStateAt<E extends Entry>(entries: E[] | undefined, atMs: number): SpatialObject | null | undefined;
+export {};

package/vendor/map-engine/temporal/journal.js

@@ -0,0 +1,34 @@
+/** Entries grouped by object, oldest first (stable for equal times). */
+export function groupJournal(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        if (!e || typeof e.objectId !== 'string' || !Number.isFinite(Date.parse(e.at)))
+            continue;
+        let list = out.get(e.objectId);
+        if (!list)
+            out.set(e.objectId, (list = []));
+        list.push(e);
+    }
+    for (const list of out.values())
+        list.sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+    return out;
+}
+/**
+ * One object's state at `atMs`: its last entry at or before that time. Absent (null) when it did not exist yet,
+ * or its last entry says it was removed. `undefined` when the journal says nothing about it at all.
+ */
+export function journalStateAt(entries, atMs) {
+    if (!entries?.length)
+        return undefined;
+    let last;
+    for (const e of entries) {
+        if (Date.parse(e.at) > atMs)
+            break;
+        last = e;
+    }
+    if (!last)
+        return null; // first known after this time: not there yet
+    if (last.kind === 'removed' || !last.object)
+        return null;
+    return last.object;
+}

package/vendor/map-engine/temporal/playback.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A playback clock for replay (doc 07). The application owns time (ADR-010): it creates a Playback, shows its
+ * controls, and passes each tick to `runtime.setTime`. The engine never runs a clock on its own.
+ */
+import type { TimeRange } from '../core/types.js';
+export interface PlaybackOptions {
+    range: TimeRange;
+    /** Start position. Default: range start. */
+    at?: string;
+    /** Simulated seconds per real second. Default 1. */
+    speed?: number;
+    /** Called with the new time on every tick and seek. */
+    onTime: (at: string) => void;
+    /** Called when playback reaches the end of the range (and stops). */
+    onEnd?: () => void;
+    /** Schedules the next frame. Default: requestAnimationFrame, else a 50 ms timer. */
+    frame?: (cb: (nowMs: number) => void) => void;
+    now?: () => number;
+}
+export declare class Playback {
+    private readonly options;
+    private atMs;
+    private startMs;
+    private endMs;
+    private speed;
+    private playing;
+    private lastReal;
+    private generation;
+    private readonly frame;
+    private readonly now;
+    constructor(options: PlaybackOptions);
+    get time(): string;
+    get isPlaying(): boolean;
+    get rate(): number;
+    get range(): TimeRange;
+    play(): void;
+    pause(): void;
+    seek(at: string): void;
+    setSpeed(speed: number): void;
+    dispose(): void;
+}