@plitzi/sdk-mcp 0.38.7 → 0.38.8

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

@@ -2,14 +2,16 @@ import { cloneSpace } from "../../helpers/space.js";
 import { expandOperations } from "./expandOperations.js";
 import { fixTouched, lintDraft } from "./lintDraft.js";
 import { newSuggestions } from "./newSuggestions.js";
+import { normalizeOperations } from "./normalizeOperations.js";
 import { validateOperations } from "./validator/index.js";
 import { applyOperations } from "../apply/dispatch.js";
 //#region src/modules/mcp/tools/shared/draftBatch.ts
 /**
 * A batch run on a copy of the space and read back — the one way every tool that takes operations handles them, so
-* `plitzi_validate` answers exactly what `plitzi_apply` would, and `plitzi_render` holds a widget to the same rules.
+* a `dryRun` answers exactly what `plitzi_apply` would save, and `plitzi_render` holds a widget to the same rules.
 *
-* In order: the sugar ops expanded; what was already wrong with the elements the batch touches fixed where it has one
+* In order: the sugar ops expanded; what has one reading read that way (`normalizeOperations`, said in `warnings`);
+* what was already wrong with the elements the batch touches fixed where it has one
 * reading (`fixTouched`, each fix said in `warnings`); each op checked against the input it takes; the batch applied to
 * the copy; and the copy read by `lintDraft` — structure and meaning, the same reading every other writer gets. The
 * first stage to refuse ends it; the space handed in is never touched.
@@ -21,23 +23,32 @@ var draftBatch = (space, env, operations, mode = "space") => {
 		errors: expansion.errors,
 		warnings: []
 	};
-	const ops = expansion.operations;
+	const { operations: ops, notes } = normalizeOperations(space, expansion.operations);
 	const prepared = fixTouched(space, ops);
 	const validation = validateOperations(prepared.space, ops, mode);
 	if (!validation.valid) return {
 		ok: false,
 		errors: validation.errors,
-		warnings: [...prepared.fixed, ...validation.warnings]
+		warnings: [
+			...notes,
+			...prepared.fixed,
+			...validation.warnings
+		]
 	};
 	const draft = cloneSpace(prepared.space);
 	const outcome = applyOperations(draft, env, ops);
 	if (outcome.errors.length > 0) return {
 		ok: false,
 		errors: outcome.errors,
-		warnings: [...prepared.fixed, ...validation.warnings]
+		warnings: [
+			...notes,
+			...prepared.fixed,
+			...validation.warnings
+		]
 	};
 	const reading = lintDraft(draft, ops, prepared.space);
 	const warnings = [
+		...notes,
 		...prepared.fixed,
 		...validation.warnings,
 		...reading.warnings

package/dist/modules/mcp/tools/shared/effects.d.ts

@@ -0,0 +1,2 @@
+import { Space } from '../../helpers';
+export declare const effectsOf: (before: Space, after: Space) => string[];

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

@@ -0,0 +1,155 @@
+import { canonicalJson } from "@plitzi/sdk-shared/helpers/canonicalJson";
+import { isRecord } from "@plitzi/sdk-shared/helpers/isRecord";
+//#region src/modules/mcp/tools/shared/effects.ts
+/**
+* What a write did to the space, read off the documents before and after it — never off what was asked. An agent
+* that is told only what it asked for cannot see the element a shared class also restyled, the child a move took with
+* it, or the operation that changed nothing; every one of those is a line here. Past `LIMIT` lines the rest is
+* counted, never dropped unsaid.
+*/
+var LIMIT = 40;
+var SHOWN = 60;
+var same = (before, after) => canonicalJson(before) === canonicalJson(after);
+var shown = (value) => {
+	const text = canonicalJson(value);
+	return text.length > SHOWN ? `${text.slice(0, 59)}…` : text;
+};
+/** Each entry of a list by what names it — its `id`, or its `name` — when every entry has one. */
+var keyedList = (list) => {
+	const keyed = /* @__PURE__ */ new Map();
+	for (const entry of list) {
+		const key = isRecord(entry) ? entry.id ?? entry.name : void 0;
+		if (typeof key !== "string" || keyed.has(key)) return;
+		keyed.set(key, entry);
+	}
+	return keyed;
+};
+var isScalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+/** Every difference between two values, at its path: a key added, removed or changed, an entry of a named list. */
+var differences = (path, before, after, out) => {
+	if (same(before, after)) return;
+	if (before === void 0) {
+		out.push(`${path} = ${shown(after)}`);
+		return;
+	}
+	if (after === void 0) {
+		out.push(`${path} removed (was ${shown(before)})`);
+		return;
+	}
+	if (Array.isArray(before) && Array.isArray(after)) {
+		const was = keyedList(before);
+		const is = keyedList(after);
+		if (was && is) {
+			for (const key of /* @__PURE__ */ new Set([...was.keys(), ...is.keys()])) differences(`${path}[${key}]`, was.get(key), is.get(key), out);
+			if ([...was.keys()].join("\n") !== [...is.keys()].join("\n") && same([...was.keys()].toSorted(), [...is.keys()].toSorted())) out.push(`${path} reordered`);
+			return;
+		}
+		if (before.every(isScalar) && after.every(isScalar)) {
+			const added = after.filter((item) => !before.includes(item));
+			const removed = before.filter((item) => !after.includes(item));
+			if (added.length > 0 || removed.length > 0) out.push(`${path}: ${[...added.map((item) => `+${shown(item)}`), ...removed.map((item) => `−${shown(item)}`)].join(" ")}`);
+			else out.push(`${path}: ${shown(before)} → ${shown(after)}`);
+			return;
+		}
+	}
+	if (isRecord(before) && isRecord(after)) {
+		for (const key of /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) differences(`${path}.${key}`, before[key], after[key], out);
+		return;
+	}
+	out.push(`${path}: ${shown(before)} → ${shown(after)}`);
+};
+/** A key of a record, or nothing when it has none — said as such, where indexing would claim it is there. */
+var lookup = (record, key) => Object.hasOwn(record, key) ? record[key] : void 0;
+/** An object without the keys a caller reads apart. */
+var without = (value, keys) => Object.fromEntries(Object.entries(value).filter(([key]) => !keys.includes(key)));
+var classesOf = (selector) => (selector ?? "").split(/\s+/).filter(Boolean);
+/** An element's own changes: its attributes, its classes, where it is, and the rest of its definition. */
+var elementChanges = (id, before, after, out) => {
+	const bound = new Map((after.definition.bindings?.attributes ?? []).map((binding) => [binding.to, binding.source]));
+	for (const key of /* @__PURE__ */ new Set([...Object.keys(before.attributes), ...Object.keys(after.attributes)])) {
+		const lines = [];
+		differences(`${id}.${key}`, before.attributes[key], after.attributes[key], lines);
+		const source = bound.get(key);
+		out.push(...source ? lines.map((line) => `${line} — bound to ${source}: the page shows the binding's value`) : lines);
+	}
+	const { parentId: wasIn, items: hadItems, styleSelectors: wore } = before.definition;
+	const { parentId: isIn, items: hasItems, styleSelectors: wears } = after.definition;
+	if (wasIn !== isIn) out.push(`${id} moved from ${wasIn ?? "the top"} to ${isIn ?? "the top"}`);
+	if (!same(hadItems, hasItems) && same([...hadItems ?? []].toSorted(), [...hasItems ?? []].toSorted())) out.push(`${id}'s children reordered`);
+	for (const selector of /* @__PURE__ */ new Set([...Object.keys(wore), ...Object.keys(wears)])) {
+		const was = classesOf(wore[selector]);
+		const is = classesOf(wears[selector]);
+		const added = is.filter((name) => !was.includes(name));
+		const removed = was.filter((name) => !is.includes(name));
+		if (added.length > 0 || removed.length > 0) {
+			const changes = [...added.map((name) => `+${name}`), ...removed.map((name) => `−${name}`)].join(" ");
+			out.push(`${id} classes${selector === "base" ? "" : ` (${selector})`}: ${changes}`);
+		} else if (was.join(" ") !== is.join(" ")) out.push(`${id} classes${selector === "base" ? "" : ` (${selector})`} reordered`);
+	}
+	const apart = [
+		"parentId",
+		"items",
+		"styleSelectors"
+	];
+	differences(id, without(before.definition, apart), without(after.definition, apart), out);
+};
+/** The elements added to a tree, or taken from it, said by the outermost of each subtree with how many it held. */
+var subtrees = (ids, flat, verb, where, out) => {
+	const top = (id) => {
+		const parentId = flat[id].definition.parentId;
+		return parentId !== void 0 && ids.has(parentId) ? top(parentId) : id;
+	};
+	const held = /* @__PURE__ */ new Map();
+	for (const id of ids) {
+		const root = top(id);
+		held.set(root, (held.get(root) ?? 0) + (root === id ? 0 : 1));
+	}
+	for (const [id, inside] of held) {
+		const { type, parentId } = flat[id].definition;
+		out.push(`${id} (${type}) ${verb}${parentId ? ` ${verb === "added" ? "in" : "from"} ${parentId}` : ""}${where}${inside > 0 ? `, with ${String(inside)} inside` : ""}`);
+	}
+};
+var treeChanges = (before, after, where, out) => {
+	const added = new Set(Object.keys(after).filter((id) => !(id in before)));
+	const removed = new Set(Object.keys(before).filter((id) => !(id in after)));
+	subtrees(added, after, "added", where, out);
+	subtrees(removed, before, "removed", where, out);
+	for (const id of Object.keys(after)) {
+		const was = lookup(before, id);
+		if (was) elementChanges(id, was, after[id], out);
+	}
+};
+var effectsOf = (before, after) => {
+	const out = [];
+	treeChanges(before.schema.flat, after.schema.flat, "", out);
+	const components = /* @__PURE__ */ new Set([...Object.keys(before.schema.components), ...Object.keys(after.schema.components)]);
+	for (const id of components) {
+		const was = lookup(before.schema.components, id);
+		const is = lookup(after.schema.components, id);
+		if (!was || !is) {
+			const held = Object.keys((was ?? is)?.flat ?? {}).length;
+			out.push(`component ${id} ${was ? "removed" : "added"}, ${String(held)} elements`);
+			continue;
+		}
+		treeChanges(was.flat, is.flat, ` (component ${id})`, out);
+		differences(`component ${id}`, without(was, ["flat"]), without(is, ["flat"]), out);
+	}
+	differences("space", without(before.schema, [
+		"flat",
+		"components",
+		"pages"
+	]), without(after.schema, [
+		"flat",
+		"components",
+		"pages"
+	]), out);
+	differences("space.pages", before.schema.pages.filter((id) => after.schema.pages.includes(id)), after.schema.pages.filter((id) => before.schema.pages.includes(id)), out);
+	differences("style", without(before.style, ["cache"]), without(after.style, ["cache"]), out);
+	differences("connectors", before.connectors, after.connectors, out);
+	differences("actions", before.actions, after.actions, out);
+	differences("functions", before.functions, after.functions, out);
+	differences("data", before.data, after.data, out);
+	return out.length > LIMIT ? [...out.slice(0, LIMIT), `… and ${String(out.length - LIMIT)} more changes: read the resources listed in \`changed\``] : out;
+};
+//#endregion
+export { effectsOf };

