@happyvertical/smrt-svelte 0.43.9 → 0.44.0

package/AGENTS.md

@@ -18,13 +18,16 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
 | `src/web/webmcp-provider.ts` | Provider config for generated data/model WebMCP tools: definitions, effect policy, namespace, budget, legacy/canonical filters, and fetcher seams (#2520) | — |
 | `src/web/webmcp-ui.ts` | Fixed, low-cardinality WebMCP adapter over the Provider's mounted form-control and data-surface registries (#2521) | — |
+| `src/web/webmcp.svelte.ts` (`useWebMcpTool`) | Component-owned bespoke WebMCP tool. Routes through `@happyvertical/smrt-web`'s `registerWebMcpBespokeTool`, so it shares the fail-closed effect classification and `effects` exposure policy of generated tools — undeclared `annotations` classify destructive and are excluded by default. `namespace` and `maxTools` never apply to a bespoke tool (#2586) | — |
 
 The composed WebMCP fixture in
 `src/web/__tests__/webmcp-composed.integration.svelte.test.ts` mounts a real
 Provider, rich Form, DataTable/DataSurface, and a bespoke `useWebMcpTool`
 component intent. Preserve its lifecycle assertions: SSR and missing
 `document.modelContext` are no-ops, mounted tools are fixed-cardinality, and
-all registrations abort when their owning component unmounts.
+all registrations abort when their owning component unmounts. It also covers
+an undeclared bespoke tool being excluded under the default read-only policy
+(#2586) — never remove that assertion when editing the fixture.
 
 ## The UI split — primitive-adoption contract (#1589)
 
@@ -68,7 +71,10 @@ human applies or discards them in the form's local review surface. Keep this
 state machine in smrt-ui; smrt-svelte contributes Provider-backed field
 registration and consumes the shared component rather than duplicating it.
 The generated WebMCP form tool proposes registry stages; it never writes or
-submits field values directly.
+submits field values directly. It declares itself write-class (never
+destructive) and, being an explicit `<Form webmcp>` opt-in, falls back to a
+`['read', 'write']` exposure policy only when no ancestor Provider declares an
+explicit `webmcp.effects` — an explicit Provider policy always wins (#2586).
 Rich `FieldDefinition` registrations may carry a `subject` for record-qualified
 identity. The Form bridge also folds live DOM disabled/read-only state into the
 registry and omits those fields from WebMCP schemas and staging.
@@ -115,6 +121,36 @@ adapter for a prefix; configure distinct prefixes for intentional coexistence.
 | `useTTS()` | `speak()`, `stop()`, `isSpeaking`, `getVoices()` |
 | `useLLM()` | `chat()`, `initialize()`, `unload()`, `isGenerating`, `downloadProgress` |
 | `useTheme()` | Theme context from `ThemeProvider` |
+| `useWebMcpTool(factory)` | Registers one imperative browser tool for a component's lifetime (the escape hatch for computed tool sets) |
+| `useViewIntent(intent, { identity })` | Binds a DECLARED view intent (#2588) to a mounted registry identity |
+
+## Declarative view intents (#2588)
+
+`useViewIntent(intent, { identity })` binds an intent declared with
+`defineIntent` in a `.ts` sidecar to this component's mounted registry
+identity — `{ formId, controlId }` for a control intent, `{ surfaceId, kind }`
+for a data-surface one — for exactly the component's lifetime.
+
+- **The contract is not here.** The declaration type, the registry, and the
+  compilation to a browser tool live in `@happyvertical/smrt-web` with no
+  Svelte dependency. This binding is the thin part; a second framework is a
+  binding, not a rewrite. Do not add intent semantics to this package.
+- **Built on `useWebMcpTool`.** Do not write a second WebMCP lifecycle: the
+  synchronous Provider policy read, the `options.effects` fallback, serialized
+  same-name re-registration across effect reruns, and the lazy
+  `@happyvertical/smrt-web` import all come from it. The compiler is imported
+  from `@happyvertical/smrt-web/intents`, the dependency-free entry, so
+  binding an intent never pulls the client-data engine.
+- **Registries come from the nearest Provider's WebMCP UI context**, or from
+  an explicit `controlRegistry`/`dataSurfaceRegistry` override. With neither,
+  it is a silent no-op — an intent with nothing mounted to dispatch to
+  registers nothing. A mismatched `identity` shape THROWS: that is an author
+  error, not an environment difference.
+- **Execution dispatches one registry command as `source: 'agent'`.** Staged
+  review, the trusted local-gesture requirement, sensitivity, and writability
+  all apply unchanged, and there is no path to REST.
+- The six fixed `smrt_ui_*` tools are unchanged by this and must stay so;
+  intents sit above them.
 
 ## AI System
 

package/dist/Provider.svelte

@@ -18,6 +18,7 @@ import type {
 } from './state/app-state.js';
 import { createAppState } from './state/app-state.svelte.js';
 import { setAppStateContext } from './state/context.js';
+import { setWebMcpBespokeContext } from './web/webmcp-bespoke-context.js';
 import type { WebMcpProviderConfig } from './web/webmcp-provider.js';
 import { registerWebMcpUiTools } from './web/webmcp-ui.js';
 import { setWebMcpUiContext } from './web/webmcp-ui-context.js';
@@ -155,6 +156,16 @@ setWebMcpUiContext({
   },
 });
 
+// A descendant's useWebMcpTool() reads this so a bespoke component tool is
+// subject to the same `effects` policy as this Provider's generated tools
+// (#2586), without requiring `webmcp` to be configured at all — absent this
+// Provider, useWebMcpTool falls back to the registrar's own read-only default.
+setWebMcpBespokeContext({
+  get effects() {
+    return webMcpConfig?.effects;
+  },
+});
+
 $effect(() => {
   const currentPreferences = untrack(() => appState.state.session.preferences);
   if (currentPreferences.autoEnableSmrt === autoEnableSmrt) {

package/dist/Provider.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Provider.svelte.d.ts","sourceRoot":"","sources":["../src/Provider.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,YAAY,EACZ,IAAI,EACL,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAKrE,UAAU,KAAK;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;;;;;;OAeG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACxC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAiPD,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"Provider.svelte.d.ts","sourceRoot":"","sources":["../src/Provider.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,YAAY,EACZ,IAAI,EACL,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAKrE,UAAU,KAAK;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;;;;;;OAeG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACxC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AA4PD,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/components/forms/Form.svelte

@@ -55,12 +55,17 @@ export interface Props {
   formId?: string;
   /** Default record-qualified identity for registered fields. */
   subject?: ControlSubject;
+  /** Registry for form control interactions and staged edits. */
   interactionRegistry?: ControlInteractionRegistry;
+  /** Called when a form control interaction event occurs. */
   oninteraction?: (event: ControlInteractionEvent) => void;
   /** Render the built-in human review surface for staged changes. */
   stagedReview?: boolean;
+  /** HTML id attribute for the form element. */
   id?: string;
+  /** HTML name attribute for the form element. */
   name?: string;
+  /** CSS classes to apply to the form element. */
   class?: string;
 }
 
@@ -929,19 +934,30 @@ async function stageForWebMcp(args: Record<string, unknown>): Promise<string> {
     : `Staged ${completed} changes for review; ${rejected} rejected`;
 }
 
-useWebMcpTool(() => {
-  if (!webmcp) return null;
-  const options = typeof webmcp === 'object' ? webmcp : {};
-  return {
-    name: options.name ?? `${collection ?? resolvedFormId}_stage_changes`,
-    description:
-      options.description ??
-      `Propose changes to the ${collection ?? name ?? resolvedFormId} form for local human review`,
-    inputSchema: formInputSchema(),
-    annotations: { readOnlyHint: false },
-    execute: stageForWebMcp,
-  };
-});
+useWebMcpTool(
+  () => {
+    if (!webmcp) return null;
+    const options = typeof webmcp === 'object' ? webmcp : {};
+    return {
+      name: options.name ?? `${collection ?? resolvedFormId}_stage_changes`,
+      description:
+        options.description ??
+        `Propose changes to the ${collection ?? name ?? resolvedFormId} form for local human review`,
+      inputSchema: formInputSchema(),
+      // This tool only ever stages a proposal into local review state — it
+      // never writes or submits data on its own (a human gesture still
+      // applies it) — so it is write-class, not destructive.
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      execute: stageForWebMcp,
+    };
+  },
+  // `<Form webmcp>` is an explicit component-level opt-in, so it supplies
+  // its own `['read', 'write']` fallback for when no Provider ancestor
+  // declares an `effects` policy. A Provider's explicit policy still wins
+  // when present — a narrower Provider policy fails closed over this
+  // default — and this default never includes `destructive`.
+  { effects: ['read', 'write'] },
+);
 
 // Clean up extracted values based on field type
 function cleanValue(value: unknown, fieldType: string): unknown {

package/dist/components/forms/Form.svelte.d.ts

@@ -31,12 +31,17 @@ export interface Props {
     formId?: string;
     /** Default record-qualified identity for registered fields. */
     subject?: ControlSubject;
+    /** Registry for form control interactions and staged edits. */
     interactionRegistry?: ControlInteractionRegistry;
+    /** Called when a form control interaction event occurs. */
     oninteraction?: (event: ControlInteractionEvent) => void;
     /** Render the built-in human review surface for staged changes. */
     stagedReview?: boolean;
+    /** HTML id attribute for the form element. */
     id?: string;
+    /** HTML name attribute for the form element. */
     name?: string;
+    /** CSS classes to apply to the form element. */
     class?: string;
 }
 declare const Form: import("svelte").Component<Props, {

package/dist/components/forms/Form.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Form.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Form.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAG/B,KAAK,cAAc,EAIpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,MAAM,WAAW,KAAK;IACpB,oBAAoB;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB;IACvB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;IACjD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACzD,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA04CD,QAAA,MAAM,IAAI;uBAjFe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;kCAQZ,0BAA0B;MAyEZ,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}
+{"version":3,"file":"Form.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Form.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAG/B,KAAK,cAAc,EAIpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAatC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,MAAM,WAAW,KAAK;IACpB,oBAAoB;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB;IACvB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;IACjD,2DAA2D;IAC3D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACzD,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAq5CD,QAAA,MAAM,IAAI;uBAjFe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;kCAQZ,0BAA0B;MAyEZ,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}