@plitzi/sdk-server 0.32.5 → 0.32.7

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

@@ -1,18 +1,51 @@
-import { generateObjectId } from "../../../helpers/space.js";
+import { findElementByRef, findPageByRef, generateObjectId, indexAddElement, indexReRefElement, resolveRef, spaceIndex } from "../../../helpers/space.js";
+import { folderUri, foldersUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../../../helpers/uris.js";
+import { fail } from "../../../helpers/opResult.js";
+import { isValidIdRef, makeIdRef } from "@plitzi/sdk-schema/helpers/idRef";
 //#region src/modules/mcp/tools/operations/schema/write.ts
-var pageUri = (env, ref) => `plitzi://schema/${env}/pages/${ref}`;
-var pagesUri = (env) => `plitzi://schema/${env}/pages`;
-var foldersUri = (env) => `plitzi://folders/${env}`;
-var folderUri = (env, ref) => `plitzi://folders/${env}/${ref}`;
-var schemaVarsUri = (env) => `plitzi://schema-variables/${env}`;
-var removeFromParent = (space, childId) => {
-	for (const el of Object.values(space.schema.flat)) if (el.definition.items?.includes(childId)) el.definition.items = el.definition.items.filter((id) => id !== childId);
+var ID_REF_HINT = "Start with a letter, then letters, numbers, hyphens and underscores (e.g. \"hero-cta\" or \"food_item\"). The ref becomes the element idRef, which the runtime embeds in source names like `apiContainer_<idRef>.field` and in interaction targets — a dot would split those paths (an underscore is fine: the FIRST `_` separates the type from the idRef, and element types carry none, so extra underscores are unambiguous).";
+var TAKEN_HINT = "An idRef must be unique across the space — pick a different ref, or address the existing element by this ref.";
+/** Every ref in an element input tree (the element plus its nested children) — each becomes a new element's idRef. */
+var collectInputRefs = (input) => [input.ref, ...(input.children ?? []).flatMap(collectInputRefs)];
+/** Validate a ref that is about to become an element's idRef: the charset, then whether anything already answers
+*  to it. The charset rule is sdk-schema's `isValidIdRef` — never a regex restated here, so the MCP cannot drift
+*  from what the builder and the schema validator enforce.
+*
+*  Uniqueness is checked with the ref lookups rather than `FlatMap.idRefConflict`, and deliberately so: these are
+*  a superset of it. FlatMap asks whether another element holds this idRef; the MCP must also refuse a ref that
+*  shadows a raw id or a page slug, because its handlers resolve refs through those too — calling both would just
+*  run the same rule twice. Null when the ref is usable.
+*
+*  Enforced here, at every point a ref BECOMES an idRef — addressing an existing element by its raw id is not
+*  charset-checked, which is why the validator cannot simply tighten its own REF_RE for every ref it sees. */
+var guardNewRef = (space, ref, field) => {
+	if (!isValidIdRef(ref)) return fail(field, `"${ref}" is not a valid idRef`, ID_REF_HINT);
+	if (findElementByRef(space.schema, ref) || findPageByRef(space.schema, ref)) return fail(field, `"${ref}" is already used by another element in this space`, TAKEN_HINT);
+	return null;
+};
+var removeFromParent = (space, child) => {
+	const parent = child.definition.parentId ? space.schema.flat[child.definition.parentId] : void 0;
+	if (parent?.definition.items) parent.definition.items = parent.definition.items.filter((id) => id !== child.id);
 };
 var placeChild = (parent, childId, index) => {
 	const items = parent.definition.items ?? (parent.definition.items = []);
 	if (index === void 0 || index < 0 || index >= items.length) items.push(childId);
 	else items.splice(index, 0, childId);
 };
+var writeInitialState = (el, input, merge) => {
+	const current = el.definition.initialState ?? {};
+	const next = { ...current };
+	if (input.styleVariant !== void 0) if (merge) {
+		const merged = { ...current.styleVariant };
+		for (const [cls, selectors] of Object.entries(input.styleVariant)) merged[cls] = {
+			...merged[cls],
+			...selectors
+		};
+		next.styleVariant = merged;
+	} else next.styleVariant = input.styleVariant;
+	if (input.visibility !== void 0) next.visibility = input.visibility;
+	el.definition.initialState = next;
+};
 var createElement = (space, page, input, parent, index) => {
 	const id = generateObjectId();
 	const { subType, ...props } = {
@@ -21,8 +54,9 @@ var createElement = (space, page, input, parent, index) => {
 	};
 	const styleSelectors = { base: (input.style?.base ?? []).join(" ") };
 	for (const [slot, classes] of Object.entries(input.style?.slots ?? {})) styleSelectors[slot] = classes.join(" ");
-	space.schema.flat[id] = {
+	const el = {
 		id,
+		idRef: input.ref,
 		attributes: subType === void 0 ? props : {
 			subType,
 			...props
@@ -33,12 +67,43 @@ var createElement = (space, page, input, parent, index) => {
 			label: input.label ?? input.ref,
 			type: input.type,
 			items: [],
-			styleSelectors,
-			aiRef: input.ref
+			styleSelectors
 		}
 	};
+	space.schema.flat[id] = el;
 	placeChild(parent, id, index);
-	for (const child of input.children ?? []) createElement(space, page, child, space.schema.flat[id], void 0);
+	indexAddElement(space.schema, el, page.id);
+	if (input.initialState) writeInitialState(el, input.initialState, false);
+	for (const child of input.children ?? []) createElement(space, page, child, el, void 0);
+};
+/** The idRef an element is wired by, minting one when it has none. Interactions are keyed by idRef, so an element
+*  that is about to host or be targeted by a flow must have one — rather than make the agent assign it with a
+*  separate patchElement, the MCP gives it a free `<type>-<n>` ref (unique across the space) and proceeds. An
+*  element that already has an idRef keeps it. Mutates the element in place and returns the ref. */
+var ensureIdRef = (space, el) => {
+	if (el.idRef) return el.idRef;
+	const index = spaceIndex(space.schema);
+	el.idRef = makeIdRef(el.definition.type, (candidate) => index.elementByRef.has(candidate) || index.pageByRef.has(candidate));
+	indexReRefElement(space.schema, el);
+	return el.idRef;
+};
+/** The key an interaction node must store to reach a target element. Every ref field also accepts a raw id, so a
+*  target given as an id is resolved to the element's idRef — the key the runtime registers callbacks under. A
+*  target that has no idRef is given one (see `ensureIdRef`), since it must be reachable to be wired to. A target
+*  that resolves to no element is left as written — it is already a ref, or a key only a plugin knows. */
+var resolveTargetRef = (space, elementId) => {
+	const el = space.schema.flat[elementId] ?? findElementByRef(space.schema, elementId);
+	return el ? ensureIdRef(space, el) : elementId;
+};
+/** Resolve a non-page element within a page for the element-scoped ops (bindings, interactions). Returns the
+*  element, or a teachable OpResult when the page or element ref does not resolve — so each op reports the same
+*  errors as patchElement without repeating them. */
+var resolveElement = (space, env, pageRef, ref) => {
+	const page = findPageByRef(space.schema, pageRef);
+	if (!page) return { error: fail("pageRef", `Page "${pageRef}" not found`, `Read plitzi://schema/${env}/pages for valid refs`) };
+	const el = resolveRef(space.schema, page, ref);
+	if (!el || el.id === page.id) return { error: fail("ref", `Element "${ref}" not found in page "${pageRef}"`, "Use an existing element ref or id") };
+	return { el };
 };
 //#endregion
-export { createElement, folderUri, foldersUri, pageUri, pagesUri, placeChild, removeFromParent, schemaVarsUri };
+export { ID_REF_HINT, collectInputRefs, createElement, ensureIdRef, folderUri, foldersUri, guardNewRef, pageUri, pagesUri, placeChild, removeFromParent, resolveElement, resolveTargetRef, schemaVarsUri, settingsUri, writeInitialState };

package/dist/modules/mcp/tools/operations/style/{deleteDefinition.js → definitions/deleteDefinition.js}

@@ -1,7 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { MODES, defUri, defsUri, guardKind } from "./write.js";
+import { defUri, defsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { MODES, guardKind } from "../write.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/deleteDefinition.ts
+//#region src/modules/mcp/tools/operations/style/definitions/deleteDefinition.ts
 var deleteDefinitionOp = z.object({
 	type: z.literal("deleteDefinition"),
 	ref: z.string().describe("Class ref of the definition to delete")

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

@@ -1,9 +1,10 @@
-import { empty, fail } from "../../../helpers/opResult.js";
-import { definitionToAI } from "./translator.js";
-import { defUri, defsUri, guardKind, mergePatch, writeStyleItem } from "./write.js";
-import { patchCssShape } from "./shared.js";
+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 { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/patchDefinition.ts
+//#region src/modules/mcp/tools/operations/style/definitions/patchDefinition.ts
 var patchDefinitionOp = z.object({
 	type: z.literal("patchDefinition"),
 	ref: z.string().describe("Existing class ref to patch"),

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

@@ -1,8 +1,9 @@
-import { empty } from "../../../helpers/opResult.js";
-import { defUri, defsUri, guardKind, writeStyleItem } from "./write.js";
-import { upsertCssShape } from "./shared.js";
+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 { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/upsertDefinition.ts
+//#region src/modules/mcp/tools/operations/style/definitions/upsertDefinition.ts
 var upsertDefinitionOp = z.object({
 	type: z.literal("upsertDefinition"),
 	ref: z.string().describe("Class name you choose (kebab-case), or an existing class ref to fully replace"),

package/dist/modules/mcp/tools/operations/style/{deleteGlobalStyle.js → globalStyles/deleteGlobalStyle.js}

@@ -1,7 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { MODES, globalUri, globalsUri, guardKind } from "./write.js";
+import { globalUri, globalsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { MODES, guardKind } from "../write.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/deleteGlobalStyle.ts
+//#region src/modules/mcp/tools/operations/style/globalStyles/deleteGlobalStyle.ts
 var deleteGlobalStyleOp = z.object({
 	type: z.literal("deleteGlobalStyle"),
 	componentType: z.string().describe("Element type whose site-wide style to remove")

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

@@ -1,9 +1,10 @@
-import { empty, fail } from "../../../helpers/opResult.js";
-import { globalStyleToAI } from "./translator.js";
-import { globalUri, globalsUri, guardKind, mergePatch, writeStyleItem } from "./write.js";
-import { patchCssShape } from "./shared.js";
+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 { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/patchGlobalStyle.ts
+//#region src/modules/mcp/tools/operations/style/globalStyles/patchGlobalStyle.ts
 var patchGlobalStyleOp = z.object({
 	type: z.literal("patchGlobalStyle"),
 	componentType: z.string().describe("Element type whose global style to merge into; affects ALL of that type"),

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

@@ -1,8 +1,9 @@
-import { empty } from "../../../helpers/opResult.js";
-import { globalUri, globalsUri, guardKind, writeStyleItem } from "./write.js";
-import { upsertCssShape } from "./shared.js";
+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 { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/upsertGlobalStyle.ts
+//#region src/modules/mcp/tools/operations/style/globalStyles/upsertGlobalStyle.ts
 var upsertGlobalStyleOp = z.object({
 	type: z.literal("upsertGlobalStyle"),
 	componentType: z.string().describe("Element type to style site-wide (e.g. \"button\"); affects ALL of that type"),

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

@@ -0,0 +1,21 @@
+import { idUri, idsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { MODES, guardKind } from "../write.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/idStyles/deleteIdStyle.ts
+var deleteIdStyleOp = z.object({
+	type: z.literal("deleteIdStyle"),
+	targetId: z.string().describe("DOM id whose id rule to remove (without the # prefix)")
+}).describe("Remove the id rule (`#id`) for a single element (the element keeps its own classes).");
+var deleteIdStyle = (space, env, op) => {
+	const guard = guardKind(space.style, op.targetId, "id");
+	if (guard) return guard;
+	for (const mode of MODES) Reflect.deleteProperty(space.style.platform[mode], op.targetId);
+	return {
+		...empty(),
+		deleted: 1,
+		staleResources: [idUri(env, op.targetId), idsUri(env)]
+	};
+};
+//#endregion
+export { deleteIdStyle, deleteIdStyleOp };

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

@@ -0,0 +1,28 @@
+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 { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/idStyles/patchIdStyle.ts
+var patchIdStyleOp = z.object({
+	type: z.literal("patchIdStyle"),
+	targetId: z.string().describe("DOM id whose id rule to merge into (without the # prefix)"),
+	...patchCssShape
+}).describe("Partially update the CSS of an id rule (`#id`): CSS is merged (a null value removes a property). Never creates — use upsertIdStyle for that.");
+var patchIdStyle = (space, env, op) => {
+	const guard = guardKind(space.style, op.targetId, "id");
+	if (guard) return guard;
+	const existing = idStyleToAI(space.style, op.targetId);
+	if (!existing) return fail("targetId", `No id rule for "${op.targetId}"`, "patchIdStyle only updates an existing id rule; use upsertIdStyle to create one");
+	const { type, targetId, slots: slotsPatch, ...basePatch } = op;
+	const { base, slots } = mergePatch(existing, basePatch, slotsPatch);
+	writeStyleItem(space.style, targetId, base, slots, "id", void 0);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [idUri(env, targetId), idsUri(env)]
+	};
+};
+//#endregion
+export { patchIdStyle, patchIdStyleOp };

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

@@ -0,0 +1,24 @@
+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 { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/idStyles/upsertIdStyle.ts
+var upsertIdStyleOp = z.object({
+	type: z.literal("upsertIdStyle"),
+	targetId: z.string().describe("DOM id of the element to style (without the # prefix); matches its `id` attribute"),
+	...upsertCssShape
+}).describe("Create or fully replace the CSS for a single element addressed by its DOM id (`#id`). The element must carry that `id` attribute. To style by reusable class instead, use upsertDefinition. Use patchIdStyle for a partial change.");
+var upsertIdStyle = (space, env, op) => {
+	const { type, targetId, slots, ...base } = op;
+	const guard = guardKind(space.style, targetId, "id");
+	if (guard) return guard;
+	writeStyleItem(space.style, targetId, base, slots, "id", void 0);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [idUri(env, targetId), idsUri(env)]
+	};
+};
+//#endregion
+export { upsertIdStyle, upsertIdStyleOp };

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

@@ -1,11 +1,14 @@
-import { deleteDefinitionOp } from "./deleteDefinition.js";
-import { deleteGlobalStyleOp } from "./deleteGlobalStyle.js";
-import { deleteStyleVariableOp } from "./deleteStyleVariable.js";
-import { patchDefinitionOp } from "./patchDefinition.js";
-import { patchGlobalStyleOp } from "./patchGlobalStyle.js";
-import { upsertDefinitionOp } from "./upsertDefinition.js";
-import { upsertGlobalStyleOp } from "./upsertGlobalStyle.js";
-import { upsertStyleVariableOp } from "./upsertStyleVariable.js";
+import { deleteDefinitionOp } from "./definitions/deleteDefinition.js";
+import { patchDefinitionOp } from "./definitions/patchDefinition.js";
+import { upsertDefinitionOp } from "./definitions/upsertDefinition.js";
+import { deleteGlobalStyleOp } from "./globalStyles/deleteGlobalStyle.js";
+import { patchGlobalStyleOp } from "./globalStyles/patchGlobalStyle.js";
+import { upsertGlobalStyleOp } from "./globalStyles/upsertGlobalStyle.js";
+import { deleteIdStyleOp } from "./idStyles/deleteIdStyle.js";
+import { patchIdStyleOp } from "./idStyles/patchIdStyle.js";
+import { upsertIdStyleOp } from "./idStyles/upsertIdStyle.js";
+import { deleteStyleVariableOp } from "./variables/deleteStyleVariable.js";
+import { upsertStyleVariableOp } from "./variables/upsertStyleVariable.js";
 //#region src/modules/mcp/tools/operations/style/operations.ts
 var styleOps = {
 	upsertDefinition: upsertDefinitionOp,
@@ -14,6 +17,9 @@ var styleOps = {
 	upsertGlobalStyle: upsertGlobalStyleOp,
 	patchGlobalStyle: patchGlobalStyleOp,
 	deleteGlobalStyle: deleteGlobalStyleOp,
+	upsertIdStyle: upsertIdStyleOp,
+	patchIdStyle: patchIdStyleOp,
+	deleteIdStyle: deleteIdStyleOp,
 	upsertStyleVariable: upsertStyleVariableOp,
 	deleteStyleVariable: deleteStyleVariableOp
 };

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

@@ -38,6 +38,18 @@ var projectItem = (style, ref, accept) => {
 	return found ? def : void 0;
 };
 var definitionToAI = (style, ref) => projectItem(style, ref, isClassDefinition);
+var definitionVariantNames = (style, ref) => {
+	const def = definitionToAI(style, ref);
+	if (!def) return;
+	const result = {};
+	const baseVariants = Object.keys(def.variants ?? {});
+	if (baseVariants.length > 0) result.base = baseVariants.sort();
+	for (const [slot, slotDef] of Object.entries(def.slots ?? {})) {
+		const variants = Object.keys(slotDef.variants ?? {});
+		if (variants.length > 0) result[slot] = variants.sort();
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
 var globalStylesForType = (style, componentType) => {
 	const isGlobal = (item) => item.type === "element" && item.componentType === componentType;
 	const refs = /* @__PURE__ */ new Set();
@@ -64,6 +76,18 @@ var globalStyleTypes = (style) => {
 	for (const mode of DISPLAY_MODES) for (const item of Object.values(style.platform[mode])) if (item.type === "element" && item.componentType) types.add(item.componentType);
 	return Array.from(types).sort();
 };
+var idStyleIds = (style) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const mode of DISPLAY_MODES) for (const [name, item] of Object.entries(style.platform[mode])) if (item.type === "id") ids.add(name);
+	return Array.from(ids).sort();
+};
+var idStyleToAI = (style, targetId) => {
+	const def = projectItem(style, targetId, (item) => item.type === "id");
+	return def ? {
+		...def,
+		targetId
+	} : void 0;
+};
 var styleVariablesToAI = (style) => {
 	const data = {};
 	for (const [category, group] of Object.entries(style.variables)) data[category] = Object.entries(group).map(([name, value]) => ({
@@ -74,4 +98,4 @@ var styleVariablesToAI = (style) => {
 	return data;
 };
 //#endregion
-export { definitionRefs, definitionToAI, globalStyleToAI, globalStyleTypes, globalStylesForType, isClassDefinition, styleVariablesToAI };
+export { definitionRefs, definitionToAI, definitionVariantNames, globalStyleToAI, globalStyleTypes, globalStylesForType, idStyleIds, idStyleToAI, isClassDefinition, styleVariablesToAI };

package/dist/modules/mcp/tools/operations/style/{deleteStyleVariable.js → variables/deleteStyleVariable.js}

@@ -1,8 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { styleVarUri, styleVarsUri } from "./write.js";
-import { styleCategory } from "./shared.js";
+import { styleVarUri, styleVarsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { styleCategory } from "../shared.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/deleteStyleVariable.ts
+//#region src/modules/mcp/tools/operations/style/variables/deleteStyleVariable.ts
 var deleteStyleVariableOp = z.object({
 	type: z.literal("deleteStyleVariable"),
 	category: styleCategory,

package/dist/modules/mcp/tools/operations/style/{upsertStyleVariable.js → variables/upsertStyleVariable.js}

@@ -1,8 +1,8 @@
-import { empty } from "../../../helpers/opResult.js";
-import { styleVarUri, styleVarsUri } from "./write.js";
-import { styleCategory, themeValue } from "./shared.js";
+import { styleVarUri, styleVarsUri } from "../../../../helpers/uris.js";
+import { empty } from "../../../../helpers/opResult.js";
+import { styleCategory, themeValue } from "../shared.js";
 import { z } from "zod";
-//#region src/modules/mcp/tools/operations/style/upsertStyleVariable.ts
+//#region src/modules/mcp/tools/operations/style/variables/upsertStyleVariable.ts
 var upsertStyleVariableOp = z.object({
 	type: z.literal("upsertStyleVariable"),
 	category: styleCategory,

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

@@ -1,5 +1,6 @@
+import { expandShorthand } from "../../../catalogs/cssCatalog.js";
+import { defUri, defsUri, globalUri, globalsUri, idUri, idsUri, styleVarUri, styleVarsUri } from "../../../helpers/uris.js";
 import { fail } from "../../../helpers/opResult.js";
-import { expandShorthand } from "./cssCatalog.js";
 import processSelector from "@plitzi/sdk-style/helpers/processSelector";
 //#region src/modules/mcp/tools/operations/style/write.ts
 var MODES = [
@@ -7,18 +8,25 @@ var MODES = [
 	"tablet",
 	"mobile"
 ];
-var defUri = (env, ref) => `plitzi://definitions/${env}/${ref}`;
-var defsUri = (env) => `plitzi://definitions/${env}`;
-var globalUri = (env, componentType) => `plitzi://global-styles/${env}/${componentType}`;
-var globalsUri = (env) => `plitzi://global-styles/${env}`;
-var styleVarUri = (env, category) => `plitzi://style-variables/${env}/${category}`;
-var styleVarsUri = (env) => `plitzi://style-variables/${env}`;
-var describeKind = (item) => item.type === "element" ? `a global style for every "${item.componentType}" element` : item.type === "class" ? "a reusable class definition" : "an id rule";
+var KIND_LABEL = {
+	class: "a reusable class definition",
+	element: "a global style for an element type",
+	id: "an id rule targeting a single element"
+};
+var KIND_TOOL = {
+	class: "upsertDefinition/patchDefinition",
+	element: "upsertGlobalStyle/patchGlobalStyle",
+	id: "upsertIdStyle/patchIdStyle"
+};
+var KIND_FIELD = {
+	class: "ref",
+	element: "componentType",
+	id: "targetId"
+};
 var guardKind = (style, ref, want) => {
 	const clash = MODES.map((mode) => style.platform[mode][ref]).find((item) => item !== void 0 && item.type !== want);
 	if (!clash) return null;
-	const wantIsClass = want === "class";
-	return fail(wantIsClass ? "ref" : "componentType", `"${ref}" is already ${describeKind(clash)}; it cannot be edited as ${wantIsClass ? "a class definition" : "a global element style"}`, wantIsClass ? "To restyle every element of a type on purpose, use upsertGlobalStyle/patchGlobalStyle with its componentType. Otherwise pick a different class name." : "That name is a class definition — edit it with upsertDefinition/patchDefinition, or choose a different componentType.");
+	return fail(KIND_FIELD[want], `"${ref}" is already ${KIND_LABEL[clash.type]}; it cannot be edited as ${KIND_LABEL[want]}`, `Edit it with ${KIND_TOOL[clash.type]}, or choose a different ${KIND_FIELD[want]}.`);
 };
 var slotToBlocks = (slot) => {
 	const perMode = {};
@@ -97,4 +105,4 @@ var mergePatch = (existing, basePatch, slotsPatch) => {
 	};
 };
 //#endregion
-export { MODES, defUri, defsUri, globalUri, globalsUri, guardKind, mergePatch, styleVarUri, styleVarsUri, writeStyleItem };
+export { MODES, defUri, defsUri, globalUri, globalsUri, guardKind, idUri, idsUri, mergePatch, styleVarUri, styleVarsUri, writeStyleItem };

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

@@ -24,7 +24,7 @@ var read = (input, space, env) => {
 var readTool = defineTool({
 	name: "plitzi_read",
 	title: "Batch read",
-	description: "Read MANY resources at once by URI — the batch alternative to opening resources one by one. Pass an array of URIs (pages, elements, definitions, variables), e.g. the ready-made uris from plitzi_search or a write response, and get them all back in a single call instead of one read per URI. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch.",
+	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)

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

@@ -0,0 +1,114 @@
+import { emptySpace } from "../helpers/space.js";
+import { operations } from "./operations/index.js";
+import { applyOperations } from "./apply/dispatch.js";
+import { defineTool } from "./shared/tool.js";
+import { validateOperations } from "./shared/validator/index.js";
+import { auditResources } from "./shared/validator/audit.js";
+import { validateSchema } from "@plitzi/sdk-schema";
+import { generateCache } from "@plitzi/sdk-style";
+//#region src/modules/mcp/tools/render.ts
+var HOST_PAGE_REF = "render";
+var seedSpace = () => {
+	const space = emptySpace();
+	space.schema.definition.name = "Widget";
+	space.schema.flat[HOST_PAGE_REF] = {
+		id: HOST_PAGE_REF,
+		idRef: HOST_PAGE_REF,
+		attributes: {
+			slug: "",
+			name: "Render",
+			default: true
+		},
+		definition: {
+			rootId: HOST_PAGE_REF,
+			label: "Page",
+			type: "page",
+			items: [],
+			styleSelectors: { base: "" }
+		}
+	};
+	space.schema.pages = [HOST_PAGE_REF];
+	return space;
+};
+var noWarnings = (warnings) => warnings.length > 0 ? warnings : void 0;
+var renderShape = { operations };
+var render = (input) => {
+	const space = seedSpace();
+	const validation = validateOperations(space, input.operations);
+	if (!validation.valid) return {
+		rendered: false,
+		errors: validation.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const outcome = applyOperations(space, "main", input.operations);
+	if (outcome.errors.length > 0) return {
+		rendered: false,
+		errors: outcome.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const integrity = validateSchema(space.schema);
+	if (!integrity.valid) return {
+		rendered: false,
+		errors: integrity.errors.map((error) => ({
+			path: error.elementId ? `schema.${error.elementId}` : "schema",
+			message: error.message,
+			hint: "The authored widget is structurally inconsistent (broken parent/child link or a cycle)."
+		})),
+		warnings: noWarnings(validation.warnings)
+	};
+	const audit = auditResources(space, input.operations);
+	const warnings = [...validation.warnings, ...audit.warnings];
+	if (audit.errors.length > 0) return {
+		rendered: false,
+		errors: audit.errors,
+		warnings: noWarnings(warnings)
+	};
+	space.style.cache = generateCache(space.style);
+	return {
+		rendered: true,
+		rootRef: HOST_PAGE_REF,
+		elementCount: Object.keys(space.schema.flat).length - 1,
+		offlineData: {
+			schema: space.schema,
+			style: space.style
+		},
+		warnings: noWarnings(warnings)
+	};
+};
+var toRenderResult = (res) => {
+	if (!res.rendered) return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			rendered: false,
+			errors: res.errors,
+			warnings: res.warnings
+		})
+	}] };
+	const summary = {
+		rendered: true,
+		rootRef: res.rootRef,
+		elementCount: res.elementCount,
+		warnings: res.warnings
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(summary)
+		}],
+		structuredContent: {
+			...summary,
+			offlineData: res.offlineData
+		}
+	};
+};
+var renderTool = defineTool({
+	name: "plitzi_render",
+	title: "Render widget",
+	description: "Render a small self-contained UI widget the user can SEE, with the Plitzi SDK offline (no backend). Reach for it in two cases: (1) the user asks you to create/design/build/show a piece of UI (a card, hero, form, button, banner, pricing table…); (2) you are answering a content question and a visual layout communicates better than prose — render the ANSWER as a widget (a recipe as a card, a comparison as a table, steps as a checklist, a profile, a menu). Prefer showing it over a long text answer whenever the content is naturally visual. You author the widget as operations targeting the pre-seeded host page `pageRef: \"render\"` (same vocabulary as plitzi_apply: upsertElement, upsertDefinition, …). Returns a compact summary; the rendered widget is shown to the user. To edit an existing space page instead, use plitzi_preview.",
+	inputShape: renderShape,
+	access: "read",
+	spaceless: true,
+	run: (input) => toRenderResult(render(input))
+});
+//#endregion
+export { render, renderShape, renderTool };