@plitzi/sdk-server 0.32.16 → 0.32.18

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) {

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/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.\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). 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 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 };