package/dist/modules/mcp/tools/shared/effects.test.d.ts

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

package/dist/modules/mcp/tools/shared/look.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { ScreenshotImage } from '../../types';
+import { Operation } from '../operations';
+import { ToolContext } from './tool';
+type LookViewport = 'desktop' | 'mobile' | 'both';
+type LookView = 'html' | 'image' | 'accessibility' | 'both';
+export declare const pageRef: z.ZodOptional<z.ZodString>;
+export declare const viewport: z.ZodOptional<z.ZodEnum<{
+    desktop: "desktop";
+    mobile: "mobile";
+    both: "both";
+}>>;
+export declare const fullPage: z.ZodOptional<z.ZodBoolean>;
+type LookRequest = {
+    pageRef?: string;
+    /** A batch to render without saving it; left out, what is saved. */
+    operations?: Operation[];
+    view: LookView;
+    viewport?: LookViewport;
+    fullPage?: boolean;
+};
+/** What a look found: the facts about the page, and the pictures when one was asked for and could be taken. */
+type Look = {
+    meta: Record<string, unknown>;
+    images: ScreenshotImage[];
+};
+/** A look that could not happen at all — no renderer, or a batch the renderer refused — said as the tools say it. */
+type LookRefusal = {
+    refused: Record<string, unknown>;
+};
+export declare const lookAt: (ctx: ToolContext, request: LookRequest) => Promise<Look | LookRefusal>;
+export {};

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

