@happyvertical/smrt-web 0.46.0 → 0.47.0

package/AGENTS.md

@@ -40,6 +40,7 @@ module you are editing. This file keeps what holds in every module.
 | `sse-client.ts` | the client half of live cache invalidation — the app-wide subscriber, the wire contract it consumes, and SSE-vs-polling behaviour | [agents/live-invalidation.md](agents/live-invalidation.md) |
 | `webmcp.ts` | framework-agnostic WebMCP registrar; validates an optionally bounded/namespaced, effect-filtered prospective set atomically, keeps legacy list-backed tools on collection state, and executes canonical tool-only definitions directly through REST fetchers. `registerWebMcpBespokeTool` is the single-tool sibling a UI layer's hand-written component tool routes through (`useWebMcpTool` in smrt-svelte, #2586): same fail-closed effect classification and `effects` policy, no `namespace`/`maxTools` | — |
 | `persistence/` + `update-state.ts` | the read-cache rehydrate capability and the framework-free `updateAvailable` primitive (bundle + contract signals) | [agents/version-persistence.md](agents/version-persistence.md) |
+| `webmcp-tool-names.ts` | the document-global tool-name lock every registration path reserves through (#2613). Dependency-free; ships as `@happyvertical/smrt-web/webmcp-tool-names` | see below |
 | `intents.ts` + `capability-classification.ts` | the framework-agnostic declarative view-intent contract, its declaration registry, and the one capability classification rule both it and `webmcp.ts` apply (#2587, #2588). Ships as the dependency-free `@happyvertical/smrt-web/intents` entry — importing it pulls no client-data engine | — |
 | `data-query.ts` | dependency-free browser mirror and defensive response normalizer for the canonical bounded data-query envelope (#2444) | — |
 | `remote-query.ts` | query-shaped remote pages over a `SmrtWebCollection`, with keyed stale cache, execution modes, cancellation/latest-query-wins, and optional query-scoped live subscriptions (#2445) | — |
@@ -172,15 +173,13 @@ declared intent derives, at the one place both are visible. Two such intents
 would otherwise fight over a single WebMCP tool name at mount, where the
 failure is a shadowed or rejected registration rather than a clear error.
 
-**Gotcha — that check covers intents only.** A derived name can still collide
-with a GENERATED model tool (`${model}_${action}`) or, under a custom
-`webmcp.ui.prefix`, with one of the six fixed UI tools. Neither is knowable at
-declaration time, because both depend on a runtime `namespace`/`prefix` the
-declaration never sees, and there is no document-global tool-name lock for
-bespoke registrations to participate in. Nothing escalates — an intent stays
-browser-only and fail-closed either way — but one registration silently
-shadows or loses to the other. Keep an intent's first id segment out of your
-model names, or give `registerWebMcpTools` a `namespace`.
+**That check covers intents only** — a derived name can still collide with a
+GENERATED model tool (`${model}_${action}`) or, under a custom
+`webmcp.ui.prefix`, with one of the six fixed UI tools, and neither is
+knowable at declaration time because both depend on a runtime
+`namespace`/`prefix` the declaration never sees. Those cross-path collisions
+are caught at REGISTRATION instead, by the document-global tool-name lock
+below (#2613).
 
 ### The no-REST invariant
 
@@ -195,6 +194,59 @@ tool's `execute` is then CONSTRUCTED by `compileViewIntentToolSpec` from
 declaration, it must be data, and it must be reachable by the scanner without
 evaluation.
 
+## The document-global tool-name lock (#2613)
+
+`webmcp-tool-names.ts` is the reservation table the three name-deriving paths
+coordinate through, and ships as the dependency-free
+`@happyvertical/smrt-web/webmcp-tool-names` entry so a UI layer can reserve
+its own names without pulling the client-data engine.
+
+The three paths do NOT share one registrar — verify this before assuming a
+funnel. `registerWebMcpTools` and `registerWebMcpUiTools` (in
+`@happyvertical/smrt-svelte`) each call `document.modelContext.registerTool`
+directly; only intents and `useWebMcpTool` route through
+`registerWebMcpBespokeTool`. So each path reserves for itself:
+
+| Path | Owner | Reserves in |
+|---|---|---|
+| generated model tools | `generated` | `registerWebMcpTools`, after selection/budget validation, before the first `registerTool` |
+| the six fixed `smrt_ui_*` tools | `ui` | `registerWebMcpUiTools` (`smrt-svelte`), after the prefix lock |
+| declared view intents | `intent` | `registerWebMcpBespokeTool`'s shared body — via `registerViewIntent`, or via `registerWebMcpBespokeTool` with `owner: 'intent'` |
+| bespoke `useWebMcpTool` tools | `bespoke` | the same shared body (the default owner) |
+
+Reservation is all-or-nothing and rejects a duplicate SYNCHRONOUSLY with
+`WebMcpToolNameCollisionError`, which carries the colliding name plus the
+owner holding it and the owner that asked. Previously the host rejected the
+later registration and the tool was silently absent. **This is a behavior
+change**: `registerWebMcpBespokeTool` and `registerViewIntent` now throw where
+they used to succeed-then-lose-the-tool.
+
+Rules for anything that adds a fourth path or edits an existing one:
+
+- **The table is keyed on the `document`, not on module state.** A registrar
+  with an injectable document must pass the SAME object it reads
+  `modelContext` from, or its reservations land in a different table. Module
+  state would fragment across bundle chunks, a duplicated dependency, and HMR;
+  the table is stored on the document under a `Symbol.for` key so every copy
+  of the module resolves to one slot. It is stamped with the `modelContext` it
+  was built for and resets when the host installs a new one, so tools the old
+  registry held never strand their names.
+- **Dispose must release**, or a mount/unmount cycle wedges the name
+  permanently — the failure mode #2595 already hit as a re-registration race.
+  A reservation releases only names it still holds.
+- **A tool the effects policy excluded reserves nothing**: it was never
+  registered, so its name stays available.
+- **A binding that compiles an intent itself must pass `owner: 'intent'`.**
+  `registerViewIntent` is not the shipped intent path: `useViewIntent` in
+  `@happyvertical/smrt-svelte` compiles the spec and hands it to
+  `useWebMcpTool`, because that package must not duplicate the WebMCP
+  lifecycle. Without the explicit owner every intent collision would report
+  `bespoke` and send an author looking for a `useWebMcpTool` call that does
+  not exist. The label is a diagnostic only — it grants nothing.
+- Consumer app code that registers directly against `document.modelContext`
+  (for example `packages/template-sveltekit`'s runtime-diagnostics tools) does
+  not participate and can still collide at the host.
+
 ## Reference consumer
 
 `packages/products` consumes the runtime as its reference store across npm,

package/README.md

@@ -131,7 +131,7 @@ core.
 | Persistence | `persistCollection`, `wipeDurableStore` |
 | Live updates | `createSmrtWebEventSubscriber`, `liveInvalidation` |
 | Version awareness | `createUpdateState` |
-| WebMCP | `registerWebMcpTools` |
+| WebMCP | `registerWebMcpTools`, `registerWebMcpBespokeTool`, `registerViewIntent`, `reserveWebMcpToolNames` |
 
 ## WebMCP capability exposure
 
@@ -191,6 +191,29 @@ collections. Their duplicate tool names or collection/action identities reject
 the registration atomically. Prefer the canonical set for complete generated
 coverage, or compose only disjoint legacy and canonical subsets.
 
+### Tool names are locked per document
+
+Generated model tools, the six fixed `smrt_ui_*` tools a UI layer registers
+under its own prefix, declared view intents, and hand-written bespoke tools all
+derive names independently and all end at one `document.modelContext`. None can
+see the others at declaration time, because a `namespace` and a UI `prefix` are
+runtime values.
+
+Every path reserves its names through a document-global lock before the browser
+sees them, so a cross-path collision is refused synchronously with a
+`WebMcpToolNameCollisionError` naming the tool and the owner holding it
+(`generated`, `ui`, `intent`, or `bespoke`). The browser used to reject the
+later registration and the tool was simply absent.
+
+Reservation is all-or-nothing, and disposing a registration releases its names,
+so a mount / unmount / remount cycle under one name keeps working. A UI layer
+that registers its own fixed tool set reserves through the dependency-free
+`@happyvertical/smrt-web/webmcp-tool-names` entry, passing the same `document`
+it reads `modelContext` from. A binding that compiles a declared view intent
+itself and registers it with `registerWebMcpBespokeTool` — rather than through
+`registerViewIntent` — passes `owner: 'intent'` so the diagnostic names the
+intent. The owner is a label only; it grants nothing.
+
 WebMCP policy controls which capabilities a page advertises; it is not an
 authorization boundary. Execution still uses the page's authenticated REST
 transport, whose auth, tenancy, writable-field, and sensitive-field guards must

package/dist/chunks/{src-D1ZtD6Bt.js → src-DHH8ptH8.js}

@@ -1,4 +1,5 @@
 import { c as capabilityAnnotations, l as resolveDeclaredCapability, n as compileViewIntentToolSpec, s as WEBMCP_TOOL_EFFECTS } from "./intents-BUTyN7YQ.js";
+import { reserveWebMcpToolNames } from "../webmcp-tool-names.js";
 import { createCollection } from "@tanstack/db";
 import { QueryClient } from "@tanstack/query-core";
 import { queryCollectionOptions } from "@tanstack/query-db-collection";
@@ -2127,11 +2128,13 @@ function registerWebMcpTools(definitions, options = {}) {
 	const controller = new AbortController();
 	const collections = /* @__PURE__ */ new Map();
 	const collectionFetchers = /* @__PURE__ */ new Map();
+	const reservation = reserveWebMcpToolNames(tools.map((tool) => tool.name), "generated");
 	let disposed = false;
 	const dispose = () => {
 		if (disposed) return;
 		disposed = true;
 		controller.abort();
+		reservation.release();
 		for (const collection of collections.values()) collection.cleanup().catch(() => void 0);
 	};
 	const registrations = [];
@@ -2196,16 +2199,22 @@ function registrationDisposer(dispose, ready) {
 	return Object.assign(dispose, { ready });
 }
 function registerWebMcpBespokeTool(spec, options = {}) {
+	return registerSingleTool(spec, options, options.owner ?? "bespoke");
+}
+function registerSingleTool(spec, options, owner) {
 	const { allowedEffects } = validateExposurePolicy(options);
 	const ctx = getModelContext();
 	if (!ctx) return registrationDisposer(() => {}, Promise.resolve());
 	const semantics = actionSemantics("bespoke", bespokeDeclaredSemantics(spec.annotations));
 	if (!allowedEffects.has(semantics.effect)) return registrationDisposer(() => {}, Promise.resolve());
+	const reservation = reserveWebMcpToolNames([spec.name], owner);
 	const controller = new AbortController();
 	let disposed = false;
 	const dispose = () => {
+		if (disposed) return;
 		disposed = true;
 		controller.abort();
+		reservation.release();
 	};
 	let registration;
 	try {
@@ -2231,7 +2240,7 @@ function registerWebMcpBespokeTool(spec, options = {}) {
 	return registrationDisposer(dispose, ready);
 }
 function registerViewIntent(intent, binding, options = {}) {
-	return registerWebMcpBespokeTool(compileViewIntentToolSpec(intent, binding), options);
+	return registerSingleTool(compileViewIntentToolSpec(intent, binding), options, "intent");
 }
 var VALID_EFFECTS = WEBMCP_TOOL_EFFECTS;
 var NAMESPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -3030,4 +3039,4 @@ function createSmrtCollection(definition, options) {
 //#endregion
 export { MAX_SMRT_WEB_DATA_QUERY_OFFSET as A, offlineOutbox as C, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as D, wipeDurableStore as E, MAX_SMRT_WEB_DATA_QUERY_WARNINGS as F, executeSmrtWebDataQuery as I, normalizeSmrtWebDataQueryResult as L, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as M, MAX_SMRT_WEB_DATA_QUERY_ROWS as N, MAX_SMRT_WEB_DATA_QUERY_FACETS as O, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as P, runWrapMutation as R, getOutboxHandle as S, registerDurableResource as T, createSmrtWebEventSubscriber as _, createSmrtWebClient as a, DEFAULT_PERSIST_DEBOUNCE_MS as b, newLocalId as c, unwrapListResult as d, validateSmrtWebClient as f, createUpdateState as g, registerWebMcpTools as h, createSmrtCollection as i, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as j, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as k, throwIfSmrtWebError as l, registerWebMcpBespokeTool as m, buildListQuery as n, getEngineCollection as o, registerViewIntent as p, createDefinitionFetchers as r, invalidateSmrtWebCollections as s, SmrtWebRequestError as t, unwrapItemResult as u, liveInvalidation as v, durableStoreNamespace as w, persistCollection as x, createSmrtWebQuery as y };
 
-//# sourceMappingURL=src-D1ZtD6Bt.js.map
+//# sourceMappingURL=src-DHH8ptH8.js.map