@plitzi/sdk-server 0.32.4 → 0.32.6

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

@@ -0,0 +1,108 @@
+import { expandShorthand } from "../../../catalogs/cssCatalog.js";
+import { defUri, defsUri, globalUri, globalsUri, idUri, idsUri, styleVarUri, styleVarsUri } from "../../../helpers/uris.js";
+import { fail } from "../../../helpers/opResult.js";
+import processSelector from "@plitzi/sdk-style/helpers/processSelector";
+//#region src/modules/mcp/tools/operations/style/write.ts
+var MODES = [
+	"desktop",
+	"tablet",
+	"mobile"
+];
+var KIND_LABEL = {
+	class: "a reusable class definition",
+	element: "a global style for an element type",
+	id: "an id rule targeting a single element"
+};
+var KIND_TOOL = {
+	class: "upsertDefinition/patchDefinition",
+	element: "upsertGlobalStyle/patchGlobalStyle",
+	id: "upsertIdStyle/patchIdStyle"
+};
+var KIND_FIELD = {
+	class: "ref",
+	element: "componentType",
+	id: "targetId"
+};
+var guardKind = (style, ref, want) => {
+	const clash = MODES.map((mode) => style.platform[mode][ref]).find((item) => item !== void 0 && item.type !== want);
+	if (!clash) return null;
+	return fail(KIND_FIELD[want], `"${ref}" is already ${KIND_LABEL[clash.type]}; it cannot be edited as ${KIND_LABEL[want]}`, `Edit it with ${KIND_TOOL[clash.type]}, or choose a different ${KIND_FIELD[want]}.`);
+};
+var slotToBlocks = (slot) => {
+	const perMode = {};
+	for (const mode of MODES) {
+		const block = {};
+		const baseCss = slot[mode];
+		if (baseCss && Object.keys(baseCss).length > 0) block.default = expandShorthand(baseCss);
+		for (const [state, dm] of Object.entries(slot.states ?? {})) if (dm[mode]) (block.states ??= {})[state] = expandShorthand(dm[mode]);
+		for (const [name, dm] of Object.entries(slot.variants ?? {})) if (dm[mode]) (block.variants ??= {})[name] = { default: expandShorthand(dm[mode]) };
+		if (Object.keys(block).length > 0) perMode[mode] = block;
+	}
+	return perMode;
+};
+var writeStyleItem = (style, ref, base, slots, itemType, componentType) => {
+	for (const mode of MODES) {
+		const attributes = {};
+		const baseBlocks = slotToBlocks(base);
+		if (baseBlocks[mode]) attributes.base = baseBlocks[mode];
+		for (const [slotName, slotDef] of Object.entries(slots ?? {})) {
+			const blocks = slotToBlocks(slotDef);
+			if (blocks[mode]) attributes[slotName] = blocks[mode];
+		}
+		if (Object.keys(attributes).length === 0) Reflect.deleteProperty(style.platform[mode], ref);
+		else {
+			const styleItem = {
+				name: ref,
+				type: itemType,
+				attributes,
+				cache: ""
+			};
+			if (componentType !== void 0) styleItem.componentType = componentType;
+			styleItem.cache = processSelector(styleItem);
+			style.platform[mode][ref] = styleItem;
+		}
+	}
+};
+var mergeCss = (base, patch) => {
+	const merged = { ...base };
+	for (const [key, value] of Object.entries(patch ?? {})) if (value === null) Reflect.deleteProperty(merged, key);
+	else merged[key] = value;
+	return Object.keys(merged).length > 0 ? merged : void 0;
+};
+var mergeDisplayMode = (base, patch) => {
+	const result = {};
+	for (const mode of MODES) {
+		const css = mergeCss(base?.[mode], patch?.[mode]);
+		if (css) result[mode] = css;
+	}
+	return result;
+};
+var mergeNamedModes = (base, patch) => {
+	const names = /* @__PURE__ */ new Set([...Object.keys(base ?? {}), ...Object.keys(patch ?? {})]);
+	const result = {};
+	for (const name of names) {
+		const dm = mergeDisplayMode(base?.[name], patch?.[name]);
+		if (Object.keys(dm).length > 0) result[name] = dm;
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
+var mergeSlot = (base, patch) => {
+	const merged = mergeDisplayMode(base, patch);
+	const states = mergeNamedModes(base?.states, patch.states);
+	if (states) merged.states = states;
+	const variants = mergeNamedModes(base?.variants, patch.variants);
+	if (variants) merged.variants = variants;
+	return merged;
+};
+var mergePatch = (existing, basePatch, slotsPatch) => {
+	const base = mergeSlot(existing, basePatch);
+	const slotNames = /* @__PURE__ */ new Set([...Object.keys(existing.slots ?? {}), ...Object.keys(slotsPatch ?? {})]);
+	const slots = {};
+	for (const name of slotNames) slots[name] = mergeSlot(existing.slots?.[name], slotsPatch?.[name] ?? {});
+	return {
+		base,
+		slots: Object.keys(slots).length > 0 ? slots : void 0
+	};
+};
+//#endregion
+export { MODES, defUri, defsUri, globalUri, globalsUri, guardKind, idUri, idsUri, mergePatch, styleVarUri, styleVarsUri, writeStyleItem };

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

@@ -0,0 +1,37 @@
+import { operation } from "./operations/index.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/preview.ts
+var previewShape = {
+	pageRef: z.string().optional().describe("Page ref or id to preview; defaults to the space default page"),
+	operations: z.array(operation).max(100).optional().describe("Unsaved edits to apply to a throwaway clone before rendering, so you can preview a change WITHOUT persisting it (same op vocabulary as plitzi_apply). Omit to preview the current saved state.")
+};
+var previewTool = defineTool({
+	name: "plitzi_preview",
+	title: "Preview (HTML)",
+	description: "Render a page to a full HTML document to inspect the structure of your edits. Pass unsaved `operations` to preview a change before committing (nothing is persisted). Returns the HTML plus the page path and stateVersion. For a real rendered IMAGE that reveals visual issues like overflow, use plitzi_screenshot.",
+	inputShape: previewShape,
+	access: "read",
+	run: async (input, ctx) => {
+		if (!ctx.preview || ctx.spaceId === void 0) return {
+			error: "PREVIEW_UNAVAILABLE",
+			message: "Visual preview is not enabled on this server.",
+			hint: "Preview needs the SSR render service; it is unavailable in MCP-only mode."
+		};
+		const result = await ctx.preview.render({
+			spaceId: ctx.spaceId,
+			env: ctx.env,
+			pageRef: input.pageRef,
+			operations: input.operations
+		});
+		if (!result.ok) return result;
+		return {
+			pageRef: input.pageRef ?? "default",
+			pagePath: result.pagePath,
+			stateVersion: result.stateVersion,
+			html: result.html
+		};
+	}
+});
+//#endregion
+export { previewShape, previewTool };

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

@@ -0,0 +1,33 @@
+import { resourceErrorMessage } from "../resources/canonical.js";
+import { readResource } from "../resources/router.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/read.ts
+var readShape = { uris: z.array(z.string()).min(1).max(50).describe("Resource URIs to read in one batch (max 50). Use the ready-made uris from search / write responses.") };
+var read = (input, space, env) => {
+	return { results: input.uris.map((uri) => {
+		const found = readResource(space, env, uri);
+		if (found) return {
+			uri,
+			stateVersion: found.stateVersion,
+			data: found.data
+		};
+		const parsed = JSON.parse(resourceErrorMessage(env, uri));
+		return {
+			uri,
+			error: parsed.error,
+			message: parsed.message,
+			hint: parsed.hint
+		};
+	}) };
+};
+var readTool = defineTool({
+	name: "plitzi_read",
+	title: "Batch read",
+	description: "Batch-fetch resource content for URIs you ALREADY HOLD (from plitzi_search or a write response) — the tool form of opening MCP resources, for many at once. Pass an array of URIs (pages, elements, definitions, variables) and get them all in one call. NOT for finding things: to locate an element by label/type use plitzi_search; to browse what exists, list the plitzi:// resources. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch. Never hand-build a URI to guess your way to an element — search for it.",
+	inputShape: readShape,
+	access: "read",
+	run: (input, ctx) => read(input, ctx.space, ctx.env)
+});
+//#endregion
+export { read, readShape, readTool };

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

@@ -0,0 +1,83 @@
+import { operation } from "./operations/index.js";
+import { defineTool, imageResult } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/screenshot.ts
+var VIEWPORTS = {
+	desktop: {
+		label: "desktop",
+		width: 1440,
+		height: 900
+	},
+	mobile: {
+		label: "mobile",
+		width: 390,
+		height: 844
+	}
+};
+var resolveViewports = (choice) => {
+	if (choice === "both") return [VIEWPORTS.desktop, VIEWPORTS.mobile];
+	if (choice === "mobile") return [VIEWPORTS.mobile];
+	return [VIEWPORTS.desktop];
+};
+var screenshotShape = {
+	pageRef: z.string().optional().describe("Page ref or id to capture; defaults to the space default page"),
+	operations: z.array(operation).max(100).optional().describe("Unsaved edits to apply before rendering, so you can screenshot a proposed change WITHOUT persisting it (same op vocabulary as plitzi_apply). Omit to capture the current saved state."),
+	viewport: z.enum([
+		"desktop",
+		"mobile",
+		"both"
+	]).optional().describe("Which viewport(s) to capture. \"both\" catches responsive issues (e.g. overflow at one width). Default desktop.")
+};
+var screenshotTool = defineTool({
+	name: "plitzi_screenshot",
+	title: "Screenshot",
+	description: "Render a page to a real PNG image so you can SEE the visual result of your edits — overflow, misalignment and broken layout that data alone never reveals. Pass unsaved `operations` to screenshot a proposed change before committing, and viewport \"both\" to compare desktop and mobile. Returns the image(s).",
+	inputShape: screenshotShape,
+	access: "read",
+	requires: "screenshot",
+	run: async (input, ctx) => {
+		if (!ctx.preview || ctx.spaceId === void 0) return {
+			error: "PREVIEW_UNAVAILABLE",
+			message: "Visual preview is not enabled on this server.",
+			hint: "Preview needs the SSR render service; it is unavailable in MCP-only mode."
+		};
+		const pv = await ctx.preview.render({
+			spaceId: ctx.spaceId,
+			env: ctx.env,
+			pageRef: input.pageRef,
+			operations: input.operations
+		});
+		if (!pv.ok) return pv;
+		const viewports = resolveViewports(input.viewport);
+		if (!ctx.screenshot) return {
+			warning: "SCREENSHOT_DISABLED",
+			message: "The screenshot service is not configured; returning the HTML preview instead.",
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			html: pv.html
+		};
+		const shot = await ctx.screenshot.capture({
+			pagePath: pv.pagePath,
+			token: pv.token,
+			viewports
+		});
+		if (!shot.ok) return {
+			warning: "SCREENSHOT_UNAVAILABLE",
+			message: `The screenshot service failed (${shot.message}); returning the HTML preview instead.`,
+			hint: "The dedicated browser service is down or unreachable. Inspect the HTML, or retry later.",
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			html: pv.html
+		};
+		return imageResult(shot.images, {
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			viewports: viewports.map((v) => v.label)
+		});
+	}
+});
+//#endregion
+export { screenshotShape, screenshotTool };

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

@@ -0,0 +1,115 @@
+import { computeVersion } from "../helpers/computeVersion.js";
+import { elementRefOf, getPageElements, isPageElement, nameOf, pageRefOf, pageRefOfElement } from "../helpers/space.js";
+import { elementUri, pageUri } from "../helpers/uris.js";
+import { definitionRefs, definitionToAI } from "./operations/style/translator.js";
+import { elementView, pageSkeletonToAI } from "./operations/schema/translator.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/search.ts
+var searchShape = {
+	query: z.string().describe("Case-insensitive match on label, type and attribute values"),
+	filters: z.object({
+		type: z.string().optional(),
+		pageRef: z.string().optional()
+	}).optional(),
+	include: z.literal("detail").optional().describe("Set to \"detail\" to inline each hit's full props/style so an edit needs no follow-up read"),
+	limit: z.number().int().min(1).max(100).optional().describe("Max element hits to return (default 50). Response echoes total and, if more remain, nextOffset."),
+	offset: z.number().int().min(0).optional().describe("Element hits to skip (default 0). Page by re-calling with offset = nextOffset until it is absent.")
+};
+var breadcrumb = (schema, el) => {
+	const chain = [];
+	let current = el;
+	const guard = /* @__PURE__ */ new Set();
+	while (current && !guard.has(current.id)) {
+		guard.add(current.id);
+		chain.push(nameOf(current));
+		current = current.definition.parentId ? schema.flat[current.definition.parentId] : void 0;
+	}
+	return chain.reverse();
+};
+var search = (input, space, env) => {
+	const query = input.query.toLowerCase();
+	const matched = [];
+	for (const el of Object.values(space.schema.flat)) {
+		if (isPageElement(space.schema, el)) continue;
+		if (input.filters?.type && el.definition.type !== input.filters.type) continue;
+		const pageRef = pageRefOfElement(space.schema, el);
+		if (input.filters?.pageRef && pageRef !== input.filters.pageRef) continue;
+		const matches = [];
+		if (el.definition.label.toLowerCase().includes(query)) matches.push(`label: ${el.definition.label}`);
+		if (el.definition.type.toLowerCase().includes(query)) matches.push(`type: ${el.definition.type}`);
+		for (const [key, value] of Object.entries(el.attributes)) if (String(value).toLowerCase().includes(query)) matches.push(`${key}: ${String(value).slice(0, 100)}`);
+		if (matches.length === 0) continue;
+		matched.push({
+			el,
+			pageRef,
+			ref: elementRefOf(el),
+			matches
+		});
+	}
+	const offset = input.offset ?? 0;
+	const limit = input.limit ?? 50;
+	const total = matched.length;
+	const nextOffset = offset + limit < total ? offset + limit : void 0;
+	const results = matched.slice(offset, offset + limit).map((hit) => {
+		const { detail, version } = elementView(space.schema, hit.el, space.style);
+		return {
+			pageRef: hit.pageRef,
+			ref: hit.ref,
+			uri: elementUri(env, hit.ref),
+			pageUri: pageUri(env, hit.pageRef),
+			stateVersion: version,
+			parentRef: detail.parentRef,
+			path: breadcrumb(space.schema, hit.el),
+			label: hit.el.definition.label,
+			type: hit.el.definition.type,
+			matches: hit.matches,
+			detail: input.include === "detail" ? detail : void 0
+		};
+	});
+	const definitions = [];
+	for (const ref of definitionRefs(space.style)) {
+		if (ref.toLowerCase().includes(query)) {
+			const def = definitionToAI(space.style, ref);
+			if (def) definitions.push(def);
+		}
+		if (definitions.length >= 50) break;
+	}
+	const pages = [];
+	for (const page of getPageElements(space.schema)) {
+		const label = nameOf(page);
+		const slug = typeof page.attributes.slug === "string" ? page.attributes.slug : "";
+		const matches = [];
+		if (label.toLowerCase().includes(query)) matches.push(`label: ${label}`);
+		if (slug && slug.toLowerCase().includes(query)) matches.push(`slug: ${slug}`);
+		if (matches.length === 0) continue;
+		const ref = pageRefOf(page);
+		pages.push({
+			ref,
+			uri: pageUri(env, ref),
+			stateVersion: computeVersion(pageSkeletonToAI(space.schema, page, space.style)),
+			label,
+			slug,
+			matches
+		});
+	}
+	return {
+		results,
+		total,
+		offset,
+		limit,
+		nextOffset,
+		definitions: definitions.length > 0 ? definitions : void 0,
+		pages: pages.length > 0 ? pages : void 0
+	};
+};
+var searchTool = defineTool({
+	name: "plitzi_search",
+	title: "Search",
+	description: "FIND elements when you know what you want but not its ref/uri (e.g. \"the hero button\"). Matches label, type or attribute value across all pages. Each hit returns the element uri, its stateVersion (edit with optimistic concurrency, no read needed) and its tree path. Pass include: \"detail\" to inline the full props/style of each hit plus resolvedStyle (the CSS of its classes). Also returns any style definitions matching the query (with full CSS) under `definitions`, and matching pages under `pages`. Element hits are paginated: it returns at most `limit` (default 50) starting at `offset`, plus `total` and — while more remain — `nextOffset` to fetch the next page.",
+	inputShape: searchShape,
+	access: "read",
+	run: (input, ctx) => search(input, ctx.space, ctx.env)
+});
+//#endregion
+export { search, searchShape, searchTool };

package/dist/modules/mcp/tools/shared/tool.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+//#region src/modules/mcp/tools/shared/tool.ts
+/** Build the MCP CallToolResult for an image-returning tool: a text meta block followed by one image block per
+*  PNG, so a vision-capable agent (or MCP client) sees the render directly. */
+var imageResult = (images, meta) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(meta)
+}, ...images.map((img) => ({
+	type: "image",
+	data: img.data,
+	mimeType: img.mimeType
+}))] });
+/** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
+*  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.
+*  Adding a tool is: call defineTool in its own file and append it to the `tools` registry. */
+var defineTool = (spec) => ({
+	name: spec.name,
+	title: spec.title,
+	description: spec.description,
+	inputShape: spec.inputShape,
+	access: spec.access,
+	requires: spec.requires,
+	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
+});
+//#endregion
+export { defineTool, imageResult };

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

