@plitzi/sdk-server 0.32.16 → 0.32.18

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @plitzi/sdk-server
 
+## 0.32.18
+
+### Patch Changes
+
+- v0.32.18
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.18
+  - @plitzi/sdk-schema@0.32.18
+  - @plitzi/sdk-shared@0.32.18
+
+## 0.32.17
+
+### Patch Changes
+
+- v0.32.17
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.17
+  - @plitzi/sdk-schema@0.32.17
+  - @plitzi/sdk-shared@0.32.17
+
 ## 0.32.16
 
 ### Patch Changes

package/dist/helpers/serverLog.js

@@ -8,12 +8,12 @@ var renderRequest = (event) => {
 };
 var renderTool = (event) => {
 	const args = event.argsSummary ? ` ${event.argsSummary}` : "";
-	return `[mcp] tools/call ${event.name}${args} ${Math.round(event.durationMs)}ms ${outcomeOf(event)}`;
+	return `[MCP] tools/call ${event.name}${args} ${Math.round(event.durationMs)}ms ${outcomeOf(event)}`;
 };
-var renderResource = (event) => `[mcp] resources/read ${event.name} ${Math.round(event.durationMs)}ms ${outcomeOf(event)}`;
+var renderResource = (event) => `[MCP] resources/read ${event.name} ${Math.round(event.durationMs)}ms ${outcomeOf(event)}`;
 /** One line for any {@link ServerLogEvent}: an HTTP request reads as an access-log line
 *  (`[SSR] 203.0.113.7 GET /pricing 200 12ms ok`), the MCP events as what happened inside one
-*  (`[mcp] tools/call plitzi_apply {operations:[3]} 41ms ok`). Rendering is a pure format — the dispatcher
+*  (`[MCP] tools/call plitzi_apply {operations:[3]} 41ms ok`). Rendering is a pure format — the dispatcher
 *  already stripped query values, collected no headers, cookies or tokens and summarised tool args by shape;
 *  the client IP it does carry is personal data, so a sink that persists these lines must say so. */
 var renderLogEvent = (event) => {

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

@@ -1,10 +1,12 @@
 /* eslint-disable react-refresh/only-export-components -- one bundled entry: components cannot move out. */
 import { useApp, useHostStyles } from '@modelcontextprotocol/ext-apps/react';
 import PlitziSdk from '@plitzi/plitzi-sdk';
-import { Component, useEffect, useState } from 'react';
+import { Component, useEffect, useRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 
-import type { McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+import { readHeldBatch, writeHeldBatch } from './heldBatch';
+
+import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { OfflineDataRaw } from '@plitzi/sdk-shared';
 import type { ReactNode } from 'react';
@@ -39,17 +41,119 @@ class RenderBoundary extends Component<{ children: ReactNode }, { error?: Error
   }
 }
 
+/** The batch the widget on screen was built from. It lives on the HOST side — this ref plus localStorage — because
+ *  the server keeps nothing between calls, which is what lets any replica (or an edge deployment) answer any
+ *  request. A patch is merged into it and sent back through `callServerTool`, so the full batch never enters the
+ *  model's context. The ref alone would not do: the host gives each tool call its own view, so a patch usually
+ *  starts from an empty instance and reads the batch back from storage by renderId (see heldBatch.ts). */
+type Held = { renderId?: string; operations: unknown[] };
+
+const summarise = (result: CallToolResult): string => {
+  const text = result.content.find(entry => entry.type === 'text');
+
+  return text?.text ?? 'no summary';
+};
+
 const RenderApp = () => {
   const [result, setResult] = useState<CallToolResult | null>(null);
   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);
+
+  // 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)
+  // from a payload that travelled host↔server, and the model hears the outcome through updateModelContext.
+  const applyPatch = async (renderId: string, delta: unknown[]): Promise<void> => {
+    const app = appRef.current;
+    if (!app) {
+      return;
+    }
+
+    const base = held.current.renderId === renderId ? held.current.operations : (readHeldBatch(renderId) ?? []);
+    if (base.length === 0) {
+      await app.updateModelContext({
+        content: [
+          {
+            type: 'text',
+            text: `The widget ${renderId} could not be recovered, so nothing was patched. Call plitzi_render again with the complete batch and without \`patch\`.`
+          }
+        ]
+      });
+
+      return;
+    }
+
+    const merged = [...base, ...delta];
+    // The round trip can fail on its own: a host that forwards no tool calls, a connection dropped mid-patch, a
+    // view torn down while the answer is in flight. Unreported it would surface as an unhandled rejection inside
+    // the sandbox and the model would wait forever for a widget that is never coming.
+    try {
+      const rendered = await app.callServerTool({
+        name: 'plitzi_render',
+        arguments: { operations: merged, renderId }
+      });
+      const offlineData = rendered.structuredContent?.offlineData;
+      if (offlineData) {
+        const applied = (rendered.structuredContent?.operations as unknown[] | undefined) ?? merged;
+        held.current = { renderId, operations: applied };
+        writeHeldBatch(renderId, applied);
+        setResult(rendered);
+      }
+
+      await app.updateModelContext({
+        content: [
+          {
+            type: 'text',
+            text: offlineData
+              ? `Widget updated: ${summarise(rendered)}`
+              : `The patch did not apply, the widget is unchanged: ${summarise(rendered)}`
+          }
+        ]
+      });
+    } catch (reason) {
+      await app
+        .updateModelContext({
+          content: [
+            {
+              type: 'text',
+              text: `The patch could not be delivered (${reason instanceof Error ? reason.message : String(reason)}), so the widget is unchanged. Re-send the full batch without \`patch\` if it needs to change.`
+            }
+          ]
+        })
+        .catch(() => undefined);
+    }
+  };
 
   // useApp creates the App, runs onAppCreated so every handler is in place BEFORE the handshake, and connects.
   const { app, error } = useApp({
     appInfo: { name: 'Plitzi Widget', version: '1.0.0' },
     capabilities: {},
     onAppCreated: instance => {
-      instance.ontoolresult = setResult;
+      appRef.current = instance;
+      instance.ontoolresult = toolResult => {
+        const renderId = toolResult.structuredContent?.renderId as string | undefined;
+        if (toolResult.structuredContent?.patch === true && renderId) {
+          void applyPatch(renderId, (toolResult.structuredContent.operations as unknown[] | undefined) ?? []);
+
+          return;
+        }
+
+        // A result carrying no widget is a failed render or a refused patch. The model already reads its reasons
+        // as text, so it must not blank a widget that is on screen — nor drop the batch that widget was built
+        // from, which is the only copy of it anywhere. With nothing on screen yet, the error IS the view.
+        if (!toolResult.structuredContent?.offlineData && held.current.operations.length > 0) {
+          return;
+        }
+
+        const operations = (toolResult.structuredContent?.operations as unknown[] | undefined) ?? [];
+        held.current = { renderId, operations };
+        if (renderId && operations.length > 0) {
+          writeHeldBatch(renderId, operations);
+        }
+
+        setResult(toolResult);
+      };
       instance.ontoolcancelled = params => setCancelled(params.reason ?? 'The host cancelled the render.');
       instance.onhostcontextchanged = params => setContext(previous => ({ ...previous, ...params }));
       instance.onteardown = () => ({});

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

@@ -10,17 +10,34 @@
     <title><%= title %></title>
 
     <style>
+      /*
+        The page inherits the HOST's theme, which may be dark: nothing here paints a surface, so an app that sets no
+        colours would otherwise draw the browser's black default text over the host's own background — unreadable in
+        a dark chat. `light-dark()` picks the right side of every pair; `color-scheme` is what tells it which side,
+        and it follows the OS until useHostStyles replaces it with the theme the host actually reported (that hook
+        also fills the --color-* variables in, so the var() fallbacks below only apply on a host that sends none).
+      */
+      html {
+        color-scheme: light dark;
+      }
+
       html,
       body {
         margin: 0;
       }
+
+      body {
+        background-color: transparent;
+        color: var(--color-text-primary, light-dark(#0f172a, #e8eaed));
+        font-family: var(--font-sans, system-ui, sans-serif);
+      }
       /* The app renders nothing until the host pushes the tool result in. */
       #app:empty::after {
         content: 'Rendering…';
         display: block;
         padding: 16px;
-        font: 14px system-ui, sans-serif;
-        color: #64748b;
+        font-size: 14px;
+        color: var(--color-text-tertiary, light-dark(#64748b, #9aa4b2));
       }
     </style>
     <style>

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

@@ -202,7 +202,12 @@ pointed at the old name is repointed with it, so the element stays wired. You do
   (prefer a unitless ratio like \`1.5\`, which tracks the font size). Changing one without the other leaves cramped or
   loosely-spaced text — they are a joint change, not two separate ones.
 - A definition lives in the **style schema**; an element's \`style.base\` (element schema) is the link that applies
-  it. Styling an element = upsertDefinition + upsertElement with that ref in \`style.base\`, in one batch.
+  it. Styling an element = upsertDefinitions + upsertElement with that ref in \`style.base\`, in one batch.
+- **Repeating siblings**: when a set of siblings shares a shape and differs only in data (a list, cards, rows,
+  steps), use \`repeatElement\` — the template once with \`{{item.field}}\` placeholders plus \`items\`, which
+  creates the wrapper and numbers each row's refs (\`step-1\`, \`step-2\`…). A list inside each row is the same op:
+  the wrapping node carries \`repeat: { items: "{{item.<list>}}", template: … }\` and its refs number both levels
+  (\`blk-2-3\`). Copy-pasting the subtree N times costs N times the tokens and drifts.
 - CSS keys are **kebab-case** (\`background-color\`). camelCase is rejected — read \`plitzi://css-properties\`.
 - **Write normal CSS — shorthands are accepted and expanded for you.** \`border\`, \`border-{side}\`,
   \`border-width\`/\`-color\`/\`-style\`, \`border-radius\`, \`padding\`, \`margin\`, \`inset\`, \`gap\`, \`overflow\`,
@@ -232,7 +237,9 @@ pointed at the old name is repointed with it, so the element stays wired. You do
 - **Three kinds of style live in the style schema — do not confuse them:**
   - **Definitions** = reusable CSS **classes** (\`upsertDefinition\`/\`patchDefinition\`/\`deleteDefinition\`, keyed by a
     class \`ref\`). Attach one to an element via \`style.base\` to style **that** element (and anything else that opts in).
-    This is the **default** way to style one element.
+    This is the **default** way to style one element. Declaring MORE than one class in a batch? Use
+    \`upsertDefinitions\` — one op carrying \`{ "<class>": { desktop: … }, … }\`, same result as the run of
+    \`upsertDefinition\` it replaces, without repeating the envelope once per class.
   - **Global styles** = the CSS equivalent of a bare element selector like \`button { … }\`
     (\`upsertGlobalStyle\`/\`patchGlobalStyle\`/\`deleteGlobalStyle\`, keyed by \`componentType\`). They style **every**
     element of that type at once. Use these for site-wide intent — e.g. "all buttons rounded":

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

@@ -280,7 +280,7 @@ var pageRefOfElement = (schema, el) => {
 /** Total number of descendant elements under a subtree (excluding the root). */
 var descendantCount = (schema, rootId) => descendantIds(schema, rootId).length;
 var emptySpaceMessage = "Space data not available";
-var unauthorizedSpaceMessage = "This tool/resource needs a space, but no spaceId could be resolved from the Authorization token";
+var unauthorizedSpaceMessage = "This connection has no space attached (a guest or widgets-only grant, or a token that carries no space), so NOTHING in a space can be read or edited — every other space tool will fail the same way, do not retry them. Use plitzi_render instead: it builds a self-contained widget offline, with no space, backend or account (read plitzi://render/guide). To edit a real space, the user must reconnect the integration and grant access to one.";
 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("")}`;
 };

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

@@ -33,8 +33,26 @@ Most widgets are **presentation only** — the structure + styling below is all
 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.
+Each call renders a **fresh** widget: send **every** operation it needs in the one call.
+
+**To CHANGE a widget you already rendered, do not rebuild it** — every render answers with a \`renderId\`; call
+again with that id, \`patch: true\` and only the operations that differ:
+
+\`\`\`json
+{ "patch": true, "renderId": "r7f3a2c", "operations": [
+  { "type": "patchDefinition", "ref": "tl-card", "desktop": { "border-radius": "20px" } },
+  { "type": "patchElement", "pageRef": "render", "ref": "title-2", "props": { "content": "EPCOT (día largo)" } }
+] }
+\`\`\`
+The widget merges the delta into the batch it was built from and reports back what it applied — including the
+errors, if a ref does not exist. Address rows by the refs you already know (\`card-1\`, \`blk-2-3\`). If it reports
+that the widget could not be recovered (a surface that renders none, a host that keeps no storage, a conversation
+resumed elsewhere), send the whole batch again without \`patch\`.
+
+**Patch only to modify what is on screen.** A different subject, or a different kind of widget, is a FRESH render
+with no \`patch\` — the delta is merged into the previous widget, so patching a new idea leaves the user looking at
+both at once. Rebuilding when you could have patched only costs tokens; patching when you should have rebuilt costs
+the user a wrong widget.
 
 ## Build the whole widget in ONE upsertElement (nest with \`children\`)
 
@@ -58,28 +76,172 @@ An element is \`{ ref, type, subType?, props?, style?, children? }\`. Children r
 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
+## Repeating rows — repeatElement, never copy-paste
 
-Styling is separate from structure: declare a class, then attach it by ref.
+The moment two siblings have the same shape and different data — a list, steps, cards, a table, a timeline —
+**write the shape once** and hand over the rows. \`repeatElement\` creates the wrapper (style it with the row/grid
+class) and renders the template once per entry of \`items\`:
 
 \`\`\`json
-{ "type": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "24px", "border-radius": "12px" } }
+{ "type": "repeatElement", "pageRef": "render", "ref": "steps", "style": { "base": ["list"] },
+  "template": {
+    "ref": "step", "type": "container", "style": { "base": ["row"] },
+    "children": [
+      { "ref": "at",   "type": "paragraph", "style": { "base": ["time"] }, "props": { "content": "{{item.time}}" } },
+      { "ref": "what", "type": "paragraph", "style": { "base": ["txt"] },  "props": { "content": "{{item.text}}" } }
+    ]
+  },
+  "items": [
+    { "time": "08:00", "text": "Doors open, head straight to the main hall." },
+    { "time": "10:30", "text": "Workshops in the east wing." },
+    { "time": "13:00", "text": "Lunch, then the keynote." }
+  ]
+}
 \`\`\`
+- \`{{item.<field>}}\` is replaced by that row's field, anywhere in the template (props, a style ref, a param).
+  A placeholder that is the WHOLE value keeps the field's type (\`"{{item.count}}"\` with \`count: 3\` stays the
+  number 3); mixed with text it interpolates. Dotted paths work: \`{{item.author.name}}\`.
+- Every ref in the template gets the row number appended — \`step\` becomes \`step-1\`, \`step-2\`… — so rows never
+  collide and you can address one later without reading anything back.
+- Other \`{{…}}\` names are left untouched, so schema variables keep working inside a template.
+- A row missing a field the template reads fails the batch and names the row and the fields it does carry.
+- Up to 100 rows per op. Rows that differ in SHAPE (not just data) are not rows — write those as plain elements.
+
+**A list inside each row** — a timeline of days each with its own steps, a menu of sections each with its dishes —
+is one op too: give the node that should wrap the sub-list a \`repeat\`, and put the sub-rows in the row's data.
+
+\`\`\`json
+{ "type": "repeatElement", "pageRef": "render", "ref": "timeline", "style": { "base": ["tl"] },
+  "template": {
+    "ref": "day", "type": "container", "style": { "base": ["day"] },
+    "children": [
+      { "ref": "title", "type": "heading", "subType": "h3", "props": { "content": "{{item.park}}" } },
+      { "ref": "body", "type": "container", "style": { "base": ["body"] },
+        "repeat": { "items": "{{item.blocks}}", "template": {
+            "ref": "blk", "type": "container", "style": { "base": ["blk"] },
+            "children": [
+              { "ref": "at",   "type": "paragraph", "props": { "content": "{{item.time}}" } },
+              { "ref": "what", "type": "paragraph", "props": { "content": "{{item.text}}" } }
+            ]
+        } } }
+    ]
+  },
+  "items": [
+    { "park": "Magic Kingdom", "blocks": [ { "time": "08:00", "text": "Rope drop." }, { "time": "10:30", "text": "Space Mountain." } ] },
+    { "park": "EPCOT",         "blocks": [ { "time": "08:30", "text": "Cosmic Rewind." } ] }
+  ]
+}
+\`\`\`
+- The node carrying \`repeat\` becomes the WRAPPER of its sub-list (its own \`children\` are ignored), so put the
+  sub-list's layout class on it.
+- Inside the sub-template \`{{item.…}}\` reads the SUB-row; a field of the outer row is not reachable from there,
+  so repeat it in each sub-row if you need it.
+- Refs number both levels, outer first: \`blk-2-3\` is the third block of the second day.
+- **One level of nesting**: the sub-template is a plain element tree, so it cannot carry another \`repeat\`.
+- The whole op is capped at 500 rows across both levels.
+
+## Style with reusable classes — upsertDefinitions
+
+Styling is separate from structure: declare the classes, then attach them by ref. **Declare them all in ONE
+\`upsertDefinitions\`**, keyed by class name — a widget usually needs a dozen classes, and one op per class spends a
+noticeable slice of the call on repeated \`{"type":"upsertDefinition","ref":…}\` envelopes.
+
+\`\`\`json
+{ "type": "upsertDefinitions", "definitions": {
+    "card": { "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "16px", "border-radius": "12px" } },
+    "title": { "desktop": { "font-size": "16px", "font-weight": "600", "margin-top": "0", "margin-bottom": "0" } }
+} }
+\`\`\`
+Each value is exactly what \`upsertDefinition\` takes minus \`type\`/\`ref\` (\`desktop\`/\`tablet\`/\`mobile\`, \`states\`,
+\`variants\`, \`slots\`), and the result is identical. The single \`upsertDefinition\` still exists for a one-off class,
+and \`patchDefinition\` still changes only some CSS of one class.
 - 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" }\`.
+- Lay containers out with flexbox or grid — pick the direction on purpose, see **Fit the panel** below.
+- **You are not styling from zero.** Each type lands on the page with CSS you did not write, and it is the usual
+  reason a widget does not look like the definitions say:
+  - The per-type rule the SDK ships — the one that changes layouts is \`container\`, which carries
+    \`min-width: 50px; min-height: 50px\`. A rail, a divider, a dot, a spacer or a narrow cell will NOT go below
+    50px until you say \`"min-width": "0"\` (and/or \`"min-height": "0"\`) on it: a 2px timeline line renders 50px
+    wide otherwise. Any flex child that must be allowed to shrink needs it too.
+  - The BROWSER's own defaults for the rest: \`heading\` keeps its UA font-size and ~0.67em top/bottom margins,
+    \`paragraph\` ~1em margins, \`list\` a 40px \`padding-left\`, \`button\` its native chrome, \`image\` its intrinsic
+    size, \`link\` its own colour and underline. In a compact widget set these explicitly — usually
+    \`"margin-top": "0"\`, \`"margin-bottom": "0"\` — and space things with the parent's \`gap\` instead.
+  - Borders start at \`0 solid\`, so \`border-color\` alone paints nothing: give \`border-width\` (and the colour).
+  - The \`defaultStyle\` a type reports in the EDITING catalog (\`plitzi://types\`) is authoring metadata for the
+    builder — it does not paint here, so do not count on it in a widget.
 - **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.
+- **Shorthands are welcome** and cheaper to write: \`padding: 8px 16px\`, \`border: 1px solid #ddd\`,
+  \`font: bold 16px/1.5 Arial\`, \`flex: 1 1 auto\`, \`transition: opacity 200ms ease\`. They are stored expanded to
+  their longhands, so a breakpoint, state or variant can override each property on its own — and a read-back shows
+  the longhands, not what you wrote. 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\`).
 
+## Fit the panel — go wide, stay short
+
+The widget renders in a **side panel** (Claude Desktop, ChatGPT, the Plitzi builder), so it gets a usable width but
+very little height: everything past the first screenful costs the user a scroll. Height is the scarce resource —
+spend width instead.
+
+Plain containers are blocks, so doing nothing stacks children **vertically** and produces exactly the tall,
+half-empty widget to avoid. Choose the axis every time:
+
+- **Peers side by side** — metrics, plans, options, a comparison, an image next to its text: a row, wrapping when
+  it runs out of width, children sharing it (no fixed widths).
+  \`\`\`json
+  { "type": "upsertDefinitions", "definitions": {
+      "row": { "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } },
+      "col": { "desktop": { "flex-grow": "1", "flex-basis": "0%", "min-width": "150px" } }
+  } }
+  \`\`\`
+  \`flex-grow: 1\` + \`flex-basis: 0%\` splits the row evenly; \`min-width\` is the wrap threshold — under it the item
+  drops to the next line by itself, so a narrow panel degrades gracefully with no breakpoints.
+- **Many uniform items** — cards, tiles, a gallery: one grid line does it all.
+  \`\`\`json
+  { "type": "upsertDefinitions", "definitions": { "grid": { "desktop": { "display": "grid", "grid-template-columns": "repeat(auto-fit, minmax(160px, 1fr))", "gap": "12px" } } } }
+  \`\`\`
+- **Label + value pairs** stay on one line (\`display: flex\`, \`justify-content: space-between\`) instead of two.
+- **Vertical is right** for reading order: a heading over its paragraph, a form, a step list, long prose.
+- Force a stack on tiny screens with the \`mobile\` block: \`"mobile": { "flex-direction": "column" }\`.
+
+Keep it compact, and the numbers low: \`padding\` 12–16px (24+ only on a single hero card), \`gap\` 8–12px,
+\`font-size\` 13–15px for body and 16–20px for headings. Let the outer container **fill** the panel — no \`width\` on
+it — and reach for \`max-width\` only to stop one lone card from stretching across the whole panel.
+
+## Match the host theme — never hardcode a light palette
+
+The widget is embedded in the host's own UI (Claude Desktop, ChatGPT, the builder), and that UI **may be in dark
+mode**. A widget painted with fixed light colours is the most common way to ship something unusable: a white card
+in a dark chat glares, and — worse — text left at a dark default disappears against the host's dark background.
+
+The host publishes its palette as CSS variables on the page, so use them for every colour, with a
+\`light-dark(<light>, <dark>)\` fallback for hosts that send none:
+
+\`\`\`json
+{ "type": "upsertDefinitions", "definitions": { "card": { "desktop": {
+    "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))",
+    "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))",
+    "border-width": "1px", "border-style": "solid",
+    "border-color": "var(--color-border-primary, light-dark(#e2e8f0, #333a48))"
+} } } }
+\`\`\`
+
+- Surfaces: \`--color-background-primary\` (the page), \`--color-background-secondary\` / \`--color-background-tertiary\`
+  (cards, raised areas). Text: \`--color-text-primary\`, \`--color-text-secondary\`, \`--color-text-tertiary\` (muted).
+  Borders: \`--color-border-primary\` / \`--color-border-secondary\`. Status pairs: \`--color-background-danger\` |
+  \`success\` | \`warning\` | \`info\` with the matching \`--color-text-…\`. Also \`--font-sans\`, \`--border-radius-md\` /
+  \`lg\` / \`full\`, \`--shadow-sm\` / \`md\`.
+- **Set \`color\` wherever you set \`background-color\`** — the pair is what stays legible, either one alone is a
+  gamble. Same rule for a brand accent: a CTA on your own blue must state its own text colour (\`#ffffff\`).
+- Prefer a border to a drop shadow for separation: shadows all but vanish on a dark surface.
+
 ## Element types (type → what to set)
 
 | type | renders | set |
@@ -103,21 +265,46 @@ 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
+## 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).
+- **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.
+
+## Full worked example — two plans side by side
+
+The cards sit in a wrapping row and split it evenly, so the widget uses the panel's width and stays short; on a
+narrow panel \`min-width\` drops the second card under the first on its own.
 
 \`\`\`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": "upsertDefinitions", "definitions": {
+        "plans": { "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } },
+        "card": { "desktop": { "display": "flex", "flex-direction": "column", "gap": "6px", "flex-grow": "1", "flex-basis": "0%", "min-width": "150px", "padding": "16px", "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))", "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))", "border-width": "1px", "border-style": "solid", "border-color": "var(--color-border-primary, light-dark(#e2e8f0, #333a48))", "border-radius": "var(--border-radius-lg, 12px)", "text-align": "center" } },
+        "price": { "desktop": { "font-size": "28px", "font-weight": "800", "color": "#3b82f6" } },
+        "cta": { "desktop": { "background-color": "#3b82f6", "color": "#ffffff", "padding": "10px 16px", "border-radius": "8px", "font-weight": "600" }, "states": { "hover": { "desktop": { "background-color": "#2563eb" } } } }
+    } },
     { "type": "upsertElement", "pageRef": "render", "element": {
-        "ref": "card", "type": "container", "style": { "base": ["card"] },
+        "ref": "plans", "type": "container", "style": { "base": ["plans"] },
         "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"] } }
+          { "ref": "free", "type": "container", "style": { "base": ["card"] }, "children": [
+            { "ref": "free-plan",   "type": "heading", "subType": "h3", "props": { "content": "Starter" } },
+            { "ref": "free-amount", "type": "text",    "props": { "content": "$0" }, "style": { "base": ["price"] } },
+            { "ref": "free-buy",    "type": "button",  "props": { "content": "Start free" }, "style": { "base": ["cta"] } }
+          ] },
+          { "ref": "pro", "type": "container", "style": { "base": ["card"] }, "children": [
+            { "ref": "pro-plan",   "type": "heading", "subType": "h3", "props": { "content": "Pro" } },
+            { "ref": "pro-amount", "type": "text",    "props": { "content": "$29/mo" }, "style": { "base": ["price"] } },
+            { "ref": "pro-buy",    "type": "button",  "props": { "content": "Start free trial" }, "style": { "base": ["cta"] } }
+          ] }
         ]
     } }
   ]

package/dist/modules/mcp/server.js

@@ -43,7 +43,7 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.16"
+		version: "0.32.18"
 	}, { instructions: serverInstructions });
 	registerResources(server, getSpace, MCP_ENV, log);
 	registerApps(server);

package/dist/modules/mcp/tools/apply/dispatch.js

@@ -19,6 +19,7 @@ import { upsertVariable } from "../operations/schema/variables/upsertVariable.js
 import { deleteDefinition } from "../operations/style/definitions/deleteDefinition.js";
 import { patchDefinition } from "../operations/style/definitions/patchDefinition.js";
 import { upsertDefinition } from "../operations/style/definitions/upsertDefinition.js";
+import { upsertDefinitions } from "../operations/style/definitions/upsertDefinitions.js";
 import { deleteGlobalStyle } from "../operations/style/globalStyles/deleteGlobalStyle.js";
 import { patchGlobalStyle } from "../operations/style/globalStyles/patchGlobalStyle.js";
 import { upsertGlobalStyle } from "../operations/style/globalStyles/upsertGlobalStyle.js";
@@ -49,6 +50,7 @@ var executeOp = (space, env, op) => {
 		case "deleteInteraction": return deleteInteraction(space, env, op);
 		case "patchSettings": return patchSettings(space, env, op);
 		case "upsertDefinition": return upsertDefinition(space, env, op);
+		case "upsertDefinitions": return upsertDefinitions(space, env, op);
 		case "patchDefinition": return patchDefinition(space, env, op);
 		case "deleteDefinition": return deleteDefinition(space, env, op);
 		case "upsertGlobalStyle": return upsertGlobalStyle(space, env, op);

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

@@ -2,6 +2,7 @@ import { cloneSpace } from "../../helpers/space.js";
 import { environment, operations } from "../operations/index.js";
 import { applyOperations } from "./dispatch.js";
 import { changedResources, conflictMessage, detectConflicts, resolvedElements } from "./writeResult.js";
+import { expandOperations } from "../shared/expandOperations.js";
 import { defineTool } from "../shared/tool.js";
 import { validateOperations } from "../shared/validator/index.js";
 import { auditResources } from "../shared/validator/audit.js";
@@ -22,7 +23,20 @@ var schemaErrorToValidation = (error) => ({
 });
 var apply = async (input, space, persisters) => {
 	const env = input.environment ?? "main";
-	const validation = validateOperations(space, input.operations);
+	const expansion = expandOperations(input.operations);
+	if (expansion.errors.length > 0) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		errors: expansion.errors
+	};
+	const ops = expansion.operations;
+	const validation = validateOperations(space, ops);
 	if (!validation.valid) return {
 		applied: false,
 		persisted: false,
@@ -51,7 +65,7 @@ var apply = async (input, space, persisters) => {
 		}
 	};
 	const draft = cloneSpace(space);
-	const outcome = applyOperations(draft, env, input.operations);
+	const outcome = applyOperations(draft, env, ops);
 	if (outcome.errors.length > 0) return {
 		applied: false,
 		persisted: false,
@@ -77,7 +91,7 @@ var apply = async (input, space, persisters) => {
 		errors: integrity.errors.map(schemaErrorToValidation),
 		warnings: noWarnings(validation.warnings)
 	};
-	const audit = auditResources(draft, input.operations);
+	const audit = auditResources(draft, ops);
 	const warnings = [...validation.warnings, ...audit.warnings];
 	if (audit.errors.length > 0) return {
 		applied: false,

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

@@ -1,9 +1,12 @@
 import { elementOps } from "./schema/operations.js";
+import { registerSharedSchemaIds } from "./schemaIds.js";
 import { styleOps } from "./style/operations.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/index.ts
+registerSharedSchemaIds();
 var operation = z.discriminatedUnion("type", [
 	elementOps.upsertElement,
+	elementOps.repeatElement,
 	elementOps.patchElement,
 	elementOps.deleteElement,
 	elementOps.moveElement,
@@ -21,6 +24,7 @@ var operation = z.discriminatedUnion("type", [
 	elementOps.deleteInteraction,
 	elementOps.patchSettings,
 	styleOps.upsertDefinition,
+	styleOps.upsertDefinitions,
 	styleOps.patchDefinition,
 	styleOps.deleteDefinition,
 	styleOps.upsertGlobalStyle,