@plitzi/sdk-server 0.32.18 → 0.32.20

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+
+- v0.32.19
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.19
+  - @plitzi/sdk-schema@0.32.19
+  - @plitzi/sdk-shared@0.32.19
+
 ## 0.32.18
 
 ### Patch Changes

package/README.md

@@ -839,6 +839,24 @@ When `devMode: true`, per-phase timing is instrumented on every render and repor
 
 In production (`devMode: false`) timing instrumentation is skipped entirely — no `Server-Timing` header, no console output.
 
+## Agent skill
+
+This package ships an [Agent Skill](https://agentskills.io/) for `plitzi_render`, the MCP tool that renders a
+self-contained UI widget from a batch of operations. The skill teaches an agent when to show a widget instead of
+writing prose, the shape of a good call, the layout/theme traps that make a widget look wrong in a chat panel, and
+how to iterate on a widget it already rendered.
+
+It lives in [`skills/plitzi-render`](./skills/plitzi-render/SKILL.md) and is a plain `SKILL.md`, so it installs by
+copying that folder into the skills directory of the agent you use (Claude Code, VS Code / Copilot, Codex, Gemini
+CLI, Cline, Goose…):
+
+```bash
+cp -R node_modules/@plitzi/sdk-server/skills/plitzi-render ~/.claude/skills/
+```
+
+The skill only pays off with the Plitzi MCP server connected — it defers every detail to the `plitzi://render/guide`
+resource the server publishes, so the two never drift apart.
+
 ## Exported types
 
 ```ts

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,4 +1,5 @@
-import { require } from "../shared/resolve.js";
+import { VIEW_DIR } from "../shared/assets.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
@@ -9,8 +10,8 @@ var renderApp = {
 	name: "plitzi-render-app",
 	title: "Plitzi widget",
 	description: "Interactive view that renders a plitzi_render widget with the Plitzi SDK.",
-	entry: path.join(HERE, "view.tsx"),
-	styles: () => [path.join(path.dirname(require.resolve("@plitzi/plitzi-sdk")), "plitzi-sdk.css")]
+	entry: path.join(HERE, VIEW_DIR, "index.tsx"),
+	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/heldBatch.ts

@@ -0,0 +1,107 @@
+/** Where the batch a widget was built from survives between calls — on the HOST, so the server can keep nothing.
+ *
+ *  It cannot live in the view's memory: the Apps spec binds a view to ONE tool call (`ui/notifications/tool-input`
+ *  is sent "at most once", and the host renders a fresh iframe when a UI tool is called), so the patch call the
+ *  model makes arrives in a brand-new instance whose memory is empty. localStorage keyed by an id the server hands
+ *  back is the spec's own state-persistence pattern (`_meta.viewUUID` in the Apps docs); here the key is the
+ *  renderId, which the model also carries, so a patch names the widget it means instead of assuming "the last one".
+ */
+
+const PREFIX = 'plitzi.render.';
+const MAX_ENTRIES = 5;
+// A renderId only lives in one conversation's context, so a batch outlives its usefulness the moment that
+// conversation is over — and a conversation the user abandoned would otherwise leave its widget in the host's
+// storage for good. Generous enough that no live conversation loses its widget, short enough to be housekeeping.
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+type Stored = { savedAt: number; operations: unknown[] };
+
+// A sandboxed iframe without allow-same-origin throws on the ACCESS to localStorage, not on the call — so even
+// reading the property has to be guarded. A host that denies storage simply gets no patching.
+const localStore = (): Storage | undefined => {
+  try {
+    return window.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+const parse = (raw: string | null): Stored | undefined => {
+  if (raw === null) {
+    return undefined;
+  }
+
+  try {
+    const value = JSON.parse(raw) as Stored;
+
+    return Array.isArray(value.operations) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const ownKeys = (store: Storage): string[] => {
+  const keys: string[] = [];
+  for (let index = 0; index < store.length; index += 1) {
+    const key = store.key(index);
+    if (key !== null && key.startsWith(PREFIX)) {
+      keys.push(key);
+    }
+  }
+
+  return keys;
+};
+
+const dropStale = (store: Storage, keep: string): void => {
+  const others = ownKeys(store)
+    .filter(key => key !== keep)
+    .map(key => ({ key, savedAt: parse(store.getItem(key))?.savedAt ?? 0 }))
+    .sort((a, b) => b.savedAt - a.savedAt);
+  const expired = Date.now() - MAX_AGE_MS;
+
+  for (const [index, entry] of others.entries()) {
+    if (index >= MAX_ENTRIES - 1 || entry.savedAt < expired) {
+      store.removeItem(entry.key);
+    }
+  }
+};
+
+export const readHeldBatch = (renderId: string, store = localStore()): unknown[] | undefined => {
+  if (!store) {
+    return undefined;
+  }
+
+  const stored = parse(store.getItem(`${PREFIX}${renderId}`));
+  if (!stored || stored.savedAt < Date.now() - MAX_AGE_MS) {
+    return undefined;
+  }
+
+  return stored.operations;
+};
+
+export const writeHeldBatch = (renderId: string, operations: unknown[], store = localStore()): void => {
+  if (!store) {
+    return;
+  }
+
+  const key = `${PREFIX}${renderId}`;
+  const payload = JSON.stringify({ savedAt: Date.now(), operations } satisfies Stored);
+
+  try {
+    dropStale(store, key);
+    store.setItem(key, payload);
+  } catch {
+    // Out of quota: the widget just rendered is the only one still worth patching, so the rest go.
+    for (const other of ownKeys(store)) {
+      if (other !== key) {
+        store.removeItem(other);
+      }
+    }
+
+    try {
+      store.setItem(key, payload);
+    } catch {
+      // Storage is full or refused: patching degrades to "re-send the full batch", never to a wrong widget.
+    }
+  }
+};

package/dist/modules/mcp/apps/render/{view.tsx → 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/assets.js

@@ -0,0 +1,10 @@
+import "node:path";
+//#region src/modules/mcp/apps/shared/assets.ts
+/** The one folder of an app that ships to dist as SOURCE: its browser entry (`view/index.tsx`) and every module
+*  that entry bundles. The server builds it with esbuild at request time, so none of it is in the module graph the
+*  library build compiles — a view-side module that does not travel verbatim is simply missing at runtime, which
+*  the package only finds out when a host asks for the page. Everything else in an app (its definition) compiles
+*  like any other module. */
+var VIEW_DIR = "view";
+//#endregion
+export { VIEW_DIR };

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

@@ -2,21 +2,22 @@ import { require } from "./resolve.js";
 import { zodEnglishOnly } from "./zodEnglishOnly.js";
 import { build } from "esbuild";
 //#region src/modules/mcp/apps/shared/bundle.ts
+var options = (entry) => ({
+	entryPoints: [entry],
+	bundle: true,
+	write: false,
+	format: "iife",
+	platform: "browser",
+	target: "es2022",
+	jsx: "automatic",
+	minify: true,
+	alias: { "@plitzi/plitzi-sdk": require.resolve("@plitzi/plitzi-sdk") },
+	define: { "process.env.NODE_ENV": "\"production\"" },
+	plugins: [zodEnglishOnly],
+	logLevel: "silent"
+});
 var bundle = async (entry) => {
-	return (await build({
-		entryPoints: [entry],
-		bundle: true,
-		write: false,
-		format: "iife",
-		platform: "browser",
-		target: "es2022",
-		jsx: "automatic",
-		minify: true,
-		alias: { "@plitzi/plitzi-sdk": require.resolve("@plitzi/plitzi-sdk") },
-		define: { "process.env.NODE_ENV": "\"production\"" },
-		plugins: [zodEnglishOnly],
-		logLevel: "silent"
-	})).outputFiles[0].text;
+	return (await build(options(entry))).outputFiles[0].text;
 };
 //#endregion
 export { bundle };

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;
 };