@happyvertical/smrt-web 0.43.10 → 0.44.1

package/dist/webmcp.d.ts

@@ -1,3 +1,48 @@
+/**
+ * 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.
  *
@@ -170,6 +215,181 @@ declare interface SmrtWebToolRouteDescriptor {
     optionsBag?: boolean;
 }
 
+/**
+ * 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.
+ */
+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. */
+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").
+ */
+declare type ViewIntentControlAction = 'focus' | 'reveal' | 'highlight' | 'explain' | 'validate' | 'stage' | 'apply' | 'discard' | 'clear' | 'undo';
+
+/** A mounted control's full registry key, subject included. */
+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.
+ */
+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.
+ */
+declare interface ViewIntentControlTarget {
+    registry: 'control';
+    action: ViewIntentControlAction;
+    formId?: string;
+    controlId?: string;
+}
+
+/** A mounted data surface's full registry key, subject included. */
+declare interface ViewIntentDataSurfaceIdentity {
+    surfaceId: string;
+    kind: ViewIntentDataSurfaceKind;
+    subject?: ViewIntentSubject;
+}
+
+/** Mirrors `DataSurfaceIdentity['kind']` in `@happyvertical/smrt-ui/data`. */
+declare type ViewIntentDataSurfaceKind = 'table' | 'list' | 'report' | 'custom';
+
+/** The `DataSurfaceRegistry` surface an intent uses. */
+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.
+ */
+declare interface ViewIntentDataSurfaceTarget {
+    registry: 'dataSurface';
+    /** The visible-command `controlId` the mounted surface implements. */
+    controlId: string;
+    surfaceId?: string;
+    kind?: ViewIntentDataSurfaceKind;
+}
+
+/**
+ * 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`.
+ */
+declare interface ViewIntentSubject {
+    type: string;
+    id: string;
+    label?: string;
+}
+
+declare type ViewIntentTarget = ViewIntentControlTarget | ViewIntentDataSurfaceTarget;
+
+/**
+ * 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>;
+}
+
+/** 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;
+}
+
 export declare interface WebMcpExposurePolicy {
     /** Allowed effects. Omitted means read-only exposure. */
     effects?: readonly WebMcpToolEffect[];
@@ -211,6 +431,30 @@ 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/webmcp.js

@@ -1,2 +1,2 @@
-import { p as registerWebMcpTools } from "./chunks/src-n14q6RHC.js";
-export { registerWebMcpTools };
+import { h as registerWebMcpTools, m as registerWebMcpBespokeTool, p as registerViewIntent } from "./chunks/src-D1ZtD6Bt.js";
+export { registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-web",
-  "version": "0.43.10",
+  "version": "0.44.1",
   "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
   "author": "HappyVertical",
   "type": "module",
@@ -20,6 +20,10 @@
     "./webmcp": {
       "types": "./dist/webmcp.d.ts",
       "import": "./dist/webmcp.js"
+    },
+    "./intents": {
+      "types": "./dist/intents.d.ts",
+      "import": "./dist/intents.js"
     }
   },
   "dependencies": {
@@ -33,8 +37,8 @@
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-core": "0.43.10",
-    "@happyvertical/smrt-scanner": "0.43.10"
+    "@happyvertical/smrt-core": "0.44.1",
+    "@happyvertical/smrt-scanner": "0.44.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",