@happyvertical/smrt-svelte 0.43.3 → 0.43.5

package/AGENTS.md

@@ -16,6 +16,15 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/components/settings/` (`./settings`) | `SettingsCatalog`, `paginateSettingsCatalog`, and the summary-vs-detail scalability contract | [agents/settings.md](agents/settings.md) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
 | `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) | — |
+
+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.
 
 ## The UI split — primitive-adoption contract (#1589)
 
@@ -53,6 +62,17 @@ migration; flips strict per package as it adopts the primitives).
 
 Wraps app in `+layout.svelte`. Provides auth state, permissions, WebSocket, and AI capabilities.
 
+The rich `Form` uses smrt-ui's shared staged-edit review contract. Agent
+proposals never mutate field bindings directly: they remain staged until a
+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.
+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.
+
 ```svelte
 <script>
   let { data, children } = $props();
@@ -64,6 +84,26 @@ Wraps app in `+layout.svelte`. Provides auth state, permissions, WebSocket, and
 </Provider>
 ```
 
+An object `webmcp` config with `definitions` registers generated data/model
+tools through the same registrar as direct smrt-web callers. With no `effects`
+policy, only `read`-effect tools register; `write` and `destructive` require
+explicit opt-in. Use `filter` for legacy collection definitions and `filterTool`
+for canonical definitions; a filter supplied for definitions of the other kind
+fails closed. Namespace, budget, resolver, annotation, and atomic-validation
+behavior must stay identical between Provider and direct registration. The
+authenticated REST route remains the execution authorization boundary.
+
+With the fixed mounted-UI adapter enabled, Provider also owns shared
+control/data-surface registries and registers six fixed `smrt_ui_*` tools. This
+adapter is a separate, consent-gated surface and is not governed by the
+generated-model effect policy. Descendant rich Forms use the shared
+control registry unless their explicit `interactionRegistry` prop overrides it.
+Supply `webmcp.ui.dataSurfaceRegistry` when mounted surface components already
+share an application registry. The adapter resolves registry state at execution
+time, never reads the DOM, never accepts agent confirmation, and removes the
+entire tool set with one abort signal. A document may have only one active
+adapter for a prefix; configure distinct prefixes for intentional coexistence.
+
 ## Hooks
 
 | Hook | Returns |
@@ -78,6 +118,11 @@ Wraps app in `+layout.svelte`. Provides auth state, permissions, WebSocket, and
 
 ## AI System
 
+- Rich Form WebMCP tools only stage review proposals. Structured payloads are
+  limited to published schema properties, money uses safe integer minor units,
+  and injected legacy registries without `executeBatch` use ordered `execute`
+  calls.
+
 - **Preload strategies**: `none`, `eager`, `idle` (recommended), `on-visible`
 - **Warm client cache**: module-level Map survives navigation/remounts -- avoids re-downloading WASM/models
 - **Adapters**: STT (browser-speech, whisper-cpp, whisper-wasm), TTS (browser-synthesis), LLM (webllm, transformers-llm)

package/README.md

