@plitzi/sdk-server 0.32.4 → 0.32.6

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

@@ -0,0 +1,47 @@
+import { compoundLonghands, expandShorthand, isCssProperty, suggestCssProperty } from "../../../catalogs/cssCatalog.js";
+import { checkStyleVarRefs, checkVarRefs, warnOnce } from "./context.js";
+//#region src/modules/mcp/tools/shared/validator/css.ts
+var checkCss = (css, path, ctx) => {
+	if (!css) return;
+	const declared = {};
+	for (const [key, value] of Object.entries(css)) if (value !== null) declared[key] = value;
+	for (const [key, value] of Object.entries(expandShorthand(declared))) {
+		const longhands = compoundLonghands(key);
+		if (longhands) if (!isCssProperty(key)) ctx.errors.push({
+			path: `${path}.${key}`,
+			message: `Compound CSS shorthand "${key}" is not supported — write its atomic longhand properties`,
+			hint: `Use: ${longhands.join(", ")}. (Note: flex layout is display + flex-direction + flex-grow/shrink/basis, not "flex".)`,
+			validValues: longhands
+		});
+		else warnOnce(ctx, `CSS shorthand "${key}" at ${path}.${key} is accepted but stored as one compound value. Plitzi styling is atomic — prefer the longhands (${longhands.join(", ")}) so a breakpoint/state/variant can override each property independently.`);
+		else if (!isCssProperty(key)) {
+			const suggestion = suggestCssProperty(key);
+			ctx.errors.push({
+				path: `${path}.${key}`,
+				message: `Unknown CSS property "${key}"`,
+				hint: suggestion ? `Use the kebab-case key "${suggestion}"` : "Read plitzi://css-properties for the valid property keys"
+			});
+		}
+		if (typeof value === "string") {
+			checkStyleVarRefs(value, `${path}.${key}`, ctx);
+			checkVarRefs(value, `${path}.${key}`, ctx);
+		}
+	}
+};
+var checkSlotCss = (slot, path, ctx) => {
+	checkCss(slot.desktop, `${path}.desktop`, ctx);
+	checkCss(slot.tablet, `${path}.tablet`, ctx);
+	checkCss(slot.mobile, `${path}.mobile`, ctx);
+	for (const [state, dm] of Object.entries(slot.states ?? {})) {
+		checkCss(dm.desktop, `${path}.states.${state}.desktop`, ctx);
+		checkCss(dm.tablet, `${path}.states.${state}.tablet`, ctx);
+		checkCss(dm.mobile, `${path}.states.${state}.mobile`, ctx);
+	}
+	for (const [name, dm] of Object.entries(slot.variants ?? {})) {
+		checkCss(dm.desktop, `${path}.variants.${name}.desktop`, ctx);
+		checkCss(dm.tablet, `${path}.variants.${name}.tablet`, ctx);
+		checkCss(dm.mobile, `${path}.variants.${name}.mobile`, ctx);
+	}
+};
+//#endregion
+export { checkCss, checkSlotCss };

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

