@plitzi/sdk-server 0.32.17 → 0.32.19

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

@@ -18,7 +18,7 @@ var patchInteractionNodeOp = z.object({
 	when,
 	elementId,
 	preview
-}).describe("Partially update ONE step of an interaction flow (found by nodeId): only the fields you pass change; the flow order/links are untouched. This is how you DISABLE/deactivate a step without removing it: pass { enabled: false } (re-enable with { enabled: true }) — the step stays in the flow. Use deleteInteraction only to actually remove a step or a flow. Fails if the node does not exist.");
+}).describe("Partially update ONE step of a flow (found by nodeId): only the fields you pass change, the order/links are untouched. This is how you DISABLE a step without removing it — { enabled: false } keeps it in the flow. deleteInteraction is for actually removing one. Fails if the node does not exist.");
 var patchInteractionNode = (space, env, op) => {
 	const found = resolveElement(space, env, op.pageRef, op.ref);
 	if ("error" in found) return found.error;

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

@@ -11,7 +11,7 @@ var upsertInteractionFlowOp = z.object({
 	ref: z.string().describe("Element ref or id"),
 	flowId: z.string().optional().describe("Existing flow to replace (the trigger node id). Omit to create a new flow"),
 	nodes: z.array(interactionNode).min(1).describe("Ordered steps of the flow: the FIRST must be a trigger, the rest run after it in order")
-}).describe("Create or replace one interaction flow on an element from an ordered list of steps. The stored beforeNode/afterNode/flowId links are computed for you — pass the steps in execution order. For a globalCallback (addNotification, setState, navigate, auth*, *CollectionRecord) OMIT elementId: it is registered on a source module, not the host element, and the MCP sets the right source and fills the default param values for you. To edit a single step in place use patchInteractionNode.");
+}).describe("Create or replace one interaction flow on an element from an ordered list of steps — pass them in execution order, the beforeNode/afterNode/flowId links are computed for you. For a globalCallback OMIT elementId: it is registered on a source module, not the host element, and the source and default params are filled in for you. To edit a single step in place use patchInteractionNode.");
 var upsertInteractionFlow = (space, env, op) => {
 	const found = resolveElement(space, env, op.pageRef, op.ref);
 	if ("error" in found) return found.error;

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

@@ -4,6 +4,7 @@ import { upsertBindingOp } from "./bindings/upsertBinding.js";
 import { deleteElementOp } from "./elements/deleteElement.js";
 import { moveElementOp } from "./elements/moveElement.js";
 import { patchElementOp } from "./elements/patchElement.js";
+import { repeatElementOp } from "./elements/repeatElement.js";
 import { upsertElementOp } from "./elements/upsertElement.js";
 import { deleteFolderOp } from "./folders/deleteFolder.js";
 import { upsertFolderOp } from "./folders/upsertFolder.js";
@@ -18,6 +19,7 @@ import { upsertVariableOp } from "./variables/upsertVariable.js";
 //#region src/modules/mcp/tools/operations/schema/operations.ts
 var elementOps = {
 	upsertElement: upsertElementOp,
+	repeatElement: repeatElementOp,
 	patchElement: patchElementOp,
 	deleteElement: deleteElementOp,
 	moveElement: moveElementOp,

package/dist/modules/mcp/tools/operations/schema/pages/upsertPage.js

@@ -8,7 +8,7 @@ var upsertPageOp = z.object({
 	type: z.literal("upsertPage"),
 	ref: z.string().describe("Page id/slug to update, or a new id you choose to create one. On a new page it is stored as its idRef: starts with a letter, then letters, numbers, hyphens and underscores (\"pricing\"), unique across the space."),
 	label: z.string().optional(),
-	slug: z.string().optional().describe("The page URL path, RELATIVE — do NOT start it with \"/\" (the runtime and any parent folder slugs prepend the path; a leading \"/\" is stripped). Good practice: always set one on create for a clean, stable route, e.g. \"pricing\" or \"posts/:postId\" (a \":name\" segment is a route param, readable as {{name}} and as the source navigation.routeParams.name). Omitted on create → the page ref is used as the slug."),
+	slug: z.string().optional().describe("The page URL path, RELATIVE — never start it with \"/\" (parent folder slugs prepend it; a leading \"/\" is stripped). Set one on create for a stable route: \"pricing\", \"posts/:postId\". A \":name\" segment is a route param, readable as {{name}} and as navigation.routeParams.name. Omitted → the page ref is used."),
 	folder: z.string().nullable().optional().describe("Ref of an existing folder to place this page in; \"\" or null moves it to the root. Unknown → error"),
 	default: z.boolean().optional(),
 	enabled: z.boolean().optional().describe("false disables the page in the published SDK runtime (not routable/accessible to end users); it stays editable here. Defaults to true")

package/dist/modules/mcp/tools/operations/schema/shared.js

@@ -60,14 +60,17 @@ var initialStateInput = z.object({
 	styleVariant: styleVariantInput.optional().describe("Variant each attached class uses: { className: { base|slot: variantName | [names] } }"),
 	visibility: z.boolean().optional().describe("Initial visibility of the element")
 });
-var elementInput = z.lazy(() => z.object({
-	ref: z.string().describe("Semantic id you choose, or an existing element ref/id. On a new element this is stored as its idRef and becomes the key everything else addresses it by — its data source is named `<type>_<ref>`, and an interaction targets it by this ref. Start with a letter, then letters, numbers, hyphens and underscores (\"hero-cta\" or \"food_item\"): a dot would break the `<type>_<idRef>.<field>` grammar (an underscore is fine — the first `_` separates the type from the idRef). Must be unique across the space."),
+var elementShape = {
+	ref: z.string().describe("Semantic id you choose, or an existing element ref/id. On a new element it becomes the idRef everything addresses it by: its data source is `<type>_<ref>`, and interactions target it by this ref. Letters, digits, `-` and `_`, starting with a letter — a dot would break the `<type>_<idRef>.<field>` grammar. Unique across the space."),
 	type: z.string().describe("Type from plitzi://types"),
 	label: z.string().optional(),
 	subType: z.string().optional(),
 	props: z.record(z.string(), z.unknown()).optional().describe("Full replacement on update"),
 	style: styleRefs.optional().describe("Definition refs per slot; style the element by attaching a definition"),
-	initialState: initialStateInput.optional().describe("Applied style variant(s) and initial visibility (see plitzi://guide styling)"),
+	initialState: initialStateInput.optional().describe("Applied style variant(s) and initial visibility (see plitzi://guide styling)")
+};
+var elementInput = z.lazy(() => z.object({
+	...elementShape,
 	children: z.array(elementInput).optional()
 }));
 var position = z.enum([
@@ -112,8 +115,8 @@ var interactionNode = z.object({
 	params: z.record(z.string(), z.unknown()).optional(),
 	enabled: z.boolean().optional(),
 	when: ruleGroup.optional().describe("QueryBuilder RuleGroup gating this step (validated structurally)"),
-	elementId: z.string().optional().describe("Element whose callback this step invokes; defaults to this element. Give its ref or its raw id — a raw id is normalised to the element idRef the runtime looks callbacks up by, and a target without an idRef is given one automatically."),
+	elementId: z.string().optional().describe("Element whose callback this step invokes; defaults to this element. Its ref or raw id — a raw id is normalised to the idRef the runtime looks callbacks up by, and a target without one is given it."),
 	preview: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
-export { bindingCategory, bindingInput, elementInput, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };
+export { bindingCategory, bindingInput, elementInput, elementShape, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };

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

@@ -0,0 +1,54 @@
+import { bindingInput, elementInput, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
+import { cssMap, cssPatchMap, definitionSlot, definitionSlotPatch, displayModeCss, displayModeCssPatch, themeValue } from "./style/shared.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/schemaIds.ts
+/** The op union is the tool input of plitzi_apply, plitzi_validate, plitzi_render AND plitzi_preview, and every
+*  host reads it as JSON Schema on tools/list — four copies of the same 30 operations in the model's context, on
+*  EVERY request of every conversation the server is connected to. It measured ~25k tokens PER TOOL (~100k in
+*  total), which dwarfs anything a widget payload ever costs.
+*
+*  Most of that weight is one subschema pasted over and over: an element tree appears in upsertElement,
+*  patchElement and both repeat templates; a breakpoint CSS block in every style op; a rule group in every binding
+*  and interaction step. Zod emits a named `definitions` entry (and `$ref`s to it) for any schema carrying an `id`
+*  in the global registry, so registering the shared ones here collapses those copies — without touching the ops,
+*  the tools, or the MCP SDK, whose own converter honours the registry (it is given no options otherwise).
+*
+*  An id only pays when the schema is REUSED: giving one to a subschema that appears once makes the listing bigger,
+*  because the `definitions` entry and the ref cost more than the single copy they replace (measured, and reverted).
+*
+*  The ids are the names the MODEL reads in the refs, so they are written for it: `Element`, not `ElementInput`.
+*  This runs once, at module load of the op vocabulary, so every conversion path benefits — the MCP tools list and
+*  the co-worker's own tool-schema converter alike. */
+var SHARED_SCHEMAS = [
+	[elementInput, "Element"],
+	[ruleGroup, "RuleGroup"],
+	[styleRefs, "StyleRefs"],
+	[initialStateInput, "InitialState"],
+	[styleVariantInput, "StyleVariant"],
+	[interactionNode, "InteractionNode"],
+	[bindingInput, "Binding"],
+	[position, "Position"],
+	[cssMap, "Css"],
+	[cssPatchMap, "CssPatch"],
+	[definitionSlot, "StyleSlot"],
+	[definitionSlotPatch, "StyleSlotPatch"],
+	[displayModeCss, "BreakpointCss"],
+	[displayModeCssPatch, "BreakpointCssPatch"],
+	[themeValue, "ThemeValue"]
+];
+var claimSchemaId = (schema, id) => {
+	const taken = z.globalRegistry._idmap.get(id);
+	if (taken !== void 0 && taken !== schema) {
+		z.globalRegistry.add(schema, { id: `Plitzi${id}` });
+		return;
+	}
+	z.globalRegistry.add(schema, { id });
+};
+/** Idempotent: the module can be imported more than once in a test run, and a schema that already carries its id
+*  is left alone (re-adding the same one is harmless but pointless). Runs at module load, never per request — the
+*  MCP builds a server per request and this must not grow with them (pinned in the statelessness test). */
+var registerSharedSchemaIds = () => {
+	for (const [schema, id] of SHARED_SCHEMAS) if (z.globalRegistry.get(schema)?.id === void 0) claimSchemaId(schema, id);
+};
+//#endregion
+export { claimSchemaId, registerSharedSchemaIds };

package/dist/modules/mcp/tools/operations/style/definitions/patchDefinition.js

@@ -1,8 +1,8 @@
 import { defUri, defsUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
 import { definitionToAI } from "../translator.js";
-import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { patchCssShape } from "../shared.js";
+import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/definitions/patchDefinition.ts
 var patchDefinitionOp = z.object({

package/dist/modules/mcp/tools/operations/style/definitions/upsertDefinition.js

@@ -1,7 +1,7 @@
 import { defUri, defsUri } from "../../../../helpers/uris.js";
 import { empty } from "../../../../helpers/opResult.js";
-import { guardKind, writeStyleItem } from "../write.js";
 import { upsertCssShape } from "../shared.js";
+import { guardKind, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/definitions/upsertDefinition.ts
 var upsertDefinitionOp = z.object({

package/dist/modules/mcp/tools/operations/style/definitions/upsertDefinitions.js

@@ -0,0 +1,40 @@
+import { defUri, defsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { upsertCssShape } from "../shared.js";
+import { guardKind, writeStyleItem } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/definitions/upsertDefinitions.ts
+var definitionBody = z.object(upsertCssShape);
+var upsertDefinitionsOp = z.object({
+	type: z.literal("upsertDefinitions"),
+	definitions: z.record(z.string(), definitionBody).describe("Every class keyed by the class name you choose (kebab-case); the value is that class CSS")
+}).describe("Create or fully replace SEVERAL style classes in ONE operation — identical to a run of upsertDefinition, minus the repeated envelope, so prefer it whenever a batch declares more than one class. Apply each by attaching its name to an element via style.base. Use patchDefinition to change only some CSS of one class.");
+/** Writes each entry exactly as {@link upsertDefinition} would. Entries are independent: one bad class reports its
+*  own error under `definitions.<ref>` and the rest still write — nothing is persisted while the batch carries
+*  errors, so a partial write cannot escape. */
+var upsertDefinitions = (space, env, op) => {
+	const result = {
+		...empty(),
+		staleResources: [defsUri(env)]
+	};
+	const errors = [];
+	for (const [ref, { slots, ...base }] of Object.entries(op.definitions)) {
+		const guard = guardKind(space.style, ref, "class");
+		if (guard?.errors) {
+			errors.push(...guard.errors.map((error) => ({
+				...error,
+				path: `definitions.${ref}`
+			})));
+			continue;
+		}
+		writeStyleItem(space.style, ref, base, slots, "class", void 0);
+		result.updated += 1;
+		result.staleResources.push(defUri(env, ref));
+	}
+	return errors.length > 0 ? {
+		...result,
+		errors
+	} : result;
+};
+//#endregion
+export { upsertDefinitions, upsertDefinitionsOp };

package/dist/modules/mcp/tools/operations/style/globalStyles/patchGlobalStyle.js

@@ -1,8 +1,8 @@
 import { globalUri, globalsUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
 import { globalStyleToAI } from "../translator.js";
-import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { patchCssShape } from "../shared.js";
+import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/globalStyles/patchGlobalStyle.ts
 var patchGlobalStyleOp = z.object({

package/dist/modules/mcp/tools/operations/style/globalStyles/upsertGlobalStyle.js

@@ -1,7 +1,7 @@
 import { globalUri, globalsUri } from "../../../../helpers/uris.js";
 import { empty } from "../../../../helpers/opResult.js";
-import { guardKind, writeStyleItem } from "../write.js";
 import { upsertCssShape } from "../shared.js";
+import { guardKind, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/globalStyles/upsertGlobalStyle.ts
 var upsertGlobalStyleOp = z.object({

package/dist/modules/mcp/tools/operations/style/idStyles/patchIdStyle.js

@@ -1,8 +1,8 @@
 import { idUri, idsUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
 import { idStyleToAI } from "../translator.js";
-import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { patchCssShape } from "../shared.js";
+import { guardKind, mergePatch, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/idStyles/patchIdStyle.ts
 var patchIdStyleOp = z.object({

package/dist/modules/mcp/tools/operations/style/idStyles/upsertIdStyle.js

@@ -1,7 +1,7 @@
 import { idUri, idsUri } from "../../../../helpers/uris.js";
 import { empty } from "../../../../helpers/opResult.js";
-import { guardKind, writeStyleItem } from "../write.js";
 import { upsertCssShape } from "../shared.js";
+import { guardKind, writeStyleItem } from "../write.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/style/idStyles/upsertIdStyle.ts
 var upsertIdStyleOp = z.object({

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

@@ -1,6 +1,7 @@
 import { deleteDefinitionOp } from "./definitions/deleteDefinition.js";
 import { patchDefinitionOp } from "./definitions/patchDefinition.js";
 import { upsertDefinitionOp } from "./definitions/upsertDefinition.js";
+import { upsertDefinitionsOp } from "./definitions/upsertDefinitions.js";
 import { deleteGlobalStyleOp } from "./globalStyles/deleteGlobalStyle.js";
 import { patchGlobalStyleOp } from "./globalStyles/patchGlobalStyle.js";
 import { upsertGlobalStyleOp } from "./globalStyles/upsertGlobalStyle.js";
@@ -12,6 +13,7 @@ import { upsertStyleVariableOp } from "./variables/upsertStyleVariable.js";
 //#region src/modules/mcp/tools/operations/style/operations.ts
 var styleOps = {
 	upsertDefinition: upsertDefinitionOp,
+	upsertDefinitions: upsertDefinitionsOp,
 	patchDefinition: patchDefinitionOp,
 	deleteDefinition: deleteDefinitionOp,
 	upsertGlobalStyle: upsertGlobalStyleOp,

package/dist/modules/mcp/tools/operations/style/shared.js

@@ -56,4 +56,4 @@ var patchCssShape = {
 	slots: z.record(z.string(), definitionSlotPatch).optional()
 };
 //#endregion
-export { displayModeCss, displayModeCssPatch, patchCssShape, styleCategory, themeValue, upsertCssShape };
+export { cssMap, cssPatchMap, definitionSlot, definitionSlotPatch, displayModeCss, displayModeCssPatch, patchCssShape, styleCategory, themeValue, upsertCssShape };

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

@@ -1,5 +1,7 @@
+import { noSpaceError, unauthorizedSpaceMessage } from "../helpers/space.js";
 import { resourceErrorMessage } from "../resources/canonical.js";
-import { readResource } from "../resources/router.js";
+import { RENDER_GUIDE_URI, RENDER_TYPES_URI } from "../resources/renderGuide.js";
+import { readPublicResource, readResource } from "../resources/router.js";
 import { defineTool } from "./shared/tool.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/read.ts
@@ -21,13 +23,29 @@ var read = (input, space, env) => {
 		};
 	}) };
 };
+var publicHint = `Readable on this connection: ${RENDER_GUIDE_URI}, ${RENDER_TYPES_URI}, plitzi://guide, plitzi://css-properties. Everything else lives in a space this connection has none of.`;
+var readPublic = (input, env) => ({ results: input.uris.map((uri) => {
+	const found = readPublicResource(env, uri);
+	if (found) return {
+		uri,
+		stateVersion: found.stateVersion,
+		data: found.data
+	};
+	return {
+		uri,
+		error: noSpaceError,
+		message: unauthorizedSpaceMessage,
+		hint: publicHint
+	};
+}) });
 var readTool = defineTool({
 	name: "plitzi_read",
 	title: "Batch read",
 	description: "Batch-fetch resource content for URIs you ALREADY HOLD (from plitzi_search or a write response) — the tool form of opening MCP resources, for many at once. Pass an array of URIs (pages, elements, definitions, variables) and get them all in one call. NOT for finding things: to locate an element by label/type use plitzi_search; to browse what exists, list the plitzi:// resources. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch. Never hand-build a URI to guess your way to an element — search for it.",
 	inputShape: readShape,
 	access: "read",
-	run: (input, ctx) => read(input, ctx.space, ctx.env)
+	run: (input, ctx) => read(input, ctx.space, ctx.env),
+	runPublic: readPublic
 });
 //#endregion
-export { read, readShape, readTool };
+export { read, readPublic, readShape, readTool };

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

@@ -2,9 +2,12 @@ import { RENDER_APP_URI } from "../apps/render/index.js";
 import { emptySpace } from "../helpers/space.js";
 import { operations } from "./operations/index.js";
 import { applyOperations } from "./apply/dispatch.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";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
 import { validateSchema } from "@plitzi/sdk-schema/helpers/schemaValidator";
 import { generateCache } from "@plitzi/sdk-style/StyleHelper";
 //#region src/modules/mcp/tools/render.ts
@@ -32,16 +35,26 @@ var seedSpace = () => {
 	return space;
 };
 var noWarnings = (warnings) => warnings.length > 0 ? warnings : void 0;
-var renderShape = { operations };
+var renderShape = {
+	operations,
+	patch: z.boolean().optional().describe("Set true to CHANGE a widget you already rendered instead of rebuilding it: send its `renderId` and ONLY the operations that differ (patchDefinition, patchElement, deleteElement, a new repeatElement…). The widget merges them into the batch it was built from and reports back what it applied. The refs it already has (card-1, blk-2-3) are the ones to address. If that widget cannot be recovered — a surface that renders none, a host that keeps no storage — the answer says so and you re-send the whole batch."),
+	renderId: z.string().optional().describe("Handle returned by a previous render. Required with patch:true; it names the widget being changed.")
+};
 var render = (input) => {
 	const space = seedSpace();
-	const validation = validateOperations(space, input.operations);
+	const expansion = expandOperations(input.operations);
+	if (expansion.errors.length > 0) return {
+		rendered: false,
+		errors: expansion.errors
+	};
+	const ops = expansion.operations;
+	const validation = validateOperations(space, ops);
 	if (!validation.valid) return {
 		rendered: false,
 		errors: validation.errors,
 		warnings: noWarnings(validation.warnings)
 	};
-	const outcome = applyOperations(space, "main", input.operations);
+	const outcome = applyOperations(space, "main", ops);
 	if (outcome.errors.length > 0) return {
 		rendered: false,
 		errors: outcome.errors,
@@ -57,7 +70,7 @@ var render = (input) => {
 		})),
 		warnings: noWarnings(validation.warnings)
 	};
-	const audit = auditResources(space, input.operations);
+	const audit = auditResources(space, ops);
 	const warnings = [...validation.warnings, ...audit.warnings];
 	if (audit.errors.length > 0) return {
 		rendered: false,
@@ -67,6 +80,7 @@ var render = (input) => {
 	space.style.cache = generateCache(space.style);
 	return {
 		rendered: true,
+		operations: ops,
 		rootRef: HOST_PAGE_REF,
 		elementCount: Object.keys(space.schema.flat).length - 1,
 		offlineData: {
@@ -76,7 +90,53 @@ var render = (input) => {
 		warnings: noWarnings(warnings)
 	};
 };
-var toRenderResult = (res) => {
+/** A patch is not rendered here — it CANNOT be: this server keeps nothing between calls (no session, no store,
+*  any replica answers any request), so the previous widget only exists on the host side. The delta therefore
+*  travels as a courier result: the model pays for the delta alone, the view recovers the batch that widget was
+*  built from (by renderId — see apps/render/heldBatch.ts), merges, and re-calls this same tool with the whole
+*  thing over the host bridge, never through the model's context, then reports back with ui/update-model-context.
+*
+*  The renderId is the explicit handle the MCP RC asks for in place of implicit session state: the model carries
+*  it, so a patch names the widget it means and any replica can serve it.
+*
+*  Validation is not skipped, only deferred: the re-call carries the full batch, so refs, integrity and the audit
+*  all run exactly as they do on a first render, and their errors reach the model through that report. */
+var toPatchResult = (ops, renderId) => {
+	if (ops.length === 0) return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			patch: false,
+			error: "A patch carries no operations",
+			hint: "Send the operations that differ from the widget on screen, or drop `patch` to render a new one."
+		})
+	}] };
+	if (renderId === void 0) return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			patch: false,
+			error: "A patch needs the renderId of the widget it changes",
+			hint: "Pass the renderId the render answered with, or drop `patch` to render a new widget."
+		})
+	}] };
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				patch: true,
+				renderId,
+				operations: ops.length,
+				note: "Handed to the widget; it will report what it applied. If nothing reports back, it could not be recovered — re-send the full batch without patch."
+			})
+		}],
+		structuredContent: {
+			patch: true,
+			renderId,
+			operations: ops
+		}
+	};
+};
+var newRenderId = () => `r${randomUUID().slice(0, 8)}`;
+var toRenderResult = (res, renderId) => {
 	if (!res.rendered) return { content: [{
 		type: "text",
 		text: JSON.stringify({
@@ -87,6 +147,7 @@ var toRenderResult = (res) => {
 	}] };
 	const summary = {
 		rendered: true,
+		renderId,
 		rootRef: res.rootRef,
 		elementCount: res.elementCount,
 		warnings: res.warnings
@@ -98,19 +159,20 @@ var toRenderResult = (res) => {
 		}],
 		structuredContent: {
 			...summary,
-			offlineData: res.offlineData
+			offlineData: res.offlineData,
+			operations: res.operations
 		}
 	};
 };
 var renderTool = defineTool({
 	name: "plitzi_render",
 	title: "Render widget",
-	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n2. STYLE — declare reusable classes with upsertDefinition { ref, desktop:{ …CSS props in kebab-case… } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Watch the SDK defaults: every container has min-width/min-height 50px (set them to \"0\" for rails, dividers, dots and any flex child that must shrink), and heading/paragraph keep the browser's own margins (zero them and space with the parent's gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nReturns a compact summary (the widget is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
+	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look (not per property), and never hand-draw a scene in a data: URI — it costs more than the whole widget; use an https image, a flat colour or a gradient.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,
 	ui: { resourceUri: RENDER_APP_URI },
-	run: (input) => toRenderResult(render(input))
+	run: (input) => input.patch === true ? toPatchResult(input.operations, input.renderId) : toRenderResult(render(input), input.renderId ?? newRenderId())
 });
 //#endregion
 export { render, renderShape, renderTool };

package/dist/modules/mcp/tools/shared/expandOperations.js

@@ -0,0 +1,44 @@
+import { expandRepeat } from "../operations/schema/elements/repeatElement.js";
+//#region src/modules/mcp/tools/shared/expandOperations.ts
+/** Rewrites the sugar ops into the vocabulary the rest of the pipeline knows, BEFORE validation — today that is
+*  `repeatElement`, which stands for the `upsertElement` its template + rows expand to. Everything downstream
+*  (validator, dispatch, audit, versions) therefore stays unaware of it, and a row that renders a bad element is
+*  reported by the ordinary element checks.
+*
+*  One op in, one op out: the indices the agent sent are the indices every error path names, so `operations[3]`
+*  still means the fourth operation it wrote. */
+var expandOperations = (ops) => {
+	if (!ops.some((op) => op.type === "repeatElement")) return {
+		operations: ops,
+		errors: []
+	};
+	const operations = [];
+	const errors = [];
+	for (const [index, op] of ops.entries()) {
+		if (op.type !== "repeatElement") {
+			operations.push(op);
+			continue;
+		}
+		const expanded = expandRepeat(op);
+		if (!expanded.element) {
+			errors.push(...expanded.errors.map((error) => ({
+				...error,
+				path: `operations[${index}].${error.path}`
+			})));
+			continue;
+		}
+		operations.push({
+			type: "upsertElement",
+			pageRef: op.pageRef,
+			element: expanded.element,
+			...op.parentRef === void 0 ? {} : { parentRef: op.parentRef },
+			...op.position === void 0 ? {} : { position: op.position }
+		});
+	}
+	return {
+		operations,
+		errors
+	};
+};
+//#endregion
+export { expandOperations };

package/dist/modules/mcp/tools/shared/tool.js

@@ -13,16 +13,21 @@ var imageResult = (images, meta) => ({ content: [{
 /** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
 *  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.
 *  Adding a tool is: call defineTool in its own file and append it to the `tools` registry. */
-var defineTool = (spec) => ({
-	name: spec.name,
-	title: spec.title,
-	description: spec.description,
-	inputShape: spec.inputShape,
-	access: spec.access,
-	requires: spec.requires,
-	spaceless: spec.spaceless,
-	ui: spec.ui,
-	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
-});
+var defineTool = (spec) => {
+	const { runPublic } = spec;
+	const parse = (args) => z.object(spec.inputShape).parse(args);
+	return {
+		name: spec.name,
+		title: spec.title,
+		description: spec.description,
+		inputShape: spec.inputShape,
+		access: spec.access,
+		requires: spec.requires,
+		spaceless: spec.spaceless,
+		ui: spec.ui,
+		execute: (args, ctx) => spec.run(parse(args), ctx),
+		...runPublic ? { executePublic: (args, env) => runPublic(parse(args), env) } : {}
+	};
+};
 //#endregion
 export { defineTool, imageResult };

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

@@ -78,6 +78,9 @@ var collectTouched = (ops) => {
 		case "patchDefinition":
 			touched.definitions.add(op.ref);
 			break;
+		case "upsertDefinitions":
+			for (const ref of Object.keys(op.definitions)) touched.definitions.add(ref);
+			break;
 		case "upsertGlobalStyle":
 		case "patchGlobalStyle":
 			touched.globalStyles.add(op.componentType);

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

@@ -16,13 +16,22 @@ var batchDeclaredFolders = (ops) => {
 	for (const op of ops) if (op.type === "upsertFolder") refs.add(op.ref);
 	return refs;
 };
+var variantNamesOf = (source) => {
+	const names = new Set(Object.keys(source.variants ?? {}));
+	for (const slot of Object.values(source.slots ?? {})) for (const name of Object.keys(slot.variants ?? {})) names.add(name);
+	return names;
+};
 var batchDeclaredVariants = (ops) => {
 	const map = /* @__PURE__ */ new Map();
+	const record = (ref, names) => {
+		if (names.size > 0) map.set(ref, /* @__PURE__ */ new Set([...map.get(ref) ?? [], ...names]));
+	};
 	for (const op of ops) {
-		if (op.type !== "upsertDefinition" && op.type !== "patchDefinition") continue;
-		const names = new Set(Object.keys(op.variants ?? {}));
-		for (const slot of Object.values(op.slots ?? {})) for (const name of Object.keys(slot.variants ?? {})) names.add(name);
-		if (names.size > 0) map.set(op.ref, /* @__PURE__ */ new Set([...map.get(op.ref) ?? [], ...names]));
+		if (op.type === "upsertDefinitions") {
+			for (const [ref, definition] of Object.entries(op.definitions)) record(ref, variantNamesOf(definition));
+			continue;
+		}
+		if (op.type === "upsertDefinition" || op.type === "patchDefinition") record(op.ref, variantNamesOf(op));
 	}
 	return map;
 };

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

@@ -96,6 +96,21 @@ var validateOperations = (space, ops) => {
 				checkVariantApplication(op.initialState, `${base}.initialState`, ctx);
 				break;
 			}
+			case "upsertDefinitions": {
+				const entries = Object.entries(op.definitions);
+				if (entries.length === 0) ctx.errors.push({
+					path: `${base}.definitions`,
+					message: "This operation declares no classes",
+					hint: "Key each class by its name: { \"definitions\": { \"card\": { \"desktop\": { … } } } }"
+				});
+				for (const [ref, { slots, ...slot }] of entries) {
+					const entry = `${base}.definitions.${ref}`;
+					checkRef(ref, entry, ctx);
+					checkSlotCss(slot, entry, ctx);
+					for (const [slotName, slotDef] of Object.entries(slots ?? {})) checkSlotCss(slotDef, `${entry}.slots.${slotName}`, ctx);
+				}
+				break;
+			}
 			case "upsertDefinition":
 			case "patchDefinition": {
 				const { type, ref, slots, ...slot } = op;