@@ -92,6 +92,79 @@ hydrating its whole collection. It exposes `rows`, `page`, `total`,
 </Provider>
 ```
 
+The Provider can own generated WebMCP tools for the same lifecycle. Its policy
+is identical to `registerWebMcpTools`; omitted `effects` exposes reads only:
+
+```svelte
+<Provider webmcp={{
+  definitions,
+  effects: ['read', 'write'],
+  namespace: 'workspace',
+  maxTools: 24
+}}>
+  {@render children()}
+</Provider>
+```
+
+This controls capability exposure, not authorization. Tool execution still
+crosses the authenticated REST boundary and must retain its auth and tenancy
+guards. The `effects`, `filter`, and `filterTool` policy applies to generated
+data/model tools only; the fixed mounted-UI adapter has the separate controls
+described below.
+
+WebMCP test doubles and polyfills should implement the browser's
+promise-returning `document.modelContext.registerTool()` contract; declare the
+function `async` when migrating older void-returning fixtures.
+
+### Mounted UI through WebMCP
+
+`<Provider webmcp>` registers six fixed `smrt_ui_*` tools for the mounted UI:
+list, inspect, and execute for form controls and data surfaces. The tool set does
+not change as components mount and unmount; each call reads the current
+transport-neutral registries instead of inspecting or simulating the DOM.
+
+Forms automatically join the Provider's control registry. An explicit Form
+`interactionRegistry` still takes precedence. Pass the same data-surface
+registry used by `DataTable` or `CollectionToolbar` when those mounted surfaces
+should be discoverable:
+
+```svelte
+<script lang="ts">
+  import { createDataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
+  import { Provider } from '@happyvertical/smrt-svelte';
+
+  const surfaces = createDataSurfaceRegistry();
+</script>
+
+<Provider webmcp={{ ui: { dataSurfaceRegistry: surfaces } }}>
+  <!-- pass {surfaces} to mounted data-surface components -->
+  {@render children()}
+</Provider>
+```
+
+The default prefix is `smrt_ui_`. Configure `ui.prefix` when multiple Providers
+must coexist in one document; the same prefix cannot be registered twice.
+`ui: false` disables only the fixed UI adapter while leaving generated model
+tools enabled. For compatibility, an object config that omits `ui` continues to
+enable only generated model tools; use `webmcp={true}` or provide `ui: {}` to
+enable the mounted-UI adapter.
+
+Form commands always run with `source: 'agent'`. WebMCP input cannot assert
+confirmation: staging is allowed by the registry policy, while apply, clear,
+and undo require a separate human-confirmed path. Secret control values and
+hidden data-surface columns are not serialized. Read responses are marked as
+untrusted content. Bespoke `useWebMcpTool` and `<Form webmcp>` tools retain their
+existing lifecycle and submit behavior.
+
+Custom rich fields may continue to call `registerField(field)` and later
+`unregisterField(name)`. New code should retain and invoke the disposer returned
+by `registerField`: it is bound to that exact registration, so cleanup cannot
+remove a same-name replacement. The return value is additive; legacy form
+contexts whose `registerField` returns `void` remain supported. Context accessors
+bind legacy name-based cleanup to registrations made by that caller, so
+overlapping same-name fields can unmount in either order without retaining a
+detached control.
+
 ### Form Components
 
 ```svelte

package/dist/Provider.svelte

@@ -1,14 +1,11 @@
 <script lang="ts">
+import { createDataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
+import { createControlInteractionRegistry } from '@happyvertical/smrt-ui/forms';
 import {
   createI18nContext,
   type I18nSnapshot,
   setI18nContext,
 } from '@happyvertical/smrt-ui/i18n';
-import {
-  type RegisterWebMcpToolsOptions,
-  type SmrtWebClient,
-  type SmrtWebCollectionDefinition,
-} from '@happyvertical/smrt-web';
 import type { Snippet } from 'svelte';
 import { onDestroy, untrack } from 'svelte';
 import { logger } from './internal/logger.js';
@@ -21,6 +18,9 @@ import type {
 } from './state/app-state.js';
 import { createAppState } from './state/app-state.svelte.js';
 import { setAppStateContext } from './state/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';
 
 interface Props {
   /**
@@ -84,9 +84,9 @@ interface Props {
    */
   i18n?: I18nSnapshot;
   /**
-   * Opt in to the generated collection tools for this browser surface.
-   * WebMCP is feature-detected by smrt-web, so this is safe during SSR and on
-   * browsers that do not expose `document.modelContext`.
+   * Opt in to generated data tools and the fixed mounted-UI tool adapter for
+   * this browser surface. WebMCP is feature-detected, so this is safe during
+   * SSR and on browsers that do not expose `document.modelContext`.
    */
   webmcp?: boolean | WebMcpProviderConfig;
   /**
@@ -95,15 +95,6 @@ interface Props {
   children: Snippet;
 }
 
-export interface WebMcpProviderConfig {
-  definitions?: SmrtWebCollectionDefinition[];
-  client?: SmrtWebClient;
-  basePath?: string;
-  fetchFn?: typeof fetch;
-  scope?: string;
-  filter?: RegisterWebMcpToolsOptions['filter'];
-}
-
 const {
   mode,
   autoEnableSmrt = true,
@@ -135,6 +126,35 @@ const appState = createAppState({
   },
 });
 
+const localControlRegistry = createControlInteractionRegistry();
+const localDataSurfaceRegistry = createDataSurfaceRegistry();
+const webMcpConfig = $derived(typeof webmcp === 'object' ? webmcp : undefined);
+const webMcpUiConfig = $derived(
+  webmcp === true
+    ? {}
+    : typeof webMcpConfig?.ui === 'object'
+      ? webMcpConfig.ui
+      : undefined,
+);
+const resolvedControlRegistry = $derived(
+  webMcpUiConfig?.controlRegistry ?? localControlRegistry,
+);
+const resolvedDataSurfaceRegistry = $derived(
+  webMcpUiConfig?.dataSurfaceRegistry ?? localDataSurfaceRegistry,
+);
+
+setWebMcpUiContext({
+  get enabled() {
+    return webMcpUiConfig !== undefined;
+  },
+  get controlRegistry() {
+    return resolvedControlRegistry;
+  },
+  get dataSurfaceRegistry() {
+    return resolvedDataSurfaceRegistry;
+  },
+});
+
 $effect(() => {
   const currentPreferences = untrack(() => appState.state.session.preferences);
   if (currentPreferences.autoEnableSmrt === autoEnableSmrt) {
@@ -149,6 +169,21 @@ $effect(() => {
   });
 });
 
+// Register one fixed UI tool set. Mounted components change registry contents,
+// not the document-level WebMCP tool set.
+$effect(() => {
+  if (typeof window === 'undefined' || !webmcp || !webMcpUiConfig) return;
+  try {
+    return registerWebMcpUiTools({
+      controlRegistry: resolvedControlRegistry,
+      dataSurfaceRegistry: resolvedDataSurfaceRegistry,
+      ...(webMcpUiConfig.prefix ? { prefix: webMcpUiConfig.prefix } : {}),
+    });
+  } catch (error) {
+    logger.warn('Provider: WebMCP UI tool registration rejected', { error });
+  }
+});
+
 // Keep generated data-plane tools scoped to this Provider. The registrar
 // feature-detects WebMCP itself; effects do not run during SSR.
 $effect(() => {
@@ -160,16 +195,38 @@ $effect(() => {
 
   // Keep the data-plane engine out of applications that do not opt in. The
   // dynamic import also means SSR never evaluates browser-only engine code.
-  void import('@happyvertical/smrt-web').then(({ registerWebMcpTools }) => {
-    if (cancelled) return;
-    dispose = registerWebMcpTools(config.definitions ?? [], {
-      ...(config.client ? { client: config.client } : {}),
-      ...(config.basePath ? { basePath: config.basePath } : {}),
-      ...(config.fetchFn ? { fetchFn: config.fetchFn } : {}),
-      ...(config.scope ? { scope: config.scope } : {}),
-      ...(config.filter ? { filter: config.filter } : {}),
+  void import('@happyvertical/smrt-web')
+    .then(({ registerWebMcpTools }) => {
+      if (cancelled) return;
+      const registration = registerWebMcpTools(config.definitions ?? [], {
+        client: config.client,
+        basePath: config.basePath,
+        fetchFn: config.fetchFn,
+        scope: config.scope,
+        filter: config.filter,
+        filterTool: config.filterTool,
+        resolveFetchers: config.resolveFetchers,
+        resolveToolFetchers: config.resolveToolFetchers,
+        effects: config.effects,
+        namespace: config.namespace,
+        maxTools: config.maxTools,
+      });
+      dispose = registration;
+      void registration.ready.catch((error) => {
+        if (!cancelled) {
+          logger.warn('Provider: WebMCP data tool registration rejected', {
+            error,
+          });
+        }
+      });
+    })
+    .catch((error) => {
+      if (!cancelled) {
+        logger.warn('Provider: WebMCP data tool registration rejected', {
+          error,
+        });
+      }
     });
-  });
 
   return () => {
     cancelled = true;

package/dist/Provider.svelte.d.ts

@@ -1,15 +1,7 @@
 import { type I18nSnapshot } from '@happyvertical/smrt-ui/i18n';
-import { type RegisterWebMcpToolsOptions, type SmrtWebClient, type SmrtWebCollectionDefinition } from '@happyvertical/smrt-web';
 import type { Snippet } from 'svelte';
 import type { AIConfig, AILoadingState, AppMode, SocketConfig, User } from './state/app-state.js';
-export interface WebMcpProviderConfig {
-    definitions?: SmrtWebCollectionDefinition[];
-    client?: SmrtWebClient;
-    basePath?: string;
-    fetchFn?: typeof fetch;
-    scope?: string;
-    filter?: RegisterWebMcpToolsOptions['filter'];
-}
+import type { WebMcpProviderConfig } from './web/webmcp-provider.js';
 interface Props {
     /**
      * Initial mode: 'default' | 'smrt'
@@ -72,9 +64,9 @@ interface Props {
      */
     i18n?: I18nSnapshot;
     /**
-     * Opt in to the generated collection tools for this browser surface.
-     * WebMCP is feature-detected by smrt-web, so this is safe during SSR and on
-     * browsers that do not expose `document.modelContext`.
+     * Opt in to generated data tools and the fixed mounted-UI tool adapter for
+     * this browser surface. WebMCP is feature-detected, so this is safe during
+     * SSR and on browsers that do not expose `document.modelContext`.
      */
     webmcp?: boolean | WebMcpProviderConfig;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"Provider.svelte.d.ts","sourceRoot":"","sources":["../src/Provider.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,2BAA2B,EACjC,MAAM,yBAAyB,CAAC;AACjC,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;AAK9B,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,2BAA2B,EAAE,CAAC;IAC5C,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAED,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;AA4KD,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;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"}

package/dist/__tests__/provider-webmcp-harness.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+import Provider from '../Provider.svelte';
+import type { WebMcpProviderConfig } from '../web/webmcp-provider.js';
+
+interface Props {
+  webmcp: WebMcpProviderConfig;
+}
+
+const { webmcp }: Props = $props();
+</script>
+
+<Provider {webmcp}>
+  <span></span>
+</Provider>

package/dist/__tests__/provider-webmcp-harness.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { WebMcpProviderConfig } from '../web/webmcp-provider.js';
+interface Props {
+    webmcp: WebMcpProviderConfig;
+}
+declare const ProviderWebmcpHarness: import("svelte").Component<Props, {}, "">;
+type ProviderWebmcpHarness = ReturnType<typeof ProviderWebmcpHarness>;
+export default ProviderWebmcpHarness;
+//# sourceMappingURL=provider-webmcp-harness.svelte.d.ts.map

package/dist/__tests__/provider-webmcp-harness.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-webmcp-harness.svelte.d.ts","sourceRoot":"","sources":["../../src/__tests__/provider-webmcp-harness.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGtE,UAAU,KAAK;IACb,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAeD,QAAA,MAAM,qBAAqB,2CAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}

package/dist/components/forms/AddressInput.svelte

@@ -1,12 +1,16 @@
 <script lang="ts">
 import { useI18n } from '@happyvertical/smrt-ui/i18n';
-import { onDestroy, onMount } from 'svelte';
+import { untrack } from 'svelte';
 import { useAppState } from '../../hooks/useAppState.svelte.js';
 import { M } from '../../i18n/strings.forms.js';
 import {
   type FieldDefinition,
   tryGetFormContext,
 } from '../../state/form-context.js';
+import {
+  invalidStagedValue,
+  prepareTextFieldValue,
+} from './prepare-field-value.js';
 import type { AddressValue } from './types.js';
 
 const { t } = useI18n();
@@ -80,8 +84,66 @@ let {
   onchange,
 }: Props = $props();
 
+function countryValues(): string[] {
+  return [...new Set(countries.map((option) => option.value))];
+}
+
+function provinceValues(): string[] {
+  return [
+    ...new Set([
+      ...(!required ? [''] : []),
+      ...provinces.map((option) => option.value),
+    ]),
+  ];
+}
+
+function schemaForField(field: AddressField): Record<string, unknown> {
+  if (field === 'country') return { type: 'string', enum: countryValues() };
+  if (field === 'province') return { type: 'string', enum: provinceValues() };
+  return { type: 'string' };
+}
+
+function validatesAddressMembers(candidate: unknown): boolean {
+  if (typeof candidate !== 'object' || Array.isArray(candidate)) return false;
+  const address = candidate as Record<string, unknown>;
+  if (
+    ![Object.prototype, null].includes(Object.getPrototypeOf(address)) ||
+    !Object.keys(address).every((key) =>
+      fields.includes(key as AddressField),
+    ) ||
+    !fields.every(
+      (field) =>
+        !Object.hasOwn(address, field) || typeof address[field] === 'string',
+    )
+  ) {
+    return false;
+  }
+  if (
+    (Object.hasOwn(address, 'country') &&
+      !countryValues().includes(address.country as string)) ||
+    (Object.hasOwn(address, 'province') &&
+      !provinceValues().includes(address.province as string))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function validatesAddressCandidate(candidate: unknown): boolean {
+  if (candidate === null || candidate === undefined) return !required;
+  if (!validatesAddressMembers(candidate)) return false;
+  if (!required) return true;
+  const address = candidate as Record<string, unknown>;
+  return fields.every(
+    (field) =>
+      typeof address[field] === 'string' && address[field].trim().length > 0,
+  );
+}
+
 const app = useAppState();
 const formContext = tryGetFormContext();
+const fieldOwnerId = $props.id();
+const fieldOwnerToken = `smrt-rich-field-${fieldOwnerId}`;
 
 const isSmrt = $derived(app.state.mode === 'smrt');
 
@@ -90,7 +152,7 @@ let street = $state(value.street ?? '');
 let city = $state(value.city ?? '');
 let province = $state(value.province ?? '');
 let postalCode = $state(value.postalCode ?? '');
-let country = $state(value.country ?? 'CA');
+let country = $state(value.country ?? untrack(() => countries[0]?.value ?? ''));
 
 // Keep in sync with external value changes
 $effect(() => {
@@ -105,13 +167,18 @@ $effect(() => {
     country = value.country;
 });
 
-function updateValue() {
+function currentValue(): Partial<AddressValue> {
   const newValue: Partial<AddressValue> = {};
   if (fields.includes('street')) newValue.street = street;
   if (fields.includes('city')) newValue.city = city;
   if (fields.includes('province')) newValue.province = province;
   if (fields.includes('postalCode')) newValue.postalCode = postalCode;
   if (fields.includes('country')) newValue.country = country;
+  return newValue;
+}
+
+function updateValue() {
+  const newValue = currentValue();
   value = newValue;
   onchange?.(newValue);
 }
@@ -141,11 +208,16 @@ function parseSpokenAddress(text: string): Partial<AddressValue> {
     }
   }
 
-  // Try to extract country
-  if (/\bcanada\b/i.test(normalized)) {
-    result.country = 'CA';
-  } else if (/\bunited states\b|\busa\b|\bu\.?s\.?a?\.?\b/i.test(normalized)) {
-    result.country = 'US';
+  // Try to extract a currently configured country by its label or value.
+  for (const option of countries) {
+    const matches = [option.label, option.value].some((candidate) => {
+      const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      return new RegExp(`(^|\\W)${escaped}(?=$|\\W)`, 'i').test(normalized);
+    });
+    if (matches) {
+      result.country = option.value;
+      break;
+    }
   }
 
   // Common city extraction patterns
@@ -192,26 +264,33 @@ const primaryFieldId = $derived.by(() => {
 });
 
 // Register with form context
-onMount(() => {
+$effect(() => {
   if (formContext) {
+    const registeredName = name;
     const fieldDef: FieldDefinition = {
-      name,
+      name: registeredName,
+      ownerToken: fieldOwnerToken,
       type: 'address',
-      label,
-      description:
-        description ||
-        'A mailing address with street, city, province, postal code, and country',
+      get label() {
+        return label;
+      },
+      get description() {
+        return (
+          description ||
+          'A mailing address with street, city, province, postal code, and country'
+        );
+      },
       setValue: (v: unknown) => {
         if (v === null || v === undefined) {
           street = '';
           city = '';
           province = '';
           postalCode = '';
-          country = 'CA';
+          country = countries[0]?.value ?? '';
           updateValue();
           return;
         }
-        if (typeof v === 'object' && v !== null) {
+        if (validatesAddressMembers(v)) {
           const addr = v as Partial<AddressValue>;
           if (addr.street !== undefined) street = addr.street;
           if (addr.city !== undefined) city = addr.city;
@@ -222,36 +301,70 @@ onMount(() => {
           return;
         }
         // Try to parse spoken address
-        const parsed = parseSpokenAddress(String(v));
-        if (Object.keys(parsed).length > 0) {
-          if (parsed.street) street = parsed.street;
-          if (parsed.city) city = parsed.city;
-          if (parsed.province) province = parsed.province;
-          if (parsed.postalCode) postalCode = parsed.postalCode;
-          if (parsed.country) country = parsed.country;
+        const parsed = Object.fromEntries(
+          Object.entries(parseSpokenAddress(String(v))).filter(([field]) =>
+            fields.includes(field as AddressField),
+          ),
+        ) as Partial<AddressValue>;
+        if (Object.keys(parsed).length > 0 && validatesAddressMembers(parsed)) {
+          if (parsed.street !== undefined) street = parsed.street;
+          if (parsed.city !== undefined) city = parsed.city;
+          if (parsed.province !== undefined) province = parsed.province;
+          if (parsed.postalCode !== undefined) postalCode = parsed.postalCode;
+          if (parsed.country !== undefined) country = parsed.country;
           updateValue();
         }
       },
-      getValue: () => value,
-      constraints: { required },
-      webMcpSchema: {
-        type: 'object',
-        properties: Object.fromEntries(
-          fields.map((field) => [field, { type: 'string' }]),
-        ),
-        ...(required ? { required: [...fields] } : {}),
+      getValue: currentValue,
+      prepareValue: (candidate) => {
+        if (candidate === null || candidate === undefined) {
+          return Object.fromEntries(
+            fields.map((field) => [
+              field,
+              field === 'country' ? (countries[0]?.value ?? '') : '',
+            ]),
+          );
+        }
+        if (typeof candidate === 'object' && !Array.isArray(candidate)) {
+          return candidate;
+        }
+        const parsed = parseSpokenAddress(prepareTextFieldValue(candidate));
+        const configured = Object.fromEntries(
+          Object.entries(parsed).filter(([field]) =>
+            fields.includes(field as AddressField),
+          ),
+        );
+        return Object.keys(configured).length > 0
+          ? { ...currentValue(), ...configured }
+          : invalidStagedValue();
+      },
+      clear: () => {
+        street = '';
+        city = '';
+        province = '';
+        postalCode = '';
+        country = countries[0]?.value ?? '';
+        updateValue();
+        return true;
+      },
+      getState: () => ({ disabled }),
+      get constraints() {
+        return { required };
+      },
+      get webMcpSchema() {
+        return {
+          type: 'object',
+          additionalProperties: false,
+          properties: Object.fromEntries(
+            fields.map((field) => [field, schemaForField(field)]),
+          ),
+          ...(required ? { required: [...fields] } : {}),
+        };
       },
-      validate: () =>
-        !required ||
-        fields.every((field) => String(value[field] ?? '').trim().length > 0),
+      validateValue: validatesAddressCandidate,
+      validate: () => validatesAddressCandidate(currentValue()),
     };
-    formContext.registerField(fieldDef);
-  }
-});
-
-onDestroy(() => {
-  if (formContext) {
-    formContext.unregisterField(name);
+    return formContext.registerField(fieldDef);
   }
 });
 
@@ -281,7 +394,7 @@ function handleCountryChange(e: Event) {
 }
 </script>
 
-  <div class="smrt-address">
+  <div class="smrt-address" data-smrt-field-owner={fieldOwnerToken}>
   {#if label}
     <label class="smrt-label" for={primaryFieldId}>
       {label}

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

@@ -1 +1 @@
-{"version":3,"file":"AddressInput.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/AddressInput.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,KAAK,YAAY,GAAG,MAAM,YAAY,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,0CAA0C;IAC1C,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gCAAgC;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;CACnD;AAmUD,QAAA,MAAM,YAAY,gDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"AddressInput.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/AddressInput.svelte.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,KAAK,YAAY,GAAG,MAAM,YAAY,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,0CAA0C;IAC1C,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gCAAgC;IAChC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;CACnD;AAibD,QAAA,MAAM,YAAY,gDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}