@honua/app-platform 0.0.20-alpha.0

package/operator/workspace/types.js

@@ -0,0 +1,47 @@
+/**
+ * Operator workspace types — UI view models the operator controllers
+ * and reference components consume. They are not the wire DTOs the
+ * server emits; the canonical operator contract
+ * (`honua-server/docs/archive/developer/AI_OPERATOR_CONTRACT.md`,
+ * §AnalysisIntent, §ClarificationRequest, §ClarificationResponse,
+ * §AnalysisPlan, §ExecutionJob) names different fields and uses
+ * different shapes for the same semantic objects.
+ *
+ * The split is deliberate: controllers want form-friendly clarification
+ * fields and a flat plan-step shape that the plan-review UI can
+ * decorate, while the wire contract carries `planId`/`stepId`,
+ * `dependsOn` adjacency, string-keyed `inputs` maps, and reason-coded
+ * clarification questions. The `OperatorClient` implementation is
+ * responsible for the bidirectional adapter at the transport boundary
+ * (HTTP / MCP / gRPC); controllers in this module deliberately know
+ * nothing about the wire framing.
+ *
+ * Adapter mapping responsibilities, by SDK type:
+ *
+ * - {@link ClarificationField} ↔ server `ClarificationQuestion`
+ *   (`id` ↔ `questionId`, `label` ↔ `prompt`, `type` ↔ `kind`).
+ * - {@link ClarificationAnswer} ↔ entries in the server's
+ *   `ClarificationResponse.answers` map (`fieldId` is the
+ *   `questionId`; `value` becomes a single-element string array on the
+ *   wire — multi-select callers send the controller multiple
+ *   `ClarificationAnswer` entries with the same `fieldId`).
+ * - {@link PlanStep} ↔ server `PlanStep` (`id` ↔ `stepId`, `inputs`
+ *   string array ↔ string-keyed `inputs` map, `outputs` string array
+ *   ↔ server `outputs` artifact-kind enum, `dependsOn` is collapsed
+ *   into the steps the controller orders).
+ * - {@link AnalysisPlan} / {@link PublishingPlan} / {@link BuilderPlan} /
+ *   {@link DeploymentPlan} ↔ server `AnalysisPlan` (`id` ↔ `planId`).
+ *   Server-side `warnings[]` is preserved on the open `[extra: string]`
+ *   index signature instead of being modelled at this layer.
+ *
+ * Shapes follow the mirror-not-duplicate posture used by
+ * `src/runtime/map-package.ts`: structurally typed, additive fields
+ * preserved through the open `[extra: string]: unknown` index signature,
+ * no parallel validation logic.
+ *
+ * `AppPackage` is forward-declared as a stub until the canonical server
+ * shape is delivered alongside the `HonuaClient` operator transport.
+ *
+ * @module
+ */
+export {};

