@plitzi/sdk-server 0.32.5 → 0.32.6

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

@@ -0,0 +1,70 @@
+import { getTransformer, suggestTransformer } from "../../../catalogs/builtinTransformers.js";
+import { descendantIds, elementRefOf, findElementByRef } from "../../../helpers/space.js";
+import { warnOnce } from "./context.js";
+import getSourceName from "@plitzi/sdk-shared/dataSource/helpers/getSourceName";
+//#region src/modules/mcp/tools/shared/validator/bindings.ts
+var providerOfSource = (space, source) => {
+	const head = source.split(".")[0];
+	const sep = head.indexOf("_");
+	if (sep < 0) return;
+	const idRef = head.slice(sep + 1);
+	const el = findElementByRef(space.schema, idRef);
+	if (!el || getSourceName(el.definition.type, el) !== head) return;
+	return {
+		ref: elementRefOf(el),
+		id: el.id
+	};
+};
+var checkBindingTarget = (ref, category, to, path, ctx) => {
+	if (category !== "attributes" && category !== "initialState") return;
+	const type = ctx.elementType(ref);
+	const targets = type ? ctx.typeMeta.get(type)?.bindingTargets?.[category] : void 0;
+	if (!targets || targets.size === 0 || targets.has(to)) return;
+	warnOnce(ctx, `Binding target "${to}" at ${path} is not among the "${category}" targets the type "${type}" declares (${[...targets].sort().join(", ")}). Verify against plitzi://data-sources; it may still be valid.`);
+};
+var checkBindingSourceScope = (space, ctx, elementRef, source, path) => {
+	const provider = providerOfSource(space, source);
+	if (!provider) return;
+	const bound = findElementByRef(space.schema, elementRef);
+	if (!bound) return;
+	if (bound.id !== provider.id && descendantIds(space.schema, provider.id).includes(bound.id)) return;
+	ctx.errors.push({
+		path,
+		message: `Binding source "${source}" is provided by element "${provider.ref}", but "${elementRef}" is not inside its subtree`,
+		hint: `An element source is scoped to its DESCENDANTS only, so this binding resolves to nothing at runtime (the source is not available outside "${provider.ref}"). Move "${elementRef}" under "${provider.ref}", or bind to a source that is in scope (e.g. a global module source like state/space/navigation).`
+	});
+};
+var checkBindingTransformers = (transformers, path, ctx) => {
+	transformers?.forEach((transformer, i) => {
+		if (transformer.enabled === false) return;
+		const base = `${path}[${i}]`;
+		const spec = getTransformer(transformer.action);
+		if (!spec) {
+			const suggestion = suggestTransformer(transformer.action);
+			ctx.errors.push({
+				path: `${base}.action`,
+				message: `Unknown transformer action "${transformer.action}"`,
+				hint: `The runtime skips an unknown transformer and passes the value through unchanged.${suggestion ? ` Did you mean "${suggestion}"?` : ""} See the transformers list in plitzi://data-sources.`
+			});
+			return;
+		}
+		const params = transformer.params;
+		const unknown = Object.keys(params).filter((key) => !(key in spec.params));
+		if (spec.strictParams && unknown.length > 0) warnOnce(ctx, `Transformer "${transformer.action}" at ${base} got unknown param(s) ${unknown.map((k) => `"${k}"`).join(", ")} — the runtime ignores them. Valid params: ${Object.keys(spec.params).join(", ") || "(none)"}.`);
+		for (const [key, param] of Object.entries(spec.params)) {
+			if (param.required && !(key in params)) ctx.errors.push({
+				path: `${base}.params.${key}`,
+				message: `Transformer "${transformer.action}" is missing required param "${key}"`,
+				hint: param.description
+			});
+			if (param.type === "select" && param.options && key in params && !param.options.includes(params[key])) ctx.errors.push({
+				path: `${base}.params.${key}`,
+				message: `Transformer "${transformer.action}" param "${key}" is "${params[key]}", not one of its options`,
+				hint: `Use one of: ${param.options.join(", ")}.`,
+				validValues: param.options
+			});
+		}
+	});
+};
+//#endregion
+export { checkBindingSourceScope, checkBindingTarget, checkBindingTransformers };

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

