@honua/app-platform 0.0.20-alpha.0

package/operator/controllers/clarification.js

@@ -0,0 +1,121 @@
+/**
+ * `ClarificationController` — typed form derived from
+ * `intent.clarifications[]`. Submission is a pass-through to
+ * `OperatorClient.operator.clarify` and yields a fresh intent revision.
+ *
+ * @module
+ */
+import { HonuaOperatorIntentError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+export class ClarificationController {
+    #client;
+    #telemetry;
+    #bag = new ListenerBag();
+    #intent;
+    #answers = new Map();
+    #submitting = false;
+    // Bumped on every load() and submit(); an in-flight submit checks
+    // this on resolution so a slow clarify() response cannot revive a
+    // superseded intent after the host has already moved on to a newer
+    // one. Generation > captured generation ⇒ drop the result silently.
+    #generation = 0;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+    }
+    get state() {
+        return {
+            intent: this.#intent,
+            fields: this.#intent?.clarifications ?? [],
+            answers: new Map(this.#answers),
+            submitting: this.#submitting,
+        };
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    load(intent) {
+        this.#generation += 1;
+        // Reset the submitting flag here too: a load() that supersedes a
+        // pending submit() leaves the in-flight call unable to clear it
+        // (its `finally` is generation-gated), so without this the
+        // observable `state.submitting` would stay true forever.
+        this.#submitting = false;
+        this.#intent = intent;
+        this.#answers.clear();
+        this.#bag.emit({ kind: "loaded", intent });
+    }
+    setAnswer(fieldId, value) {
+        if (!this.#intent) {
+            throw new HonuaOperatorIntentError("setAnswer called before clarification load");
+        }
+        const exists = this.#intent.clarifications?.some((field) => field.id === fieldId);
+        if (!exists) {
+            throw new HonuaOperatorIntentError(`unknown clarification field "${fieldId}"`, {
+                intentId: this.#intent.id,
+                detail: { fieldId },
+            });
+        }
+        this.#answers.set(fieldId, value);
+        this.#bag.emit({ kind: "answer-changed", fieldId, value });
+    }
+    /**
+     * Submit the current answers and resolve with the revised intent.
+     * Missing required answers reject with `HonuaOperatorIntentError`
+     * before any network call so the controller never depends on the
+     * server for required-field validation.
+     */
+    async submit(signal) {
+        if (!this.#intent) {
+            throw new HonuaOperatorIntentError("submit called before clarification load");
+        }
+        const intent = this.#intent;
+        const missing = [];
+        for (const field of intent.clarifications ?? []) {
+            if (field.required && !(this.#answers.get(field.id) ?? "").trim())
+                missing.push(field.id);
+        }
+        if (missing.length > 0) {
+            throw new HonuaOperatorIntentError("missing required clarification answers", {
+                intentId: intent.id,
+                detail: { missing },
+            });
+        }
+        const answers = [...this.#answers.entries()].map(([fieldId, value]) => ({
+            fieldId,
+            value,
+        }));
+        const gen = ++this.#generation;
+        this.#submitting = true;
+        try {
+            const revised = await withTelemetrySpan(this.#telemetry, "clarify", intent.id, () => this.#client.operator.clarify(intent.id, answers, signal), { fieldCount: answers.length });
+            if (gen !== this.#generation) {
+                // A newer load()/submit() superseded this submission while it
+                // was in flight. Drop the response without committing or
+                // emitting so the workspace cannot be driven back to a stale
+                // intent.
+                return revised;
+            }
+            this.#intent = revised;
+            this.#answers.clear();
+            this.#bag.emit({ kind: "submitted", intent: revised });
+            return revised;
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorIntentError
+                ? error
+                : new HonuaOperatorIntentError("clarification submit failed", {
+                    intentId: intent.id,
+                    cause: error,
+                });
+            if (gen === this.#generation) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+        finally {
+            if (gen === this.#generation)
+                this.#submitting = false;
+        }
+    }
+}

package/operator/controllers/execution.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `ExecutionController` — thin adapter on `IJobRun<ExecutionResult>`.
+ * Subscribes to `watch()`, surfaces snapshot transitions on a controller
+ * event stream, and routes the terminal payload onto the workspace.
+ *
+ * @module
+ */
+import { type IJobRun, type JobProgress, type JobSnapshot } from "../../contract/index.js";
+import { type OperatorClient } from "../client.js";
+import { HonuaOperatorExecutionError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import type { ExecutionResult, OperatorPlan } from "../workspace/types.js";
+import { type Unsubscribe } from "./base.js";
+export type ExecutionEvent = {
+    kind: "started";
+    executionId: string;
+} | {
+    kind: "progress";
+    executionId: string;
+    progress: JobProgress;
+} | {
+    kind: "successful";
+    executionId: string;
+    result: ExecutionResult;
+} | {
+    kind: "failed";
+    executionId: string;
+    error: HonuaOperatorExecutionError;
+} | {
+    kind: "dismissed";
+    executionId: string;
+} | {
+    kind: "error";
+    error: HonuaOperatorExecutionError;
+};
+export interface ExecutionControllerOptions {
+    client: OperatorClient;
+    telemetry?: OperatorTelemetry;
+}
+export declare class ExecutionController {
+    #private;
+    constructor(options: ExecutionControllerOptions);
+    get run(): IJobRun<ExecutionResult> | undefined;
+    get snapshot(): JobSnapshot<ExecutionResult> | undefined;
+    on(listener: (event: ExecutionEvent) => void): Unsubscribe;
+    /**
+     * Submit a plan and start watching the resulting job. Resolves with
+     * the live `IJobRun` once the watch subscription is active.
+     *
+     * Concurrent calls supersede each other: the second call disposes
+     * the first (which aborts its in-flight `submitPlan`); if the older
+     * `submitPlan` still resolves, the result is cancelled and the
+     * promise rejects so the older caller does not see a started event
+     * for a run that is no longer authoritative.
+     */
+    start(plan: OperatorPlan, signal?: AbortSignal): Promise<IJobRun<ExecutionResult>>;
+    cancel(): Promise<void>;
+    dispose(): void;
+}
+//# sourceMappingURL=execution.d.ts.map

package/operator/controllers/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/execution.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,WAAW,EAChB,KAAK,WAAW,EAGjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,2BAA2B,EAA0C,MAAM,cAAc,CAAC;AACnG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,2BAA2B,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,2BAA2B,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,qBAAa,mBAAmB;;gBAeX,OAAO,EAAE,0BAA0B;IAKtD,IAAW,GAAG,IAAI,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,CAErD;IAED,IAAW,QAAQ,IAAI,WAAW,CAAC,eAAe,CAAC,GAAG,SAAS,CAE9D;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,WAAW;IAIjE;;;;;;;;;OASG;IACU,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAoFlF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C7B,OAAO,IAAI,IAAI;CAqEvB"}

package/operator/controllers/execution.js

@@ -0,0 +1,286 @@
+/**
+ * `ExecutionController` — thin adapter on `IJobRun<ExecutionResult>`.
+ * Subscribes to `watch()`, surfaces snapshot transitions on a controller
+ * event stream, and routes the terminal payload onto the workspace.
+ *
+ * @module
+ */
+import { isJobTerminal, } from "../../contract/index.js";
+import { OPERATOR_EXECUTION_OUTPUT_KEY } from "../client.js";
+import { HonuaOperatorExecutionError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+export class ExecutionController {
+    #client;
+    #telemetry;
+    #bag = new ListenerBag();
+    #activeRun;
+    #unsubscribe;
+    #activePlan;
+    #lastSnapshot;
+    // Per-start abort controller. dispose() aborts it so the in-flight
+    // submitPlan() can short-circuit; the start path also uses identity
+    // comparison (this.#startAbort === captured) to detect the case
+    // where submitPlan resolved despite the abort and a newer start
+    // already took ownership.
+    #startAbort;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+    }
+    get run() {
+        return this.#activeRun;
+    }
+    get snapshot() {
+        return this.#lastSnapshot;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    /**
+     * Submit a plan and start watching the resulting job. Resolves with
+     * the live `IJobRun` once the watch subscription is active.
+     *
+     * Concurrent calls supersede each other: the second call disposes
+     * the first (which aborts its in-flight `submitPlan`); if the older
+     * `submitPlan` still resolves, the result is cancelled and the
+     * promise rejects so the older caller does not see a started event
+     * for a run that is no longer authoritative.
+     */
+    async start(plan, signal) {
+        this.dispose();
+        const startAbort = new AbortController();
+        this.#startAbort = startAbort;
+        const linkedSignal = linkSignals(signal, startAbort);
+        let run;
+        try {
+            run = await withTelemetrySpan(this.#telemetry, "execution-start", plan.intentId, () => this.#client.operator.submitPlan(plan, linkedSignal), { planId: plan.id, planKind: plan.kind });
+        }
+        catch (error) {
+            const wrapped = wrapExecutionError(error, "plan submission failed", {
+                intentId: plan.intentId,
+                detail: { planId: plan.id, planKind: plan.kind },
+            });
+            // Suppress the error event when this start was superseded — the
+            // newer start owns the surface and a stale error would mislead
+            // observers about the current execution.
+            if (this.#startAbort === startAbort) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+        if (this.#startAbort !== startAbort) {
+            // A newer start took ownership while we were awaiting submitPlan.
+            // Cancel this run silently and reject so the original caller is
+            // not handed a stale IJobRun.
+            void run.cancel().catch(() => { });
+            throw new HonuaOperatorExecutionError("execution superseded by a newer start", {
+                intentId: plan.intentId,
+                executionId: run.id,
+                failureKind: "Cancelled",
+            });
+        }
+        this.#activeRun = run;
+        this.#activePlan = plan;
+        this.#bag.emit({ kind: "started", executionId: run.id });
+        this.#unsubscribe = run.watch((snapshot) => {
+            // Stale-watch guard: an older watch subscription can fire after
+            // dispose() if the underlying adapter has already buffered the
+            // snapshot. `#activeRun !== run` means we are no longer the
+            // authoritative run; drop without emitting.
+            if (this.#activeRun !== run)
+                return;
+            // Double-emit guard: cancel() may have already synthesized a
+            // terminal snapshot for the same run. Detect via the prior
+            // #lastSnapshot's status before overwriting it.
+            const alreadyTerminal = this.#lastSnapshot !== undefined && isJobTerminal(this.#lastSnapshot.status);
+            this.#lastSnapshot = snapshot;
+            if (snapshot.progress) {
+                this.#bag.emit({ kind: "progress", executionId: run.id, progress: snapshot.progress });
+            }
+            if (!isJobTerminal(snapshot.status))
+                return;
+            if (alreadyTerminal)
+                return;
+            this.#emitTerminal(run.id, snapshot);
+        });
+        // The shared `IJobRun` contract permits passive `watch()` implementations
+        // (the OGC adapter only registers listeners; polling is driven by
+        // `results()`). Kick off the polling path so snapshots actually flow.
+        // `results()` rejects with `HonuaJobFailedError` on failed/dismissed
+        // terminals — those are already surfaced by the watcher above, so we
+        // suppress them when the watcher already observed a terminal snapshot.
+        // Any other rejection (poll-side network failure that prevents reaching
+        // a terminal state) routes through the error event surface.
+        void run.results().catch((error) => {
+            if (this.#activeRun !== run)
+                return;
+            if (this.#lastSnapshot && isJobTerminal(this.#lastSnapshot.status))
+                return;
+            const wrapped = wrapExecutionError(error, "execution polling failed", {
+                intentId: plan.intentId,
+                executionId: run.id,
+            });
+            this.#bag.emit({ kind: "error", error: wrapped });
+        });
+        return run;
+    }
+    async cancel() {
+        if (!this.#activeRun)
+            return;
+        const run = this.#activeRun;
+        let status;
+        try {
+            status = await run.cancel();
+        }
+        catch (error) {
+            if (this.#activeRun !== run)
+                return;
+            const wrapped = wrapExecutionError(error, "execution cancel failed", {
+                intentId: this.#activePlan?.intentId,
+                executionId: run.id,
+            });
+            this.#bag.emit({ kind: "error", error: wrapped });
+            throw wrapped;
+        }
+        if (this.#activeRun !== run)
+            return;
+        if (!isJobTerminal(status))
+            return;
+        // The IJobRun contract does not require watch() to fire during
+        // cancellation, so a conforming adapter can dismiss the run
+        // without ever delivering a terminal snapshot. Synthesize one when
+        // the watcher has not already produced a terminal. The watcher's
+        // double-emit guard handles the converse race (watcher fires after
+        // we synthesize).
+        if (this.#lastSnapshot !== undefined && isJobTerminal(this.#lastSnapshot.status))
+            return;
+        let snapshot = { status };
+        if (status !== "dismissed") {
+            // The server may have raced cancel to a successful/failed
+            // terminal. poll() carries the authoritative payload; fall back
+            // to the bare status if poll fails so #emitTerminal still routes
+            // to a terminal event rather than silently dropping it.
+            try {
+                const polled = await run.poll();
+                if (this.#activeRun !== run)
+                    return;
+                snapshot = polled;
+            }
+            catch {
+                // Best-effort poll; emit the bare status snapshot.
+            }
+        }
+        if (this.#lastSnapshot !== undefined && isJobTerminal(this.#lastSnapshot.status))
+            return;
+        this.#lastSnapshot = snapshot;
+        this.#emitTerminal(run.id, snapshot);
+    }
+    dispose() {
+        this.#startAbort?.abort();
+        this.#startAbort = undefined;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#activeRun = undefined;
+        this.#activePlan = undefined;
+        this.#lastSnapshot = undefined;
+    }
+    #emitTerminal(executionId, snapshot) {
+        const intentId = this.#activePlan?.intentId;
+        const startedAt = Date.now();
+        const detail = { executionId, status: snapshot.status };
+        if (snapshot.status === "successful") {
+            const result = snapshot.result?.outputs?.[OPERATOR_EXECUTION_OUTPUT_KEY];
+            if (!result) {
+                const error = new HonuaOperatorExecutionError("execution succeeded but no result was returned", {
+                    intentId,
+                    executionId,
+                    failureKind: "OutputBindingFailed",
+                });
+                this.#bag.emit({ kind: "failed", executionId, error });
+                this.#telemetry?.error?.({
+                    kind: "execution-terminal",
+                    intentId,
+                    startedAt,
+                    finishedAt: startedAt,
+                    durationMs: 0,
+                    detail,
+                    error,
+                });
+                return;
+            }
+            this.#bag.emit({ kind: "successful", executionId, result });
+            this.#telemetry?.after?.({
+                kind: "execution-terminal",
+                intentId,
+                startedAt,
+                finishedAt: startedAt,
+                durationMs: 0,
+                detail: { ...detail, resultKind: result.kind },
+            });
+            return;
+        }
+        if (snapshot.status === "dismissed") {
+            this.#bag.emit({ kind: "dismissed", executionId });
+            this.#telemetry?.after?.({
+                kind: "execution-terminal",
+                intentId,
+                startedAt,
+                finishedAt: startedAt,
+                durationMs: 0,
+                detail,
+            });
+            return;
+        }
+        const wrapped = jobErrorToExecutionError(snapshot.error, executionId, intentId);
+        this.#bag.emit({ kind: "failed", executionId, error: wrapped });
+        this.#telemetry?.error?.({
+            kind: "execution-terminal",
+            intentId,
+            startedAt,
+            finishedAt: startedAt,
+            durationMs: 0,
+            detail,
+            error: wrapped,
+        });
+    }
+}
+function jobErrorToExecutionError(jobError, executionId, intentId) {
+    if (!jobError) {
+        return new HonuaOperatorExecutionError("execution failed", {
+            intentId,
+            executionId,
+            failureKind: "ExecutionFailed",
+        });
+    }
+    const failureKind = jobError.code;
+    return new HonuaOperatorExecutionError(jobError.message, {
+        intentId,
+        executionId,
+        failureKind,
+        detail: jobError.details ? { details: jobError.details } : undefined,
+    });
+}
+function wrapExecutionError(error, fallbackMessage, context) {
+    if (error instanceof HonuaOperatorExecutionError)
+        return error;
+    return new HonuaOperatorExecutionError(fallbackMessage, {
+        ...context,
+        failureKind: "ExecutionFailed",
+        cause: error,
+    });
+}
+/**
+ * Returns an `AbortSignal` that fires when either the externally-supplied
+ * caller signal aborts or the per-start internal controller is aborted by
+ * `dispose()`. Lets `submitPlan` be cancelled by either source.
+ */
+function linkSignals(external, internal) {
+    if (!external)
+        return internal.signal;
+    if (external.aborted) {
+        internal.abort();
+        return internal.signal;
+    }
+    external.addEventListener("abort", () => internal.abort(), { once: true });
+    return internal.signal;
+}

package/operator/controllers/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@honua/sdk-js/operator/controllers` — framework-neutral controllers behind the
+ * operator-native component architecture.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { ApprovalController } from "./approval.js";
+export type { ApprovalControllerOptions, ApprovalEvent } from "./approval.js";
+export { BuilderWorkspaceController } from "./builder-workspace.js";
+export type { BuilderWorkspaceControllerOptions, BuilderWorkspaceEvent, PreviewHandle, } from "./builder-workspace.js";
+export { ChatController } from "./chat.js";
+export type { ChatControllerOptions, ChatEvent, DecorateTurn } from "./chat.js";
+export { ClarificationController } from "./clarification.js";
+export type { ClarificationControllerOptions, ClarificationEvent, ClarificationState, } from "./clarification.js";
+export { ExecutionController } from "./execution.js";
+export type { ExecutionControllerOptions, ExecutionEvent } from "./execution.js";
+export { MapWorkspaceController } from "./map-workspace.js";
+export type { MapFactory, MapFactoryResult, MapWorkspaceControllerOptions, MapWorkspaceEvent, } from "./map-workspace.js";
+export { PlanReviewController } from "./plan-review.js";
+export type { DecorateStep, PlanReviewControllerOptions, PlanReviewEvent, PlanRevisionRequest, } from "./plan-review.js";
+//# sourceMappingURL=index.d.ts.map

package/operator/controllers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,YAAY,EACV,iCAAiC,EACjC,qBAAqB,EACrB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,qBAAqB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEhF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EACV,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,6BAA6B,EAC7B,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EACV,YAAY,EACZ,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/operator/controllers/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@honua/sdk-js/operator/controllers` — framework-neutral controllers behind the
+ * operator-native component architecture.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { ApprovalController } from "./approval.js";
+export { BuilderWorkspaceController } from "./builder-workspace.js";
+export { ChatController } from "./chat.js";
+export { ClarificationController } from "./clarification.js";
+export { ExecutionController } from "./execution.js";
+export { MapWorkspaceController } from "./map-workspace.js";
+export { PlanReviewController } from "./plan-review.js";

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

@@ -0,0 +1,85 @@
+/**
+ * `MapWorkspaceController` — orchestrates the `HonuaMapRuntime` and the
+ * `ExplorationContext` for a single result `MapPackage`. The controller
+ * owns no MapLibre source/style code of its own — every map mutation
+ * delegates to the runtime from `src/runtime/`.
+ *
+ * @module
+ */
+import { type ExplorationContext, type LinkedViewPresetName } from "../../exploration/index.js";
+import { type HonuaMapPackage, type HonuaMapPackagePopupBinding, type HonuaMapRuntime, type LegendEntry, type LoadMapPackageOptions, type MaplibreMap, type SetViewStateInput } from "../../runtime/index.js";
+import type { OperatorClient } from "../client.js";
+import { HonuaOperatorMapError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import { type Unsubscribe } from "./base.js";
+export type MapWorkspaceEvent = {
+    kind: "package-loaded";
+    pkg: HonuaMapPackage;
+} | {
+    kind: "package-refined";
+    pkg: HonuaMapPackage;
+} | {
+    kind: "package-disposed";
+} | {
+    kind: "error";
+    error: HonuaOperatorMapError;
+};
+/**
+ * Caller-supplied factory that builds the host MapLibre map and returns
+ * a teardown handle. The host owns the `MaplibreMap` lifecycle.
+ */
+export type MapFactory = () => MapFactoryResult | Promise<MapFactoryResult>;
+export interface MapFactoryResult {
+    map: MaplibreMap;
+    dispose?: () => void;
+}
+export interface MapWorkspaceControllerOptions {
+    client: OperatorClient;
+    mapFactory: MapFactory;
+    /** Linked-view preset for the embedded `ExplorationContext`. Default `"mapDriven"`. */
+    explorationPreset?: LinkedViewPresetName;
+    telemetry?: OperatorTelemetry;
+    /**
+     * Pass-through options handed to `loadMapPackage`. The controller
+     * never instantiates a `HonuaClient` itself — the host wires the
+     * runtime client through this hook.
+     */
+    loadOptions?: Omit<LoadMapPackageOptions, "telemetry">;
+}
+export declare class MapWorkspaceController {
+    #private;
+    constructor(options: MapWorkspaceControllerOptions);
+    get runtime(): HonuaMapRuntime | undefined;
+    get exploration(): ExplorationContext | undefined;
+    on(listener: (event: MapWorkspaceEvent) => void): Unsubscribe;
+    /**
+     * Bind the controller to an intent so that subsequent `refine()` calls
+     * have an intent id to attach to the server request. Idempotent.
+     */
+    bindIntent(intentId: string): void;
+    /**
+     * Load a `MapPackage` into a fresh runtime + exploration context.
+     * Tears down any previously loaded package; safe to call repeatedly.
+     *
+     * Concurrent loads supersede each other via `#opGeneration`: an
+     * older load whose factory or `loadMapPackage` is still pending when
+     * a newer load arrives discards its locally-built runtime/context
+     * instead of overwriting the newer state.
+     */
+    loadPackage(pkg: HonuaMapPackage): Promise<HonuaMapRuntime>;
+    /**
+     * Natural-language refinement. The server returns an updated
+     * `MapPackage`; the runtime's diff path applies it incrementally.
+     * Source-binding failures inside the runtime are forwarded via
+     * `runtime.reportSourceError(...)` rather than thrown.
+     */
+    refine(prompt: string, signal?: AbortSignal): Promise<HonuaMapPackage>;
+    setLayerVisibility(layerId: string, visible: boolean): void;
+    bindPopup(layerId: string, binding?: HonuaMapPackagePopupBinding): {
+        remove(): void;
+    };
+    setViewState(view: SetViewStateInput): void;
+    getLegend(): LegendEntry[];
+    dispose(): void;
+}
+//# sourceMappingURL=map-workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map-workspace.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/map-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAG1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,eAAe,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,eAAe,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE5E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,WAAW,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,oBAAoB,CAAC;IACzC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC;CACxD;AAID,qBAAa,sBAAsB;;gBAoBd,OAAO,EAAE,6BAA6B;IAQzD,IAAW,OAAO,IAAI,eAAe,GAAG,SAAS,CAEhD;IAED,IAAW,WAAW,IAAI,kBAAkB,GAAG,SAAS,CAEvD;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,WAAW;IAIpE;;;OAGG;IACI,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;;;;;OAQG;IACU,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAgFxE;;;;;OAKG;IACU,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAsD5E,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAI3D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE;IAIrF,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAI3C,SAAS,IAAI,WAAW,EAAE;IAI1B,OAAO,IAAI,IAAI;CAyEvB"}