@@ -0,0 +1,55 @@
+import { definitionVariantNames } from "../../operations/style/translator.js";
+import { RAW_CODE_TYPES, checkVarRefs, warnOnce } from "./context.js";
+import { checkIdRef } from "./refs.js";
+//#region src/modules/mcp/tools/shared/validator/elements.ts
+var checkTypeProps = (type, props, path, ctx) => {
+	if (!props || RAW_CODE_TYPES.has(type)) return;
+	const meta = ctx.typeMeta.get(type);
+	const known = meta && meta.attributes.size > 0 ? meta.attributes : ctx.typeProps.get(type);
+	if (!known || known.size === 0) return;
+	const strict = meta?.custom === false;
+	for (const key of Object.keys(props)) {
+		if (key === "subType" || known.has(key)) continue;
+		if (strict) ctx.errors.push({
+			path,
+			message: `Type "${type}" has no attribute "${key}"`,
+			hint: `Valid attributes: ${[...known].sort().join(", ")}`,
+			validValues: [...known].sort()
+		});
+		else warnOnce(ctx, `Type "${type}" has no observed prop "${key}" at ${path} (known: ${[...known].sort().join(", ")}). It may still be valid — verify against plitzi://types.`);
+	}
+};
+var checkVariantApplication = (initialState, path, ctx) => {
+	for (const [cls, selectors] of Object.entries(initialState?.styleVariant ?? {})) {
+		const declared = definitionVariantNames(ctx.style, cls);
+		const batch = ctx.batchVariants.get(cls);
+		for (const [selector, variant] of Object.entries(selectors)) {
+			const names = Array.isArray(variant) ? variant : [variant];
+			for (const name of names) if (!((declared?.[selector]?.includes(name) ?? false) || (batch?.has(name) ?? false))) warnOnce(ctx, `Element applies variant "${name}" on class "${cls}" (${selector}) at ${path}, but that class defines no such variant${declared ? ` (declares: ${Object.entries(declared).map(([s, v]) => `${s}:${v.join("/")}`).join(", ")})` : ""}. Create it via upsertDefinition/patchDefinition "variants", or fix the name.`);
+		}
+	}
+};
+var checkElementProps = (element, path, ctx) => {
+	if (!element.props || RAW_CODE_TYPES.has(element.type)) return;
+	for (const [key, value] of Object.entries(element.props)) if (typeof value === "string") checkVarRefs(value, `${path}.props.${key}`, ctx);
+	checkTypeProps(element.type, element.props, path, ctx);
+};
+var checkElementInput = (element, path, ctx, seen) => {
+	checkIdRef(element.ref, `${path}.ref`, ctx);
+	if (seen.has(element.ref)) ctx.errors.push({
+		path: `${path}.ref`,
+		message: `Duplicate ref "${element.ref}" in this batch`,
+		hint: "Use a unique ref"
+	});
+	seen.add(element.ref);
+	if (!element.type) ctx.errors.push({
+		path: `${path}.type`,
+		message: "Element type is required",
+		hint: "Read plitzi://types for known types"
+	});
+	else if (!ctx.knownTypes.has(element.type)) ctx.warnings.push(`Type "${element.type}" was not seen in this space; ensure a plugin provides it (${path}.type).`);
+	checkElementProps(element, path, ctx);
+	element.children?.forEach((child, i) => checkElementInput(child, `${path}.children[${i}]`, ctx, seen));
+};
+//#endregion
+export { checkElementInput, checkTypeProps, checkVariantApplication };

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

