@happyvertical/smrt-svelte 0.51.39 → 0.52.0

package/dist/components/forms/Form.svelte

@@ -6,13 +6,16 @@ import {
   type ControlKind,
   type ControlRuntimeState,
   type ControlSubject,
+  controlProposalProperties,
   createControlInteractionRegistry,
   StagedControlReview,
   setControlInteractionContext,
+  stageControlProposals,
 } from '@happyvertical/smrt-ui/forms';
 import { useI18n } from '@happyvertical/smrt-ui/i18n';
 import type { Snippet } from 'svelte';
 import { onDestroy, untrack } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
 import { useAppState } from '../../hooks/useAppState.svelte.js';
 import { useSTT } from '../../hooks/useSTT.svelte.js';
 import { M } from '../../i18n/strings.forms.js';
@@ -28,7 +31,20 @@ import type { LLMModelId, STTAdapterType } from './types.js';
 
 const { t } = useI18n();
 
-export interface Props {
+/**
+ * A SvelteKit-style form action: `enhance` from `$app/forms` fits as-is, or
+ * wrap it to pass a submit function (`(form) => enhance(form, submit)`).
+ */
+export type FormEnhance = (
+  form: HTMLFormElement,
+  // biome-ignore lint/suspicious/noConfusingVoidType: an action may return nothing, like Svelte's own Action type.
+) => void | { destroy?: () => void };
+
+export interface Props
+  extends Omit<
+    HTMLFormAttributes,
+    'children' | 'class' | 'id' | 'name' | 'method' | 'action' | 'onsubmit'
+  > {
   /** Form children */
   children: Snippet;
   /** Show mode toggle button */
@@ -48,7 +64,7 @@ export interface Props {
   /** Collection/model identity used when naming the generated intent. */
   collection?: string;
   /** HTTP method for native form submission (default: GET) */
-  method?: 'GET' | 'POST';
+  method?: 'GET' | 'POST' | 'get' | 'post' | 'dialog';
   /** Form action URL for native form submission */
   action?: string;
   /** Stable identity used by control/agent interaction adapters. */
@@ -67,6 +83,14 @@ export interface Props {
   name?: string;
   /** CSS classes to apply to the form element. */
   class?: string;
+  /**
+   * Progressive-enhancement action applied to the rendered `<form>` — pass
+   * SvelteKit's `enhance` (`<Form enhance={enhance}>`). A component cannot
+   * take `use:`, so this is the `use:enhance` equivalent; attachments
+   * (`{@attach …}`) and every other native form attribute (`enctype`,
+   * `novalidate`, `aria-*`, `data-*`, `autocomplete`, …) pass straight through.
+   */
+  enhance?: FormEnhance;
 }
 
 const {
@@ -89,8 +113,27 @@ const {
   id,
   name,
   class: className = '',
+  enhance,
+  ...formAttributes
 }: Props = $props();
 
+/** Apply the consumer's `enhance` action; re-run it when the action changes. */
+function applyEnhance(form: HTMLFormElement, initial: FormEnhance | undefined) {
+  let current = initial;
+  let handle = current?.(form);
+  return {
+    update(next: FormEnhance | undefined) {
+      if (next === current) return;
+      if (handle) handle.destroy?.();
+      current = next;
+      handle = current?.(form);
+    },
+    destroy() {
+      if (handle) handle.destroy?.();
+    },
+  };
+}
+
 const app = useAppState();
 const stt = useSTT();
 const instanceId = $props.id();
@@ -291,7 +334,25 @@ function recordDirectUserEdit(event: Event) {
       target as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement,
     ),
   );
-  if (!field) return;
+  if (!field) {
+    // A smrt-ui primitive (Input, Select, Combobox, …) registered itself
+    // through the control context; its element carries the address.
+    const control = target.closest<HTMLElement>('[data-smrt-control]');
+    const controlId = control?.dataset.smrtControl;
+    if (!control || !controlId) return;
+    resolvedInteractionRegistry.recordUserEdit?.({
+      formId: resolvedFormId,
+      controlId,
+      subject:
+        control.dataset.smrtSubjectType && control.dataset.smrtSubjectId
+          ? {
+              type: control.dataset.smrtSubjectType,
+              id: control.dataset.smrtSubjectId,
+            }
+          : undefined,
+    });
+    return;
+  }
   resolvedInteractionRegistry.recordUserEdit?.({
     formId: resolvedFormId,
     controlId: field.controlId ?? field.name,
@@ -812,6 +873,16 @@ function prepareInteractionValue(field: FieldDefinition, value: unknown) {
   return field.prepareValue ? field.prepareValue(preparedValue) : preparedValue;
 }
 
+/** Registry control ids owned by fields registered through this Form. */
+function richFieldControlIds(): Set<string> {
+  const ids = new Set<string>();
+  for (const field of fields.values()) {
+    ids.add(field.controlId ?? field.name);
+    ids.add(field.name);
+  }
+  return ids;
+}
+
 function formInputSchema(): Record<string, unknown> {
   void interactionRegistryRevision;
   const properties: Record<string, unknown> = {};
@@ -830,6 +901,17 @@ function formInputSchema(): Record<string, unknown> {
     if (field.constraints?.required) required.push(field.name);
   }
 
+  // Every other control mounted in this form — smrt-ui primitives
+  // (FormGroup + Input/Select/Textarea/Combobox/…) and composites registered
+  // through useControlRegistration — proposes through the same tool.
+  for (const [controlId, schema] of Object.entries(
+    controlProposalProperties(resolvedInteractionRegistry, resolvedFormId, {
+      exclude: richFieldControlIds(),
+    }),
+  )) {
+    if (!Object.hasOwn(properties, controlId)) properties[controlId] = schema;
+  }
+
   return {
     type: 'object',
     additionalProperties: false,
@@ -879,7 +961,23 @@ async function submitCurrentForm(): Promise<string> {
 }
 
 async function stageForWebMcp(args: Record<string, unknown>): Promise<string> {
-  const commands = Object.entries(args).flatMap(([name, value]) => {
+  const richArgs: Record<string, unknown> = {};
+  const controlArgs: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args ?? {})) {
+    if (fields.has(key)) richArgs[key] = value;
+    else controlArgs[key] = value;
+  }
+  const controlResult =
+    Object.keys(controlArgs).length > 0
+      ? await stageControlProposals(
+          resolvedInteractionRegistry,
+          resolvedFormId,
+          controlArgs,
+          { source: 'agent', actorId: 'webmcp' },
+          { exclude: richFieldControlIds() },
+        )
+      : undefined;
+  const commands = Object.entries(richArgs).flatMap(([name, value]) => {
     const field = fields.get(name);
     const state = field ? fieldRuntimeState(field) : undefined;
     if (
@@ -914,11 +1012,17 @@ async function stageForWebMcp(args: Record<string, unknown>): Promise<string> {
       },
     ];
   });
-  if (commands.length === 0) return 'No reviewable changes provided';
+  const controlStaged = controlResult?.staged ?? 0;
+  const controlRejected = controlResult?.rejected.length ?? 0;
+  if (commands.length === 0 && controlStaged + controlRejected === 0) {
+    return 'No reviewable changes provided';
+  }
 
   const context = { source: 'agent' as const, actorId: 'webmcp' };
   let batch;
-  if (resolvedInteractionRegistry.executeBatch) {
+  if (commands.length === 0) {
+    batch = { ok: true, results: [] };
+  } else if (resolvedInteractionRegistry.executeBatch) {
     batch = await resolvedInteractionRegistry.executeBatch(commands, context);
   } else {
     const results = [];
@@ -927,8 +1031,12 @@ async function stageForWebMcp(args: Record<string, unknown>): Promise<string> {
     }
     batch = { ok: results.every((result) => result.ok), results };
   }
-  const completed = batch.results.filter((result) => result.ok).length;
-  const rejected = batch.results.length - completed;
+  const completed =
+    batch.results.filter((result) => result.ok).length + controlStaged;
+  const rejected =
+    batch.results.length -
+    batch.results.filter((result) => result.ok).length +
+    controlRejected;
   return rejected === 0
     ? `Staged ${completed} change${completed === 1 ? '' : 's'} for review`
     : `Staged ${completed} changes for review; ${rejected} rejected`;
@@ -1412,6 +1520,7 @@ export function getInteractionRegistry(): ControlInteractionRegistry {
 </script>
 
 <form
+  {...formAttributes}
   bind:this={formElement}
   {id}
   {name}
@@ -1420,6 +1529,7 @@ export function getInteractionRegistry(): ControlInteractionRegistry {
   onsubmit={handleSubmit}
   {method}
   {action}
+  use:applyEnhance={enhance}
 >
   <!--
     Screen-reader status region (L1 #1420): announces async STT / field-

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

@@ -1,7 +1,15 @@
 import { type ControlInteractionEvent, type ControlInteractionRegistry, type ControlSubject } from '@happyvertical/smrt-ui/forms';
 import type { Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
 import type { LLMModelId, STTAdapterType } from './types.js';
-export interface Props {
+/**
+ * A SvelteKit-style form action: `enhance` from `$app/forms` fits as-is, or
+ * wrap it to pass a submit function (`(form) => enhance(form, submit)`).
+ */
+export type FormEnhance = (form: HTMLFormElement) => void | {
+    destroy?: () => void;
+};
+export interface Props extends Omit<HTMLFormAttributes, 'children' | 'class' | 'id' | 'name' | 'method' | 'action' | 'onsubmit'> {
     /** Form children */
     children: Snippet;
     /** Show mode toggle button */
@@ -24,7 +32,7 @@ export interface Props {
     /** Collection/model identity used when naming the generated intent. */
     collection?: string;
     /** HTTP method for native form submission (default: GET) */
-    method?: 'GET' | 'POST';
+    method?: 'GET' | 'POST' | 'get' | 'post' | 'dialog';
     /** Form action URL for native form submission */
     action?: string;
     /** Stable identity used by control/agent interaction adapters. */
@@ -43,6 +51,14 @@ export interface Props {
     name?: string;
     /** CSS classes to apply to the form element. */
     class?: string;
+    /**
+     * Progressive-enhancement action applied to the rendered `<form>` — pass
+     * SvelteKit's `enhance` (`<Form enhance={enhance}>`). A component cannot
+     * take `use:`, so this is the `use:enhance` equivalent; attachments
+     * (`{@attach …}`) and every other native form attribute (`enctype`,
+     * `novalidate`, `aria-*`, `data-*`, `autocomplete`, …) pass straight through.
+     */
+    enhance?: FormEnhance;
 }
 declare const Form: import("svelte").Component<Props, {
     getFormData: () => Record<string, unknown>;

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,+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"}
+{"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,EAMpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAY1D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,eAAe,KAElB,IAAI,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAErC,MAAM,WAAW,KACf,SAAQ,IAAI,CACV,kBAAkB,EAClB,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CACxE;IACD,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,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpD,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;IACf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AA2+CD,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"}

package/dist/components/forms/FormScope.svelte

@@ -0,0 +1,202 @@
+<!--
+  FormScope — makes the fields inside it readable and proposable by agents
+  without rendering a `<form>`.
+
+  Use the rich `<Form webmcp>` when the page has a form: it now passes every
+  native attribute and SvelteKit's `enhance` through. FormScope is for the
+  cases a `<form>` element does not fit — a fetch-driven wizard whose buttons
+  are `type="button"`, an editor made of several independently saved parts,
+  or a page that must keep its own `<form>` markup (scoped `form.x` styles).
+
+    <FormScope formId="new-site" purpose="Start a new town site">
+      <FormGroup label="Site name" id="site-name"><Input name="name" bind:value={name} /></FormGroup>
+    </FormScope>
+
+  Inside, smrt-ui primitives (FormGroup + Input/Select/Textarea/Combobox/…)
+  and composites registered through `useControlRegistration` join the nearest
+  `<Provider webmcp>` control registry (or a local one), and — with `webmcp`
+  (default on) and at least one proposable control — one
+  `<formId>_stage_changes` tool lets an agent PROPOSE values. Proposals show
+  in the staged-review panel; a person applies them. Nothing is saved or
+  submitted by an agent.
+-->
+<script lang="ts">
+import {
+  type ControlInteractionRegistry,
+  controlProposalInputSchema,
+  controlProposalToolName,
+  createControlInteractionRegistry,
+  StagedControlReview,
+  setControlInteractionContext,
+  stageControlProposals,
+} from '@happyvertical/smrt-ui/forms';
+import type { Snippet } from 'svelte';
+import { untrack } from 'svelte';
+import { useWebMcpTool } from '../../web/webmcp.svelte.js';
+import { tryGetWebMcpUiContext } from '../../web/webmcp-ui-context.js';
+
+export interface Props {
+  /** Stable, page-unique form identity (also names the WebMCP tool). */
+  formId: string;
+  /** Plain-language name of what the form does, for the tool description. */
+  purpose?: string;
+  /** Register the `<formId>_stage_changes` proposal tool (default true). */
+  webmcp?: boolean | { name?: string; description?: string };
+  /** Override the registry (tests, nested hosts). */
+  interactionRegistry?: ControlInteractionRegistry;
+  /** Show the staged-review summary for agent proposals (default true). */
+  stagedReview?: boolean;
+  children: Snippet;
+}
+
+const {
+  formId,
+  purpose,
+  webmcp = true,
+  interactionRegistry,
+  stagedReview = true,
+  children,
+}: Props = $props();
+
+const providerUi = tryGetWebMcpUiContext();
+const localRegistry = createControlInteractionRegistry();
+const registry = $derived(
+  interactionRegistry ??
+    (providerUi?.enabled ? providerUi.controlRegistry : undefined) ??
+    localRegistry,
+);
+
+setControlInteractionContext({
+  get formId() {
+    return formId;
+  },
+  get registry() {
+    return registry;
+  },
+});
+
+let scope = $state<HTMLDivElement | null>(null);
+let formElement = $state<HTMLFormElement | null>(null);
+$effect(() => {
+  if (!scope) return;
+  const element = scope;
+  const find = () => {
+    formElement = element.querySelector('form');
+  };
+  find();
+  // A form can appear after mount ({#if} around it); keep the reference current.
+  const observer = new MutationObserver(find);
+  observer.observe(element, { childList: true, subtree: true });
+  return () => observer.disconnect();
+});
+
+// Record trusted human edits so a staged proposal goes stale when the person
+// types over it (the same contract as the base and rich Form).
+function recordDirectUserEdit(event: Event) {
+  if (!event.isTrusted) return;
+  const target = event.target;
+  if (!(target instanceof Element)) return;
+  const control = target.closest<HTMLElement>('[data-smrt-control]');
+  const controlId = control?.dataset.smrtControl;
+  if (!control || !controlId) return;
+  registry.recordUserEdit?.({
+    formId,
+    controlId,
+    subject:
+      control.dataset.smrtSubjectType && control.dataset.smrtSubjectId
+        ? {
+            type: control.dataset.smrtSubjectType,
+            id: control.dataset.smrtSubjectId,
+          }
+        : undefined,
+  });
+}
+
+$effect(() => {
+  const element = scope;
+  if (!element) return;
+  element.addEventListener('input', recordDirectUserEdit);
+  element.addEventListener('change', recordDirectUserEdit);
+  return () => {
+    element.removeEventListener('input', recordDirectUserEdit);
+    element.removeEventListener('change', recordDirectUserEdit);
+  };
+});
+
+// The registry is not reactive; bump a counter on registration changes so
+// the tool's schema follows controls as they mount, unmount, or disable.
+let registryRevision = $state(0);
+$effect(() => {
+  const currentFormId = formId;
+  return registry.subscribe((event) => {
+    if (event.identity.formId !== currentFormId) return;
+    if (
+      event.type === 'registered' ||
+      event.type === 'unregistered' ||
+      event.type === 'refreshed'
+    ) {
+      registryRevision = untrack(() => registryRevision) + 1;
+    }
+  });
+});
+
+useWebMcpTool(
+  () => {
+    if (!webmcp) return null;
+    void registryRevision;
+    const options = typeof webmcp === 'object' ? webmcp : {};
+    const currentRegistry = registry;
+    const currentFormId = formId;
+    const inputSchema = controlProposalInputSchema(
+      currentRegistry,
+      currentFormId,
+    );
+    // Nothing an agent could fill (yet): no tool, rather than an empty one.
+    if (Object.keys(inputSchema.properties as object).length === 0) return null;
+    return {
+      name: options.name ?? controlProposalToolName(currentFormId),
+      description:
+        options.description ??
+        `Propose values for the "${purpose ?? currentFormId}" form. The person reviews and applies them; nothing is saved or submitted.`,
+      inputSchema,
+      // Stages proposals only: write-class, never destructive.
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      execute: async (args) => {
+        const result = await stageControlProposals(
+          currentRegistry,
+          currentFormId,
+          (args ?? {}) as Record<string, unknown>,
+          { source: 'agent', actorId: 'assistant' },
+        );
+        return JSON.stringify({
+          ...result,
+          message:
+            result.staged > 0
+              ? 'Proposed changes are waiting for the person to review and apply them. Nothing was saved or submitted.'
+              : 'No reviewable changes provided',
+        });
+      },
+    };
+  },
+  // Same fallback as `<Form webmcp>`: used only when no Provider declares an
+  // explicit `webmcp.effects` policy.
+  { effects: ['read', 'write'] },
+);
+</script>
+
+<div class="smrt-form-scope" data-smrt-form-scope={formId} bind:this={scope}>
+  {@render children()}
+  <StagedControlReview {registry} {formId} {formElement} summary={stagedReview} />
+</div>
+
+<style>
+  /* Layout-neutral: the wrapped content lays out exactly as before. */
+  .smrt-form-scope {
+    display: contents;
+  }
+</style>

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

@@ -0,0 +1,22 @@
+import { type ControlInteractionRegistry } from '@happyvertical/smrt-ui/forms';
+import type { Snippet } from 'svelte';
+export interface Props {
+    /** Stable, page-unique form identity (also names the WebMCP tool). */
+    formId: string;
+    /** Plain-language name of what the form does, for the tool description. */
+    purpose?: string;
+    /** Register the `<formId>_stage_changes` proposal tool (default true). */
+    webmcp?: boolean | {
+        name?: string;
+        description?: string;
+    };
+    /** Override the registry (tests, nested hosts). */
+    interactionRegistry?: ControlInteractionRegistry;
+    /** Show the staged-review summary for agent proposals (default true). */
+    stagedReview?: boolean;
+    children: Snippet;
+}
+declare const FormScope: import("svelte").Component<Props, {}, "">;
+type FormScope = ReturnType<typeof FormScope>;
+export default FormScope;
+//# sourceMappingURL=FormScope.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormScope.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/FormScope.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,0BAA0B,EAOhC,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAMtC,MAAM,WAAW,KAAK;IACpB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,0BAA0B,CAAC;IACjD,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA+JD,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/components/forms/__tests__/Form.ui-controls.test.js

@@ -0,0 +1,119 @@
+import { createControlInteractionRegistry } from '@happyvertical/smrt-ui/forms';
+import { render, screen, waitFor } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { tick } from 'svelte';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+vi.mock('../../../hooks/useAppState.svelte.js', () => ({
+    useAppState: () => ({ state: { mode: 'default' }, setMode: vi.fn() }),
+}));
+vi.mock('../../../hooks/useSTT.svelte.js', () => ({
+    useSTT: () => ({
+        isListening: false,
+        lastResult: '',
+        isReady: false,
+        adapterType: null,
+        initialize: vi.fn(),
+        start: vi.fn(),
+        stop: vi.fn(),
+    }),
+}));
+import Fixture from './form-with-ui-controls.fixture.svelte';
+function captureTools() {
+    const registered = [];
+    document.modelContext = {
+        async registerTool(tool) {
+            registered.push(tool);
+        },
+    };
+    return registered;
+}
+afterEach(() => {
+    delete document.modelContext;
+});
+describe('rich Form: native attributes, enhance, and smrt-ui controls', () => {
+    it('passes native form attributes and attachments through to <form>', async () => {
+        const attach = vi.fn();
+        render(Fixture, { props: { attach } });
+        const form = screen.getByTestId('network-form');
+        expect(form.tagName).toBe('FORM');
+        expect(form).toHaveAttribute('enctype', 'multipart/form-data');
+        expect(form).toHaveAttribute('novalidate');
+        expect(form).toHaveAttribute('method', 'POST');
+        expect(form).toHaveAttribute('action', '?/create');
+        expect(form).toHaveAccessibleName('Set up your network');
+        expect(attach).toHaveBeenCalledWith(form);
+    });
+    it('applies an enhance action to the form and tears it down on unmount', () => {
+        const destroy = vi.fn();
+        const enhance = vi.fn(() => ({ destroy }));
+        const { unmount } = render(Fixture, { props: { enhance } });
+        expect(enhance).toHaveBeenCalledWith(screen.getByTestId('network-form'));
+        unmount();
+        expect(destroy).toHaveBeenCalledTimes(1);
+    });
+    it('lets an enhanced submit through without preventing it', async () => {
+        let submitted;
+        const enhance = (form) => {
+            const listener = (event) => {
+                submitted = event;
+                event.preventDefault();
+            };
+            form.addEventListener('submit', listener);
+            return { destroy: () => form.removeEventListener('submit', listener) };
+        };
+        render(Fixture, { props: { enhance } });
+        await userEvent.click(screen.getByRole('button', { name: 'Create' }));
+        expect(submitted).toBeDefined();
+    });
+    it('describes smrt-ui controls and rich fields in one stage-only tool', async () => {
+        const registered = captureTools();
+        render(Fixture);
+        await tick();
+        await vi.waitFor(() => expect(registered.length).toBeGreaterThan(0));
+        const tool = registered.at(-1);
+        expect(tool.name).toBe('setup-network_stage_changes');
+        expect(tool.inputSchema).toMatchObject({
+            type: 'object',
+            properties: {
+                tagline: { type: 'string', title: 'Tagline' },
+                name: { type: 'string', title: 'Network name' },
+                kind: { type: 'string', title: 'Kind of network' },
+                town: {
+                    type: 'string',
+                    title: 'Home town',
+                    enum: ['lacombe', 'blackfalds'],
+                },
+            },
+        });
+    });
+    it('stages smrt-ui control proposals for review and never writes them', async () => {
+        const registered = captureTools();
+        const registry = createControlInteractionRegistry();
+        render(Fixture, { props: { interactionRegistry: registry } });
+        await tick();
+        await vi.waitFor(() => expect(registered.length).toBeGreaterThan(0));
+        const tool = registered.at(-1);
+        const result = await tool.execute({
+            name: 'Central Alberta News',
+            town: 'blackfalds',
+            tagline: 'Local first',
+        });
+        expect(result).toBe('Staged 3 changes for review');
+        expect(screen.getByRole('textbox', { name: 'Network name' })).toHaveValue('');
+        await waitFor(() => expect(screen.getByRole('region', { name: 'Review proposed changes' })).toBeInTheDocument());
+        expect(registry.get({ formId: 'setup-network', controlId: 'name' })?.state.staged
+            ?.value).toBe('Central Alberta News');
+        expect(screen.queryByText(/setup-network\//)).not.toBeInTheDocument();
+    });
+    it('marks a staged smrt-ui proposal stale when the person types over it', async () => {
+        const registered = captureTools();
+        const registry = createControlInteractionRegistry();
+        render(Fixture, { props: { interactionRegistry: registry } });
+        await tick();
+        await vi.waitFor(() => expect(registered.length).toBeGreaterThan(0));
+        await registered.at(-1).execute({ name: 'Proposed' });
+        await userEvent.type(screen.getByRole('textbox', { name: 'Network name' }), 'Mine');
+        await waitFor(() => expect(registry.get({ formId: 'setup-network', controlId: 'name' })?.state
+            .staged?.stale).toBe(true));
+    });
+});

package/dist/components/forms/__tests__/Form.webmcp.test.js

@@ -1251,7 +1251,9 @@ describe('Form WebMCP staged-edit intent', () => {
         const fullname = screen.getByRole('textbox', { name: 'Full name' });
         expect(fullname).toHaveAttribute('data-smrt-subject-type', 'person');
         expect(fullname).toHaveAttribute('data-smrt-subject-id', 'person-1');
-        expect(await screen.findByText(/person:person-1/)).toBeInTheDocument();
+        // The review names the field, not the registry subject (plain labels).
+        expect(await screen.findByRole('button', { name: 'Apply Full name' })).toBeInTheDocument();
+        expect(screen.queryByText(/person:person-1/)).not.toBeInTheDocument();
         await view.rerender({
             webmcp: true,
             showAge: false,
@@ -1263,12 +1265,12 @@ describe('Form WebMCP staged-edit intent', () => {
         await vi.waitFor(() => expect(registered.length).toBeGreaterThan(_regLenBefore));
         expect(await registered.at(-1)?.execute({ fullname: 'Grace' })).toBe('Staged 1 change for review');
         expect(fullname).toHaveAttribute('data-smrt-subject-id', 'person-2');
-        expect(await screen.findByText(/person:person-2/)).toBeInTheDocument();
+        expect(await screen.findByRole('button', { name: 'Apply Full name' })).toBeInTheDocument();
         await userEvent.click(screen.getByRole('button', { name: 'Mutate subject' }));
         await tick();
         expect(await registered.at(-1)?.execute({ fullname: 'Katherine' })).toBe('Staged 1 change for review');
         expect(fullname).toHaveAttribute('data-smrt-subject-id', 'person-mutated');
-        expect(await screen.findByText(/person:person-mutated/)).toBeInTheDocument();
+        expect(await screen.findByRole('button', { name: 'Apply Full name' })).toBeInTheDocument();
     });
     it('publishes money in integer minor units and applies cents without rescaling', async () => {
         const registered = [];