@toon-protocol/client 0.13.0 → 0.14.0

package/dist/render/index.d.ts

@@ -0,0 +1,807 @@
+import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
+import { UiCoordinate, UI_RENDERER_KIND } from '@toon-protocol/core';
+export { UI_RENDERER_KIND, UI_TAG, UiCoordinate, buildUiCoordinate, getUiCoordinate, parseUiCoordinate, selectLatestAddressable } from '@toon-protocol/core';
+
+/**
+ * Branch 1 — the native-component registry.
+ *
+ * A `kind → native component` map for the kinds the client knows natively. This
+ * is the registry abstraction that {@link renderDispatch} consults first: a hit
+ * is branch 1 (full trust), a miss falls through to the unknown-kind branches.
+ *
+ * The component type `C` is generic so the rendering package
+ * (`@toon-protocol/views`) instantiates it with its own component contract (e.g.
+ * an `Atom`) — this keeps `@toon-protocol/client` free of any React dependency
+ * while still owning the dispatch + registry abstraction (per the epic split:
+ * dispatch in `client`, branch-1 components in `views`).
+ *
+ * Replaces ad-hoc per-kind conditionals with a single register/lookup seam.
+ */
+/** A native component registered for one or more event kinds. */
+declare class KindRegistry<C> {
+    private readonly byKind;
+    /**
+     * Register a native `component` as the renderer for one or more event
+     * `kinds`. Registering an already-registered kind overwrites it (last write
+     * wins) so a host can override a default; pass {@link register} per kind to
+     * keep the first registration explicit.
+     */
+    register(kinds: number | readonly number[], component: C): this;
+    /** The native component for `kind`, or `undefined` if the kind is unknown. */
+    lookup(kind: number): C | undefined;
+    /** Whether a native component is registered for `kind` (branch 1 applies). */
+    has(kind: number): boolean;
+    /** Every kind with a registered native component. */
+    kinds(): number[];
+    /** Number of registered kinds. */
+    get size(): number;
+}
+
+/**
+ * Render-dispatch types for the NIP-on-TOON render trust gradient.
+ *
+ * The client forks on one question — *do I know this kind?* — and the answer
+ * selects both a render strategy and a trust level. Trust runs *opposite* to
+ * flexibility: the more open-ended the render path, the less it is trusted.
+ *
+ * | Branch | Condition                | Strategy                  | Trust  |
+ * |--------|--------------------------|---------------------------|--------|
+ * | 1      | known kind               | native component          | full   |
+ * | 2      | unknown + A2UI spec      | client A2UI catalog       | medium |
+ * | 3      | unknown + raw widget     | sandboxed mcp-ui iframe   | low    |
+ * | 4      | unknown + nothing        | generative fallback       | low    |
+ *
+ * This module is render-framework-agnostic: it carries the *decision*, not the
+ * React tree. The `views` package binds branch 1's resolved native component to
+ * an actual component, and the sibling tickets (#89/#90/#92) fill in branches
+ * 2/3/4. See `skills/nip-on-toon-discovery/SKILL.md` in toon-meta for the spec.
+ */
+
+/**
+ * The four render branches of the trust gradient. The string values are stable
+ * and safe to persist / log.
+ */
+type RenderBranch = 'native' | 'a2ui' | 'mcp-ui' | 'generative';
+/** Trust tier associated with a branch. Full > medium > low. */
+type RenderTrust = 'full' | 'medium' | 'low';
+/**
+ * Branch 1 — a known kind renders with a fully-trusted native component from the
+ * client's own registry. The component type `C` is left generic so the rendering
+ * package (`@toon-protocol/views`) can specialise it with its own component
+ * contract (e.g. an `Atom`) without this package depending on React.
+ */
+interface NativeDecision<C> {
+    branch: 'native';
+    trust: 'full';
+    /** The event to render. */
+    event: NostrEvent;
+    /** The resolved native component for this kind, from the {@link KindRegistry}. */
+    component: C;
+}
+/**
+ * Branch 2 — unknown kind, an `application/a2ui+json` renderer is available. The
+ * renderer's `surfaceUpdate` is the template; `core.decodeEventFromToon(event)`
+ * is fed in as the `dataModelUpdate` (medium trust, standard catalog only).
+ *
+ * STUB for #88: the dispatch routes here; the A2UI renderer is implemented in
+ * toon-protocol/toon-client#89.
+ */
+interface A2uiDecision {
+    branch: 'a2ui';
+    trust: 'medium';
+    /** The event to render. */
+    event: NostrEvent;
+    /** The resolved `kind:31036` renderer event carrying the A2UI `surfaceUpdate`. */
+    renderer: NostrEvent;
+}
+/**
+ * Branch 3 — unknown kind, a `text/html;profile=mcp-app` raw widget renderer is
+ * available. Rendered inside a sandboxed mcp-ui iframe at low trust; the consent
+ * invariant (authorization surface drawn by the client outside the iframe,
+ * non-themeable) is enforced by the host.
+ *
+ * STUB for #88: the dispatch routes here; the sandboxed AppRenderer + consent
+ * invariant are implemented in toon-protocol/toon-client#90.
+ */
+interface McpUiDecision {
+    branch: 'mcp-ui';
+    trust: 'low';
+    /** The event to render. */
+    event: NostrEvent;
+    /** The resolved `kind:31036` renderer event carrying the raw widget. */
+    renderer: NostrEvent;
+}
+/**
+ * Branch 4 — unknown kind, no renderer available. The client falls back to a
+ * generative rendering at low trust (optionally publishing back a `kind:31036`).
+ *
+ * STUB for #88: the dispatch routes here; the generative fallback is implemented
+ * in toon-protocol/toon-client#92.
+ */
+interface GenerativeDecision {
+    branch: 'generative';
+    trust: 'low';
+    /** The event to render. */
+    event: NostrEvent;
+}
+/**
+ * The outcome of {@link renderDispatch}: a discriminated union over
+ * {@link RenderBranch}. Consumers switch on `.branch` to pick a renderer.
+ */
+type RenderDecision<C> = NativeDecision<C> | A2uiDecision | McpUiDecision | GenerativeDecision;
+
+/**
+ * Renderer-swap defense — the security guard layer around render dispatch
+ * (toon-protocol/toon-client#91, part of toon-protocol/toon-meta#58).
+ *
+ * ── THREAT: "renderer swap" ───────────────────────────────────────────────────
+ * A `kind:31036` renderer is an *addressable* event: the coordinate
+ * `31036:<author-pubkey>:<targetKind>` can later resolve to a *different* event
+ * (different `id`, different content) by publishing a newer-`created_at`
+ * revision. Because resolving the `ui` tag yields a renderer that selects the
+ * render strategy *and* the trust tier, an attacker who gets a malicious 31036
+ * selected can attack the user:
+ *
+ *   V1. Cross-author substitution — serve a 31036 authored by someone *other*
+ *       than the authoritative renderer author, hoping the client renders it.
+ *   V2. Forged / tampered renderer — serve a 31036 whose signature does not
+ *       verify (mutated tags/content, or no signature at all).
+ *   V3. Resolution race / nondeterminism — feed candidate revisions in an order
+ *       that makes some clients pick the attacker's revision.
+ *   V4. Silent mid-session swap — after a renderer has been pinned for an event,
+ *       publish a newer revision (new `id`) to swap the active renderer out from
+ *       under an already-decided render, especially to *downgrade trust* (e.g.
+ *       push a benign event into a hostile low-trust widget).
+ *
+ * Per toon#36 decisions: the renderer-author pubkey is the **event author** (the
+ * `pubkey` of the event being rendered), and clients MUST re-verify the 31036
+ * signature before it can select a render strategy.
+ *
+ * ── DEFENSE (this module) ─────────────────────────────────────────────────────
+ * {@link verifyRendererTrust} is a guard placed *between* renderer resolution and
+ * {@link renderDispatch}. It **fails closed**: on any violation it returns a
+ * rejection and the caller drops to the safe branch (native for known kinds,
+ * generative for unknown kinds) — it never renders the suspect renderer.
+ *
+ *   - **Author binding (closes V1):** the resolved 31036's `pubkey` MUST equal
+ *     the authoritative renderer author (the rendered event's `pubkey`). The
+ *     coordinate's `pubkey` segment is also checked, so a coordinate pointing at
+ *     a third-party author is refused before any fetch is trusted.
+ *   - **Signature verification (closes V2):** the 31036 event signature is
+ *     re-verified with {@link verifyEvent}; a tampered/unsigned renderer is
+ *     refused.
+ *   - **Deterministic selection (closes V3):** candidates are collapsed with
+ *     {@link selectLatestAddressable} (latest `created_at`, lowest-`id`
+ *     tiebreak), so selection is not attacker-race-controllable.
+ *   - **Anti-swap pinning + downgrade detection (closes V4):** the chosen
+ *     renderer `id` and its trust tier are pinned per coordinate in a
+ *     {@link RendererPinStore}. A later revision with a *different* `id` is a
+ *     detected swap; if it would *lower* the trust tier the swap is refused
+ *     (fail closed). High-trust kinds use the issue's stricter rule: any `id`
+ *     change at all → refuse and fall back to the native component.
+ *
+ * ── RELATION TO {@link import('./resolveRenderer.js').resolveUiRenderer} ───────
+ * `resolveRenderer.ts` (#97) is the plain, stateless `ui`→`kind:31036` resolver:
+ * author-bound coordinate, latest-addressable selection, signature re-verify,
+ * returning the renderer or `undefined`. This guard shares the SAME core
+ * primitives it builds on — `getUiCoordinate` / `selectLatestAddressable` (now
+ * from `@toon-protocol/core`) and `verifyEvent` — so the two agree bit-for-bit
+ * on which revision a coordinate selects and on signature acceptance. The guard
+ * adds what the plain resolver deliberately omits: a stateful anti-swap pin
+ * store, trust-downgrade / high-trust id-change detection, and *granular*
+ * fail-closed {@link SwapRejectionReason}s (the resolver collapses every failure
+ * to `undefined`). It is therefore a strict superset, not a parallel copy.
+ */
+
+/** Whether trust tier `next` is strictly lower than `prev` (a downgrade). */
+declare function isTrustDowngrade(prev: RenderTrust, next: RenderTrust): boolean;
+/** Why a renderer was refused. Stable string values, safe to log. */
+type SwapRejectionReason = 
+/** No `ui` coordinate on the event, or it was malformed. */
+'no-coordinate'
+/** The coordinate's author segment is not the rendered event's author. */
+ | 'coordinate-author-mismatch'
+/** No candidate `kind:31036` renderer resolved for the coordinate. */
+ | 'no-renderer'
+/** The resolved event is not a `kind:31036` renderer. */
+ | 'not-a-renderer'
+/** The resolved renderer's `pubkey` is not the authoritative author. */
+ | 'author-mismatch'
+/** The renderer's `d` tag does not match the coordinate's target kind. */
+ | 'target-kind-mismatch'
+/** The renderer signature did not verify (tampered / unsigned). */
+ | 'bad-signature'
+/** A high-trust kind's pinned renderer `id` changed (issue rule: refuse). */
+ | 'high-trust-id-changed'
+/** The swap would lower the trust tier from the pinned tier. */
+ | 'trust-downgrade';
+/** A renderer refused by the guard. The caller must fall back, not render. */
+interface SwapRejection {
+    ok: false;
+    reason: SwapRejectionReason;
+    /** Human-readable detail for logging. */
+    detail: string;
+    /** The coordinate involved, when one was resolvable. */
+    coordinate?: UiCoordinate;
+}
+/** A renderer the guard approved for dispatch. */
+interface SwapApproval {
+    ok: true;
+    /** The verified, author-bound, deterministically-selected renderer. */
+    renderer: NostrEvent;
+    /** The coordinate the renderer was selected for. */
+    coordinate: UiCoordinate;
+    /** Whether this approval newly pinned the coordinate (first sighting). */
+    pinned: boolean;
+    /** Set when an `id` swap was observed but allowed (non-downgrading). */
+    swapObserved?: boolean;
+}
+type SwapDecision = SwapApproval | SwapRejection;
+/**
+ * A pinned renderer decision for one coordinate: the `id` we committed to and
+ * the trust tier it implied. Used to detect swaps and downgrades.
+ */
+interface RendererPin {
+    /** The pinned `kind:31036` event id. */
+    id: string;
+    /** The trust tier the pinned renderer selected. */
+    trust: RenderTrust;
+}
+/**
+ * Pins the chosen renderer per coordinate so a later replaceable `kind:31036`
+ * cannot silently swap the active renderer mid-session. Keyed by the canonical
+ * coordinate string `31036:<pubkey>:<targetKind>`.
+ *
+ * In-memory by default; a host may seed pins from config (the issue's
+ * "allowlist high-trust renderers by event id" — pre-populate the expected `id`
+ * for a known kind) via {@link pin}.
+ */
+declare class RendererPinStore {
+    private readonly byCoord;
+    private static key;
+    /** The pin for `coord`, or `undefined` if not yet pinned. */
+    get(coord: UiCoordinate): RendererPin | undefined;
+    /** Pin (or overwrite) the renderer decision for `coord`. */
+    pin(coord: UiCoordinate, decision: RendererPin): this;
+    /** Whether `coord` is pinned. */
+    has(coord: UiCoordinate): boolean;
+    /** Number of pinned coordinates. */
+    get size(): number;
+}
+/** Input to {@link verifyRendererTrust}. */
+interface VerifyRendererInput<C> {
+    /** The event whose renderer is being resolved. Its `pubkey` is authoritative. */
+    event: NostrEvent;
+    /**
+     * The candidate `kind:31036` renderer(s) fetched for the event's `ui`
+     * coordinate. May contain multiple revisions; the guard picks the winner
+     * deterministically. The caller does not pre-select.
+     */
+    candidates: readonly NostrEvent[];
+    /** The branch-1 native registry; used to decide which kinds are "high trust". */
+    registry: KindRegistry<C>;
+    /** The pin store enforcing stable, anti-swap selection across resolutions. */
+    pins: RendererPinStore;
+    /**
+     * Signature verifier (defaults to nostr-tools `verifyEvent`). Injectable so
+     * tests can exercise the fail-closed path deterministically.
+     */
+    verify?: (event: NostrEvent) => boolean;
+    /**
+     * Treat the event's kind as a "high-trust" kind subject to the issue's strict
+     * id-allowlist rule (any `id` change → refuse, fall back to native). Defaults
+     * to "the registry has a native component for this kind", matching the spec:
+     * branch-1 known kinds are the high-trust set. A host may override.
+     */
+    isHighTrustKind?: (kind: number) => boolean;
+}
+/**
+ * Guard a renderer before it can select a render strategy. Runs author binding,
+ * signature verification, deterministic selection, and anti-swap / downgrade
+ * detection. **Fails closed**: any violation returns a {@link SwapRejection} and
+ * the caller must drop to the safe branch rather than render.
+ *
+ * On approval, the chosen renderer is pinned for its coordinate so a subsequent
+ * resolution that yields a different `id` is detected (and, if it would downgrade
+ * trust, refused).
+ */
+declare function verifyRendererTrust<C>(input: VerifyRendererInput<C>): SwapDecision;
+
+/**
+ * Kind-keyed render dispatch — the skeleton the four render branches plug into.
+ *
+ * Implements §"Client dispatch algorithm" of the NIP-on-TOON render-side spec
+ * (`skills/nip-on-toon-discovery/SKILL.md` in toon-meta):
+ *
+ *   1. Is this kind known? → **branch 1** (native registry). Done.
+ *   2. Otherwise resolve the event's `ui` tag to a `kind:31036` renderer.
+ *   3. If a renderer is found, read its `m` (mimeType) tag:
+ *        - `application/a2ui+json`     → **branch 2** (A2UI, medium trust)
+ *        - `text/html;profile=mcp-app` → **branch 3** (sandboxed mcp-ui, low)
+ *   4. If no renderer is found → **branch 4** (generative fallback, low trust).
+ *
+ * SCOPE (#88 — skeleton + branch 1 only): branch 1 is wired through the
+ * {@link KindRegistry}; branches 2/3/4 are returned as clearly-marked decisions
+ * for the sibling tickets to consume (#89 A2UI, #90 mcp-ui + consent, #92
+ * generative). This module does NOT render — it returns a {@link RenderDecision}.
+ *
+ * The `ui`-tag → `kind:31036` *resolution* lives outside this function — see
+ * {@link resolveUiRenderer} in `./resolveRenderer.js`, which parses the `ui`
+ * coordinate (via core's `getUiCoordinate` / `parseUiCoordinate`), picks the
+ * latest addressable `kind:31036` (`selectLatestAddressable`), and re-verifies
+ * its signature before trusting it. The dispatch takes the already-resolved
+ * renderer event via {@link DispatchInput.renderer}.
+ */
+
+/**
+ * The `m` (mimeType) tag value of a resolved `kind:31036` renderer, or
+ * `undefined` if the event is not a renderer or carries no `m` tag.
+ *
+ * The `m` tag is the format selector that picks the branch + trust tier.
+ */
+declare function resolveRendererMime(renderer: NostrEvent | undefined): string | undefined;
+/** Input to {@link renderDispatch}. */
+interface DispatchInput {
+    /** The decoded event the client wants to render. */
+    event: NostrEvent;
+    /**
+     * The `kind:31036` renderer resolved from the event's `ui` tag, if any.
+     *
+     * Resolution (parse the `ui` coordinate, fetch + pick the latest addressable
+     * `kind:31036`) is performed by the caller — see the toon#36 spike. Only
+     * consulted when the event's kind is unknown (branches 2–4).
+     */
+    renderer?: NostrEvent;
+}
+/**
+ * Route an event to one of the four render branches.
+ *
+ * @param input    The event + (optionally) its resolved `kind:31036` renderer.
+ * @param registry The branch-1 native-component registry to consult first.
+ * @returns A {@link RenderDecision} naming the branch, trust tier, and payload.
+ */
+declare function renderDispatch<C>(input: DispatchInput, registry: KindRegistry<C>): RenderDecision<C>;
+/** Input to {@link guardedRenderDispatch}. */
+interface GuardedDispatchInput {
+    /** The decoded event the client wants to render. */
+    event: NostrEvent;
+    /**
+     * The candidate `kind:31036` renderer(s) fetched for the event's `ui`
+     * coordinate, *unfiltered*. The swap-defense guard selects the winner
+     * deterministically and verifies it; the caller does NOT pre-select. Pass an
+     * empty array (or omit) when no renderer was resolved.
+     */
+    candidates?: readonly NostrEvent[];
+}
+/** Why {@link guardedRenderDispatch} fell back to a safe branch. */
+interface DispatchGuardInfo {
+    /** A renderer was refused by the swap-defense guard. */
+    rejected: SwapRejection;
+}
+/**
+ * Dispatch with the **renderer-swap defense** (toon-client#91) interposed.
+ *
+ * This is the secure entry point: it runs {@link verifyRendererTrust} over the
+ * raw candidate renderers *before* {@link renderDispatch} can pick a strategy,
+ * and **fails closed** on any violation (wrong-author, bad signature,
+ * trust-downgrading swap, high-trust id change):
+ *
+ *   - Known kind → branch 1 (native) regardless of renderers. The guard still
+ *     runs so a *high-trust* renderer swap is detected, but a known kind always
+ *     has the native component to fall back to, so the result is branch 1.
+ *   - Unknown kind, renderer **approved** → normal {@link renderDispatch} with the
+ *     single verified renderer (branches 2/3).
+ *   - Unknown kind, renderer **refused** or none → branch 4 (generative). We do
+ *     NOT pass the suspect renderer through; the user gets the safe fallback.
+ *
+ * @returns the {@link RenderDecision} plus, when a renderer was refused, the
+ * {@link DispatchGuardInfo} describing why (for logging / UX "renderer refused").
+ */
+declare function guardedRenderDispatch<C>(input: GuardedDispatchInput, registry: KindRegistry<C>, pins: RendererPinStore): {
+    decision: RenderDecision<C>;
+    guard?: DispatchGuardInfo;
+};
+
+/**
+ * The consent invariant — the load-bearing security property of branch 3
+ * (sandboxed mcp-ui, low trust) of the NIP-on-TOON render trust gradient
+ * (toon-meta#58, toon-client#90; spec §"Branch 3 — sandboxed mcp-ui & the
+ * consent invariant").
+ *
+ * ── The invariant (verbatim from the spec) ──────────────────────────────────
+ * A sandboxed widget may only *request* an action. The authorization surface is
+ * rendered by the trusted client outside the iframe and is non-themeable. The
+ * sandboxed widget can never draw, style, or spoof the consent/authorization UI.
+ * A widget that can paint the authorization UI collapses the entire trust
+ * gradient to its lowest tier.
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * This module is the framework-agnostic half of branch 3. It carries the
+ * *decision* and the *policy*, not any React tree — mirroring how `@toon-protocol/client`'s
+ * {@link ./dispatch} carries the render decision and `@toon-protocol/views`
+ * carries the rendered component. The React side (the sandboxed `AppRenderer`
+ * iframe + the host-rendered, non-themeable `ConsentPrompt`) lives in
+ * `@toon-protocol/views`; it consumes the types and functions defined here.
+ *
+ * Why the policy lives here, away from React:
+ *   - The classification of "is this a state-changing action that needs explicit
+ *     authorization?" is a pure, auditable function with no DOM dependency.
+ *   - The widget supplies ZERO inputs to this function that can influence the
+ *     *appearance* of the prompt: it supplies only the requested tool name and
+ *     arguments. Everything the prompt renders is derived by the trusted client.
+ */
+
+/**
+ * The widget payload handed to the sandboxed iframe. The `m`-tagged
+ * `text/html;profile=mcp-app` renderer ships a raw HTML widget as a UIResource;
+ * we pass the HTML through to the iframe untouched, but everything the host
+ * renders around it is client-controlled.
+ *
+ * Deliberately minimal: the host needs only the HTML to feed the iframe and the
+ * mimeType to assert the branch. No widget-supplied styling, theme, chrome, or
+ * "trusted" hints are carried — by construction the widget cannot pass any.
+ */
+interface UiResource {
+    /** The raw widget HTML to render inside the sandboxed iframe. */
+    html: string;
+    /** Always `text/html;profile=mcp-app` for branch 3 (asserted on extract). */
+    mimeType: string;
+    /** The `ui://…` resource URI, if the renderer declared one (host metadata only). */
+    uri?: string;
+}
+/**
+ * Extract the branch-3 {@link UiResource} from a resolved `kind:31036` renderer
+ * event whose `m` tag is `text/html;profile=mcp-app`.
+ *
+ * The renderer's `content` is either the raw widget HTML, or a JSON-encoded
+ * MCP `UIResource` embedded-resource block (`{ type: 'resource', resource: {
+ * uri, mimeType, text } }`) as produced by mcp-ui servers. Both are accepted;
+ * the HTML is returned verbatim for iframe passthrough.
+ *
+ * Returns `undefined` (never throws) when the event is not a usable branch-3
+ * renderer, so the caller can fall through to branch 4 rather than render
+ * something unexpected.
+ */
+declare function extractUiResource(renderer: NostrEvent | undefined): UiResource | undefined;
+/**
+ * An action a sandboxed widget *requested* (never performed). This is the only
+ * thing that crosses the iframe → host boundary, and it carries no presentation
+ * data — only the tool name and arguments the widget wants to invoke.
+ */
+interface WidgetIntent {
+    /** The tool/action name the widget asked the host to invoke. */
+    toolName: string;
+    /** The arguments the widget supplied for that tool. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * The classification of a {@link WidgetIntent}: does it need an explicit, host-
+ * rendered authorization decision before the host may act on it?
+ *
+ * - `requires-consent` — a state-changing / spendy / outbound action. The host
+ *   MUST render the {@link ConsentRequest} prompt (outside the iframe,
+ *   non-themeable) and only proceed on an explicit user grant.
+ * - `auto` — a read-only / inert request the host may forward without a prompt.
+ *
+ * Default-deny: anything not provably inert is treated as `requires-consent`.
+ */
+type IntentClassification = 'requires-consent' | 'auto';
+/**
+ * Classify a widget intent. Pure and default-deny: only an exact match against
+ * the trusted read-only allowlist is auto-forwarded; everything else requires a
+ * host-rendered consent prompt.
+ */
+declare function classifyIntent(intent: WidgetIntent): IntentClassification;
+/**
+ * The data the trusted host needs to render an authorization prompt for a
+ * widget-requested action. EVERY field here is either a fixed, client-owned
+ * constant or a plain machine value copied out of the intent — there is NO
+ * styling, theme, color, label-override, HTML, or markup field the widget could
+ * supply. This is what makes the prompt non-themeable by construction: the type
+ * simply has nowhere to put presentation input.
+ */
+interface ConsentRequest {
+    /** Stable id for correlating the prompt with its resolution. */
+    readonly id: string;
+    /** The tool the widget asked to invoke (rendered as plain text by the host). */
+    readonly toolName: string;
+    /** The arguments the widget supplied (rendered as inspectable data, not HTML). */
+    readonly arguments: Record<string, unknown>;
+    /**
+     * The trust tier of the requesting surface — always `'low'` for a branch-3
+     * sandboxed widget. Carried so the host can render the appropriate warning
+     * chrome; the widget cannot change it.
+     */
+    readonly trust: 'low';
+}
+/** The user's decision on a {@link ConsentRequest}. */
+type ConsentDecision = 'grant' | 'deny';
+/**
+ * Build a {@link ConsentRequest} from a widget intent. The host calls this when
+ * {@link classifyIntent} returns `requires-consent`. It copies ONLY the tool
+ * name and arguments out of the widget's request; it fixes `trust: 'low'` and
+ * generates the id itself. The widget contributes nothing to how the prompt
+ * looks.
+ */
+declare function buildConsentRequest(intent: WidgetIntent): ConsentRequest;
+
+/**
+ * `ui`-tag → `kind:31036` renderer resolution (toon#36).
+ *
+ * This is the resolution seam the {@link renderDispatch} skeleton (#88)
+ * deliberately left out: dispatch consumes an *already-resolved* renderer, and
+ * this module produces it. It is split out from dispatch so the relay query +
+ * cache (which is IO, and lives in the daemon / {@link import('../ToonClient.js')})
+ * stays separate from the pure selection logic — mirroring core's own
+ * "helpers are pure, resolution is client-local" split.
+ *
+ * Algorithm, per the toon#36 decisions:
+ *
+ *   1. Read the rendered event's `ui` tag and parse it into a target coordinate.
+ *      The coordinate convention is `31036:<renderer-author-pubkey>:<targetKind>`.
+ *      Per toon#36 the **renderer-author pubkey is the EVENT AUTHOR**, so the
+ *      `ui` tag MAY carry just the bare target kind (e.g. `42`); the author is
+ *      taken from `event.pubkey`. A full `31036:<pubkey>:<kind>` coordinate is
+ *      also accepted (via core's `getUiCoordinate`), but its pubkey MUST equal
+ *      the event author — a coordinate naming a different author is rejected, so
+ *      an event cannot point at a third party's renderer.
+ *   2. Filter the caller-supplied `kind:31036` candidates to that coordinate
+ *      (author === event author, `d` tag === target kind) and pick the latest
+ *      addressable one (NIP-33 latest-wins) via `selectLatestAddressable`.
+ *   3. **Re-verify the signature** of the chosen renderer with `verifyEvent`
+ *      before trusting it. A renderer that fails verification is dropped (the
+ *      resolution returns `undefined`) — the client never feeds an unverified
+ *      renderer to the dispatch.
+ *
+ * The relay query that produces `candidates` is the caller's responsibility:
+ * query `kind:31036`, `authors: [event.pubkey]`, `#d: [String(targetKind)]`.
+ */
+
+/**
+ * The renderer coordinate a rendered event points at: a `kind:31036` event
+ * authored by the rendered event's author, targeting `targetKind`.
+ */
+interface ResolvedCoordinate {
+    /** Always {@link UI_RENDERER_KIND} (31036). */
+    kind: typeof UI_RENDERER_KIND;
+    /** The renderer author pubkey — per toon#36, the EVENT AUTHOR's pubkey. */
+    pubkey: string;
+    /** The kind of event the renderer targets (the renderer's `d` value). */
+    targetKind: number;
+}
+/**
+ * Compute the renderer coordinate a rendered event points at, anchoring the
+ * renderer-author pubkey to the **event author** per toon#36.
+ *
+ * Accepts two `ui` tag shapes:
+ *   - a bare target kind, e.g. `["ui", "42"]` → author = `event.pubkey`;
+ *   - a full coordinate, e.g. `["ui", "31036:<pubkey>:42"]` → accepted only if
+ *     `<pubkey>` equals `event.pubkey` (else `null`).
+ *
+ * Pure: no IO.
+ *
+ * @param event - The rendered event that may carry a `ui` tag.
+ * @returns The resolved coordinate, or `null` if there is no usable `ui` tag.
+ */
+declare function resolveUiCoordinate(event: NostrEvent): ResolvedCoordinate | null;
+/**
+ * Resolve a rendered event's `ui` tag to a verified `kind:31036` renderer.
+ *
+ * Filters `candidates` to the coordinate computed by {@link resolveUiCoordinate},
+ * picks the latest addressable match, and **re-verifies its signature** before
+ * returning it. The result feeds {@link renderDispatch} as `DispatchInput.renderer`.
+ *
+ * @param event      - The rendered event carrying the `ui` tag.
+ * @param candidates - `kind:31036` events the caller fetched for this coordinate
+ *                     (the relay query is the caller's responsibility).
+ * @returns The latest verified renderer, or `undefined` if none resolves /
+ *          verifies.
+ */
+declare function resolveUiRenderer(event: NostrEvent, candidates: readonly NostrEvent[]): NostrEvent | undefined;
+
+/**
+ * Render-side protocol constants for NIP-on-TOON.
+ *
+ * The canonical homes for the renderer kind, the `ui` tag, and the
+ * `UiCoordinate` helpers are `@toon-protocol/core` (published in `1.6.0`):
+ * {@link UI_RENDERER_KIND} (31036), {@link UI_TAG}, and `parseUiCoordinate` /
+ * `buildUiCoordinate` / `getUiCoordinate` / `selectLatestAddressable`. They are
+ * re-exported here so the render module has a single import surface; only the
+ * mime-type selectors below are owned locally (core does not export them).
+ */
+
+/**
+ * The `m` (mimeType) tag value selecting **branch 2** — A2UI, medium trust.
+ *
+ * Owned locally: core does not export the render-branch mime selectors.
+ */
+declare const MIME_A2UI = "application/a2ui+json";
+/**
+ * The `m` (mimeType) tag value selecting **branch 3** — sandboxed mcp-ui iframe,
+ * low trust.
+ *
+ * Owned locally: core does not export the render-branch mime selectors.
+ */
+declare const MIME_MCP_APP = "text/html;profile=mcp-app";
+
+/**
+ * Branch 4 — generative fallback + optional `kind:31036` publish-back.
+ *
+ * Implements §"branch 4 — generative fallback" of the NIP-on-TOON render-side
+ * spec (`skills/nip-on-toon-discovery/SKILL.md` in toon-meta) and
+ * toon-protocol/toon-client#92.
+ *
+ * Branch 4 is reached by {@link renderDispatch} when a kind is **unknown** *and*
+ * no resolvable `kind:31036` renderer exists (no `ui` tag, or nothing resolves,
+ * or the resolved renderer carries no recognised `m` tag). With nothing else to
+ * go on, the client generates a best-effort rendering for the unknown event's
+ * shape at **low trust**.
+ *
+ * Design seams (per the issue's `needs:human` open questions — the model, the
+ * curation policy, and the publish-back opt-in semantics are product decisions
+ * the host owns, so this module hardcodes none of them):
+ *
+ *  - **Generator** ({@link RendererGenerator}) — the actual model call is
+ *    abstracted behind an interface the host injects. The host wires its own
+ *    provider/keys/prompt; this module never imports an LLM SDK. A deterministic
+ *    non-LLM generator ({@link deterministicGenerator}) is provided as the
+ *    default and for tests, so branch 4 always produces *something* renderable
+ *    even with no model configured.
+ *  - **Publish-back** — optionally republish the generated renderer as a
+ *    `kind:31036` addressable event so the next client has a "known" renderer
+ *    for that kind (branch 4 slowly feeds branch 1). This is a **guarded,
+ *    off-by-default** capability: it only fires when the host explicitly passes
+ *    `publish: { enabled: true, ... }`. The published renderer is clearly
+ *    low-trust / curation-pending; the namespacing & curation policy for
+ *    community-published renderers is an open question in the epic (toon#58) and
+ *    is intentionally *not* built here.
+ */
+
+/**
+ * A generated renderer for an unknown event kind: an HTML `UIResource`-style
+ * document plus the `m` (mimeType) tag that classifies it.
+ *
+ * The HTML is the raw widget body; if published back as a `kind:31036` event it
+ * is rendered through branch 3 (sandboxed mcp-ui iframe) by a downstream client,
+ * which is why {@link mimeType} defaults to the branch-3 selector.
+ */
+interface GeneratedRenderer {
+    /** The generated HTML document (the `UIResource` body). */
+    html: string;
+    /**
+     * The `m` (mimeType) tag for the generated renderer. Defaults to
+     * {@link MIME_MCP_APP} (`text/html;profile=mcp-app`) so a published renderer
+     * routes through branch 3 (sandboxed, low trust) on the next client.
+     */
+    mimeType: string;
+    /**
+     * Whether this rendering came from a model (`'model'`) or the built-in
+     * deterministic fallback (`'deterministic'`). Surfaced so the host can label
+     * trust/provenance in the UI.
+     */
+    source: 'model' | 'deterministic';
+}
+/** Context handed to a {@link RendererGenerator}. */
+interface GenerateContext {
+    /** The unknown event the client wants to render. */
+    event: NostrEvent;
+}
+/**
+ * The pluggable generator seam. A host injects its own implementation (wired to
+ * whatever model endpoint, key, and prompt it has chosen — all `needs:human`
+ * product decisions this module deliberately does not own).
+ *
+ * Implementations should be best-effort and resilient: a failed model call
+ * should reject so {@link GenerativeFallbackRenderer} can fall back to the
+ * deterministic generator rather than render nothing.
+ */
+interface RendererGenerator {
+    generate(ctx: GenerateContext): Promise<GeneratedRenderer>;
+}
+/**
+ * A deterministic, non-LLM generator: renders a best-effort, dependency-free
+ * "unknown kind" card from the event's shape (kind, author, tags, content). It
+ * never calls a network or a model, so it is the safe default and the basis for
+ * tests — given the same event it always produces the same HTML.
+ *
+ * The output is intentionally generic and clearly marked as a low-trust
+ * fallback; it makes no claim to understand the kind's semantics.
+ */
+declare const deterministicGenerator: RendererGenerator;
+/**
+ * The pure HTML projection used by {@link deterministicGenerator}. Exported so
+ * tests (and hosts wanting the fallback body without the Promise wrapper) can
+ * assert on it directly.
+ */
+declare function renderDeterministicHtml(event: NostrEvent): string;
+/** Host-supplied signer seam used to finalize the publish-back event. */
+interface RendererSigner {
+    /** The author pubkey (hex) the renderer is published under (the coordinate author). */
+    getPublicKey(): string;
+    /** Finalize an unsigned event template into a signed `NostrEvent`. */
+    signEvent(template: EventTemplate): NostrEvent;
+}
+/** Host-supplied publisher seam used to broadcast the publish-back event. */
+interface RendererPublisher {
+    publishEvent(event: NostrEvent): Promise<unknown>;
+}
+/**
+ * Publish-back configuration. **Off by default**: publish-back never happens
+ * unless the host passes this object with `enabled: true` *and* supplies a
+ * signer and publisher. This is the explicit-enablement gate the issue requires
+ * — there is no implicit / always-on publish path.
+ */
+interface PublishBackOptions {
+    /** Master switch. Must be `true` for any publish to occur. */
+    enabled: boolean;
+    /** Signs the `kind:31036` event (also supplies the coordinate author pubkey). */
+    signer: RendererSigner;
+    /** Broadcasts the signed event. */
+    publisher: RendererPublisher;
+}
+/** Options for {@link GenerativeFallbackRenderer}. */
+interface GenerativeFallbackOptions {
+    /**
+     * The generator to use. Defaults to {@link deterministicGenerator}. A host
+     * injects its model-backed generator here.
+     */
+    generator?: RendererGenerator;
+    /**
+     * Publish-back config. Omit (or pass `enabled: false`) to keep publish-back
+     * off — the default. See {@link PublishBackOptions}.
+     */
+    publish?: PublishBackOptions;
+}
+/** The outcome of {@link GenerativeFallbackRenderer.render}. */
+interface GenerativeFallbackResult {
+    /** The generated renderer (model output, or the deterministic fallback). */
+    rendered: GeneratedRenderer;
+    /** Always `'low'` — branch 4 is a low-trust path. */
+    trust: 'low';
+    /**
+     * The signed `kind:31036` event that was published back, or `undefined` when
+     * publish-back was disabled (the default) or could not run.
+     */
+    published?: NostrEvent;
+}
+/**
+ * Build the unsigned `kind:31036` renderer event for a generated renderer. The
+ * `d` tag is the target kind; the `m` tag is the renderer's mimeType; the body
+ * is the generated HTML. The signed event's coordinate is
+ * `31036:<author-pubkey>:<targetKind>` (see {@link buildUiCoordinate}).
+ *
+ * Exported for tests / hosts that want to inspect the event before signing.
+ */
+declare function buildRendererEventTemplate(targetKind: number, rendered: GeneratedRenderer): EventTemplate;
+/**
+ * Branch 4 renderer: generate a best-effort rendering for an unknown event and,
+ * if explicitly enabled, publish it back as a `kind:31036` renderer.
+ *
+ * Generation is resilient: if the injected model generator throws, the renderer
+ * transparently falls back to {@link deterministicGenerator} so a rendering is
+ * always produced.
+ */
+declare class GenerativeFallbackRenderer {
+    private readonly generator;
+    private readonly publish?;
+    constructor(options?: GenerativeFallbackOptions);
+    /**
+     * Generate a fallback rendering for `event` (low trust), optionally publishing
+     * the result back as a `kind:31036` renderer when publish-back is enabled.
+     */
+    render(event: NostrEvent): Promise<GenerativeFallbackResult>;
+    /** Whether publish-back is currently enabled (for host introspection/UI). */
+    get publishBackEnabled(): boolean;
+}
+/**
+ * The coordinate (`31036:<author-pubkey>:<targetKind>`) a publish-back will/did
+ * use for `targetKind` under `signer`'s identity. Convenience for hosts that
+ * want to show or pre-resolve the coordinate.
+ *
+ * Throws if the signer's pubkey or `targetKind` is malformed — core's
+ * {@link buildUiCoordinate} returns `null` for invalid inputs, which here can
+ * only mean the host wired a bad signer.
+ */
+declare function publishBackCoordinate(signer: RendererSigner, targetKind: number): string;
+
+export { type A2uiDecision, type ConsentDecision, type ConsentRequest, type DispatchGuardInfo, type DispatchInput, type GenerateContext, type GeneratedRenderer, type GenerativeDecision, type GenerativeFallbackOptions, GenerativeFallbackRenderer, type GenerativeFallbackResult, type GuardedDispatchInput, type IntentClassification, KindRegistry, MIME_A2UI, MIME_MCP_APP, type McpUiDecision, type NativeDecision, type PublishBackOptions, type RenderBranch, type RenderDecision, type RenderTrust, type RendererGenerator, type RendererPin, RendererPinStore, type RendererPublisher, type RendererSigner, type ResolvedCoordinate, type SwapApproval, type SwapDecision, type SwapRejection, type SwapRejectionReason, type UiResource, type VerifyRendererInput, type WidgetIntent, buildConsentRequest, buildRendererEventTemplate, classifyIntent, deterministicGenerator, extractUiResource, guardedRenderDispatch, isTrustDowngrade, publishBackCoordinate, renderDeterministicHtml, renderDispatch, resolveRendererMime, resolveUiCoordinate, resolveUiRenderer, verifyRendererTrust };