@@ -0,0 +1,128 @@
+import { unnamedControls } from "../../accessibilityOutline.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/shared/look.ts
+/**
+* How a page looks — as HTML, as a picture, or as a screen reader and a browser agent read it — rendered from the saved
+* space or from a batch that was never saved.
+*
+* One path for every tool that shows a page: `plitzi_apply`'s `dryRun` (the batch it just checked, so the agent writes
+* its operations once instead of once to check, once to look and once to save), and `plitzi_look` (what is saved).
+*/
+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 CAPTURES = {
+	image: ["image"],
+	accessibility: ["accessibility"],
+	both: ["image", "accessibility"]
+};
+var pageRef = z.string().optional().describe("The page, by name; defaults to the space default page");
+var 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 fullPage = z.boolean().optional().describe("Capture the full scrollable page instead of only the visible viewport. Default false.");
+/** Each viewport's outline, with what in it has no name — the part an agent acts on. */
+var readingOf = (outlines) => outlines.map(({ label, outline }) => ({
+	viewport: label,
+	outline,
+	unnamed: unnamedControls(outline)
+}));
+var ACCESSIBILITY_HINT = "Every entry in `unnamed` is a control or picture announced by its role alone (\"button\") — nobody using a screen reader, and no browser agent, can tell what it does. Name it — a button: `title` or words inside; a link: `label`; a field: `label` (with `hideLabel` to keep it out of sight); an image: `alt`, or `decorative: true`; an icon that means something alone: `label`. `line` is where it sits in the outline.";
+var lookAt = async (ctx, request) => {
+	if (!ctx.preview || ctx.spaceId === void 0) return { refused: {
+		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 draft = {
+		spaceId: ctx.spaceId,
+		env: ctx.env,
+		pageRef: request.pageRef,
+		operations: request.operations
+	};
+	const page = request.pageRef ?? "default";
+	const wantsHtml = request.view === "html" || !ctx.screenshot;
+	const rendered = await ctx.preview.render({
+		...draft,
+		includeHtml: wantsHtml
+	});
+	if (!rendered.ok) return { refused: rendered };
+	const facts = {
+		pageRef: page,
+		pagePath: rendered.pagePath,
+		stateVersion: rendered.stateVersion
+	};
+	if (request.view === "html") return {
+		meta: {
+			...facts,
+			html: rendered.html
+		},
+		images: []
+	};
+	if (!ctx.screenshot) return {
+		meta: {
+			...facts,
+			warning: "SCREENSHOT_DISABLED",
+			message: request.view === "image" ? "The screenshot service is not configured; returning the HTML preview instead." : "No browser is configured, so the accessibility tree cannot be read; returning the HTML preview instead. Its roles and names are in the markup: every button, link and field needs words, every image an `alt`.",
+			html: rendered.html
+		},
+		images: []
+	};
+	const viewports = resolveViewports(request.viewport);
+	const shot = await ctx.screenshot.capture({
+		pagePath: rendered.pagePath,
+		token: rendered.token,
+		viewports,
+		fullPage: request.fullPage,
+		views: CAPTURES[request.view]
+	});
+	if (!shot.ok) {
+		const fallback = await ctx.preview.render(draft);
+		return {
+			meta: {
+				...facts,
+				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.",
+				html: fallback.ok ? fallback.html : ""
+			},
+			images: []
+		};
+	}
+	const meta = {
+		...facts,
+		viewports: viewports.map((v) => v.label)
+	};
+	const accessibility = request.view === "image" ? {} : shot.accessibility ? {
+		accessibility: readingOf(shot.accessibility),
+		hint: ACCESSIBILITY_HINT
+	} : {
+		warning: "ACCESSIBILITY_UNSUPPORTED",
+		message: "The browser service answered without the accessibility tree — it predates the accessibility view. The image, if asked for, is still here."
+	};
+	return {
+		meta: {
+			...meta,
+			...accessibility
+		},
+		images: request.view === "accessibility" ? [] : shot.images
+	};
+};
+//#endregion
+export { fullPage, lookAt, pageRef, viewport };

package/dist/modules/mcp/tools/shared/normalizeOperations.d.ts

@@ -0,0 +1,6 @@
+import { Space } from '../../helpers';
+import { Operation } from '../operations';
+export declare const normalizeOperations: (space: Space, operations: Operation[]) => {
+    operations: Operation[];
+    notes: string[];
+};

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

@@ -0,0 +1,37 @@
+import { buildTypeRegistry } from "../../catalogs/registry.js";
+import { elementTypeNames } from "../../catalogs/index.js";
+//#region src/modules/mcp/tools/shared/normalizeOperations.ts
+/**
+* What a batch wrote that has one reading, read that way and said: an element type spelt with other capitals
+* (`Heading`) is the type the catalog spells (`heading`). A guess between two names is never made here — a name with a
+* typo is refused, or warned of, with the nearest one, by the checks that come after.
+*/
+/** The element types this space renders: the SDK's own and every one its catalog or its elements bring. */
+var knownTypes = (space) => /* @__PURE__ */ new Set([...Object.keys(buildTypeRegistry(space.schema, space.catalog).types), ...elementTypeNames]);
+var normalizedTree = (element, path, byLowerCase, known, notes) => {
+	const spelt = known.has(element.type) ? void 0 : byLowerCase.get(element.type.toLowerCase());
+	if (spelt) notes.push(`Read element type "${element.type}" as "${spelt}" (${path}.type): write it as the catalog spells it.`);
+	const children = element.children?.map((child, index) => normalizedTree(child, `${path}.children[${String(index)}]`, byLowerCase, known, notes));
+	return {
+		...element,
+		...spelt ? { type: spelt } : {},
+		...children ? { children } : {}
+	};
+};
+var normalizeOperations = (space, operations) => {
+	const known = knownTypes(space);
+	const spellings = /* @__PURE__ */ new Map();
+	for (const type of known) spellings.set(type.toLowerCase(), [...spellings.get(type.toLowerCase()) ?? [], type]);
+	const byLowerCase = new Map([...spellings].flatMap(([lower, types]) => types.length === 1 ? [[lower, types[0]]] : []));
+	const notes = [];
+	const normalized = operations.map((operation, index) => operation.type === "upsertElement" ? {
+		...operation,
+		element: normalizedTree(operation.element, `operations[${String(index)}].element`, byLowerCase, known, notes)
+	} : operation);
+	return {
+		operations: notes.length > 0 ? normalized : operations,
+		notes
+	};
+};
+//#endregion
+export { normalizeOperations };

package/dist/modules/mcp/tools/shared/repeats.d.ts

@@ -0,0 +1,13 @@
+/** One batch, by where it was sent and what it holds. */
+export declare const batchKey: (scope: string, operations: unknown) => string;
+/** How many times this batch was refused lately — before this one. */
+export declare const timesRefused: (key: string, now?: number) => number;
+/** The batch was refused once more. */
+export declare const noteRefused: (key: string, now?: number) => void;
+/** The batch went through: what was refused before no longer counts. */
+export declare const forgetRefused: (key: string) => void;
+export declare const AGAIN: string;
+export declare const REPEATED: {
+    error: string;
+    message: string;
+};

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

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+//#region src/modules/mcp/tools/shared/repeats.ts
+/**
+* The same batch refused again — an agent going round in circles, which a model is not trusted to notice. Counted per
+* process, as a hint and never a lock: a call that lands on another worker only loses the hint.
+*/
+var WINDOW_MS = 6e5;
+var KEPT = 500;
+var refused = /* @__PURE__ */ new Map();
+/** One batch, by where it was sent and what it holds. */
+var batchKey = (scope, operations) => `${scope}:${createHash("sha256").update(JSON.stringify(operations)).digest("hex")}`;
+/** How many times this batch was refused lately — before this one. */
+var timesRefused = (key, now = Date.now()) => {
+	const entry = refused.get(key);
+	return entry && now - entry.at < WINDOW_MS ? entry.count : 0;
+};
+/** The batch was refused once more. */
+var noteRefused = (key, now = Date.now()) => {
+	refused.set(key, {
+		count: timesRefused(key, now) + 1,
+		at: now
+	});
+	if (refused.size > KEPT) {
+		const oldest = refused.keys().next().value;
+		if (oldest !== void 0) refused.delete(oldest);
+	}
+};
+/** The batch went through: what was refused before no longer counts. */
+var forgetRefused = (key) => {
+	refused.delete(key);
+};
+var AGAIN = "This batch was refused before, for these reasons. Sending it again will not change the answer: change what the errors name — plitzi_describe_operation { type } gives an operation’s fields, a hint its way out — or stop and ask the person what they meant.";
+var REPEATED = {
+	error: "REPEATED_BATCH",
+	message: "This exact batch was refused twice, and was not run again. Change what the errors named, or ask the person."
+};
+//#endregion
+export { AGAIN, REPEATED, batchKey, forgetRefused, noteRefused, timesRefused };

package/dist/modules/mcp/tools/shared/tool.d.ts

@@ -24,9 +24,6 @@ export interface ToolContext {
      *  wired it. Only plitzi_try_function uses it. */
     tryFunction?: (task: string, params: Record<string, unknown>) => Promise<ActionRunReport>;
 }
-/** A capability a tool depends on; the host skips registering a tool whose capability it did not wire (so
- *  plitzi_screenshot simply does not appear when no browser service is configured). */
-export type ToolRequires = 'screenshot';
 /** 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. */
 export declare const imageResult: (images: ScreenshotImage[], meta: unknown) => CallToolResult;
@@ -40,8 +37,13 @@ export interface ToolSpec<Shape extends ZodRawShape> {
     description: string;
     inputShape: Shape;
     access: 'read' | 'write';
-    /** A host capability this tool needs; hosts that did not wire it skip registering the tool. */
-    requires?: ToolRequires;
+    /** This tool's input carries the whole operations vocabulary (`plitzi_apply`): the one copy of it a connection lists. */
+    carriesOperations?: boolean;
+    /**
+     * What is LISTED for this tool when another tool on the connection carries the vocabulary: the same input with the
+     * operations' fields left out. Its calls are still parsed against `inputShape`, so nothing is checked less.
+     */
+    compactInputShape?: ZodRawShape;
     /** The tool operates on no space (plitzi_render authors a throwaway one), so the host must NOT resolve a spaceId
      *  or load a space for it — that keeps it callable with no auth, on the public surface. */
     spaceless?: boolean;
@@ -63,7 +65,8 @@ export interface ToolDef {
     description: string;
     inputShape: ZodRawShape;
     access: 'read' | 'write';
-    requires?: ToolRequires;
+    carriesOperations?: boolean;
+    compactInputShape?: ZodRawShape;
     spaceless?: boolean;
     ui?: McpUiToolMeta;
     execute: (args: unknown, ctx: ToolContext) => unknown;

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

@@ -22,7 +22,8 @@ var defineTool = (spec) => {
 		description: spec.description,
 		inputShape: spec.inputShape,
 		access: spec.access,
-		requires: spec.requires,
+		carriesOperations: spec.carriesOperations,
+		compactInputShape: spec.compactInputShape,
 		spaceless: spec.spaceless,
 		ui: spec.ui,
 		execute: (args, ctx) => spec.run(parse(args), ctx),

package/dist/modules/mcp/tools/shared/validator/context.d.ts

@@ -21,7 +21,6 @@ export interface ValidationCtx {
     errors: ValidationError[];
     warnings: string[];
     warned: Set<string>;
-    knownTypes: Set<string>;
     typeProps: Map<string, Set<string>>;
     typeMeta: Map<string, TypeMeta>;
     elementType: (ref: string) => string | undefined;

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

@@ -48,7 +48,6 @@ var checkElementInput = (element, path, ctx, seen) => {
 		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));
 };

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

@@ -2,7 +2,6 @@ import { componentView, findComponentByRef } from "../../../helpers/components.j
 import { findElementByRef, findFolderByRef, findPageByRef, findRootByRef, folderAncestorIds, getLayoutElements, getPageElements, pageFoldersOf, resolveRef, routeParamNames } from "../../../helpers/space.js";
 import { observedDataSources, observedInteractionActions } from "../../../catalogs/observed.js";
 import { buildTypeRegistry } from "../../../catalogs/registry.js";
-import { elementTypeNames } from "../../../catalogs/index.js";
 import { MAX_OPS } from "../../operations/index.js";
 import { batchDeclaredElements, batchDeclaredFolders, batchDeclaredPages, batchDeclaredVariants, batchDeclaredVars } from "./batch.js";
 import { checkObservedName, warnOnce } from "./context.js";
@@ -13,6 +12,7 @@ import { checkRef } from "./refs.js";
 import { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication } from "./elements.js";
 import { checkInteractionNode } from "./interactions.js";
 import { treeOf } from "@plitzi/sdk-schema/helpers/components";
+import { closest } from "@plitzi/sdk-authoring";
 import { isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
 //#region src/modules/mcp/tools/shared/validator/index.ts
 var STYLE_CATEGORIES = [
@@ -49,7 +49,6 @@ var buildValidationCtx = (space, ops, mode = "space") => {
 		errors: [],
 		warnings: [],
 		warned: /* @__PURE__ */ new Set(),
-		knownTypes: /* @__PURE__ */ new Set([...Object.keys(registry.types), ...elementTypeNames]),
 		typeProps: new Map(Object.entries(registry.types).map(([type, info]) => [type, new Set(Object.keys(info.props))])),
 		typeMeta: buildTypeMeta(space.catalog),
 		elementType: (ref) => treeOf(space.schema, ref)?.flat[ref]?.definition.type,
@@ -76,6 +75,28 @@ var validateOperations = (space, ops, mode = "space") => {
 		if (input.type === PROVIDER_TYPE) checkProviderElement(space, ctx, input.ref, input.runtime, input.props, batchConnectors, base);
 		(input.children ?? []).forEach((child, i) => checkProviders(child, `${base}.children[${i}]`));
 	};
+	const classes = /* @__PURE__ */ new Set([...Object.values(space.style.platform).flatMap((breakpoint) => Object.entries(breakpoint).filter(([, item]) => item.type === "class").map(([name]) => name)), ...ops.flatMap((op) => op.type === "upsertDefinition" ? [op.ref] : op.type === "upsertDefinitions" ? Object.keys(op.definitions) : [])]);
+	const checkClasses = (style, path) => {
+		const worn = [...(style?.base ?? []).map((name) => ({
+			name,
+			at: `${path}.base`
+		})), ...Object.entries(style?.slots ?? {}).flatMap(([slot, names]) => names.map((name) => ({
+			name,
+			at: `${path}.slots.${slot}`
+		})))];
+		for (const { name, at } of worn) if (!classes.has(name)) {
+			const nearest = closest(name, classes);
+			ctx.errors.push({
+				path: at,
+				message: `"${name}" is not a class of the space${nearest ? ` — did you mean "${nearest}"?` : ""}`,
+				hint: "Name one of plitzi://definitions/{env}, or declare it earlier in the batch with upsertDefinition"
+			});
+		}
+	};
+	const checkTreeClasses = (input, path) => {
+		checkClasses(input.style, `${path}.style`);
+		(input.children ?? []).forEach((child, i) => checkTreeClasses(child, `${path}.children[${i}]`));
+	};
 	if (ops.length > 1e3) ctx.errors.push({
 		path: "operations",
 		message: `Batch has ${ops.length} operations (max ${MAX_OPS})`,
@@ -103,11 +124,13 @@ var validateOperations = (space, ops, mode = "space") => {
 		switch (op.type) {
 			case "upsertElement":
 				checkElementInput(op.element, `${base}.element`, ctx, /* @__PURE__ */ new Set());
+				checkTreeClasses(op.element, `${base}.element`);
 				checkVariantApplication(op.element.initialState, `${base}.element.initialState`, ctx);
 				checkProviders(op.element, `${base}.element`);
 				break;
 			case "patchElement": {
 				checkRef(op.ref, `${base}.ref`, ctx);
+				checkClasses(op.style, `${base}.style`);
 				const page = findRootByRef(scoped, component ? component.rootId : op.pageRef);
 				const target = page ? resolveRef(scoped, page, op.ref) : void 0;
 				if (op.props && target && target.id !== page?.id) {

package/dist/modules/mcp/types/screenshotTypes.d.ts

@@ -44,9 +44,9 @@ export type ScreenshotInput = {
      */
     views?: CaptureView[];
 };
-/** How plitzi_screenshot reaches the headless-browser service. The consumer injects an implementation (an HTTP
- *  client to the dedicated browser pod); absent → the tool is not registered. A capture that fails (pod down)
- *  returns `ok:false` rather than throwing, so the tool can degrade to the HTML preview. */
+/** How a look reaches the headless-browser service. The consumer injects an implementation (an HTTP
+ *  client to the dedicated browser pod); absent, or a capture that fails (pod down) and answers `ok:false` rather than
+ *  throwing, and the look answers the HTML instead. */
 export type ScreenshotClient = {
     capture: (input: ScreenshotInput) => Promise<ScreenshotResult>;
 };

package/dist/modules/mcp/types/toolTypes.d.ts

@@ -44,6 +44,8 @@ export interface WriteResponse {
         updated: number;
         deleted: number;
     };
+    /** What the batch did, read off the space before and after it: a line per change, nothing left unsaid. */
+    effects?: string[];
     changed: ChangedResource[];
     elements?: WriteElement[];
     warnings?: string[];
@@ -83,10 +85,6 @@ export interface ApplyInput {
     expectedResourceVersions?: Record<string, string>;
     operations: Operation[];
 }
-export interface ValidateInput {
-    environment?: string;
-    operations: Operation[];
-}
 export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];