package/operator/workspace/workspace.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `OperatorWorkspace` — cross-surface orchestrator. Wires controllers
+ * for chat, clarification, plan review, execution, map and builder
+ * workspaces, and approval into a single typed event stream that
+ * embedders can subscribe to.
+ *
+ * Individual controllers stay independently usable; the workspace is
+ * the orchestrator, not a gatekeeper.
+ *
+ * @module
+ */
+import type { LinkedViewPresetName } from "../../exploration/index.js";
+import type { LoadMapPackageOptions } from "../../runtime/index.js";
+import type { OperatorClient } from "../client.js";
+import { ApprovalController } from "../controllers/approval.js";
+import { BuilderWorkspaceController } from "../controllers/builder-workspace.js";
+import { ChatController } from "../controllers/chat.js";
+import { ClarificationController } from "../controllers/clarification.js";
+import { ExecutionController } from "../controllers/execution.js";
+import { type MapFactory, MapWorkspaceController } from "../controllers/map-workspace.js";
+import { PlanReviewController } from "../controllers/plan-review.js";
+import type { MessageCatalog } from "../i18n/messages.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import { type ThemeProvider } from "../theming/provider.js";
+import type { OperatorThemeTokens } from "../theming/tokens.js";
+import type { Unsubscribe, WorkspaceEvent } from "./events.js";
+export interface OperatorWorkspaceOptions {
+    client: OperatorClient;
+    /** Optional MapLibre map factory; required if the host plans to load map packages. */
+    mapFactory?: MapFactory;
+    /** Map-runtime options for `loadMapPackage`. */
+    mapLoadOptions?: Omit<LoadMapPackageOptions, "telemetry">;
+    /** Linked-view preset for the embedded `ExplorationContext`. Defaults to `"mapDriven"`. */
+    explorationPreset?: LinkedViewPresetName;
+    theme?: ThemeProvider | OperatorThemeTokens;
+    messages?: MessageCatalog;
+    telemetry?: OperatorTelemetry;
+}
+export declare class OperatorWorkspace {
+    #private;
+    readonly chat: ChatController;
+    readonly clarification: ClarificationController;
+    readonly planReview: PlanReviewController;
+    readonly execution: ExecutionController;
+    readonly map: MapWorkspaceController | undefined;
+    readonly builder: BuilderWorkspaceController;
+    readonly approval: ApprovalController;
+    readonly theme: ThemeProvider;
+    readonly messages: MessageCatalog | undefined;
+    constructor(options: OperatorWorkspaceOptions);
+    on(listener: (event: WorkspaceEvent) => void): Unsubscribe;
+    dispose(): void;
+    /** Read-only accessor used by host code that needs the active context. */
+    get activeIntentId(): string | undefined;
+    get activeOperationId(): string | undefined;
+}
+export type { Unsubscribe, WorkspaceEvent } from "./events.js";
+//# sourceMappingURL=workspace.d.ts.map

package/operator/workspace/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../../src/operator/workspace/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,KAAK,UAAU,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG/D,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,cAAc,CAAC;IACvB,sFAAsF;IACtF,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,gDAAgD;IAChD,cAAc,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC;IAC1D,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,oBAAoB,CAAC;IACzC,KAAK,CAAC,EAAE,aAAa,GAAG,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,qBAAa,iBAAiB;;IAC5B,SAAgB,IAAI,EAAE,cAAc,CAAC;IACrC,SAAgB,aAAa,EAAE,uBAAuB,CAAC;IACvD,SAAgB,UAAU,EAAE,oBAAoB,CAAC;IACjD,SAAgB,SAAS,EAAE,mBAAmB,CAAC;IAC/C,SAAgB,GAAG,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACxD,SAAgB,OAAO,EAAE,0BAA0B,CAAC;IACpD,SAAgB,QAAQ,EAAE,kBAAkB,CAAC;IAC7C,SAAgB,KAAK,EAAE,aAAa,CAAC;IACrC,SAAgB,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAC;gBAQlC,OAAO,EAAE,wBAAwB;IAkC7C,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,WAAW;IAI1D,OAAO,IAAI,IAAI;IAqRtB,0EAA0E;IAC1E,IAAW,cAAc,IAAI,MAAM,GAAG,SAAS,CAE9C;IAED,IAAW,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEjD;CACF;AAED,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/operator/workspace/workspace.js

