@plitzi/sdk-server 0.32.6 → 0.32.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @plitzi/sdk-server
 
+## 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
+
+- v0.32.7
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.7
+  - @plitzi/sdk-schema@0.32.7
+  - @plitzi/sdk-shared@0.32.7
+
 ## 0.32.6
 
 ### 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/ai/toolkit.js

@@ -48,6 +48,7 @@ var toolResponseFromResult = (result) => {
 	});
 	return {
 		content,
+		data: result.structuredContent,
 		isError: result.isError ? true : void 0
 	};
 };

package/dist/modules/mcp/handler.js

@@ -25,33 +25,52 @@ var serveMcp = async (raw, res, server) => {
 		res.end();
 		return;
 	}
+	if (raw.url?.startsWith("/.well-known/")) {
+		res.writeHead(404);
+		res.end();
+		return;
+	}
+	if (raw.method !== "POST") {
+		res.writeHead(405, {
+			"Content-Type": "application/json",
+			Allow: "POST, OPTIONS"
+		});
+		res.end(JSON.stringify({
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message: "Method not allowed; this MCP endpoint accepts JSON-RPC over POST only."
+			},
+			id: null
+		}));
+		return;
+	}
 	const transport = new StreamableHTTPServerTransport({
 		sessionIdGenerator: void 0,
 		enableJsonResponse: true
 	});
 	await server.connect(transport);
 	try {
-		if (raw.method === "POST") {
-			let body = raw.body;
-			if (body === void 0) try {
-				body = await readMcpBody(raw);
-			} catch {
-				res.writeHead(400, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: "Invalid JSON body" }));
-				return;
-			}
-			await transport.handleRequest(raw, res, body);
-		} else await transport.handleRequest(raw, res);
+		let body = raw.body;
+		if (body === void 0) try {
+			body = await readMcpBody(raw);
+		} catch {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "Invalid JSON body" }));
+			return;
+		}
+		await transport.handleRequest(raw, res, body);
 	} finally {
 		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/helpers/space.js

@@ -4,6 +4,32 @@ var cloneSpace = (space) => ({
 	style: structuredClone(space.style),
 	...space.catalog ? { catalog: space.catalog } : {}
 });
+var emptySpace = () => ({
+	schema: {
+		flat: {},
+		definition: {
+			name: "",
+			permanentUrl: ""
+		},
+		variables: [],
+		settings: { customCss: "" },
+		pages: [],
+		pageFolders: []
+	},
+	style: {
+		platform: {
+			desktop: {},
+			tablet: {},
+			mobile: {}
+		},
+		theme: {
+			default: "system",
+			schemes: ["light", "dark"]
+		},
+		variables: {},
+		cache: ""
+	}
+});
 var slugify = (value) => value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "";
 /** A value when it is a string, otherwise undefined — for the many attributes typed as `unknown` that are strings
 *  in practice (name, slug, subType, dom id…). */
@@ -259,4 +285,4 @@ var generateObjectId = () => {
 	return `${Math.floor(Date.now() / 1e3).toString(16).padStart(8, "0")}${Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("")}`;
 };
 //#endregion
-export { cloneSpace, descendantCount, descendantIds, elementById, elementRefOf, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, indexAddElement, indexAddPage, indexInvalidateDetails, indexReRefElement, indexReRefPage, indexRemoveElements, indexRemovePage, isPageElement, nameOf, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, spaceIndex, strOr, unauthorizedSpaceMessage };
+export { cloneSpace, descendantCount, descendantIds, elementById, elementRefOf, emptySpace, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, indexAddElement, indexAddPage, indexInvalidateDetails, indexReRefElement, indexReRefPage, indexRemoveElements, indexRemovePage, isPageElement, nameOf, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, spaceIndex, strOr, unauthorizedSpaceMessage };

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,174 @@
+//#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 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: { ui: { csp: RENDER_APP_CSP } }
+	}, () => ({ contents: [{
+		uri: RENDER_APP_URI,
+		mimeType: RENDER_APP_MIME,
+		text: html
+	}] }));
+};
+//#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

@@ -1,7 +1,8 @@
-import { emptySpaceMessage, unauthorizedSpaceMessage } from "./helpers/space.js";
+import { emptySpace, emptySpaceMessage, unauthorizedSpaceMessage } from "./helpers/space.js";
 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.6"
+		version: "0.32.8"
 	}, { 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,
@@ -52,16 +54,24 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 		preview,
 		screenshot
 	});
+	const spacelessContext = () => ({
+		space: emptySpace(),
+		env: MCP_ENV,
+		persisters,
+		preview,
+		screenshot
+	});
 	for (const tool of tools) {
 		if (tool.requires === "screenshot" && !screenshot) continue;
 		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 {
-				const result = await tool.execute(args, await toolContext());
+				const result = await tool.execute(args, tool.spaceless ? spacelessContext() : await toolContext());
 				log.toolCall(tool.name, args, performance.now() - start);
 				return isCallToolResult(result) ? result : asText(result);
 			} catch (error) {

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

@@ -4,6 +4,7 @@ import { validateOperations } from "./shared/validator/index.js";
 import { apply, applyShape, applyTool } from "./apply/index.js";
 import { previewTool } from "./preview.js";
 import { read, readShape, readTool } from "./read.js";
+import { renderTool } from "./render.js";
 import { screenshotTool } from "./screenshot.js";
 import { search, searchShape, searchTool } from "./search.js";
 import { validate, validateShape, validateTool } from "./validate.js";
@@ -15,6 +16,7 @@ var tools = [
 	validateTool,
 	searchTool,
 	readTool,
+	renderTool,
 	previewTool,
 	screenshotTool
 ];