@happyvertical/smrt-web 0.51.32 → 0.51.34

package/dist/webmcp.d.ts

@@ -1,653 +1,193 @@
-/**
- * Register one declared view intent (#2588) against a mounted registry
- * binding, for as long as the returned disposer is not called.
- *
- * This is the ONLY way an intent reaches the browser, and it goes through
- * {@link registerWebMcpBespokeTool}, so an intent inherits the same
- * fail-closed `effects` exposure policy as a generated model tool. The
- * intent's classification was resolved at declaration time by the shared
- * rule, and the hints `compileViewIntentToolSpec` emits round-trip through
- * the bespoke registrar's own re-resolution unchanged.
- *
- * The `execute` registered here is constructed by
- * `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;
-
-/**
- * Register one hand-written browser tool through the same fail-closed effect
- * classification and `effects` exposure policy as {@link registerWebMcpTools}
- * (#2586). A tool with no `annotations`, or with annotations that leave its
- * effect undeclared, classifies destructive/non-idempotent/open-world — the
- * same default `actionSemantics` gives an undeclared custom model action —
- * and is excluded unless the policy allows `destructive`. `namespace` and
- * `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;
-
-export declare interface RegisterWebMcpBespokeToolOptions {
-    /**
-     * Allowed effects. Omitted means read-only exposure — the same default as
-     * {@link registerWebMcpTools}. `namespace` and `maxTools` deliberately do
-     * not apply to a bespoke tool (#2586): a component author already chose a
-     * stable name, and counting one intent against a shared budget could make
-     * 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;
-
-export declare interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy {
-    /** REST base path for the fetchers (default `/api/v1`). */
-    basePath?: string;
-    /** Injectable fetch (tests / SSR-safe wrappers). */
-    fetchFn?: typeof fetch;
-    /** Shared smrt-web cache handle used by page collections. */
-    client?: SmrtWebClient;
-    /** Optional cache scope matching the page collection's scope. */
-    scope?: string;
-    /**
-     * Override how a definition's CRUD fetchers are built. Defaults to
-     * {@link createDefinitionFetchers}; the primary seam for testing `execute`
-     * without a live server.
-     */
-    resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
-    /**
-     * Override direct REST fetchers for a canonical tool-only definition.
-     * Fetchers are optional because a get-only or custom-action-only model does
-     * not have a list or create route.
-     */
-    resolveToolFetchers?: (definition: WebMcpToolDefinition) => Partial<SmrtCrudFetchers>;
-    /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
-    filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
-    /** Predicate for canonical per-tool definitions. */
-    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`).
- *
- * Return types are `unknown` on purpose: generated fetchers resolve with
- * whatever the server sent, so this package normalizes and validates payloads
- * centrally — see {@link unwrapListResult} / {@link unwrapItemResult}.
- */
-declare interface SmrtCrudFetchers {
-    list(params?: Record<string, unknown>): Promise<unknown>;
-    get?(id: string): Promise<unknown>;
-    create(data: Record<string, unknown>): Promise<unknown>;
-    update?(id: string, data: Record<string, unknown>): Promise<unknown>;
-    delete?(id: string): Promise<unknown>;
-    /** Invoke a generated custom action route. */
-    custom?(action: string, args: Record<string, unknown>, route?: SmrtWebToolRouteDescriptor): Promise<unknown>;
-}
-
-/**
- * Opaque handle to the shared client cache / request-dedup layer. Create one
- * with {@link createSmrtWebClient} and pass the SAME instance to every
- * collection that should share a cache and deduplicate in-flight requests.
- *
- * The engine (currently a TanStack Query client) is intentionally hidden behind
- * this brand so it stays swappable — do not depend on its concrete shape.
- */
-declare interface SmrtWebClient {
-    /** Phantom brand — this handle wraps the hidden client-cache engine. */
-    readonly __smrtWebClient: 'SmrtWebClient';
-}
-
-declare interface SmrtWebCollectionDefinition<TData extends object = object> {
-    /** REST collection name (e.g. `products`). */
-    name: string;
-    /**
-     * Canonical qualified model identity (e.g.
-     * `@happyvertical/smrt-products:Product`). Generated definitions always
-     * provide it; optional here for source compatibility with manual literals
-     * authored before policy-aware web collections.
-     */
-    objectRef?: string;
-    /** Source class name (e.g. `Product`). */
-    className: string;
-    /** Path under the API base path (e.g. `/products`). */
-    endpoint: string;
-    /** Primary key field name (`id` for SmrtObject). */
-    idField: string;
-    /** CRUD + custom actions exposed by the api decorator config. */
-    actions: string[];
-    /**
-     * WebMCP/MCP tool descriptors for the exposed actions (#1812). Optional so
-     * hand-built definitions (older codegen, tests) still satisfy the type; a
-     * missing value means "no WebMCP tools to register".
-     */
-    toolDescriptors?: WebToolDescriptor[];
-    /** Persisted field metadata keyed by field name. */
-    fields: Record<string, SmrtWebFieldDefinition>;
-    /**
-     * Manifest-derived relationship edges to sibling REST collections. Drives
-     * relationship-derived cache invalidation: a settled mutation on this
-     * collection invalidates the caches of the collections these edges name.
-     * Optional so hand-built definitions (older codegen, tests) still satisfy the
-     * type; a missing value means "no derived edges".
-     */
-    relationships?: SmrtWebRelationship[];
-    /** Phantom row-type carrier — never present at runtime. */
-    _row?: TData;
-}
-
-/**
- * Field metadata emitted per column by the `@happyvertical/smrt-virt-web`
- * virtual module (generated from the package manifest).
- */
-declare interface SmrtWebFieldDefinition {
-    type: SmrtWebFieldType;
-    required?: boolean;
-    /** Whether the public field contract explicitly permits `null`. */
-    nullable?: boolean;
-    default?: unknown;
-    /** Developer-authored `@field({ description })` (#2046) — end-user help seed. */
-    description?: string;
-    /** Static `@field({ ui })` hints (#2046). */
-    ui?: SmrtWebFieldUIHints;
-}
-
-/**
- * The field types core's web-collection emission actually produces —
- * relationship pseudo-columns (`oneToMany`/`manyToMany`) and STI `meta`
- * internals never reach an emitted definition. Textual mirror of core's
- * `WebFieldType` (this package is deliberately smrt-dependency-free, so it
- * cannot import the source type); the four co-managed sites are core's
- * runtime type, the ambient virt-web d.ts, the physical `@smrt/web` d.ts,
- * and this mirror.
- */
-declare type SmrtWebFieldType = 'text' | 'decimal' | 'boolean' | 'integer' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
-
-/** Static `@field({ ui })` hints (#2046) — the field-policy rail seed. */
-declare interface SmrtWebFieldUIHints {
-    basic?: boolean;
-    group?: string;
-    order?: number;
-    locked?: boolean;
-}
-
-/**
- * A manifest-derived edge from this collection to a sibling REST collection,
- * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation
- * on this collection settles, the caches of the collections named by these
- * edges are invalidated (relationship-derived invalidation, #1761), so a
- * dependent view refetches without any hand-wired cache key.
- *
- * SMRT-owned data — no client-engine (`@tanstack/*`) type appears here, so it
- * stays inside the engine-absorption boundary.
- */
-declare interface SmrtWebRelationship {
-    /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */
-    field: string;
-    /** The relationship kind, mirroring the manifest field type. */
-    kind: SmrtWebRelationshipKind;
-    /** REST collection name the edge resolves to (e.g. `ad_groups`). */
-    relatedCollection: string;
-}
-
-/** The relationship kinds a generated web collection edge can describe. */
-declare type SmrtWebRelationshipKind = 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';
-
-declare interface SmrtWebToolRouteDescriptor {
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    scope: 'item' | 'collection';
-    /** Route segments below the collection endpoint; dynamic segments use `[x]`. */
-    path: string[];
-    /** Transport names rewritten by the tool schema (e.g. `actionId` → `id`). */
-    parameterAliases?: Record<string, string>;
-    /** The generated method accepts one `options` bag as its sole argument. */
-    optionsBag?: boolean;
-}
-
-/**
- * A validated, frozen intent.
- *
- * `kind: 'intent'` and `id` are the exported identity a `smrt-playbooks`
- * step reference (`{ kind: 'intent', id }`) names, and this object is
- * directly assignable to that package's `PlaybookIntentRecord` seam —
- * `{ id, classification, planes }` — so {@link resolveViewIntent} can be
- * passed as its `intents` resolver unchanged.
- */
-declare interface ViewIntent {
-    readonly kind: 'intent';
-    readonly id: string;
-    readonly description: string;
-    readonly inputSchema: Record<string, unknown>;
-    /** Resolved through the shared fail-closed rule at declaration time. */
-    readonly classification: WebMcpCapabilityClassification;
-    readonly target: ViewIntentTarget;
-    /**
-     * An intent moves mounted browser state, so it is browser-valid only. A
-     * server-side agent reaches one through the #2446 command/ack bridge, which
-     * a playbook must declare explicitly.
-     */
-    readonly planes: readonly ['browser'];
-}
-
-/** The mounted identity a binding supplies for an intent's lifetime. */
-declare type ViewIntentBinding = {
-    registry: 'control';
-    registryPort: ViewIntentControlRegistryPort;
-    identity: ViewIntentControlIdentity;
-} | {
-    registry: 'dataSurface';
-    registryPort: ViewIntentDataSurfaceRegistryPort;
-    identity: ViewIntentDataSurfaceIdentity;
-};
-
-/**
- * Control commands a view intent may dispatch. Structurally mirrors
- * `ControlCommandAction` in `@happyvertical/smrt-ui/forms`; this package
- * cannot import that one (see AGENTS.md "No inter-smrt dependencies").
- */
-declare type ViewIntentControlAction = 'focus' | 'reveal' | 'highlight' | 'explain' | 'validate' | 'stage' | 'apply' | 'discard' | 'clear' | 'undo';
-
-/** A mounted control's full registry key, subject included. */
-declare interface ViewIntentControlIdentity {
-    formId: string;
-    controlId: string;
-    subject?: ViewIntentSubject;
-}
-
-/**
- * The `ControlInteractionRegistry` surface an intent uses. Declared
- * structurally so this package takes no dependency on
- * `@happyvertical/smrt-ui`; the real registry satisfies it.
- */
-declare interface ViewIntentControlRegistryPort {
-    execute(command: {
-        action: ViewIntentControlAction;
-        identity: ViewIntentControlIdentity;
-        value?: unknown;
-        durationMs?: number;
-        revision?: number;
-    }, context?: {
-        source: 'agent';
-    }): Promise<{
-        ok: boolean;
-        reason?: string;
-    }>;
-}
-
-/**
- * A control-registry target: the intent dispatches exactly one
- * `ControlInteractionRegistry` command against a mounted control.
- *
- * `formId`/`controlId` are the statically declared half of the identity. A
- * binding supplies the mounted identity and must MATCH anything declared
- * here — a declaration is authority over a binding, never the other way
- * round.
- */
-declare interface ViewIntentControlTarget {
-    registry: 'control';
-    action: ViewIntentControlAction;
-    formId?: string;
-    controlId?: string;
-}
-
-/** A mounted data surface's full registry key, subject included. */
-declare interface ViewIntentDataSurfaceIdentity {
-    surfaceId: string;
-    kind: ViewIntentDataSurfaceKind;
-    subject?: ViewIntentSubject;
-}
-
-/** Mirrors `DataSurfaceIdentity['kind']` in `@happyvertical/smrt-ui/data`. */
-declare type ViewIntentDataSurfaceKind = 'table' | 'list' | 'report' | 'custom';
-
-/** The `DataSurfaceRegistry` surface an intent uses. */
-declare interface ViewIntentDataSurfaceRegistryPort {
-    inspect(identity: ViewIntentDataSurfaceIdentity): {
-        revision: number;
-    } | undefined;
-    execute(command: {
-        version: 1;
-        commandId: string;
-        identity: ViewIntentDataSurfaceIdentity;
-        expectedRevision: number;
-        controlId: string;
-        payload?: unknown;
-    }): Promise<{
-        ok: boolean;
-        revision?: number;
-        reason?: string;
-    }>;
-}
-
-/**
- * A data-surface target: the intent dispatches one
- * `DataSurfaceVisibleCommand` — a browser-visible state transition, never a
- * server-side query or mutation.
- */
-declare interface ViewIntentDataSurfaceTarget {
-    registry: 'dataSurface';
-    /** The visible-command `controlId` the mounted surface implements. */
-    controlId: string;
-    surfaceId?: string;
-    kind?: ViewIntentDataSurfaceKind;
-}
-
-/**
- * The optional record a registry identity is qualified by. Rich forms use it
- * to tell apart controls that share a `formId`/`controlId` across records.
- * Structurally mirrors `ControlIdentity['subject']` /
- * `DataSurfaceIdentity['subject']` in `@happyvertical/smrt-ui`.
- */
-declare interface ViewIntentSubject {
-    type: string;
-    id: string;
-    label?: string;
-}
-
-declare type ViewIntentTarget = ViewIntentControlTarget | ViewIntentDataSurfaceTarget;
-
-/**
- * A hand-written browser tool from application code — not generated from a
- * `@smrt()` model. Structurally identical to the WebMCP `registerTool` input;
- * kept as a separate type so this framework-agnostic module never depends on
- * a UI layer's tool-spec type.
- */
-export declare interface WebMcpBespokeToolSpec {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    annotations?: {
-        readOnlyHint?: boolean;
-        destructiveHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-        untrustedContentHint?: boolean;
-    };
-    execute: (args: Record<string, unknown>, options?: WebMcpToolExecutionOptions) => string | Promise<string>;
-}
-
-/** A fully resolved classification. */
-declare interface WebMcpCapabilityClassification {
-    effect: WebMcpToolEffect;
-    /**
-     * Derived, never declared: every non-read effect is annotated destructive
-     * to the browser, so a `write` capability cannot claim the MCP
-     * additive-only guarantee.
-     */
-    destructive: boolean;
-    idempotent: boolean;
-    openWorld: boolean;
-}
-
-export declare interface WebMcpExposurePolicy {
-    /** Allowed effects. Omitted means read-only exposure. */
-    effects?: readonly WebMcpToolEffect[];
-    /** Prefix every registered tool name with `<namespace>_`. */
-    namespace?: string;
-    /** Optional maximum tools registered by one call. */
-    maxTools?: number;
-}
-
-/** Accepted legacy collection definitions and canonical per-tool definitions. */
-export declare type WebMcpRegistrationDefinition = SmrtWebCollectionDefinition | WebMcpToolDefinition;
-
-/** Disposes a registration and exposes completion of browser registration. */
-export declare interface WebMcpRegistrationDisposer {
-    (): void;
-    /** Rejects if the browser rejects any tool; all sibling tools are aborted. */
-    readonly ready: Promise<void>;
-}
-
-/**
- * Canonical data-only definition for one API-backed browser tool. Unlike a
- * collection definition, this does not imply that a list route or client cache
- * exists. Generated definitions carry explicit semantics; manual legacy
- * literals may omit them and register with fail-closed defaults.
- */
-declare interface WebMcpToolDefinition extends WebToolDescriptor {
-    /** Stable definition identity is `(collection, action)`. */
-    collection: string;
-    /** Canonical qualified row-model identity. */
-    objectRef: string;
-    /** Row-model class used by the shared MCP tool vocabulary. */
-    className: string;
-    endpoint: string;
-    idField: string;
-    idType: 'uuid' | 'text';
-    /** Complete generated route metadata, including CRUD actions. */
-    route: SmrtWebToolRouteDescriptor;
-    /** Cache-invalidation edges for materialized sibling collections. */
-    relationships: SmrtWebRelationship[];
-}
-
-/**
- * The one capability classification rule this package applies, extracted so
- * every declaration site in smrt-web shares a single implementation (#2587,
- * #2588).
- *
- * Two sites consume it today: `webmcp.ts` (canonical definitions trusted
- * through it directly, and its legacy CRUD switch's fail-closed default
- * branch) and `intents.ts` (a declared view intent, which is never a CRUD
- * verb and so resolves through the declaration rule alone). Keeping the rule
- * here rather than private to `webmcp.ts` is what lets the intent path be a
- * dependency-free module that never pulls the client-data engine.
- *
- * This module structurally mirrors `CapabilityEffect` / `CapabilityDeclaration`
- * / `CapabilityClassification` in `@happyvertical/smrt-types` rather than
- * importing them — this package's dependency-DAG guardrails keep it free of
- * every `@happyvertical/*` dependency (see AGENTS.md "No inter-smrt
- * dependencies"), the same reason `data-query.ts` mirrors that package's
- * bounded query envelope structurally instead of importing it.
- */
-/**
- * Browser/agent-visible effect classification for a capability. `'read'`
- * never mutates; `'write'` mutates within the application; `'destructive'`
- * may remove or irreversibly change data.
- */
-export declare type WebMcpToolEffect = 'read' | 'write' | 'destructive';
-
-/** Host-supplied per-invocation options, distinct from registration lifetime. */
-export declare interface WebMcpToolExecutionOptions {
-    /** Caller cancellation. Older hosts may omit execution options entirely. */
-    signal?: AbortSignal;
-}
-
-/**
- * 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
- * type carrier threaded through codegen — it never exists at runtime, it only
- * lets factories infer the row type from a definition.
- */
-/**
- * One WebMCP / MCP tool descriptor for a collection action (#1812). Emitted by
- * the core web-collections codegen as PLAIN DATA (this package has no smrt
- * dependency), shaped to match Chrome's `document.modelContext.registerTool`
- * input — see https://developer.chrome.com/docs/ai/webmcp. Consumed by
- * {@link registerWebMcpTools} in `./webmcp`.
- */
-declare interface WebToolDescriptor {
-    /** The action this tool performs (`list` | `get` | … | a custom method name). */
-    action: string;
-    /** Tool id, `${className.toLowerCase()}_${action}` (e.g. `product_list`). */
-    name: string;
-    description: string;
-    /** JSON Schema for the tool's arguments. */
-    inputSchema: Record<string, unknown>;
-    /** True for non-mutating reads → WebMCP `annotations.readOnlyHint`. */
-    readOnly: boolean;
-    /** Capability effect used by WebMCP exposure policy. */
-    effect?: 'read' | 'write' | 'destructive';
-    /** Whether repeating the tool with the same arguments is safe. */
-    idempotent?: boolean;
-    /** Whether the tool may interact outside the SMRT application. */
-    openWorld?: boolean;
-    /** Generated custom-route transport metadata. */
-    route?: SmrtWebToolRouteDescriptor;
-}
-
-export { }
+/**
+ * WebMCP browser tool registration (#1812).
+ *
+ * Registers each collection's generated {@link WebToolDescriptor}s with the
+ * browser's WebMCP registry (`document.modelContext.registerTool`) so an
+ * in-page AI agent can discover and invoke them — see
+ * https://developer.chrome.com/docs/ai/webmcp. Each tool's `execute` runs
+ * through the shared smrt-web collection AS THE PAGE'S AUTHENTICATED USER, so
+ * the generated REST guards (auth, tenant gate #1554, writable + sensitive-field
+ * policy #1540) are the security boundary — nothing is re-implemented here.
+ *
+ * Framework-agnostic: this module imports no UI framework. `document.modelContext`
+ * is a browser global, not a dependency. Legacy list-backed mutations use the
+ * same optimistic path as page code through `createSmrtCollection`; canonical
+ * tool-only definitions execute through REST fetchers and invalidate any
+ * materialized sibling caches through the host's shared `SmrtWebClient`.
+ */
+import { type WebMcpToolEffect } from './capability-classification.js';
+import { type SmrtCrudFetchers, type SmrtWebClient, type SmrtWebCollectionDefinition, type WebMcpToolDefinition } from './index.js';
+import { type ViewIntent, type ViewIntentBinding } from './intents.js';
+import { type WebMcpToolNameOwner } from './webmcp-tool-names.js';
+/** Host-supplied per-invocation options, distinct from registration lifetime. */
+export interface WebMcpToolExecutionOptions {
+    /** Caller cancellation. Older hosts may omit execution options entirely. */
+    signal?: AbortSignal;
+}
+/** Disposes a registration and exposes completion of browser registration. */
+export interface WebMcpRegistrationDisposer {
+    (): void;
+    /** Rejects if the browser rejects any tool; all sibling tools are aborted. */
+    readonly ready: Promise<void>;
+}
+/**
+ * Re-exported from `./capability-classification.js`, where the one
+ * classification rule this package applies now lives so the declarative
+ * view-intent entry (#2588) can share it without importing this module.
+ */
+export type { WebMcpToolEffect } from './capability-classification.js';
+/**
+ * Re-exported from `./webmcp-tool-names.js` so a host catching a collision
+ * does not have to import the lock entry separately. That entry
+ * (`@happyvertical/smrt-web/webmcp-tool-names`) stays the import a UI layer
+ * uses to reserve its own fixed tool names, because it is dependency-free.
+ */
+export { reserveWebMcpToolNames, WebMcpToolNameCollisionError, type WebMcpToolNameOwner, type WebMcpToolNameReservation, webMcpToolNameOwner, } from './webmcp-tool-names.js';
+export interface WebMcpExposurePolicy {
+    /** Allowed effects. Omitted means read-only exposure. */
+    effects?: readonly WebMcpToolEffect[];
+    /** Prefix every registered tool name with `<namespace>_`. */
+    namespace?: string;
+    /** Optional maximum tools registered by one call. */
+    maxTools?: number;
+}
+/**
+ * A hand-written browser tool from application code — not generated from a
+ * `@smrt()` model. Structurally identical to the WebMCP `registerTool` input;
+ * kept as a separate type so this framework-agnostic module never depends on
+ * a UI layer's tool-spec type.
+ */
+export interface WebMcpBespokeToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    execute: (args: Record<string, unknown>, options?: WebMcpToolExecutionOptions) => string | Promise<string>;
+}
+export interface RegisterWebMcpBespokeToolOptions {
+    /**
+     * Allowed effects. Omitted means read-only exposure — the same default as
+     * {@link registerWebMcpTools}. `namespace` and `maxTools` deliberately do
+     * not apply to a bespoke tool (#2586): a component author already chose a
+     * stable name, and counting one intent against a shared budget could make
+     * 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'>;
+}
+export interface RegisterWebMcpToolsOptions extends WebMcpExposurePolicy {
+    /** REST base path for the fetchers (default `/api/v1`). */
+    basePath?: string;
+    /** Injectable fetch (tests / SSR-safe wrappers). */
+    fetchFn?: typeof fetch;
+    /** Shared smrt-web cache handle used by page collections. */
+    client?: SmrtWebClient;
+    /** Optional cache scope matching the page collection's scope. */
+    scope?: string;
+    /**
+     * Override how a definition's CRUD fetchers are built. Defaults to
+     * {@link createDefinitionFetchers}; the primary seam for testing `execute`
+     * without a live server.
+     */
+    resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
+    /**
+     * Override direct REST fetchers for a canonical tool-only definition.
+     * Fetchers are optional because a get-only or custom-action-only model does
+     * not have a list or create route.
+     */
+    resolveToolFetchers?: (definition: WebMcpToolDefinition) => Partial<SmrtCrudFetchers>;
+    /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
+    filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
+    /** Predicate for canonical per-tool definitions. */
+    filterTool?: (definition: WebMcpToolDefinition) => boolean;
+}
+/** Accepted legacy collection definitions and canonical per-tool definitions. */
+export type WebMcpRegistrationDefinition = SmrtWebCollectionDefinition | WebMcpToolDefinition;
+/**
+ * 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;
+/**
+ * Register one hand-written browser tool through the same fail-closed effect
+ * classification and `effects` exposure policy as {@link registerWebMcpTools}
+ * (#2586). A tool with no `annotations`, or with annotations that leave its
+ * effect undeclared, classifies destructive/non-idempotent/open-world — the
+ * same default `actionSemantics` gives an undeclared custom model action —
+ * and is excluded unless the policy allows `destructive`. `namespace` and
+ * `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;
+/**
+ * Register one declared view intent (#2588) against a mounted registry
+ * binding, for as long as the returned disposer is not called.
+ *
+ * This is the ONLY way an intent reaches the browser, and it goes through
+ * {@link registerWebMcpBespokeTool}, so an intent inherits the same
+ * fail-closed `effects` exposure policy as a generated model tool. The
+ * intent's classification was resolved at declaration time by the shared
+ * rule, and the hints `compileViewIntentToolSpec` emits round-trip through
+ * the bespoke registrar's own re-resolution unchanged.
+ *
+ * The `execute` registered here is constructed by
+ * `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;
+//# sourceMappingURL=webmcp.d.ts.map