@plitzi/sdk-server 0.32.3 → 0.32.5

package/dist/index.js

@@ -1,8 +1,21 @@
-import { bindTools, getAllowedModes, isToolActive, resolveToolHandler, toolResponseErr, toolResponseOk, zodToJsonSchema } from "./modules/mcp/helpers.js";
-import { tools_exports } from "./modules/mcp/tools/index.js";
+import { operation } from "./modules/mcp/tools/operations/index.js";
+import { apply, applyShape } from "./modules/mcp/tools/apply/index.js";
+import { read, readShape } from "./modules/mcp/tools/read.js";
+import { search, searchShape } from "./modules/mcp/tools/search.js";
+import { validate, validateShape } from "./modules/mcp/tools/validate.js";
+import { tools } from "./modules/mcp/tools/index.js";
+import { bindTools, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema } from "./modules/ai/toolkit.js";
 import { createMcpServer } from "./modules/mcp/server.js";
-import AIEngine from "./modules/ai/AIEngine.js";
-import { handleMcp, readMcpBody } from "./modules/mcp/handler.js";
-import { createSSRServer } from "./core/createServer.js";
+import { handleMcp, readMcpBody, serveMcp } from "./modules/mcp/handler.js";
+import { createHttpPreviewClient } from "./modules/mcp/previewClient.js";
+import { PREVIEW_TOKEN_PARAM } from "./modules/mcp/constants.js";
+import { createHttpScreenshotClient } from "./modules/mcp/screenshotClient.js";
+import { createMemoryDraftStore, createPreview } from "./modules/ssr/preview.js";
+import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
+import { createMCPServer } from "./core/server/mcpServer.js";
+import { resolveServices } from "./core/services/resolve.js";
+import { createSSRServer } from "./core/server/ssrServer.js";
+import { createServer } from "./core/createServer.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
-export { AIEngine, bindTools, createJsonAdapters, createMcpServer, createSSRServer, getAllowedModes, handleMcp, isToolActive, readMcpBody, resolveToolHandler, toolResponseErr, toolResponseOk, tools_exports as tools, zodToJsonSchema };
+import AIEngine from "./modules/ai/AIEngine.js";
+export { AIEngine, PREVIEW_TOKEN_PARAM, apply, applyShape, bindTools, buildHealthPayload, createHttpPreviewClient, createHttpScreenshotClient, createJsonAdapters, createMCPServer, createMcpServer, createMemoryDraftStore, createPreview, createSSRServer, createServer, getAllowedModes, handleMcp, isCallToolResult, isToolActive, operation, read, readMcpBody, readShape, registerHealthCheck, resolveServices, resolveToolHandler, search, searchShape, serveMcp, toolResponseErr, toolResponseFromResult, toolResponseOk, tools, validate, validateShape, zodToJsonSchema };

package/dist/modules/ai/AIEngine.js