@@ -0,0 +1,226 @@
+import { observedDataSources, observedInteractionActions } from "../../../catalogs/observed.js";
+import { buildTypeRegistry } from "../../../catalogs/registry.js";
+import { findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, getPageElements, pageFoldersOf, pageRefOf, resolveRef, routeParamNames } from "../../../helpers/space.js";
+import { MAX_OPS } from "../../operations/index.js";
+import { batchDeclaredFolders, batchDeclaredPages, batchDeclaredVariants, batchDeclaredVars } from "./batch.js";
+import { checkObservedName, checkVarRefs, warnOnce } from "./context.js";
+import { checkBindingSourceScope, checkBindingTarget, checkBindingTransformers } from "./bindings.js";
+import { checkSlotCss } from "./css.js";
+import { checkRef } from "./refs.js";
+import { checkElementInput, checkTypeProps, checkVariantApplication } from "./elements.js";
+import { checkInteractionNode } from "./interactions.js";
+//#region src/modules/mcp/tools/shared/validator/index.ts
+var STYLE_CATEGORIES = [
+	"color",
+	"spacing",
+	"shadow",
+	"custom"
+];
+var buildTypeMeta = (catalog) => {
+	const meta = /* @__PURE__ */ new Map();
+	for (const [type, entry] of Object.entries(catalog ?? {})) {
+		const bindingsAllowed = entry.bindingsAllowed;
+		meta.set(type, {
+			attributes: new Set(entry.attributes ?? []),
+			styleSelectors: new Set(entry.styleSelectors ?? []),
+			custom: entry.custom ?? false,
+			...bindingsAllowed ? { bindingTargets: {
+				attributes: new Set(bindingsAllowed.attributes ?? []),
+				initialState: new Set(bindingsAllowed.initialState ?? [])
+			} } : {}
+		});
+	}
+	return meta;
+};
+/** The shared validation context, derived from a space (+ the batch's ops, for batch-declared names). Extracted so
+*  the post-apply resource audit (auditResources) can run the same checks against the resulting draft. */
+var buildValidationCtx = (space, ops) => {
+	const registry = buildTypeRegistry(space.schema, space.catalog);
+	return {
+		errors: [],
+		warnings: [],
+		warned: /* @__PURE__ */ new Set(),
+		knownTypes: new Set(Object.keys(registry.types)),
+		typeProps: new Map(Object.entries(registry.types).map(([type, info]) => [type, new Set(Object.keys(info.props))])),
+		typeMeta: buildTypeMeta(space.catalog),
+		elementType: (ref) => (findElementByRef(space.schema, ref) ?? findPageByRef(space.schema, ref))?.definition.type,
+		schemaVars: /* @__PURE__ */ new Set([
+			...space.schema.variables.map((v) => v.name),
+			...routeParamNames(space.schema),
+			...batchDeclaredVars(ops)
+		]),
+		styleVars: new Set(Object.values(space.style.variables).flatMap((group) => Object.keys(group))),
+		style: space.style,
+		batchVariants: batchDeclaredVariants(ops),
+		observedActions: observedInteractionActions(space.schema),
+		observedSources: observedDataSources(space.schema)
+	};
+};
+var validateOperations = (space, ops) => {
+	const batchPages = batchDeclaredPages(ops);
+	const batchFolders = batchDeclaredFolders(ops);
+	const folderRefs = () => pageFoldersOf(space.schema).map((f) => f.id);
+	const ctx = buildValidationCtx(space, ops);
+	if (ops.length > 1e3) ctx.errors.push({
+		path: "operations",
+		message: `Batch has ${ops.length} operations (max ${MAX_OPS})`,
+		hint: `Split into batches of at most ${MAX_OPS}`
+	});
+	ops.forEach((op, i) => {
+		const base = `operations[${i}]`;
+		if ((op.type === "upsertElement" || op.type === "patchElement" || op.type === "deleteElement" || op.type === "moveElement" || op.type === "upsertBinding" || op.type === "patchBinding" || op.type === "deleteBinding" || op.type === "upsertInteractionFlow" || op.type === "patchInteractionNode" || op.type === "deleteInteraction") && op.pageRef) {
+			if (!findPageByRef(space.schema, op.pageRef) && !batchPages.has(op.pageRef)) {
+				const validRefs = getPageElements(space.schema).map(pageRefOf);
+				ctx.errors.push({
+					path: `${base}.pageRef`,
+					message: `Page "${op.pageRef}" does not exist`,
+					hint: "Use an existing page ref, or create it with upsertPage earlier in the same batch",
+					validValues: validRefs
+				});
+			}
+		}
+		switch (op.type) {
+			case "upsertElement":
+				checkElementInput(op.element, `${base}.element`, ctx, /* @__PURE__ */ new Set());
+				checkVariantApplication(op.element.initialState, `${base}.element.initialState`, ctx);
+				break;
+			case "patchElement": {
+				checkRef(op.ref, `${base}.ref`, ctx);
+				const page = findPageByRef(space.schema, op.pageRef);
+				const target = page ? resolveRef(space.schema, page, op.ref) : void 0;
+				if (op.props) {
+					for (const [key, value] of Object.entries(op.props)) if (typeof value === "string") checkVarRefs(value, `${base}.props.${key}`, ctx);
+					if (target && target.id !== page?.id) checkTypeProps(target.definition.type, op.props, base, ctx);
+				}
+				checkVariantApplication(op.initialState, `${base}.initialState`, ctx);
+				break;
+			}
+			case "upsertDefinition":
+			case "patchDefinition": {
+				const { type, ref, slots, ...slot } = op;
+				checkRef(ref, `${base}.ref`, ctx);
+				checkSlotCss(slot, base, ctx);
+				for (const [slotName, slotDef] of Object.entries(slots ?? {})) checkSlotCss(slotDef, `${base}.slots.${slotName}`, ctx);
+				break;
+			}
+			case "upsertGlobalStyle":
+			case "patchGlobalStyle": {
+				const { type, componentType, slots, ...slot } = op;
+				checkRef(componentType, `${base}.componentType`, ctx);
+				checkSlotCss(slot, base, ctx);
+				for (const [slotName, slotDef] of Object.entries(slots ?? {})) checkSlotCss(slotDef, `${base}.slots.${slotName}`, ctx);
+				break;
+			}
+			case "deleteGlobalStyle":
+				checkRef(op.componentType, `${base}.componentType`, ctx);
+				break;
+			case "upsertPage":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				if (op.slug === void 0 && !findPageByRef(space.schema, op.ref)) warnOnce(ctx, `Page "${op.ref}" is being created without a slug. Set a slug for a clean, stable URL (good practice); the page ref is used as a fallback.`);
+				if (typeof op.folder === "string" && op.folder !== "") {
+					if (!findFolderByRef(space.schema, op.folder) && !batchFolders.has(op.folder)) ctx.errors.push({
+						path: `${base}.folder`,
+						message: `Folder "${op.folder}" does not exist`,
+						hint: "Create it with upsertFolder earlier in the same batch, or read plitzi://folders for valid refs",
+						validValues: folderRefs()
+					});
+				}
+				break;
+			case "upsertFolder":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				if (typeof op.parentId === "string") {
+					checkRef(op.parentId, `${base}.parentId`, ctx);
+					const parent = findFolderByRef(space.schema, op.parentId);
+					if (!parent && !batchFolders.has(op.parentId)) ctx.errors.push({
+						path: `${base}.parentId`,
+						message: `Parent folder "${op.parentId}" does not exist`,
+						hint: "Create the parent with upsertFolder first, or read plitzi://folders for valid refs",
+						validValues: folderRefs()
+					});
+					const selfId = findFolderByRef(space.schema, op.ref)?.id ?? op.ref;
+					if ((parent?.id ?? op.parentId) === selfId || parent && folderAncestorIds(pageFoldersOf(space.schema), parent.id).includes(selfId)) ctx.errors.push({
+						path: `${base}.parentId`,
+						message: `Folder "${op.ref}" cannot be nested under itself or one of its descendants`,
+						hint: "Choose a parent that is not this folder or below it"
+					});
+				}
+				break;
+			case "deleteDefinition":
+			case "deleteFolder":
+			case "deletePage":
+			case "upsertVariable":
+			case "deleteVariable":
+				checkRef("ref" in op ? op.ref : op.name, `${base}.${"ref" in op ? "ref" : "name"}`, ctx);
+				break;
+			case "upsertStyleVariable":
+			case "deleteStyleVariable":
+				if (!STYLE_CATEGORIES.includes(op.category)) ctx.errors.push({
+					path: `${base}.category`,
+					message: `Unknown style-variable category "${op.category}"`,
+					hint: "Use one of the valid categories",
+					validValues: STYLE_CATEGORIES
+				});
+				break;
+			case "upsertBinding":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				checkObservedName(op.binding.source, ctx.observedSources, "Data source", "plitzi://data-sources", `${base}.binding.source`, ctx);
+				checkBindingTarget(op.ref, op.category, op.binding.to, `${base}.binding.to`, ctx);
+				checkBindingSourceScope(space, ctx, op.ref, op.binding.source, `${base}.binding.source`);
+				checkBindingTransformers(op.binding.transformers, `${base}.binding.transformers`, ctx);
+				break;
+			case "patchBinding":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				checkObservedName(op.source, ctx.observedSources, "Data source", "plitzi://data-sources", `${base}.source`, ctx);
+				checkBindingTarget(op.ref, op.category, op.to, `${base}.to`, ctx);
+				if (op.source !== void 0) checkBindingSourceScope(space, ctx, op.ref, op.source, `${base}.source`);
+				checkBindingTransformers(op.transformers, `${base}.transformers`, ctx);
+				break;
+			case "deleteBinding":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				break;
+			case "upsertInteractionFlow":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				if (op.nodes[0] && op.nodes[0].nodeType !== "trigger") ctx.errors.push({
+					path: `${base}.nodes[0].nodeType`,
+					message: "The first node of a flow must be a trigger",
+					hint: "Put the trigger first; the callbacks/utilities that run after it follow in order"
+				});
+				op.nodes.forEach((node, n) => checkInteractionNode(node, `${base}.nodes[${n}]`, ctx, op.ref));
+				break;
+			case "patchInteractionNode": {
+				checkRef(op.ref, `${base}.ref`, ctx);
+				const existing = findElementByRef(space.schema, op.ref)?.definition.interactions?.[op.nodeId];
+				if (existing) checkInteractionNode({
+					id: existing.id,
+					title: op.title ?? existing.title,
+					nodeType: existing.type,
+					action: op.action ?? existing.action,
+					params: {
+						...existing.params,
+						...op.params ?? {}
+					},
+					enabled: op.enabled ?? existing.enabled,
+					elementId: op.elementId ?? existing.elementId ?? void 0
+				}, base, ctx, op.ref);
+				else checkObservedName(op.action, ctx.observedActions, "Interaction action", "plitzi://interactions", `${base}.action`, ctx);
+				break;
+			}
+			case "deleteInteraction":
+				checkRef(op.ref, `${base}.ref`, ctx);
+				if (Boolean(op.flowId) === Boolean(op.nodeId)) ctx.errors.push({
+					path: `${base}.nodeId`,
+					message: "Provide exactly one of flowId or nodeId",
+					hint: "flowId removes a whole flow; nodeId removes a single step"
+				});
+				break;
+			default: break;
+		}
+	});
+	return {
+		valid: ctx.errors.length === 0,
+		errors: ctx.errors,
+		warnings: ctx.warnings
+	};
+};
+//#endregion
+export { buildValidationCtx, validateOperations };

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

