@happyvertical/smrt-svelte 0.55.9 → 0.55.10

package/dist/components/overview/assistant-surface.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The server half of the overview assistant (#3727 phase 4): one overview, for
+ * one principal, as the adapter `@happyvertical/smrt-chat`'s
+ * `createOverviewTools()` operates on. The chat package depends on no UI
+ * package, so it types this object structurally; this module is the
+ * implementation a host returns from its `open(run, pageId)`.
+ *
+ * Every plan and every restore runs through the phase-1 model and
+ * `checkOverviewOverride`, so the assistant can only store an override the
+ * save endpoint would accept. Persistence stays the host's (phase 3): the
+ * surface calls `persist` with the canonical override and keeps its own copy
+ * of the value it last persisted.
+ *
+ * Svelte-free; on `./overview/server`.
+ */
+import { type OverviewOverrideCheck } from './model.js';
+import { type DescribeOverviewInput, type OverviewDescription, type OverviewPlan } from './operations.js';
+import { type WidgetRegistry } from './registry.js';
+import type { OverviewDefinition, OverviewOverride } from './types.js';
+export interface OverviewAssistantSurfaceOptions {
+    /** The page's declaration (allowed set, models, defaults, cap). */
+    definition: OverviewDefinition;
+    /** Defaults to the shared registry. */
+    registry?: WidgetRegistry;
+    /**
+     * The principal's stored override for this page (untrusted JSON; `null`
+     * for none), as the host loaded it for this request.
+     */
+    override: unknown;
+    /**
+     * The concurrency token of the stored row the host loaded `override` from
+     * (`null` when it loaded no row), echoed back to `persist`. With the
+     * phase-3 store (`createOverviewStore` of `@happyvertical/smrt-preferences`)
+     * this is `state.user.revision` from its `load`.
+     */
+    revision: string | null;
+    /** Whether this principal may customize this page (the role gate). */
+    canCustomize: boolean;
+    /**
+     * Store the canonical override (`null` = back to the defaults) in the
+     * principal's tier, CONDITIONALLY on `expected.revision` still being the
+     * stored one: a save that landed since must answer
+     * `{ ok: false, reason: 'conflict' }`, never be overwritten. The phase-3
+     * store plugs in directly:
+     * `(override, { revision }) => store.save(definition, registry, { scope: 'user', override, revision })`
+     * with `store = createOverviewStore({ db })` from `@happyvertical/smrt-preferences`.
+     */
+    persist: (override: OverviewOverride | null, expected: {
+        revision: string | null;
+    }) => OverviewAssistantPersistResult | Promise<OverviewAssistantPersistResult>;
+    /** Turns titles and labels that are i18n keys into text. */
+    translate?: DescribeOverviewInput['translate'];
+    /** Batch cap (default 20). */
+    maxOperations?: number;
+}
+/**
+ * A conditional write's outcome. `revision` is the stored row's new token
+ * (`null` when the write removed the row); omitted, the surface keeps the
+ * token it had. Structurally `OverviewSaveResult` of
+ * `@happyvertical/smrt-preferences`.
+ */
+export type OverviewAssistantPersistResult = {
+    ok: true;
+    revision?: string | null;
+} | {
+    ok: false;
+    reason: 'conflict' | 'not_allowed' | 'invalid';
+    issues?: readonly unknown[];
+};
+/** One overview for one principal; what `createOverviewTools()` drives. */
+export interface OverviewAssistantSurface {
+    readonly pageId: string;
+    readonly canCustomize: boolean;
+    /** Allowed widget types with their option fields, and the arrangement. */
+    describe(): OverviewDescription;
+    /** The canonical override in effect (`null` = defaults). */
+    current(): OverviewOverride | null;
+    /** Plan a batch against {@link current}. Applies nothing. */
+    plan(operations: unknown): OverviewPlan;
+    /** Validate an override (the Undo value) the way a save is validated. */
+    check(override: unknown): OverviewOverrideCheck;
+    /**
+     * Persist a canonical override if the stored row is still the loaded
+     * revision; on success {@link current} and the revision follow it.
+     */
+    persist(override: OverviewOverride | null): Promise<OverviewAssistantPersistResult>;
+}
+/** Build the assistant adapter for one overview and one principal. */
+export declare function createOverviewAssistantSurface(options: OverviewAssistantSurfaceOptions): OverviewAssistantSurface;
+//# sourceMappingURL=assistant-surface.d.ts.map

package/dist/components/overview/assistant-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-surface.d.ts","sourceRoot":"","sources":["../../../src/components/overview/assistant-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,qBAAqB,EAE3B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,qBAAqB,EAE1B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,+BAA+B;IAC9C,mEAAmE;IACnE,UAAU,EAAE,kBAAkB,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,EAAE,CACP,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAClC,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC9E,4DAA4D;IAC5D,SAAS,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC/C,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GACtC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACtC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B,CAAC;AAEN,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,IAAI,mBAAmB,CAAC;IAChC,4DAA4D;IAC5D,OAAO,IAAI,gBAAgB,GAAG,IAAI,CAAC;IACnC,6DAA6D;IAC7D,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,YAAY,CAAC;IACxC,yEAAyE;IACzE,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,qBAAqB,CAAC;IAChD;;;OAGG;IACH,OAAO,CACL,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAChC,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC5C;AAED,sEAAsE;AACtE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,CA2C1B"}

package/dist/components/overview/assistant-surface.js

@@ -0,0 +1,65 @@
+/**
+ * The server half of the overview assistant (#3727 phase 4): one overview, for
+ * one principal, as the adapter `@happyvertical/smrt-chat`'s
+ * `createOverviewTools()` operates on. The chat package depends on no UI
+ * package, so it types this object structurally; this module is the
+ * implementation a host returns from its `open(run, pageId)`.
+ *
+ * Every plan and every restore runs through the phase-1 model and
+ * `checkOverviewOverride`, so the assistant can only store an override the
+ * save endpoint would accept. Persistence stays the host's (phase 3): the
+ * surface calls `persist` with the canonical override and keeps its own copy
+ * of the value it last persisted.
+ *
+ * Svelte-free; on `./overview/server`.
+ */
+import { checkOverviewOverride, diffOverview, resolveOverview, } from './model.js';
+import { describeOverview, planOverviewOperations, } from './operations.js';
+import { defaultWidgetRegistry } from './registry.js';
+/** Build the assistant adapter for one overview and one principal. */
+export function createOverviewAssistantSurface(options) {
+    const registry = options.registry ?? defaultWidgetRegistry;
+    const { definition } = options;
+    const initial = checkOverviewOverride(definition, options.override, registry);
+    // A stored value the model no longer accepts resolves leniently on load;
+    // its canonical form is whatever survives sanitizing.
+    let current = initial.ok
+        ? initial.override
+        : sanitizedCurrent(definition, registry, options.override);
+    let revision = options.revision;
+    return {
+        pageId: definition.id,
+        canCustomize: options.canCustomize,
+        describe: () => describeOverview({
+            definition,
+            registry,
+            override: current,
+            canCustomize: options.canCustomize,
+            translate: options.translate,
+            maxOperations: options.maxOperations,
+        }),
+        current: () => current,
+        plan: (operations) => planOverviewOperations({
+            definition,
+            registry,
+            override: current,
+            operations,
+            maxOperations: options.maxOperations,
+        }),
+        check: (override) => checkOverviewOverride(definition, override, registry),
+        async persist(override) {
+            const result = await options.persist(override, { revision });
+            if (result.ok) {
+                current = override;
+                if ('revision' in result && result.revision !== undefined) {
+                    revision = result.revision;
+                }
+            }
+            return result;
+        },
+    };
+}
+function sanitizedCurrent(definition, registry, override) {
+    const resolved = resolveOverview(definition, override, registry);
+    return diffOverview(resolved.base, resolved.document);
+}

package/dist/components/overview/assistant.svelte.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The overview assistant in the browser (#3727 phase 4): the structured
+ * operations an in-page assistant (the AssistantDock) applies to a mounted
+ * overview, with a single-step Undo.
+ *
+ * A batch is planned with {@link planOverviewOperations} against the
+ * controller's definition and current override, so it is atomic (one invalid
+ * operation rejects the batch and nothing changes) and can only produce an
+ * override the save endpoint accepts. A valid batch lands through
+ * `controller.restore`, so the grid updates live and the host's `onchange`
+ * persists it like any other edit. The override before the batch is kept for
+ * Undo; Undo restores it exactly, and refuses once the overview changed in
+ * between (it would discard that edit).
+ *
+ * The browser tools (`overview_describe`, `overview_apply`, `overview_undo`)
+ * register on the page's WebMCP registry through `useWebMcpTool`, the same
+ * path every bespoke page tool takes, so the dock offers and runs them like
+ * any other page tool (a `write` waits for the person's Allow unless the host
+ * policy says otherwise). The browser session is the principal: the
+ * controller only holds this viewer's override, and `canCustomize` gates every
+ * apply and undo.
+ */
+import type { Toaster } from '@happyvertical/smrt-ui/feedback';
+import type { WebMcpToolSpec } from '../../web/webmcp.svelte.js';
+import type { OverviewController } from './controller.svelte.js';
+import { type OverviewDescription, type OverviewOperationIssue, type OverviewOperationKind, type OverviewOperationResult } from './operations.js';
+import type { OverviewOverride } from './types.js';
+/** One applied batch, kept for Undo. */
+export interface OverviewAssistantBatch {
+    /** Opaque id; `undo(id)` only undoes this batch. */
+    id: string;
+    results: OverviewOperationResult[];
+    /** How many operations of each kind the batch applied. */
+    counts: Partial<Record<OverviewOperationKind, number>>;
+    /** The override before the batch (what Undo restores). */
+    before: OverviewOverride | null;
+    /** The override the batch produced. */
+    after: OverviewOverride | null;
+}
+export type OverviewAssistantApplyResult = {
+    ok: true;
+    /** `null` when the batch changed nothing (no Undo is offered). */
+    batchId: string | null;
+    results: OverviewOperationResult[];
+} | {
+    ok: false;
+    reason: 'not_allowed' | 'invalid';
+    issues: OverviewOperationIssue[];
+};
+export type OverviewAssistantUndoResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not_allowed' | 'nothing_to_undo' | 'changed_since';
+};
+export interface OverviewAssistantOptions {
+    /**
+     * Tool name prefix (default `overview`): tools are `<prefix>_describe`,
+     * `<prefix>_apply` and `<prefix>_undo`. Give each overview on one page its
+     * own prefix.
+     */
+    toolPrefix?: string;
+    /** Turns widget titles and labels that are i18n keys into text. */
+    translate?: (key: string) => string;
+    /**
+     * Also show each applied batch as a toast with an Undo action (the host
+     * mounts a smrt-ui `ToastViewport` for it). `OverviewAssistantUndo` is the
+     * inline alternative.
+     */
+    toaster?: Toaster;
+    /** Toast and inline message text; receives the batch. */
+    message?: (batch: OverviewAssistantBatch) => string;
+    /** Undo button label (default `Undo`). */
+    undoLabel?: string;
+    /** Called after a batch applies. */
+    onapply?: (batch: OverviewAssistantBatch) => void;
+    /** Batch cap (default 20). */
+    maxOperations?: number;
+}
+export declare class OverviewAssistant {
+    #private;
+    readonly controller: OverviewController;
+    constructor(controller: OverviewController, options?: OverviewAssistantOptions);
+    /** The last applied batch while it can still be undone. */
+    get lastBatch(): OverviewAssistantBatch | null;
+    /** Text for the Undo affordance. */
+    message(batch: OverviewAssistantBatch): string;
+    get undoLabel(): string;
+    /** What the overview allows and shows now. */
+    describe(): OverviewDescription;
+    /** Apply a batch atomically; the grid updates through the controller. */
+    apply(operations: unknown): OverviewAssistantApplyResult;
+    /**
+     * Restore the override from before the last batch. Refused when the
+     * overview changed after that batch (the person edited it), or when `id`
+     * names another batch.
+     */
+    undo(id?: string): OverviewAssistantUndoResult;
+    /** Forget the last batch (hides the Undo affordance). */
+    dismiss(): void;
+    /** The browser tool specs (register with `useOverviewAssistantTools`). */
+    tools(): WebMcpToolSpec[];
+}
+/** Create the browser overview assistant for a controller. */
+export declare function createOverviewAssistant(controller: OverviewController, options?: OverviewAssistantOptions): OverviewAssistant;
+/**
+ * Register the assistant's browser tools on the page's WebMCP registry for
+ * the calling component's lifetime. Call during component initialization.
+ * `apply` and `undo` are `write` tools: the nearest Provider's
+ * `webmcp.effects` must allow `write`, or only `describe` is exposed.
+ */
+export declare function useOverviewAssistantTools(assistant: OverviewAssistant, options?: {
+    effects?: readonly ('read' | 'write' | 'destructive')[];
+}): void;
+//# sourceMappingURL=assistant.svelte.d.ts.map

