@happyvertical/smrt-web 0.46.0 → 0.47.1

package/dist/index.d.ts

@@ -565,6 +565,16 @@ export declare function registerDurableResource(namespace: string, resource: Dur
  * `compileViewIntentToolSpec` from `intent.target`. No author-supplied code
  * runs, and the only thing it can do is dispatch one browser registry
  * command — the runtime half of the no-REST invariant.
+ *
+ * The intent's derived tool name is claimed against the document-global
+ * tool-name lock (#2613), so an id whose flattened name collides with a
+ * generated model tool or a fixed UI tool throws
+ * {@link WebMcpToolNameCollisionError} here rather than silently losing the
+ * tool at the host. `defineIntent`'s own intent-vs-intent check cannot see
+ * either, because both depend on a runtime `namespace` / `prefix` the
+ * declaration never sees.
+ *
+ * @throws {WebMcpToolNameCollisionError} when the derived name is already held.
  */
 export declare function registerViewIntent(intent: ViewIntent, binding: ViewIntentBinding, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
 
@@ -578,9 +588,19 @@ export declare function registerViewIntent(intent: ViewIntent, binding: ViewInte
  * `maxTools` are out of scope for a bespoke tool; see
  * {@link RegisterWebMcpBespokeToolOptions}.
  *
+ * The tool's name is also claimed against the
+ * document-global tool-name lock before the browser sees it. A name a
+ * generated model tool, a fixed UI tool, or another live bespoke tool /
+ * intent already holds throws {@link WebMcpToolNameCollisionError}
+ * SYNCHRONOUSLY, naming the colliding name and the owner that holds it.
+ * Previously the host accepted the call and silently dropped the losing
+ * registration. Disposing releases the name, so register/dispose/re-register
+ * under one name still succeeds.
+ *
  * @returns a disposer that deregisters the tool this call registered (a
  * no-op double-call). On a browser without WebMCP, or when policy excludes
  * the tool's effect, the call is a no-op and the disposer is inert.
+ * @throws {WebMcpToolNameCollisionError} when the name is already held.
  */
 export declare function registerWebMcpBespokeTool(spec: WebMcpBespokeToolSpec, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
 
@@ -593,13 +613,36 @@ export declare interface RegisterWebMcpBespokeToolOptions {
      * an unrelated generated tool set fail to register.
      */
     effects?: readonly WebMcpToolEffect[];
+    /**
+     * Which path this registration belongs to, used ONLY to label its
+     * tool-name reservation (#2613) so a later collision names the right
+     * source. Defaults to `bespoke`.
+     *
+     * A UI-framework binding that compiles a declared view intent itself and
+     * registers it here — rather than through {@link registerViewIntent} —
+     * must pass `'intent'`. `useViewIntent` in `@happyvertical/smrt-svelte`
+     * does exactly that, because reusing `useWebMcpTool`'s single WebMCP
+     * lifecycle is a documented invariant of that package; without this it
+     * would be the only shipped intent path and every intent collision would
+     * blame a `useWebMcpTool` call that does not exist.
+     *
+     * Purely a diagnostic label: it grants no capability, narrows no policy,
+     * and changes nothing about how the tool registers or executes.
+     */
+    owner?: Extract<WebMcpToolNameOwner, 'intent' | 'bespoke'>;
 }
 
 /**
  * Register every collection's generated tool descriptors with WebMCP.
  *
+ * Every selected tool name is claimed against the document-global tool-name
+ * lock (#2613) before the first browser registration, so a collision with a
+ * UI-layer or bespoke tool throws {@link WebMcpToolNameCollisionError} with
+ * the offending name and its current owner instead of reaching the host.
+ *
  * @returns a disposer that deregisters all tools this call registered. On a
  * browser without WebMCP the call is a no-op and the disposer is inert.
+ * @throws {WebMcpToolNameCollisionError} when a selected name is already held.
  */
 export declare function registerWebMcpTools(definitions: readonly WebMcpRegistrationDefinition[], options?: RegisterWebMcpToolsOptions): WebMcpRegistrationDisposer;
 
@@ -630,6 +673,34 @@ export declare interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy
     filterTool?: (definition: WebMcpToolDefinition) => boolean;
 }
 
+/**
+ * Reserve `names` for `owner` against the document's WebMCP registry.
+ *
+ * Reservation is ALL-OR-NOTHING: if any name is already held — by this path
+ * or another — nothing is reserved and a {@link WebMcpToolNameCollisionError}
+ * naming the colliding name and its current owner is thrown synchronously,
+ * before any tool reaches `document.modelContext`. Duplicates within `names`
+ * itself collide the same way.
+ *
+ * Off-WebMCP (no document) the call is a no-op returning an inert
+ * reservation, matching every registrar's own no-op guarantee.
+ *
+ * A reservation releases only the names it took: `release()` never drops a
+ * name a later reservation has since acquired, so a dispose that lands after
+ * a same-name re-registration cannot revoke the new holder's claim.
+ */
+export declare function reserveWebMcpToolNames(names: readonly string[], owner: WebMcpToolNameOwner, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameReservation;
+
+declare interface ReserveWebMcpToolNamesOptions {
+    /**
+     * The document whose `modelContext` the names are registered against.
+     * Defaults to `globalThis.document`. Registrars that accept an injectable
+     * document (tests, non-window hosts) must pass the SAME object they read
+     * `modelContext` from, or their reservations land in a different table.
+     */
+    document?: unknown;
+}
+
 /**
  * Run the `wrapMutation` hook across `capabilities` in array order for one
  * mutation, short-circuiting on the FIRST capability that returns `{ handled:
@@ -1667,6 +1738,89 @@ export declare interface WebMcpToolDefinition extends WebToolDescriptor {
  */
 export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
 
+/**
+ * Thrown synchronously when a name is already held. Carries the colliding
+ * name and the owner that holds it so a host can report both without parsing
+ * the message.
+ */
+export declare class WebMcpToolNameCollisionError extends Error {
+    readonly toolName: string;
+    /** The path that already holds {@link toolName}. */
+    readonly owner: WebMcpToolNameOwner;
+    /** The path that tried to take it. */
+    readonly requestedBy: WebMcpToolNameOwner;
+    constructor(toolName: string, 
+    /** The path that already holds {@link toolName}. */
+    owner: WebMcpToolNameOwner, 
+    /** The path that tried to take it. */
+    requestedBy: WebMcpToolNameOwner);
+}
+
+/**
+ * Document-global WebMCP tool-name lock (#2613).
+ *
+ * A browser tool name is derived independently on three paths that all end at
+ * the same `document.modelContext`:
+ *
+ * 1. **generated** model tools — `<namespace>_<model>_<action>`, built by
+ *    `registerWebMcpTools` from the exposure policy;
+ * 2. **ui** — the six fixed `smrt_ui_*` tools a UI layer registers under a
+ *    configurable prefix (`registerWebMcpUiTools` in `@happyvertical/smrt-svelte`);
+ * 3. **intent** / **bespoke** — declared view intents (#2588) and hand-written
+ *    `useWebMcpTool` tools, whose names come from the declaration `id` or the
+ *    spec `name`.
+ *
+ * None of the three can see the others at declaration time: a namespace and a
+ * UI prefix are runtime values a declaration never sees. `registerWebMcpTools`
+ * rejects duplicates WITHIN its own prospective set, but nothing checked
+ * ACROSS the paths, so a collision reached the host — which rejects the later
+ * registration and leaves the tool silently absent.
+ *
+ * This module is the shared reservation table those paths coordinate through.
+ * It is an AVAILABILITY guard, not a trust boundary: every path stays
+ * fail-closed and browser-only regardless, and a collision loses a tool rather
+ * than granting one. The authenticated REST surface remains the auth, tenant,
+ * and field-write boundary.
+ *
+ * ## Why the table lives on the document, not in this module
+ *
+ * The lock must be shared by every registrar reachable from one page, which
+ * spans package boundaries (`smrt-web` and a UI layer) and therefore possibly
+ * more than one copy of this module — a second bundle chunk, a duplicated
+ * dependency, or an HMR reload that replaces module state while the host
+ * registry keeps every tool it already accepted. Module-level state loses the
+ * reservations in all of those cases, and a lost reservation is worse than no
+ * lock: it lets a duplicate through, or (on the release side) strands a name
+ * forever. The table is therefore stored on the `document` object itself under
+ * a cross-realm `Symbol.for` key, which every copy of this module resolves to
+ * the same slot.
+ *
+ * The table is additionally stamped with the `modelContext` it was built for.
+ * When a host installs a NEW model context on the same document — a fresh
+ * origin-trial registry, or a test harness swapping the double — every tool
+ * the old registry held is gone, so the table resets rather than stranding
+ * those names.
+ *
+ * This module is dependency-free by design (see the package's dependency-DAG
+ * guardrails) and ships as the `@happyvertical/smrt-web/webmcp-tool-names`
+ * entry so a UI layer can reserve its fixed tool names without pulling in the
+ * client-data engine.
+ */
+/** Which registration path holds a reserved WebMCP tool name. */
+export declare type WebMcpToolNameOwner = 'generated' | 'ui' | 'intent' | 'bespoke';
+
+/**
+ * The owner currently holding `name` on this document, or undefined. For
+ * diagnostics and tests; registration paths use
+ * {@link reserveWebMcpToolNames}, which is atomic.
+ */
+export declare function webMcpToolNameOwner(name: string, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameOwner | undefined;
+
+/** Releases every name one reservation holds. Idempotent. */
+export declare interface WebMcpToolNameReservation {
+    release(): void;
+}
+
 /**
  * One generated collection definition: everything needed to construct a client
  * collection over the generated REST surface. The `_row` property is a phantom

package/dist/index.js

@@ -1,3 +1,4 @@
-import { A as MAX_SMRT_WEB_DATA_QUERY_OFFSET, C as offlineOutbox, D as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, E as wipeDurableStore, F as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, I as executeSmrtWebDataQuery, L as normalizeSmrtWebDataQueryResult, M as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, N as MAX_SMRT_WEB_DATA_QUERY_ROWS, O as MAX_SMRT_WEB_DATA_QUERY_FACETS, P as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, R as runWrapMutation, S as getOutboxHandle, T as registerDurableResource, _ as createSmrtWebEventSubscriber, a as createSmrtWebClient, b as DEFAULT_PERSIST_DEBOUNCE_MS, c as newLocalId, d as unwrapListResult, f as validateSmrtWebClient, g as createUpdateState, h as registerWebMcpTools, i as createSmrtCollection, j as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, k as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, l as throwIfSmrtWebError, m as registerWebMcpBespokeTool, n as buildListQuery, o as getEngineCollection, p as registerViewIntent, r as createDefinitionFetchers, s as invalidateSmrtWebCollections, t as SmrtWebRequestError, u as unwrapItemResult, v as liveInvalidation, w as durableStoreNamespace, x as persistCollection, y as createSmrtWebQuery } from "./chunks/src-D1ZtD6Bt.js";
+import { A as MAX_SMRT_WEB_DATA_QUERY_OFFSET, C as offlineOutbox, D as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, E as wipeDurableStore, F as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, I as executeSmrtWebDataQuery, L as normalizeSmrtWebDataQueryResult, M as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, N as MAX_SMRT_WEB_DATA_QUERY_ROWS, O as MAX_SMRT_WEB_DATA_QUERY_FACETS, P as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, R as runWrapMutation, S as getOutboxHandle, T as registerDurableResource, _ as createSmrtWebEventSubscriber, a as createSmrtWebClient, b as DEFAULT_PERSIST_DEBOUNCE_MS, c as newLocalId, d as unwrapListResult, f as validateSmrtWebClient, g as createUpdateState, h as registerWebMcpTools, i as createSmrtCollection, j as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, k as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, l as throwIfSmrtWebError, m as registerWebMcpBespokeTool, n as buildListQuery, o as getEngineCollection, p as registerViewIntent, r as createDefinitionFetchers, s as invalidateSmrtWebCollections, t as SmrtWebRequestError, u as unwrapItemResult, v as liveInvalidation, w as durableStoreNamespace, x as persistCollection, y as createSmrtWebQuery } from "./chunks/src-DHH8ptH8.js";
 import { n as compileViewIntentToolSpec, o as viewIntentToolName } from "./chunks/intents-BUTyN7YQ.js";
-export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, compileViewIntentToolSpec, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, invalidateSmrtWebCollections, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools, runWrapMutation, throwIfSmrtWebError, unwrapItemResult, unwrapListResult, validateSmrtWebClient, viewIntentToolName, wipeDurableStore };
+import { WebMcpToolNameCollisionError, reserveWebMcpToolNames, webMcpToolNameOwner } from "./webmcp-tool-names.js";
+export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, WebMcpToolNameCollisionError, buildListQuery, compileViewIntentToolSpec, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, invalidateSmrtWebCollections, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools, reserveWebMcpToolNames, runWrapMutation, throwIfSmrtWebError, unwrapItemResult, unwrapListResult, validateSmrtWebClient, viewIntentToolName, webMcpToolNameOwner, wipeDurableStore };

package/dist/webmcp-tool-names.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Reserve `names` for `owner` against the document's WebMCP registry.
+ *
+ * Reservation is ALL-OR-NOTHING: if any name is already held — by this path
+ * or another — nothing is reserved and a {@link WebMcpToolNameCollisionError}
+ * naming the colliding name and its current owner is thrown synchronously,
+ * before any tool reaches `document.modelContext`. Duplicates within `names`
+ * itself collide the same way.
+ *
+ * Off-WebMCP (no document) the call is a no-op returning an inert
+ * reservation, matching every registrar's own no-op guarantee.
+ *
+ * A reservation releases only the names it took: `release()` never drops a
+ * name a later reservation has since acquired, so a dispose that lands after
+ * a same-name re-registration cannot revoke the new holder's claim.
+ */
+export declare function reserveWebMcpToolNames(names: readonly string[], owner: WebMcpToolNameOwner, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameReservation;
+
+export declare interface ReserveWebMcpToolNamesOptions {
+    /**
+     * The document whose `modelContext` the names are registered against.
+     * Defaults to `globalThis.document`. Registrars that accept an injectable
+     * document (tests, non-window hosts) must pass the SAME object they read
+     * `modelContext` from, or their reservations land in a different table.
+     */
+    document?: unknown;
+}
+
+/**
+ * Thrown synchronously when a name is already held. Carries the colliding
+ * name and the owner that holds it so a host can report both without parsing
+ * the message.
+ */
+export declare class WebMcpToolNameCollisionError extends Error {
+    readonly toolName: string;
+    /** The path that already holds {@link toolName}. */
+    readonly owner: WebMcpToolNameOwner;
+    /** The path that tried to take it. */
+    readonly requestedBy: WebMcpToolNameOwner;
+    constructor(toolName: string, 
+    /** The path that already holds {@link toolName}. */
+    owner: WebMcpToolNameOwner, 
+    /** The path that tried to take it. */
+    requestedBy: WebMcpToolNameOwner);
+}
+
+/**
+ * Document-global WebMCP tool-name lock (#2613).
+ *
+ * A browser tool name is derived independently on three paths that all end at
+ * the same `document.modelContext`:
+ *
+ * 1. **generated** model tools — `<namespace>_<model>_<action>`, built by
+ *    `registerWebMcpTools` from the exposure policy;
+ * 2. **ui** — the six fixed `smrt_ui_*` tools a UI layer registers under a
+ *    configurable prefix (`registerWebMcpUiTools` in `@happyvertical/smrt-svelte`);
+ * 3. **intent** / **bespoke** — declared view intents (#2588) and hand-written
+ *    `useWebMcpTool` tools, whose names come from the declaration `id` or the
+ *    spec `name`.
+ *
+ * None of the three can see the others at declaration time: a namespace and a
+ * UI prefix are runtime values a declaration never sees. `registerWebMcpTools`
+ * rejects duplicates WITHIN its own prospective set, but nothing checked
+ * ACROSS the paths, so a collision reached the host — which rejects the later
+ * registration and leaves the tool silently absent.
+ *
+ * This module is the shared reservation table those paths coordinate through.
+ * It is an AVAILABILITY guard, not a trust boundary: every path stays
+ * fail-closed and browser-only regardless, and a collision loses a tool rather
+ * than granting one. The authenticated REST surface remains the auth, tenant,
+ * and field-write boundary.
+ *
+ * ## Why the table lives on the document, not in this module
+ *
+ * The lock must be shared by every registrar reachable from one page, which
+ * spans package boundaries (`smrt-web` and a UI layer) and therefore possibly
+ * more than one copy of this module — a second bundle chunk, a duplicated
+ * dependency, or an HMR reload that replaces module state while the host
+ * registry keeps every tool it already accepted. Module-level state loses the
+ * reservations in all of those cases, and a lost reservation is worse than no
+ * lock: it lets a duplicate through, or (on the release side) strands a name
+ * forever. The table is therefore stored on the `document` object itself under
+ * a cross-realm `Symbol.for` key, which every copy of this module resolves to
+ * the same slot.
+ *
+ * The table is additionally stamped with the `modelContext` it was built for.
+ * When a host installs a NEW model context on the same document — a fresh
+ * origin-trial registry, or a test harness swapping the double — every tool
+ * the old registry held is gone, so the table resets rather than stranding
+ * those names.
+ *
+ * This module is dependency-free by design (see the package's dependency-DAG
+ * guardrails) and ships as the `@happyvertical/smrt-web/webmcp-tool-names`
+ * entry so a UI layer can reserve its fixed tool names without pulling in the
+ * client-data engine.
+ */
+/** Which registration path holds a reserved WebMCP tool name. */
+export declare type WebMcpToolNameOwner = 'generated' | 'ui' | 'intent' | 'bespoke';
+
+/**
+ * The owner currently holding `name` on this document, or undefined. For
+ * diagnostics and tests; registration paths use
+ * {@link reserveWebMcpToolNames}, which is atomic.
+ */
+export declare function webMcpToolNameOwner(name: string, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameOwner | undefined;
+
+/** Releases every name one reservation holds. Idempotent. */
+export declare interface WebMcpToolNameReservation {
+    release(): void;
+}
+
+export { }

package/dist/webmcp-tool-names.js

@@ -0,0 +1,73 @@
+//#region src/webmcp-tool-names.ts
+var WebMcpToolNameCollisionError = class extends Error {
+	constructor(toolName, owner, requestedBy) {
+		super(`WebMCP tool name "${toolName}" is already registered by the ${owner} path; the ${requestedBy} path cannot register it. Rename the ${requestedBy} tool, or give the generated tools a webmcp namespace / the UI tools a different prefix.`);
+		this.toolName = toolName;
+		this.owner = owner;
+		this.requestedBy = requestedBy;
+		this.name = "WebMcpToolNameCollisionError";
+	}
+	toolName;
+	owner;
+	requestedBy;
+};
+var TABLE_KEY = /* @__PURE__ */ Symbol.for("@happyvertical/smrt-web:webmcp-tool-names");
+var INERT_RESERVATION = { release: () => {} };
+function resolveDocument(documentLike) {
+	const doc = documentLike ?? globalThis.document ?? void 0;
+	return doc && typeof doc === "object" ? doc : void 0;
+}
+function tableFor(doc) {
+	const slot = doc;
+	const modelContext = doc.modelContext;
+	const existing = slot[TABLE_KEY];
+	if (existing && existing.modelContext === modelContext) return existing;
+	const table = {
+		modelContext,
+		names: /* @__PURE__ */ new Map()
+	};
+	Object.defineProperty(doc, TABLE_KEY, {
+		value: table,
+		configurable: true,
+		enumerable: false,
+		writable: true
+	});
+	return table;
+}
+function reserveWebMcpToolNames(names, owner, options = {}) {
+	const doc = resolveDocument(options.document);
+	if (!doc) return INERT_RESERVATION;
+	const table = tableFor(doc);
+	const token = {};
+	const taken = [];
+	const drop = () => {
+		for (const name of taken) if (table.names.get(name)?.token === token) table.names.delete(name);
+	};
+	for (const name of names) {
+		const held = table.names.get(name);
+		if (held) {
+			drop();
+			throw new WebMcpToolNameCollisionError(name, held.owner, owner);
+		}
+		table.names.set(name, {
+			owner,
+			token
+		});
+		taken.push(name);
+	}
+	let released = false;
+	return { release: () => {
+		if (released) return;
+		released = true;
+		drop();
+	} };
+}
+function webMcpToolNameOwner(name, options = {}) {
+	const doc = resolveDocument(options.document);
+	if (!doc) return void 0;
+	return tableFor(doc).names.get(name)?.owner;
+}
+//#endregion
+export { WebMcpToolNameCollisionError, reserveWebMcpToolNames, webMcpToolNameOwner };
+
+//# sourceMappingURL=webmcp-tool-names.js.map

package/dist/webmcp-tool-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp-tool-names.js","names":[],"sources":["../src/webmcp-tool-names.ts"],"sourcesContent":["/**\n * Document-global WebMCP tool-name lock (#2613).\n *\n * A browser tool name is derived independently on three paths that all end at\n * the same `document.modelContext`:\n *\n * 1. **generated** model tools — `<namespace>_<model>_<action>`, built by\n *    `registerWebMcpTools` from the exposure policy;\n * 2. **ui** — the six fixed `smrt_ui_*` tools a UI layer registers under a\n *    configurable prefix (`registerWebMcpUiTools` in `@happyvertical/smrt-svelte`);\n * 3. **intent** / **bespoke** — declared view intents (#2588) and hand-written\n *    `useWebMcpTool` tools, whose names come from the declaration `id` or the\n *    spec `name`.\n *\n * None of the three can see the others at declaration time: a namespace and a\n * UI prefix are runtime values a declaration never sees. `registerWebMcpTools`\n * rejects duplicates WITHIN its own prospective set, but nothing checked\n * ACROSS the paths, so a collision reached the host — which rejects the later\n * registration and leaves the tool silently absent.\n *\n * This module is the shared reservation table those paths coordinate through.\n * It is an AVAILABILITY guard, not a trust boundary: every path stays\n * fail-closed and browser-only regardless, and a collision loses a tool rather\n * than granting one. The authenticated REST surface remains the auth, tenant,\n * and field-write boundary.\n *\n * ## Why the table lives on the document, not in this module\n *\n * The lock must be shared by every registrar reachable from one page, which\n * spans package boundaries (`smrt-web` and a UI layer) and therefore possibly\n * more than one copy of this module — a second bundle chunk, a duplicated\n * dependency, or an HMR reload that replaces module state while the host\n * registry keeps every tool it already accepted. Module-level state loses the\n * reservations in all of those cases, and a lost reservation is worse than no\n * lock: it lets a duplicate through, or (on the release side) strands a name\n * forever. The table is therefore stored on the `document` object itself under\n * a cross-realm `Symbol.for` key, which every copy of this module resolves to\n * the same slot.\n *\n * The table is additionally stamped with the `modelContext` it was built for.\n * When a host installs a NEW model context on the same document — a fresh\n * origin-trial registry, or a test harness swapping the double — every tool\n * the old registry held is gone, so the table resets rather than stranding\n * those names.\n *\n * This module is dependency-free by design (see the package's dependency-DAG\n * guardrails) and ships as the `@happyvertical/smrt-web/webmcp-tool-names`\n * entry so a UI layer can reserve its fixed tool names without pulling in the\n * client-data engine.\n */\n\n/** Which registration path holds a reserved WebMCP tool name. */\nexport type WebMcpToolNameOwner = 'generated' | 'ui' | 'intent' | 'bespoke';\n\n/**\n * Thrown synchronously when a name is already held. Carries the colliding\n * name and the owner that holds it so a host can report both without parsing\n * the message.\n */\nexport class WebMcpToolNameCollisionError extends Error {\n  constructor(\n    readonly toolName: string,\n    /** The path that already holds {@link toolName}. */\n    readonly owner: WebMcpToolNameOwner,\n    /** The path that tried to take it. */\n    readonly requestedBy: WebMcpToolNameOwner,\n  ) {\n    super(\n      `WebMCP tool name \"${toolName}\" is already registered by the ${owner} path; the ${requestedBy} path cannot register it. Rename the ${requestedBy} tool, or give the generated tools a webmcp namespace / the UI tools a different prefix.`,\n    );\n    this.name = 'WebMcpToolNameCollisionError';\n  }\n}\n\n/** Releases every name one reservation holds. Idempotent. */\nexport interface WebMcpToolNameReservation {\n  release(): void;\n}\n\nexport interface ReserveWebMcpToolNamesOptions {\n  /**\n   * The document whose `modelContext` the names are registered against.\n   * Defaults to `globalThis.document`. Registrars that accept an injectable\n   * document (tests, non-window hosts) must pass the SAME object they read\n   * `modelContext` from, or their reservations land in a different table.\n   */\n  document?: unknown;\n}\n\n/** A held name plus the token identifying the reservation that holds it. */\ninterface HeldName {\n  owner: WebMcpToolNameOwner;\n  token: object;\n}\n\ninterface ToolNameTable {\n  /** The model context these reservations were taken against. */\n  modelContext: unknown;\n  names: Map<string, HeldName>;\n}\n\nconst TABLE_KEY = Symbol.for('@happyvertical/smrt-web:webmcp-tool-names');\n\nconst INERT_RESERVATION: WebMcpToolNameReservation = { release: () => {} };\n\nfunction resolveDocument(documentLike: unknown): object | undefined {\n  const doc =\n    documentLike ??\n    (globalThis as { document?: unknown }).document ??\n    undefined;\n  return doc && typeof doc === 'object' ? (doc as object) : undefined;\n}\n\nfunction tableFor(doc: object): ToolNameTable {\n  const slot = doc as Record<symbol, ToolNameTable | undefined>;\n  const modelContext = (doc as { modelContext?: unknown }).modelContext;\n  const existing = slot[TABLE_KEY];\n  // A replaced model context means the host registry that held the old\n  // reservations no longer exists; start clean rather than stranding names.\n  if (existing && existing.modelContext === modelContext) return existing;\n  const table: ToolNameTable = { modelContext, names: new Map() };\n  Object.defineProperty(doc, TABLE_KEY, {\n    value: table,\n    configurable: true,\n    enumerable: false,\n    writable: true,\n  });\n  return table;\n}\n\n/**\n * Reserve `names` for `owner` against the document's WebMCP registry.\n *\n * Reservation is ALL-OR-NOTHING: if any name is already held — by this path\n * or another — nothing is reserved and a {@link WebMcpToolNameCollisionError}\n * naming the colliding name and its current owner is thrown synchronously,\n * before any tool reaches `document.modelContext`. Duplicates within `names`\n * itself collide the same way.\n *\n * Off-WebMCP (no document) the call is a no-op returning an inert\n * reservation, matching every registrar's own no-op guarantee.\n *\n * A reservation releases only the names it took: `release()` never drops a\n * name a later reservation has since acquired, so a dispose that lands after\n * a same-name re-registration cannot revoke the new holder's claim.\n */\nexport function reserveWebMcpToolNames(\n  names: readonly string[],\n  owner: WebMcpToolNameOwner,\n  options: ReserveWebMcpToolNamesOptions = {},\n): WebMcpToolNameReservation {\n  const doc = resolveDocument(options.document);\n  if (!doc) return INERT_RESERVATION;\n\n  const table = tableFor(doc);\n  const token = {};\n  const taken: string[] = [];\n  const drop = (): void => {\n    for (const name of taken) {\n      // Only ever drop a name this reservation still holds. Together with the\n      // `released` latch below, a stale handle can neither release twice nor\n      // revoke a claim a later reservation has since taken under the same name.\n      if (table.names.get(name)?.token === token) table.names.delete(name);\n    }\n  };\n\n  for (const name of names) {\n    const held = table.names.get(name);\n    if (held) {\n      // All-or-nothing: give back everything taken so far, so a rejected\n      // reservation leaves no name stranded and the caller can retry with a\n      // corrected set.\n      drop();\n      throw new WebMcpToolNameCollisionError(name, held.owner, owner);\n    }\n    table.names.set(name, { owner, token });\n    taken.push(name);\n  }\n\n  let released = false;\n  return {\n    release: () => {\n      if (released) return;\n      released = true;\n      drop();\n    },\n  };\n}\n\n/**\n * The owner currently holding `name` on this document, or undefined. For\n * diagnostics and tests; registration paths use\n * {@link reserveWebMcpToolNames}, which is atomic.\n */\nexport function webMcpToolNameOwner(\n  name: string,\n  options: ReserveWebMcpToolNamesOptions = {},\n): WebMcpToolNameOwner | undefined {\n  const doc = resolveDocument(options.document);\n  if (!doc) return undefined;\n  return tableFor(doc).names.get(name)?.owner;\n}\n"],"mappings":";AA2DO,IAAM,+BAAN,cAA2C,MAAM;CACtD,YACW,UAEA,OAEA,aACT;EACA,MACE,qBAAqB,SAAQ,iCAAkC,MAAK,aAAc,YAAW,uCAAwC,YAAW,yFAClJ;EARS,KAAA,WAAA;EAEA,KAAA,QAAA;EAEA,KAAA,cAAA;EAKT,KAAK,OAAO;CACd;CAVW;CAEA;CAEA;AAOb;AA6BA,IAAM,YAAY,uBAAO,IAAI,2CAA2C;AAExE,IAAM,oBAA+C,EAAE,eAAe,CAAC,EAAE;AAEzE,SAAS,gBAAgB,cAA2C;CAClE,MAAM,MACJ,gBACC,WAAsC,YACvC,KAAA;CACF,OAAO,OAAO,OAAO,QAAQ,WAAY,MAAiB,KAAA;AAC5D;AAEA,SAAS,SAAS,KAA4B;CAC5C,MAAM,OAAO;CACb,MAAM,eAAgB,IAAmC;CACzD,MAAM,WAAW,KAAK;CAGtB,IAAI,YAAY,SAAS,iBAAiB,cAAc,OAAO;CAC/D,MAAM,QAAuB;EAAE;EAAc,uBAAO,IAAI,IAAI;CAAE;CAC9D,OAAO,eAAe,KAAK,WAAW;EACpC,OAAO;EACP,cAAc;EACd,YAAY;EACZ,UAAU;CACZ,CAAC;CACD,OAAO;AACT;AAkBO,SAAS,uBACd,OACA,OACA,UAAyC,CAAC,GACf;CAC3B,MAAM,MAAM,gBAAgB,QAAQ,QAAQ;CAC5C,IAAI,CAAC,KAAK,OAAO;CAEjB,MAAM,QAAQ,SAAS,GAAG;CAC1B,MAAM,QAAQ,CAAC;CACf,MAAM,QAAkB,CAAC;CACzB,MAAM,aAAmB;EACvB,KAAA,MAAW,QAAQ,OAIjB,IAAI,MAAM,MAAM,IAAI,IAAI,CAAA,EAAG,UAAU,OAAO,MAAM,MAAM,OAAO,IAAI;CAEvE;CAEA,KAAA,MAAW,QAAQ,OAAO;EACxB,MAAM,OAAO,MAAM,MAAM,IAAI,IAAI;EACjC,IAAI,MAAM;GAIR,KAAK;GACL,MAAM,IAAI,6BAA6B,MAAM,KAAK,OAAO,KAAK;EAChE;EACA,MAAM,MAAM,IAAI,MAAM;GAAE;GAAO;EAAM,CAAC;EACtC,MAAM,KAAK,IAAI;CACjB;CAEA,IAAI,WAAW;CACf,OAAO,EACL,eAAe;EACb,IAAI,UAAU;EACd,WAAW;EACX,KAAK;CACP,EACF;AACF;AAOO,SAAS,oBACd,MACA,UAAyC,CAAC,GACT;CACjC,MAAM,MAAM,gBAAgB,QAAQ,QAAQ;CAC5C,IAAI,CAAC,KAAK,OAAO,KAAA;CACjB,OAAO,SAAS,GAAG,CAAA,CAAE,MAAM,IAAI,IAAI,CAAA,EAAG;AACxC"}

package/dist/webmcp.d.ts

@@ -13,6 +13,16 @@
  * `compileViewIntentToolSpec` from `intent.target`. No author-supplied code
  * runs, and the only thing it can do is dispatch one browser registry
  * command — the runtime half of the no-REST invariant.
+ *
+ * The intent's derived tool name is claimed against the document-global
+ * tool-name lock (#2613), so an id whose flattened name collides with a
+ * generated model tool or a fixed UI tool throws
+ * {@link WebMcpToolNameCollisionError} here rather than silently losing the
+ * tool at the host. `defineIntent`'s own intent-vs-intent check cannot see
+ * either, because both depend on a runtime `namespace` / `prefix` the
+ * declaration never sees.
+ *
+ * @throws {WebMcpToolNameCollisionError} when the derived name is already held.
  */
 export declare function registerViewIntent(intent: ViewIntent, binding: ViewIntentBinding, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
 
@@ -26,9 +36,19 @@ export declare function registerViewIntent(intent: ViewIntent, binding: ViewInte
  * `maxTools` are out of scope for a bespoke tool; see
  * {@link RegisterWebMcpBespokeToolOptions}.
  *
+ * The tool's name is also claimed against the
+ * document-global tool-name lock before the browser sees it. A name a
+ * generated model tool, a fixed UI tool, or another live bespoke tool /
+ * intent already holds throws {@link WebMcpToolNameCollisionError}
+ * SYNCHRONOUSLY, naming the colliding name and the owner that holds it.
+ * Previously the host accepted the call and silently dropped the losing
+ * registration. Disposing releases the name, so register/dispose/re-register
+ * under one name still succeeds.
+ *
  * @returns a disposer that deregisters the tool this call registered (a
  * no-op double-call). On a browser without WebMCP, or when policy excludes
  * the tool's effect, the call is a no-op and the disposer is inert.
+ * @throws {WebMcpToolNameCollisionError} when the name is already held.
  */
 export declare function registerWebMcpBespokeTool(spec: WebMcpBespokeToolSpec, options?: RegisterWebMcpBespokeToolOptions): WebMcpRegistrationDisposer;
 
@@ -41,13 +61,36 @@ export declare interface RegisterWebMcpBespokeToolOptions {
      * an unrelated generated tool set fail to register.
      */
     effects?: readonly WebMcpToolEffect[];
+    /**
+     * Which path this registration belongs to, used ONLY to label its
+     * tool-name reservation (#2613) so a later collision names the right
+     * source. Defaults to `bespoke`.
+     *
+     * A UI-framework binding that compiles a declared view intent itself and
+     * registers it here — rather than through {@link registerViewIntent} —
+     * must pass `'intent'`. `useViewIntent` in `@happyvertical/smrt-svelte`
+     * does exactly that, because reusing `useWebMcpTool`'s single WebMCP
+     * lifecycle is a documented invariant of that package; without this it
+     * would be the only shipped intent path and every intent collision would
+     * blame a `useWebMcpTool` call that does not exist.
+     *
+     * Purely a diagnostic label: it grants no capability, narrows no policy,
+     * and changes nothing about how the tool registers or executes.
+     */
+    owner?: Extract<WebMcpToolNameOwner, 'intent' | 'bespoke'>;
 }
 
 /**
  * Register every collection's generated tool descriptors with WebMCP.
  *
+ * Every selected tool name is claimed against the document-global tool-name
+ * lock (#2613) before the first browser registration, so a collision with a
+ * UI-layer or bespoke tool throws {@link WebMcpToolNameCollisionError} with
+ * the offending name and its current owner instead of reaching the host.
+ *
  * @returns a disposer that deregisters all tools this call registered. On a
  * browser without WebMCP the call is a no-op and the disposer is inert.
+ * @throws {WebMcpToolNameCollisionError} when a selected name is already held.
  */
 export declare function registerWebMcpTools(definitions: readonly WebMcpRegistrationDefinition[], options?: RegisterWebMcpToolsOptions): WebMcpRegistrationDisposer;
 
@@ -78,6 +121,34 @@ export declare interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy
     filterTool?: (definition: WebMcpToolDefinition) => boolean;
 }
 
+/**
+ * Reserve `names` for `owner` against the document's WebMCP registry.
+ *
+ * Reservation is ALL-OR-NOTHING: if any name is already held — by this path
+ * or another — nothing is reserved and a {@link WebMcpToolNameCollisionError}
+ * naming the colliding name and its current owner is thrown synchronously,
+ * before any tool reaches `document.modelContext`. Duplicates within `names`
+ * itself collide the same way.
+ *
+ * Off-WebMCP (no document) the call is a no-op returning an inert
+ * reservation, matching every registrar's own no-op guarantee.
+ *
+ * A reservation releases only the names it took: `release()` never drops a
+ * name a later reservation has since acquired, so a dispose that lands after
+ * a same-name re-registration cannot revoke the new holder's claim.
+ */
+export declare function reserveWebMcpToolNames(names: readonly string[], owner: WebMcpToolNameOwner, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameReservation;
+
+declare interface ReserveWebMcpToolNamesOptions {
+    /**
+     * The document whose `modelContext` the names are registered against.
+     * Defaults to `globalThis.document`. Registrars that accept an injectable
+     * document (tests, non-window hosts) must pass the SAME object they read
+     * `modelContext` from, or their reservations land in a different table.
+     */
+    document?: unknown;
+}
+
 /**
  * The per-collection CRUD surface of the generated REST client
  * (`createClient(basePath).<collection>` from `@happyvertical/smrt-virt-client`).
@@ -457,6 +528,89 @@ declare interface WebMcpToolDefinition extends WebToolDescriptor {
  */
 export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
 
+/**
+ * Thrown synchronously when a name is already held. Carries the colliding
+ * name and the owner that holds it so a host can report both without parsing
+ * the message.
+ */
+export declare class WebMcpToolNameCollisionError extends Error {
+    readonly toolName: string;
+    /** The path that already holds {@link toolName}. */
+    readonly owner: WebMcpToolNameOwner;
+    /** The path that tried to take it. */
+    readonly requestedBy: WebMcpToolNameOwner;
+    constructor(toolName: string, 
+    /** The path that already holds {@link toolName}. */
+    owner: WebMcpToolNameOwner, 
+    /** The path that tried to take it. */
+    requestedBy: WebMcpToolNameOwner);
+}
+
+/**
+ * Document-global WebMCP tool-name lock (#2613).
+ *
+ * A browser tool name is derived independently on three paths that all end at
+ * the same `document.modelContext`:
+ *
+ * 1. **generated** model tools — `<namespace>_<model>_<action>`, built by
+ *    `registerWebMcpTools` from the exposure policy;
+ * 2. **ui** — the six fixed `smrt_ui_*` tools a UI layer registers under a
+ *    configurable prefix (`registerWebMcpUiTools` in `@happyvertical/smrt-svelte`);
+ * 3. **intent** / **bespoke** — declared view intents (#2588) and hand-written
+ *    `useWebMcpTool` tools, whose names come from the declaration `id` or the
+ *    spec `name`.
+ *
+ * None of the three can see the others at declaration time: a namespace and a
+ * UI prefix are runtime values a declaration never sees. `registerWebMcpTools`
+ * rejects duplicates WITHIN its own prospective set, but nothing checked
+ * ACROSS the paths, so a collision reached the host — which rejects the later
+ * registration and leaves the tool silently absent.
+ *
+ * This module is the shared reservation table those paths coordinate through.
+ * It is an AVAILABILITY guard, not a trust boundary: every path stays
+ * fail-closed and browser-only regardless, and a collision loses a tool rather
+ * than granting one. The authenticated REST surface remains the auth, tenant,
+ * and field-write boundary.
+ *
+ * ## Why the table lives on the document, not in this module
+ *
+ * The lock must be shared by every registrar reachable from one page, which
+ * spans package boundaries (`smrt-web` and a UI layer) and therefore possibly
+ * more than one copy of this module — a second bundle chunk, a duplicated
+ * dependency, or an HMR reload that replaces module state while the host
+ * registry keeps every tool it already accepted. Module-level state loses the
+ * reservations in all of those cases, and a lost reservation is worse than no
+ * lock: it lets a duplicate through, or (on the release side) strands a name
+ * forever. The table is therefore stored on the `document` object itself under
+ * a cross-realm `Symbol.for` key, which every copy of this module resolves to
+ * the same slot.
+ *
+ * The table is additionally stamped with the `modelContext` it was built for.
+ * When a host installs a NEW model context on the same document — a fresh
+ * origin-trial registry, or a test harness swapping the double — every tool
+ * the old registry held is gone, so the table resets rather than stranding
+ * those names.
+ *
+ * This module is dependency-free by design (see the package's dependency-DAG
+ * guardrails) and ships as the `@happyvertical/smrt-web/webmcp-tool-names`
+ * entry so a UI layer can reserve its fixed tool names without pulling in the
+ * client-data engine.
+ */
+/** Which registration path holds a reserved WebMCP tool name. */
+export declare type WebMcpToolNameOwner = 'generated' | 'ui' | 'intent' | 'bespoke';
+
+/**
+ * The owner currently holding `name` on this document, or undefined. For
+ * diagnostics and tests; registration paths use
+ * {@link reserveWebMcpToolNames}, which is atomic.
+ */
+export declare function webMcpToolNameOwner(name: string, options?: ReserveWebMcpToolNamesOptions): WebMcpToolNameOwner | undefined;
+
+/** Releases every name one reservation holds. Idempotent. */
+export declare interface WebMcpToolNameReservation {
+    release(): void;
+}
+
 /**
  * One generated collection definition: everything needed to construct a client
  * collection over the generated REST surface. The `_row` property is a phantom

package/dist/webmcp.js

@@ -1,2 +1,3 @@
-import { h as registerWebMcpTools, m as registerWebMcpBespokeTool, p as registerViewIntent } from "./chunks/src-D1ZtD6Bt.js";
-export { registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools };
+import { h as registerWebMcpTools, m as registerWebMcpBespokeTool, p as registerViewIntent } from "./chunks/src-DHH8ptH8.js";
+import { WebMcpToolNameCollisionError, reserveWebMcpToolNames, webMcpToolNameOwner } from "./webmcp-tool-names.js";
+export { WebMcpToolNameCollisionError, registerViewIntent, registerWebMcpBespokeTool, registerWebMcpTools, reserveWebMcpToolNames, webMcpToolNameOwner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-web",
-  "version": "0.46.0",
+  "version": "0.47.1",
   "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
   "author": "HappyVertical",
   "type": "module",
@@ -24,6 +24,10 @@
     "./intents": {
       "types": "./dist/intents.d.ts",
       "import": "./dist/intents.js"
+    },
+    "./webmcp-tool-names": {
+      "types": "./dist/webmcp-tool-names.d.ts",
+      "import": "./dist/webmcp-tool-names.js"
     }
   },
   "dependencies": {
@@ -32,13 +36,13 @@
     "@tanstack/query-db-collection": "^1.0.46"
   },
   "devDependencies": {
+    "@happyvertical/smrt-core": "0.47.1",
+    "@happyvertical/smrt-scanner": "0.47.1",
     "@types/node": "24.13.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "5.9.3",
     "vite": "8.1.4",
-    "vitest": "4.1.10",
-    "@happyvertical/smrt-core": "0.46.0",
-    "@happyvertical/smrt-scanner": "0.46.0"
+    "vitest": "4.1.10"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",