@plitzi/sdk-server 0.32.5 → 0.32.6

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -24,7 +24,7 @@ var read = (input, space, env) => {
 var readTool = defineTool({
 	name: "plitzi_read",
 	title: "Batch read",
-	description: "Read MANY resources at once by URI — the batch alternative to opening resources one by one. Pass an array of URIs (pages, elements, definitions, variables), e.g. the ready-made uris from plitzi_search or a write response, and get them all back in a single call instead of one read per URI. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch.",
+	description: "Batch-fetch resource content for URIs you ALREADY HOLD (from plitzi_search or a write response) — the tool form of opening MCP resources, for many at once. Pass an array of URIs (pages, elements, definitions, variables) and get them all in one call. NOT for finding things: to locate an element by label/type use plitzi_search; to browse what exists, list the plitzi:// resources. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch. Never hand-build a URI to guess your way to an element — search for it.",
 	inputShape: readShape,
 	access: "read",
 	run: (input, ctx) => read(input, ctx.space, ctx.env)

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

@@ -1,7 +1,8 @@
 import { computeVersion } from "../helpers/computeVersion.js";
-import { elementRefOf, getPageElements, isPageElement, pageRefOf, pageRefOfElement } from "../helpers/space.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 { elementDetailToAI, pageSkeletonToAI } from "./operations/schema/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
@@ -15,21 +16,20 @@ var searchShape = {
 	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 labelOf = (el) => (typeof el.attributes.name === "string" ? el.attributes.name : void 0) ?? el.definition.label;
 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(labelOf(current));
+		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 results = [];
+	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;
@@ -40,22 +40,33 @@ var search = (input, space, env) => {
 		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;
-		const ref = elementRefOf(el);
-		const detail = elementDetailToAI(space.schema, el, space.style);
-		results.push({
+		matched.push({
+			el,
 			pageRef,
-			ref,
-			uri: `plitzi://schema/${env}/elements/${ref}`,
-			pageUri: `plitzi://schema/${env}/pages/${pageRef}`,
-			stateVersion: computeVersion(detail),
-			parentRef: detail.parentRef,
-			path: breadcrumb(space.schema, el),
-			label: el.definition.label,
-			type: el.definition.type,
-			matches,
-			detail: input.include === "detail" ? detail : void 0
+			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)) {
@@ -66,7 +77,7 @@ var search = (input, space, env) => {
 	}
 	const pages = [];
 	for (const page of getPageElements(space.schema)) {
-		const label = labelOf(page);
+		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}`);
@@ -75,19 +86,15 @@ var search = (input, space, env) => {
 		const ref = pageRefOf(page);
 		pages.push({
 			ref,
-			uri: `plitzi://schema/${env}/pages/${ref}`,
-			stateVersion: computeVersion(pageSkeletonToAI(space.schema, page)),
+			uri: pageUri(env, ref),
+			stateVersion: computeVersion(pageSkeletonToAI(space.schema, page, space.style)),
 			label,
 			slug,
 			matches
 		});
 	}
-	const offset = input.offset ?? 0;
-	const limit = input.limit ?? 50;
-	const total = results.length;
-	const nextOffset = offset + limit < total ? offset + limit : void 0;
 	return {
-		results: results.slice(offset, offset + limit),
+		results,
 		total,
 		offset,
 		limit,
@@ -99,7 +106,7 @@ var search = (input, space, env) => {
 var searchTool = defineTool({
 	name: "plitzi_search",
 	title: "Search",
-	description: "Find elements by 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.",
+	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)

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