@plitzi/sdk-server 0.32.19 → 0.32.20

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @plitzi/sdk-server
 
+## 0.32.20
+
+### Patch Changes
+
+- v0.32.20
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.20
+  - @plitzi/sdk-schema@0.32.20
+  - @plitzi/sdk-shared@0.32.20
+
 ## 0.32.19
 
 ### Patch Changes

package/dist/core/services/mcp.js

@@ -8,7 +8,8 @@ var serveMcp = async (ctx) => {
 	ctx.operation = await handleMcp(ctx.raw, ctx.rawRes, ctx.req, adapters, {
 		preview: previewClient ? createHttpPreviewClient(previewClient) : void 0,
 		screenshot: screenshot ? createHttpScreenshotClient(screenshot) : void 0,
-		logger
+		logger,
+		renderStreaming: ctx.config.mcpAi?.renderStreaming
 	});
 };
 var mcpStage = async (ctx) => {

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

@@ -1,12 +1,16 @@
 import { registerApp } from "./shared/registerApp.js";
+import { iconFontCss } from "./render/styles.js";
 import { RENDER_APP_URI, renderApp } from "./render/index.js";
 //#region src/modules/mcp/apps/index.ts
+/** What a view gets when the deployment says nothing: streaming on, because a host that streams no arguments
+*  paints exactly what it painted before. */
+var DEFAULT_VIEW_SETTINGS = { streaming: true };
 /** Every MCP App this server serves. A new one is a folder beside `render/` (its definition + its view) and one
 *  line here — the tool that opens it points at its `uri` through `ui: { resourceUri }`. Start from `example/`,
 *  which is that same shape stripped to the minimum. */
 var apps = [renderApp];
-var registerApps = (server) => {
-	for (const app of apps) registerApp(server, app);
+var registerApps = (server, settings = DEFAULT_VIEW_SETTINGS) => {
+	for (const app of apps) registerApp(server, app, settings);
 };
 //#endregion
-export { RENDER_APP_URI, apps, registerApps };
+export { DEFAULT_VIEW_SETTINGS, RENDER_APP_URI, apps, iconFontCss, registerApps };

package/dist/modules/mcp/apps/render/index.js

@@ -1,5 +1,5 @@
 import { VIEW_DIR } from "../shared/assets.js";
-import { require } from "../shared/resolve.js";
+import { iconFontCss, widgetCss } from "./styles.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/modules/mcp/apps/render/index.ts
@@ -11,7 +11,7 @@ var renderApp = {
 	title: "Plitzi widget",
 	description: "Interactive view that renders a plitzi_render widget with the Plitzi SDK.",
 	entry: path.join(HERE, VIEW_DIR, "index.tsx"),
-	styles: () => [path.join(path.dirname(require.resolve("@plitzi/plitzi-sdk")), "plitzi-sdk.css")]
+	styles: () => [widgetCss()]
 };
 //#endregion
-export { RENDER_APP_URI, renderApp };
+export { RENDER_APP_URI, iconFontCss, renderApp };

package/dist/modules/mcp/apps/render/styles.js

@@ -0,0 +1,54 @@
+import { require } from "../shared/resolve.js";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+//#region src/modules/mcp/apps/render/styles.ts
+/** The SDK stylesheet, split in two.
+*
+*  Everything the page shell inlines is paid for by EVERY widget: the host loads the ui:// page into a fresh
+*  sandboxed iframe and parses it whole before anything paints, which is the "Rendering…" the user waits through.
+*  Three of those @font-face blocks are Font Awesome shipped as base64 woff2 — ~330 KB, close to a fifth of the
+*  page — and only a widget that authored a `fontAwesome` element has any use for them.
+*
+*  So the shell takes the base, and the fonts travel in the tool result of the renders that actually draw an icon
+*  (see tools/render.ts). A widget without icons never downloads a glyph; one with icons looks exactly the same as
+*  before. */
+/** Where the closing brace of the block opened at `open` is, so a nested one cannot end it early. Returns the
+*  string's length when the CSS is truncated mid-block, which drops that tail rather than mixing it into the base. */
+var blockEnd = (css, open) => {
+	let depth = 0;
+	for (let at = open; at < css.length; at++) if (css[at] === "{") depth++;
+	else if (css[at] === "}") {
+		depth--;
+		if (depth === 0) return at + 1;
+	}
+	return css.length;
+};
+/** Lifts every @font-face block out of a stylesheet. Brace counting rather than a CSS parser: a @font-face body is
+*  plain declarations, and base64 payloads and url() values carry no braces of their own. */
+var splitFontFaces = (css) => {
+	const base = [];
+	const fonts = [];
+	let cursor = 0;
+	for (let at = css.indexOf("@font-face", cursor); at !== -1; at = css.indexOf("@font-face", cursor)) {
+		const open = css.indexOf("{", at);
+		if (open === -1) break;
+		const end = blockEnd(css, open);
+		base.push(css.slice(cursor, at));
+		fonts.push(css.slice(at, end));
+		cursor = end;
+	}
+	base.push(css.slice(cursor));
+	return {
+		base: base.join(""),
+		fonts: fonts.join("")
+	};
+};
+var stylesheet = () => readFileSync(path.join(path.dirname(require.resolve("@plitzi/plitzi-sdk")), "plitzi-sdk.css"), "utf-8");
+var split;
+var sdkStyles = () => split ??= splitFontFaces(stylesheet());
+/** What the page shell inlines: the SDK stylesheet without the icon fonts. */
+var widgetCss = () => sdkStyles().base;
+/** The icon fonts, for the renders that draw one. */
+var iconFontCss = () => sdkStyles().fonts;
+//#endregion
+export { iconFontCss, splitFontFaces, widgetCss };

package/dist/modules/mcp/apps/render/view/index.tsx

@@ -5,7 +5,9 @@ import { Component, useEffect, useRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 
 import { readHeldBatch, writeHeldBatch } from './heldBatch';
+import { mergeProgress, streamProgress } from './streamProgress';
 
+import type { StreamProgress } from './streamProgress';
 import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { OfflineDataRaw } from '@plitzi/sdk-shared';
@@ -25,6 +27,62 @@ const ErrorPanel = ({ title, details }: { title: string; details: string }) => (
   </div>
 );
 
+/** The wait a user reads as "this is slow" is the model TYPING the batch: the tool only runs once the last brace
+ *  is written, and until then the page shows its static "Rendering…". The host streams the arguments as they
+ *  arrive, so this stands in for the widget meanwhile — bars that grow with the elements already authored, and the
+ *  widget's own title as soon as the batch names it. It never shows a half-built widget: the real one replaces it
+ *  wholesale when the result lands. A host that streams nothing paints none of this and keeps the static text. */
+const SKELETON_BAR_WIDTHS = ['92%', '78%', '85%', '64%', '88%', '72%'];
+
+// The deployment's own switch (mcpAi.renderStreaming), handed over by the page. Absent means on: a page built
+// before the setting existed carries none, and a host that streams no arguments paints the same either way.
+const streamingEnabled =
+  (globalThis as { __PLITZI_VIEW__?: { streaming?: boolean } }).__PLITZI_VIEW__?.streaming !== false;
+
+const skeletonBarStyle = {
+  height: 10,
+  borderRadius: 5,
+  backgroundColor: 'var(--color-background-tertiary, light-dark(#e2e8f0, #333a48))',
+  animation: 'plitzi-skeleton-pulse 1.4s ease-in-out infinite'
+} as const;
+
+// One bar per few elements, so the block visibly grows while the model writes, and a ceiling so a 200-element
+// widget does not fill the panel with grey. Total by construction: this paints a wait, and a placeholder that
+// renders nothing at all (an empty slice off a NaN) would read as the view having died.
+const barCount = (elements: number): number => {
+  const bars = Math.ceil(elements / 3);
+
+  return Number.isFinite(bars) ? Math.min(Math.max(bars, 2), 6) : 2;
+};
+
+const StreamSkeleton = ({ progress }: { progress: StreamProgress }) => {
+  const caption = progress.patch ? 'Updating the widget…' : 'Building the widget…';
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 10,
+        padding: 16,
+        font: '13px/1.5 var(--font-sans, system-ui, sans-serif)'
+      }}
+    >
+      <style>{'@keyframes plitzi-skeleton-pulse { 0%, 100% { opacity: 0.5 } 50% { opacity: 1 } }'}</style>
+      {progress.title && <strong style={{ fontSize: 15 }}>{progress.title}</strong>}
+      {SKELETON_BAR_WIDTHS.slice(0, barCount(progress.elements)).map(width => (
+        <div key={width} style={{ ...skeletonBarStyle, width }} />
+      ))}
+      <span style={{ color: 'var(--color-text-tertiary, light-dark(#64748b, #9aa4b2))' }}>
+        {caption}
+        {progress.elements > 0 && ` ${progress.elements} elements so far`}
+      </span>
+    </div>
+  );
+};
+
 class RenderBoundary extends Component<{ children: ReactNode }, { error?: Error }> {
   state: { error?: Error } = {};
 
@@ -56,10 +114,36 @@ const summarise = (result: CallToolResult): string => {
 
 const RenderApp = () => {
   const [result, setResult] = useState<CallToolResult | null>(null);
+  const [progress, setProgress] = useState<StreamProgress | undefined>(undefined);
   const [cancelled, setCancelled] = useState<string | undefined>(undefined);
   const [context, setContext] = useState<McpUiHostContext | undefined>(undefined);
   const held = useRef<Held>({ operations: [] });
   const appRef = useRef<App | null>(null);
+  // The handlers are registered once, so they close over the FIRST render's state: a ref is the only way they can
+  // tell whether a widget is already on screen.
+  const painted = useRef(false);
+
+  const showWidget = (toolResult: CallToolResult): void => {
+    painted.current = true;
+    setResult(toolResult);
+  };
+
+  /** Streamed arguments are the one input here nobody validated: healed JSON, from a host, about a call that does
+   *  not exist yet. So it is fenced off — it feeds the placeholder and NOTHING else (never the held batch, never
+   *  storage, never the server), it cannot run once a widget is up, and it cannot throw: a notification handler
+   *  that raises would break the App's dispatch, and this one exists only to decorate a wait. */
+  const trackInput = (args: unknown): void => {
+    if (painted.current) {
+      return;
+    }
+
+    try {
+      const next = streamProgress(args);
+      setProgress(previous => mergeProgress(previous, next));
+    } catch {
+      // A placeholder that stops growing is a non-event; the widget is still on its way.
+    }
+  };
 
   // A patch carries only what changed. Merging it onto the held batch and re-calling the tool is what keeps the
   // server stateless: it re-renders the WHOLE widget (so refs, integrity and the audit are all checked as usual)
@@ -98,7 +182,7 @@ const RenderApp = () => {
         const applied = (rendered.structuredContent?.operations as unknown[] | undefined) ?? merged;
         held.current = { renderId, operations: applied };
         writeHeldBatch(renderId, applied);
-        setResult(rendered);
+        showWidget(rendered);
       }
 
       await app.updateModelContext({
@@ -131,6 +215,15 @@ const RenderApp = () => {
     capabilities: {},
     onAppCreated: instance => {
       appRef.current = instance;
+      // Streaming arguments (sent zero or more times while the model writes) and then the complete ones, which the
+      // host MUST send before the result: the last frame the placeholder gets covers the server render itself.
+      // The `on*` setters are the deprecated half of the API, kept because every other handler here uses them —
+      // mixing addEventListener for one of them would hide the lifecycle this component is built around.
+      if (streamingEnabled) {
+        instance.ontoolinputpartial = params => trackInput(params.arguments);
+        instance.ontoolinput = params => trackInput(params.arguments);
+      }
+
       instance.ontoolresult = toolResult => {
         const renderId = toolResult.structuredContent?.renderId as string | undefined;
         if (toolResult.structuredContent?.patch === true && renderId) {
@@ -152,7 +245,7 @@ const RenderApp = () => {
           writeHeldBatch(renderId, operations);
         }
 
-        setResult(toolResult);
+        showWidget(toolResult);
       };
       instance.ontoolcancelled = params => setCancelled(params.reason ?? 'The host cancelled the render.');
       instance.onhostcontextchanged = params => setContext(previous => ({ ...previous, ...params }));
@@ -174,8 +267,13 @@ const RenderApp = () => {
     return <ErrorPanel title="Could not render the widget" details={failure} />;
   }
 
-  // Still connecting, or connected and waiting for the result: the page's CSS placeholder covers both.
+  // Waiting for the result. Once the host has streamed any of the arguments the skeleton stands in for the widget
+  // being written; before that (and on a host that streams nothing) the page's own CSS placeholder covers it.
   if (!result) {
+    if (progress) {
+      return <StreamSkeleton progress={progress} />;
+    }
+
     return null;
   }
 
@@ -190,6 +288,9 @@ const RenderApp = () => {
   }
 
   const insets = context?.safeAreaInsets;
+  // The icon fonts, ~330 KB of base64 woff2, are not in the page: they arrive with the widgets that draw an icon,
+  // so every other widget's iframe has that much less to load before it paints (see ../styles.ts).
+  const iconCss = result.structuredContent?.iconCss as string | undefined;
 
   return (
     <div
@@ -197,8 +298,9 @@ const RenderApp = () => {
         padding: `${insets?.top ?? 0}px ${insets?.right ?? 0}px ${insets?.bottom ?? 0}px ${insets?.left ?? 0}px`
       }}
     >
+      {iconCss && <style>{iconCss}</style>}
       <RenderBoundary>
-        <PlitziSdk offlineData={offlineData} offlineMode environment="main" renderMode="raw" />
+        <PlitziSdk offlineData={offlineData} offlineMode environment="main" renderMode="raw" branding={false} />
       </RenderBoundary>
     </div>
   );

package/dist/modules/mcp/apps/render/view/streamProgress.ts

@@ -0,0 +1,137 @@
+/** What the host has streamed of the tool call so far, reduced to the little a placeholder can honestly show.
+ *
+ *  The wait a user sees is almost entirely the model TYPING this batch — the server render takes milliseconds —
+ *  so the only way to look alive is to read the arguments while they are still arriving. The host sends them as
+ *  "healed" JSON (it closes the braces the model has not written yet), which means every field may be missing and
+ *  the last operation is usually half-written: nothing here may assume a shape, and a fragment it cannot read
+ *  simply contributes nothing.
+ *
+ *  Two properties this module owes the view, because a placeholder that misbehaves is worse than none:
+ *  - it is TOTAL — no input throws, and every number it returns is a finite count;
+ *  - it only ever moves FORWARD (see mergeProgress) — healing is best-effort and the spec warns that fields may
+ *    change between notifications, so a frame that recovers less than the one before it must not shrink the
+ *    placeholder, which the eye reads as flicker. */
+export type StreamProgress = { elements: number; title?: string; patch: boolean };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const asArray = (value: unknown): unknown[] => (Array.isArray(value) ? value : []);
+
+// The walk is over a structure this code did not build, so it is bounded rather than trusted: a pathological
+// nesting would otherwise turn a placeholder into a stack overflow, which kills the view for good — including
+// the widget that was on its way. Far beyond anything a real widget nests.
+const MAX_DEPTH = 64;
+
+// A title is a label in a small panel: whitespace collapsed so a multi-line heading cannot push the bars off
+// screen, and cut where it stops being a label.
+const MAX_TITLE = 80;
+
+// A repeat renders its template once per row, so the rows are what the user will actually count on screen. An
+// items list that has not started streaming yet still stands for at least the one template being written.
+const rowsOf = (items: unknown): number => Math.max(asArray(items).length, 1);
+
+const countElements = (node: unknown, depth = 0): number => {
+  if (!isRecord(node) || depth > MAX_DEPTH) {
+    return 0;
+  }
+
+  const repeat = isRecord(node.repeat) ? node.repeat : undefined;
+  const nested = repeat ? countElements(repeat.template, depth + 1) * rowsOf(repeat.items) : 0;
+
+  return asArray(node.children).reduce<number>((total, child) => total + countElements(child, depth + 1), 1 + nested);
+};
+
+// A heading's content arrives one fragment at a time, so this runs against half-written text: `{{` rules out a
+// repeat template's placeholder (a literal "{{item.name}}" on screen reads as a bug, not as progress), and an
+// empty string is what a heading looks like before its content exists at all.
+const titleOf = (content: unknown): string | undefined => {
+  if (typeof content !== 'string' || content.includes('{{')) {
+    return undefined;
+  }
+
+  const text = content.replace(/\s+/gu, ' ').trim();
+  if (text === '') {
+    return undefined;
+  }
+
+  return text.length > MAX_TITLE ? `${text.slice(0, MAX_TITLE)}…` : text;
+};
+
+// The first heading the batch declares is the widget's own title far more often than not, so showing it turns the
+// placeholder from "something is happening" into "your pricing table is coming".
+const findTitle = (node: unknown, depth = 0): string | undefined => {
+  if (!isRecord(node) || depth > MAX_DEPTH) {
+    return undefined;
+  }
+
+  const props = isRecord(node.props) ? node.props : undefined;
+  if (node.type === 'heading') {
+    const title = titleOf(props?.content);
+    if (title !== undefined) {
+      return title;
+    }
+  }
+
+  for (const child of asArray(node.children)) {
+    const found = findTitle(child, depth + 1);
+    if (found !== undefined) {
+      return found;
+    }
+  }
+
+  return undefined;
+};
+
+// An op either builds a tree (upsertElement) or repeats one (repeatElement); anything else — a definition, a
+// binding, the truncated tail — adds no elements to count.
+const treeOf = (op: Record<string, unknown>): unknown => {
+  if (isRecord(op.element)) {
+    return op.element;
+  }
+
+  return isRecord(op.template) ? op.template : undefined;
+};
+
+export const streamProgress = (args: unknown): StreamProgress => {
+  const record = isRecord(args) ? args : {};
+  let elements = 0;
+  let title: string | undefined;
+
+  for (const op of asArray(record.operations)) {
+    if (!isRecord(op)) {
+      continue;
+    }
+
+    const tree = treeOf(op);
+    if (tree === undefined) {
+      continue;
+    }
+
+    elements += countElements(tree) * (isRecord(op.template) ? rowsOf(op.items) : 1);
+    title ??= findTitle(tree);
+  }
+
+  return { elements: Number.isFinite(elements) ? elements : 0, title, patch: record.patch === true };
+};
+
+/** Fold a freshly read frame into what the placeholder already shows. Monotonic on purpose — the count never goes
+ *  down and a title, once read, is never taken away — because the healed JSON of frame N+1 can legitimately
+ *  recover LESS than frame N, and a placeholder that shrinks and grows is the flicker this whole thing exists to
+ *  avoid. Returns the previous object unchanged when nothing moved, so an unchanged frame costs no re-render. */
+export const mergeProgress = (previous: StreamProgress | undefined, next: StreamProgress): StreamProgress => {
+  if (!previous) {
+    return next;
+  }
+
+  const merged: StreamProgress = {
+    elements: Math.max(previous.elements, next.elements),
+    title: next.title ?? previous.title,
+    patch: previous.patch || next.patch
+  };
+  if (merged.elements === previous.elements && merged.title === previous.title && merged.patch === previous.patch) {
+    return previous;
+  }
+
+  return merged;
+};

package/dist/modules/mcp/apps/shared/page.js

@@ -6,16 +6,27 @@ import ejs from "ejs";
 //#region src/modules/mcp/apps/shared/page.ts
 var SHELL = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "shell.ejs");
 var template = () => ejs.compile(readFileSync(SHELL, "utf-8"), { filename: SHELL });
+var scripts = /* @__PURE__ */ new Map();
 var pages = /* @__PURE__ */ new Map();
-var page = (app) => {
-	let html = pages.get(app.uri);
+var script = (entry) => {
+	let built = scripts.get(entry);
+	if (!built) {
+		built = bundle(entry);
+		scripts.set(entry, built);
+	}
+	return built;
+};
+var page = (app, settings) => {
+	const key = `${app.uri}|${JSON.stringify(settings)}`;
+	let html = pages.get(key);
 	if (!html) {
-		html = bundle(app.entry).then((script) => template()({
+		html = script(app.entry).then((code) => template()({
 			title: app.title,
-			app: script,
-			css: (app.styles?.() ?? []).map((file) => readFileSync(file, "utf-8")).join("\n")
+			app: code,
+			css: (app.styles?.() ?? []).join("\n"),
+			settings: JSON.stringify(settings)
 		}));
-		pages.set(app.uri, html);
+		pages.set(key, html);
 	}
 	return html;
 };

package/dist/modules/mcp/apps/shared/registerApp.js

@@ -11,7 +11,7 @@ var DEFAULT_CSP = {
 };
 /** Serves the app as a self-contained page: no import map, no asset mounts, no cross-origin fetches, so the
 *  strictest host sandbox runs it and no deployment has to serve anything extra. */
-var registerApp = (server, app) => {
+var registerApp = (server, app, settings) => {
 	const meta = { ui: { csp: app.csp ?? DEFAULT_CSP } };
 	registerAppResource(server, app.name, app.uri, {
 		description: app.description,
@@ -19,7 +19,7 @@ var registerApp = (server, app) => {
 	}, async () => ({ contents: [{
 		uri: app.uri,
 		mimeType: RESOURCE_MIME_TYPE,
-		text: await page(app),
+		text: await page(app, settings),
 		_meta: meta
 	}] }));
 };

package/dist/modules/mcp/apps/shared/shell.ejs

@@ -47,6 +47,11 @@
   <body>
     <div id="app"></div>
 
+    <%# Deployment switches, before the app so the view reads them as it mounts. They ride in the page, not the
+        bundle, so a server serving both settings still builds the browser bundle once. -%>
+    <script id="plitzi-view-settings">
+      window.__PLITZI_VIEW__ = <%- settings %>;
+    </script>
     <script>
 <%- app %>
     </script>

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

@@ -10,6 +10,8 @@ var RENDER_TYPE_CATEGORIES = /* @__PURE__ */ new Set([
 	"form",
 	"provider"
 ]);
+var RENDER_RAW_HTML_TYPE = "blockHtml";
+var rawHtmlDescription = "Renders a raw HTML string (props.content) — in a widget, the way to draw an inline <svg>: a logo, an icon, a sparkline, a decorative shape. Use fill/stroke \"currentColor\" so it takes the host theme. Markup only: <script>, javascript: URLs and inline on* handlers are rejected.";
 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 = {};
@@ -18,6 +20,12 @@ var renderTypes = () => {
 		category: info.category,
 		description: info.description
 	};
+	const rawHtml = BUILTIN_COMPONENTS[RENDER_RAW_HTML_TYPE];
+	if (rawHtml) types[RENDER_RAW_HTML_TYPE] = {
+		label: rawHtml.label,
+		category: rawHtml.category,
+		description: rawHtmlDescription
+	};
 	return {
 		note: renderTypesNote,
 		types
@@ -256,24 +264,61 @@ The host publishes its palette as CSS variables on the page, so use them for eve
 | \`video\` | embedded video | \`props.src\` |
 | \`list\` / \`listItem\` | \`<ul>\` / \`<li>\` | nesting only |
 | \`markdown\` | rendered markdown | \`props.content\` |
+| \`blockHtml\` | a raw HTML string, as written | \`props.content\` — how you draw an inline \`<svg>\`, see below |
 
 \`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.
+\`image\`/\`video\` \`src\` accepts any \`https\` URL, or a \`data:\`/\`blob:\` URI for a fully self-contained graphic (a
+base64 raster) — both render with no extra setup. For a **vector** graphic do not encode a \`data:\` URI: draw it
+inline, as below.
+
+## Draw with inline SVG
+
+A widget can draw its own graphics, and it is often the difference between a plain block of text and something
+worth showing: a brand mark, a sparkline or donut, a badge, an empty-state glyph, a wave or blob behind a header,
+an arrow between two steps. Put the SVG **inline** in a \`blockHtml\` element — its \`props.content\` is rendered as
+written, so the markup needs no escaping, and the element is styled and laid out like any other box.
+
+\`\`\`json
+{
+  "operations": [
+    { "type": "upsertDefinitions", "definitions": {
+        "mark": { "desktop": { "display": "flex", "width": "32px", "height": "32px", "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))" } }
+    } },
+    { "type": "upsertElement", "pageRef": "render", "element": {
+        "ref": "trend", "type": "blockHtml", "style": { "base": ["mark"] },
+        "props": { "content": "<svg viewBox='0 0 24 24' width='100%' height='100%' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round'><path d='M3 17l6-6 4 4 8-8'/><path d='M21 7v6h-6'/></svg>" }
+    } }
+  ]
+}
+\`\`\`
+- **Size from the class, not the drawing**: keep a \`viewBox\` and set \`width\`/\`height\` to \`100%\`, then the
+  \`blockHtml\`'s own \`width\`/\`height\` decide how big it renders — one drawing, any size.
+- **Colour with \`currentColor\`** (\`fill\` and/or \`stroke\`) and set \`color\` on the class from a host variable. A hex
+  buried inside the path is the same mistake as a hardcoded light palette: it cannot follow the theme.
+- **Single quotes inside the markup** keep the JSON free of \`\\"\` escapes, as above.
+- **Markup only.** \`<script>\`, \`javascript:\` URLs and inline \`on*\` handlers are rejected with an error — a widget
+  runs inside the host's UI. Animate with CSS (a \`states\` block, a \`transition\`) and wire behaviour with
+  interaction flows.
+
+**The budget.** Every path is text you write, so an SVG earns its place only while it stays small: a handful of
+paths, a few hundred characters, drawn ONCE and reused (same class, same content, or a \`repeatElement\` row) rather
+than redrawn per card. Skip it entirely when something cheaper does the job — a \`fontAwesome\` icon, an emoji in a
+\`text\`, an \`https\` image the user gave you, a CSS gradient or a \`border-radius\` shape. And a full illustration or
+a photo-real scene (a castle, a skyline, a detailed mascot) is still the wrong trade: it costs more than the entire
+rest of the widget and renders worse than the image it is imitating.
 
 ## Keep the call small
 
 Everything in \`operations\` is text you write, and a widget that takes two calls because the first ran long is a
 widget the user waits twice for. Two habits pay for themselves:
 
-- **Do not draw pictures in \`data:\` URIs.** A hand-written SVG scene (a castle, a skyline, a logo) costs more than
-  the entire rest of the widget and renders worse than nothing at all. Use an \`https\` image the user gave you, a
-  flat colour or a two-stop \`linear-gradient\` as a banner, an emoji or an \`fontAwesome\` icon for a glyph — or drop
-  the decoration. A small self-contained \`data:\` SVG is fine for a **simple** shape (a check, an arrow, a dot).
+- **Keep a drawing to a drawing.** Inline SVG is allowed and often worth it (see above), but a graphic that runs
+  longer than the widget around it has stopped paying for itself: a handful of paths, drawn once and reused rather
+  than redrawn per card, and an \`https\` image, a flat colour or a two-stop \`linear-gradient\` for anything bigger.
 - **One class per look, not per property.** Classes like \`tone-blue\` + \`tone-blue-text\` + \`tone-blue-bg\` for the
   same card triple the declarations and the attachments. Put everything the look needs in one class, add a second
   only for the part that genuinely varies between siblings (a colour), and reuse it — the whole point of a class.

package/dist/modules/mcp/server.js

@@ -13,7 +13,7 @@ var asText = (data) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(data)
 }] });
-var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger }) => {
+var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming = true }) => {
 	const log = createMcpLog(logger);
 	const spaceId = await getSpaceId().catch(() => void 0);
 	const hasSpace = spaceId !== void 0;
@@ -44,10 +44,10 @@ var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.19"
+		version: "0.32.20"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace);
-	registerApps(server);
+	registerApps(server, { streaming: renderStreaming });
 	const toolContext = async () => ({
 		space: await getSpace(),
 		env: MCP_ENV,

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

@@ -1,3 +1,4 @@
+import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
 import { emptySpace } from "../helpers/space.js";
 import { operations } from "./operations/index.js";
@@ -48,7 +49,7 @@ var render = (input) => {
 		errors: expansion.errors
 	};
 	const ops = expansion.operations;
-	const validation = validateOperations(space, ops);
+	const validation = validateOperations(space, ops, "widget");
 	if (!validation.valid) return {
 		rendered: false,
 		errors: validation.errors,
@@ -136,6 +137,8 @@ var toPatchResult = (ops, renderId) => {
 	};
 };
 var newRenderId = () => `r${randomUUID().slice(0, 8)}`;
+var ICON_TYPE = "fontAwesome";
+var drawsIcons = (offlineData) => Object.values(offlineData.schema.flat).some((element) => element.definition.type === ICON_TYPE);
 var toRenderResult = (res, renderId) => {
 	if (!res.rendered) return { content: [{
 		type: "text",
@@ -160,14 +163,15 @@ var toRenderResult = (res, renderId) => {
 		structuredContent: {
 			...summary,
 			offlineData: res.offlineData,
-			operations: res.operations
+			operations: res.operations,
+			...drawsIcons(res.offlineData) ? { iconCss: iconFontCss() } : {}
 		}
 	};
 };
 var renderTool = defineTool({
 	name: "plitzi_render",
 	title: "Render widget",
-	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.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look (not per property), and never hand-draw a scene in a data: URI — it costs more than the whole widget; use an https image, a flat colour or a gradient.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\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.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
+	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.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look, not per property.\n2a. GRAPHICS — a logo, a sparkline, a badge, a decorative shape: draw it as an INLINE <svg> in a blockHtml element (props.content), keeping a viewBox with width/height \"100%\" so its class sizes it, and fill/stroke \"currentColor\" so it follows the host theme. Budget it: a handful of paths, drawn once and reused, never a data: URI and never a full illustration — a photo-real scene costs more than the whole widget, so use an https image, a flat colour or a gradient for that. Markup only: scripts and on* handlers are rejected.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\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.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,

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

@@ -32,7 +32,17 @@ var checkVariantApplication = (initialState, path, ctx) => {
 		}
 	}
 };
+var EXECUTABLE_MARKUP = /<script\b|\son[a-z]+\s*=|javascript:/i;
+var checkRawMarkup = (type, props, path, ctx) => {
+	if (ctx.mode !== "widget" || !props || !RAW_CODE_TYPES.has(type)) return;
+	for (const [key, value] of Object.entries(props)) if (typeof value === "string" && EXECUTABLE_MARKUP.test(value)) ctx.errors.push({
+		path: `${path}.props.${key}`,
+		message: `Executable markup in a "${type}" prop is not allowed in a widget`,
+		hint: "A widget renders inside the host UI, so <script>, javascript: URLs and inline on* handlers are rejected. Keep the markup inert (an inline <svg> is what this type is for) and wire behaviour with upsertInteractionFlow."
+	});
+};
 var checkElementProps = (element, path, ctx) => {
+	checkRawMarkup(element.type, element.props, path, ctx);
 	if (!element.props || RAW_CODE_TYPES.has(element.type)) return;
 	for (const [key, value] of Object.entries(element.props)) if (typeof value === "string") checkVarRefs(value, `${path}.props.${key}`, ctx);
 	checkTypeProps(element.type, element.props, path, ctx);
@@ -55,4 +65,4 @@ var checkElementInput = (element, path, ctx, seen) => {
 	element.children?.forEach((child, i) => checkElementInput(child, `${path}.children[${i}]`, ctx, seen));
 };
 //#endregion
-export { checkElementInput, checkTypeProps, checkVariantApplication };
+export { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication };

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

@@ -8,7 +8,7 @@ import { checkObservedName, checkVarRefs, warnOnce } from "./context.js";
 import { checkBindingSourceScope, checkBindingTarget, checkBindingTransformers } from "./bindings.js";
 import { checkSlotCss } from "./css.js";
 import { checkRef } from "./refs.js";
-import { checkElementInput, checkTypeProps, checkVariantApplication } from "./elements.js";
+import { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication } from "./elements.js";
 import { checkInteractionNode } from "./interactions.js";
 //#region src/modules/mcp/tools/shared/validator/index.ts
 var STYLE_CATEGORIES = [
@@ -35,9 +35,10 @@ var buildTypeMeta = (catalog) => {
 };
 /** The shared validation context, derived from a space (+ the batch's ops, for batch-declared names). Extracted so
 *  the post-apply resource audit (auditResources) can run the same checks against the resulting draft. */
-var buildValidationCtx = (space, ops) => {
+var buildValidationCtx = (space, ops, mode = "space") => {
 	const registry = buildTypeRegistry(space.schema, space.catalog);
 	return {
+		mode,
 		errors: [],
 		warnings: [],
 		warned: /* @__PURE__ */ new Set(),
@@ -57,11 +58,11 @@ var buildValidationCtx = (space, ops) => {
 		observedSources: observedDataSources(space.schema)
 	};
 };
-var validateOperations = (space, ops) => {
+var validateOperations = (space, ops, mode = "space") => {
 	const batchPages = batchDeclaredPages(ops);
 	const batchFolders = batchDeclaredFolders(ops);
 	const folderRefs = () => pageFoldersOf(space.schema).map((f) => f.id);
-	const ctx = buildValidationCtx(space, ops);
+	const ctx = buildValidationCtx(space, ops, mode);
 	if (ops.length > 1e3) ctx.errors.push({
 		path: "operations",
 		message: `Batch has ${ops.length} operations (max ${MAX_OPS})`,
@@ -91,7 +92,10 @@ var validateOperations = (space, ops) => {
 				const target = page ? resolveRef(space.schema, page, op.ref) : void 0;
 				if (op.props) {
 					for (const [key, value] of Object.entries(op.props)) if (typeof value === "string") checkVarRefs(value, `${base}.props.${key}`, ctx);
-					if (target && target.id !== page?.id) checkTypeProps(target.definition.type, op.props, base, ctx);
+					if (target && target.id !== page?.id) {
+						checkRawMarkup(target.definition.type, op.props, base, ctx);
+						checkTypeProps(target.definition.type, op.props, base, ctx);
+					}
 				}
 				checkVariantApplication(op.initialState, `${base}.initialState`, ctx);
 				break;

package/dist/src/modules/mcp/apps/index.d.ts

@@ -1,8 +1,11 @@
-import { McpApp } from '../types';
+import { McpApp, McpViewSettings } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** What a view gets when the deployment says nothing: streaming on, because a host that streams no arguments
+ *  paints exactly what it painted before. */
+export declare const DEFAULT_VIEW_SETTINGS: McpViewSettings;
 /** Every MCP App this server serves. A new one is a folder beside `render/` (its definition + its view) and one
  *  line here — the tool that opens it points at its `uri` through `ui: { resourceUri }`. Start from `example/`,
  *  which is that same shape stripped to the minimum. */
 export declare const apps: McpApp[];
-export declare const registerApps: (server: McpServer) => void;
-export { RENDER_APP_URI } from './render';
+export declare const registerApps: (server: McpServer, settings?: McpViewSettings) => void;
+export { iconFontCss, RENDER_APP_URI } from './render';

package/dist/src/modules/mcp/apps/render/index.d.ts

@@ -1,3 +1,4 @@
 import { McpApp } from '../../types';
 export declare const RENDER_APP_URI = "ui://plitzi/render.html";
 export declare const renderApp: McpApp;
+export { iconFontCss } from './styles';

package/dist/src/modules/mcp/apps/render/styles.d.ts

@@ -0,0 +1,10 @@
+/** Lifts every @font-face block out of a stylesheet. Brace counting rather than a CSS parser: a @font-face body is
+ *  plain declarations, and base64 payloads and url() values carry no braces of their own. */
+export declare const splitFontFaces: (css: string) => {
+    base: string;
+    fonts: string;
+};
+/** What the page shell inlines: the SDK stylesheet without the icon fonts. */
+export declare const widgetCss: () => string;
+/** The icon fonts, for the renders that draw one. */
+export declare const iconFontCss: () => string;

package/dist/src/modules/mcp/apps/render/styles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/apps/shared/page.d.ts

@@ -1,2 +1,2 @@
-import { McpApp } from '../../types';
-export declare const page: (app: McpApp) => Promise<string>;
+import { McpApp, McpViewSettings } from '../../types';
+export declare const page: (app: McpApp, settings: McpViewSettings) => Promise<string>;

package/dist/src/modules/mcp/apps/shared/registerApp.d.ts

@@ -1,5 +1,5 @@
-import { McpApp } from '../../types';
+import { McpApp, McpViewSettings } from '../../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /** Serves the app as a self-contained page: no import map, no asset mounts, no cross-origin fetches, so the
  *  strictest host sandbox runs it and no deployment has to serve anything extra. */
-export declare const registerApp: (server: McpServer, app: McpApp) => void;
+export declare const registerApp: (server: McpServer, app: McpApp, settings: McpViewSettings) => void;

package/dist/src/modules/mcp/e2e/mcpEndpoint.d.ts

@@ -18,8 +18,10 @@ export interface McpEndpointOptions {
     /** Attach a space to the connection, the way an authorized connector's token does — the server then offers its
      *  editing surface. Omitted, the endpoint is the guest one: no space, so only what works without one. */
     spaceId?: number;
+    /** The deployment switch a consumer sets as `mcpAi.renderStreaming`. Omitted, the server's own default stands. */
+    renderStreaming?: boolean;
 }
 /** Start the endpoint and connect a real MCP client to it, as a remote connector does. */
-export declare const startMcpEndpoint: ({ spaceId }?: McpEndpointOptions) => Promise<McpEndpoint>;
+export declare const startMcpEndpoint: ({ spaceId, renderStreaming }?: McpEndpointOptions) => Promise<McpEndpoint>;
 /** Read a ui:// resource. A page that came back as a blob is a bug a host would meet as a blank frame. */
 export declare const readAppPage: (endpoint: McpEndpoint, uri: string) => Promise<AppPage>;

package/dist/src/modules/mcp/e2e/renderingHost.d.ts

@@ -13,6 +13,11 @@ export interface RenderingHostOptions {
 export interface RenderingHost {
     bridge: AppBridge;
     window: JSDOM['window'];
+    /** Push arguments the way a host does while the model is still writing the call: healed JSON, sent zero or more
+     *  times, any field possibly missing. */
+    streamInput: (args: Record<string, unknown>) => Promise<void>;
+    /** The complete arguments, which the spec makes the host send once before any result. */
+    completeInput: (args: Record<string, unknown>) => Promise<void>;
     /** Deliver a tool result and let the App paint before assertions run. */
     showResult: (result: McpUiToolResultNotification['params']) => Promise<void>;
     /** What the App reported back to the model with ui/update-model-context, in order. */

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

@@ -9,6 +9,8 @@ export type McpRequestOptions = {
     preview?: PreviewClient;
     screenshot?: ScreenshotClient;
     logger?: ServerLogger;
+    /** Deployment switch for the plitzi_render view (see `mcpAi.renderStreaming`). Defaults to true. */
+    renderStreaming?: boolean;
 };
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
 export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<string | undefined>;

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

@@ -19,5 +19,8 @@ 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?: ServerLogger;
+    /** May the plitzi_render view paint from tool arguments the host is still streaming (see `mcpAi.renderStreaming`)?
+     *  Defaults to true. */
+    renderStreaming?: boolean;
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => Promise<McpServer>;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming }: McpServerContext) => Promise<McpServer>;

package/dist/src/modules/mcp/tools/shared/validator/context.d.ts

@@ -1,6 +1,9 @@
 import { ValidationError } from '../../../types';
 import { Style } from '@plitzi/sdk-shared';
 export declare const RAW_CODE_TYPES: Set<string>;
+/** What the batch is authoring. A `widget` (plitzi_render) is embedded in a host's chat UI we do not own, so its
+ *  raw markup is held to a stricter rule than a space the account owns. */
+export type ValidationMode = 'space' | 'widget';
 /** Authoritative per-type metadata from the component catalog (default sdk-elements ∪ this space's plugins).
  *  `custom` drives strict-vs-lenient validation: a default type (custom:false) owns its full attribute set, so an
  *  unknown attribute/setState key on it is an error; a plugin type (custom:true) is best-effort (warnings). */
@@ -14,6 +17,7 @@ export interface TypeMeta {
     };
 }
 export interface ValidationCtx {
+    mode: ValidationMode;
     errors: ValidationError[];
     warnings: string[];
     warned: Set<string>;

package/dist/src/modules/mcp/tools/shared/validator/elements.d.ts

@@ -3,4 +3,5 @@ import { ElementInput } from '../../operations';
 import { InitialStateInput } from '../../operations/schema/shared';
 export declare const checkTypeProps: (type: string, props: Record<string, unknown> | undefined, path: string, ctx: ValidationCtx) => void;
 export declare const checkVariantApplication: (initialState: InitialStateInput | undefined, path: string, ctx: ValidationCtx) => void;
+export declare const checkRawMarkup: (type: string, props: Record<string, unknown> | undefined, path: string, ctx: ValidationCtx) => void;
 export declare const checkElementInput: (element: ElementInput, path: string, ctx: ValidationCtx, seen: Set<string>) => void;

package/dist/src/modules/mcp/tools/shared/validator/index.d.ts

@@ -1,8 +1,8 @@
-import { ValidationCtx } from './context';
+import { ValidationCtx, ValidationMode } from './context';
 import { Space } from '../../../helpers';
 import { ValidationResult } from '../../../types';
 import { Operation } from '../../operations';
 /** The shared validation context, derived from a space (+ the batch's ops, for batch-declared names). Extracted so
  *  the post-apply resource audit (auditResources) can run the same checks against the resulting draft. */
-export declare const buildValidationCtx: (space: Space, ops: Operation[]) => ValidationCtx;
-export declare const validateOperations: (space: Space, ops: Operation[]) => ValidationResult;
+export declare const buildValidationCtx: (space: Space, ops: Operation[], mode?: ValidationMode) => ValidationCtx;
+export declare const validateOperations: (space: Space, ops: Operation[], mode?: ValidationMode) => ValidationResult;

package/dist/src/modules/mcp/types/appTypes.d.ts

@@ -7,7 +7,15 @@ export interface McpApp {
     title: string;
     /** Absolute path to the view: the app's browser entry. */
     entry: string;
-    /** Stylesheets to inline, by absolute path — lazy so a missing one only fails on read. */
+    /** CSS to inline in the page, in order. Lazy, and the app produces the text itself: what a view needs is not
+     *  always a file as it sits on disk (the render app leaves the icon fonts out of its stylesheet). */
     styles?: () => string[];
     csp?: McpUiResourceCsp;
 }
+/** Deployment switches the page hands to the view. They travel in the HTML rather than the bundle so a server
+ *  that serves both settings still builds the (expensive) browser bundle once. The view reads them off
+ *  `window.__PLITZI_VIEW__`, and must treat every one as optional: an older page carries none. */
+export interface McpViewSettings {
+    /** May the view paint from tool arguments the host is still streaming? See `mcpAi.renderStreaming`. */
+    streaming: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.19",
+  "version": "0.32.20",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,9 +30,9 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@plitzi/plitzi-sdk": "0.32.19",
-    "@plitzi/sdk-schema": "0.32.19",
-    "@plitzi/sdk-shared": "0.32.19",
+    "@plitzi/plitzi-sdk": "0.32.20",
+    "@plitzi/sdk-schema": "0.32.20",
+    "@plitzi/sdk-shared": "0.32.20",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"

package/skills/plitzi-render/SKILL.md

@@ -131,8 +131,12 @@ Everything the widget needs travels in ONE call, as `operations`. Three ops carr
 3. **Watch the SDK defaults.** Every container has `min-width`/`min-height: 50px` — set them to `0` for rails,
    dividers, dots and any flex child that must shrink. Headings and paragraphs keep the browser's margins; zero
    them and space with the parent's `gap`.
-4. **Never hand-draw a scene in a `data:` URI.** An inline SVG illustration costs more tokens than the entire rest
-   of the widget. Use an `https` image, a flat colour, or a CSS gradient.
+4. **Draw with inline SVG, on a budget.** A logo, a sparkline, a badge or a decorative shape goes in a `blockHtml`
+   element whose `props.content` is an `<svg>` — keep a `viewBox` with `width`/`height` `100%` so the element's
+   class sizes it, and `fill`/`stroke` `currentColor` so it follows the theme. A handful of paths, drawn once and
+   reused. Never a `data:` URI, and never a full illustration or a photo-real scene: that costs more than the rest
+   of the widget, so use an `https` image, a flat colour or a CSS gradient instead. Markup only — `<script>` and
+   inline `on*` handlers are rejected.
 5. **Write CSS plainly.** Kebab-case properties, shorthands welcome (`padding: 8px 16px`, `border: 1px solid red`,
    `font: bold 16px/1.5 Arial`) — they are expanded and stored as longhands, so a breakpoint or state can override
    one property on its own.