@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/map/source-to-maplibre.js

@@ -0,0 +1,454 @@
+/**
+ * Plan-bound canonical Source → MapLibre GeoJSON workflow.
+ *
+ * This module is peer-injected and safe to import in Node/SSR/worker code: it
+ * never imports `maplibre-gl`. The first production slice deliberately covers
+ * exact feature-query plans; tile and realtime strategies remain separate.
+ */
+import { HonuaSdkError, mergeHonuaErrorContext } from "../core/error-envelope.js";
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { canonicalStringify, toJsonValue } from "../query-planner/canonical.js";
+import { assertQueryPlanExecutionContextV1 } from "../query-planner/execution-context.js";
+import { queryFromCanonical, queryIrSourceIdentity } from "../query-planner/ir.js";
+import { hashQueryPlanV1 } from "../query-planner/planner.js";
+import { HonuaQueryPlanExecutionError, } from "../query-planner/types.js";
+import { canonicalFeaturesToGeoJson, defaultPaint, geometryKind, geometryKinds, layerType, mapLibreGeometryType, removeUndefined, safeId, } from "./geojson-projection.js";
+/** A stable, machine-readable adapter failure. */
+export class HonuaMapLibreSourceAdapterError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail, options = {}) {
+        super(MAPLIBRE_SOURCE_ADAPTER_CODES[code], message, {
+            ...options,
+            context: mergeHonuaErrorContext(detail, options.context),
+        });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaMapLibreSourceAdapterError";
+    }
+}
+const MAPLIBRE_SOURCE_ADAPTER_CODES = {
+    disposed: "map.source-adapter.disposed",
+    "source-conflict": "map.source-adapter.source-conflict",
+    "layer-conflict": "map.source-adapter.layer-conflict",
+    "unsupported-plan": "map.source-adapter.unsupported-plan",
+    "invalid-option": "map.source-adapter.invalid-option",
+    "map-mutation-failed": "map.source-adapter.map-mutation-failed",
+};
+/**
+ * Project an already-executed plan result into native MapLibre source/layers.
+ * This function is deterministic and does not mutate a map.
+ */
+export function projectSourceToMapLibre(source, plan, result, options = {}) {
+    assertProjectionPlanContext(source, plan);
+    assertFeaturePlan(plan, result);
+    assertQueryable(source);
+    validateStaticOptions(options);
+    const sourceId = options.sourceId ?? `honua-${safeId(source.descriptor.id)}`;
+    const layerId = options.layerId ?? `${sourceId}-features`;
+    const converted = canonicalFeaturesToGeoJson(result.features, source.descriptor.schema?.primaryKey);
+    const presentKinds = geometryKinds(converted.data.features);
+    const requestedKind = options.geometry === "auto" || options.geometry === undefined ? undefined : options.geometry;
+    // Auto mode installs a stable three-layer geometry matrix. Refresh can then
+    // move between geometry kinds through setData without structural layer churn.
+    const renderKinds = requestedKind
+        ? [requestedKind]
+        : options.cluster
+            ? ["point"]
+            : ["point", "line", "polygon"];
+    if (options.cluster &&
+        (requestedKind !== undefined ? requestedKind !== "point" : presentKinds.some((kind) => kind !== "point"))) {
+        throw new HonuaMapLibreSourceAdapterError("invalid-option", "MapLibre clustering is supported only for point GeoJSON sources.", { sourceId, geometryKinds: renderKinds });
+    }
+    const diagnostics = [
+        diagnostic(source, plan, "strategy-selected", "info", "project", "exact", "Selected exact bounded GeoJSON query strategy."),
+    ];
+    if (result.features.length === 0) {
+        diagnostics.push(diagnostic(source, plan, "empty-result", "info", "execute", "exact", "The accepted plan returned no features.", {
+            rowCount: 0,
+        }));
+    }
+    if (result.exceededTransferLimit) {
+        diagnostics.push(diagnostic(source, plan, "transfer-limit", "warning", "execute", "equivalent", "The accepted bounded query returned a page while additional source rows exist.", { renderedRowCount: result.features.length }));
+    }
+    if (result.degraded && result.degraded.length > 0) {
+        diagnostics.push(diagnostic(source, plan, "source-degraded", "warning", "execute", "equivalent", "The source reported degraded execution semantics.", { reasons: result.degraded.map((entry) => entry.reason) }));
+    }
+    if (converted.unsupported > 0) {
+        diagnostics.push(diagnostic(source, plan, "geometry-unsupported", "warning", "project", "unsupported", `${converted.unsupported} feature geometry value(s) could not be projected and remain attribute-only.`, { unsupportedGeometryCount: converted.unsupported }));
+    }
+    const mismatchedGeometryCount = requestedKind
+        ? converted.data.features.filter((feature) => {
+            const kind = geometryKind(feature.geometry);
+            return kind !== undefined && kind !== requestedKind;
+        }).length
+        : 0;
+    if (requestedKind && mismatchedGeometryCount > 0) {
+        diagnostics.push(diagnostic(source, plan, "geometry-mismatch", "warning", "project", "unsupported", `${mismatchedGeometryCount} feature(s) do not match the explicit ${requestedKind} geometry layer and will not render.`, {
+            requestedGeometry: requestedKind,
+            mismatchedGeometryCount,
+            renderedGeometryCount: result.features.length - mismatchedGeometryCount - converted.unsupported,
+        }));
+    }
+    if (presentKinds.length > 1 && !requestedKind) {
+        diagnostics.push(diagnostic(source, plan, "mixed-geometry", "warning", "project", "equivalent", "Mixed geometry output uses one filtered layer per geometry kind.", {
+            geometryKinds: presentKinds,
+        }));
+    }
+    const mapSource = {
+        type: "geojson",
+        data: converted.data,
+        promoteId: source.descriptor.schema?.primaryKey,
+        attribution: options.attribution ?? source.descriptor.attribution,
+        ...(options.cluster
+            ? { cluster: true, clusterRadius: positiveInteger(options.clusterRadius, 50, "clusterRadius") }
+            : {}),
+    };
+    removeUndefined(mapSource);
+    return Object.freeze({
+        strategy: "geojson-query",
+        sourceId,
+        layerId,
+        planId: plan.id,
+        planFingerprint: plan.fingerprint,
+        sourceVersion: plan.ir.source.sourceVersion,
+        schemaVersion: plan.ir.source.schemaVersion,
+        authorizationScope: plan.ir.source.authorizationScope,
+        source: Object.freeze(mapSource),
+        layers: Object.freeze(renderKinds.map((kind, index) => Object.freeze({
+            id: renderKinds.length === 1 ? layerId : `${layerId}-${kind}`,
+            type: layerType(kind),
+            source: sourceId,
+            filter: ["==", ["geometry-type"], mapLibreGeometryType(kind)],
+            paint: { ...defaultPaint(kind), ...(options.paint ?? {}) },
+            ...(options.layout ? { layout: { ...options.layout } } : {}),
+            metadata: {
+                "honua:strategy": "geojson-query",
+                "honua:planId": plan.id,
+                "honua:planFingerprint": plan.fingerprint,
+                "honua:sourceVersion": plan.ir.source.sourceVersion,
+                "honua:geometryOrder": index,
+            },
+        }))),
+        diagnostics: Object.freeze(diagnostics),
+        state: diagnostics.some((entry) => entry.severity === "warning")
+            ? "degraded"
+            : result.features.length === 0
+                ? "empty"
+                : "ready",
+    });
+}
+/**
+ * Execute an accepted plan, mount its projection, and return one lifecycle.
+ * Omitted execution bindings inherit the accepted plan; explicit overrides
+ * remain fail-closed when they describe another context.
+ */
+export async function mountSourceToMapLibre(map, source, plan, options = {}) {
+    assertProjectionPlanContext(source, plan);
+    assertFeaturePlan(plan);
+    assertQueryable(source);
+    validateStaticOptions(options);
+    const intendedSourceId = options.sourceId ?? `honua-${safeId(source.descriptor.id)}`;
+    if (map.getSource(intendedSourceId)) {
+        throw new HonuaMapLibreSourceAdapterError("source-conflict", `MapLibre source "${intendedSourceId}" already exists.`, {
+            sourceId: intendedSourceId,
+        });
+    }
+    for (const layerId of projectedLayerIds(intendedSourceId, options)) {
+        if (map.getLayer(layerId)) {
+            throw new HonuaMapLibreSourceAdapterError("layer-conflict", `MapLibre layer "${layerId}" already exists.`, {
+                layerId,
+            });
+        }
+    }
+    const lifecycleController = new AbortController();
+    const executeOptions = {
+        ...executionOptions(plan, options),
+        signal: combineSignals([lifecycleController.signal, options.signal]),
+    };
+    const result = await executeAcceptedFeaturePlan(plan, source, executeOptions);
+    throwIfAborted(executeOptions.signal);
+    let projection = projectSourceToMapLibre(source, plan, result, options);
+    throwIfAborted(executeOptions.signal);
+    assertMapIdsAvailable(map, projection);
+    const attemptedLayerIds = [];
+    try {
+        map.addSource(projection.sourceId, projection.source);
+        for (const layer of projection.layers) {
+            attemptedLayerIds.push(String(layer.id));
+            map.addLayer(layer, options.beforeId);
+        }
+    }
+    catch (cause) {
+        const rollbackFailures = rollbackMapMutation(map, projection.sourceId, attemptedLayerIds);
+        throw new HonuaMapLibreSourceAdapterError("map-mutation-failed", `Failed to mount source "${projection.sourceId}" transactionally.`, {
+            sourceId: projection.sourceId,
+            attemptedLayerIds,
+            rollbackFailureCount: rollbackFailures.length,
+            rollbackFailures: rollbackFailures.map(errorMessage),
+        }, { cause });
+    }
+    let state = projection.state;
+    let diagnostics = [...projection.diagnostics];
+    const layerIds = projection.layers.map((layer) => String(layer.id));
+    const isDisposed = () => state === "disposed";
+    let refreshTail = Promise.resolve();
+    const runRefresh = async (refreshOptions) => {
+        if (isDisposed())
+            throw new HonuaMapLibreSourceAdapterError("disposed", "Cannot refresh a disposed MapLibre source mount.");
+        const effectiveSignal = combineSignals([lifecycleController.signal, refreshOptions.signal]);
+        throwIfAborted(effectiveSignal);
+        const nextExecutionOptions = {
+            ...executeOptions,
+            ...refreshOptions,
+            signal: effectiveSignal,
+        };
+        const nextResult = await executeAcceptedFeaturePlan(plan, source, nextExecutionOptions);
+        throwIfAborted(effectiveSignal);
+        if (isDisposed())
+            throw new HonuaMapLibreSourceAdapterError("disposed", "MapLibre source mount was disposed during refresh.");
+        const next = projectSourceToMapLibre(source, plan, nextResult, options);
+        throwIfAborted(effectiveSignal);
+        const handle = map.getSource(projection.sourceId);
+        if (!handle || typeof handle.setData !== "function") {
+            throw new HonuaMapLibreSourceAdapterError("map-mutation-failed", `Mounted source "${projection.sourceId}" no longer exposes setData().`);
+        }
+        throwIfAborted(effectiveSignal);
+        const previousData = projection.source.data;
+        try {
+            handle.setData(next.source.data);
+        }
+        catch (cause) {
+            let rollbackFailure;
+            try {
+                handle.setData(previousData);
+            }
+            catch (error) {
+                rollbackFailure = error;
+            }
+            state = "degraded";
+            diagnostics = [
+                ...diagnostics,
+                diagnostic(source, plan, "incremental-update-failed", "warning", "update", "unsupported", rollbackFailure
+                    ? "MapLibre setData failed and the previous projection could not be restored."
+                    : "MapLibre setData failed; the previous projection was restored.", { rollbackSucceeded: rollbackFailure === undefined }),
+            ];
+            throw new HonuaMapLibreSourceAdapterError("map-mutation-failed", `Failed to refresh mounted source "${projection.sourceId}" through setData().`, {
+                sourceId: projection.sourceId,
+                planId: plan.id,
+                rollbackSucceeded: rollbackFailure === undefined,
+                ...(rollbackFailure ? { rollbackFailure: errorMessage(rollbackFailure) } : {}),
+            }, { cause });
+        }
+        diagnostics = [
+            ...next.diagnostics,
+            diagnostic(source, plan, "incremental-update", "info", "update", "exact", "Updated GeoJSON data in place with setData()."),
+        ];
+        projection = { ...next, diagnostics };
+        state = next.state;
+        return projection;
+    };
+    const enqueueRefresh = (refreshOptions) => {
+        const result = refreshTail.then(() => runRefresh(refreshOptions));
+        refreshTail = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    return {
+        strategy: "geojson-query",
+        sourceId: projection.sourceId,
+        layerIds,
+        planId: plan.id,
+        planFingerprint: plan.fingerprint,
+        get state() {
+            return state;
+        },
+        get diagnostics() {
+            return diagnostics;
+        },
+        refresh(refreshOptions = {}) {
+            return enqueueRefresh(refreshOptions);
+        },
+        dispose() {
+            if (state === "disposed")
+                return;
+            lifecycleController.abort(new DOMException("MapLibre source mount disposed", "AbortError"));
+            const failures = [];
+            for (const layerId of [...layerIds].reverse()) {
+                try {
+                    if (map.getLayer(layerId))
+                        map.removeLayer(layerId);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            try {
+                if (map.getSource(projection.sourceId))
+                    map.removeSource(projection.sourceId);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            state = "disposed";
+            if (failures.length > 0) {
+                throw new HonuaMapLibreSourceAdapterError("map-mutation-failed", `MapLibre source "${projection.sourceId}" disposal completed with ${failures.length} renderer failure(s).`, { sourceId: projection.sourceId, failureCount: failures.length }, { cause: failures[0] });
+            }
+        },
+    };
+}
+function assertQueryable(source) {
+    if (!source.capabilities.has("query")) {
+        throw new HonuaCapabilityNotSupportedError("query", source.descriptor.protocol, source.descriptor.id);
+    }
+}
+function assertProjectionPlanContext(source, plan) {
+    if (hashQueryPlanV1(plan) !== plan.fingerprint) {
+        throw new HonuaQueryPlanExecutionError("invalid-plan", "Plan content does not match its fingerprint; project only the accepted immutable plan.");
+    }
+    const identity = queryIrSourceIdentity(source.descriptor, {
+        schemaVersion: plan.ir.source.schemaVersion,
+        sourceVersion: plan.ir.source.sourceVersion,
+        authorizationScope: plan.ir.source.authorizationScope,
+    });
+    const runtimeCapabilities = [...source.capabilities].sort();
+    const descriptorCapabilities = [...source.descriptor.capabilities].sort();
+    const planCapabilities = [...plan.ir.source.capabilities].sort();
+    if (canonicalStringify(toJsonValue(identity)) !== canonicalStringify(toJsonValue(plan.ir.source)) ||
+        canonicalStringify(toJsonValue(runtimeCapabilities)) !== canonicalStringify(toJsonValue(descriptorCapabilities)) ||
+        canonicalStringify(toJsonValue(runtimeCapabilities)) !== canonicalStringify(toJsonValue(planCapabilities))) {
+        throw new HonuaQueryPlanExecutionError("plan-context-mismatch", "Source identity, descriptor capabilities, or runtime capabilities do not match the accepted plan projection context.");
+    }
+}
+function assertFeaturePlan(plan, result) {
+    const first = plan.steps[0];
+    const featureShape = plan.ir.query.aggregation === undefined &&
+        plan.ir.query.returnGeometry !== false &&
+        plan.steps.length === 1 &&
+        first?.engine === "remote" &&
+        (first.operation === "query" || first.operation === "queryAll");
+    if (!featureShape || result?.aggregateRows !== undefined) {
+        throw new HonuaMapLibreSourceAdapterError("unsupported-plan", "MapLibre GeoJSON mounting requires a feature-query plan; aggregate or client-materialization plans are not renderable by this strategy.", { planId: plan.id, operations: plan.steps.map((step) => step.operation) });
+    }
+}
+async function executeAcceptedFeaturePlan(plan, source, options) {
+    try {
+        assertQueryPlanExecutionContextV1(plan, source, options);
+        const step = plan.steps[0];
+        if (!step || step.engine !== "remote" || (step.operation !== "query" && step.operation !== "queryAll")) {
+            throw new HonuaMapLibreSourceAdapterError("unsupported-plan", "MapLibre GeoJSON mounting requires one remote feature-query step.", { planId: plan.id });
+        }
+        const query = queryFromCanonical(step.query, options.signal);
+        return step.operation === "queryAll" ? await source.queryAll(query) : await source.query(query);
+    }
+    catch (error) {
+        // Preserve this bridge's established AbortSignal reason while the shared
+        // canonical execution-context boundary supplies plan validation.
+        if (options.signal?.aborted)
+            options.signal.throwIfAborted();
+        throw error;
+    }
+}
+function assertMapIdsAvailable(map, projection) {
+    if (map.getSource(projection.sourceId)) {
+        throw new HonuaMapLibreSourceAdapterError("source-conflict", `MapLibre source "${projection.sourceId}" already exists.`, {
+            sourceId: projection.sourceId,
+        });
+    }
+    for (const layer of projection.layers) {
+        if (map.getLayer(String(layer.id))) {
+            throw new HonuaMapLibreSourceAdapterError("layer-conflict", `MapLibre layer "${String(layer.id)}" already exists.`, {
+                layerId: layer.id,
+            });
+        }
+    }
+}
+function rollbackMapMutation(map, sourceId, layerIds) {
+    const failures = [];
+    for (const layerId of [...layerIds].reverse()) {
+        try {
+            if (map.getLayer(layerId))
+                map.removeLayer(layerId);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    try {
+        if (map.getSource(sourceId))
+            map.removeSource(sourceId);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    return failures;
+}
+function diagnostic(source, plan, code, severity, stage, fidelity, message, detail) {
+    return {
+        code,
+        severity,
+        stage,
+        fidelity,
+        sourceId: source.descriptor.id,
+        planId: plan.id,
+        message,
+        ...(detail ? { detail } : {}),
+    };
+}
+function executionOptions(plan, options) {
+    const schemaVersion = options.schemaVersion ?? plan.ir.source.schemaVersion;
+    const sourceVersion = options.sourceVersion ?? plan.ir.source.sourceVersion;
+    const authorizationScope = options.authorizationScope ?? plan.ir.source.authorizationScope;
+    const discovery = options.discovery ?? plan.provenance.discovery;
+    const executionMode = options.executionMode ?? plan.validity.executionMode;
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(schemaVersion !== undefined ? { schemaVersion } : {}),
+        ...(sourceVersion !== undefined ? { sourceVersion } : {}),
+        ...(authorizationScope !== undefined ? { authorizationScope } : {}),
+        ...(discovery !== undefined ? { discovery } : {}),
+        ...(executionMode !== undefined ? { executionMode } : {}),
+    };
+}
+function combineSignals(signals) {
+    const available = signals.filter((signal) => signal !== undefined);
+    return available.length === 1 ? available[0] : AbortSignal.any(available);
+}
+function throwIfAborted(signal) {
+    signal.throwIfAborted();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function positiveInteger(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new HonuaMapLibreSourceAdapterError("invalid-option", `${name} must be a positive integer.`, {
+            [name]: value,
+        });
+    }
+    return value;
+}
+function validateStaticOptions(options) {
+    if (options.clusterRadius !== undefined && options.cluster !== true) {
+        throw new HonuaMapLibreSourceAdapterError("invalid-option", "clusterRadius requires cluster: true.", {
+            clusterRadius: options.clusterRadius,
+        });
+    }
+    if (options.cluster) {
+        positiveInteger(options.clusterRadius, 50, "clusterRadius");
+        if (options.geometry !== undefined && options.geometry !== "auto" && options.geometry !== "point") {
+            throw new HonuaMapLibreSourceAdapterError("invalid-option", "MapLibre clustering is supported only for point GeoJSON sources.", { geometry: options.geometry });
+        }
+    }
+}
+function projectedLayerIds(sourceId, options) {
+    const base = options.layerId ?? `${sourceId}-features`;
+    const kind = options.geometry === "auto" ? undefined : options.geometry;
+    const kinds = kind
+        ? [kind]
+        : options.cluster
+            ? ["point"]
+            : ["point", "line", "polygon"];
+    return kinds.length === 1 ? [base] : kinds.map((entry) => `${base}-${entry}`);
+}

package/map/temporal-playback.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Temporal playback (issue #497 REQ-004): a renderer-neutral play/pause/
+ * scrub controller over a time extent, plus thin bindings that drive time
+ * filters through the data-to-map bridge (`MountedSource.setFilter`) or
+ * directly through MapLibre layer filters.
+ *
+ * Memory is bounded by construction: the controller keeps only the current
+ * window (two numbers). Filter application is coalesced — at most one
+ * request in flight and at most one pending window; intermediate windows
+ * are dropped, never queued. No window data is pre-fetched or cached by the
+ * controller itself (the issue's snapshot-plus-delta realtime vocabulary
+ * from #393 applies only when playback is layered over a realtime feed;
+ * playback over static data has no realtime dependency).
+ *
+ * @module
+ */
+import { HonuaSdkError } from "../core/error-envelope.js";
+/** A half-open time window `[start, end)` in epoch milliseconds. @experimental */
+export interface TemporalWindow {
+    readonly start: number;
+    readonly end: number;
+}
+/** Accepted time inputs: epoch ms, `Date`, or an ISO-8601 string. @experimental */
+export type TemporalInstant = number | Date | string;
+/** Payload for `"tick"` listeners. @experimental */
+export interface TemporalPlaybackTick {
+    /** The window that was just applied. */
+    readonly window: TemporalWindow;
+    /** Window-start progress through the extent, 0..1. */
+    readonly progress: number;
+    readonly playing: boolean;
+}
+/** Event names emitted by the controller. @experimental */
+export type TemporalPlaybackEventType = "tick" | "play" | "pause" | "end" | "error";
+/** Listener registration handle. @experimental */
+export interface TemporalPlaybackSubscription {
+    remove(): void;
+}
+/**
+ * Bridge-shaped filter sink: the subset of `MountedSource` the playback
+ * binding needs. Any object with a Query-shaped `setFilter` works.
+ *
+ * @experimental
+ */
+export interface TemporalFilterHandle {
+    setFilter(query: {
+        where?: string;
+    } | undefined): Promise<unknown>;
+}
+/** MapLibre-shaped filter sink for client-side (already materialized) data. @experimental */
+export interface TemporalFilterMap {
+    setFilter(layerId: string, filter: unknown): void;
+    getFilter?(layerId: string): unknown;
+}
+/** Options for {@link createTemporalPlayback}. @experimental */
+export interface TemporalPlaybackOptions {
+    /** Full playable time extent as `[start, end]`. */
+    readonly extent: readonly [TemporalInstant, TemporalInstant];
+    /** Window length in milliseconds. */
+    readonly windowMs: number;
+    /** Wall-clock delay between frames. @default 500 */
+    readonly frameIntervalMs?: number;
+    /** How far the window advances per frame. @default `windowMs` (non-overlapping windows) */
+    readonly stepMs?: number;
+    /** Restart from the extent start after the last window. @default false */
+    readonly loop?: boolean;
+    /**
+     * Bridge binding: a `MountedSource` (or anything with a Query-shaped
+     * `setFilter`). Each window becomes a `where` clause on `timeField`.
+     */
+    readonly handle?: TemporalFilterHandle;
+    /**
+     * MapLibre binding: client-side `setFilter` over already-materialized
+     * layers. Each window becomes a numeric range filter on `timeField`
+     * composed (`all`) with the layer's filter at bind time, so bridge
+     * geometry filters survive. Requires numeric (epoch ms) properties.
+     */
+    readonly layer?: {
+        readonly map: TemporalFilterMap;
+        readonly layerIds: readonly string[];
+    };
+    /** Custom sink; use instead of (or in addition to) `handle`/`layer`. */
+    readonly apply?: (window: TemporalWindow) => void | Promise<void>;
+    /** Feature property holding the feature's time. Required with `handle`/`layer`. */
+    readonly timeField?: string;
+    /** Extra query properties merged under the generated `where` (handle binding). */
+    readonly baseQuery?: Readonly<Record<string, unknown>> & {
+        readonly where?: string;
+    };
+    /**
+     * Override the generated `where` clause (handle binding). The default is
+     * `<timeField> >= <startMs> AND <timeField> < <endMs>`.
+     */
+    readonly formatWhere?: (window: TemporalWindow, timeField: string) => string;
+}
+/** Playback controller returned by {@link createTemporalPlayback}. @experimental */
+export interface TemporalPlayback {
+    readonly playing: boolean;
+    /** The current window (epoch ms, half-open). */
+    readonly window: TemporalWindow;
+    /** The normalized extent (epoch ms). */
+    readonly extent: TemporalWindow;
+    /** Start advancing one window per frame. Applies the current window immediately. */
+    play(): void;
+    pause(): void;
+    /** Jump the window start to a time (clamped to the extent) and apply it. */
+    scrub(time: TemporalInstant): void;
+    /** Change the window length, keeping the current start, and apply it. */
+    setWindow(windowMs: number): void;
+    on(type: "tick", listener: (event: TemporalPlaybackTick) => void): TemporalPlaybackSubscription;
+    on(type: "play" | "pause" | "end", listener: () => void): TemporalPlaybackSubscription;
+    on(type: "error", listener: (error: unknown) => void): TemporalPlaybackSubscription;
+    /** Stop the timer and drop all listeners. Idempotent. */
+    dispose(): void;
+}
+/** Raised for invalid playback options. @experimental */
+export declare class HonuaTemporalPlaybackError extends HonuaSdkError {
+    constructor(message: string);
+}
+/**
+ * Create a temporal playback controller over a time extent.
+ *
+ * @example
+ * ```ts
+ * const playback = createTemporalPlayback({
+ *   handle: mounted, // from mountSource()
+ *   timeField: "event_time",
+ *   extent: ["2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z"],
+ *   windowMs: 24 * 60 * 60 * 1000,
+ *   frameIntervalMs: 400,
+ * });
+ * playback.on("tick", ({ window, progress }) => updateSlider(progress));
+ * playback.play();
+ * ```
+ *
+ * @experimental
+ */
+export declare function createTemporalPlayback(options: TemporalPlaybackOptions): TemporalPlayback;
+//# sourceMappingURL=temporal-playback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-playback.d.ts","sourceRoot":"","sources":["../../../src/map/temporal-playback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI1D,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAErD,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,2DAA2D;AAC3D,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAEpF,kDAAkD;AAClD,MAAM,WAAW,4BAA4B;IAC3C,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpE;AAED,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAClD,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC;AAED,gEAAgE;AAChE,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAC7D,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAC3F,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,mFAAmF;IACnF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrF;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9E;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,oFAAoF;IACpF,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,4EAA4E;IAC5E,KAAK,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,yEAAyE;IACzE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,4BAA4B,CAAC;IAChG,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,4BAA4B,CAAC;IACvF,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,4BAA4B,CAAC;IACpF,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,yDAAyD;AACzD,qBAAa,0BAA2B,SAAQ,aAAa;gBACxC,OAAO,EAAE,MAAM;CAInC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAgJzF"}