@jini-ai/ui 0.1.2 → 0.3.1

package/dist/features/mcp-ui/sandbox-proxy.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @module features/mcp-ui/sandbox-proxy
+ *
+ * The one piece of NEW infrastructure the official `@mcp-ui/client` swap needs that this package's
+ * hand-rolled Host never did: a **sandbox proxy** page.
+ *
+ * ## Why this exists
+ *
+ * `@mcp-ui/client`'s `AppRenderer`/`AppFrame` do not mount a View by writing HTML into an iframe's
+ * `srcdoc` (the old `McpUiHost` did exactly that). Instead they point an iframe's `src` at a real,
+ * separately-served URL — the "sandbox proxy" — wait for that page to report itself ready
+ * (`ui/notifications/sandbox-proxy-ready`), and only THEN hand it the View's HTML via
+ * `ui/notifications/sandbox-resource-ready`. A host that never serves such a page gets an iframe
+ * that loads nothing and a `AppFrame`/`AppRenderer` that times out after 10s waiting for a ready
+ * signal that will never come.
+ *
+ * This module exports the proxy's source as a **string constant** rather than a static file this
+ * package's own build copies into `dist/`, for the same reason `surfaces/document.ts` builds HTML as
+ * template strings: the natural way for a HOST APPLICATION (Tovu's admin server, `examples/reference-web`'s
+ * dev server, any future consumer) to serve this is to mount ONE route that responds with this exact
+ * body — `res.type('html').send(SANDBOX_PROXY_HTML)` — not to vendor a copy of a file from this
+ * package's `dist/` into their own static-asset pipeline. A string a host can `fetch`/import needs no
+ * new build-script wiring on either side.
+ *
+ * ## What actually needs to be served, and where — the part this package cannot do for you
+ *
+ * This module only produces the BYTES. Actually serving them — mounting a route, choosing a path,
+ * deciding whether it needs a separate origin from the host app for defense-in-depth — is real
+ * per-host infrastructure this package has no way to reach into a consumer's server and add itself.
+ * See this constant's own doc for the concrete tradeoff. `examples/reference-web` mounts it (see
+ * that example's own server/vite config) as the reference wiring for both local development in this
+ * monorepo and for any external host copying the pattern.
+ *
+ * ## The relay contract this implements, verified against the real `@mcp-ui/client@7.1.1` bundle
+ *
+ * `AppFrame`'s internal mount effect (traced from the built package, since this exact mechanism is
+ * not part of its public `.d.ts` surface):
+ * 1. Creates an iframe, sets `sandbox="allow-scripts allow-same-origin allow-forms"`, and navigates
+ *    it to the configured `sandbox.url`.
+ * 2. Waits (10s timeout) for a `postMessage` from that iframe's `contentWindow` whose `data.method`
+ *    is `"ui/notifications/sandbox-proxy-ready"`.
+ * 3. Once ready, delivers the View's HTML via `postMessage({method: "ui/notifications/sandbox-resource-ready",
+ *    params: {html}}, ...)`.
+ *
+ * This module's script does the minimum that satisfies that contract, matching the official
+ * project's own reference implementation (`docs/src/guide/client/walkthrough.md`,
+ * `MCP-UI-Org/mcp-ui` on GitHub, step 3 — verified 2026-08-18): post `sandbox-proxy-ready`
+ * immediately, then on receiving `sandbox-resource-ready`, `document.open(); document.write(html);
+ * document.close();`.
+ *
+ * ## Why `document.write`, not a second nested iframe, and what that means for `window.parent`
+ *
+ * The official docs' own architecture description elsewhere characterizes this as a "double-iframe"
+ * design (an inner iframe hosting the untrusted app inside the outer sandbox-proxy iframe), and a
+ * more hardened production deployment may well nest a second iframe for an additional isolation
+ * hop. This module deliberately does NOT do that, and the choice is load-bearing for THIS package's
+ * existing surface documents: every surface `surfaces/document.ts`/`surfaces/bridge.ts` generate
+ * already contains its own inline protocol bridge script (`renderBridgeScript`) that talks to
+ * `window.parent` directly — written years before this swap, on the assumption (true for the OLD
+ * `srcdoc`-based Host) that its immediate parent IS the ultimate Host. `document.write`-ing that HTML
+ * into THIS SAME window/document (rather than into a second, nested iframe) preserves that
+ * assumption exactly: the guest script's `window.parent` is still the real Host, one hop away, same
+ * as before. A nested-iframe proxy would put the guest TWO hops from the Host, breaking every
+ * existing surface's bridge script silently (its `postMessage`s would land on the proxy, not the
+ * Host, and nothing would ever answer `ui/initialize`). Choosing the single-hop shape is what makes
+ * this swap possible WITHOUT touching `surfaces/bridge.ts`/`surfaces/document.ts`/any existing
+ * surface builder — the wire protocol those already speak (JSON-RPC to `window.parent`) is exactly
+ * what a single-hop proxy delivers unmodified.
+ *
+ * The real security tradeoff this simplification makes, spelled out rather than buried: the outer
+ * (and, here, only) iframe carries `allow-same-origin` (`AppFrame`'s own hardcoded default — not
+ * configurable away without also breaking the ready/resource-ready handshake, which this package's
+ * script needs `window.parent` for regardless of same-origin status). Combined with `document.write`
+ * happening in that SAME window, the guest surface gets full same-origin access to whatever origin
+ * this proxy page is served from. This is the exact hazard `../protocol.ts`'s `MCP_UI_VIEW_SANDBOX`
+ * comment warns about for a `srcdoc` frame — and it is why the official guidance is explicit that a
+ * production sandbox proxy MUST be served from an origin distinct from the host application's own,
+ * so "full same-origin access" only ever reaches an origin that holds nothing sensitive (no cookies,
+ * no session, nothing but this one static page). **Serving this from the SAME origin as an admin
+ * app, as a same-origin convenience route, reopens exactly the risk this package's `srcdoc` design
+ * spent real effort avoiding.** See this session's report for why that tradeoff is left as an
+ * explicitly flagged follow-up rather than silently accepted.
+ *
+ * ## Who is allowed to hand this page HTML — the origin check, and why it is shaped this way
+ *
+ * `document.write`-ing a `postMessage` payload is script execution on this page's origin, so the
+ * listener's guard IS the trust boundary. The first version of this file had none: it read
+ * `event.data` without ever looking at `event.origin` or `event.source`, which meant ANY page that
+ * could get a handle on this window — by framing it, or by `window.open`-ing it and keeping the
+ * returned reference — could post `sandbox-resource-ready` and run its own script on the serving
+ * origin. Two checks close that, and both are needed:
+ *
+ * - `event.source === window.parent` binds delivery to the window that actually embedded this page.
+ *   `event.source` is set by the browser and cannot be forged by the sender, and it is the only
+ *   check that covers the `window.open` case at all: an opener is `window.opener`, never
+ *   `window.parent`. The `window.parent === window` early return makes that airtight — a top-level
+ *   (unframed) copy of this page registers no listener and does nothing, which is correct, because
+ *   an unframed sandbox proxy has no host to serve and no handshake to complete.
+ * - `event.origin === window.location.origin` is the second, independent check, and it is what
+ *   makes a hostile FRAMER fail too (that attacker does satisfy `event.source === window.parent`).
+ *   A host serving this page cross-origin from itself — the hardening the section above recommends
+ *   — will need to widen this to an allowlist. That allowlist must be baked into the served bytes
+ *   by the host's own server, NOT read from this page's query string or fragment: an attacker who
+ *   can frame the page also picks the `src`, so a URL-supplied expected origin is attacker-supplied
+ *   and defeats the check entirely. That is deliberately left unbuilt rather than built wrong.
+ *
+ * For the same reason the ready notification is addressed to `window.location.origin` rather than
+ * broadcast with `"*"`: a hostile framer should not even learn that the page loaded. Neither check
+ * hardcodes any particular host — a consumer's origin is discovered at runtime from the page's own
+ * URL — and neither touches the single-hop `document.write` shape the section above depends on.
+ */
+/**
+ * The sandbox proxy page's complete, self-contained source — see this module's own doc for the
+ * protocol it implements and the security tradeoff serving it makes.
+ *
+ * A host mounts this at whatever URL it then passes as `sandbox={{ url }}` to `AppRenderer`/
+ * `AppFrame` (this package's `McpUiHost`/`useMcpUiHost` included) — e.g. an Express route:
+ * `app.get('/mcp-ui/sandbox-proxy.html', (_req, res) => res.type('html').send(SANDBOX_PROXY_HTML))`.
+ *
+ * That route SHOULD also send `Content-Security-Policy: frame-ancestors 'self'` (plus
+ * `X-Frame-Options: SAMEORIGIN` for browsers predating it). The page's own origin check already
+ * refuses to `document.write` anything a hostile framer sends it, but the header is what stops the
+ * page being framed by a third party in the first place — and it is the layer that still holds if a
+ * future edit to the script below regresses. `frame-ancestors 'none'`/`X-Frame-Options: DENY` is
+ * NOT the value to reach for: this page exists to be framed by its host, so `DENY` breaks every
+ * surface. Do not add `default-src`/`script-src` directives to that header either: a header CSP
+ * survives `document.open()` and would then apply to the guest HTML written in below, silently
+ * breaking any UIResource whose HTML this package did not build. Surfaces built by
+ * `surfaces/document.ts` already carry their own `SURFACE_CSP` meta tag for exactly that job.
+ */
+export declare const SANDBOX_PROXY_HTML = "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>MCP-UI sandbox proxy</title>\n<style>html, body { margin: 0; padding: 0; width: 100%; height: 100%; }</style>\n</head>\n<body>\n<script>\n(function () {\n  \"use strict\";\n  var host = window.parent;\n  var hostOrigin = window.location.origin;\n  if (host === window) return;\n\n  function isFromHost(event) {\n    return event.source === host && event.origin === hostOrigin;\n  }\n\n  window.addEventListener(\"message\", function (event) {\n    if (!isFromHost(event)) return;\n    var data = event.data;\n    if (!data || typeof data !== \"object\") return;\n    if (data.method !== \"ui/notifications/sandbox-resource-ready\") return;\n    var html = data.params && data.params.html;\n    if (typeof html !== \"string\") return;\n    document.open();\n    document.write(html);\n    document.close();\n  });\n\n  host.postMessage({ method: \"ui/notifications/sandbox-proxy-ready\", params: {} }, hostOrigin);\n}());\n</script>\n</body>\n</html>";
+//# sourceMappingURL=sandbox-proxy.d.ts.map

package/dist/features/mcp-ui/sandbox-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-proxy.d.ts","sourceRoot":"","sources":["../../../src/features/mcp-ui/sandbox-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,4/BAmCvB,CAAC"}

package/dist/features/mcp-ui/sandbox-proxy.js

@@ -0,0 +1,167 @@
+/**
+ * @module features/mcp-ui/sandbox-proxy
+ *
+ * The one piece of NEW infrastructure the official `@mcp-ui/client` swap needs that this package's
+ * hand-rolled Host never did: a **sandbox proxy** page.
+ *
+ * ## Why this exists
+ *
+ * `@mcp-ui/client`'s `AppRenderer`/`AppFrame` do not mount a View by writing HTML into an iframe's
+ * `srcdoc` (the old `McpUiHost` did exactly that). Instead they point an iframe's `src` at a real,
+ * separately-served URL — the "sandbox proxy" — wait for that page to report itself ready
+ * (`ui/notifications/sandbox-proxy-ready`), and only THEN hand it the View's HTML via
+ * `ui/notifications/sandbox-resource-ready`. A host that never serves such a page gets an iframe
+ * that loads nothing and a `AppFrame`/`AppRenderer` that times out after 10s waiting for a ready
+ * signal that will never come.
+ *
+ * This module exports the proxy's source as a **string constant** rather than a static file this
+ * package's own build copies into `dist/`, for the same reason `surfaces/document.ts` builds HTML as
+ * template strings: the natural way for a HOST APPLICATION (Tovu's admin server, `examples/reference-web`'s
+ * dev server, any future consumer) to serve this is to mount ONE route that responds with this exact
+ * body — `res.type('html').send(SANDBOX_PROXY_HTML)` — not to vendor a copy of a file from this
+ * package's `dist/` into their own static-asset pipeline. A string a host can `fetch`/import needs no
+ * new build-script wiring on either side.
+ *
+ * ## What actually needs to be served, and where — the part this package cannot do for you
+ *
+ * This module only produces the BYTES. Actually serving them — mounting a route, choosing a path,
+ * deciding whether it needs a separate origin from the host app for defense-in-depth — is real
+ * per-host infrastructure this package has no way to reach into a consumer's server and add itself.
+ * See this constant's own doc for the concrete tradeoff. `examples/reference-web` mounts it (see
+ * that example's own server/vite config) as the reference wiring for both local development in this
+ * monorepo and for any external host copying the pattern.
+ *
+ * ## The relay contract this implements, verified against the real `@mcp-ui/client@7.1.1` bundle
+ *
+ * `AppFrame`'s internal mount effect (traced from the built package, since this exact mechanism is
+ * not part of its public `.d.ts` surface):
+ * 1. Creates an iframe, sets `sandbox="allow-scripts allow-same-origin allow-forms"`, and navigates
+ *    it to the configured `sandbox.url`.
+ * 2. Waits (10s timeout) for a `postMessage` from that iframe's `contentWindow` whose `data.method`
+ *    is `"ui/notifications/sandbox-proxy-ready"`.
+ * 3. Once ready, delivers the View's HTML via `postMessage({method: "ui/notifications/sandbox-resource-ready",
+ *    params: {html}}, ...)`.
+ *
+ * This module's script does the minimum that satisfies that contract, matching the official
+ * project's own reference implementation (`docs/src/guide/client/walkthrough.md`,
+ * `MCP-UI-Org/mcp-ui` on GitHub, step 3 — verified 2026-08-18): post `sandbox-proxy-ready`
+ * immediately, then on receiving `sandbox-resource-ready`, `document.open(); document.write(html);
+ * document.close();`.
+ *
+ * ## Why `document.write`, not a second nested iframe, and what that means for `window.parent`
+ *
+ * The official docs' own architecture description elsewhere characterizes this as a "double-iframe"
+ * design (an inner iframe hosting the untrusted app inside the outer sandbox-proxy iframe), and a
+ * more hardened production deployment may well nest a second iframe for an additional isolation
+ * hop. This module deliberately does NOT do that, and the choice is load-bearing for THIS package's
+ * existing surface documents: every surface `surfaces/document.ts`/`surfaces/bridge.ts` generate
+ * already contains its own inline protocol bridge script (`renderBridgeScript`) that talks to
+ * `window.parent` directly — written years before this swap, on the assumption (true for the OLD
+ * `srcdoc`-based Host) that its immediate parent IS the ultimate Host. `document.write`-ing that HTML
+ * into THIS SAME window/document (rather than into a second, nested iframe) preserves that
+ * assumption exactly: the guest script's `window.parent` is still the real Host, one hop away, same
+ * as before. A nested-iframe proxy would put the guest TWO hops from the Host, breaking every
+ * existing surface's bridge script silently (its `postMessage`s would land on the proxy, not the
+ * Host, and nothing would ever answer `ui/initialize`). Choosing the single-hop shape is what makes
+ * this swap possible WITHOUT touching `surfaces/bridge.ts`/`surfaces/document.ts`/any existing
+ * surface builder — the wire protocol those already speak (JSON-RPC to `window.parent`) is exactly
+ * what a single-hop proxy delivers unmodified.
+ *
+ * The real security tradeoff this simplification makes, spelled out rather than buried: the outer
+ * (and, here, only) iframe carries `allow-same-origin` (`AppFrame`'s own hardcoded default — not
+ * configurable away without also breaking the ready/resource-ready handshake, which this package's
+ * script needs `window.parent` for regardless of same-origin status). Combined with `document.write`
+ * happening in that SAME window, the guest surface gets full same-origin access to whatever origin
+ * this proxy page is served from. This is the exact hazard `../protocol.ts`'s `MCP_UI_VIEW_SANDBOX`
+ * comment warns about for a `srcdoc` frame — and it is why the official guidance is explicit that a
+ * production sandbox proxy MUST be served from an origin distinct from the host application's own,
+ * so "full same-origin access" only ever reaches an origin that holds nothing sensitive (no cookies,
+ * no session, nothing but this one static page). **Serving this from the SAME origin as an admin
+ * app, as a same-origin convenience route, reopens exactly the risk this package's `srcdoc` design
+ * spent real effort avoiding.** See this session's report for why that tradeoff is left as an
+ * explicitly flagged follow-up rather than silently accepted.
+ *
+ * ## Who is allowed to hand this page HTML — the origin check, and why it is shaped this way
+ *
+ * `document.write`-ing a `postMessage` payload is script execution on this page's origin, so the
+ * listener's guard IS the trust boundary. The first version of this file had none: it read
+ * `event.data` without ever looking at `event.origin` or `event.source`, which meant ANY page that
+ * could get a handle on this window — by framing it, or by `window.open`-ing it and keeping the
+ * returned reference — could post `sandbox-resource-ready` and run its own script on the serving
+ * origin. Two checks close that, and both are needed:
+ *
+ * - `event.source === window.parent` binds delivery to the window that actually embedded this page.
+ *   `event.source` is set by the browser and cannot be forged by the sender, and it is the only
+ *   check that covers the `window.open` case at all: an opener is `window.opener`, never
+ *   `window.parent`. The `window.parent === window` early return makes that airtight — a top-level
+ *   (unframed) copy of this page registers no listener and does nothing, which is correct, because
+ *   an unframed sandbox proxy has no host to serve and no handshake to complete.
+ * - `event.origin === window.location.origin` is the second, independent check, and it is what
+ *   makes a hostile FRAMER fail too (that attacker does satisfy `event.source === window.parent`).
+ *   A host serving this page cross-origin from itself — the hardening the section above recommends
+ *   — will need to widen this to an allowlist. That allowlist must be baked into the served bytes
+ *   by the host's own server, NOT read from this page's query string or fragment: an attacker who
+ *   can frame the page also picks the `src`, so a URL-supplied expected origin is attacker-supplied
+ *   and defeats the check entirely. That is deliberately left unbuilt rather than built wrong.
+ *
+ * For the same reason the ready notification is addressed to `window.location.origin` rather than
+ * broadcast with `"*"`: a hostile framer should not even learn that the page loaded. Neither check
+ * hardcodes any particular host — a consumer's origin is discovered at runtime from the page's own
+ * URL — and neither touches the single-hop `document.write` shape the section above depends on.
+ */
+/**
+ * The sandbox proxy page's complete, self-contained source — see this module's own doc for the
+ * protocol it implements and the security tradeoff serving it makes.
+ *
+ * A host mounts this at whatever URL it then passes as `sandbox={{ url }}` to `AppRenderer`/
+ * `AppFrame` (this package's `McpUiHost`/`useMcpUiHost` included) — e.g. an Express route:
+ * `app.get('/mcp-ui/sandbox-proxy.html', (_req, res) => res.type('html').send(SANDBOX_PROXY_HTML))`.
+ *
+ * That route SHOULD also send `Content-Security-Policy: frame-ancestors 'self'` (plus
+ * `X-Frame-Options: SAMEORIGIN` for browsers predating it). The page's own origin check already
+ * refuses to `document.write` anything a hostile framer sends it, but the header is what stops the
+ * page being framed by a third party in the first place — and it is the layer that still holds if a
+ * future edit to the script below regresses. `frame-ancestors 'none'`/`X-Frame-Options: DENY` is
+ * NOT the value to reach for: this page exists to be framed by its host, so `DENY` breaks every
+ * surface. Do not add `default-src`/`script-src` directives to that header either: a header CSP
+ * survives `document.open()` and would then apply to the guest HTML written in below, silently
+ * breaking any UIResource whose HTML this package did not build. Surfaces built by
+ * `surfaces/document.ts` already carry their own `SURFACE_CSP` meta tag for exactly that job.
+ */
+export const SANDBOX_PROXY_HTML = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>MCP-UI sandbox proxy</title>
+<style>html, body { margin: 0; padding: 0; width: 100%; height: 100%; }</style>
+</head>
+<body>
+<script>
+(function () {
+  "use strict";
+  var host = window.parent;
+  var hostOrigin = window.location.origin;
+  if (host === window) return;
+
+  function isFromHost(event) {
+    return event.source === host && event.origin === hostOrigin;
+  }
+
+  window.addEventListener("message", function (event) {
+    if (!isFromHost(event)) return;
+    var data = event.data;
+    if (!data || typeof data !== "object") return;
+    if (data.method !== "ui/notifications/sandbox-resource-ready") return;
+    var html = data.params && data.params.html;
+    if (typeof html !== "string") return;
+    document.open();
+    document.write(html);
+    document.close();
+  });
+
+  host.postMessage({ method: "ui/notifications/sandbox-proxy-ready", params: {} }, hostOrigin);
+}());
+</script>
+</body>
+</html>`;
+//# sourceMappingURL=sandbox-proxy.js.map