@@ -0,0 +1,339 @@
+/**
+ * `OperatorWorkspace` — cross-surface orchestrator. Wires controllers
+ * for chat, clarification, plan review, execution, map and builder
+ * workspaces, and approval into a single typed event stream that
+ * embedders can subscribe to.
+ *
+ * Individual controllers stay independently usable; the workspace is
+ * the orchestrator, not a gatekeeper.
+ *
+ * @module
+ */
+import { ApprovalController } from "../controllers/approval.js";
+import { ListenerBag } from "../controllers/base.js";
+import { BuilderWorkspaceController } from "../controllers/builder-workspace.js";
+import { ChatController } from "../controllers/chat.js";
+import { ClarificationController } from "../controllers/clarification.js";
+import { ExecutionController } from "../controllers/execution.js";
+import { MapWorkspaceController } from "../controllers/map-workspace.js";
+import { PlanReviewController } from "../controllers/plan-review.js";
+import { HonuaOperatorIntentError, HonuaOperatorPlanError, isHonuaOperatorError } from "../errors.js";
+import { createThemeProvider } from "../theming/provider.js";
+export class OperatorWorkspace {
+    chat;
+    clarification;
+    planReview;
+    execution;
+    map;
+    builder;
+    approval;
+    theme;
+    messages;
+    #telemetry;
+    #bag = new ListenerBag();
+    #unsubscribers = [];
+    #activeIntentId;
+    #activeOperationId;
+    constructor(options) {
+        const { client, telemetry } = options;
+        this.#telemetry = telemetry;
+        this.theme =
+            options.theme && typeof options.theme.apply === "function"
+                ? options.theme
+                : createThemeProvider(options.theme);
+        this.messages = options.messages;
+        this.chat = new ChatController({ client, telemetry });
+        this.clarification = new ClarificationController({ client, telemetry });
+        this.planReview = new PlanReviewController({ client, telemetry });
+        this.execution = new ExecutionController({ client, telemetry });
+        this.builder = new BuilderWorkspaceController({ client, telemetry });
+        this.approval = new ApprovalController({ client, telemetry });
+        this.map = options.mapFactory
+            ? new MapWorkspaceController({
+                client,
+                mapFactory: options.mapFactory,
+                explorationPreset: options.explorationPreset,
+                telemetry,
+                ...(options.mapLoadOptions ? { loadOptions: options.mapLoadOptions } : {}),
+            })
+            : undefined;
+        this.#wireChat();
+        this.#wireClarification();
+        this.#wirePlanReview();
+        this.#wireExecution();
+        this.#wireMap();
+        this.#wireBuilder();
+        this.#wireApproval();
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    dispose() {
+        // Abort any in-flight chat stream first so its for-await loop
+        // exits before we tear down listeners. Without this a slow chat
+        // network request could keep mutating chat state after the
+        // workspace has been disposed.
+        this.chat.abort();
+        for (const off of this.#unsubscribers.splice(0))
+            off();
+        this.execution.dispose();
+        this.map?.dispose();
+        this.builder.dispose();
+        this.#bag.clear();
+    }
+    // ── Wiring ──────────────────────────────────────────────────
+    #wireChat() {
+        this.#unsubscribers.push(this.chat.on((event) => {
+            switch (event.kind) {
+                case "turn-updated":
+                    this.#bag.emit({ kind: "turn-updated", turn: event.turn });
+                    break;
+                case "intent-drafted":
+                    this.#activeIntentId = event.intent.id;
+                    this.map?.bindIntent(event.intent.id);
+                    this.builder.bindIntent(event.intent.id);
+                    this.#bag.emit({ kind: "intent-drafted", intent: event.intent });
+                    if (event.intent.clarifications && event.intent.clarifications.length > 0) {
+                        this.clarification.load(event.intent);
+                        this.#bag.emit({ kind: "clarification-needed", intent: event.intent });
+                    }
+                    else {
+                        this.#advanceToPlan(event.intent.id);
+                    }
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+            }
+        }));
+    }
+    #wireClarification() {
+        this.#unsubscribers.push(this.clarification.on((event) => {
+            switch (event.kind) {
+                case "submitted":
+                    this.#activeIntentId = event.intent.id;
+                    this.map?.bindIntent(event.intent.id);
+                    this.builder.bindIntent(event.intent.id);
+                    this.#bag.emit({ kind: "clarification-answered", intent: event.intent });
+                    if (event.intent.clarifications && event.intent.clarifications.length > 0) {
+                        this.#bag.emit({ kind: "clarification-needed", intent: event.intent });
+                    }
+                    else {
+                        this.#advanceToPlan(event.intent.id);
+                    }
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+                case "loaded":
+                case "answer-changed":
+                    // Intermediate signals — embedder reads through controller.
+                    break;
+            }
+        }));
+    }
+    #wirePlanReview() {
+        this.#unsubscribers.push(this.planReview.on((event) => {
+            switch (event.kind) {
+                case "plan-loaded":
+                case "plan-revised":
+                    // Defence-in-depth: PlanReviewController already drops
+                    // stale resolutions via its generation token, but a host
+                    // that drives planReview.load directly could still queue a
+                    // plan whose intent is no longer the active one. The
+                    // filter only fires when an active intent is set; hosts
+                    // that exercise plan-review without going through the
+                    // chat/clarification flow still see the events.
+                    if (this.#activeIntentId !== undefined && event.plan.intentId !== this.#activeIntentId) {
+                        break;
+                    }
+                    this.#bag.emit({ kind: "plan-loaded", plan: event.plan });
+                    break;
+                case "plan-accepted":
+                    if (this.#activeIntentId !== undefined && event.plan.intentId !== this.#activeIntentId) {
+                        break;
+                    }
+                    this.#bag.emit({ kind: "plan-accepted", plan: event.plan });
+                    this.#advanceToExecution(event.plan);
+                    break;
+                case "plan-revising":
+                    // Intermediate; embedder watches the controller event stream.
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+            }
+        }));
+    }
+    #wireExecution() {
+        this.#unsubscribers.push(this.execution.on((event) => {
+            switch (event.kind) {
+                case "started":
+                    this.#activeOperationId = event.executionId;
+                    this.#bag.emit({ kind: "execution-started", executionId: event.executionId });
+                    break;
+                case "progress":
+                    this.#bag.emit({
+                        kind: "execution-progress",
+                        executionId: event.executionId,
+                        ...(event.progress.percent !== undefined ? { percent: event.progress.percent } : {}),
+                        ...(event.progress.message !== undefined ? { message: event.progress.message } : {}),
+                    });
+                    break;
+                case "successful": {
+                    // Bind the result load to the executionId that produced
+                    // it. If a newer execution takes ownership before this
+                    // load finishes, the .catch suppresses the stale error and
+                    // the controller-level generation token prevents the stale
+                    // package from clobbering newer state.
+                    const executionId = event.executionId;
+                    if (executionId !== this.#activeOperationId)
+                        break;
+                    this.#bag.emit({ kind: "execution-terminal", executionId, result: event.result });
+                    const { result } = event;
+                    if (result.mapPackage && this.map) {
+                        // Map / app loadPackage always rejects with a typed
+                        // operator error after wrapping; route any rejection
+                        // through `#emitError` (which wraps unknowns) so a host
+                        // factory failure cannot disappear from the event stream
+                        // — but only when the execution is still active.
+                        void this.map.loadPackage(result.mapPackage).catch((error) => {
+                            if (executionId !== this.#activeOperationId)
+                                return;
+                            this.#emitError(error);
+                        });
+                    }
+                    if (result.appPackage) {
+                        void this.builder.loadPackage(result.appPackage).catch((error) => {
+                            if (executionId !== this.#activeOperationId)
+                                return;
+                            this.#emitError(error);
+                        });
+                        if (result.mapPackage)
+                            this.builder.bindMapPackage(result.mapPackage);
+                    }
+                    break;
+                }
+                case "failed":
+                    this.#emitError(event.error);
+                    break;
+                case "dismissed":
+                    this.#bag.emit({ kind: "execution-dismissed", executionId: event.executionId });
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+            }
+        }));
+    }
+    // Cross-surface hand-offs. The workspace orchestrates the documented
+    // state machine — chat/clarification → plan-load → execution-start —
+    // so embedders observe a single event stream rather than wiring each
+    // controller transition by hand. Async failures surface through the
+    // controllers' own `error` events, which `#wirePlanReview` /
+    // `#wireExecution` route to `#emitError`; the trailing `.catch` here
+    // only suppresses the unhandled-rejection warning.
+    #advanceToPlan(intentId) {
+        void this.planReview.load(intentId).catch(() => { });
+    }
+    #advanceToExecution(plan) {
+        void this.execution.start(plan).catch(() => { });
+    }
+    #wireMap() {
+        if (!this.map)
+            return;
+        this.#unsubscribers.push(this.map.on((event) => {
+            switch (event.kind) {
+                case "package-loaded":
+                    this.#bag.emit({ kind: "map-loaded", pkg: event.pkg });
+                    break;
+                case "package-refined":
+                    this.#bag.emit({ kind: "map-refined", pkg: event.pkg });
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+                case "package-disposed":
+                    break;
+            }
+        }));
+    }
+    #wireBuilder() {
+        this.#unsubscribers.push(this.builder.on((event) => {
+            switch (event.kind) {
+                case "package-loaded":
+                    this.#bag.emit({ kind: "app-loaded", pkg: event.pkg });
+                    break;
+                case "package-refined":
+                    this.#bag.emit({ kind: "app-refined", pkg: event.pkg });
+                    break;
+                case "map-bound":
+                    // Internal hand-off; not a top-level workspace event.
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+            }
+        }));
+    }
+    #wireApproval() {
+        this.#unsubscribers.push(this.approval.on((event) => {
+            switch (event.kind) {
+                case "loaded":
+                    // Defence-in-depth: ApprovalController already drops stale
+                    // resolutions, but a host that drives approval.load
+                    // directly could still queue a decision whose operation is
+                    // no longer active. The filter only fires when an active
+                    // operation is set, so hosts exercising approval without
+                    // an execution still see the events.
+                    if (this.#activeOperationId !== undefined && event.decision.operationId !== this.#activeOperationId) {
+                        break;
+                    }
+                    if (event.decision.state === "pending") {
+                        this.#bag.emit({ kind: "approval-required", decision: event.decision });
+                    }
+                    else {
+                        this.#bag.emit({ kind: "approval-resolved", decision: event.decision });
+                    }
+                    break;
+                case "confirmed":
+                    if (this.#activeOperationId !== undefined && event.decision.operationId !== this.#activeOperationId) {
+                        break;
+                    }
+                    this.#bag.emit({ kind: "approval-resolved", decision: event.decision });
+                    break;
+                case "audit":
+                    // Audit fan-out happens through telemetry.
+                    break;
+                case "error":
+                    this.#emitError(event.error);
+                    break;
+            }
+        }));
+    }
+    #emitError(error) {
+        if (isHonuaOperatorError(error)) {
+            this.#bag.emit({ kind: "error", error, recoverable: this.#isRecoverable(error) });
+            return;
+        }
+        // Defensive: anything that is not a known operator error gets
+        // wrapped as an intent-stage error so embedders never see a raw
+        // `unknown` on the workspace event stream.
+        const wrapped = new HonuaOperatorIntentError("workspace observed an unrecognized error", { cause: error });
+        this.#bag.emit({ kind: "error", error: wrapped, recoverable: false });
+    }
+    #isRecoverable(error) {
+        if (error instanceof HonuaOperatorIntentError)
+            return true;
+        if (error instanceof HonuaOperatorPlanError)
+            return true;
+        return false;
+    }
+    /** Read-only accessor used by host code that needs the active context. */
+    get activeIntentId() {
+        return this.#activeIntentId;
+    }
+    get activeOperationId() {
+        return this.#activeOperationId;
+    }
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@honua/app-platform",
+  "version": "0.0.20-alpha.0",
+  "description": "Honua application-platform surfaces: app-shell, workspace, scene, operator, studio, and hosted-product clients",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./app-workspace/index.js",
+  "types": "./app-workspace/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./app-workspace/index.d.ts",
+      "default": "./app-workspace/index.js"
+    },
+    "./app": {
+      "types": "./app/index.d.ts",
+      "default": "./app/index.js"
+    },
+    "./app-controller": {
+      "types": "./app-controller/index.d.ts",
+      "default": "./app-controller/index.js"
+    },
+    "./app-workspace": {
+      "types": "./app-workspace/index.d.ts",
+      "default": "./app-workspace/index.js"
+    },
+    "./scene-workspace": {
+      "types": "./scene-workspace/index.d.ts",
+      "default": "./scene-workspace/index.js"
+    },
+    "./collaboration": {
+      "types": "./collaboration/index.d.ts",
+      "default": "./collaboration/index.js"
+    },
+    "./control-plane": {
+      "types": "./control-plane/index.d.ts",
+      "default": "./control-plane/index.js"
+    },
+    "./replica-sync": {
+      "types": "./replica-sync/index.d.ts",
+      "default": "./replica-sync/index.js"
+    },
+    "./share": {
+      "types": "./share/index.d.ts",
+      "default": "./share/index.js"
+    },
+    "./operate": {
+      "types": "./operate/index.d.ts",
+      "default": "./operate/index.js"
+    },
+    "./generated-app": {
+      "types": "./generated-app/index.d.ts",
+      "default": "./generated-app/index.js"
+    },
+    "./studio": {
+      "types": "./studio/index.d.ts",
+      "default": "./studio/index.js"
+    },
+    "./operator": {
+      "types": "./operator/index.d.ts",
+      "default": "./operator/index.js"
+    },
+    "./operator/controllers": {
+      "types": "./operator/controllers/index.d.ts",
+      "default": "./operator/controllers/index.js"
+    },
+    "./operator/workspace": {
+      "types": "./operator/workspace/index.d.ts",
+      "default": "./operator/workspace/index.js"
+    },
+    "./operator/theming": {
+      "types": "./operator/theming/index.d.ts",
+      "default": "./operator/theming/index.js"
+    },
+    "./operator/i18n": {
+      "types": "./operator/i18n/index.d.ts",
+      "default": "./operator/i18n/index.js"
+    },
+    "./controls": {
+      "types": "./controls/index.d.ts",
+      "default": "./controls/index.js"
+    },
+    "./web-components": {
+      "types": "./web-components/index.d.ts",
+      "default": "./web-components/index.js"
+    }
+  },
+  "dependencies": {
+    "@maplibre/maplibre-gl-style-spec": "^24.7.0"
+  },
+  "peerDependencies": {
+    "maplibre-gl": "^5.0.0",
+    "cesium": "^1.139.0"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    },
+    "cesium": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/realtime/exploration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Realtime helpers for linked exploration views.
+ *
+ * @module
+ */
+import type { SourceId } from "../contract/types.js";
+import type { ExplorationViewController, FeatureSelectionTarget } from "../exploration/types.js";
+import type { RealtimeFeatureState } from "./types.js";
+export interface ReconcileRealtimeSelectionOptions {
+    readonly sourceId?: SourceId;
+    /** Remove selections when the record is absent from live state. @default true */
+    readonly requireLiveRecord?: boolean;
+}
+export declare function filterRealtimeSelection<TFeature>(selection: ReadonlyArray<FeatureSelectionTarget>, state: RealtimeFeatureState<TFeature>, options?: ReconcileRealtimeSelectionOptions): ReadonlyArray<FeatureSelectionTarget>;
+export declare function reconcileRealtimeSelection<TFeature>(view: ExplorationViewController, state: RealtimeFeatureState<TFeature>, options?: ReconcileRealtimeSelectionOptions): void;
+//# sourceMappingURL=exploration.d.ts.map

