@happyvertical/smrt-web 0.51.32 → 0.51.34

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

@@ -1,112 +1,106 @@
-/**
- * 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 { }
+/**
+ * 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 type WebMcpToolNameOwner = 'generated' | 'ui' | 'intent' | 'bespoke';
+/**
+ * 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);
+}
+/** Releases every name one reservation holds. Idempotent. */
+export interface WebMcpToolNameReservation {
+    release(): void;
+}
+export 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=webmcp-tool-names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp-tool-names.d.ts","sourceRoot":"","sources":["../src/webmcp-tool-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,mBAAmB;IACnC,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,mBAAmB;gBAJhC,QAAQ,EAAE,MAAM;IACzB,oDAAoD;IAC3C,KAAK,EAAE,mBAAmB;IACnC,sCAAsC;IAC7B,WAAW,EAAE,mBAAmB;CAO5C;AAED,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA2CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,6BAAkC,GAC1C,yBAAyB,CAqC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,6BAAkC,GAC1C,mBAAmB,GAAG,SAAS,CAIjC"}