@@ -1,4 +1,4 @@
-import { toolResponseErr } from "../mcp/helpers.js";
+import { firstText, toolResponseErr } from "./toolkit.js";
 //#region src/modules/ai/AIEngine.ts
 var AIEngine = class {
 	mode;
@@ -44,12 +44,12 @@ var AIEngine = class {
 		let resultParsed;
 		if (result.data !== void 0) resultParsed = result.data;
 		else try {
-			resultParsed = JSON.parse(result.content[0]?.text ?? "");
+			resultParsed = JSON.parse(firstText(result.content) ?? "");
 		} catch {}
 		if (result.isError) this.callbacks.onToolError?.({
 			name,
 			args,
-			result: resultParsed ?? { error: result.content[0]?.text ?? "Tool failed" }
+			result: resultParsed ?? { error: firstText(result.content) ?? "Tool failed" }
 		});
 		else this.callbacks.onToolSuccess?.({
 			name,
@@ -96,7 +96,7 @@ var AIEngine = class {
 		if (outputError) this.callbacks.onLog?.("info", `tool output schema drift: ${name} — ${outputError}`);
 		const tool = this.toolsAvailables.get(name);
 		if (!result.isError && tool?.mcpDefinition.outputSchema && result.data !== void 0 && result.data !== null) result.structuredContent = typeof result.data === "object" && !Array.isArray(result.data) ? result.data : { data: result.data };
-		if (result.isError) this.callbacks.onLog?.("error", `tool failed: ${name} error=${result.content[0]?.text ?? "unknown"}`);
+		if (result.isError) this.callbacks.onLog?.("error", `tool failed: ${name} error=${firstText(result.content) ?? "unknown"}`);
 		await this.after(name, args, result);
 		return result;
 	};

package/dist/modules/ai/toolkit.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+//#region src/modules/ai/toolkit.ts
+/** Convert a Zod schema to the JSON Schema an AI provider (Anthropic / OpenAI) expects in a tool definition.
+*  Delegates to Zod v4's built-in converter — one implementation, so descriptions, literal discriminators,
+*  enums, nested objects and recursive (z.lazy) shapes all survive and the provider sees the same contract an
+*  MCP client does. `io: 'input'` describes what the agent must SEND; `unrepresentable: 'any'` degrades an
+*  exotic type to an empty schema instead of throwing, so one unusual tool never breaks the whole tool list. */
+var zodToJsonSchema = (schema) => {
+	const json = z.toJSONSchema(schema, {
+		target: "draft-7",
+		io: "input",
+		unrepresentable: "any"
+	});
+	delete json.$schema;
+	return json;
+};
+var firstText = (content) => content.find((block) => block.type === "text")?.text;
+var getAllowedModes = (operationType) => {
+	return operationType === "write" ? ["build"] : ["plan", "build"];
+};
+var toolResponseOk = (data, agentMessage) => {
+	return {
+		content: [{
+			type: "text",
+			text: agentMessage ?? JSON.stringify(data ?? null, null, 2)
+		}],
+		data
+	};
+};
+var toolResponseErr = (error) => ({
+	content: [{
+		type: "text",
+		text: error instanceof Error ? error.message : error
+	}],
+	isError: true
+});
+var isCallToolResult = (result) => typeof result === "object" && result !== null && Array.isArray(result.content);
+var toolResponseFromResult = (result) => {
+	const content = [];
+	for (const block of result.content) if (block.type === "text") content.push({
+		type: "text",
+		text: block.text
+	});
+	else if (block.type === "image") content.push({
+		type: "image",
+		data: block.data,
+		mimeType: block.mimeType
+	});
+	return {
+		content,
+		isError: result.isError ? true : void 0
+	};
+};
+var isToolActive = (tool) => Boolean(tool.handler);
+var resolveToolHandler = (tool) => tool.handler;
+var bindTools = (tools) => tools.filter(isToolActive);
+//#endregion
+export { bindTools, firstText, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema };

package/dist/modules/mcp/constants.js

@@ -0,0 +1,4 @@
+//#region src/modules/mcp/constants.ts
+var PREVIEW_TOKEN_PARAM = "__pt";
+//#endregion
+export { PREVIEW_TOKEN_PARAM };

package/dist/modules/mcp/handler.js

@@ -1,5 +1,4 @@
 import { createMcpServer } from "./server.js";
-import AIEngine from "../ai/AIEngine.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp";
 //#region src/modules/mcp/handler.ts
 var readMcpBody = (req) => new Promise((resolve, reject) => {
@@ -16,38 +15,33 @@ var readMcpBody = (req) => new Promise((resolve, reject) => {
 	});
 	req.on("error", reject);
 });
-var handleMcp = async (req, res, config, server, transport, context) => {
-	if (!server) {
-		const ctx = context ?? {
-			userId: 0,
-			spaceId: 0,
-			environment: "main",
-			mode: "plan"
-		};
-		const engine = new AIEngine(ctx.mode, {}, ctx);
-		server = createMcpServer(config.adapters, engine, config.tools, config.prompts);
-	}
-	if (!transport) transport = new StreamableHTTPServerTransport({
+var serveMcp = async (raw, res, server) => {
+	const transport = new StreamableHTTPServerTransport({
 		sessionIdGenerator: void 0,
 		enableJsonResponse: true
 	});
 	await server.connect(transport);
 	try {
-		if (req.method === "POST") {
-			let body;
-			if (req.body !== void 0) body = req.body;
-			else try {
-				body = await readMcpBody(req);
+		if (raw.method === "POST") {
+			let body = raw.body;
+			if (body === void 0) try {
+				body = await readMcpBody(raw);
 			} catch {
 				res.writeHead(400, { "Content-Type": "application/json" });
 				res.end(JSON.stringify({ error: "Invalid JSON body" }));
 				return;
 			}
-			await transport.handleRequest(req, res, body);
-		} else await transport.handleRequest(req, res);
+			await transport.handleRequest(raw, res, body);
+		} else await transport.handleRequest(raw, res);
 	} finally {
 		await transport.close();
 	}
 };
+var handleMcp = (raw, res, req, adapters, preview, screenshot) => serveMcp(raw, res, createMcpServer({
+	adapters,
+	getSpaceId: () => adapters.getSpaceId?.(req) ?? Promise.resolve(void 0),
+	preview,
+	screenshot
+}));
 //#endregion
-export { handleMcp, readMcpBody };
+export { createMcpServer, handleMcp, readMcpBody, serveMcp };

package/dist/modules/mcp/helpers/computeVersion.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+//#region src/modules/mcp/helpers/computeVersion.ts
+var canonicalize = (data) => {
+	if (data === null || data === void 0) return "null";
+	if (typeof data === "string") return JSON.stringify(data);
+	if (typeof data === "number" || typeof data === "boolean") return String(data);
+	if (Array.isArray(data)) return `[${data.map(canonicalize).join(",")}]`;
+	if (typeof data === "bigint") return data.toString();
+	if (typeof data === "object") return `{${Object.keys(data).sort().map((k) => `${canonicalize(k)}:${canonicalize(data[k])}`).join(",")}}`;
+	return "null";
+};
+var computeVersion = (data) => {
+	return createHash("sha1").update(canonicalize(data)).digest("hex").slice(0, 12);
+};
+//#endregion
+export { computeVersion };

package/dist/modules/mcp/helpers/guide.js

@@ -0,0 +1,130 @@
+//#region src/modules/mcp/helpers/guide.ts
+var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Refs accept a semantic aiRef or the raw id. CSS is kebab-case (shorthands like border/padding are accepted); style vars are var(--name), schema vars are {{name}}.";
+var guideText = `# Plitzi AI MCP — usage guide
+
+A Plitzi space is **two separate schemas** you edit together:
+- **Element schema** — the tree of pages and elements (their type, label, props, and which style classes they use).
+- **Style schema** — reusable **definitions** (CSS classes), design tokens (variables), theme.
+
+They are stored and persisted independently, but a single \`plitzi_apply\` batch may touch **both atomically**.
+To style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**
+it via the element's \`style.base\` (element schema). Example — "rename button X to PEPE and make it red":
+\`\`\`json
+{ "operations": [
+  { "type": "upsertDefinition", "ref": "btn-x", "desktop": { "color": "red" } },
+  { "type": "upsertElement", "pageRef": "home",
+    "element": { "ref": "X", "type": "button", "label": "PEPE", "style": { "base": ["btn-x"] } } }
+] }
+\`\`\`
+
+Reads are cheap by design — treat them like a filesystem: **list** to navigate, **read one item** for detail.
+Never download a whole tree you do not need.
+
+## Resources (read)
+- \`plitzi://primer/{env}\` — **cold-start bundle**: guide + types + css-properties + page/definition/variable
+  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only — open a
+  page skeleton or element for its tree/detail.
+- \`plitzi://guide\` — this guide.
+- \`plitzi://types\` — element types **observed in this space** (ground truth): props, slots, subTypes.
+- \`plitzi://css-properties\` — valid kebab-case CSS property keys.
+- \`plitzi://schema/{env}/pages\` — page **summaries** (ref, label, elementCount, folder). No element trees.
+- \`plitzi://folders/{env}\` — page **folders** (the sidebar tree): ref, name, slug, parentId. \`/{ref}\` for one.
+- \`plitzi://schema/{env}/pages/{ref}\` — one page as a **skeleton tree**: each node is \`ref/type/label\` **plus the
+  style classes it attaches** (\`base\`, and \`slots\` for non-base slots) — names only, no CSS. So you can map every
+  element to its class in a single page read, without opening each element just to learn which class it uses.
+- \`plitzi://schema/{env}/pages/{ref}/styles\` — **every style the page uses in one read**: the class definitions its
+  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.
+  Reach for this to recolor/restyle a whole page — it needs no shared class-name prefix and no per-element reads.
+- \`plitzi://schema/{env}/elements/{ref}\` — one element in **full detail** (props, style, parentRef, childRefs).
+  Its \`resolvedStyle\` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you
+  can see and edit its style without a separate definition read. Its \`globalStyles\` lists the **global element
+  selectors** that also affect it (the CSS equivalent of \`button { … }\`, keyed by the type they target) — every
+  element of that type inherits them. Edit a global only through the global-style tools (never per element).
+- \`plitzi://definitions/{env}\` — the **names** of every style definition.
+- \`plitzi://definitions/{env}/{ref}\` — one definition's CSS.
+- \`plitzi://global-styles/{env}\` — element **types** that have a site-wide global style. \`/{componentType}\` for one.
+- \`plitzi://style-variables/{env}\` — design tokens by category. \`/{category}\` for one.
+- \`plitzi://schema-variables/{env}\` — space-level values referenced in props as \`{{name}}\`.
+
+The style resources also answer under the \`plitzi://schema/{env}/…\` root as aliases — \`plitzi://schema/{env}/definitions/{ref}\`, \`plitzi://schema/{env}/style-variables/{category}\`, \`plitzi://schema/{env}/schema-variables\` — but prefer the ready-made \`uri\` from search / a write response over hand-building either form.
+
+Data resources return \`{ stateVersion, data }\`. Keep \`stateVersion\` for optimistic concurrency.
+
+## Navigating (files analogy)
+Pages and containers are folders; elements are files. **Prefer \`plitzi_search\` (especially with \`include: "detail"\`)
+over reading elements one by one** — it jumps straight to elements by label/type/attribute and each hit already
+carries the element's \`uri\`, \`stateVersion\`, \`pageUri\`, \`parentRef\` and tree \`path\`, so you can edit it (with
+optimistic concurrency) **without a follow-up read**. \`include: "detail"\` additionally inlines each hit's props/style
+**and** its \`resolvedStyle\` (the CSS behind its classes) — so a search-then-edit is the efficient path and a manual
+element read is the exception. Search also matches **pages** by name/slug (returned under \`pages\`, each with its uri +
+stateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under \`definitions\`.
+When you do hold several refs to open (e.g. from a skeleton), read them together with \`plitzi_read\` rather than one at a time.
+
+## Tools (write)
+- \`plitzi_validate\` — check a batch, returns teachable errors/warnings. Writes nothing.
+- \`plitzi_apply\` — validate → apply → persist atomically. Rejects the whole batch on any error or conflict. Pass
+  \`dryRun: true\` to apply in memory only and get the same result back (changed versions + full element detail)
+  without persisting — inspect it, then re-run without \`dryRun\` to commit.
+- \`plitzi_search\` — find elements (and pages/definitions) across the space.
+- \`plitzi_read\` — read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the
+  ready-made uris from search / a write response; each result is \`{ uri, stateVersion, data }\` or a teachable error,
+  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.
+
+Write tools return what **changed** (\`{ uri, stateVersion }\`) plus counts, and the **full detail of every element
+they created or updated** — each with its own \`uri\` and \`stateVersion\` (\`elements: [...]\`) so a follow-up edit of
+the same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only
+uri+stateVersion — re-read them if you need their new content. The operation shapes are in each tool's input
+schema (discriminated by \`type\`).
+
+## Addressing
+Refs are a semantic \`aiRef\` you choose (e.g. \`"hero.cta"\`) or the element's **raw id**. Both always resolve, so
+schemas predating aiRef keep working through ids. Creating an element stores its \`ref\` as the aiRef.
+
+## Styling (crosses both schemas)
+- A definition lives in the **style schema**; an element's \`style.base\` (element schema) is the link that applies
+  it. Styling an element = upsertDefinition + upsertElement with that ref in \`style.base\`, in one batch.
+- CSS keys are **kebab-case** (\`background-color\`). camelCase is rejected — read \`plitzi://css-properties\`.
+- Common **shorthands are accepted** and expanded for you: \`border\`, \`border-{side}\`, \`border-radius\`,
+  \`padding\`, \`margin\`, \`inset\`, \`gap\` (they persist as their longhand keys).
+- CSS is grouped by breakpoint: \`desktop\`, \`tablet\`, \`mobile\`.
+- Reference a style variable in CSS as \`var(--name)\`; a schema variable in a prop as \`{{name}}\`.
+- \`element.style.base\` is a list of definition refs; other slots go under \`element.style.slots\`.
+- **Two kinds of style live in the style schema — do not confuse them:**
+  - **Definitions** = reusable CSS **classes** (\`upsertDefinition\`/\`patchDefinition\`/\`deleteDefinition\`, keyed by a
+    class \`ref\`). Attach one to an element via \`style.base\` to style **that** element (and anything else that opts in).
+  - **Global styles** = the CSS equivalent of a bare element selector like \`button { … }\`
+    (\`upsertGlobalStyle\`/\`patchGlobalStyle\`/\`deleteGlobalStyle\`, keyed by \`componentType\`). They style **every**
+    element of that type at once. Use these for site-wide intent — e.g. "all buttons rounded":
+    \`{ "type": "upsertGlobalStyle", "componentType": "button", "desktop": { "border-radius": "9999px" } }\`.
+  - The two share one name space, so a class op refuses a name held by a global and vice-versa (guards against a
+    typo silently rewriting every element of a type). If refused, you targeted the wrong kind — switch tools or
+    rename. To style one element only, never reach for a global.
+
+## Pages & folders
+Pages can be grouped into **folders** (the sidebar tree). A folder is \`{ ref, name, slug, parentId? }\`; its \`ref\`
+**is its id** (there is no separate aiRef), and that id is what a page and a nested folder reference.
+- Create/rename/move a folder with \`upsertFolder\` (the \`ref\` you pass on create becomes its id — pick a stable one
+  like \`"blog"\`). Nest it under another with \`parentId\` (a folder ref); \`parentId: null\` moves it back to the root.
+- Put a page in a folder with \`upsertPage\`'s \`folder\` (a folder ref). A page's \`folder\` is always either **empty
+  (root)** or an **existing folder id**: \`folder: null\` or \`folder: ""\` moves it to the root, and any other value
+  must resolve to a folder that already exists or is created earlier in the same batch — an unknown folder is
+  rejected, never stored.
+- \`deleteFolder\` removes a folder and **promotes its contents up one level** — its child folders and its pages move
+  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.
+
+## Semantics
+- **props are fully replaced** on \`upsertElement\`: send every prop you want to keep. To change only some props,
+  use **\`patchElement\`** — it merges \`props\`/\`style\` onto the existing element (listed keys change, \`null\` unsets
+  a key, everything else is preserved) and never creates. Combined with \`plitzi_search\` (which returns the ref +
+  stateVersion), a targeted edit is two calls with no read.
+- **definition CSS is fully replaced** on \`upsertDefinition\`: send every property you want to keep. To change only
+  some declarations, use **\`patchDefinition\`** — it merges CSS per breakpoint/state/variant/slot onto the existing
+  definition (listed keys change, \`null\` removes a property, everything else is preserved) and never creates.
+  Example — recolor one definition without resending it: \`{ "type": "patchDefinition", "ref": "btn-x",
+  "desktop": { "background-color": "#111" } }\`.
+- **Atomic batches**: if any operation fails, \`plitzi_apply\` persists nothing.
+- **Optimistic concurrency**: pass \`expectedResourceVersions\` (URI → the stateVersion you read). If the live data
+  drifted, apply is rejected with a conflict; re-read the reported resources and retry.
+`;
+//#endregion
+export { guideText, serverInstructions };

package/dist/modules/mcp/helpers/opResult.js

@@ -0,0 +1,18 @@
+//#region src/modules/mcp/helpers/opResult.ts
+var empty = () => ({
+	created: 0,
+	updated: 0,
+	deleted: 0,
+	staleResources: []
+});
+var fail = (path, message, hint, validValues) => ({
+	...empty(),
+	errors: [{
+		path,
+		message,
+		hint,
+		validValues
+	}]
+});
+//#endregion
+export { empty, fail };

package/dist/modules/mcp/helpers/space.js

@@ -0,0 +1,137 @@
+//#region src/modules/mcp/helpers/space.ts
+var cloneSpace = (space) => structuredClone(space);
+var slugify = (value) => value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "";
+var isPageElement = (schema, el) => schema.pages.includes(el.id) || el.definition.type === "page";
+var getPageElements = (schema) => Object.values(schema.flat).filter((el) => isPageElement(schema, el));
+/** Stable, human-readable ref for a page. Prefers an agent-chosen aiRef, then slug, then a slugified label. */
+var pageRefOf = (el) => {
+	if (el.definition.aiRef) return el.definition.aiRef;
+	const slug = typeof el.attributes.slug === "string" ? el.attributes.slug.trim() : "";
+	if (slug) return slugify(slug);
+	if (el.attributes.default === true) return "home";
+	return slugify(typeof el.attributes.name === "string" ? el.attributes.name : el.definition.label) || el.id;
+};
+/** Stable ref for a non-page element. An agent-chosen aiRef when present, otherwise the opaque id. */
+var elementRefOf = (el) => el.definition.aiRef ?? el.id;
+/** Finds a page by its semantic ref (aiRef/slug/…) or its raw id, so legacy schemas without an aiRef still resolve. */
+var findPageByRef = (schema, pageRef) => getPageElements(schema).find((el) => pageRefOf(el) === pageRef || el.id === pageRef);
+var pageFoldersOf = (schema) => {
+	schema.pageFolders ??= [];
+	return schema.pageFolders;
+};
+/** Resolve a folder by its id, or (for agent convenience) by an exact name or slug when that is unambiguous. */
+var findFolderByRef = (schema, ref) => {
+	const folders = pageFoldersOf(schema);
+	const byId = folders.find((f) => f.id === ref);
+	if (byId) return byId;
+	const byName = folders.filter((f) => f.name === ref);
+	if (byName.length === 1) return byName[0];
+	const bySlug = folders.filter((f) => f.slug === ref);
+	return bySlug.length === 1 ? bySlug[0] : void 0;
+};
+/** Order folders so every parent precedes its children — the invariant the schema validator enforces on
+*  pageFolders (a parentId must appear earlier in the array). Cycles (rejected upstream) are left in place. */
+var sortFolders = (folders) => {
+	const byId = new Map(folders.map((f) => [f.id, f]));
+	const placed = /* @__PURE__ */ new Set();
+	const result = [];
+	const visit = (folder, ancestry) => {
+		if (placed.has(folder.id)) return;
+		const parent = folder.parentId ? byId.get(folder.parentId) : void 0;
+		if (parent && !ancestry.has(parent.id)) visit(parent, new Set(ancestry).add(folder.id));
+		if (!placed.has(folder.id)) {
+			placed.add(folder.id);
+			result.push(folder);
+		}
+	};
+	for (const folder of folders) visit(folder, /* @__PURE__ */ new Set([folder.id]));
+	return result;
+};
+/** Ancestor ids of a folder (following parentId), stopping on a cycle. Used to reject a parent change that would
+*  make a folder its own ancestor. */
+var folderAncestorIds = (folders, startParentId) => {
+	const byId = new Map(folders.map((f) => [f.id, f]));
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set();
+	let current = startParentId ? byId.get(startParentId) : void 0;
+	while (current && !seen.has(current.id)) {
+		seen.add(current.id);
+		chain.push(current.id);
+		current = current.parentId ? byId.get(current.parentId) : void 0;
+	}
+	return chain;
+};
+/** Route params a page's slug binds (e.g. ":spaceId/update/*" → ["spaceId"]). These are valid {{name}}
+*  references on that page even though they are not space-level schema variables. */
+var slugRouteParams = (slug) => {
+	const params = [];
+	for (const segment of slug.split("/")) if (segment.startsWith(":")) params.push(segment.slice(1).replace(/[*+?]+$/, ""));
+	return params;
+};
+/** Every route param bound by any page slug in the space (union), so {{name}} validation does not false-flag a
+*  page-scoped dynamic binding. */
+var routeParamNames = (schema) => {
+	const params = /* @__PURE__ */ new Set();
+	for (const page of getPageElements(schema)) {
+		const slug = typeof page.attributes.slug === "string" ? page.attributes.slug : "";
+		for (const param of slugRouteParams(slug)) params.add(param);
+	}
+	return [...params];
+};
+/** Indexed lookup that reflects the runtime reality: a flat id may be dangling (rsc placeholders, stale items). */
+var elementById = (schema, id) => schema.flat[id];
+/** All element ids belonging to a page subtree (excluding the page root). */
+var collectDescendants = (schema, rootId, acc) => {
+	const el = elementById(schema, rootId);
+	if (!el) return;
+	const childIds = el.definition.items ?? [];
+	for (const childId of childIds) if (elementById(schema, childId)) {
+		acc.push(childId);
+		collectDescendants(schema, childId, acc);
+	}
+};
+var descendantIds = (schema, pageRootId) => {
+	const acc = [];
+	collectDescendants(schema, pageRootId, acc);
+	return acc;
+};
+/** Resolve a ref to a concrete element within a page subtree (or the page root itself). Accepts either the
+*  semantic ref (aiRef) or the raw element id, so schemas predating aiRef keep working through their ids. */
+var resolveRef = (schema, page, ref) => {
+	if (elementRefOf(page) === ref || pageRefOf(page) === ref || page.id === ref) return page;
+	for (const id of descendantIds(schema, page.id)) {
+		const el = elementById(schema, id);
+		if (el && (elementRefOf(el) === ref || el.id === ref)) return el;
+	}
+};
+/** Ordered children of an element, honoring definition.items and skipping dangling ids. */
+var orderedChildren = (schema, el) => {
+	return (el.definition.items ?? []).map((id) => schema.flat[id]).filter((child) => Boolean(child));
+};
+/** The page ref an element belongs to, walking up parents. 'unknown' when it has no page ancestor. */
+var pageRefOfElement = (schema, el) => {
+	let current = el;
+	const guard = /* @__PURE__ */ new Set();
+	while (current && !guard.has(current.id)) {
+		guard.add(current.id);
+		if (isPageElement(schema, current)) return pageRefOf(current);
+		current = current.definition.parentId ? schema.flat[current.definition.parentId] : void 0;
+	}
+	return "unknown";
+};
+/** Find any non-page element by its semantic ref (aiRef) or raw id, across the whole space. */
+var findElementByRef = (schema, ref) => {
+	for (const el of Object.values(schema.flat)) {
+		if (isPageElement(schema, el)) continue;
+		if (elementRefOf(el) === ref || el.id === ref) return el;
+	}
+};
+/** Total number of descendant elements under a subtree (excluding the root). */
+var descendantCount = (schema, rootId) => descendantIds(schema, rootId).length;
+var emptySpaceMessage = "Space data not available";
+var unauthorizedSpaceMessage = "This tool/resource needs a space, but no spaceId could be resolved from the Authorization token";
+var generateObjectId = () => {
+	return `${Math.floor(Date.now() / 1e3).toString(16).padStart(8, "0")}${Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("")}`;
+};
+//#endregion
+export { cloneSpace, descendantCount, descendantIds, elementById, elementRefOf, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, isPageElement, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, unauthorizedSpaceMessage };

package/dist/modules/mcp/previewClient.js

@@ -0,0 +1,31 @@
+//#region src/modules/mcp/previewClient.ts
+/** Default `PreviewClient`: POSTs the preview request to the SSR `/preview` endpoint over HTTP. Used when the
+*  MCP server is a separate process from the SSR renderer (the common case). A network/HTTP failure surfaces as
+*  an `ok:false` result rather than throwing, so the calling tool can degrade gracefully. */
+var createHttpPreviewClient = ({ url, secret, fetchImpl = fetch }) => ({ async render(body) {
+	let res;
+	try {
+		res = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...secret ? { "x-preview-secret": secret } : {}
+			},
+			body: JSON.stringify(body)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: "PREVIEW_UNREACHABLE",
+			message: `Preview endpoint unreachable: ${String(err)}`
+		};
+	}
+	if (!res.ok && res.status !== 422) return {
+		ok: false,
+		error: "PREVIEW_REQUEST_FAILED",
+		message: `Preview endpoint returned ${res.status}.`
+	};
+	return await res.json();
+} });
+//#endregion
+export { createHttpPreviewClient };

package/dist/modules/mcp/resources/canonical.js

@@ -0,0 +1,45 @@
+//#region src/modules/mcp/resources/canonical.ts
+var ALIASED_ROOTS = [
+	"definitions",
+	"global-styles",
+	"style-variables",
+	"schema-variables",
+	"folders"
+];
+var canonicalUri = (env, uri) => {
+	const aliasPrefix = `plitzi://schema/${env}/`;
+	if (!uri.startsWith(aliasPrefix)) return uri;
+	const rest = uri.slice(aliasPrefix.length);
+	for (const root of ALIASED_ROOTS) {
+		if (rest === root) return `plitzi://${root}/${env}`;
+		if (rest.startsWith(`${root}/`)) return `plitzi://${root}/${env}/${rest.slice(root.length + 1)}`;
+	}
+	return uri;
+};
+var itemTemplates = (env) => [
+	`plitzi://schema/${env}/pages/{ref}`,
+	`plitzi://schema/${env}/elements/{ref}`,
+	`plitzi://definitions/${env}/{ref}`,
+	`plitzi://global-styles/${env}/{componentType}`,
+	`plitzi://style-variables/${env}/{category}`,
+	`plitzi://folders/${env}/{ref}`
+];
+/** Teachable message for a URI that read as null. Distinguishes a well-formed URI whose ref does not resolve (the
+*  resource may be stale/deleted) from a URI whose shape matches no template at all (malformed — echo the valid
+*  templates so the agent stops hand-building URIs). See RFC 0004 I2. */
+var resourceErrorMessage = (env, uri) => {
+	const canonical = canonicalUri(env, uri);
+	if (itemTemplates(env).some((tpl) => canonical.startsWith(tpl.slice(0, tpl.lastIndexOf("/") + 1)))) return JSON.stringify({
+		error: "NOT_FOUND",
+		message: `No resource at '${uri}'. Its shape is valid but the ref does not resolve.`,
+		hint: "It may have been deleted or your URI is stale. Re-list the parent resource (pages/definitions) to refresh."
+	});
+	return JSON.stringify({
+		error: "MALFORMED_URI",
+		message: `'${uri}' matches no resource template.`,
+		hint: "Do not hand-build element URIs — take the ready-made uri from plitzi_search or a write response.",
+		validTemplates: [`plitzi://primer/${env}`, ...itemTemplates(env)]
+	});
+};
+//#endregion
+export { canonicalUri, itemTemplates, resourceErrorMessage };

package/dist/modules/mcp/resources/core.js

@@ -0,0 +1,14 @@
+import { guideText } from "../helpers/guide.js";
+import { envelope } from "./envelope.js";
+import { cssProperties } from "../tools/operations/style/cssCatalog.js";
+import { buildTypeRegistry } from "../tools/operations/schema/registry.js";
+//#region src/modules/mcp/resources/core.ts
+/** Space-independent singletons: the usage guide, the observed type registry and the CSS property catalog.
+*  Returns undefined when the URI is not one of these, so the router falls through to the next resolver. */
+var readCoreResource = (space, uri) => {
+	if (uri === "plitzi://guide") return envelope(guideText);
+	if (uri === "plitzi://types") return envelope(buildTypeRegistry(space.schema));
+	if (uri === "plitzi://css-properties") return envelope(cssProperties);
+};
+//#endregion
+export { readCoreResource };

package/dist/modules/mcp/resources/envelope.js

@@ -0,0 +1,14 @@
+import { computeVersion } from "../helpers/computeVersion.js";
+//#region src/modules/mcp/resources/envelope.ts
+/** Wrap any read projection with the version its optimistic-concurrency checks key on. */
+var envelope = (data) => ({
+	stateVersion: computeVersion(data),
+	data
+});
+var jsonContents = (uri, data) => ({ contents: [{
+	uri,
+	mimeType: "application/json",
+	text: JSON.stringify(data)
+}] });
+//#endregion
+export { envelope, jsonContents };

package/dist/modules/mcp/resources/primer.js

@@ -0,0 +1,25 @@
+import { guideText } from "../helpers/guide.js";
+import { envelope } from "./envelope.js";
+import { cssProperties } from "../tools/operations/style/cssCatalog.js";
+import { buildTypeRegistry } from "../tools/operations/schema/registry.js";
+import { definitionRefs, styleVariablesToAI } from "../tools/operations/style/translator.js";
+import { foldersToAI, pageSummariesToAI, schemaVariablesToAI } from "../tools/operations/schema/translator.js";
+//#region src/modules/mcp/resources/primer.ts
+/** The cold-start bundle: everything the guide says to read before the first write, in one round-trip.
+*  Summaries only — never full page/element trees (those are opened on demand), so it stays cheap even on a
+*  large space. Returns undefined when the URI is not the primer. */
+var readPrimerResource = (space, env, uri) => {
+	if (uri !== `plitzi://primer/${env}`) return;
+	return envelope({
+		guide: guideText,
+		types: buildTypeRegistry(space.schema),
+		cssProperties,
+		pages: pageSummariesToAI(space.schema),
+		folders: foldersToAI(space.schema),
+		definitions: definitionRefs(space.style),
+		styleVariables: styleVariablesToAI(space.style),
+		schemaVariables: schemaVariablesToAI(space.schema, false)
+	});
+};
+//#endregion
+export { readPrimerResource };