@happyvertical/smrt-svelte 0.46.0 → 0.47.0

package/AGENTS.md

@@ -117,6 +117,15 @@ 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.
+The six derived names are also reserved through smrt-web's document-global
+tool-name lock (`@happyvertical/smrt-web/webmcp-tool-names`, #2613), so a
+generated model tool, a view intent, or a `useWebMcpTool` tool that would
+occupy one of them under the configured prefix fails at registration with the
+owner named instead of losing a tool at the host. Reserve before the first
+`registerTool` and release on dispose. Both locks here — the per-document
+prefix set and the shared name table — are stamped with the `modelContext`
+they were taken against and reset when a host installs a new one; keep them in
+step, or a prefix stays refused against a registry that never held its tools.
 
 ## Hooks
 
@@ -143,6 +152,20 @@ for a data-surface one — for exactly the component's lifetime.
   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.
+- **`useViewIntent` reserves as `intent`, not `bespoke`.** It reuses
+  `useWebMcpTool` rather than `registerViewIntent`, so it passes
+  `owner: 'intent'` explicitly; drop that and every intent collision blames a
+  `useWebMcpTool` call that does not exist. Diagnostic label only.
+- **A tool-name collision (#2613) reports, it does not throw at the caller.**
+  `registerWebMcpBespokeTool` throws synchronously, but both bindings here run
+  it after a lazy import inside an effect, so neither can hand the exception
+  back to a component. `<Provider>` catches the UI and generated registrars
+  into `logger.warn`; `useWebMcpTool` catches only
+  `WebMcpToolNameCollisionError` into its existing
+  `console.warn('[smrt-svelte] bespoke WebMCP tool registration failed', …)`
+  path — its `register()` is fire-and-forget, so anything it does not catch
+  becomes a page-level unhandled rejection. Every other synchronous throw (an
+  invalid `effects` policy) still propagates: that is an author bug.
 - **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

package/README.md

@@ -145,7 +145,12 @@ should be discoverable:
 ```
 
 The default prefix is `smrt_ui_`. Configure `ui.prefix` when multiple Providers
-must coexist in one document; the same prefix cannot be registered twice.
+must coexist in one document; the same prefix cannot be registered twice. The
+six derived names are reserved through the document-global tool-name lock, so
+a generated model tool, a view intent, or a `useWebMcpTool` tool that would
+take one of them under your prefix fails at registration with a message naming
+the tool and its current owner, rather than being silently dropped by the
+browser.
 `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

package/dist/web/__tests__/view-intent.svelte.test.js

@@ -9,6 +9,7 @@
  */
 import { createDataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
 import { createControlInteractionRegistry } from '@happyvertical/smrt-ui/forms';
+import { WebMcpToolNameCollisionError, webMcpToolNameOwner, } from '@happyvertical/smrt-web';
 import { render } from '@testing-library/svelte';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 const registerBespokeSpy = vi.hoisted(() => vi.fn());
@@ -118,7 +119,12 @@ describe('useViewIntent', () => {
             },
         });
         await vi.waitFor(() => expect(registerBespokeSpy).toHaveBeenCalledTimes(1));
-        expect(registerBespokeSpy.mock.calls[0][1]).toEqual({ effects: ['read'] });
+        // `owner: 'intent'` rides along on every intent registration so the
+        // tool-name lock blames the intent, not a bespoke tool (#2613).
+        expect(registerBespokeSpy.mock.calls[0][1]).toEqual({
+            effects: ['read'],
+            owner: 'intent',
+        });
         // The six fixed `smrt_ui_*` tools register alongside it; only the intent
         // must be absent.
         expect(toolNamed(registered, 'fixture_clear_notes')).toBeUndefined();
@@ -188,6 +194,43 @@ describe('useViewIntent', () => {
         expect(registered).toHaveLength(0);
         expect(registerBespokeSpy).not.toHaveBeenCalled();
     });
+    it('reserves its tool name as `intent`, not `bespoke` (#2613)', async () => {
+        // This binding is the only shipped intent path — it reuses
+        // `useWebMcpTool` rather than calling `registerViewIntent`, because the
+        // WebMCP lifecycle must not be duplicated. A collision against a mounted
+        // intent must still blame the INTENT, or an author goes looking for a
+        // `useWebMcpTool` call that does not exist.
+        const registered = installModelContext();
+        const view = render(Fixture, {
+            props: {
+                intent: revealNotesIntent,
+                identity: { formId: 'order-form', controlId: 'notes' },
+                controlRegistry: mountedControlRegistry(),
+            },
+        });
+        await vi.waitFor(() => expect(registered).toHaveLength(1));
+        expect(registered[0].name).toBe('fixture_reveal_notes');
+        expect(webMcpToolNameOwner('fixture_reveal_notes')).toBe('intent');
+        let thrown;
+        try {
+            // What a generated model tool named `fixture_reveal_notes` would hit.
+            const { registerWebMcpBespokeTool } = await import('@happyvertical/smrt-web');
+            registerWebMcpBespokeTool({
+                name: 'fixture_reveal_notes',
+                description: 'x',
+                inputSchema: { type: 'object' },
+                annotations: { readOnlyHint: true },
+                execute: () => 'ok',
+            });
+        }
+        catch (error) {
+            thrown = error;
+        }
+        expect(thrown).toBeInstanceOf(WebMcpToolNameCollisionError);
+        expect(thrown.owner).toBe('intent');
+        view.unmount();
+        expect(webMcpToolNameOwner('fixture_reveal_notes')).toBeUndefined();
+    });
     it('rejects an identity that does not match the declared target registry', () => {
         installModelContext();
         expect(() => render(Fixture, {

package/dist/web/__tests__/webmcp-ui.test.js

@@ -1,6 +1,7 @@
 import { createDataSurfaceRegistry, } from '@happyvertical/smrt-ui/data';
 import { createControlInteractionRegistry, } from '@happyvertical/smrt-ui/forms';
-import { describe, expect, it, vi } from 'vitest';
+import { registerWebMcpBespokeTool, WebMcpToolNameCollisionError, } from '@happyvertical/smrt-web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { registerWebMcpUiTools } from '../webmcp-ui.js';
 function modelContext() {
     const registered = [];
@@ -584,3 +585,121 @@ describe('registerWebMcpUiTools', () => {
         expect(() => registerWebMcpUiTools({ ...registries, document })).not.toThrow();
     });
 });
+/**
+ * The fixed UI tools and a hand-written `useWebMcpTool` tool are derived on
+ * different paths and neither can see the other's runtime prefix, so before
+ * #2613 a bespoke name matching a custom-prefixed UI tool reached the host and
+ * one of the two was silently lost. Both paths now reserve through the
+ * document-global tool-name lock. These use the real jsdom `document` because
+ * that is the object both registrars key their reservations on in a page —
+ * `registerWebMcpBespokeTool` reads `globalThis.document` and has no injection
+ * seam.
+ */
+describe('cross-path tool-name lock (#2613)', () => {
+    const registries = () => ({
+        controlRegistry: createControlInteractionRegistry(),
+        dataSurfaceRegistry: createDataSurfaceRegistry(),
+    });
+    function installPageModelContext() {
+        const registered = [];
+        document.modelContext = {
+            async registerTool(tool) {
+                registered.push(tool);
+            },
+        };
+        return registered;
+    }
+    function bespoke(name) {
+        return {
+            name,
+            description: 'A component-owned tool',
+            inputSchema: { type: 'object', properties: {} },
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            execute: () => 'ok',
+        };
+    }
+    afterEach(() => {
+        document.modelContext = undefined;
+    });
+    it('refuses a bespoke tool named for a UI tool under a custom prefix', () => {
+        const registered = installPageModelContext();
+        const dispose = registerWebMcpUiTools({
+            ...registries(),
+            prefix: 'agent_ui_',
+        });
+        expect(registered).toHaveLength(6);
+        let thrown;
+        try {
+            registerWebMcpBespokeTool(bespoke('agent_ui_execute_form_control'));
+        }
+        catch (error) {
+            thrown = error;
+        }
+        expect(thrown).toBeInstanceOf(WebMcpToolNameCollisionError);
+        const collision = thrown;
+        expect(collision.toolName).toBe('agent_ui_execute_form_control');
+        expect(collision.owner).toBe('ui');
+        expect(collision.requestedBy).toBe('bespoke');
+        expect(registered).toHaveLength(6);
+        // The default prefix was never mounted, so the same suffix is free there.
+        const other = registerWebMcpBespokeTool(bespoke('smrt_ui_execute_form_control'));
+        expect(registered).toHaveLength(7);
+        other();
+        dispose();
+    });
+    it('refuses a UI prefix a live bespoke tool already occupies', () => {
+        const registered = installPageModelContext();
+        const held = registerWebMcpBespokeTool(bespoke('agent_ui_inspect_form_control'));
+        expect(registered).toHaveLength(1);
+        let thrown;
+        try {
+            registerWebMcpUiTools({ ...registries(), prefix: 'agent_ui_' });
+        }
+        catch (error) {
+            thrown = error;
+        }
+        expect(thrown).toBeInstanceOf(WebMcpToolNameCollisionError);
+        expect(thrown.owner).toBe('bespoke');
+        // Atomic: not one of the six reached the host.
+        expect(registered).toHaveLength(1);
+        // And the refused mount released its own prefix lock, so the same prefix
+        // works once the bespoke tool goes away.
+        held();
+        const dispose = registerWebMcpUiTools({
+            ...registries(),
+            prefix: 'agent_ui_',
+        });
+        expect(registered).toHaveLength(7);
+        dispose();
+    });
+    it('frees the prefix and the names when the host swaps its model context', () => {
+        const registered = installPageModelContext();
+        // Deliberately never disposed: the adapter's six tools live in the old
+        // registry, which the host is about to throw away. Both the prefix lock
+        // and the name reservations must let go with it, or the same prefix stays
+        // permanently refused against a registry that never held it.
+        registerWebMcpUiTools({ ...registries(), prefix: 'agent_ui_' });
+        expect(registered).toHaveLength(6);
+        const rebound = installPageModelContext();
+        const dispose = registerWebMcpUiTools({
+            ...registries(),
+            prefix: 'agent_ui_',
+        });
+        expect(rebound).toHaveLength(6);
+        dispose();
+    });
+    it('frees the six names on dispose so a remount succeeds', () => {
+        const registered = installPageModelContext();
+        for (let cycle = 0; cycle < 3; cycle += 1) {
+            registerWebMcpUiTools({ ...registries(), prefix: 'agent_ui_' })();
+        }
+        expect(registered).toHaveLength(18);
+        const bespokeDisposer = registerWebMcpBespokeTool(bespoke('agent_ui_execute_form_control'));
+        expect(registered).toHaveLength(19);
+        bespokeDisposer();
+    });
+});

package/dist/web/__tests__/webmcp.test.js

@@ -1,3 +1,4 @@
+import { registerWebMcpBespokeTool as registerBespokeDirect, reserveWebMcpToolNames, WebMcpToolNameCollisionError, webMcpToolNameOwner, } from '@happyvertical/smrt-web';
 import { render } from '@testing-library/svelte';
 import { tick } from 'svelte';
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -149,6 +150,53 @@ describe('useWebMcpTool', () => {
         view.unmount();
         warnSpy.mockRestore();
     });
+    it('reports a tool-name collision through its warn path, not as an unhandled rejection (#2613)', async () => {
+        const registered = installModelContext();
+        // Stand in for whatever already holds the name — a generated model tool,
+        // a fixed `smrt_ui_*` tool under a custom prefix, or another mounted
+        // component. `registerWebMcpBespokeTool` now throws SYNCHRONOUSLY here,
+        // inside this hook's fire-and-forget `register()`, so without the
+        // narrowed catch the page would see a global unhandled rejection instead
+        // of a diagnostic naming the tool and its owner.
+        const held = reserveWebMcpToolNames(['harness_tool_1'], 'generated');
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const unhandled = vi.fn();
+        window.addEventListener('unhandledrejection', unhandled);
+        const view = render(Harness, { props: { version: 1 } });
+        await vi.waitFor(() => expect(warn).toHaveBeenCalled());
+        // Two macrotask turns is enough for an unhandled rejection to surface.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(unhandled).not.toHaveBeenCalled();
+        expect(registered).toHaveLength(0);
+        const [message, name, error] = warn.mock.calls[0];
+        expect(message).toContain('bespoke WebMCP tool registration failed');
+        expect(name).toBe('harness_tool_1');
+        expect(error).toBeInstanceOf(WebMcpToolNameCollisionError);
+        expect(error.owner).toBe('generated');
+        // The losing registrant strands nothing: the holder keeps the name, and
+        // unmounting the component leaves it exactly as it was.
+        expect(webMcpToolNameOwner('harness_tool_1')).toBe('generated');
+        view.unmount();
+        expect(webMcpToolNameOwner('harness_tool_1')).toBe('generated');
+        held.release();
+        expect(webMcpToolNameOwner('harness_tool_1')).toBeUndefined();
+        window.removeEventListener('unhandledrejection', unhandled);
+        warn.mockRestore();
+    });
+    it('still propagates a non-collision synchronous registrar throw', async () => {
+        installModelContext();
+        // The narrowed catch above must not swallow an authoring error. An
+        // invalid `effects` policy is the synchronous throw that already existed.
+        expect(() => registerBespokeDirect({
+            name: 'harness_tool_1',
+            description: 'x',
+            inputSchema: { type: 'object' },
+            annotations: { readOnlyHint: true },
+            execute: () => 'ok',
+        }, { effects: ['nonsense'] })).toThrow(/Invalid WebMCP effect/);
+        expect(webMcpToolNameOwner('harness_tool_1')).toBeUndefined();
+    });
     it('registers a previously-excluded bespoke tool when a Provider policy loosens to permit it (#2599)', async () => {
         const registered = installModelContext();
         const view = render(EffectsReactivity, {

package/dist/web/view-intent.svelte.d.ts

@@ -41,7 +41,7 @@ export interface UseViewIntentOptions {
  *
  * Registration therefore goes through `registerWebMcpBespokeTool`, so an
  * intent is subject to the same fail-closed exposure policy as a generated
- * model tool. Execution dispatches exactly one registry command with
+ * model tool, and reserves its tool name as `intent` rather than `bespoke`. Execution dispatches exactly one registry command with
  * `source: 'agent'` — `StagedControlReview` stays on the path, agent-staged
  * values remain proposals, and there is no path to REST.
  *

package/dist/web/view-intent.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-intent.svelte.d.ts","sourceRoot":"","sources":["../../src/web/view-intent.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,KAAK,EACV,UAAU,EAEV,yBAAyB,EACzB,6BAA6B,EAC7B,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AASjC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,6BAA6B,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,sEAAsE;IACtE,eAAe,CAAC,EAAE,0BAA0B,CAAC;IAC7C,qDAAqD;IACrD,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CA8BN"}
+{"version":3,"file":"view-intent.svelte.d.ts","sourceRoot":"","sources":["../../src/web/view-intent.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,KAAK,EACV,UAAU,EAEV,yBAAyB,EACzB,6BAA6B,EAC7B,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AASjC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,6BAA6B,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,sEAAsE;IACtE,eAAe,CAAC,EAAE,0BAA0B,CAAC;IAC7C,qDAAqD;IACrD,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAsCN"}

package/dist/web/view-intent.svelte.js

@@ -20,7 +20,7 @@ import { tryGetWebMcpUiContext } from './webmcp-ui-context.js';
  *
  * Registration therefore goes through `registerWebMcpBespokeTool`, so an
  * intent is subject to the same fail-closed exposure policy as a generated
- * model tool. Execution dispatches exactly one registry command with
+ * model tool, and reserves its tool name as `intent` rather than `bespoke`. Execution dispatches exactly one registry command with
  * `source: 'agent'` — `StagedControlReview` stays on the path, agent-staged
  * values remain proposals, and there is no path to REST.
  *
@@ -57,7 +57,15 @@ export function useViewIntent(intent, options) {
             (uiContext?.enabled ? uiContext.dataSurfaceRegistry : undefined);
         const binding = resolveBinding(intent, options.identity, controlRegistry, dataSurfaceRegistry);
         return binding ? compileViewIntentToolSpec(intent, binding) : null;
-    }, options.effects ? { effects: options.effects } : {});
+    }, {
+        // This hook, not `registerViewIntent`, is the shipped intent path — the
+        // WebMCP lifecycle lives in `useWebMcpTool` and must not be duplicated
+        // here. Label the tool-name reservation `intent` anyway (#2613), or a
+        // collision against a mounted intent would report `bespoke` and send an
+        // author looking for a `useWebMcpTool` call that does not exist.
+        owner: 'intent',
+        ...(options.effects ? { effects: options.effects } : {}),
+    });
 }
 function assertIdentityShape(intent, identity) {
     if (intent.target.registry === 'control' && !('formId' in identity)) {

package/dist/web/webmcp-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp-ui.d.ts","sourceRoot":"","sources":["../../src/web/webmcp-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,mBAAmB,EAGzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAKV,0BAA0B,EAE3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AA8CzD,MAAM,WAAW,4BAA4B;IAC3C,eAAe,EAAE,0BAA0B,CAAC;IAC5C,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,sBAAsB,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,sBAAsB;IAC9B,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AA6fD,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,MAAM,IAAI,CAoDZ"}
+{"version":3,"file":"webmcp-ui.d.ts","sourceRoot":"","sources":["../../src/web/webmcp-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,mBAAmB,EAGzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAKV,0BAA0B,EAE3B,MAAM,8BAA8B,CAAC;AAKtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AA0DzD,MAAM,WAAW,4BAA4B;IAC3C,eAAe,EAAE,0BAA0B,CAAC;IAC5C,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,sBAAsB,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,sBAAsB;IAC9B,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AA6fD,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,MAAM,IAAI,CA6EZ"}

package/dist/web/webmcp-ui.js

@@ -1,4 +1,5 @@
 import { DATA_SURFACE_IDENTIFIER_MAX_LENGTH, DATA_SURFACE_MAX_REQUEST_BYTES, } from '@happyvertical/smrt-ui/data';
+import { reserveWebMcpToolNames, } from '@happyvertical/smrt-web/webmcp-tool-names';
 const CONTROL_ACTIONS = new Set([
     'focus',
     'reveal',
@@ -28,6 +29,15 @@ const PUBLIC_CONTROL_RESULT_REASONS = new Set([
     'nothing_to_undo',
     'denied',
 ]);
+/**
+ * Active UI prefixes per document, stamped with the model context they were
+ * taken against. The stamp matters for the same reason smrt-web's tool-name
+ * table carries one (#2613): when a host installs a new `modelContext`, every
+ * tool the old registry held is gone, so a prefix must not stay locked against
+ * the new one. Without it the two locks in `registerWebMcpUiTools` would
+ * disagree — the names would be free while the prefix stayed permanently
+ * refused.
+ */
 const documentLocks = new WeakMap();
 class PublicToolError extends Error {
     reason;
@@ -438,15 +448,36 @@ export function registerWebMcpUiTools(options) {
     if (!modelContext || typeof modelContext.registerTool !== 'function') {
         return () => { };
     }
-    let locks = documentLocks.get(documentLike);
-    if (!locks) {
+    const entry = documentLocks.get(documentLike);
+    let locks;
+    if (entry && entry.modelContext === modelContext) {
+        locks = entry.prefixes;
+    }
+    else {
         locks = new Set();
-        documentLocks.set(documentLike, locks);
+        documentLocks.set(documentLike, { modelContext, prefixes: locks });
     }
     if (locks.has(prefix)) {
         throw new Error(`WebMCP UI prefix is already registered: ${prefix}`);
     }
     locks.add(prefix);
+    const specs = tools(prefix, options.controlRegistry, options.dataSurfaceRegistry);
+    // The six fixed names go through the document-global tool-name lock (#2613)
+    // so a generated model tool, a declared view intent, or a bespoke
+    // `useWebMcpTool` name cannot silently take one of them from us — or lose to
+    // one of ours — at the host. Under a custom `prefix` these names are not
+    // knowable from any declaration, which is exactly why the lock exists.
+    // Reserved before the first `registerTool`, and released by `dispose`; the
+    // prefix lock above stays because it names the more common mistake (two
+    // Providers, one prefix) more precisely.
+    let reservation;
+    try {
+        reservation = reserveWebMcpToolNames(specs.map((spec) => spec.name), 'ui', { document: documentLike });
+    }
+    catch (error) {
+        locks.delete(prefix);
+        throw error;
+    }
     const controller = new AbortController();
     let disposed = false;
     const dispose = () => {
@@ -455,9 +486,10 @@ export function registerWebMcpUiTools(options) {
         disposed = true;
         controller.abort();
         locks.delete(prefix);
+        reservation.release();
     };
     try {
-        for (const tool of tools(prefix, options.controlRegistry, options.dataSurfaceRegistry)) {
+        for (const tool of specs) {
             const registration = modelContext.registerTool(tool, {
                 signal: controller.signal,
             });

package/dist/web/webmcp.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { WebMcpBespokeToolSpec, WebMcpToolEffect } from '@happyvertical/smrt-web';
+import type { RegisterWebMcpBespokeToolOptions, WebMcpBespokeToolSpec, WebMcpToolEffect } from '@happyvertical/smrt-web';
 /** A tool exposed to the browser's WebMCP model context. */
 export type WebMcpToolSpec = WebMcpBespokeToolSpec;
 export interface UseWebMcpToolOptions {
@@ -11,6 +11,15 @@ export interface UseWebMcpToolOptions {
      * registrar's own read-only default as the no-Provider fallback.
      */
     effects?: readonly WebMcpToolEffect[];
+    /**
+     * Which path this tool belongs to, for the tool-name lock's collision
+     * diagnostic only (#2613). Defaults to `bespoke`, which is right for every
+     * hand-written component tool. `useViewIntent` passes `intent` because it
+     * routes a declared view intent through this same hook rather than
+     * duplicating the WebMCP lifecycle — see
+     * `RegisterWebMcpBespokeToolOptions['owner']`. It grants nothing.
+     */
+    owner?: RegisterWebMcpBespokeToolOptions['owner'];
 }
 declare global {
     interface Document {
@@ -42,6 +51,9 @@ declare global {
  *
  * @param options.effects a fallback exposure policy applied only when no
  * Provider ancestor declares one — see {@link UseWebMcpToolOptions}.
+ * @param options.owner the tool-name lock's diagnostic label for this
+ * registration (#2613); `useViewIntent` passes `intent`, everything else
+ * leaves the `bespoke` default.
  */
 export declare function useWebMcpTool(factory: () => WebMcpToolSpec | null | undefined, options?: UseWebMcpToolOptions): void;
 //# sourceMappingURL=webmcp.svelte.d.ts.map

package/dist/web/webmcp.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.svelte.d.ts","sourceRoot":"","sources":["../../src/web/webmcp.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EAErB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAGjC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACvC;AAID,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,QAAQ;QAChB,YAAY,CAAC,EAAE,kBAAkB,CAAC;KACnC;IAED,UAAU,kBAAkB;QAC1B,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;KAClB;CACF;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,EAChD,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAuFN"}
+{"version":3,"file":"webmcp.svelte.d.ts","sourceRoot":"","sources":["../../src/web/webmcp.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gCAAgC,EAChC,qBAAqB,EAErB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAGjC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,gCAAgC,CAAC,OAAO,CAAC,CAAC;CACnD;AAID,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,QAAQ;QAChB,YAAY,CAAC,EAAE,kBAAkB,CAAC;KACnC;IAED,UAAU,kBAAkB;QAC1B,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;KAClB;CACF;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,EAChD,OAAO,GAAE,oBAAyB,GACjC,IAAI,CA2GN"}

package/dist/web/webmcp.svelte.js

@@ -28,6 +28,9 @@ function getModelContext() {
  *
  * @param options.effects a fallback exposure policy applied only when no
  * Provider ancestor declares one — see {@link UseWebMcpToolOptions}.
+ * @param options.owner the tool-name lock's diagnostic label for this
+ * registration (#2613); `useViewIntent` passes `intent`, everything else
+ * leaves the `bespoke` default.
  */
 export function useWebMcpTool(factory, options = {}) {
     const bespokeContext = tryGetWebMcpBespokeContext();
@@ -69,18 +72,20 @@ export function useWebMcpTool(factory, options = {}) {
         const priorReady = previousDisposer?.ready;
         let cancelled = false;
         let dispose = () => { };
+        function reportRegistrationFailure(error) {
+            if (cancelled)
+                return;
+            console.warn('[smrt-svelte] bespoke WebMCP tool registration failed', spec.name, error);
+        }
         async function register() {
             // The dynamic import failing to load is expected in bundle profiles
             // without `@happyvertical/smrt-web` — treat it like WebMCP being
             // unavailable and no-op, silently. Only THIS statement's failure is
-            // caught: a synchronous throw from `registerWebMcpBespokeTool` below
-            // (e.g. an invalid `effects` policy) happens outside this try block
-            // and is deliberately left to propagate as an unhandled rejection of
-            // `register()`'s own promise, rather than being swallowed alongside
-            // the load-failure case.
-            let registerWebMcpBespokeTool;
+            // caught here; a synchronous throw from `registerWebMcpBespokeTool`
+            // below is handled by its own narrower catch.
+            let smrtWeb;
             try {
-                ({ registerWebMcpBespokeTool } = await import('@happyvertical/smrt-web'));
+                smrtWeb = await import('@happyvertical/smrt-web');
             }
             catch {
                 return;
@@ -94,14 +99,35 @@ export function useWebMcpTool(factory, options = {}) {
                 if (cancelled)
                     return;
             }
-            const registration = registerWebMcpBespokeTool(spec, { effects });
+            let registration;
+            try {
+                registration = smrtWeb.registerWebMcpBespokeTool(spec, {
+                    effects,
+                    ...(options.owner ? { owner: options.owner } : {}),
+                });
+            }
+            catch (error) {
+                // A tool-name collision (#2613) is a RUNTIME condition — a generated
+                // model tool, a fixed `smrt_ui_*` tool, or another live component
+                // already holds this name — not an authoring error in this call, and
+                // it is exactly what the lock exists to report. Route it to the same
+                // warning a host rejection of `ready` produces, so a losing bespoke
+                // registrant gets a diagnostic naming the tool and its owner instead
+                // of a global unhandled rejection: `register()` is fire-and-forget
+                // (`void register()` below), so nothing observes this promise. Both
+                // Provider-owned paths already catch their registrar's throw the same
+                // way. Every other synchronous throw — an invalid `effects` policy is
+                // the one that exists — still propagates, because that is an author
+                // bug the page should surface loudly.
+                if (error instanceof smrtWeb.WebMcpToolNameCollisionError) {
+                    reportRegistrationFailure(error);
+                    return;
+                }
+                throw error;
+            }
             dispose = registration;
             previousDisposer = registration;
-            void registration.ready.catch((error) => {
-                if (!cancelled) {
-                    console.warn('[smrt-svelte] bespoke WebMCP tool registration failed', spec.name, error);
-                }
-            });
+            void registration.ready.catch(reportRegistrationFailure);
         }
         void register();
         return () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "smrtJsdoc": "strict",
   "description": "Svelte 5 components for SMRT user management - auth, users, tenants, roles, permissions, groups",
   "type": "module",
@@ -121,13 +121,13 @@
   },
   "dependencies": {
     "@happyvertical/logger": "^0.89.4",
+    "@happyvertical/smrt-languages": "0.47.0",
+    "@happyvertical/smrt-types": "0.47.0",
+    "@happyvertical/smrt-ui": "0.47.0",
+    "@happyvertical/smrt-web": "0.47.0",
     "@tanstack/db": "^0.6.14",
     "@tanstack/svelte-db": "^0.1.91",
-    "esm-env": "^1.2.2",
-    "@happyvertical/smrt-languages": "0.46.0",
-    "@happyvertical/smrt-ui": "0.46.0",
-    "@happyvertical/smrt-types": "0.46.0",
-    "@happyvertical/smrt-web": "0.46.0"
+    "esm-env": "^1.2.2"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",
@@ -155,6 +155,14 @@
     }
   },
   "devDependencies": {
+    "@happyvertical/smrt-agents": "0.47.0",
+    "@happyvertical/smrt-chat": "0.47.0",
+    "@happyvertical/smrt-content": "0.47.0",
+    "@happyvertical/smrt-core": "0.47.0",
+    "@happyvertical/smrt-reports": "0.47.0",
+    "@happyvertical/smrt-scanner": "0.47.0",
+    "@happyvertical/smrt-tenancy": "0.47.0",
+    "@happyvertical/smrt-users": "0.47.0",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@testing-library/jest-dom": "^6.9.1",
@@ -166,15 +174,7 @@
     "svelte-check": "^4.7.1",
     "typescript": "5.9.3",
     "vite": "8.1.4",
-    "vitest": "4.1.10",
-    "@happyvertical/smrt-agents": "0.46.0",
-    "@happyvertical/smrt-chat": "0.46.0",
-    "@happyvertical/smrt-content": "0.46.0",
-    "@happyvertical/smrt-core": "0.46.0",
-    "@happyvertical/smrt-reports": "0.46.0",
-    "@happyvertical/smrt-tenancy": "0.46.0",
-    "@happyvertical/smrt-users": "0.46.0",
-    "@happyvertical/smrt-scanner": "0.46.0"
+    "vitest": "4.1.10"
   },
   "scripts": {
     "build": "svelte-package -i src --tsconfig tsconfig.svelte.json",