@@ -0,0 +1,124 @@
+import { elementRefOf, findElementByRef } from "../../../helpers/space.js";
+import { definitionToAI, globalStyleToAI, idStyleToAI } from "../../operations/style/translator.js";
+import { checkBindingSourceScope, checkBindingTarget, checkBindingTransformers } from "./bindings.js";
+import { checkSlotCss } from "./css.js";
+import { checkVariantApplication } from "./elements.js";
+import { checkInteractionNode } from "./interactions.js";
+import { buildValidationCtx } from "./index.js";
+//#region src/modules/mcp/tools/shared/validator/audit.ts
+var harvest = (ctx, into, label, run) => {
+	const sub = {
+		...ctx,
+		errors: [],
+		warnings: [],
+		warned: /* @__PURE__ */ new Set()
+	};
+	run(sub);
+	for (const e of sub.errors) into.errors.push({
+		path: e.path,
+		message: `Pre-existing malformation in ${label}: ${e.message}`,
+		hint: `${e.hint ? `${e.hint} ` : ""}This issue already exists in the space (NOT caused by your change), but the save is blocked until you fix it too, in this same batch.`,
+		...e.validValues ? { validValues: e.validValues } : {}
+	});
+	for (const w of sub.warnings) {
+		const message = `Pre-existing issue in ${label} (not caused by your change, but worth fixing too): ${w}`;
+		if (!into.warnings.includes(message)) into.warnings.push(message);
+	}
+};
+var toNode = (id, node) => ({
+	id,
+	title: node.title,
+	nodeType: node.type,
+	action: node.action,
+	params: node.params,
+	enabled: node.enabled,
+	when: node.when,
+	elementId: node.elementId ?? void 0,
+	preview: node.preview
+});
+var auditElement = (space, sub, el) => {
+	const hostRef = elementRefOf(el);
+	const base = `element "${hostRef}"`;
+	for (const [category, list] of Object.entries(el.definition.bindings ?? {})) for (const binding of list) {
+		const path = `${base}.bindings.${category}[to=${binding.to}]`;
+		checkBindingTransformers(binding.transformers, `${path}.transformers`, sub);
+		checkBindingSourceScope(space, sub, hostRef, binding.source, `${path}.source`);
+		checkBindingTarget(hostRef, category, binding.to, path, sub);
+	}
+	for (const [id, node] of Object.entries(el.definition.interactions ?? {})) checkInteractionNode(toNode(id, node), `${base}.interactions.${id}`, sub, hostRef);
+	checkVariantApplication(el.definition.initialState, `${base}.initialState`, sub);
+};
+var auditDefinitionCss = (sub, label, def) => {
+	const { ref: _ref, slots, ...slot } = def;
+	checkSlotCss(slot, label, sub);
+	for (const [name, slotDef] of Object.entries(slots ?? {})) checkSlotCss(slotDef, `${label}.slots.${name}`, sub);
+};
+var collectTouched = (ops) => {
+	const touched = {
+		elementRefs: /* @__PURE__ */ new Set(),
+		definitions: /* @__PURE__ */ new Set(),
+		globalStyles: /* @__PURE__ */ new Set(),
+		idStyles: /* @__PURE__ */ new Set()
+	};
+	for (const op of ops) switch (op.type) {
+		case "upsertElement":
+			touched.elementRefs.add(op.element.ref);
+			break;
+		case "patchElement":
+		case "moveElement":
+		case "upsertBinding":
+		case "patchBinding":
+		case "deleteBinding":
+		case "upsertInteractionFlow":
+		case "patchInteractionNode":
+		case "deleteInteraction":
+			touched.elementRefs.add(op.ref);
+			break;
+		case "upsertDefinition":
+		case "patchDefinition":
+			touched.definitions.add(op.ref);
+			break;
+		case "upsertGlobalStyle":
+		case "patchGlobalStyle":
+			touched.globalStyles.add(op.componentType);
+			break;
+		case "upsertIdStyle":
+		case "patchIdStyle":
+			touched.idStyles.add(op.targetId);
+			break;
+		default: break;
+	}
+	return touched;
+};
+var auditResources = (space, ops) => {
+	const ctx = buildValidationCtx(space, ops);
+	const result = {
+		valid: true,
+		errors: [],
+		warnings: []
+	};
+	const touched = collectTouched(ops);
+	const seenElements = /* @__PURE__ */ new Set();
+	for (const ref of touched.elementRefs) {
+		const el = findElementByRef(space.schema, ref);
+		if (!el || seenElements.has(el.id)) continue;
+		seenElements.add(el.id);
+		harvest(ctx, result, `element "${elementRefOf(el)}"`, (sub) => auditElement(space, sub, el));
+	}
+	for (const ref of touched.definitions) {
+		const def = definitionToAI(space.style, ref);
+		if (def) harvest(ctx, result, `definition "${ref}"`, (sub) => auditDefinitionCss(sub, `definition "${ref}"`, def));
+	}
+	for (const componentType of touched.globalStyles) {
+		const def = globalStyleToAI(space.style, componentType);
+		if (def) harvest(ctx, result, `global style "${componentType}"`, (sub) => auditDefinitionCss(sub, `global style "${componentType}"`, def));
+	}
+	for (const targetId of touched.idStyles) {
+		const def = idStyleToAI(space.style, targetId);
+		if (def) harvest(ctx, result, `id style "#${targetId}"`, (sub) => auditDefinitionCss(sub, `id style "#${targetId}"`, def));
+	}
+	result.valid = result.errors.length === 0;
+	return result;
+};
+//#endregion
+export { auditResources };

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