package/dist/features/mcp-ui/sandbox-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-proxy.js","sourceRoot":"","sources":["../../../src/features/mcp-ui/sandbox-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmC1B,CAAC"}

package/dist/features/mcp-ui/surfaces/bridge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The global a surface's own script reaches the protocol through.
+ *
+ * A global rather than a module export because the surface script is a second classic `<script>` in
+ * the same document — there are no modules to import between them.
+ */
+export declare const SURFACE_BRIDGE_GLOBAL = "jiniMcpUi";
+/**
+ * Set on `<html>` when the handshake fails, so a host, a test, or a human with devtools open can
+ * tell "the Host never answered `ui/initialize`" apart from "the surface's own script threw".
+ */
+export declare const SURFACE_HANDSHAKE_FAILED_ATTRIBUTE = "data-mcpui-handshake-failed";
+export interface BridgeScriptSpec {
+    /** Reported to the Host as `appInfo.name` in `ui/initialize`. */
+    readonly appName: string;
+    /** Reported to the Host as `appInfo.version`. */
+    readonly appVersion: string;
+    /** Defaults to {@link MCP_UI_PROTOCOL_VERSION}. */
+    readonly protocolVersion?: string;
+}
+/**
+ * Renders the View-side protocol bridge as JavaScript source.
+ *
+ * The emitted script defines `window[SURFACE_BRIDGE_GLOBAL]` with:
+ * - `callTool(name, args)` → `Promise` of the tool result, queued until the handshake completes and
+ *   rejected with the Host's own error message on a JSON-RPC error response.
+ * - `notify(method, params)` → a raw fire-and-forget notification, for the lifecycle messages a
+ *   surface may want beyond what the bridge sends itself.
+ * - `openLink(url)` → `ui/open-link`, the only way an isolated frame can navigate anything.
+ * - `requestTeardown()` → `ui/notifications/request-teardown`, the draft-spec way for a "Done"
+ *   button to ask the Host to remove the frame.
+ * - `whenReady(fn)` → runs `fn` after the handshake, immediately if it already completed.
+ *
+ * The script also answers the Host's `ui/resource-teardown` request. That answer is not optional
+ * politeness: our Host waits (bounded) for it before removing the frame, so a View that never
+ * responded would stall every teardown to its timeout.
+ *
+ * @param spec - See {@link BridgeScriptSpec}.
+ * @returns JavaScript source, to be placed in a classic `<script>` before the surface's own script.
+ * @complexity O(1) — a constant template with three interpolations.
+ */
+export declare function renderBridgeScript(spec: BridgeScriptSpec): string;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/features/mcp-ui/surfaces/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/bridge.ts"],"names":[],"mappings":"AA2CA;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kCAAkC,gCAAgC,CAAC;AAEhF,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CA4HjE"}