package/dist/components/overview/assistant.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/assistant.svelte.ts"],"names":[],"mappings":"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"}

package/dist/components/overview/assistant.svelte.js

@@ -0,0 +1,260 @@
+/**
+ * The overview assistant in the browser (#3727 phase 4): the structured
+ * operations an in-page assistant (the AssistantDock) applies to a mounted
+ * overview, with a single-step Undo.
+ *
+ * A batch is planned with {@link planOverviewOperations} against the
+ * controller's definition and current override, so it is atomic (one invalid
+ * operation rejects the batch and nothing changes) and can only produce an
+ * override the save endpoint accepts. A valid batch lands through
+ * `controller.restore`, so the grid updates live and the host's `onchange`
+ * persists it like any other edit. The override before the batch is kept for
+ * Undo; Undo restores it exactly, and refuses once the overview changed in
+ * between (it would discard that edit).
+ *
+ * The browser tools (`overview_describe`, `overview_apply`, `overview_undo`)
+ * register on the page's WebMCP registry through `useWebMcpTool`, the same
+ * path every bespoke page tool takes, so the dock offers and runs them like
+ * any other page tool (a `write` waits for the person's Allow unless the host
+ * policy says otherwise). The browser session is the principal: the
+ * controller only holds this viewer's override, and `canCustomize` gates every
+ * apply and undo.
+ */
+import { useWebMcpTool } from '../../web/webmcp.svelte.js';
+import { describeOverview, OVERVIEW_MAX_OPERATIONS, OVERVIEW_OPERATION_SCHEMA, planOverviewOperations, } from './operations.js';
+const TOOL_PREFIX = /^[a-z][a-z0-9_]{0,40}$/;
+let batchSeq = 0;
+function sameJson(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+function defaultMessage(batch) {
+    void batch;
+    return 'The assistant updated this overview.';
+}
+export class OverviewAssistant {
+    controller;
+    #options;
+    #prefix;
+    #last = $state.raw(null);
+    #toastId = null;
+    constructor(controller, options = {}) {
+        const prefix = options.toolPrefix ?? 'overview';
+        if (!TOOL_PREFIX.test(prefix)) {
+            throw new Error(`createOverviewAssistant: invalid toolPrefix "${prefix}"`);
+        }
+        this.controller = controller;
+        this.#options = options;
+        this.#prefix = prefix;
+    }
+    /** The last applied batch while it can still be undone. */
+    get lastBatch() {
+        return this.#last;
+    }
+    /** Text for the Undo affordance. */
+    message(batch) {
+        return (this.#options.message ?? defaultMessage)(batch);
+    }
+    get undoLabel() {
+        return this.#options.undoLabel ?? 'Undo';
+    }
+    /** What the overview allows and shows now. */
+    describe() {
+        return describeOverview({
+            definition: this.controller.definition,
+            registry: this.controller.registry,
+            override: this.controller.committedOverride,
+            canCustomize: this.controller.canCustomize,
+            translate: this.#options.translate,
+            maxOperations: this.#options.maxOperations,
+        });
+    }
+    /** Apply a batch atomically; the grid updates through the controller. */
+    apply(operations) {
+        const controller = this.controller;
+        if (!controller.canCustomize) {
+            return { ok: false, reason: 'not_allowed', issues: [] };
+        }
+        // What the controller last committed, even if the host has not fed it
+        // back yet.
+        const before = controller.committedOverride;
+        const plan = planOverviewOperations({
+            definition: controller.definition,
+            registry: controller.registry,
+            override: before,
+            operations,
+            maxOperations: this.#options.maxOperations,
+        });
+        if (!plan.ok)
+            return { ok: false, reason: 'invalid', issues: plan.issues };
+        if (plan.unchanged) {
+            return { ok: true, batchId: null, results: plan.results };
+        }
+        const restored = controller.restore(plan.override);
+        if (!restored.ok) {
+            if (restored.reason === 'unchanged') {
+                return { ok: true, batchId: null, results: plan.results };
+            }
+            return { ok: false, reason: 'not_allowed', issues: [] };
+        }
+        const counts = {};
+        for (const result of plan.results) {
+            counts[result.op] = (counts[result.op] ?? 0) + 1;
+        }
+        batchSeq += 1;
+        const batch = {
+            id: `b${batchSeq}`,
+            results: plan.results,
+            counts,
+            before,
+            after: plan.override,
+        };
+        this.#last = batch;
+        this.#showToast(batch);
+        this.#options.onapply?.(batch);
+        return { ok: true, batchId: batch.id, results: plan.results };
+    }
+    /**
+     * Restore the override from before the last batch. Refused when the
+     * overview changed after that batch (the person edited it), or when `id`
+     * names another batch.
+     */
+    undo(id) {
+        const batch = this.#last;
+        if (!batch || (id !== undefined && id !== batch.id)) {
+            return { ok: false, reason: 'nothing_to_undo' };
+        }
+        const controller = this.controller;
+        if (!controller.canCustomize)
+            return { ok: false, reason: 'not_allowed' };
+        if (!sameJson(controller.committedOverride, batch.after)) {
+            this.dismiss();
+            return { ok: false, reason: 'changed_since' };
+        }
+        const restored = controller.restore(batch.before);
+        if (!restored.ok && restored.reason !== 'unchanged') {
+            return { ok: false, reason: 'not_allowed' };
+        }
+        this.dismiss();
+        return { ok: true };
+    }
+    /** Forget the last batch (hides the Undo affordance). */
+    dismiss() {
+        this.#last = null;
+        if (this.#toastId)
+            this.#options.toaster?.dismiss(this.#toastId);
+        this.#toastId = null;
+    }
+    #showToast(batch) {
+        const toaster = this.#options.toaster;
+        if (!toaster)
+            return;
+        if (this.#toastId)
+            toaster.dismiss(this.#toastId);
+        this.#toastId = toaster.show({
+            message: this.message(batch),
+            variant: 'info',
+            duration: 10_000,
+            action: { label: this.undoLabel, run: () => void this.undo(batch.id) },
+        });
+    }
+    /** The browser tool specs (register with `useOverviewAssistantTools`). */
+    tools() {
+        const p = this.#prefix;
+        const json = (value) => JSON.stringify(value);
+        return [
+            {
+                name: `${p}_describe`,
+                description: 'Describe this overview page: the widget types it allows (with their option fields, allowed values and span range) and the widgets it shows now, in order. Call before changing it; never invent types, option keys or models.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                    additionalProperties: false,
+                },
+                annotations: { readOnlyHint: true },
+                execute: () => json(this.describe()),
+            },
+            {
+                name: `${p}_apply`,
+                description: 'Change this overview with a batch of structured operations (add, configure, move, resize, remove). The batch is all-or-nothing: if any operation is invalid nothing changes and the issues are returned to fix. The person can undo the batch.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['operations'],
+                    additionalProperties: false,
+                    properties: {
+                        operations: {
+                            type: 'array',
+                            minItems: 1,
+                            maxItems: this.#options.maxOperations ?? OVERVIEW_MAX_OPERATIONS,
+                            items: OVERVIEW_OPERATION_SCHEMA,
+                        },
+                    },
+                },
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                execute: (args) => {
+                    const result = this.apply(args.operations);
+                    if (result.ok) {
+                        return json({
+                            ok: true,
+                            changed: result.batchId !== null,
+                            undoToken: result.batchId,
+                            applied: result.results,
+                            widgets: this.describe().widgets,
+                        });
+                    }
+                    return json({
+                        ok: false,
+                        error: result.reason === 'not_allowed'
+                            ? 'You may not change this overview.'
+                            : 'The batch was rejected and nothing changed. Fix the listed operations and call again.',
+                        issues: result.issues,
+                    });
+                },
+            },
+            {
+                name: `${p}_undo`,
+                description: 'Undo the last batch you applied to this overview (pass its undoToken). Single step; refused if the overview changed since.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['undoToken'],
+                    additionalProperties: false,
+                    properties: { undoToken: { type: 'string' } },
+                },
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+                execute: (args) => {
+                    const token = typeof args.undoToken === 'string' ? args.undoToken : '';
+                    const result = this.undo(token);
+                    return json(result.ok
+                        ? { ok: true, widgets: this.describe().widgets }
+                        : { ok: false, error: result.reason });
+                },
+            },
+        ];
+    }
+}
+/** Create the browser overview assistant for a controller. */
+export function createOverviewAssistant(controller, options) {
+    return new OverviewAssistant(controller, options);
+}
+/**
+ * Register the assistant's browser tools on the page's WebMCP registry for
+ * the calling component's lifetime. Call during component initialization.
+ * `apply` and `undo` are `write` tools: the nearest Provider's
+ * `webmcp.effects` must allow `write`, or only `describe` is exposed.
+ */
+export function useOverviewAssistantTools(assistant, options = {}) {
+    for (const spec of assistant.tools()) {
+        useWebMcpTool(() => spec, {
+            ...(options.effects ? { effects: options.effects } : {}),
+        });
+    }
+}