@@ -0,0 +1,30 @@
+import { slugRouteParams } from "../../../helpers/space.js";
+//#region src/modules/mcp/tools/shared/validator/batch.ts
+var batchDeclaredVars = (ops) => {
+	const names = [];
+	for (const op of ops) if (op.type === "upsertVariable") names.push(op.name);
+	else if (op.type === "upsertPage" && typeof op.slug === "string") names.push(...slugRouteParams(op.slug));
+	return names;
+};
+var batchDeclaredPages = (ops) => {
+	const refs = /* @__PURE__ */ new Set();
+	for (const op of ops) if (op.type === "upsertPage") refs.add(op.ref);
+	return refs;
+};
+var batchDeclaredFolders = (ops) => {
+	const refs = /* @__PURE__ */ new Set();
+	for (const op of ops) if (op.type === "upsertFolder") refs.add(op.ref);
+	return refs;
+};
+var batchDeclaredVariants = (ops) => {
+	const map = /* @__PURE__ */ new Map();
+	for (const op of ops) {
+		if (op.type !== "upsertDefinition" && op.type !== "patchDefinition") continue;
+		const names = new Set(Object.keys(op.variants ?? {}));
+		for (const slot of Object.values(op.slots ?? {})) for (const name of Object.keys(slot.variants ?? {})) names.add(name);
+		if (names.size > 0) map.set(op.ref, /* @__PURE__ */ new Set([...map.get(op.ref) ?? [], ...names]));
+	}
+	return map;
+};
+//#endregion
+export { batchDeclaredFolders, batchDeclaredPages, batchDeclaredVariants, batchDeclaredVars };

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