@@ -0,0 +1,106 @@
+import { hiddenParams, invalidParams, missingRequiredParams, reconcileParams } from "../../../catalogs/paramSpec.js";
+import { getGlobalCallback } from "../../../catalogs/builtinCallbacks.js";
+import { getElementCallback } from "../../../catalogs/builtinElementCallbacks.js";
+import { getUtility } from "../../../catalogs/builtinUtilities.js";
+import { NULLISH_ELEMENT_IDS } from "../../../helpers/interactions.js";
+import { checkObservedName, warnOnce } from "./context.js";
+//#region src/modules/mcp/tools/shared/validator/interactions.ts
+var describeType = (type) => {
+	switch (type) {
+		case "boolean": return "a boolean";
+		case "number": return "a number";
+		case "select": return "one of its allowed values";
+		case "scalar": return "a string, number or boolean";
+		default: return "a string";
+	}
+};
+var checkParams = (label, action, params, spec, base, ctx) => {
+	const unknown = Object.keys(params).filter((key) => !(key in spec));
+	if (unknown.length > 0) warnOnce(ctx, `${label} "${action}" at ${base} got unknown param(s) ${unknown.map((k) => `"${k}"`).join(", ")} — these are dropped on apply. Valid params: ${Object.keys(spec).join(", ")}.`);
+	const effective = reconcileParams(params, spec, true);
+	const missing = missingRequiredParams(params, effective, spec);
+	if (missing.length > 0) warnOnce(ctx, `${label} "${action}" at ${base} is missing required param(s) ${missing.map((k) => `"${k}"`).join(", ")} — the step is malformed without them (see plitzi://interactions for what each does).`);
+	const hidden = hiddenParams(params, effective, spec);
+	if (hidden.length > 0) warnOnce(ctx, `${label} "${action}" at ${base}: param(s) ${hidden.map((k) => `"${k}"`).join(", ")} are ignored under the current params (they only apply when a companion param is set — see plitzi://interactions). Set the companion param or drop them.`);
+	for (const { key, expected, got, options } of invalidParams(params, effective, spec)) {
+		const detail = options ? ` Allowed values: ${options.join(", ")}.` : "";
+		ctx.errors.push({
+			path: `${base}.params.${key}`,
+			message: `${label} "${action}" at ${base}: param "${key}" must be ${describeType(expected)} but got ${got}.${detail}`,
+			hint: `Set "${key}" to ${describeType(expected)}.`,
+			...options ? { validValues: options } : {}
+		});
+	}
+};
+var checkGlobalCallback = (node, base, ctx) => {
+	const builtin = getGlobalCallback(node.action);
+	if (!builtin) {
+		if (getUtility(node.action)) warnOnce(ctx, `"${node.action}" at ${base} is a utility, not a global callback — use nodeType "utility".`);
+		else if (getElementCallback(node.action)) warnOnce(ctx, `"${node.action}" at ${base} is an element callback, not a global callback — use nodeType "callback" and set elementId to the element it acts on.`);
+		return;
+	}
+	if (node.elementId !== void 0 && node.elementId !== builtin.source) warnOnce(ctx, `Global callback "${node.action}" at ${base} is registered on "${builtin.source}", not on "${node.elementId}". Omit elementId (the MCP sets "${builtin.source}") or set it to "${builtin.source}".`);
+	if (node.params && builtin.strictParams) checkParams("Global callback", node.action, node.params, builtin.params, base, ctx);
+};
+var checkSetStateKey = (node, base, ctx, hostRef) => {
+	const key = node.params?.key;
+	if (typeof key !== "string" || key === "") return;
+	const targetRef = typeof node.elementId === "string" && node.elementId !== "" ? node.elementId : hostRef;
+	const type = ctx.elementType(targetRef);
+	const meta = type ? ctx.typeMeta.get(type) : void 0;
+	if (!meta) return;
+	const state = node.params?.category === "state";
+	const validKeys = state ? /* @__PURE__ */ new Set(["visibility", ...[...meta.styleSelectors].map((selector) => `styleSelectors.${selector}`)]) : meta.attributes;
+	if (validKeys.size === 0 || validKeys.has(key)) return;
+	const kind = state ? "state" : "attribute";
+	const valid = [...validKeys].sort();
+	const detail = `Element setState at ${base} sets ${kind} "${key}" on type "${type}", which has no such ${kind} key`;
+	if (!meta.custom) ctx.errors.push({
+		path: base,
+		message: detail,
+		hint: `Use one of: ${valid.join(", ")}`,
+		validValues: valid
+	});
+	else warnOnce(ctx, `${detail} (${valid.join(", ")}). It may still be valid — verify against plitzi://types.`);
+};
+var checkElementCallback = (node, base, ctx, hostRef) => {
+	const builtin = getElementCallback(node.action);
+	if (!builtin) {
+		if (getUtility(node.action)) warnOnce(ctx, `"${node.action}" at ${base} is a utility, not an element callback — use nodeType "utility".`);
+		else {
+			const global = getGlobalCallback(node.action);
+			if (global) warnOnce(ctx, `"${node.action}" at ${base} is a global callback (source "${global.source}"), not an element callback — use nodeType "globalCallback" and omit elementId.`);
+		}
+		return;
+	}
+	if (node.params && builtin.strictParams) checkParams("Element callback", node.action, node.params, builtin.params, base, ctx);
+	if (node.action === "setState") checkSetStateKey(node, base, ctx, hostRef);
+};
+var checkUtility = (node, base, ctx) => {
+	if (node.elementId && !NULLISH_ELEMENT_IDS.has(node.elementId)) warnOnce(ctx, `Utility "${node.action}" at ${base} has elementId "${node.elementId}" — a utility takes NO element (it is resolved by its action alone). Omit elementId; the MCP stores null. Pointing it at an element is a no-op.`);
+	const utility = getUtility(node.action);
+	if (!utility) {
+		if (getGlobalCallback(node.action)) warnOnce(ctx, `"${node.action}" at ${base} is a global callback, not a utility — use nodeType "globalCallback".`);
+		else if (getElementCallback(node.action)) warnOnce(ctx, `"${node.action}" at ${base} is an element callback, not a utility — use nodeType "callback".`);
+		return;
+	}
+	if (node.params && utility.strictParams) checkParams("Utility", node.action, node.params, utility.params, base, ctx);
+};
+var checkInteractionNode = (node, base, ctx, hostRef) => {
+	checkObservedName(node.action, ctx.observedActions, "Interaction action", "plitzi://interactions", `${base}.action`, ctx);
+	if (node.elementId === "undefined" || node.elementId === "null") warnOnce(ctx, `Node "${node.action}" at ${base} has the literal string elementId "${node.elementId}" — a stringified nullish value. Re-save the step: elementId must be a real element ref, a source module, or empty for a utility.`);
+	switch (node.nodeType) {
+		case "globalCallback":
+			checkGlobalCallback(node, base, ctx);
+			break;
+		case "callback":
+			checkElementCallback(node, base, ctx, hostRef);
+			break;
+		case "utility":
+			checkUtility(node, base, ctx);
+			break;
+		default: break;
+	}
+};
+//#endregion
+export { checkInteractionNode };

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

