@plitzi/sdk-server 0.32.7 → 0.32.9

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @plitzi/sdk-server
 
+## 0.32.9
+
+### Patch Changes
+
+- v0.32.9
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.9
+  - @plitzi/sdk-schema@0.32.9
+  - @plitzi/sdk-shared@0.32.9
+
+## 0.32.8
+
+### Patch Changes
+
+- v0.32.8
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.8
+  - @plitzi/sdk-schema@0.32.8
+  - @plitzi/sdk-shared@0.32.8
+
 ## 0.32.7
 
 ### Patch Changes

package/dist/core/http/stages/static.js

@@ -18,6 +18,8 @@ var configStaticStage = (ctx) => {
 	for (const [prefix, rootDir] of Object.entries(mounts)) {
 		const normalizedPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
 		if (ctx.req.path === prefix || ctx.req.path.startsWith(normalizedPrefix)) {
+			ctx.res.setHeader("Access-Control-Allow-Origin", "*");
+			ctx.res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
 			if (serveStatic({
 				...ctx.req,
 				path: ctx.req.path.slice(prefix.length) || "/"

package/dist/core/services/mcp.js

@@ -7,7 +7,7 @@ var serveMcp = (ctx) => {
 	const { previewClient, screenshot } = ctx.config;
 	const preview = previewClient ? createHttpPreviewClient(previewClient) : void 0;
 	const screenshotClient = screenshot ? createHttpScreenshotClient(screenshot) : void 0;
-	return handleMcp(ctx.raw, ctx.rawRes, ctx.req, ctx.config.adapters, preview, screenshotClient, ctx.config.mcpLogger);
+	return handleMcp(ctx.raw, ctx.rawRes, ctx.req, ctx.config.adapters, preview, screenshotClient, ctx.config.mcpLogger, ctx.config.renderApp);
 };
 var mcpStage = async (ctx) => {
 	if (!ctx.req.path.startsWith(mcpPathOf(ctx.config.mcp?.path))) return false;

package/dist/core/services/registry.js

@@ -25,6 +25,10 @@ var buildSSRPipeline = (services) => {
 	stages.push(services.ssr ? ssrStage : notFoundStage);
 	return stages;
 };
-var buildMCPPipeline = () => [healthStage, mcpOnlyStage];
+var buildMCPPipeline = () => [
+	healthStage,
+	configStaticStage,
+	mcpOnlyStage
+];
 //#endregion
 export { buildMCPPipeline, buildSSRPipeline };

package/dist/modules/mcp/handler.js

@@ -64,12 +64,13 @@ var serveMcp = async (raw, res, server) => {
 		await transport.close();
 	}
 };
-var handleMcp = (raw, res, req, adapters, preview, screenshot, logger) => serveMcp(raw, res, createMcpServer({
+var handleMcp = (raw, res, req, adapters, preview, screenshot, logger, renderApp) => serveMcp(raw, res, createMcpServer({
 	adapters,
 	getSpaceId: () => adapters.getSpaceId?.(req) ?? Promise.resolve(void 0),
 	preview,
 	screenshot,
-	logger
+	logger,
+	renderApp
 }));
 //#endregion
 export { createMcpServer, handleMcp, readMcpBody, serveMcp };

package/dist/modules/mcp/helpers/guide.js

@@ -1,5 +1,5 @@
 //#region src/modules/mcp/helpers/guide.ts
-var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is kebab-case and ATOMIC (shorthands like border/padding expanded; compound ones like flex/background/font rejected — use longhands); style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers).";
+var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is kebab-case and ATOMIC (shorthands like border/padding expanded; compound ones like flex/background/font rejected — use longhands); style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
 var guideQuickstart = `# Plitzi AI MCP — quickstart
 This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
 

package/dist/modules/mcp/resources/register.js

@@ -3,6 +3,7 @@ import { guideText } from "../helpers/guide.js";
 import { resourceErrorMessage } from "./canonical.js";
 import { envelope, jsonContents } from "./envelope.js";
 import { readResource } from "./router.js";
+import { registerRenderResources } from "./renderGuide.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
 //#region src/modules/mcp/resources/register.ts
 /** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
@@ -32,6 +33,7 @@ var registerResources = (server, getSpace, env, log) => {
 		description: "Valid kebab-case CSS property keys",
 		mimeType: "application/json"
 	}, () => jsonContents("plitzi://css-properties", envelope(cssProperties)));
+	registerRenderResources(server);
 	const fixed = [
 		[
 			"Primer",

package/dist/modules/mcp/resources/renderApp.js

@@ -0,0 +1,182 @@
+//#region src/modules/mcp/resources/renderApp.ts
+var RENDER_APP_URI = "ui://plitzi/render.html";
+var RENDER_APP_MIME = "text/html;profile=mcp-app";
+var RENDER_APP_CSP = {
+	resourceDomains: [
+		"*",
+		"data:",
+		"blob:"
+	],
+	connectDomains: ["*"]
+};
+var RENDER_APP_META = {
+	ui: { csp: RENDER_APP_CSP },
+	"openai/widgetCSP": {
+		resource_domains: RENDER_APP_CSP.resourceDomains,
+		connect_domains: RENDER_APP_CSP.connectDomains
+	}
+};
+var appHtml = (sdkBase, devMode) => {
+	const js = `${sdkBase}/sdk-assets/plitzi-sdk.js`;
+	const vendor = `${sdkBase}/sdk-assets/${devMode ? "plitzi-sdk-dev-vendor.js" : "plitzi-sdk-vendor.js"}`;
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Plitzi widget</title>
+    <link rel="modulepreload" href="${vendor}" crossorigin />
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "${vendor}",
+          "react-dom": "${vendor}",
+          "react-dom/client": "${vendor}",
+          "react/jsx-runtime": "${vendor}",
+          "react/compiler-runtime": "${vendor}",
+          "@plitzi/plitzi-sdk": "${js}"
+        }
+      }
+    <\/script>
+    <link href="${`${sdkBase}/sdk-assets/plitzi-sdk.css`}" rel="stylesheet" />
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+      #plitzi:empty::after {
+        content: 'Rendering…';
+        display: block;
+        padding: 16px;
+        font: 14px system-ui, sans-serif;
+        color: #64748b;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="plitzi" class="plitzi-root-container"></div>
+    <script type="module">
+      const send = msg => window.parent.postMessage(msg, '*');
+      const root = document.getElementById('plitzi');
+      let mounted = false;
+
+      // Replace the 'Rendering…' placeholder with an explicit failure panel — otherwise a tool that returns
+      // { rendered:false } (no offlineData) or an SDK that fails to load would leave the iframe stuck forever.
+      const showError = (title, details) => {
+        mounted = true;
+        root.textContent = '';
+        const box = document.createElement('div');
+        box.setAttribute('style', 'padding:16px;font:13px/1.5 system-ui,sans-serif;color:#b91c1c');
+        const h = document.createElement('strong');
+        h.textContent = title;
+        box.appendChild(h);
+        if (details) {
+          const pre = document.createElement('pre');
+          pre.setAttribute('style', 'margin:8px 0 0;white-space:pre-wrap;color:#7f1d1d;font-size:12px');
+          pre.textContent = details;
+          box.appendChild(pre);
+        }
+
+        root.appendChild(box);
+      };
+
+      // The failed-render text is the tool's JSON summary ({ rendered:false, errors:[{path,message,hint}] }).
+      const errorText = params => {
+        const item = Array.isArray(params && params.content) ? params.content.find(c => c.type === 'text') : undefined;
+        if (!item) {
+          return '';
+        }
+
+        try {
+          const parsed = JSON.parse(item.text);
+          if (Array.isArray(parsed.errors)) {
+            return parsed.errors
+              .map(e => '• ' + (e.path ? e.path + ': ' : '') + e.message + (e.hint ? ' — ' + e.hint : ''))
+              .join('\\n');
+          }
+
+          return item.text;
+        } catch {
+          return item.text;
+        }
+      };
+
+      const mount = async params => {
+        if (mounted) {
+          return;
+        }
+
+        const offlineData = params && params.structuredContent && params.structuredContent.offlineData;
+        if (!offlineData) {
+          showError('Render failed', errorText(params) || 'The tool returned no widget data.');
+
+          return;
+        }
+
+        mounted = true;
+        try {
+          const { render } = await import('@plitzi/plitzi-sdk');
+          render('plitzi', { offlineData, offlineMode: true, environment: 'main', renderMode: 'raw' }, {}, false, false);
+        } catch (err) {
+          showError('SDK failed to load', String((err && err.message) || err));
+        }
+      };
+
+      window.addEventListener('message', event => {
+        const msg = event.data;
+        if (!msg || msg.jsonrpc !== '2.0') {
+          return;
+        }
+
+        // Reply to the initialize result: the host withholds tool data until it gets our 'initialized' notification.
+        if (msg.id === 1 && 'result' in msg) {
+          send({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
+
+          return;
+        }
+
+        if (msg.method === 'ui/notifications/tool-result') {
+          void mount(msg.params);
+        }
+      });
+
+      // Start the handshake immediately — nothing external blocks it, so the iframe is 'ready' at once.
+      send({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'ui/initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          appInfo: { name: 'Plitzi Widget', version: '1.0.0' },
+          appCapabilities: { availableDisplayModes: ['inline'] }
+        }
+      });
+    <\/script>
+  </body>
+</html>`;
+};
+var appCache = /* @__PURE__ */ new Map();
+var getAppHtml = (sdkBase, devMode) => {
+	const key = `${devMode ? "dev" : "prod"}|${sdkBase}`;
+	let html = appCache.get(key);
+	if (!html) {
+		html = appHtml(sdkBase, devMode);
+		appCache.set(key, html);
+	}
+	return html;
+};
+var registerRenderApp = (server, sdkBase, devMode) => {
+	const html = getAppHtml(sdkBase, devMode);
+	server.registerResource("plitzi-render-app", RENDER_APP_URI, {
+		description: "Interactive view that renders a plitzi_render widget with the Plitzi SDK (client-side).",
+		mimeType: RENDER_APP_MIME,
+		_meta: RENDER_APP_META
+	}, () => ({ contents: [{
+		uri: RENDER_APP_URI,
+		mimeType: RENDER_APP_MIME,
+		text: html,
+		_meta: RENDER_APP_META
+	}] }));
+};
+//#endregion
+export { RENDER_APP_URI, registerRenderApp };

package/dist/modules/mcp/resources/renderGuide.js

@@ -0,0 +1,186 @@
+import { BUILTIN_COMPONENTS } from "../catalogs/builtinComponents.js";
+import { envelope, jsonContents } from "./envelope.js";
+//#region src/modules/mcp/resources/renderGuide.ts
+var RENDER_GUIDE_URI = "plitzi://render/guide";
+var RENDER_TYPES_URI = "plitzi://render/types";
+var RENDER_TYPE_CATEGORIES = /* @__PURE__ */ new Set([
+	"structure",
+	"basic",
+	"media",
+	"form",
+	"provider"
+]);
+var renderTypesNote = "The built-in element types you can put in a plitzi_render widget, grouped by category. Pick by `description`. For the props of each type and the full authoring model, read plitzi://render/guide. Types that need a backend (providers) or a plugin are omitted because the widget renders offline.";
+var renderTypes = () => {
+	const types = {};
+	for (const [name, info] of Object.entries(BUILTIN_COMPONENTS)) if (info && info.category && RENDER_TYPE_CATEGORIES.has(info.category)) types[name] = {
+		label: info.label,
+		category: info.category,
+		description: info.description
+	};
+	return {
+		note: renderTypesNote,
+		types
+	};
+};
+var renderGuideText = `# plitzi_render — authoring guide
+
+\`plitzi_render\` shows the user a live UI widget. You build it as a list of \`operations\` (applied IN ORDER) that
+assemble an element tree under one pre-seeded root page whose ref is **"render"**. It renders fully offline — no
+space, no backend, no account. Same operation vocabulary as the editing tool plitzi_apply, aimed at one page.
+
+Most widgets are **presentation only** — the structure + styling below is all you need, so start there. The widget
+runs the live Plitzi SDK though, so it can also **fetch data** (an \`apiContainer\`) and **react to events**
+(interaction flows); see "Data & interactivity" at the end when a widget needs them.
+
+Each call renders a **fresh** widget with no memory of previous calls — always send **every** operation the widget
+needs in the one call. To change a widget, re-send the whole thing.
+
+## Build the whole widget in ONE upsertElement (nest with \`children\`)
+
+The simplest, least error-prone path: a single \`upsertElement\` whose \`element\` carries a nested \`children\` tree —
+so you describe the layout the way it renders, no ref-juggling. \`pageRef: "render"\` is required; each element in the
+tree needs a unique \`ref\` — a name you choose from letters, digits, \`-\` and \`_\`, **starting with a letter and with
+no dots** (e.g. \`price-row\`, \`cta_button\`).
+
+\`\`\`json
+{ "type": "upsertElement", "pageRef": "render", "element": {
+    "ref": "card", "type": "container", "style": { "base": ["card"] },
+    "children": [
+      { "ref": "plan",   "type": "heading",   "subType": "h3", "props": { "content": "Pro" } },
+      { "ref": "amount", "type": "text",      "props": { "content": "$29/mo" }, "style": { "base": ["price"] } },
+      { "ref": "buy",    "type": "button",    "props": { "content": "Start free trial" }, "style": { "base": ["cta"] } }
+    ]
+} }
+\`\`\`
+
+An element is \`{ ref, type, subType?, props?, style?, children? }\`. Children render in array order. (You *can* also
+add elements one-by-one with a top-level \`parentRef: "<existing ref>"\` and optional \`position\` — useful to append to
+or restructure something you already created — but for a fresh widget the inline \`children\` tree is easier.)
+
+## Style with reusable classes — upsertDefinition
+
+Styling is separate from structure: declare a class, then attach it by ref.
+
+\`\`\`json
+{ "type": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "24px", "border-radius": "12px" } }
+\`\`\`
+- CSS properties in **kebab-case** (\`background-color\`, \`font-size\`, \`border-radius\`), values as plain strings.
+- Attach to an element via \`style: { "base": ["card"] }\`. Stack classes: \`"base": ["card", "shadow"]\`.
+- One \`ref\` can name both an element and its class (as above) — they live in different namespaces.
+- Lay containers out with flexbox: \`{ "display": "flex", "flex-direction": "column", "gap": "12px" }\`.
+- **Mind the intrinsic display.** Some types start non-block: \`text\` is \`display: inline\`, so to stack or size it,
+  wrap it in a \`container\` (or set \`display: block\`). \`heading\` and \`paragraph\` are already block.
+- **Use atomic longhands.** \`padding\`, \`margin\`, \`border\`, \`border-radius\` are fine (they expand cleanly), but
+  \`flex\`, \`background\` and \`font\` are rejected — write \`display\`+\`flex-direction\`, \`background-color\`,
+  \`font-size\`+\`font-weight\` instead. An unknown property errors with the correct kebab-case key suggested.
+- **Responsive:** add \`tablet\` and/or \`mobile\` blocks next to \`desktop\` (same shape); they override desktop on
+  smaller screens — \`{ "desktop": { "font-size": "36px" }, "mobile": { "font-size": "24px" } }\`.
+- **Interactive states:** nest under \`states\` keyed by pseudo-class, each with its own breakpoint block —
+  \`{ "desktop": { "background-color": "#3b82f6" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } }\`
+  (\`hover\`, \`active\`, \`focus\`).
+
+## Element types (type → what to set)
+
+| type | renders | set |
+|---|---|---|
+| \`container\` | layout box (a div) | nothing — style it with flex/grid |
+| \`heading\` | h1–h6 title | \`props.content\`, element \`subType\`: "h1"…"h6" |
+| \`paragraph\` | body text block (\`<p>\`) | \`props.content\` |
+| \`text\` | inline text | \`props.content\` |
+| \`button\` | clickable button | \`props.content\` |
+| \`link\` | anchor | \`props.content\` (label), \`props.href\`, \`props.target\`: "self" \\| "blank" |
+| \`image\` | \`<img>\` | \`props.src\`, \`props.alt\` |
+| \`video\` | embedded video | \`props.src\` |
+| \`list\` / \`listItem\` | \`<ul>\` / \`<li>\` | nesting only |
+| \`markdown\` | rendered markdown | \`props.content\` |
+
+\`subType\` is an element-level field (not a prop). Guessing is safe: an unknown prop for a type comes back as a
+**warning naming the right one**, not an error. This table covers the everyday types; the resource
+**plitzi://render/types** lists every built-in type you can use (with descriptions) — read it when you need one
+that is not here (lists, tabs, dialogs, forms, icons…).
+
+\`image\`/\`video\` \`src\` accepts any \`https\` URL, or a \`data:\`/\`blob:\` URI for a fully self-contained graphic
+(e.g. an inline SVG icon or a base64 image) — both render with no extra setup.
+
+## Full worked example — a pricing card
+
+\`\`\`json
+{
+  "operations": [
+    { "type": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "24px", "background-color": "#ffffff", "border-radius": "12px", "width": "260px", "text-align": "center", "box-shadow": "0 4px 20px rgba(0,0,0,0.08)" } },
+    { "type": "upsertDefinition", "ref": "price", "desktop": { "font-size": "36px", "font-weight": "800", "color": "#3b82f6" } },
+    { "type": "upsertDefinition", "ref": "cta", "desktop": { "background-color": "#3b82f6", "color": "#ffffff", "padding": "12px 20px", "border-radius": "8px", "font-weight": "600" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } },
+    { "type": "upsertElement", "pageRef": "render", "element": {
+        "ref": "card", "type": "container", "style": { "base": ["card"] },
+        "children": [
+          { "ref": "plan",   "type": "heading",   "subType": "h3", "props": { "content": "Pro" } },
+          { "ref": "amount", "type": "text",      "props": { "content": "$29/mo" }, "style": { "base": ["price"] } },
+          { "ref": "feat",   "type": "paragraph", "props": { "content": "Unlimited projects" } },
+          { "ref": "buy",    "type": "button",    "props": { "content": "Start free trial" }, "style": { "base": ["cta"] } }
+        ]
+    } }
+  ]
+}
+\`\`\`
+
+## Data & interactivity (optional)
+
+The widget runs the live SDK, so beyond static layout it can fetch data and respond to events. Both are wired by
+\`ref\`, just like styling. (Full reference: **plitzi://guide** — sections Data bindings and Interactions.)
+
+### Fetch data — a provider + a binding
+An \`apiContainer\` fetches at runtime and exposes the result as the source **\`apiContainer_<idRef>.data\`**, visible
+to its **DESCENDANTS only** — the bound element must live inside the container's subtree. \`upsertBinding\` then
+connects that source to a descendant's field.
+
+\`\`\`json
+{
+  "operations": [
+    { "type": "upsertElement", "pageRef": "render", "element": {
+        "ref": "products", "type": "apiContainer", "props": { "query": "<your data query — see plitzi://guide>" },
+        "children": [ { "ref": "title", "type": "heading", "subType": "h3", "props": { "content": "…" } } ]
+    } },
+    { "type": "upsertBinding", "pageRef": "render", "ref": "title", "category": "attributes", "binding": { "to": "content", "source": "apiContainer_products.data.0.name" } }
+  ]
+}
+\`\`\`
+- \`category\`: \`"attributes"\` (a prop such as \`content\`/\`src\`), \`"style"\` (a CSS value) or \`"initialState"\`.
+- \`binding.to\` is the target field; \`binding.source\` is the \`<type>_<idRef>.path\` into the provider's data.
+- \`mockData\` on the provider is builder-only — set a real \`query\` for the widget to actually fetch.
+
+### React to events — an interaction flow
+\`upsertInteractionFlow\` attaches an ordered \`nodes\` list to an element; the FIRST node is a \`trigger\` (e.g.
+\`onClick\`), the rest run after it. Each following step is one of:
+- **\`globalCallback\`** (OMIT \`elementId\`) — a built-in app action: \`addNotification\` (\`params.content\`),
+  \`navigate\`, \`setState\` (\`key\`/\`type\`/\`value\`), \`authLogin\`/\`authLogout\`…
+- **\`callback\`** (\`elementId\` = an element, defaults to the trigger's) — that ELEMENT's OWN callback: e.g. an
+  \`apiContainer\` re-fetches, a \`form\` submits. Each type's own callback action names are in plitzi://guide.
+
+\`\`\`json
+{ "type": "upsertInteractionFlow", "pageRef": "render", "ref": "buy", "nodes": [
+    { "title": "On click", "nodeType": "trigger", "action": "onClick" },
+    { "title": "Toast", "nodeType": "globalCallback", "action": "addNotification", "params": { "content": "Added to cart" } }
+] }
+\`\`\`
+
+## When it fails
+The tool returns \`rendered: false\` with \`errors: [{ path, message, hint }]\`. Read the hint, fix that one op, and
+retry — you never lose the rest of the batch.
+`;
+var registerRenderResources = (server) => {
+	server.registerResource("Render guide", RENDER_GUIDE_URI, {
+		description: "How to author a plitzi_render widget: operations, element types, styling, examples.",
+		mimeType: "text/markdown"
+	}, () => ({ contents: [{
+		uri: RENDER_GUIDE_URI,
+		mimeType: "text/markdown",
+		text: renderGuideText
+	}] }));
+	server.registerResource("Render element types", RENDER_TYPES_URI, {
+		description: "Built-in element types a plitzi_render widget can use, with descriptions.",
+		mimeType: "application/json"
+	}, () => jsonContents(RENDER_TYPES_URI, envelope(renderTypes())));
+};
+//#endregion
+export { RENDER_GUIDE_URI, RENDER_TYPES_URI, registerRenderResources };

package/dist/modules/mcp/server.js

@@ -2,6 +2,7 @@ import { emptySpace, emptySpaceMessage, unauthorizedSpaceMessage } from "./helpe
 import { serverInstructions } from "./helpers/guide.js";
 import { createMcpLog } from "./helpers/log.js";
 import { registerResources } from "./resources/register.js";
+import { registerRenderApp } from "./resources/renderApp.js";
 import { tools } from "./tools/index.js";
 import { isCallToolResult } from "../ai/toolkit.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
@@ -11,7 +12,7 @@ var asText = (data) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(data)
 }] });
-var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) => {
+var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger, renderApp }) => {
 	const log = createMcpLog(logger);
 	let spaceIdPromise;
 	const requireSpaceId = () => spaceIdPromise ??= getSpaceId().then((id) => {
@@ -41,9 +42,10 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.7"
+		version: "0.32.9"
 	}, { instructions: serverInstructions });
 	registerResources(server, getSpace, MCP_ENV, log);
+	if (renderApp) registerRenderApp(server, renderApp.sdkBase, renderApp.devMode ?? false);
 	const toolContext = async () => ({
 		space: await getSpace(),
 		env: MCP_ENV,
@@ -64,7 +66,8 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 		server.registerTool(tool.name, {
 			title: tool.title,
 			description: tool.description,
-			inputSchema: tool.inputShape
+			inputSchema: tool.inputShape,
+			...tool.ui && renderApp ? { _meta: { ui: tool.ui } } : {}
 		}, async (args) => {
 			const start = performance.now();
 			try {

package/dist/modules/mcp/tools/render.js

@@ -1,4 +1,5 @@
 import { emptySpace } from "../helpers/space.js";
+import { RENDER_APP_URI } from "../resources/renderApp.js";
 import { operations } from "./operations/index.js";
 import { applyOperations } from "./apply/dispatch.js";
 import { defineTool } from "./shared/tool.js";
@@ -104,10 +105,11 @@ var toRenderResult = (res) => {
 var renderTool = defineTool({
 	name: "plitzi_render",
 	title: "Render widget",
-	description: "Render a small self-contained UI widget the user can SEE, with the Plitzi SDK offline (no backend). Reach for it in two cases: (1) the user asks you to create/design/build/show a piece of UI (a card, hero, form, button, banner, pricing table…); (2) you are answering a content question and a visual layout communicates better than prose — render the ANSWER as a widget (a recipe as a card, a comparison as a table, steps as a checklist, a profile, a menu). Prefer showing it over a long text answer whenever the content is naturally visual. You author the widget as operations targeting the pre-seeded host page `pageRef: \"render\"` (same vocabulary as plitzi_apply: upsertElement, upsertDefinition, …). Returns a compact summary; the rendered widget is shown to the user. To edit an existing space page instead, use plitzi_preview.",
+	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n2. STYLE — declare reusable classes with upsertDefinition { ref, desktop:{ …CSS props in kebab-case… } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid.\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nReturns a compact summary (the widget is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,
+	ui: { resourceUri: RENDER_APP_URI },
 	run: (input) => toRenderResult(render(input))
 });
 //#endregion

package/dist/modules/mcp/tools/shared/tool.js

@@ -21,6 +21,7 @@ var defineTool = (spec) => ({
 	access: spec.access,
 	requires: spec.requires,
 	spaceless: spec.spaceless,
+	ui: spec.ui,
 	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
 });
 //#endregion

package/dist/modules/mcp/tools/shared/validator/index.js

@@ -1,3 +1,4 @@
+import { BUILTIN_COMPONENTS } from "../../../catalogs/builtinComponents.js";
 import { observedDataSources, observedInteractionActions } from "../../../catalogs/observed.js";
 import { buildTypeRegistry } from "../../../catalogs/registry.js";
 import { findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, getPageElements, pageFoldersOf, pageRefOf, resolveRef, routeParamNames } from "../../../helpers/space.js";
@@ -40,7 +41,7 @@ var buildValidationCtx = (space, ops) => {
 		errors: [],
 		warnings: [],
 		warned: /* @__PURE__ */ new Set(),
-		knownTypes: new Set(Object.keys(registry.types)),
+		knownTypes: /* @__PURE__ */ new Set([...Object.keys(registry.types), ...Object.keys(BUILTIN_COMPONENTS)]),
 		typeProps: new Map(Object.entries(registry.types).map(([type, info]) => [type, new Set(Object.keys(info.props))])),
 		typeMeta: buildTypeMeta(space.catalog),
 		elementType: (ref) => (findElementByRef(space.schema, ref) ?? findPageByRef(space.schema, ref))?.definition.type,

package/dist/src/modules/mcp/handler.d.ts

@@ -5,5 +5,8 @@ import { SSRAdapters, SSRRequest, McpLogger } from '@plitzi/sdk-shared';
 import { IncomingMessage, ServerResponse } from 'node:http';
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
 export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<void>;
-export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient, logger?: McpLogger) => Promise<void>;
+export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient, logger?: McpLogger, renderApp?: {
+    sdkBase: string;
+    devMode?: boolean;
+}) => Promise<void>;
 export { createMcpServer };

package/dist/src/modules/mcp/resources/renderApp.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+export declare const RENDER_APP_URI = "ui://plitzi/render.html";
+export declare const registerRenderApp: (server: McpServer, sdkBase: string, devMode: boolean) => void;

package/dist/src/modules/mcp/resources/renderGuide.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
+export declare const RENDER_TYPES_URI = "plitzi://render/types";
+export declare const registerRenderResources: (server: McpServer) => void;

package/dist/src/modules/mcp/server.d.ts

@@ -18,5 +18,13 @@ export interface McpServerContext {
     /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
     logger?: McpLogger;
+    /** MCP Apps: the interactive render view for plitzi_render. `sdkBase` is this server's absolute origin, which
+     *  serves the Plitzi SDK bundle under /sdk-assets; the iframe imports it and renders the widget client-side.
+     *  `devMode` picks the SDK vendor bundle name (dev vs prod split) to match the served bundle. Absent → the
+     *  ui:// view is not registered (the tool still returns its text summary + offlineData). */
+    renderApp?: {
+        sdkBase: string;
+        devMode?: boolean;
+    };
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => McpServer;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderApp }: McpServerContext) => McpServer;

package/dist/src/modules/mcp/tools/shared/tool.d.ts

@@ -34,6 +34,11 @@ export interface ToolSpec<Shape extends ZodRawShape> {
     /** The tool operates on no space (plitzi_render authors a throwaway one), so the host must NOT resolve a spaceId
      *  or load a space for it — that keeps it callable with no auth, on the public surface. */
     spaceless?: boolean;
+    /** MCP Apps: link this tool to an interactive UI resource (a `ui://` HTML page the host renders in a sandboxed
+     *  iframe, receiving the tool result). The `_meta.ui` the host reads is built from this. */
+    ui?: {
+        resourceUri: string;
+    };
     run: (input: z.infer<ZodObject<Shape>>, ctx: ToolContext) => unknown;
 }
 /** What the registry holds and the hosts register from: the same metadata plus a type-erased `execute` that
@@ -46,6 +51,9 @@ export interface ToolDef {
     access: 'read' | 'write';
     requires?: ToolRequires;
     spaceless?: boolean;
+    ui?: {
+        resourceUri: string;
+    };
     execute: (args: unknown, ctx: ToolContext) => unknown;
 }
 /** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.7",
+  "version": "0.32.9",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -23,9 +23,9 @@
   "sideEffects": false,
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@plitzi/plitzi-sdk": "0.32.7",
-    "@plitzi/sdk-schema": "0.32.7",
-    "@plitzi/sdk-shared": "0.32.7",
+    "@plitzi/plitzi-sdk": "0.32.9",
+    "@plitzi/sdk-schema": "0.32.9",
+    "@plitzi/sdk-shared": "0.32.9",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"