@plitzi/sdk-server 0.32.17 → 0.32.18

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

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/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/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,20 +76,91 @@ 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
+
+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": "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 a class, then attach it by ref.
+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": "upsertDefinition", "ref": "card", "desktop": { "display": "flex", "flex-direction": "column", "gap": "8px", "padding": "24px", "border-radius": "12px" } }
+{ "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 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 SDK stylesheet resets almost nothing (\`box-sizing\`,
-  \`border: 0 solid\`, \`body\` margin), so anything you leave unset comes from one of two places:
+  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
@@ -85,9 +174,10 @@ Styling is separate from structure: declare a class, then attach it by ref.
     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 —
@@ -106,14 +196,16 @@ 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": "upsertDefinition", "ref": "row", "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } }
-  { "type": "upsertDefinition", "ref": "col", "desktop": { "flex-grow": "1", "flex-basis": "0%", "min-width": "150px" } }
+  { "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": "upsertDefinition", "ref": "grid", "desktop": { "display": "grid", "grid-template-columns": "repeat(auto-fit, minmax(160px, 1fr))", "gap": "12px" } }
+  { "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.
@@ -133,12 +225,12 @@ The host publishes its palette as CSS variables on the page, so use them for eve
 \`light-dark(<light>, <dark>)\` fallback for hosts that send none:
 
 \`\`\`json
-{ "type": "upsertDefinition", "ref": "card", "desktop": {
+{ "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\`
@@ -173,6 +265,19 @@ 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.
 
+## 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
@@ -181,10 +286,12 @@ narrow panel \`min-width\` drops the second card under the first on its own.
 \`\`\`json
 {
   "operations": [
-    { "type": "upsertDefinition", "ref": "plans", "desktop": { "display": "flex", "flex-direction": "row", "flex-wrap": "wrap", "gap": "12px", "align-items": "stretch" } },
-    { "type": "upsertDefinition", "ref": "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" } },
-    { "type": "upsertDefinition", "ref": "price", "desktop": { "font-size": "28px", "font-weight": "800", "color": "#3b82f6" } },
-    { "type": "upsertDefinition", "ref": "cta", "desktop": { "background-color": "#3b82f6", "color": "#ffffff", "padding": "10px 16px", "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": "plans", "type": "container", "style": { "base": ["plans"] },
         "children": [

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.17"
+		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,

package/dist/modules/mcp/tools/operations/schema/elements/patchElement.js

@@ -10,7 +10,7 @@ var patchElementOp = z.object({
 	type: z.literal("patchElement"),
 	pageRef: z.string().describe("Page ref or id"),
 	ref: z.string().describe("Existing element ref or id"),
-	idRef: z.string().optional().describe("Assign or rename the idRef of this element ([A-Za-z0-9_-], starting with a letter, unique in the space). Give an element one to make it bindable: without an idRef it publishes no data source. Renaming one moves its source name with it — every binding and interaction across the space that targeted the old name is repointed for you, so the wiring survives the rename."),
+	idRef: z.string().optional().describe("Assign or rename this element idRef ([A-Za-z0-9_-], starting with a letter, unique in the space). Without one an element publishes no data source, so it is not bindable. A rename moves the source name with it: every binding and interaction that targeted the old one is repointed for you."),
 	label: z.string().optional(),
 	subType: z.string().optional(),
 	props: z.record(z.string(), z.unknown()).optional().describe("Merged onto existing props: listed keys change, null unsets a key, others are preserved"),