package/dist/features/mcp-ui/surfaces/bridge.js

@@ -0,0 +1,200 @@
+/**
+ * @module features/mcp-ui/surfaces/bridge
+ *
+ * The inline `<script>` every generated surface carries: the View half of the MCP Apps handshake,
+ * emitted as a JavaScript source string because it runs inside a sandboxed iframe with no bundler,
+ * no module loader, and no shared runtime to import from.
+ *
+ * ## Why the surface HTML cannot just post an action and be done
+ *
+ * `mcp-ui-apps.ts` states the ordering rule the spec makes normative: a Host MUST NOT send anything
+ * to a View before `ui/notifications/initialized`, and — the mirror of it, which is what this script
+ * has to respect — a Host answers a View's requests only once the handshake is complete. Our own
+ * Host refuses a `tools/call` that arrives in `awaiting-initialize` with a JSON-RPC
+ * `invalidRequest`. So a surface that posted its action on click without ever handshaking would get
+ * a refusal, not an execution. {@link renderBridgeScript} therefore runs `ui/initialize` at load
+ * time and queues any `callTool` made before the response lands.
+ *
+ * ## Which action shape this emits, and what it deliberately does not
+ *
+ * The community `@mcp-ui/client` SDK accepts a legacy, non-JSON-RPC action —
+ * `{ type: 'tool', payload: { toolName, params } }` — and the reference implementation's
+ * `delete-confirmation-ui.ts` emits exactly that. This bridge emits the JSON-RPC
+ * `tools/call` request from {@link MCP_UI_VIEW_METHODS} instead, and emits **only** that.
+ *
+ * That is a real divergence from the brief this module was built to, and it is deliberate: the two
+ * shapes are alternatives, not layers. Emitting both would mean a host that understands both
+ * executes the tool twice — the worst possible outcome for a surface whose entire purpose is
+ * confirming a destructive action. JSON-RPC wins because it is what the Host in `react/mcp-ui/`
+ * speaks, what the standardized spec fixed, and the only one of the two with a response correlated
+ * back to the caller, which is what lets a dialog report "done" or "failed" instead of appearing to
+ * do nothing. A consumer needing the legacy shape for an existing mcp-ui host should build that
+ * surface with its own script rather than have this one emit both.
+ *
+ * ## What the script must never do
+ *
+ * No `localStorage` / `sessionStorage` (both throw `SecurityError` in the opaque origin this
+ * package's sandbox produces — see `MCP_UI_VIEW_SANDBOX`), no `scrollIntoView` (it breaks iframe
+ * preview layout), no cross-document `<a href>` (dead in an isolated frame; use `ui/open-link`
+ * through {@link SURFACE_BRIDGE_GLOBAL} instead).
+ */
+import { escapeJsValue } from '../escape.js';
+import { MCP_UI_PROTOCOL_VERSION } from '../protocol.js';
+/**
+ * The global a surface's own script reaches the protocol through.
+ *
+ * A global rather than a module export because the surface script is a second classic `<script>` in
+ * the same document — there are no modules to import between them.
+ */
+export const SURFACE_BRIDGE_GLOBAL = 'jiniMcpUi';
+/**
+ * Set on `<html>` when the handshake fails, so a host, a test, or a human with devtools open can
+ * tell "the Host never answered `ui/initialize`" apart from "the surface's own script threw".
+ */
+export const SURFACE_HANDSHAKE_FAILED_ATTRIBUTE = 'data-mcpui-handshake-failed';
+/**
+ * Renders the View-side protocol bridge as JavaScript source.
+ *
+ * The emitted script defines `window[SURFACE_BRIDGE_GLOBAL]` with:
+ * - `callTool(name, args)` → `Promise` of the tool result, queued until the handshake completes and
+ *   rejected with the Host's own error message on a JSON-RPC error response.
+ * - `notify(method, params)` → a raw fire-and-forget notification, for the lifecycle messages a
+ *   surface may want beyond what the bridge sends itself.
+ * - `openLink(url)` → `ui/open-link`, the only way an isolated frame can navigate anything.
+ * - `requestTeardown()` → `ui/notifications/request-teardown`, the draft-spec way for a "Done"
+ *   button to ask the Host to remove the frame.
+ * - `whenReady(fn)` → runs `fn` after the handshake, immediately if it already completed.
+ *
+ * The script also answers the Host's `ui/resource-teardown` request. That answer is not optional
+ * politeness: our Host waits (bounded) for it before removing the frame, so a View that never
+ * responded would stall every teardown to its timeout.
+ *
+ * @param spec - See {@link BridgeScriptSpec}.
+ * @returns JavaScript source, to be placed in a classic `<script>` before the surface's own script.
+ * @complexity O(1) — a constant template with three interpolations.
+ */
+export function renderBridgeScript(spec) {
+    const appInfo = escapeJsValue({ name: spec.appName, version: spec.appVersion });
+    const protocolVersion = escapeJsValue(spec.protocolVersion ?? MCP_UI_PROTOCOL_VERSION);
+    const global = SURFACE_BRIDGE_GLOBAL;
+    const failedAttribute = escapeJsValue(SURFACE_HANDSHAKE_FAILED_ATTRIBUTE);
+    return `(function () {
+  "use strict";
+  var HOST = window.parent;
+  var APP_INFO = ${appInfo};
+  var PROTOCOL_VERSION = ${protocolVersion};
+  var nextId = 1;
+  var pending = Object.create(null);
+  var ready = false;
+  var settled = false;
+  var queuedCalls = [];
+  var readyHandlers = [];
+  var hostContext = null;
+
+  // Posted to "*", not to a specific origin, because a sandboxed frame without allow-same-origin
+  // has an opaque origin and no way to learn its embedder's. The Host does not trust origin either
+  // — it authenticates by event.source identity against its own iframe's contentWindow, which a
+  // third party cannot forge.
+  function post(message) { HOST.postMessage(message, "*"); }
+
+  function notify(method, params) {
+    post(params === undefined
+      ? { jsonrpc: "2.0", method: method }
+      : { jsonrpc: "2.0", method: method, params: params });
+  }
+
+  function request(method, params) {
+    return new Promise(function (resolve, reject) {
+      var id = "view-" + nextId++;
+      pending[id] = { resolve: resolve, reject: reject };
+      post({ jsonrpc: "2.0", id: id, method: method, params: params });
+    });
+  }
+
+  // A call made before the handshake completes is held, not sent: our Host answers a pre-handshake
+  // tools/call with a JSON-RPC invalidRequest, so sending early would turn "the user clicked a
+  // little too fast" into a refusal the surface would have to explain. A call held when the
+  // handshake FAILS is rejected rather than held forever, so the dialog can say so.
+  function callTool(name, args) {
+    var params = { name: name, arguments: args || {} };
+    if (ready) return request("tools/call", params);
+    return new Promise(function (resolve, reject) {
+      queuedCalls.push({ resolve: resolve, reject: reject, params: params });
+    });
+  }
+
+  function reportSize() {
+    var root = document.documentElement;
+    notify("ui/notifications/size-changed", { width: root.scrollWidth, height: root.scrollHeight });
+  }
+
+  window.addEventListener("message", function (event) {
+    var data = event.data;
+    if (!data || typeof data !== "object" || data.jsonrpc !== "2.0") return;
+    if (typeof data.method === "string") {
+      if (!("id" in data)) return;
+      if (data.method === "ui/resource-teardown") {
+        post({ jsonrpc: "2.0", id: data.id, result: {} });
+        return;
+      }
+      post({ jsonrpc: "2.0", id: data.id, error: { code: -32601, message: "View does not implement " + data.method } });
+      return;
+    }
+    var waiter = pending[data.id];
+    if (!waiter) return;
+    delete pending[data.id];
+    if (data.error) waiter.reject(toError(data.error));
+    else waiter.resolve(data.result);
+  });
+
+  function toError(error) {
+    var failure = new Error(error && typeof error.message === "string" ? error.message : "Host returned an error");
+    if (error && typeof error.code === "number") failure.code = error.code;
+    return failure;
+  }
+
+  function onHandshakeDone(result) {
+    hostContext = result && result.hostContext ? result.hostContext : null;
+    ready = true;
+    settled = true;
+    notify("ui/notifications/initialized");
+    reportSize();
+    var calls = queuedCalls;
+    var handlers = readyHandlers;
+    queuedCalls = [];
+    readyHandlers = [];
+    for (var i = 0; i < calls.length; i++) request("tools/call", calls[i].params).then(calls[i].resolve, calls[i].reject);
+    for (var j = 0; j < handlers.length; j++) handlers[j]();
+    if (typeof ResizeObserver === "function") new ResizeObserver(reportSize).observe(document.documentElement);
+  }
+
+  function onHandshakeFailed(error) {
+    settled = true;
+    document.documentElement.setAttribute(${failedAttribute}, "true");
+    var calls = queuedCalls;
+    queuedCalls = [];
+    // Rejected, never dropped: a queued call is a click the human already made, and a promise that
+    // never settles is a dialog stuck on "Working…" with nothing to say.
+    for (var i = 0; i < calls.length; i++) calls[i].reject(error instanceof Error ? error : new Error("MCP-UI handshake failed"));
+    // readyHandlers are intentionally not run — "when ready" never became true.
+    readyHandlers = [];
+  }
+
+  request("ui/initialize", {
+    protocolVersion: PROTOCOL_VERSION,
+    appInfo: APP_INFO,
+    appCapabilities: {}
+  }).then(onHandshakeDone, onHandshakeFailed);
+
+  window.${global} = {
+    callTool: callTool,
+    notify: notify,
+    openLink: function (url) { notify("ui/open-link", { url: url }); },
+    requestTeardown: function () { notify("ui/notifications/request-teardown"); },
+    whenReady: function (fn) { if (ready) fn(); else if (!settled) readyHandlers.push(fn); },
+    hostContext: function () { return hostContext; },
+    isReady: function () { return ready; }
+  };
+}());`;
+}
+//# sourceMappingURL=bridge.js.map

