@honua/app-platform 0.1.2-beta.0 → 0.1.7-beta.0

package/scene-workspace/cesium-scene-owner.d.ts

@@ -0,0 +1,160 @@
+/**
+ * One owner for both halves of a Cesium scene.
+ *
+ * A Cesium application that draws a published scene *and* an accepted-plan
+ * feature query had two lifecycle owners and nothing above them:
+ * {@link mountScenePrimitivesToCesium} owns terrain, imagery, tilesets, and
+ * models on `viewer.scene`, and {@link mountSourceToCesium} owns entities on
+ * `viewer.entities`. Composing them worked — that is proven against a real
+ * `Viewer` — but the application had to hold two handles, dispose them in the
+ * right order, and get that right on every error path. This module is the
+ * missing owner (epic #395 REQ-003, issue #1050).
+ *
+ * {@link mountCesiumScene} is deliberately a **delegating** owner rather than a
+ * new adapter:
+ *
+ * - It does not reimplement either mount. The primitive mount keeps its own
+ *   diff, layer ceiling, transactional apply, and rebuild boundaries; each
+ *   entity mount keeps its own refresh diff, entity ceiling, and rollback. The
+ *   owner adds ordering, admission, and a single `dispose()`.
+ * - It does not change the beta mount's shape. `mountScenePrimitivesToCesium`
+ *   and its handle are untouched and remain the supported way to own primitives
+ *   alone; `mountCesiumScene` is additive, and a host that already holds a
+ *   primitive mount keeps working exactly as before.
+ * - One target. A live `Viewer` structurally satisfies
+ *   {@link CesiumSceneOwnerTarget} — `camera`, `scene`, `clock`, `entities` —
+ *   so the owner is handed the viewer, not a pair of collections the caller has
+ *   to keep consistent.
+ *
+ * Disposal releases entity mounts first, in reverse acquisition order, and the
+ * primitive mount last. That is the order the browser lane measures: entity
+ * visualizers attach their own primitives to `scene.primitives`, and releasing
+ * an elevation-source handle resets the globe's terrain provider, so tearing the
+ * scene down underneath live entities is the arrangement worth avoiding. A
+ * refusing mount leaves the owner in `disposing`, still owning exactly what did
+ * not release, so `dispose()` can be called again.
+ *
+ * @experimental Held back from the beta `@honua/app-platform/scene-workspace`
+ *   tier with the accepted-plan entity slice it composes: the entity half has no
+ *   symbology surface yet, and adding one changes shapes this owner forwards.
+ *   See `docs/cesium-entity-adapter.md`.
+ * @module
+ */
+import type { Source } from "../contract/types.js";
+import type { QueryExecutionPlanV1 } from "../query-planner/types.js";
+import type { CesiumSceneRuntimeTarget } from "./cesium-adapter.js";
+import { type ApplyMountedScenePrimitivesOptions, type MountScenePrimitivesToCesiumOptions, type MountedCesiumScenePrimitives, type MountedScenePrimitiveApplyResult } from "./cesium-mount.js";
+import type { SceneRuntimePrimitive } from "./primitives.js";
+import { type CesiumEntityCollectionTarget, type MountSourceToCesiumOptions, type MountedCesiumEntitySource } from "./source-to-cesium.js";
+/**
+ * Default ceiling on the number of live entity mounts one owner may hold.
+ *
+ * Each mount materializes up to `DEFAULT_CESIUM_ENTITY_LIMIT` entities, so an
+ * unbounded set of mounts is an unbounded scene. Eight is generous for an
+ * operational view — a handful of feature layers over a published scene — and
+ * small enough that a runaway generated application fails closed. Raise it
+ * deliberately with {@link MountCesiumSceneOptions.maxSources}.
+ */
+export declare const DEFAULT_CESIUM_SCENE_SOURCE_LIMIT = 8;
+/** Failure codes raised by the scene owner's own contract. */
+export type CesiumSceneOwnerErrorCode = "disposed" | "entities-unavailable" | "invalid-option" | "source-conflict" | "source-limit-exceeded";
+/**
+ * A lifecycle refusal from {@link mountCesiumScene} or the handle it returns.
+ * Failures raised by the mounts it delegates to keep their own error types —
+ * `HonuaCesiumSceneMountError` and `HonuaCesiumEntityAdapterError` — so a caller
+ * can still tell a layer-ceiling refusal from an entity-ceiling refusal.
+ */
+export declare class HonuaCesiumSceneOwnerError extends Error {
+    readonly code: CesiumSceneOwnerErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: CesiumSceneOwnerErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: ErrorOptions);
+}
+/**
+ * The live Cesium surface both halves of the scene attach to. A `Viewer`
+ * satisfies it structurally; `entities` is optional so a scene that never mounts
+ * a source can hand over the same target the primitive adapter already accepts.
+ */
+export interface CesiumSceneOwnerTarget extends CesiumSceneRuntimeTarget {
+    /** Live `viewer.entities`. Required before {@link MountedCesiumScene.mountSource} can run. */
+    readonly entities?: CesiumEntityCollectionTarget;
+}
+/**
+ * Lifecycle state of a scene owner.
+ *
+ * `disposing` is durable when a mount refused to release: the owner permanently
+ * refuses new work while remaining retryable, exactly like the primitive mount.
+ */
+export type CesiumSceneOwnerState = "ready" | "disposing" | "disposed";
+/** Options for {@link mountCesiumScene}. */
+export interface MountCesiumSceneOptions extends MountScenePrimitivesToCesiumOptions {
+    /**
+     * Ceiling on the live entity mounts this owner may hold. Defaults to
+     * {@link DEFAULT_CESIUM_SCENE_SOURCE_LIMIT}. Must be a positive integer.
+     */
+    readonly maxSources?: number;
+}
+/**
+ * One owner of a whole Cesium scene: the primitive plan and every accepted-plan
+ * source mounted over it.
+ *
+ * Callers hold the owner, not the mounts. The mounts are still reachable —
+ * {@link primitives} and {@link sources} expose them so their diagnostics,
+ * revisions, and rebuild boundaries stay readable — but ownership is the owner's,
+ * and {@link dispose} is the only teardown a host has to sequence.
+ */
+export interface MountedCesiumScene {
+    readonly renderer: "cesium";
+    /** Lifecycle state. See {@link CesiumSceneOwnerState}. */
+    readonly state: CesiumSceneOwnerState;
+    /** The primitive mount this owner created. Its own lifecycle is owned here. */
+    readonly primitives: MountedCesiumScenePrimitives;
+    /** Live entity mounts keyed by their `sourceId`, in acquisition order. */
+    readonly sources: ReadonlyMap<string, MountedCesiumEntitySource>;
+    /** The entity-mount ceiling this owner was created with. */
+    readonly sourceLimit: number;
+    /**
+     * Apply a revised primitive plan. Delegates to the primitive mount's diff, so
+     * unchanged primitives are reused and the owner's entity mounts are untouched.
+     */
+    applyPrimitives(primitives: readonly SceneRuntimePrimitive[], options?: ApplyMountedScenePrimitivesOptions): Promise<MountedScenePrimitiveApplyResult>;
+    /**
+     * Mount an accepted plan against a source and take ownership of the result.
+     *
+     * The mount runs under the owner's lifecycle: disposing the owner mid-mount
+     * aborts it and leaves nothing attached. A source whose `sourceId` is already
+     * mounted is refused with `source-conflict` and the redundant mount is
+     * released, so the owner can never hold two mounts fighting over one set of
+     * entity ids.
+     */
+    mountSource<T>(source: Source<T>, plan: QueryExecutionPlanV1, options?: MountSourceToCesiumOptions): Promise<MountedCesiumEntitySource>;
+    /**
+     * Release one entity mount by `sourceId`, leaving the rest of the scene alone.
+     * Returns `false` when the owner does not hold that source. A mount that
+     * refuses to release stays owned so a later {@link dispose} retries it.
+     */
+    releaseSource(sourceId: string): boolean;
+    /**
+     * Release every mount this owner holds — entity mounts first, in reverse
+     * acquisition order, then the primitive mount. Idempotent.
+     *
+     * A mount that refuses to release does not stop the teardown: everything that
+     * can be released is, the failures are aggregated and thrown, the owner stays
+     * in `disposing` still owning exactly what refused, and a later `dispose()`
+     * retries only that. One stuck entity therefore never pins the scene's GPU
+     * resources indefinitely.
+     */
+    dispose(): void;
+}
+/**
+ * Mount a whole Cesium scene — primitives now, sources later — behind one owner.
+ *
+ * The initial primitive plan is applied before the promise resolves, so a
+ * resolved owner is a mounted scene. A rejection means nothing was left
+ * attached: the primitive mount's transactional rollback has already run and no
+ * source has been mounted yet. Pass an empty plan to own entity mounts alone.
+ *
+ * @param target Live Cesium `Viewer`/`Scene` surface, optionally carrying `entities`.
+ * @param primitives The accepted scene plan.
+ */
+export declare function mountCesiumScene(target: CesiumSceneOwnerTarget, primitives: readonly SceneRuntimePrimitive[], options?: MountCesiumSceneOptions): Promise<MountedCesiumScene>;
+//# sourceMappingURL=cesium-scene-owner.d.ts.map

