fix(client): sandbox proxy speaks the current bridge protocol

[witt3rd]

Fixes #213.

Problem

The reference sandbox proxy (sdks/typescript/client/scripts/proxy/index.html) uses a pre-1.7 postMessage protocol that no longer matches the @modelcontextprotocol/ext-apps bridge that @mcp-ui/client depends on. A host that copies this proxy (the documented integration path) gets a ready-handshake timeout → blank card, because the bridge never sees the ready signal it waits for.

What the proxy posted:

window.parent.postMessage({ type: 'ui-proxy-iframe-ready' }, '*');   // ready
// ...and listened for:
event.data.type === 'ui-html-content'                                // html

What the bridge waits for (setupSandboxProxyIframe / AppBridge.sendSandboxResourceReady, verified against ext-apps@1.7.4):

event.data.method === SANDBOX_PROXY_READY_METHOD   // 'ui/notifications/sandbox-proxy-ready'
// html delivered as a JSON-RPC notification:
{ method: 'ui/notifications/sandbox-resource-ready', params: { html, csp } }

Different field (type vs method) and different strings, so onReady never resolves, AppFrame times out at DEFAULT_SANDBOX_TIMEOUT_MS, and no HTML is ever sent.

Fix

scripts/proxy/index.html, rawhtml mode only (the external-url branch is untouched):

• Emit { method: 'ui/notifications/sandbox-proxy-ready' } as the ready signal.
• Read HTML from event.data.params.html on the ui/notifications/sandbox-resource-ready notification.

The double-iframe structure, document.write rendering, and bidirectional relay are unchanged — only the three stale protocol strings are corrected.

Test hardening

ProxyScript.test.ts previously asserted the proxy's own stale strings, which is why it stayed green while the proxy drifted from the bridge. It now:

• imports the real SANDBOX_PROXY_READY_METHOD from @modelcontextprotocol/ext-apps/app-bridge (so it can't drift from the SDK again), and
• sends HTML in the bridge's actual notification shape ({ method, params: { html } }).

Verification: full @mcp-ui/client suite — 74/74 passing (vitest run).

Note

Filed from a fork; happy to adjust the shape to your preferences. If you'd also like the proxy shipped as a package export (so integrators reference a version-matched file rather than copying a scripts/ artifact), I can add that in a follow-up.

[forge-witt3rd]

Second drift found + fixed in this PR (611960f). The protocol-string fix was necessary but not sufficient — a live consumer (spire-ui rendering via AppRenderer) still got a blank card + timed out waiting for sandbox proxy iframe to render.

Root: the proxy gated raw-HTML mode behind ?contentType=rawhtml, but the host component never sets it. AppFrame → buildSandboxUrl sets neither contentType nor url — it delivers HTML via postMessage (sendSandboxResourceReady). So the gate never fired; the proxy fell through to Error: missing url or html parameter, never posted the ready signal, and AppFrame timed out. Confirmed no production caller sets either query param (grep across components/ + utils/ — empty).

Fix: raw-HTML is now the default mode (taken when there's no explicit ?url= target); external-URL is the opt-in. ?contentType=rawhtml still honored, no longer required — matching how AppFrame actually drives the proxy.

Regression guard: ProxyScript.test.ts gains a test that loads the proxy with no query params (as AppFrame does) and asserts it enters raw-HTML mode. Proven both directions — fails against the pre-fix proxy, passes with the fix. Full client suite: 75/75.

Verified in a live browser: fixed proxy served by spire-ui, AppRenderer renders real specialist HTML in the sandboxed iframe — the card paints where it was blank before. This PR now carries both drifts: the wire-format protocol strings and the mode-default gating.