package/dist/features/mcp-ui/surfaces/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,6BAA6B,CAAC;AAWhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAChF,MAAM,eAAe,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,IAAI,uBAAuB,CAAC,CAAC;IACvF,MAAM,MAAM,GAAG,qBAAqB,CAAC;IACrC,MAAM,eAAe,GAAG,aAAa,CAAC,kCAAkC,CAAC,CAAC;IAE1E,OAAO;;;mBAGU,OAAO;2BACC,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CAwFE,eAAe;;;;;;;;;;;;;;;;WAgBhD,MAAM;;;;;;;;;MASX,CAAC;AACP,CAAC"}

package/dist/features/mcp-ui/surfaces/checkbox.d.ts

@@ -0,0 +1,25 @@
+export interface CheckboxProps {
+    /** HTML `name`, DOM `id` suffix, and the params key the value is posted under. */
+    readonly name: string;
+    readonly label: string;
+    /** Initial checked state. Defaults to unchecked. */
+    readonly value?: boolean;
+    /** Help text, wired up with `aria-describedby`. */
+    readonly hint?: string;
+    /**
+     * Native checkbox `required` semantics: the box must be CHECKED to submit, not merely answered.
+     * That is the right meaning for the case this control exists for ("I understand this deletes the
+     * record"), and the wrong meaning for a plain optional toggle — leave it off for those.
+     */
+    readonly required?: boolean;
+    readonly disabled?: boolean;
+}
+/**
+ * Renders one boolean field.
+ *
+ * @param props - See {@link CheckboxProps}.
+ * @returns An HTML fragment.
+ * @complexity O(n) in the rendered length.
+ */
+export declare function renderCheckbox(props: CheckboxProps): string;
+//# sourceMappingURL=checkbox.d.ts.map

