@plitzi/sdk-mcp 0.38.6 → 0.38.8

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

@@ -2,7 +2,7 @@ import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
 import { emptySpace } from "../helpers/space.js";
 import { proxifyResources } from "../proxy/rewrite.js";
-import { documentOperations } from "./operations/index.js";
+import { compactDocumentOperations, documentOperations } from "./operations/index.js";
 import { draftBatch } from "./shared/draftBatch.js";
 import { defineTool } from "./shared/tool.js";
 import { interactionReport } from "./shared/interactionReport.js";
@@ -146,6 +146,10 @@ var renderTool = defineTool({
 	title: "Render widget",
 	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look, not per property.\n2a. GRAPHICS — a logo, a sparkline, a badge, a decorative shape: draw it as an INLINE <svg> in a blockHtml element (props.content), keeping a viewBox with width/height \"100%\" so its class sizes it, and fill/stroke \"currentColor\" so it follows the host theme. Budget it: a handful of paths, drawn once and reused, never a data: URI and never a full illustration — a photo-real scene costs more than the whole widget, so use an https image, a flat colour or a gradient for that. Markup only: scripts and on* handlers are rejected.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. Write real https URLs: everything the widget loads from outside (images, media, fonts, an apiContainer endpoint) is fetched for it by the render server, so redirects and hotlink rules are handled and there is nothing to configure. It must still point at the actual file — use a URL you have seen work, and when you have none, draw the block with a gradient or an inline SVG instead of guessing one. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user), plus — when the widget has interaction flows — an `interactions` line per flow naming what got wired to what. That reports the WIRING, not that a click was performed: say what you connected, never that you verified it at runtime. On failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
+	compactInputShape: {
+		...renderShape,
+		operations: compactDocumentOperations
+	},
 	access: "read",
 	spaceless: true,
 	ui: { resourceUri: RENDER_APP_URI },

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

@@ -17,9 +17,10 @@ export type DraftResult = {
 };
 /**
  * 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.

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