@@ -0,0 +1,35 @@
+//#region src/modules/mcp/tools/shared/validator/context.ts
+var VAR_REF = /\{\{\s*([A-Za-z_][\w.-]*)\s*\}\}/g;
+var CSS_VAR = /var\(\s*--([A-Za-z_][\w-]*)\s*\)/g;
+var RAW_CODE_TYPES = /* @__PURE__ */ new Set([
+	"blockJsx",
+	"blockHtml",
+	"custom"
+]);
+var warnOnce = (ctx, message) => {
+	if (!ctx.warned.has(message)) {
+		ctx.warned.add(message);
+		ctx.warnings.push(message);
+	}
+};
+var checkVarRefs = (text, path, ctx) => {
+	for (const match of text.matchAll(VAR_REF)) {
+		const name = match[1];
+		if (!ctx.schemaVars.has(name)) warnOnce(ctx, `Unknown variable {{${name}}} at ${path}: not a space schema variable or a page route param. Read plitzi://schema-variables, or use a route param from the page skeleton (routeParams).`);
+	}
+};
+var checkStyleVarRefs = (text, path, ctx) => {
+	for (const match of text.matchAll(CSS_VAR)) {
+		const name = match[1];
+		if (!ctx.styleVars.has(name)) {
+			const tokens = [...ctx.styleVars];
+			warnOnce(ctx, `Unknown style variable var(--${name}) at ${path}: not a design token in this space. ${tokens.length > 0 ? `Available tokens: ${tokens.slice(0, 30).join(", ")}${tokens.length > 30 ? ", …" : ""}.` : "Read plitzi://style-variables for the valid token names."}`);
+		}
+	}
+};
+var checkObservedName = (value, observed, kind, resource, path, ctx) => {
+	if (!value || observed.size === 0 || observed.has(value)) return;
+	warnOnce(ctx, `${kind} "${value}" at ${path} was not seen in this space. Verify against ${resource}; it may still be valid.`);
+};
+//#endregion
+export { RAW_CODE_TYPES, checkObservedName, checkStyleVarRefs, checkVarRefs, warnOnce };

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

@@ -1,16 +1,36 @@
+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.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) => validateOperations(space, input.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.",
+	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)

package/dist/modules/ssr/preview.js

@@ -1,7 +1,7 @@
 import { computeVersion } from "../mcp/helpers/computeVersion.js";
 import { cloneSpace, findPageByRef, getPageElements } from "../mcp/helpers/space.js";
 import { applyOperations } from "../mcp/tools/apply/dispatch.js";
-import { validateOperations } from "../mcp/tools/shared/validator.js";
+import { validateOperations } from "../mcp/tools/shared/validator/index.js";
 import { PREVIEW_TOKEN_PARAM } from "../mcp/constants.js";
 import { buildBody } from "./buildBody.js";
 import { randomUUID } from "node:crypto";

package/dist/modules/ssr/views/template.ejs

@@ -10,6 +10,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://cdn.plitzi.com" />
 
+    <% if (!locals.ssrOnly) { %>
     <link rel="modulepreload" href="<%= locals.react || '' %>" crossorigin />
     <link rel="modulepreload" href="<%= locals.reactDom || '' %>" crossorigin />
 
@@ -25,6 +26,7 @@
         }
       }
     </script>
+    <% } %>
 
     <link
       rel="preload"

package/dist/src/index.d.ts

@@ -3,7 +3,7 @@ export { registerHealthCheck, buildHealthPayload } from './core/health';
 export type { HealthCheckApp, HealthIdentity } from './core/health';
 export { createJsonAdapters } from './adapters/jsonAdapters';
 export { AIEngine, toolResponseOk, toolResponseErr, zodToJsonSchema, getAllowedModes, bindTools, isToolActive, resolveToolHandler, isCallToolResult, toolResponseFromResult } from './modules/ai';
-export { createMcpServer, handleMcp, serveMcp, readMcpBody, createHttpPreviewClient, createHttpScreenshotClient } from './modules/mcp';
+export { createMcpServer, handleMcp, serveMcp, readMcpBody, buildAgentGuide, createHttpPreviewClient, createHttpScreenshotClient } from './modules/mcp';
 export { createPreview, createMemoryDraftStore, PREVIEW_TOKEN_PARAM } from './modules/ssr/preview';
 export { apply, search, read, validate, applyShape, searchShape, readShape, validateShape, operation, tools } from './modules/mcp/tools';
 export type { JsonAdaptersConfig } from './adapters/jsonAdapters';