@plitzi/sdk-server 0.32.17 → 0.32.19

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,24 +76,95 @@ 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 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:
-  - 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.
+  reason a widget does not look like the definitions say:
+  - The per-type CSS the SDK ships imposes **no minimum size**: a rail, a divider, a dot or a narrow cell is
+    exactly as small as you make it, and no \`"min-width": "0"\` escape hatch is needed. The flip side is that an
+    element with no content and no size takes no space at all — give a spacer its own \`height\`. (The 50px box
+    empty containers show on the builder canvas is a drop target, scoped to it; it never reaches a widget.)
   - 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
@@ -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": [
@@ -248,6 +355,13 @@ connects that source to a descendant's field.
 The tool returns \`rendered: false\` with \`errors: [{ path, message, hint }]\`. Read the hint, fix that one op, and
 retry — you never lose the rest of the batch.
 `;
+/** The same two documents through the READ path (the router, hence plitzi_read), not only as MCP resources: an
+*  agent that reaches for the batch-read tool — the reflex the guide itself teaches — must not be told its own
+*  authoring guide does not exist. Space-independent, like the core singletons. */
+var readRenderResource = (uri) => {
+	if (uri === "plitzi://render/guide") return envelope(renderGuideText);
+	if (uri === "plitzi://render/types") return envelope(renderTypes());
+};
 var registerRenderResources = (server, log) => {
 	server.registerResource("Render guide", RENDER_GUIDE_URI, {
 		description: "How to author a plitzi_render widget: operations, element types, styling, examples.",
@@ -273,4 +387,4 @@ var registerRenderResources = (server, log) => {
 	});
 };
 //#endregion
-export { RENDER_GUIDE_URI, RENDER_TYPES_URI, registerRenderResources };
+export { RENDER_GUIDE_URI, RENDER_TYPES_URI, readRenderResource, registerRenderResources };

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

@@ -1,11 +1,15 @@
+import { emptySpace } from "../helpers/space.js";
+import "../helpers/uris.js";
 import { canonicalUri } from "./canonical.js";
 import { readCoreResource } from "./core.js";
 import { readPrimerResource } from "./primer.js";
+import { readRenderResource } from "./renderGuide.js";
 import { readSchemaResource } from "./schema.js";
 import { readStyleResource } from "./style.js";
 //#region src/modules/mcp/resources/router.ts
 var resolvers = [
 	(space, _env, uri) => readCoreResource(space, uri),
+	(_space, _env, uri) => readRenderResource(uri),
 	readPrimerResource,
 	readSchemaResource,
 	readStyleResource
@@ -19,7 +23,15 @@ var readResource = (space, env, rawUri) => {
 	}
 	return null;
 };
+/** What a connection carrying NO space (a guest / widgets-only grant) can still read: the space-independent
+*  singletons and the render docs. Undefined for everything else, so the caller says the connection has no space
+*  instead of answering out of an empty one — an empty page list would read as "this space has no pages". */
+var readPublicResource = (env, rawUri) => {
+	const uri = canonicalUri(env, rawUri);
+	if (uri === "plitzi://types") return;
+	return readRenderResource(uri) ?? readCoreResource(emptySpace(), uri);
+};
 /** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
 var resourceVersion = (space, env, uri) => readResource(space, env, uri)?.stateVersion ?? null;
 //#endregion
-export { readResource, resourceVersion };
+export { readPublicResource, readResource, resourceVersion };

package/dist/modules/mcp/server.js

@@ -1,6 +1,6 @@
 import { registerApps } from "./apps/index.js";
-import { emptySpace, emptySpaceMessage, unauthorizedSpaceMessage } from "./helpers/space.js";
-import { serverInstructions } from "./helpers/guide.js";
+import { NoSpaceError, emptySpace, emptySpaceMessage, noSpaceError } from "./helpers/space.js";
+import { serverInstructions, widgetsOnlyInstructions } from "./helpers/guide.js";
 import { createMcpLog } from "./helpers/log.js";
 import { registerResources } from "./resources/register.js";
 import { tools } from "./tools/index.js";
@@ -13,19 +13,20 @@ var asText = (data) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(data)
 }] });
-var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) => {
+var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger }) => {
 	const log = createMcpLog(logger);
-	let spaceIdPromise;
-	const requireSpaceId = () => spaceIdPromise ??= getSpaceId().then((id) => {
-		if (!id) throw new Error(unauthorizedSpaceMessage);
-		return id;
-	});
+	const spaceId = await getSpaceId().catch(() => void 0);
+	const hasSpace = spaceId !== void 0;
+	const requireSpaceId = () => {
+		if (spaceId === void 0) throw new NoSpaceError();
+		return spaceId;
+	};
 	const loadSpace = async () => {
-		const spaceId = await requireSpaceId();
+		const id = requireSpaceId();
 		const [schema, style, catalog] = await Promise.all([
-			adapters.getSchema?.(spaceId, MCP_ENV),
-			adapters.getStyle?.(spaceId, MCP_ENV),
-			adapters.getComponentCatalog?.(spaceId, MCP_ENV).catch(() => void 0)
+			adapters.getSchema?.(id, MCP_ENV),
+			adapters.getStyle?.(id, MCP_ENV),
+			adapters.getComponentCatalog?.(id, MCP_ENV).catch(() => void 0)
 		]);
 		if (!schema || !style) throw new Error(emptySpaceMessage);
 		return {
@@ -36,22 +37,22 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	};
 	const { saveSchema, saveStyle } = adapters;
 	const persisters = {
-		schema: saveSchema ? async (schema) => saveSchema(await requireSpaceId(), MCP_ENV, schema) : void 0,
-		style: saveStyle ? async (style) => saveStyle(await requireSpaceId(), MCP_ENV, style) : void 0
+		schema: saveSchema ? (schema) => saveSchema(requireSpaceId(), MCP_ENV, schema) : void 0,
+		style: saveStyle ? (style) => saveStyle(requireSpaceId(), MCP_ENV, style) : void 0
 	};
 	let spacePromise;
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.17"
-	}, { instructions: serverInstructions });
-	registerResources(server, getSpace, MCP_ENV, log);
+		version: "0.32.19"
+	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
+	registerResources(server, getSpace, MCP_ENV, log, hasSpace);
 	registerApps(server);
 	const toolContext = async () => ({
 		space: await getSpace(),
 		env: MCP_ENV,
 		persisters,
-		spaceId: await requireSpaceId(),
+		spaceId: requireSpaceId(),
 		preview,
 		screenshot
 	});
@@ -62,16 +63,27 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 		preview,
 		screenshot
 	});
+	const behaviorOf = (tool) => {
+		if (tool.spaceless) return (args) => tool.execute(args, spacelessContext());
+		if (hasSpace) return async (args) => tool.execute(args, await toolContext());
+		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
+	};
 	for (const tool of tools) {
 		if (tool.requires === "screenshot" && !screenshot) continue;
+		const behavior = behaviorOf(tool);
+		if (!behavior) continue;
 		const run = async (args) => {
 			const start = performance.now();
 			try {
-				const result = await tool.execute(args, tool.spaceless ? spacelessContext() : await toolContext());
+				const result = await behavior(args);
 				log.toolCall(tool.name, args, performance.now() - start);
 				return isCallToolResult(result) ? result : asText(result);
 			} catch (error) {
 				log.toolCall(tool.name, args, performance.now() - start, error);
+				if (error instanceof NoSpaceError) return asText({
+					error: noSpaceError,
+					message: error.message
+				});
 				throw error;
 			}
 		};

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"),

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

@@ -0,0 +1,148 @@
+import { elementInput, elementShape, position, styleRefs } from "../shared.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schema/elements/repeatElement.ts
+var item = z.record(z.string(), z.unknown());
+var MAX_ITEMS = 100;
+var MAX_ROWS = 500;
+var templateElement = z.lazy(() => z.object({
+	...elementShape,
+	children: z.array(templateElement).optional(),
+	repeat: z.object({
+		items: z.string().describe("The row field holding the sub-list, as \"{{item.<field>}}\" (or just the field path)"),
+		template: elementInput.describe("Rendered once per entry of that sub-list (a plain element tree)")
+	}).optional().describe("Makes THIS element the wrapper of a nested list — a list inside each row")
+}));
+var repeatElementOp = z.object({
+	type: z.literal("repeatElement"),
+	pageRef: z.string().describe("Page ref or id"),
+	ref: z.string().describe("Ref of the WRAPPER element this creates; the rows become its children"),
+	elementType: z.string().optional().describe("Type of the wrapper; defaults to container"),
+	label: z.string().optional(),
+	style: styleRefs.optional().describe("Classes for the wrapper — this is where the row/grid layout goes"),
+	parentRef: z.string().optional().describe("Anchor ref/id; defaults to page root"),
+	position: position.optional(),
+	template: templateElement.describe("The subtree ONE row renders, with {{item.field}} placeholders"),
+	items: z.array(item).min(1).max(MAX_ITEMS).describe("One object per row; its fields fill the {{item.field}} placeholders of the template")
+}).describe("Build a LIST from one template plus its `items` data, instead of repeating near-identical elements. Creates a wrapper whose children are the template rendered once per row. `{{item.<field>}}` is replaced by that row field — alone as the whole value it keeps the field type, mixed with text it interpolates. Every ref gets the row number appended (\"day\" → \"day-1\"), which is how you address a row later. A template node may carry `repeat: { items: \"{{item.<list>}}\", template: … }` to nest a list inside each row: it becomes the sub-list wrapper, refs number both levels (\"step-2-3\"), and `{{item.…}}` there reads the SUB-row. Other {{…}} names are untouched, so schema variables still work.");
+var PLACEHOLDER = /\{\{\s*item\.([A-Za-z0-9_.-]+)\s*\}\}/g;
+var WHOLE_PLACEHOLDER = /^\{\{\s*item\.([A-Za-z0-9_.-]+)\s*\}\}$/;
+var lookup = (row, path) => path.split(".").reduce((value, key) => {
+	if (value === null || typeof value !== "object") return;
+	return value[key];
+}, row);
+/** One string of the template, with its placeholders resolved. A placeholder that IS the whole string yields the
+*  field's own value (a number stays a number, an array stays an array); mixed text interpolates. */
+var fillString = (text, row) => {
+	const whole = WHOLE_PLACEHOLDER.exec(text);
+	if (whole) {
+		const value = lookup(row, whole[1]);
+		return value === void 0 ? {
+			value: text,
+			missing: whole[1]
+		} : { value };
+	}
+	let missing;
+	const value = text.replace(PLACEHOLDER, (match, path) => {
+		const found = lookup(row, path);
+		if (found === void 0) {
+			missing ??= path;
+			return match;
+		}
+		if (typeof found === "string") return found;
+		return typeof found === "number" || typeof found === "boolean" ? found.toString() : JSON.stringify(found);
+	});
+	return missing === void 0 ? { value } : {
+		value,
+		missing
+	};
+};
+var fillValue = (value, row, missing) => {
+	if (typeof value === "string") {
+		const filled = fillString(value, row);
+		if (filled.missing) missing.add(filled.missing);
+		return filled.value;
+	}
+	if (Array.isArray(value)) return value.map((entry) => fillValue(entry, row, missing));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, fillValue(entry, row, missing)]));
+	return value;
+};
+var listOf = (row, spec) => {
+	const whole = WHOLE_PLACEHOLDER.exec(spec);
+	const value = lookup(row, whole ? whole[1] : spec);
+	if (!Array.isArray(value)) return;
+	return value.map((entry) => entry !== null && typeof entry === "object" ? entry : { value: entry });
+};
+/** One template node against one row. `suffix` is the row numbering accumulated from the OUTSIDE in, so a nested
+*  row reads "step-2-3" (row 2, sub-row 3) rather than the other way round. */
+var expandNode = (node, row, suffix, state) => {
+	const { children, repeat, ...own } = node;
+	const filled = fillValue(own, row, state.missing);
+	const element = {
+		...filled,
+		ref: `${filled.ref}${suffix}`
+	};
+	if (repeat) {
+		const rows = listOf(row, repeat.items);
+		if (!rows) {
+			state.notAList.add(repeat.items);
+			return element;
+		}
+		const capped = rows.slice(0, MAX_ITEMS);
+		state.rows += capped.length;
+		element.children = capped.map((subRow, index) => expandNode(repeat.template, subRow, `${suffix}-${index + 1}`, state));
+		return element;
+	}
+	if (children) element.children = children.map((child) => expandNode(child, row, suffix, state));
+	return element;
+};
+var rowError = (index, message, hint) => ({
+	path: `items[${index}]`,
+	message,
+	hint
+});
+var keysOf = (row) => Object.keys(row).join(", ") || "(nothing)";
+/** Expand one repeat into the single upsertElement it stands for: the wrapper, with the template rendered once per
+*  row as its children. Returns the errors instead of throwing, so a bad row reads like every other op error. */
+var expandRepeat = (op) => {
+	const errors = [];
+	const children = [];
+	let total = op.items.length;
+	for (const [index, row] of op.items.entries()) {
+		const state = {
+			missing: /* @__PURE__ */ new Set(),
+			notAList: /* @__PURE__ */ new Set(),
+			rows: 0
+		};
+		const expanded = expandNode(op.template, row, `-${index + 1}`, state);
+		total += state.rows;
+		if (state.missing.size > 0) {
+			const fields = [...state.missing];
+			errors.push(rowError(index, `Row ${index + 1} has no ${fields.map((field) => `"${field}"`).join(", ")}`, `The template reads it as {{item.${fields[0]}}}. This row carries: ${keysOf(row)}`));
+			continue;
+		}
+		if (state.notAList.size > 0) {
+			const [spec] = [...state.notAList];
+			errors.push(rowError(index, `Row ${index + 1} has no list at ${spec}`, `A nested repeat needs an ARRAY in that field. This row carries: ${keysOf(row)}`));
+			continue;
+		}
+		children.push(expanded);
+	}
+	if (errors.length > 0) return { errors };
+	if (total > MAX_ROWS) return { errors: [{
+		path: "items",
+		message: `This repeat expands to ${total} rows (max ${MAX_ROWS})`,
+		hint: "Shorten the lists, or split the widget into several repeats."
+	}] };
+	return {
+		element: {
+			ref: op.ref,
+			type: op.elementType ?? "container",
+			...op.label === void 0 ? {} : { label: op.label },
+			...op.style === void 0 ? {} : { style: op.style },
+			children
+		},
+		errors
+	};
+};
+//#endregion
+export { expandRepeat, repeatElementOp };

package/dist/modules/mcp/tools/operations/schema/interactions/deleteInteraction.js

@@ -9,7 +9,7 @@ var deleteInteractionOp = z.object({
 	ref: z.string().describe("Element ref or id"),
 	flowId: z.string().optional().describe("Remove the whole flow with this id (the trigger node id)"),
 	nodeId: z.string().optional().describe("Remove a single step; its neighbors are re-linked. Deleting a trigger removes its flow")
-}).describe("DESTRUCTIVE, not undoable — remove an interaction flow (by flowId) or a single step (by nodeId). Provide exactly one. To merely turn a step OFF without removing it, use patchInteractionNode { enabled: false } instead. Confirm with the user before deleting.");
+}).describe("DESTRUCTIVE, not undoable — remove a flow (by flowId) or a single step (by nodeId); provide exactly one. To turn a step OFF instead, patchInteractionNode { enabled: false }. Confirm with the user first.");
 var removeFlow = (interactions, flowId) => {
 	let deleted = 0;
 	for (const [nodeId, node] of Object.entries(interactions)) if ((node.flowId || node.id) === flowId) {