package/dist/components/overview/controller.svelte.d.ts

@@ -47,6 +47,14 @@ export declare class OverviewController {
     get base(): OverviewDocument;
     /** The canonical override currently applied; `null` when on defaults. */
     get override(): OverviewOverride | null;
+    /**
+     * The override this controller last committed: {@link override}, or, while
+     * a host-owned getter still answers the value from before the last edit
+     * (the host has not fed it back yet), the value handed to `onchange`. An
+     * Undo compares against this so a pending save is not mistaken for a
+     * change made elsewhere.
+     */
+    get committedOverride(): OverviewOverride | null;
     /** What was dropped or reported while resolving. */
     get issues(): readonly OverviewIssue[];
     /** True when the viewer has changed anything from the defaults. */

package/dist/components/overview/controller.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/controller.svelte.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,sCAAsC;AACtC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,OAAO,GACP,WAAW,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,uEAAuE;IACvE,MAAM,CAAC,EAAE,cAAc,GAAG,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC;IAC7D;;;;OAIG;IACH,UAAU,CAAC,EAAE,CACX,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAUD,qBAAa,kBAAkB;;gBAcjB,OAAO,EAAE,yBAAyB;IAqB9C,IAAI,UAAU,IAAI,kBAAkB,CAEnC;IAED,IAAI,QAAQ,IAAI,cAAc,CAE7B;IAED,wCAAwC;IACxC,IAAI,QAAQ,IAAI,gBAAgB,CAE/B;IAED,8BAA8B;IAC9B,IAAI,IAAI,IAAI,gBAAgB,CAE3B;IAED,yEAAyE;IACzE,IAAI,QAAQ,IAAI,gBAAgB,GAAG,IAAI,CAEtC;IAED,oDAAoD;IACpD,IAAI,MAAM,IAAI,SAAS,aAAa,EAAE,CAErC;IAED,mEAAmE;IACnE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,iDAAiD;IACjD,IAAI,IAAI,IAAI,OAAO,CAGlB;IAED,2EAA2E;IAC3E,IAAI,OAAO,IAAI,gBAAgB,EAAE,CAShC;IAED,oEAAoE;IACpE,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,mBAAmB;IAyClD,8EAA8E;IAC9E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,gBAAgB;IAoClE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB;IAUpC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAWnD,kEAAkE;IAClE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB;IAelD,2EAA2E;IAC3E,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB;IAwBlE,4EAA4E;IAC5E,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB;IAmBzC,sEAAsE;IACtE,KAAK,IAAI,gBAAgB;IAUzB;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB;IAmB5C,+CAA+C;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMxB;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAuDZ,6EAA6E;IAC7E,OAAO,IAAI,IAAI;CAIhB;AAMD,iEAAiE;AACjE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CAEpB"}
+{"version":3,"file":"controller.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/controller.svelte.ts"],"names":[],"mappings":"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"}