package/realtime/exploration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploration.d.ts","sourceRoot":"","sources":["../../../src/realtime/exploration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAC9C,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,EAChD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,iCAAsC,GAC9C,aAAa,CAAC,sBAAsB,CAAC,CAQvC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,IAAI,EAAE,yBAAyB,EAC/B,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,iCAAsC,GAC9C,IAAI,CAIN"}

package/realtime/exploration.js

@@ -0,0 +1,32 @@
+/**
+ * Realtime helpers for linked exploration views.
+ *
+ * @module
+ */
+import { isSourceQualifiedSelectionTarget } from "../exploration/selection.js";
+import { realtimeFeatureKey } from "./reducer.js";
+export function filterRealtimeSelection(selection, state, options = {}) {
+    const { sourceId, requireLiveRecord = true } = options;
+    return selection.filter((target) => {
+        const key = selectionKey(target, sourceId);
+        if (!key)
+            return true;
+        if (state.tombstones[key])
+            return false;
+        return requireLiveRecord ? Boolean(state.records[key]) : true;
+    });
+}
+export function reconcileRealtimeSelection(view, state, options = {}) {
+    const next = filterRealtimeSelection(view.state.selection, state, options);
+    if (next.length === view.state.selection.length)
+        return;
+    view.select(next, { replace: true });
+}
+function selectionKey(target, sourceId) {
+    if (isSourceQualifiedSelectionTarget(target)) {
+        return realtimeFeatureKey(target.sourceId, target.id);
+    }
+    if (!sourceId)
+        return undefined;
+    return realtimeFeatureKey(sourceId, target);
+}