@@ -0,0 +1,28 @@
+import { isValidIdRef } from "@plitzi/sdk-schema/helpers/idRef";
+//#region src/modules/mcp/tools/shared/validator/refs.ts
+var REF_RE = /^[a-zA-Z0-9._-]+$/;
+var checkRef = (ref, path, ctx) => {
+	if (!ref || ref.trim().length === 0) {
+		ctx.errors.push({
+			path,
+			message: "Ref must not be empty",
+			hint: "Use a semantic name like \"hero.title\""
+		});
+		return;
+	}
+	if (!REF_RE.test(ref)) ctx.errors.push({
+		path,
+		message: `Ref "${ref}" has invalid characters`,
+		hint: "Allowed characters: letters, numbers, dot, hyphen, underscore"
+	});
+};
+var checkIdRef = (ref, path, ctx) => {
+	checkRef(ref, path, ctx);
+	if (ref && REF_RE.test(ref) && !isValidIdRef(ref)) ctx.errors.push({
+		path,
+		message: `Ref "${ref}" is not a valid idRef`,
+		hint: "Use only letters, numbers, hyphens and underscores (e.g. \"hero-cta\" or \"my_list_card\"). This ref becomes the element idRef, which the runtime embeds in source names like `apiContainer_<idRef>.field` and in interaction targets — a dot would break those paths."
+	});
+};
+//#endregion
+export { REF_RE, checkIdRef, checkRef };

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