package/dist/features/mcp-ui/surfaces/checkbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/checkbox.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAS3D"}

package/dist/features/mcp-ui/surfaces/checkbox.js

@@ -0,0 +1,26 @@
+/**
+ * @module features/mcp-ui/surfaces/checkbox
+ *
+ * The boolean control fragment. Laid out inline (control first, label after) rather than
+ * label-above like the other controls, because a checkbox's label is its hit target and stacking it
+ * above leaves a lone box with nothing next to it.
+ */
+import { escapeHtml } from '../escape.js';
+import { fieldDescribedBy, fieldElementId, renderFieldLabel } from './document.js';
+/**
+ * Renders one boolean field.
+ *
+ * @param props - See {@link CheckboxProps}.
+ * @returns An HTML fragment.
+ * @complexity O(n) in the rendered length.
+ */
+export function renderCheckbox(props) {
+    const id = fieldElementId(props.name);
+    const attributes = ` id="${escapeHtml(id)}" name="${escapeHtml(props.name)}"` +
+        (props.value === true ? ' checked' : '') +
+        (props.required === true ? ' required' : '') +
+        (props.disabled === true ? ' disabled' : '') +
+        fieldDescribedBy(props);
+    return `<div class="mcpui-field mcpui-field-inline">\n<input class="mcpui-checkbox" type="checkbox"${attributes}>\n<span>${renderFieldLabel(props)}</span>\n</div>`;
+}
+//# sourceMappingURL=checkbox.js.map

package/dist/features/mcp-ui/surfaces/checkbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkbox.js","sourceRoot":"","sources":["../../../../src/features/mcp-ui/surfaces/checkbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAmBnF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAoB;IACjD,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,UAAU,GACd,QAAQ,UAAU,CAAC,EAAE,CAAC,WAAW,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG;QAC1D,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,OAAO,8FAA8F,UAAU,YAAY,gBAAgB,CAAC,KAAK,CAAC,iBAAiB,CAAC;AACtK,CAAC"}