package/scene-workspace/cesium-scene-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cesium-scene-owner.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/cesium-scene-owner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EACL,KAAK,kCAAkC,EACvC,KAAK,mCAAmC,EACxC,KAAK,4BAA4B,EACjC,KAAK,gCAAgC,EAEtC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAE/B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,8DAA8D;AAC9D,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,sBAAsB,GACtB,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,CAAC;AAE5B;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,IAAI,EAAE,yBAAyB;aAE/B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAF1C,IAAI,EAAE,yBAAyB,EAC/C,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA,EAC1D,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,wBAAwB;IACtE,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;CAClD;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvE,4CAA4C;AAC5C,MAAM,WAAW,uBAAwB,SAAQ,mCAAmC;IAClF;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,4BAA4B,CAAC;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACjE,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,eAAe,CACb,UAAU,EAAE,SAAS,qBAAqB,EAAE,EAC5C,OAAO,CAAC,EAAE,kCAAkC,GAC3C,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC7C;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,EACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC;;;;;;;;;OASG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,SAAS,qBAAqB,EAAE,EAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAuH7B"}

package/scene-workspace/cesium-scene-owner.js

@@ -0,0 +1,205 @@
+/**
+ * One owner for both halves of a Cesium scene.
+ *
+ * A Cesium application that draws a published scene *and* an accepted-plan
+ * feature query had two lifecycle owners and nothing above them:
+ * {@link mountScenePrimitivesToCesium} owns terrain, imagery, tilesets, and
+ * models on `viewer.scene`, and {@link mountSourceToCesium} owns entities on
+ * `viewer.entities`. Composing them worked — that is proven against a real
+ * `Viewer` — but the application had to hold two handles, dispose them in the
+ * right order, and get that right on every error path. This module is the
+ * missing owner (epic #395 REQ-003, issue #1050).
+ *
+ * {@link mountCesiumScene} is deliberately a **delegating** owner rather than a
+ * new adapter:
+ *
+ * - It does not reimplement either mount. The primitive mount keeps its own
+ *   diff, layer ceiling, transactional apply, and rebuild boundaries; each
+ *   entity mount keeps its own refresh diff, entity ceiling, and rollback. The
+ *   owner adds ordering, admission, and a single `dispose()`.
+ * - It does not change the beta mount's shape. `mountScenePrimitivesToCesium`
+ *   and its handle are untouched and remain the supported way to own primitives
+ *   alone; `mountCesiumScene` is additive, and a host that already holds a
+ *   primitive mount keeps working exactly as before.
+ * - One target. A live `Viewer` structurally satisfies
+ *   {@link CesiumSceneOwnerTarget} — `camera`, `scene`, `clock`, `entities` —
+ *   so the owner is handed the viewer, not a pair of collections the caller has
+ *   to keep consistent.
+ *
+ * Disposal releases entity mounts first, in reverse acquisition order, and the
+ * primitive mount last. That is the order the browser lane measures: entity
+ * visualizers attach their own primitives to `scene.primitives`, and releasing
+ * an elevation-source handle resets the globe's terrain provider, so tearing the
+ * scene down underneath live entities is the arrangement worth avoiding. A
+ * refusing mount leaves the owner in `disposing`, still owning exactly what did
+ * not release, so `dispose()` can be called again.
+ *
+ * @experimental Held back from the beta `@honua/app-platform/scene-workspace`
+ *   tier with the accepted-plan entity slice it composes: the entity half has no
+ *   symbology surface yet, and adding one changes shapes this owner forwards.
+ *   See `docs/cesium-entity-adapter.md`.
+ * @module
+ */
+import { mountScenePrimitivesToCesium, } from "./cesium-mount.js";
+import { mountSourceToCesium, } from "./source-to-cesium.js";
+/**
+ * Default ceiling on the number of live entity mounts one owner may hold.
+ *
+ * Each mount materializes up to `DEFAULT_CESIUM_ENTITY_LIMIT` entities, so an
+ * unbounded set of mounts is an unbounded scene. Eight is generous for an
+ * operational view — a handful of feature layers over a published scene — and
+ * small enough that a runaway generated application fails closed. Raise it
+ * deliberately with {@link MountCesiumSceneOptions.maxSources}.
+ */
+export const DEFAULT_CESIUM_SCENE_SOURCE_LIMIT = 8;
+/**
+ * A lifecycle refusal from {@link mountCesiumScene} or the handle it returns.
+ * Failures raised by the mounts it delegates to keep their own error types —
+ * `HonuaCesiumSceneMountError` and `HonuaCesiumEntityAdapterError` — so a caller
+ * can still tell a layer-ceiling refusal from an entity-ceiling refusal.
+ */
+export class HonuaCesiumSceneOwnerError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail, options) {
+        super(message, options);
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaCesiumSceneOwnerError";
+    }
+}
+/**
+ * Mount a whole Cesium scene — primitives now, sources later — behind one owner.
+ *
+ * The initial primitive plan is applied before the promise resolves, so a
+ * resolved owner is a mounted scene. A rejection means nothing was left
+ * attached: the primitive mount's transactional rollback has already run and no
+ * source has been mounted yet. Pass an empty plan to own entity mounts alone.
+ *
+ * @param target Live Cesium `Viewer`/`Scene` surface, optionally carrying `entities`.
+ * @param primitives The accepted scene plan.
+ */
+export async function mountCesiumScene(target, primitives, options = {}) {
+    const sourceLimit = resolveSourceLimit(options.maxSources);
+    const lifecycle = new AbortController();
+    const sources = new Map();
+    let state = "ready";
+    let disposeActive = false;
+    const primitiveMount = await mountScenePrimitivesToCesium(target, primitives, {
+        ...(options.signal ? { signal: combineSignals([lifecycle.signal, options.signal]) } : { signal: lifecycle.signal }),
+        ...(options.maxLayers === undefined ? {} : { maxLayers: options.maxLayers }),
+        ...(options.state ? { state: options.state } : {}),
+    });
+    const assertReady = () => {
+        if (state !== "ready") {
+            throw new HonuaCesiumSceneOwnerError("disposed", "Cannot use a disposed Cesium scene owner.", { state });
+        }
+    };
+    return {
+        renderer: "cesium",
+        get state() {
+            return state;
+        },
+        get primitives() {
+            return primitiveMount;
+        },
+        get sources() {
+            return new Map(sources);
+        },
+        sourceLimit,
+        applyPrimitives(plan, applyOptions = {}) {
+            try {
+                assertReady();
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            return primitiveMount.apply(plan, {
+                ...applyOptions,
+                signal: combineSignals([lifecycle.signal, applyOptions.signal]),
+            });
+        },
+        async mountSource(source, plan, sourceOptions = {}) {
+            assertReady();
+            const entities = target.entities;
+            if (!entities) {
+                throw new HonuaCesiumSceneOwnerError("entities-unavailable", "The Cesium scene target carries no entity collection; pass `viewer.entities` to mount a source.");
+            }
+            if (sources.size >= sourceLimit) {
+                throw new HonuaCesiumSceneOwnerError("source-limit-exceeded", `The Cesium scene owner already holds ${sources.size} source mounts, its ceiling.`, { sourceCount: sources.size, sourceLimit });
+            }
+            const signal = combineSignals([lifecycle.signal, sourceOptions.signal]);
+            signal.throwIfAborted();
+            const mounted = await mountSourceToCesium(entities, source, plan, { ...sourceOptions, signal });
+            // Disposal may have won the race with a mount that had no checkpoint left
+            // to hit. Release what it built rather than committing it into an owner the
+            // host has already torn down.
+            if (state !== "ready") {
+                mounted.dispose();
+                throw lifecycle.signal.reason;
+            }
+            if (sources.has(mounted.sourceId)) {
+                mounted.dispose();
+                throw new HonuaCesiumSceneOwnerError("source-conflict", `The Cesium scene owner already holds a mount for source "${mounted.sourceId}".`, { sourceId: mounted.sourceId });
+            }
+            sources.set(mounted.sourceId, mounted);
+            return mounted;
+        },
+        releaseSource(sourceId) {
+            const mounted = sources.get(sourceId);
+            if (!mounted)
+                return false;
+            // Delete only once the mount says it released: a refusing mount stays owned
+            // so `dispose()` retries exactly what is still attached.
+            mounted.dispose();
+            sources.delete(sourceId);
+            return true;
+        },
+        dispose() {
+            if (state === "disposed" || disposeActive)
+                return;
+            disposeActive = true;
+            if (!lifecycle.signal.aborted) {
+                lifecycle.abort(new DOMException("Cesium scene owner disposed", "AbortError"));
+            }
+            state = "disposing";
+            try {
+                const failures = [];
+                for (const [sourceId, mounted] of [...sources.entries()].reverse()) {
+                    try {
+                        mounted.dispose();
+                        sources.delete(sourceId);
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                }
+                try {
+                    primitiveMount.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                if (failures.length > 0) {
+                    throw new AggregateError(failures, "Cesium scene owner disposal is incomplete and may be retried.");
+                }
+                state = "disposed";
+            }
+            finally {
+                disposeActive = false;
+            }
+        },
+    };
+}
+function resolveSourceLimit(maxSources) {
+    if (maxSources === undefined)
+        return DEFAULT_CESIUM_SCENE_SOURCE_LIMIT;
+    if (!Number.isSafeInteger(maxSources) || maxSources <= 0) {
+        throw new HonuaCesiumSceneOwnerError("invalid-option", "maxSources must be a positive integer.", { maxSources });
+    }
+    return maxSources;
+}
+function combineSignals(signals) {
+    const available = signals.filter((signal) => signal !== undefined);
+    return available.length === 1 ? available[0] : AbortSignal.any(available);
+}

package/scene-workspace/cesium-state-sync.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The shipped 3D {@link SceneStateSyncPort}: a live Cesium `Viewer` bound to the
+ * shared scene state.
+ *
+ * The camera half reuses the adapter's existing conversion
+ * (`cameraStateToCesiumView` / `cesiumCameraToSceneState` /
+ * `applyCameraStateToCesiumCamera`) rather than re-deriving it, because the
+ * renderer-neutral camera *is* a globe pose — there is nothing to project. The
+ * slices that a globe expresses differently from a 2D map are declared
+ * differently by this port's own `mappings`, so a fidelity claim is always
+ * backed by the code that makes it.
+ *
+ * CesiumJS stays an optional peer: the viewer is duck-typed, and the only
+ * reference to the package is a lazy `import("cesium")` performed on the first
+ * apply that actually needs a Cesium constructor.
+ *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface.
+ * @module
+ */
+import type { FeatureSelectionTarget } from "../exploration/index.js";
+import { type CesiumCameraLike } from "./cesium-adapter.js";
+import { type CesiumClockTarget } from "./cesium-time.js";
+import { type SceneStateSyncPortDegradation, type SceneStateSyncRendererPort } from "./state-sync-port-kit.js";
+import { type SceneStateSyncIdentity } from "./state-sync.js";
+/** A Cesium `Event`: `addEventListener` returns its own remover. */
+export interface CesiumStateSyncEvent {
+    addEventListener(listener: (...args: never[]) => void): unknown;
+    removeEventListener?(listener: (...args: never[]) => void): unknown;
+}
+/** The bits of a Cesium `Entity` this port reads and writes. */
+export interface CesiumStateSyncEntity {
+    readonly id: string;
+    show?: boolean;
+    readonly properties?: unknown;
+}
+/** The bits of a Cesium `EntityCollection` this port reads. */
+export interface CesiumStateSyncEntityCollection {
+    readonly values: readonly CesiumStateSyncEntity[];
+    getById?(id: string): CesiumStateSyncEntity | undefined;
+}
+/**
+ * The subset of a live Cesium `Viewer` this port drives.
+ *
+ * The clock half is {@link CesiumClockTarget}, so the shared `time` slice writes
+ * a globe through exactly the binding the scene adapter uses — including its
+ * `clockOwnership` declaration, which this port honours by standing down rather
+ * than fighting a host-owned transport.
+ */
+export interface CesiumStateSyncTarget extends CesiumClockTarget {
+    readonly camera: CesiumCameraLike & {
+        readonly changed?: CesiumStateSyncEvent;
+        readonly moveEnd?: CesiumStateSyncEvent;
+    };
+    readonly entities?: CesiumStateSyncEntityCollection;
+    selectedEntity?: unknown;
+    readonly selectedEntityChanged?: CesiumStateSyncEvent;
+    readonly scene?: {
+        requestRender?(): void;
+    };
+}
+/**
+ * The Cesium symbols this port needs, modelled as the minimal slice of
+ * `typeof import("cesium")` so a mocked module satisfies it.
+ */
+export interface CesiumStateSyncModule {
+    readonly Cartesian3: {
+        fromDegrees(longitude: number, latitude: number, height?: number): unknown;
+    };
+    readonly JulianDate: {
+        fromIso8601(iso: string): unknown;
+        toIso8601(date: unknown, precision?: number): string;
+    };
+}
+export interface CreateCesiumStateSyncPortOptions {
+    readonly id?: string;
+    /** Shared-plan identity stamped onto everything this port publishes. */
+    readonly identity: SceneStateSyncIdentity;
+    readonly now?: () => string;
+    /** Inject the Cesium module. Defaults to a lazy `import("cesium")`. */
+    readonly cesium?: CesiumStateSyncModule | (() => Promise<CesiumStateSyncModule>);
+    /** Map a shared selection target onto an entity id. Defaults to the target's id. */
+    readonly entityIdForTarget?: (target: FeatureSelectionTarget) => string | undefined;
+    /** The inverse; defaults to `{ sourceId: identity.sourceId, id: entityId }`. */
+    readonly targetForEntityId?: (entityId: string) => FeatureSelectionTarget | undefined;
+    /** Read a filterable property off an entity. Defaults to its `properties` bag. */
+    readonly entityProperty?: (entity: CesiumStateSyncEntity, field: string) => unknown;
+    /** Source id the entity collection stands for, for `appliesTo` scoping. Defaults to `identity.sourceId`. */
+    readonly sourceId?: string;
+    readonly onDegraded?: (degradation: SceneStateSyncPortDegradation) => void;
+}
+/**
+ * Bind a live Cesium viewer to the shared scene state.
+ *
+ * Camera and selection changes are published automatically where the viewer
+ * raises an event for them (`camera.changed`, `camera.moveEnd`,
+ * `selectedEntityChanged`); everything else is published by the host. Because a
+ * globe's camera event is frame-driven, {@link SceneStateSyncRendererPort.readFromRenderer}
+ * is the deterministic pull complement.
+ */
+export declare function createCesiumStateSyncPort(viewer: CesiumStateSyncTarget, options: CreateCesiumStateSyncPortOptions): SceneStateSyncRendererPort;
+//# sourceMappingURL=cesium-state-sync.d.ts.map

package/scene-workspace/cesium-state-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cesium-state-sync.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/cesium-state-sync.ts"],"names":[],"mappings":"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"}