@plitzi/sdk-server 0.32.5 → 0.32.7

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';

package/dist/src/modules/mcp/catalogs/builtinCallbacks.d.ts

@@ -0,0 +1,23 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinGlobalCallback {
+    source: string;
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_GLOBAL_CALLBACKS: Record<string, BuiltinGlobalCallback>;
+/** The built-in globalCallback for an action, or undefined when the action is not a known built-in (a plugin
+ *  callback whose source/schema is not knowable here). */
+export declare const getGlobalCallback: (action: string) => BuiltinGlobalCallback | undefined;
+/** Report the param keys the agent supplied that are not valid for a built-in callback: only for CLOSED
+ *  (`strictParams`) callbacks; open ones (collection) accept arbitrary field keys so nothing is unknown. Returns []
+ *  for an unknown action (a plugin callback whose schema is not known here). */
+export declare const unknownBuiltinParams: (action: string, params: Record<string, unknown>) => string[];
+/** Resolve a `globalCallback` action against the built-in catalog: returns the module id it is registered under
+ *  (`source`) and the params reconciled to the callback's schema — unknown keys dropped for a closed callback, then
+ *  missing defaults filled. An action the catalog does not know (e.g. a plugin callback) yields no source and
+ *  unchanged params, so the caller keeps its own behavior for it. */
+export declare const applyBuiltinCallback: (action: string, params: Record<string, unknown>) => {
+    source?: string;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/catalogs/builtinComponents.d.ts

@@ -0,0 +1,4 @@
+import { ComponentCatalogEntry } from '@plitzi/sdk-shared';
+type BuiltinComponent = Required<Pick<ComponentCatalogEntry, 'label' | 'description' | 'category'>>;
+export declare const BUILTIN_COMPONENTS: Partial<Record<string, BuiltinComponent>>;
+export {};

package/dist/src/modules/mcp/catalogs/builtinElementCallbacks.d.ts

@@ -0,0 +1,20 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinElementCallback {
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_ELEMENT_CALLBACKS: Record<string, BuiltinElementCallback>;
+/** The built-in element callback for an action, or undefined when the action is not a known built-in (an
+ *  element-type-specific/plugin callback whose schema is not knowable here). */
+export declare const getElementCallback: (action: string) => BuiltinElementCallback | undefined;
+/** Param keys the agent supplied that are not valid for a built-in element callback (only for CLOSED sets). []
+ *  for an unknown action (a plugin/element-specific callback whose schema is not known here). */
+export declare const unknownElementCallbackParams: (action: string, params: Record<string, unknown>) => string[];
+/** Reconcile a `callback` action against the element-callback catalog: unknown keys dropped for a closed callback,
+ *  then missing defaults filled (category:"attribute", revertOnFinish:false). An unknown action yields unchanged
+ *  params, so a plugin/element-specific callback keeps whatever the agent passed. */
+export declare const applyElementCallback: (action: string, params: Record<string, unknown>) => {
+    known: boolean;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/catalogs/builtinTransformers.d.ts

@@ -0,0 +1,28 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinTransformer {
+    title: string;
+    description: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_TRANSFORMERS: Record<string, BuiltinTransformer>;
+/** The built-in transformer for an action, or undefined when the action is not a known built-in transformer. */
+export declare const getTransformer: (action: string) => BuiltinTransformer | undefined;
+/** The closest known transformer action to a mistyped one (substring match either way), so a wrong action like
+ *  "template" teaches "twigTemplate". Undefined when nothing is close. */
+export declare const suggestTransformer: (action: string) => string | undefined;
+export interface TransformerInfo {
+    action: string;
+    title: string;
+    description: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+        default?: string | number | boolean;
+        options?: string[];
+    }[];
+}
+/** The transformer catalog projected for the data-sources resource / primer, so the agent knows the exact action
+ *  names and params up front (the real fix for the "agent can't write transformers" problem). */
+export declare const transformerCatalog: () => TransformerInfo[];

package/dist/src/modules/mcp/catalogs/builtinTransformers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/catalogs/builtinUtilities.d.ts

@@ -0,0 +1,18 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinUtility {
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_UTILITIES: Record<string, BuiltinUtility>;
+/** The built-in utility for an action, or undefined when the action is not a known built-in utility. */
+export declare const getUtility: (action: string) => BuiltinUtility | undefined;
+/** Param keys the agent supplied that are not valid for a built-in utility (only for CLOSED sets). [] for an unknown
+ *  action (a utility whose schema is not known here). */
+export declare const unknownUtilityParams: (action: string, params: Record<string, unknown>) => string[];
+/** Reconcile a `utility` action against the utility catalog: unknown keys dropped for a closed utility, then missing
+ *  defaults filled. An unknown action yields unchanged params. */
+export declare const applyUtility: (action: string, params: Record<string, unknown>) => {
+    known: boolean;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/{tools/operations/style → catalogs}/cssCatalog.d.ts

@@ -1,10 +1,14 @@
-import { CssProps } from '../../../types';
+import { CssProps } from '../types';
 /** Every kebab-case CSS property Plitzi's style engine understands. Values written to a definition
  *  must use these exact keys — camelCase or unknown keys are rejected by the validator. */
 export declare const cssProperties: string[];
 export declare const isCssProperty: (key: string) => boolean;
 /** If a camelCase key maps to a known kebab-case property, return it — used to teach the agent the correct key. */
 export declare const suggestCssProperty: (key: string) => string | undefined;
+export declare const COMPOUND_SHORTHANDS: Record<string, string[]>;
+/** The atomic longhands to write instead of a compound shorthand, or undefined when the key is not a compound
+ *  shorthand. `flex` layout in particular is NOT `display` + `flex-direction` (those are their own properties). */
+export declare const compoundLonghands: (key: string) => string[] | undefined;
 /** Expand supported CSS shorthands to their longhand keys. Explicit longhands in the same map win over any
  *  expansion (so `{ padding: 8, padding-left: 0 }` keeps padding-left: 0). Unrecognized keys pass through. */
 export declare const expandShorthand: (css: CssProps) => CssProps;

package/dist/src/modules/mcp/catalogs/index.d.ts

@@ -0,0 +1,9 @@
+export * from './paramSpec';
+export * from './builtinCallbacks';
+export * from './builtinElementCallbacks';
+export * from './builtinUtilities';
+export * from './builtinTransformers';
+export * from './builtinComponents';
+export * from './cssCatalog';
+export * from './observed';
+export * from './registry';

package/dist/src/modules/mcp/catalogs/observed.d.ts

@@ -0,0 +1,48 @@
+import { TransformerInfo } from './builtinTransformers';
+import { AIInteractionNodeType } from '../types';
+import { Schema } from '@plitzi/sdk-shared';
+export interface BuiltinParamInfo {
+    name: string;
+    type: string;
+    description: string;
+    default?: string | number | boolean;
+    options?: string[];
+    conditional?: boolean;
+}
+export interface BuiltinGlobalCallbackInfo {
+    action: string;
+    source: string;
+    title: string;
+    strictParams: boolean;
+    params: BuiltinParamInfo[];
+}
+export interface BuiltinActionInfo {
+    action: string;
+    title: string;
+    strictParams: boolean;
+    params: BuiltinParamInfo[];
+}
+export interface InteractionCatalog {
+    note: string;
+    actions: Record<string, string[]>;
+    globalCallbacksNote: string;
+    globalCallbacks: BuiltinGlobalCallbackInfo[];
+    elementCallbacksNote: string;
+    elementCallbacks: BuiltinActionInfo[];
+    utilitiesNote: string;
+    utilities: BuiltinActionInfo[];
+    flowCount: number;
+}
+export interface DataSourceCatalog {
+    note: string;
+    scopeNote: string;
+    sources: string[];
+    targets: Record<string, string[]>;
+    transformersNote: string;
+    transformers: TransformerInfo[];
+}
+export declare const buildInteractionCatalog: (schema: Schema) => InteractionCatalog;
+export declare const buildDataSourceCatalog: (schema: Schema) => DataSourceCatalog;
+export declare const observedInteractionActions: (schema: Schema) => Set<string>;
+export declare const observedDataSources: (schema: Schema) => Set<string>;
+export declare const INTERACTION_NODE_TYPES: AIInteractionNodeType[];