[AI-stack FB4] fresh-ui: mcp-ui-widget (themed sandboxed ui:// iframe)

[rickylabs]

Add an mcp-ui-widget fresh-ui registry island that renders ui:// MCP-UI resources in a themed, sandboxed iframe and remounts cleanly on theme change.

Context

Part of epic #238 · cluster fresh-ui · wave v1 · depends-on FB0, FA3.

This slice sits at the top of the fresh-ui plane's DAG: it consumes FB0's ai collection registration and FA3's ui:// origin/server handler to ship the actual consumer-facing widget. It cannot land before either, since there is no collection to register into and no origin to point the iframe at.

Problem / motivation

eis-chat renders MCP-UI resources today via a hand-rolled iframe with no sandbox hardening, no theme propagation, and no defined remount contract, so a theme switch leaves a stale iframe showing the previous theme's injected styles (or, worse, a half-updated DOM). NetScript has no registry item at all for consuming ui:// resources; fresh-ui's generative-UI story is incomplete without a themed, sandboxed widget that the renderer can hand a resource URL to and trust it will behave consistently across theme changes.

Scope

Ships

• packages/fresh-ui/registry/islands/McpUiWidget.tsx — Fresh island rendering an <iframe> against a caller-supplied ui://-resolved src (the FA3-owned origin), with a restrictive sandbox attribute (allow-scripts only; no allow-same-origin).
• Keyed remount: the iframe is keyed on the active theme value so a theme change forces a full unmount/remount instead of reusing a stale iframe document.
• registry.manifest.ts: new registry item mcp-ui-widget (kind: 'island', layer: 3, tags ['ai', 'mcp-ui', 'iframe'], registryDependencies: ['theme-seed']), appended to the ai collection's items list (the collection itself is created by FB0).

Out of scope

• The ui:// server handler / origin that actually serves MCP-UI resources — owned by FA3.
• Creating the ai collection and registering the 7 chat primitives — owned by FB0 (hard prerequisite for this slice).
• The generative-UI renderer that decides when to hand a resource URL to this widget, and the curated design-system vocabulary around it — owned by the fresh-ui renderer slice(s) tracked separately in the epic: NetScript AI Stack — first-class AI runtime, chat & plugin seams (anchor #219) #238 DAG.
• Any postMessage/RPC bridge between host app and iframe content beyond the iframe boundary itself — not specified in this slice; flag as a follow-on if the widget needs bidirectional messaging.

Public surface

• New file packages/fresh-ui/registry/islands/McpUiWidget.tsx exporting a default island component, approximate props { src: string; theme: string; title?: string; sandbox?: string }.
• New registry.manifest.ts entry: { name: 'mcp-ui-widget', kind: 'island', layer: 3, files: [...], registryDependencies: ['theme-seed'], tags: ['ai', 'mcp-ui', 'iframe'] }.
• mcp-ui-widget added to the ai collection's items array (collection object owned/created by FB0; this slice only appends its own item id).
• No new @netscript/fresh-ui subpath exports — registry items are copy-scaffolded files, not module exports.

Acceptance & fitness gates

• F-5: McpUiWidget.tsx carries the same JSDoc/@module convention as existing registry islands (e.g. Toast.tsx); item stays within the manifest's per-item field conventions.
• F-6: @netscript/fresh-ui still publishes via deno task publish:dry-run WITHOUT --allow-slow-types after the new file and manifest entry land.
• gate:e2e -> deferred to follow-up test(cli-e2e): scaffold.runtime coverage for ui:add ai (McpUiWidget) — split from #257 #561 (ui:add scaffold.runtime e2e coverage); tracked separately, not a merge gate for the fresh-ui island (island proven via PR feat(fresh-ui): [FB4] mcp-ui-widget — themed sandboxed ui:// iframe island #550 IMPL-EVAL, evaluate-257.md).
• Keyed remount verified: changing the theme prop produces a distinct iframe mount (not a reused DOM node retaining the prior theme's injected content).
• Sandbox attribute is present and restrictive on every render path (allow-scripts without allow-same-origin), and src only ever resolves to the FA3-owned origin, never a same-origin app route.
• deno task check / lint pass on packages/fresh-ui with the new file and manifest entry included.

Dependencies

Depends on FB0, FA3 (GitHub numbers tracked in the #238 DAG checklist). FB0 must land first to create the ai collection this slice appends into; FA3 must land first to provide the ui:// origin this widget's iframe points at.

Size

M

Part of #238

[rickylabs]

Concrete context from eis-chat (the flagship consumer, rickylabs/eis-chat) — a showcase, not a recommendation. Built under app-level constraints (Fresh 2.3 + vite SSR, NetScript alpha.19, single-app embedded, hand-rolled because these seams didn't exist yet). One data point to borrow / adapt / reject as fits the framework design — the call is yours. — posted by the eis-chat coordinator agent.

We shipped this themed sandboxed ui:// widget (eis-chat #57/#51, 26e1b65 + cab2acd) and burned real time on a subtle failure your remount contract should design against.

• The widget — apps/dashboard/components/ui/mcp-widget.tsx: wraps @mcp-ui/client's AppRenderer pointed at a same-origin sandbox-proxy page (/mcp-sandbox.html, served by FA3-style middleware). Theme is read off the document root and the widget is keyed on the active theme so a toggle forces a clean remount — this matches your key-on-theme requirement.
• CSP — the per-widget CSP is serialized onto the proxy URL as a tamper-proof ?csp=<json> param, which the sandbox route turns into a real CSP header + guest <meta> (Excalidraw needed a tightly-scoped script/style/img/font/media-src set).

The gotcha saga (this is the valuable part): our "grey box" / blank-widget bug was NOT empty HTML — it was unstable props. A fresh new URL() (and a fresh sandbox object) constructed on every streaming render tore down the AppRenderer's sandbox-proxy connect effect before the sandbox-resource-ready message delivered the widget HTML. The connection never completed → blank iframe. Fix: memoize the sandbox { url, csp } object and the part, add a !!html guard, and only remount on the theme key.

Design implication for your mcp-ui-widget: the acceptance gate should assert the iframe connects and receives its resource across a streaming re-render, not just that it mounts with a sandbox attribute. The dangerous case is prop identity churn during streaming, which a static mount test won't catch. Your allow-scripts only / no allow-same-origin sandbox posture matches ours; just make sure the src/CSP props are referentially stable or the sandbox handshake races the teardown.

[rickylabs]

eis-chat matrix: FB4 renders the widget but can't ACT without the new FA4 call-handler (#379)

Matrix (.llm/tmp/run/ai-stack-238--impl/eischat-matrix.md, §9). eis-chat #39/#41/#56 (closed) ship the full interactive-MCP-App round trip. FB4 (this issue) + FA3 (#252, merged) cover the display half only. The call handler — the server route turning a widget tool action into a real tools/call with allowlist + stdio fallback — is now filed as FA4 (#379) and is a hard dependency for FB4 to be more than a static render.

Reference files (eis-chat @ HEAD b65094a):

• apps/dashboard/routes/mcp-sandbox.html.ts — sandbox proxy (FA3 side)
• apps/dashboard/routes/api/mcp-apps/call.ts — the call handler (FA4)
• apps/dashboard/lib/guest-tokens.ts — DS-token injection for themed widgets
• pinned deps: @mcp-ui/client@7.1.1, ext-apps ^1.2

ADJUST: FB4's remount-on-theme-change contract should reuse FA3's guestTokenStyle DS-token injection so a theme switch re-themes the guest, not just the host frame.