@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/core/types.d.ts

@@ -0,0 +1,709 @@
+/**
+ * Public contracts of the Map Engine.
+ *
+ * Coordinates are semantic: `{ latitude, longitude }` in WGS84 (EPSG:4326).
+ * GeoJSON's `[longitude, latitude]` order exists only in `spatial/geojson.ts`.
+ */
+export type Unsubscribe = () => void;
+/** A WGS84 position. Latitude in [-90, 90], longitude in [-180, 180]. */
+export interface Position {
+    latitude: number;
+    longitude: number;
+    /**
+     * Metres (ADR-028). What it is measured from is not guessed: a layer that draws heights declares the reference
+     * (`visualization.elevation.reference`). Without altitude, a position is on the ground (or on terrain).
+     */
+    altitude?: number;
+}
+export interface PointGeometry {
+    type: 'Point';
+    coordinates: Position;
+}
+export interface LineStringGeometry {
+    type: 'LineString';
+    coordinates: Position[];
+}
+/** Rings are closed (first position equals last). The first ring is the outer boundary; the rest are holes. */
+export interface PolygonGeometry {
+    type: 'Polygon';
+    coordinates: Position[][];
+}
+export interface MultiPointGeometry {
+    type: 'MultiPoint';
+    coordinates: Position[];
+}
+export interface MultiLineStringGeometry {
+    type: 'MultiLineString';
+    coordinates: Position[][];
+}
+export interface MultiPolygonGeometry {
+    type: 'MultiPolygon';
+    coordinates: Position[][][];
+}
+/**
+ * A circle on the ground: a centre and a radius in metres. GeoJSON has no circle, so it becomes a polygon only where
+ * it must (GeoJSON export, rendering); containment tests use the true distance.
+ */
+export interface CircleGeometry {
+    type: 'Circle';
+    center: Position;
+    radiusMeters: number;
+}
+export type Geometry = PointGeometry | LineStringGeometry | PolygonGeometry | MultiPointGeometry | MultiLineStringGeometry | MultiPolygonGeometry | CircleGeometry;
+export type GeometryType = Geometry['type'];
+/** Geometries an area visualization can draw and a geofence can use. */
+export type AreaGeometry = PolygonGeometry | MultiPolygonGeometry | CircleGeometry;
+/** What a geometry looks like on a map: a point, a line, or an area. Layers draw one family. */
+export type GeometryFamily = 'point' | 'line' | 'area';
+/** Pixels kept clear at each side of the map (for panels over it). A number pads all sides alike. */
+export type Padding = number | {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Axis-aligned bounds in degrees. MVP does not wrap the antimeridian: west <= east. */
+export interface BoundingBox {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+/** A spatial projection of an Ontology object. `objectId` is the stable identity shared with tables, charts and inspectors. */
+export interface SpatialObject {
+    objectId: string;
+    geometry: Geometry;
+    properties?: Record<string, unknown>;
+    /** When the source observed this state (ISO 8601). Used to reject stale realtime updates and to age objects. */
+    observedAt?: string;
+    /** When the source system received it (ISO 8601), for display; ordering uses `observedAt`. */
+    receivedAt?: string;
+    /** The state holds from / until (ISO 8601). Outside this window the object is not drawn (it stays queryable). */
+    validFrom?: string;
+    validUntil?: string;
+    /** How sure the source is, 0…1. What it means is the source's business; the map only shows it. */
+    confidence?: number;
+    /** Where the position may really be. */
+    uncertainty?: PositionUncertainty;
+    /** Unresolved: candidate geometries besides this one, until the source says which holds (doc 29 §4). */
+    alternatives?: ObjectAlternative[];
+    /** Where this came from, passed through untouched (UNS owns provenance; doc 29 §10). */
+    provenance?: Provenance;
+    /** Properties the user may not see: the provider removed their values (doc 28 G13). */
+    redacted?: string[];
+}
+/** An error around a position: a radius, or an ellipse (semi-axes in metres, major axis clockwise from north). */
+export interface PositionUncertainty {
+    radiusMeters?: number;
+    ellipse?: {
+        semiMajorMeters: number;
+        semiMinorMeters: number;
+        orientationDegrees?: number;
+    };
+}
+/** One candidate geometry of an unresolved object. */
+export interface ObjectAlternative {
+    id?: string;
+    geometry: Geometry;
+    /** 0…1, as the source states it. */
+    probability?: number;
+    label?: string;
+}
+/** Source, time, version and marking of an object or of one property. The engine never interprets it. */
+export interface Provenance {
+    source?: string;
+    observedAt?: string;
+    version?: string | number;
+    classification?: string;
+    signature?: 'valid' | 'invalid' | 'unsigned' | 'unknown';
+    /** Upstream ids or names this was derived from, nearest first. */
+    lineage?: string[];
+    /** Per-property provenance, when properties come from different places. */
+    properties?: Record<string, Omit<Provenance, 'properties'>>;
+    extra?: Record<string, unknown>;
+}
+export type SpatialRelation = {
+    relation: 'bbox';
+    bounds: BoundingBox;
+} | {
+    relation: 'within';
+    geometry: Geometry;
+} | {
+    relation: 'contains';
+    geometry: Geometry;
+} | {
+    relation: 'intersects';
+    geometry: Geometry;
+} | {
+    relation: 'near';
+    position: Position;
+    distanceMeters: number;
+}
+/** A ranking, not a filter: the `count` closest objects to `position`, optionally within `maxDistanceMeters`. */
+ | {
+    relation: 'nearest';
+    position: Position;
+    count: number;
+    maxDistanceMeters?: number;
+};
+/**
+ * One property condition (doc §10 filters): `property` compared with `value` using the same operators as style
+ * rules, plus `exists` (the property has a non-null value; no `value`). `between` takes [min, max] (inclusive),
+ * `in` an array, `gt`/`gte`/`lt`/`lte` a number.
+ */
+export interface PropertyCondition {
+    property: string;
+    op: RuleOperator | 'exists';
+    value?: unknown;
+}
+/**
+ * What a layer (or an application) wants. Every filtering field narrows the result.
+ * `bounds` is the viewport data boundary the runtime adds (ADR-013).
+ * `zoom` and `time` are hints (doc §13): they never narrow the result on the client, but a provider may use them
+ * to send less detail when zoomed out, or only what existed during the time range.
+ */
+export interface SpatialQuery {
+    ontologyType?: string;
+    /** Only objects with this geometry type. Layers set it (a layer draws one type), so rankings like
+     *  `nearest` count only objects the layer can show, and providers send nothing it cannot draw. */
+    geometryType?: GeometryType;
+    objectIds?: string[];
+    spatial?: SpatialRelation;
+    bounds?: BoundingBox;
+    /** Exact property values (shorthand for `eq` conditions). */
+    filter?: Record<string, unknown>;
+    /** Property conditions, all of which must hold. */
+    where?: PropertyCondition[];
+    /** Hint: the zoom the result will be shown at. */
+    zoom?: number;
+    /** Hint: the time range being shown (replay). Absent when live. */
+    time?: TimeRange;
+}
+export interface MapViewport {
+    center: Position;
+    zoom: number;
+    /** Degrees clockwise from north, in [0, 360). */
+    bearing?: number;
+    /** Degrees from vertical, in [0, 85]. */
+    pitch?: number;
+    /** Visible bounds, reported by the renderer or computed by the runtime. */
+    bounds?: BoundingBox;
+}
+export type VisualizationType = 'marker' | 'line' | 'polygon' | 'heatmap' | 'track' | 'extrusion' | 'model' | 'volume' | 'link' | 'image';
+export type IconShape = 'circle' | 'square' | 'triangle' | 'diamond' | 'arrow';
+export type RuleOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'in';
+/**
+ * Generic style rule. First match wins; a rule without `property` matches everything (the fallback).
+ * Compare `property` with `value` using `op` (default 'eq'). `between` takes [min, max] (inclusive), `in` an array.
+ * `equals` is the original shorthand for `op: 'eq', value`.
+ */
+export interface StyleRule {
+    property?: string;
+    op?: RuleOperator;
+    value?: unknown;
+    equals?: unknown;
+    style: StyleTokens;
+}
+export interface StyleTokens {
+    color?: string;
+    /** Marker layers with an icon: an image for objects matching this rule (e.g. a different marker per status). */
+    imageUrl?: string;
+    size?: number;
+    opacity?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    /** Lines and area outlines: dashed, as dash and gap lengths in line widths (e.g. [2, 2]). Omit for solid. */
+    dash?: number[];
+    /** Model layers: a glTF/GLB model for objects matching this rule. */
+    modelUrl?: string;
+    label?: string;
+}
+export interface LabelConfig {
+    /** Object property whose value is drawn as text. */
+    property: string;
+    size?: number;
+    color?: string;
+    haloColor?: string;
+    /** Hide labels below this zoom (decluttering). */
+    minZoom?: number;
+    /**
+     * Areas only: where the one label goes. 'center' (default) inside the middle; 'top' just inside the top edge —
+     * for large or nested areas (operating areas, zones) whose middles hold other things.
+     */
+    placement?: 'center' | 'top';
+}
+/** Marker icon: a built-in shape (recoloured by style rules) or an image URL (drawn as is). */
+export interface IconConfig {
+    shape?: IconShape;
+    imageUrl?: string;
+    /** Object property holding a rotation in degrees clockwise from north (e.g. heading). */
+    rotateBy?: string;
+    /** Icon size in pixels. Default 18. */
+    size?: number;
+}
+/** Group nearby markers into counted bubbles until `maxZoom`. Rendering-side clustering of loaded objects. */
+export interface ClusterConfig {
+    /** Pixel radius within which markers merge. Default 50. */
+    radius?: number;
+    /** Last zoom with clusters. Default 14. */
+    maxZoom?: number;
+}
+/** Density surface over points. Weight comes from a numeric property (default 1 per object). */
+export interface HeatmapConfig {
+    weightProperty?: string;
+    /** Multiplies the weight. Default 1. */
+    weightScale?: number;
+    /** Pixel radius of influence. Default 24. */
+    radius?: number;
+    intensity?: number;
+}
+/** What an altitude is measured from (ADR-028). Never guessed: a layer that draws heights says which. */
+export type AltitudeReference = 'msl' | 'agl' | 'ellipsoid';
+/**
+ * Draw points and lines at a height (ADR-028): from the geometry's `altitude`, or from a numeric property.
+ * `msl` = above mean sea level, `agl` = above the ground/terrain, `ellipsoid` = GNSS height.
+ */
+export interface ElevationConfig {
+    from: 'geometry' | 'property';
+    /** With `from: 'property'`: the property holding metres. */
+    property?: string;
+    reference: AltitudeReference;
+    /** Multiplies heights (to make low flight visible). Default 1. */
+    exaggeration?: number;
+    /** A thin line from each object down to the ground. */
+    stems?: boolean;
+    /** The object's footprint drawn on the ground under it. */
+    shadow?: boolean;
+}
+/** Areas raised into blocks (buildings, zones with a ceiling). Heights in metres, fixed or from properties. */
+export interface ExtrusionConfig {
+    height?: number;
+    heightProperty?: string;
+    /** Where the block starts (a floating volume). Default 0. */
+    base?: number;
+    baseProperty?: string;
+}
+/** A 3D model (glTF/GLB) at each point, oriented by properties. Per-rule models use `style.modelUrl`. */
+export interface ModelConfig {
+    url?: string;
+    /** Model size in metres along its longest side; omit to use the model's own units (metres). */
+    sizeMeters?: number;
+    /** Degrees clockwise from north. */
+    headingProperty?: string;
+    pitchProperty?: string;
+    rollProperty?: string;
+    /**
+     * A fixed correction for a model file that does not follow glTF's axes, in degrees. A glTF file has +Y up and
+     * its front facing +Z; such a file faces its heading with no correction. Added to the orientation from properties.
+     */
+    axis?: {
+        pitch?: number;
+        yaw?: number;
+        roll?: number;
+    };
+}
+/**
+ * A coverage volume at each point (sensor range): a `dome` (sphere cap of a range), or a `wedge` (a sector of a
+ * range between an azimuth ± beamWidth/2 and between two elevation angles). Values fixed or from properties.
+ */
+export interface VolumeConfig {
+    shape: 'dome' | 'wedge';
+    range?: number;
+    rangeProperty?: string;
+    /** Wedge centre, degrees clockwise from north. */
+    azimuth?: number;
+    azimuthProperty?: string;
+    /** Wedge opening, degrees. */
+    beamWidth?: number;
+    beamWidthProperty?: string;
+    /** Degrees above the horizon. Defaults 0 and 90. */
+    minElevation?: number;
+    maxElevation?: number;
+}
+/** Trail of recent positions (doc 07). Drawn as a line ending at the current time (live) or at the replay time. */
+export interface TrackVisualizationConfig {
+    /** Trail length in minutes. Default 30. */
+    windowMinutes?: number;
+}
+export interface VisualizationConfig {
+    type: VisualizationType;
+    /** Track layers only. */
+    track?: TrackVisualizationConfig;
+    style?: StyleRule[];
+    /** Text from an object property. Needs a label font in the basemap config. */
+    label?: LabelConfig;
+    /** Markers only. */
+    icon?: IconConfig;
+    /** Markers only. */
+    cluster?: ClusterConfig;
+    /** Heatmap layers only. */
+    heatmap?: HeatmapConfig;
+    /** Marker, line, track, model and volume layers: draw at a height (ADR-028). */
+    elevation?: ElevationConfig;
+    /** Extrusion layers only. */
+    extrusion?: ExtrusionConfig;
+    /** Model layers only. */
+    model?: ModelConfig;
+    /** Volume layers only. */
+    volume?: VolumeConfig;
+    /** How old an object may be before it ages (doc 28 G1): sets `$age` for rules, and fades. */
+    age?: AgeConfig;
+    /** Continuous styling: a number property mapped onto a style token (e.g. confidence → opacity). */
+    scales?: StyleScale[];
+    /** Point layers: draw each object's position error, and its unresolved alternatives. */
+    uncertainty?: UncertaintyDisplay;
+    /** Point layers: range rings around each object, following it. */
+    rings?: RingsConfig;
+    /** Point layers: the ground area a camera at each object sees. */
+    footprint?: FootprintConfig;
+    /** Link layers only: lines between linked objects. */
+    link?: LinkConfig;
+    /** Image layers only: a picture pinned to the ground by each object's four corners. */
+    image?: ImageOverlayConfig;
+}
+/**
+ * Age states from the time since `observedAt` (live: the clock; replay: the replay time). Objects without
+ * `observedAt` never age. Rules can use `$age` ('fresh' | 'ageing' | 'stale' | 'lost').
+ */
+export interface AgeConfig {
+    /** Default: half of staleAfterSeconds. */
+    ageingAfterSeconds?: number;
+    staleAfterSeconds: number;
+    /** Default: never lost. */
+    lostAfterSeconds?: number;
+    /** Fade ageing and stale objects (opacity 0.7 / 0.4, lost 0.2). Default true. */
+    fade?: boolean;
+    /** Leave lost objects off the map. Default false. */
+    hideLost?: boolean;
+}
+/** Linear mapping of a number onto a token, clamped to the range. `property` may be `$confidence`. */
+export interface StyleScale {
+    property: string;
+    token: 'opacity' | 'size' | 'strokeWidth' | 'color' | 'strokeColor';
+    domain: [number, number];
+    /** Numbers, or two colours (#RRGGBB) to blend between. */
+    range: [number, number] | [string, string];
+}
+export interface UncertaintyDisplay {
+    color?: string;
+    /** Fill opacity of the error areas. Default 0.15. */
+    opacity?: number;
+    /** Also draw unresolved alternatives (dashed, joined to the object). Default true. */
+    alternatives?: boolean;
+}
+export interface RingsConfig {
+    distancesMeters: number[];
+    color?: string;
+    /** Label each ring with its distance. Default true. */
+    labels?: boolean;
+}
+/**
+ * A camera's ground footprint from where it is and where it looks. With a height above ground the footprint runs
+ * from the near to the far edge of the view; without one (or looking at the horizon) it reaches `maxRangeMeters`.
+ */
+export interface FootprintConfig {
+    /** Degrees clockwise from north. */
+    headingProperty: string;
+    /** Degrees below the horizon. */
+    pitchProperty?: string;
+    pitch?: number;
+    /** Horizontal field of view, degrees. */
+    fovProperty?: string;
+    fov?: number;
+    /** Vertical field of view, degrees. Default 3/4 of the horizontal. */
+    fovVertical?: number;
+    /** Height above the ground, metres. */
+    heightProperty?: string;
+    height?: number;
+    /** Default 5000. */
+    maxRangeMeters?: number;
+    color?: string;
+}
+/** Which links a link layer draws: between objects on the map, by link type (all when omitted). */
+export interface LinkConfig {
+    types?: string[];
+}
+export interface ImageOverlayConfig {
+    /** Property holding the image URL; or one `url` for all. */
+    urlProperty?: string;
+    url?: string;
+    /** Default 0.85. */
+    opacity?: number;
+}
+export interface InteractionConfig {
+    selectable?: boolean;
+    hoverable?: boolean;
+}
+/** What to load. A layer never names a database (ADR-005). */
+export interface LayerSource {
+    ontologyType?: string;
+    objectIds?: string[];
+    spatialQuery?: SpatialRelation;
+    /** Exact property values (shorthand for `eq` conditions). */
+    filter?: Record<string, unknown>;
+    /** Property conditions, all of which must hold (e.g. status in [FAULT, ALARM], speed > 50). */
+    where?: PropertyCondition[];
+}
+export interface MapLayer {
+    id: string;
+    source: LayerSource;
+    visible: boolean;
+    zIndex: number;
+    visualization: VisualizationConfig;
+    interaction?: InteractionConfig;
+}
+export interface SelectionContext {
+    objectIds: string[];
+    primaryObjectId?: string;
+    /** Who changed the selection: 'map', 'api', or an application component name. */
+    source: string;
+    timestamp: number;
+}
+/** A SpatialObject participating in the current scene through one layer. */
+export interface SceneObject {
+    /** `${layerId}:${objectId}` — one object can appear in several layers. */
+    key: string;
+    layerId: string;
+    object: SpatialObject;
+    selected: boolean;
+    hovered: boolean;
+}
+export interface SceneState {
+    viewport: MapViewport;
+    layers: MapLayer[];
+    objects: SceneObject[];
+    selection?: SelectionContext;
+}
+export interface ScenePatch {
+    added?: SceneObject[];
+    updated?: SceneObject[];
+    /** Scene object keys. */
+    removed?: string[];
+    /** Present when layer definitions (order, visibility, style) changed. */
+    layers?: MapLayer[];
+}
+export interface BasemapConfig {
+    kind: 'none' | 'style' | 'tiles';
+    styleUrl?: string;
+    tileUrl?: string;
+    attribution?: string;
+    /**
+     * The deepest zoom the raster tiles (`tileUrl`, or `rasterFallback`) exist at. Closer in, the renderer stretches
+     * that level instead of asking for tiles a server answers with a "no data" picture. Default: none (ask freely).
+     */
+    maxZoom?: number;
+    /** Background colour when kind is 'none'. */
+    background?: string;
+    /**
+     * Font file for labels (any format the browser can load, e.g. woff2), supplied by the application so the
+     * engine bundles no font and needs no glyph server. Without it, layer labels are not drawn.
+     */
+    font?: {
+        name: string;
+        url: string;
+    };
+    /**
+     * A raster `{z}/{x}/{y}` tile URL showing the same map, for renderers that cannot draw a vector style (the 3D
+     * globe). Only used with `kind: 'style'`.
+     */
+    rasterFallback?: string;
+    /** Credit for the `rasterFallback` tiles (a style carries its own; fallback tiles often come from elsewhere). */
+    rasterFallbackAttribution?: string;
+}
+/**
+ * Elevation tiles for terrain (raster DEM), configured like the basemap: the engine runs no terrain service, and
+ * licensing is the deployment's concern (§25). Development may use public dev-only sources.
+ */
+export interface TerrainConfig {
+    /** `{z}/{x}/{y}` URL of DEM tiles. */
+    tileUrl: string;
+    /** How heights are packed into the tile colours. Default 'terrarium'. */
+    encoding?: 'terrarium' | 'mapbox';
+    tileSize?: number;
+    maxZoom?: number;
+    attribution?: string;
+    /** Multiplies terrain heights. Default 1. */
+    exaggeration?: number;
+    /** Contour lines from the same DEM tiles (doc 28 G11). */
+    contours?: ContourConfig;
+}
+export interface ContourConfig {
+    /** Metres between lines. */
+    interval: number;
+    /** Every Nth line is an index line (bolder, labelled). Default 5. */
+    majorEvery?: number;
+    color?: string;
+}
+/**
+ * What a renderer can draw beyond flat 2D (ADR-026..028). The runtime compares a map's needs with these and
+ * reports MISSING_CAPABILITY instead of leaving a layer silently empty. Absent means no.
+ */
+export interface RendererCapabilities {
+    /** `projection: 'globe'`. */
+    globe?: boolean;
+    /** `terrain` relief. */
+    terrain?: boolean;
+    /** Points and lines drawn at their height (`visualization.elevation`). */
+    altitude?: boolean;
+    extrusion?: boolean;
+    models?: boolean;
+    volumes?: boolean;
+    tiles3d?: boolean;
+    /** Can answer sampleElevation() from its terrain. */
+    elevation?: boolean;
+}
+/**
+ * A 3D Tiles tileset (phase 3E): city meshes, photogrammetry, detailed terrain — scenery, not data objects. Configured
+ * by URL like the basemap (self-hostable; no Cesium Ion). Needs the renderer's `tiles3d` capability.
+ */
+export interface TilesetConfig {
+    id: string;
+    /** URL of the tileset.json. */
+    url: string;
+    label?: string;
+    /** Detail: lower is sharper and heavier. Default 16. */
+    maximumScreenSpaceError?: number;
+    /** Default true. */
+    show?: boolean;
+}
+export interface MapConfig {
+    viewport: MapViewport;
+    basemap: BasemapConfig;
+    layers: MapLayer[];
+    /** Flat map (default) or a globe (ADR-026). */
+    projection?: 'mercator' | 'globe';
+    /** Ground relief from elevation tiles; without it the ground is flat at 0 m. */
+    terrain?: TerrainConfig;
+    /** 3D Tiles scenery (phase 3E). */
+    tilesets?: TilesetConfig[];
+    /**
+     * A disconnected site (doc 28 G14): every URL the map uses (basemap, fonts, terrain, scenery, icons, models) must
+     * be relative or on an allowed origin; anything else is refused when the config is set. `true` = relative only.
+     */
+    offline?: boolean | {
+        allowedOrigins: string[];
+    };
+}
+/** What a user made on the map (doc 29 §5): first-class, separate from application data. */
+export type AnnotationKind = 'point' | 'line' | 'polygon' | 'rectangle' | 'circle' | 'measurement' | 'label' | 'note';
+export interface Annotation {
+    id: string;
+    kind: AnnotationKind;
+    geometry: Geometry;
+    label?: string;
+    note?: string;
+    /** Overrides the default look (colour, width, opacity, dash). */
+    style?: StyleTokens;
+    author?: string;
+    /** ISO 8601. */
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A geometry an agent (or anyone) suggests; a person accepts it (it becomes an annotation) or rejects it. */
+export interface Proposal {
+    id: string;
+    geometry: Geometry;
+    label?: string;
+    note?: string;
+    /** Who suggested it, e.g. `agent:route-planner`. */
+    origin: string;
+    createdAt: string;
+}
+/** A temporary emphasis on objects that does not change the selection. */
+export interface Highlight {
+    objectIds: string[];
+    color?: string;
+    /** ISO 8601; absent = until cleared. */
+    until?: string;
+    origin?: string;
+}
+/** What a layer shows right now, for the application to tell its users (doc 28 G13). */
+export type LayerStatus = 'ok' | 'loading' | 'denied' | 'error' | 'missing-capability';
+export interface Size {
+    width: number;
+    height: number;
+}
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/** ISO 8601 timestamps. */
+export interface TimeRange {
+    start: string;
+    end: string;
+}
+/** One observed position. Flat latitude/longitude as in doc 07 (still semantic, never `[lon, lat]`). */
+export interface TrackPoint {
+    timestamp: string;
+    latitude: number;
+    longitude: number;
+    altitude?: number;
+    speed?: number;
+    /** Degrees clockwise from north. When missing, it is derived from neighbouring points. */
+    heading?: number;
+}
+/** Ordered positions of one object over time. */
+export interface Track {
+    objectId: string;
+    points: TrackPoint[];
+    /** The object's properties, so replay can show objects that are no longer in today's data. */
+    properties?: Record<string, unknown>;
+}
+/** What the application asks the map to show. The application owns time (ADR-010); the map follows. */
+export type TimeSetting = {
+    mode: 'live';
+} | {
+    mode: 'replay';
+    at: string;
+    range?: TimeRange;
+};
+/** What the map is showing. */
+export type TimeState = {
+    mode: 'live';
+} | {
+    mode: 'replay';
+    at: string;
+    range: TimeRange;
+};
+/**
+ * A zone that watches objects. Client-side evaluation is for display and analysis; authoritative alerting and the
+ * right to create or edit geofences belong to the server runtime (doc 16, ADR-016).
+ */
+export interface Geofence {
+    id: string;
+    name?: string;
+    /** A polygon, a multipolygon or a circle. */
+    geometry: AreaGeometry;
+    enabled: boolean;
+    /** Which objects it watches. Empty means every point object on the map. */
+    watch?: {
+        layerIds?: string[];
+        objectIds?: string[];
+        filter?: Record<string, unknown>;
+        where?: PropertyCondition[];
+    };
+    /** Exit only when this far outside the edge (jitter, doc 15). Default 0. */
+    hysteresisMeters?: number;
+    /** Consecutive agreeing readings needed to change state (debounce). Default 1. */
+    debounceSamples?: number;
+    /** Emit one dwell event per visit after this long inside. */
+    dwellSeconds?: number;
+    /**
+     * An altitude band (phase 3E): the geofence is a volume — inside means inside the outline AND between these heights
+     * (metres, in the watched objects' own altitude reference). An object without altitude is never inside a band.
+     */
+    minAltitude?: number;
+    maxAltitude?: number;
+}
+export type GeofenceEventType = 'enter' | 'exit' | 'dwell';
+export interface GeofenceEvent {
+    geofenceId: string;
+    objectId: string;
+    type: GeofenceEventType;
+    /** Observation time of the reading that caused it (ISO 8601). */
+    timestamp: string;
+    position: Position;
+}