@@ -0,0 +1,39 @@
+import { cloneSpace } from "../helpers/space.js";
+import { environment, 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";
+//#region src/modules/mcp/tools/validate.ts
+var validateShape = {
+	environment,
+	operations
+};
+var validate = (input, space) => {
+	const validation = validateOperations(space, input.operations);
+	if (!validation.valid) return validation;
+	const env = input.environment ?? "main";
+	const draft = cloneSpace(space);
+	const outcome = applyOperations(draft, env, input.operations);
+	if (outcome.errors.length > 0) return {
+		valid: false,
+		errors: outcome.errors,
+		warnings: validation.warnings
+	};
+	const audit = auditResources(draft, input.operations);
+	return {
+		valid: audit.errors.length === 0,
+		errors: audit.errors,
+		warnings: [...validation.warnings, ...audit.warnings]
+	};
+};
+var validateTool = defineTool({
+	name: "plitzi_validate",
+	title: "Validate",
+	description: "Check a batch of operations without executing them. Returns teachable errors and warnings — including any PRE-EXISTING malformation in a resource the batch touches (which blocks a save until fixed).",
+	inputShape: validateShape,
+	access: "read",
+	run: (input, ctx) => validate(input, ctx.space)
+});
+//#endregion
+export { validate, validateShape, validateTool };

package/dist/modules/ssr/buildBody.js

@@ -3,8 +3,8 @@ import { prepareRender } from "./prepareRender.js";
 import { renderToString } from "react-dom/server";
 import { jsx } from "react/jsx-runtime";
 //#region src/modules/ssr/buildBody.tsx
-var buildBody = async (req, config, spaceId, environment, revision, renderFn, pluginManager, offlineDataCache, metrics) => {
-	const prep = await prepareRender(req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics);
+var buildBody = async (req, config, spaceId, environment, revision, renderFn, pluginManager, offlineDataCache, metrics, offlineDataOverride) => {
+	const prep = await prepareRender(req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride);
 	const result = {};
 	const reactStart = metrics ? performance.now() : 0;
 	const html = renderToString(/* @__PURE__ */ jsx(Component, {

package/dist/modules/ssr/handler.js

@@ -1,6 +1,7 @@
 import { buildHtmlCacheKey } from "../../helpers/cache/keys.js";
-import { applySSRResult } from "./applySSRResult.js";
 import { buildBody } from "./buildBody.js";
+import { takeDraftOverride } from "./preview.js";
+import { applySSRResult } from "./applySSRResult.js";
 import { streamBody } from "./streamBody.js";
 import { RequestMetrics } from "../../helpers/metrics.js";
 //#region src/modules/ssr/handler.tsx
@@ -8,7 +9,8 @@ var renderSSR = async (req, res, config, renderFn, pluginManager, caches) => {
 	const { environment = "main", spaceId = 1, revision = 0 } = req.ctx.spaceDeployment || {};
 	const devMode = config.devMode ?? false;
 	res.setHeader("Content-Type", "text/html; charset=utf-8");
-	const htmlCache = environment !== "main" ? caches.html : void 0;
+	const offlineDataOverride = await takeDraftOverride(req, config);
+	const htmlCache = environment !== "main" && !offlineDataOverride ? caches.html : void 0;
 	const cacheKey = htmlCache ? buildHtmlCacheKey(req.ctx.user?.token, spaceId, environment, revision, req) : void 0;
 	if (htmlCache && cacheKey) {
 		const cached = htmlCache.get(cacheKey);
@@ -22,10 +24,10 @@ var renderSSR = async (req, res, config, renderFn, pluginManager, caches) => {
 	const metrics = devMode ? new RequestMetrics() : void 0;
 	if (cacheKey) res.setHeader("X-Cache", "MISS");
 	if (config.streaming) {
-		await streamBody(req, res, config, spaceId, environment, revision, renderFn, pluginManager, caches.offlineData, htmlCache, cacheKey, metrics);
+		await streamBody(req, res, config, spaceId, environment, revision, renderFn, pluginManager, caches.offlineData, htmlCache, cacheKey, metrics, offlineDataOverride);
 		return;
 	}
-	const { body, result } = await buildBody(req, config, spaceId, environment, revision, renderFn, pluginManager, caches.offlineData, metrics);
+	const { body, result } = await buildBody(req, config, spaceId, environment, revision, renderFn, pluginManager, caches.offlineData, metrics, offlineDataOverride);
 	if (metrics) {
 		res.setHeader("Server-Timing", metrics.toServerTimingHeader());
 		metrics.log(`${req.method} ${req.path}`);

package/dist/modules/ssr/prepareRender.js

@@ -1,16 +1,16 @@
-import { buildOfflineDataCacheKey } from "../../helpers/cache/keys.js";
 import { loadPluginComponents } from "./loadPluginComponents.js";
 import { registerExternalPlugins } from "./registerExternalPlugins.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
+import { buildOfflineDataCacheKey } from "../../helpers/cache/keys.js";
 import { escapeJson } from "../../helpers/escapeJson.js";
 import { readCookie } from "../../helpers/readCookie.js";
 //#region src/modules/ssr/prepareRender.tsx
-var prepareRender = async (req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics) => {
+var prepareRender = async (req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride) => {
 	const m = (name, fn) => metrics ? metrics.measure(name, fn) : Promise.resolve(fn());
 	const offlineCacheKey = environment !== "main" ? buildOfflineDataCacheKey(spaceId, environment, revision) : void 0;
-	const cachedOfflineStr = offlineCacheKey ? offlineDataCache?.get(offlineCacheKey) : void 0;
-	const [offlineData, server] = await Promise.all([cachedOfflineStr ? JSON.parse(cachedOfflineStr) : m("schema", () => config.adapters.getOfflineData(spaceId, environment, revision)), m("rsc", () => buildServerInfo(req, config))]);
-	if (!cachedOfflineStr && offlineCacheKey && offlineData !== void 0) offlineDataCache?.set(offlineCacheKey, JSON.stringify(offlineData));
+	const cachedOfflineStr = offlineDataOverride === void 0 && offlineCacheKey ? offlineDataCache?.get(offlineCacheKey) : void 0;
+	const [offlineData, server] = await Promise.all([offlineDataOverride !== void 0 ? Promise.resolve(offlineDataOverride) : cachedOfflineStr ? JSON.parse(cachedOfflineStr) : m("schema", () => config.adapters.getOfflineData(spaceId, environment, revision)), m("rsc", () => buildServerInfo(req, config))]);
+	if (offlineDataOverride === void 0 && !cachedOfflineStr && offlineCacheKey && offlineData !== void 0) offlineDataCache?.set(offlineCacheKey, JSON.stringify(offlineData));
 	const v = config.assetVersion ? `?v=${config.assetVersion}` : "";
 	const sdkDevToolsStylePath = `/sdk-assets/plitzi-sdk-devtools.css${v}`;
 	const debugCookie = readCookie(req.headers.cookie, "plitzi_debug");