@happyvertical/smrt-web 0.43.10 → 0.44.1

package/dist/index.d.ts

@@ -8,6 +8,18 @@
  */
 export declare function buildListQuery(params?: Record<string, unknown>): string;
 
+/**
+ * Compile a declared intent plus a mounted binding into a bespoke tool spec.
+ *
+ * The `execute` this returns is built here from `intent.target`; nothing an
+ * author wrote is called. It dispatches exactly one registry command with
+ * `source: 'agent'`, so every policy the registry enforces — staged review,
+ * local-gesture proof, sensitivity, writability — applies unchanged.
+ *
+ * @throws if the binding does not match the intent's declared target.
+ */
+export declare function compileViewIntentToolSpec(intent: ViewIntent, binding: ViewIntentBinding): ViewIntentToolSpec;
+
 /**
  * Build CRUD fetchers from a generated collection definition — the same URL
  * scheme and payload handling as the generated REST client
@@ -538,6 +550,51 @@ export declare interface PersistCollectionConfig<TData extends object = object>
  */
 export declare function registerDurableResource(namespace: string, resource: DurableResource): () => void;
 
+/**
+ * Register one declared view intent (#2588) against a mounted registry
+ * binding, for as long as the returned disposer is not called.
+ *
+ * This is the ONLY way an intent reaches the browser, and it goes through
+ * {@link registerWebMcpBespokeTool}, so an intent inherits the same
+ * fail-closed `effects` exposure policy as a generated model tool. The
+ * intent's classification was resolved at declaration time by the shared
+ * rule, and the hints `compileViewIntentToolSpec` emits round-trip through
+ * the bespoke registrar's own re-resolution unchanged.
+ *
+ * The `execute` registered here is constructed by
+ * `compileViewIntentToolSpec` from `intent.target`. No author-supplied code
+ * runs, and the only thing it can do is dispatch one browser registry
+ * command — the runtime half of the no-REST invariant.
+ */
+export declare function registerViewIntent(intent: ViewIntent, binding: ViewIntentBinding, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
+
+/**
+ * Register one hand-written browser tool through the same fail-closed effect
+ * classification and `effects` exposure policy as {@link registerWebMcpTools}
+ * (#2586). A tool with no `annotations`, or with annotations that leave its
+ * effect undeclared, classifies destructive/non-idempotent/open-world — the
+ * same default `actionSemantics` gives an undeclared custom model action —
+ * and is excluded unless the policy allows `destructive`. `namespace` and
+ * `maxTools` are out of scope for a bespoke tool; see
+ * {@link RegisterWebMcpBespokeToolOptions}.
+ *
+ * @returns a disposer that deregisters the tool this call registered (a
+ * no-op double-call). On a browser without WebMCP, or when policy excludes
+ * the tool's effect, the call is a no-op and the disposer is inert.
+ */
+export declare function registerWebMcpBespokeTool(spec: WebMcpBespokeToolSpec, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
+
+export declare interface RegisterWebMcpBespokeToolOptions {
+    /**
+     * Allowed effects. Omitted means read-only exposure — the same default as
+     * {@link registerWebMcpTools}. `namespace` and `maxTools` deliberately do
+     * not apply to a bespoke tool (#2586): a component author already chose a
+     * stable name, and counting one intent against a shared budget could make
+     * an unrelated generated tool set fail to register.
+     */
+    effects?: readonly WebMcpToolEffect[];
+}
+
 /**
  * Register every collection's generated tool descriptors with WebMCP.
  *
@@ -1304,6 +1361,245 @@ export declare interface UpdateStateConfig {
 /** Validate that an opaque cache handle came from {@link createSmrtWebClient}. */
 export declare function validateSmrtWebClient(client: SmrtWebClient): void;
 
+/**
+ * A validated, frozen intent.
+ *
+ * `kind: 'intent'` and `id` are the exported identity a `smrt-playbooks`
+ * step reference (`{ kind: 'intent', id }`) names, and this object is
+ * directly assignable to that package's `PlaybookIntentRecord` seam —
+ * `{ id, classification, planes }` — so {@link resolveViewIntent} can be
+ * passed as its `intents` resolver unchanged.
+ */
+export declare interface ViewIntent {
+    readonly kind: 'intent';
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    /** Resolved through the shared fail-closed rule at declaration time. */
+    readonly classification: WebMcpCapabilityClassification;
+    readonly target: ViewIntentTarget;
+    /**
+     * An intent moves mounted browser state, so it is browser-valid only. A
+     * server-side agent reaches one through the #2446 command/ack bridge, which
+     * a playbook must declare explicitly.
+     */
+    readonly planes: readonly ['browser'];
+}
+
+/** The mounted identity a binding supplies for an intent's lifetime. */
+export declare type ViewIntentBinding = {
+    registry: 'control';
+    registryPort: ViewIntentControlRegistryPort;
+    identity: ViewIntentControlIdentity;
+} | {
+    registry: 'dataSurface';
+    registryPort: ViewIntentDataSurfaceRegistryPort;
+    identity: ViewIntentDataSurfaceIdentity;
+};
+
+/**
+ * Control commands a view intent may dispatch. Structurally mirrors
+ * `ControlCommandAction` in `@happyvertical/smrt-ui/forms`; this package
+ * cannot import that one (see AGENTS.md "No inter-smrt dependencies").
+ */
+export declare type ViewIntentControlAction = 'focus' | 'reveal' | 'highlight' | 'explain' | 'validate' | 'stage' | 'apply' | 'discard' | 'clear' | 'undo';
+
+/** A mounted control's full registry key, subject included. */
+export declare interface ViewIntentControlIdentity {
+    formId: string;
+    controlId: string;
+    subject?: ViewIntentSubject;
+}
+
+/**
+ * The `ControlInteractionRegistry` surface an intent uses. Declared
+ * structurally so this package takes no dependency on
+ * `@happyvertical/smrt-ui`; the real registry satisfies it.
+ */
+export declare interface ViewIntentControlRegistryPort {
+    execute(command: {
+        action: ViewIntentControlAction;
+        identity: ViewIntentControlIdentity;
+        value?: unknown;
+        durationMs?: number;
+        revision?: number;
+    }, context?: {
+        source: 'agent';
+    }): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+
+/**
+ * A control-registry target: the intent dispatches exactly one
+ * `ControlInteractionRegistry` command against a mounted control.
+ *
+ * `formId`/`controlId` are the statically declared half of the identity. A
+ * binding supplies the mounted identity and must MATCH anything declared
+ * here — a declaration is authority over a binding, never the other way
+ * round.
+ */
+export declare interface ViewIntentControlTarget {
+    registry: 'control';
+    action: ViewIntentControlAction;
+    formId?: string;
+    controlId?: string;
+}
+
+/** A mounted data surface's full registry key, subject included. */
+export declare interface ViewIntentDataSurfaceIdentity {
+    surfaceId: string;
+    kind: ViewIntentDataSurfaceKind;
+    subject?: ViewIntentSubject;
+}
+
+/** Mirrors `DataSurfaceIdentity['kind']` in `@happyvertical/smrt-ui/data`. */
+export declare type ViewIntentDataSurfaceKind = 'table' | 'list' | 'report' | 'custom';
+
+/** The `DataSurfaceRegistry` surface an intent uses. */
+export declare interface ViewIntentDataSurfaceRegistryPort {
+    inspect(identity: ViewIntentDataSurfaceIdentity): {
+        revision: number;
+    } | undefined;
+    execute(command: {
+        version: 1;
+        commandId: string;
+        identity: ViewIntentDataSurfaceIdentity;
+        expectedRevision: number;
+        controlId: string;
+        payload?: unknown;
+    }): Promise<{
+        ok: boolean;
+        revision?: number;
+        reason?: string;
+    }>;
+}
+
+/**
+ * A data-surface target: the intent dispatches one
+ * `DataSurfaceVisibleCommand` — a browser-visible state transition, never a
+ * server-side query or mutation.
+ */
+export declare interface ViewIntentDataSurfaceTarget {
+    registry: 'dataSurface';
+    /** The visible-command `controlId` the mounted surface implements. */
+    controlId: string;
+    surfaceId?: string;
+    kind?: ViewIntentDataSurfaceKind;
+}
+
+/**
+ * The literal object passed to {@link defineIntent}. Every field is data;
+ * none is a function, a URL, or a route.
+ */
+export declare interface ViewIntentDeclaration {
+    /**
+     * Stable, namespaced identity — at least one dot, lowercase, e.g.
+     * `orders.filter_by_status`. It is the intent's name in the manifest
+     * (#2591) and in a playbook step (`{ kind: 'intent', id }`, #2589), so it
+     * must not be derived from anything that can change (a namespace, a
+     * generated tool name, a route).
+     */
+    id: string;
+    /** Human/agent-readable description. Becomes the tool description. */
+    description: string;
+    /** JSON Schema for the tool's arguments. Must be plain JSON. */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Partial capability declaration resolved by the shared fail-closed rule
+     * (#2587). Omitted entirely, an intent classifies destructive,
+     * non-idempotent, open-world.
+     */
+    capability?: WebMcpCapabilityDeclaration;
+    /** Which registry this compiles into, and what it addresses there. */
+    target: ViewIntentTarget;
+}
+
+/**
+ * The optional record a registry identity is qualified by. Rich forms use it
+ * to tell apart controls that share a `formId`/`controlId` across records.
+ * Structurally mirrors `ControlIdentity['subject']` /
+ * `DataSurfaceIdentity['subject']` in `@happyvertical/smrt-ui`.
+ */
+export declare interface ViewIntentSubject {
+    type: string;
+    id: string;
+    label?: string;
+}
+
+export declare type ViewIntentTarget = ViewIntentControlTarget | ViewIntentDataSurfaceTarget;
+
+/** Derive the WebMCP tool name for an intent id. */
+export declare function viewIntentToolName(id: string): string;
+
+/**
+ * A bespoke tool spec, structurally identical to
+ * `WebMcpBespokeToolSpec` in `./webmcp.js`. Declared here rather than
+ * imported so this module stays free of even a type edge to the registrar
+ * entry.
+ */
+export declare interface ViewIntentToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: WebMcpCapabilityAnnotations;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+
+/**
+ * A hand-written browser tool from application code — not generated from a
+ * `@smrt()` model. Structurally identical to the WebMCP `registerTool` input;
+ * kept as a separate type so this framework-agnostic module never depends on
+ * a UI layer's tool-spec type.
+ */
+export declare interface WebMcpBespokeToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    execute: (args: Record<string, unknown>) => string | Promise<string>;
+}
+
+/** The MCP-shaped annotation set a resolved classification emits. */
+declare interface WebMcpCapabilityAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+    untrustedContentHint: boolean;
+}
+
+/** A fully resolved classification. */
+declare interface WebMcpCapabilityClassification {
+    effect: WebMcpToolEffect;
+    /**
+     * Derived, never declared: every non-read effect is annotated destructive
+     * to the browser, so a `write` capability cannot claim the MCP
+     * additive-only guarantee.
+     */
+    destructive: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+}
+
+/**
+ * An author-supplied, partial classification. Any omitted field resolves
+ * through the fail-closed rule on {@link resolveDeclaredCapability}, never
+ * through a CRUD- or name-based guess.
+ */
+declare interface WebMcpCapabilityDeclaration {
+    effect?: WebMcpToolEffect;
+    idempotent?: boolean;
+    openWorld?: boolean;
+}
+
 export declare interface WebMcpExposurePolicy {
     /** Allowed effects. Omitted means read-only exposure. */
     effects?: readonly WebMcpToolEffect[];
@@ -1345,6 +1641,30 @@ export declare interface WebMcpToolDefinition extends WebToolDescriptor {
     relationships: SmrtWebRelationship[];
 }
 
+/**
+ * The one capability classification rule this package applies, extracted so
+ * every declaration site in smrt-web shares a single implementation (#2587,
+ * #2588).
+ *
+ * Two sites consume it today: `webmcp.ts` (canonical definitions trusted
+ * through it directly, and its legacy CRUD switch's fail-closed default
+ * branch) and `intents.ts` (a declared view intent, which is never a CRUD
+ * verb and so resolves through the declaration rule alone). Keeping the rule
+ * here rather than private to `webmcp.ts` is what lets the intent path be a
+ * dependency-free module that never pulls the client-data engine.
+ *
+ * This module structurally mirrors `CapabilityEffect` / `CapabilityDeclaration`
+ * / `CapabilityClassification` in `@happyvertical/smrt-types` rather than
+ * importing them — this package's dependency-DAG guardrails keep it free of
+ * every `@happyvertical/*` dependency (see AGENTS.md "No inter-smrt
+ * dependencies"), the same reason `data-query.ts` mirrors that package's
+ * bounded query envelope structurally instead of importing it.
+ */
+/**
+ * Browser/agent-visible effect classification for a capability. `'read'`
+ * never mutates; `'write'` mutates within the application; `'destructive'`
+ * may remove or irreversibly change data.
+ */
 export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
 
 /**

package/dist/index.js

@@ -1,2 +1,3 @@
-import { A as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, C as registerDurableResource, D as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, E as MAX_SMRT_WEB_DATA_QUERY_FACETS, F as normalizeSmrtWebDataQueryResult, I as runWrapMutation, M as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, N as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, O as MAX_SMRT_WEB_DATA_QUERY_OFFSET, P as executeSmrtWebDataQuery, S as durableStoreNamespace, T as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, _ as createSmrtWebQuery, a as createSmrtWebClient, b as getOutboxHandle, c as newLocalId, d as unwrapListResult, f as validateSmrtWebClient, g as liveInvalidation, h as createSmrtWebEventSubscriber, i as createSmrtCollection, j as MAX_SMRT_WEB_DATA_QUERY_ROWS, k as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, l as throwIfSmrtWebError, m as createUpdateState, n as buildListQuery, o as getEngineCollection, p as registerWebMcpTools, r as createDefinitionFetchers, s as invalidateSmrtWebCollections, t as SmrtWebRequestError, u as unwrapItemResult, v as DEFAULT_PERSIST_DEBOUNCE_MS, w as wipeDurableStore, x as offlineOutbox, y as persistCollection } from "./chunks/src-n14q6RHC.js";
-export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, invalidateSmrtWebCollections, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, throwIfSmrtWebError, unwrapItemResult, unwrapListResult, validateSmrtWebClient, wipeDurableStore };
+import { A as MAX_SMRT_WEB_DATA_QUERY_OFFSET, C as offlineOutbox, D as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, E as wipeDurableStore, F as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, I as executeSmrtWebDataQuery, L as normalizeSmrtWebDataQueryResult, M as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, N as MAX_SMRT_WEB_DATA_QUERY_ROWS, O as MAX_SMRT_WEB_DATA_QUERY_FACETS, P as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, R as runWrapMutation, S as getOutboxHandle, T as registerDurableResource, _ as createSmrtWebEventSubscriber, a as createSmrtWebClient, b as DEFAULT_PERSIST_DEBOUNCE_MS, c as newLocalId, d as unwrapListResult, f as validateSmrtWebClient, g as createUpdateState, h as registerWebMcpTools, i as createSmrtCollection, j as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, k as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, l as throwIfSmrtWebError, m as registerWebMcpBespokeTool, n as buildListQuery, o as getEngineCollection, p as registerViewIntent, r as createDefinitionFetchers, s as invalidateSmrtWebCollections, t as SmrtWebRequestError, u as unwrapItemResult, v as liveInvalidation, w as durableStoreNamespace, x as persistCollection, y as createSmrtWebQuery } from "./chunks/src-D1ZtD6Bt.js";
+import { n as compileViewIntentToolSpec, o as viewIntentToolName } from "./chunks/intents-BUTyN7YQ.js";
+export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, compileViewIntentToolSpec, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, invalidateSmrtWebCollections, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools, runWrapMutation, throwIfSmrtWebError, unwrapItemResult, unwrapListResult, validateSmrtWebClient, viewIntentToolName, wipeDurableStore };

package/dist/intents.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Drop every declared intent. For tests and HMR teardown; production code
+ * has no reason to call it.
+ */
+export declare function clearViewIntentRegistry(): void;
+
+/**
+ * Compile a declared intent plus a mounted binding into a bespoke tool spec.
+ *
+ * The `execute` this returns is built here from `intent.target`; nothing an
+ * author wrote is called. It dispatches exactly one registry command with
+ * `source: 'agent'`, so every policy the registry enforces — staged review,
+ * local-gesture proof, sensitivity, writability — applies unchanged.
+ *
+ * @throws if the binding does not match the intent's declared target.
+ */
+export declare function compileViewIntentToolSpec(intent: ViewIntent, binding: ViewIntentBinding): ViewIntentToolSpec;
+
+/**
+ * Declare a view intent.
+ *
+ * Call this at MODULE SCOPE with a single object literal — no spreads, no
+ * conditionals, no computed values — in a `.ts` module, conventionally a
+ * `Foo.intents.ts` sidecar beside the component that binds it. That form is
+ * the contract #2591's scanner matcher reads without evaluating the module.
+ *
+ * The returned intent is deeply frozen and registered under its `id`. A
+ * byte-identical re-declaration returns the SAME frozen object. A
+ * re-declaration that differs REPLACES the previous one and warns: editing a
+ * sidecar is what an HMR update is for, and throwing there would break the
+ * single most common dev action on these files. Two genuinely different
+ * intents sharing an id is an authoring mistake the warning surfaces, and one
+ * #2591's scanner catches statically, where both declarations are visible at
+ * once.
+ *
+ * @throws if the declaration is not static JSON data, carries an unknown
+ * key, carries a function anywhere, names a reserved tool namespace, or
+ * derives a WebMCP tool name another intent already derives.
+ */
+export declare function defineIntent(declaration: ViewIntentDeclaration): ViewIntent;
+
+/** Every intent declared in modules loaded so far, in declaration order. */
+export declare function listViewIntents(): readonly ViewIntent[];
+
+/**
+ * Look up a declared intent by id.
+ *
+ * Directly usable as `smrt-playbooks`' `PlaybookIntentResolver` seam (#2589):
+ * a {@link ViewIntent} satisfies its `PlaybookIntentRecord` shape, so an
+ * intent step inherits this intent's classification and browser-only plane
+ * validity rather than classifying itself.
+ */
+export declare function resolveViewIntent(id: string): ViewIntent | undefined;
+
+/**
+ * A validated, frozen intent.
+ *
+ * `kind: 'intent'` and `id` are the exported identity a `smrt-playbooks`
+ * step reference (`{ kind: 'intent', id }`) names, and this object is
+ * directly assignable to that package's `PlaybookIntentRecord` seam —
+ * `{ id, classification, planes }` — so {@link resolveViewIntent} can be
+ * passed as its `intents` resolver unchanged.
+ */
+export declare interface ViewIntent {
+    readonly kind: 'intent';
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    /** Resolved through the shared fail-closed rule at declaration time. */
+    readonly classification: WebMcpCapabilityClassification;
+    readonly target: ViewIntentTarget;
+    /**
+     * An intent moves mounted browser state, so it is browser-valid only. A
+     * server-side agent reaches one through the #2446 command/ack bridge, which
+     * a playbook must declare explicitly.
+     */
+    readonly planes: readonly ['browser'];
+}
+
+/** The mounted identity a binding supplies for an intent's lifetime. */
+export declare type ViewIntentBinding = {
+    registry: 'control';
+    registryPort: ViewIntentControlRegistryPort;
+    identity: ViewIntentControlIdentity;
+} | {
+    registry: 'dataSurface';
+    registryPort: ViewIntentDataSurfaceRegistryPort;
+    identity: ViewIntentDataSurfaceIdentity;
+};
+
+/**
+ * Control commands a view intent may dispatch. Structurally mirrors
+ * `ControlCommandAction` in `@happyvertical/smrt-ui/forms`; this package
+ * cannot import that one (see AGENTS.md "No inter-smrt dependencies").
+ */
+export declare type ViewIntentControlAction = 'focus' | 'reveal' | 'highlight' | 'explain' | 'validate' | 'stage' | 'apply' | 'discard' | 'clear' | 'undo';
+
+/** A mounted control's full registry key, subject included. */
+export declare interface ViewIntentControlIdentity {
+    formId: string;
+    controlId: string;
+    subject?: ViewIntentSubject;
+}
+
+/**
+ * The `ControlInteractionRegistry` surface an intent uses. Declared
+ * structurally so this package takes no dependency on
+ * `@happyvertical/smrt-ui`; the real registry satisfies it.
+ */
+export declare interface ViewIntentControlRegistryPort {
+    execute(command: {
+        action: ViewIntentControlAction;
+        identity: ViewIntentControlIdentity;
+        value?: unknown;
+        durationMs?: number;
+        revision?: number;
+    }, context?: {
+        source: 'agent';
+    }): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+
+/**
+ * A control-registry target: the intent dispatches exactly one
+ * `ControlInteractionRegistry` command against a mounted control.
+ *
+ * `formId`/`controlId` are the statically declared half of the identity. A
+ * binding supplies the mounted identity and must MATCH anything declared
+ * here — a declaration is authority over a binding, never the other way
+ * round.
+ */
+export declare interface ViewIntentControlTarget {
+    registry: 'control';
+    action: ViewIntentControlAction;
+    formId?: string;
+    controlId?: string;
+}
+
+/** A mounted data surface's full registry key, subject included. */
+export declare interface ViewIntentDataSurfaceIdentity {
+    surfaceId: string;
+    kind: ViewIntentDataSurfaceKind;
+    subject?: ViewIntentSubject;
+}
+
+/** Mirrors `DataSurfaceIdentity['kind']` in `@happyvertical/smrt-ui/data`. */
+export declare type ViewIntentDataSurfaceKind = 'table' | 'list' | 'report' | 'custom';
+
+/** The `DataSurfaceRegistry` surface an intent uses. */
+export declare interface ViewIntentDataSurfaceRegistryPort {
+    inspect(identity: ViewIntentDataSurfaceIdentity): {
+        revision: number;
+    } | undefined;
+    execute(command: {
+        version: 1;
+        commandId: string;
+        identity: ViewIntentDataSurfaceIdentity;
+        expectedRevision: number;
+        controlId: string;
+        payload?: unknown;
+    }): Promise<{
+        ok: boolean;
+        revision?: number;
+        reason?: string;
+    }>;
+}
+
+/**
+ * A data-surface target: the intent dispatches one
+ * `DataSurfaceVisibleCommand` — a browser-visible state transition, never a
+ * server-side query or mutation.
+ */
+export declare interface ViewIntentDataSurfaceTarget {
+    registry: 'dataSurface';
+    /** The visible-command `controlId` the mounted surface implements. */
+    controlId: string;
+    surfaceId?: string;
+    kind?: ViewIntentDataSurfaceKind;
+}
+
+/**
+ * The literal object passed to {@link defineIntent}. Every field is data;
+ * none is a function, a URL, or a route.
+ */
+export declare interface ViewIntentDeclaration {
+    /**
+     * Stable, namespaced identity — at least one dot, lowercase, e.g.
+     * `orders.filter_by_status`. It is the intent's name in the manifest
+     * (#2591) and in a playbook step (`{ kind: 'intent', id }`, #2589), so it
+     * must not be derived from anything that can change (a namespace, a
+     * generated tool name, a route).
+     */
+    id: string;
+    /** Human/agent-readable description. Becomes the tool description. */
+    description: string;
+    /** JSON Schema for the tool's arguments. Must be plain JSON. */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Partial capability declaration resolved by the shared fail-closed rule
+     * (#2587). Omitted entirely, an intent classifies destructive,
+     * non-idempotent, open-world.
+     */
+    capability?: WebMcpCapabilityDeclaration;
+    /** Which registry this compiles into, and what it addresses there. */
+    target: ViewIntentTarget;
+}
+
+/**
+ * The optional record a registry identity is qualified by. Rich forms use it
+ * to tell apart controls that share a `formId`/`controlId` across records.
+ * Structurally mirrors `ControlIdentity['subject']` /
+ * `DataSurfaceIdentity['subject']` in `@happyvertical/smrt-ui`.
+ */
+export declare interface ViewIntentSubject {
+    type: string;
+    id: string;
+    label?: string;
+}
+
+export declare type ViewIntentTarget = ViewIntentControlTarget | ViewIntentDataSurfaceTarget;
+
+/** Derive the WebMCP tool name for an intent id. */
+export declare function viewIntentToolName(id: string): string;
+
+/**
+ * A bespoke tool spec, structurally identical to
+ * `WebMcpBespokeToolSpec` in `./webmcp.js`. Declared here rather than
+ * imported so this module stays free of even a type edge to the registrar
+ * entry.
+ */
+export declare interface ViewIntentToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: WebMcpCapabilityAnnotations;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+
+/** The MCP-shaped annotation set a resolved classification emits. */
+declare interface WebMcpCapabilityAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+    untrustedContentHint: boolean;
+}
+
+/** A fully resolved classification. */
+declare interface WebMcpCapabilityClassification {
+    effect: WebMcpToolEffect;
+    /**
+     * Derived, never declared: every non-read effect is annotated destructive
+     * to the browser, so a `write` capability cannot claim the MCP
+     * additive-only guarantee.
+     */
+    destructive: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+}
+
+/**
+ * An author-supplied, partial classification. Any omitted field resolves
+ * through the fail-closed rule on {@link resolveDeclaredCapability}, never
+ * through a CRUD- or name-based guess.
+ */
+declare interface WebMcpCapabilityDeclaration {
+    effect?: WebMcpToolEffect;
+    idempotent?: boolean;
+    openWorld?: boolean;
+}
+
+/**
+ * The one capability classification rule this package applies, extracted so
+ * every declaration site in smrt-web shares a single implementation (#2587,
+ * #2588).
+ *
+ * Two sites consume it today: `webmcp.ts` (canonical definitions trusted
+ * through it directly, and its legacy CRUD switch's fail-closed default
+ * branch) and `intents.ts` (a declared view intent, which is never a CRUD
+ * verb and so resolves through the declaration rule alone). Keeping the rule
+ * here rather than private to `webmcp.ts` is what lets the intent path be a
+ * dependency-free module that never pulls the client-data engine.
+ *
+ * This module structurally mirrors `CapabilityEffect` / `CapabilityDeclaration`
+ * / `CapabilityClassification` in `@happyvertical/smrt-types` rather than
+ * importing them — this package's dependency-DAG guardrails keep it free of
+ * every `@happyvertical/*` dependency (see AGENTS.md "No inter-smrt
+ * dependencies"), the same reason `data-query.ts` mirrors that package's
+ * bounded query envelope structurally instead of importing it.
+ */
+/**
+ * Browser/agent-visible effect classification for a capability. `'read'`
+ * never mutates; `'write'` mutates within the application; `'destructive'`
+ * may remove or irreversibly change data.
+ */
+declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
+
+export { }

package/dist/intents.js

@@ -0,0 +1,2 @@
+import { a as resolveViewIntent, i as listViewIntents, n as compileViewIntentToolSpec, o as viewIntentToolName, r as defineIntent, t as clearViewIntentRegistry } from "./chunks/intents-BUTyN7YQ.js";
+export { clearViewIntentRegistry, compileViewIntentToolSpec, defineIntent, listViewIntents, resolveViewIntent, viewIntentToolName };