@plitzi/sdk-server 0.32.18 → 0.32.19

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @plitzi/sdk-server
 
+## 0.32.19
+
+### Patch Changes
+
+- v0.32.19
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.19
+  - @plitzi/sdk-schema@0.32.19
+  - @plitzi/sdk-shared@0.32.19
+
 ## 0.32.18
 
 ### Patch Changes

package/README.md

@@ -839,6 +839,24 @@ When `devMode: true`, per-phase timing is instrumented on every render and repor
 
 In production (`devMode: false`) timing instrumentation is skipped entirely — no `Server-Timing` header, no console output.
 
+## Agent skill
+
+This package ships an [Agent Skill](https://agentskills.io/) for `plitzi_render`, the MCP tool that renders a
+self-contained UI widget from a batch of operations. The skill teaches an agent when to show a widget instead of
+writing prose, the shape of a good call, the layout/theme traps that make a widget look wrong in a chat panel, and
+how to iterate on a widget it already rendered.
+
+It lives in [`skills/plitzi-render`](./skills/plitzi-render/SKILL.md) and is a plain `SKILL.md`, so it installs by
+copying that folder into the skills directory of the agent you use (Claude Code, VS Code / Copilot, Codex, Gemini
+CLI, Cline, Goose…):
+
+```bash
+cp -R node_modules/@plitzi/sdk-server/skills/plitzi-render ~/.claude/skills/
+```
+
+The skill only pays off with the Plitzi MCP server connected — it defers every detail to the `plitzi://render/guide`
+resource the server publishes, so the two never drift apart.
+
 ## Exported types
 
 ```ts

package/dist/modules/mcp/apps/render/index.js

@@ -1,3 +1,4 @@
+import { VIEW_DIR } from "../shared/assets.js";
 import { require } from "../shared/resolve.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,7 +10,7 @@ var renderApp = {
 	name: "plitzi-render-app",
 	title: "Plitzi widget",
 	description: "Interactive view that renders a plitzi_render widget with the Plitzi SDK.",
-	entry: path.join(HERE, "view.tsx"),
+	entry: path.join(HERE, VIEW_DIR, "index.tsx"),
 	styles: () => [path.join(path.dirname(require.resolve("@plitzi/plitzi-sdk")), "plitzi-sdk.css")]
 };
 //#endregion

package/dist/modules/mcp/apps/render/view/heldBatch.ts

@@ -0,0 +1,107 @@
+/** Where the batch a widget was built from survives between calls — on the HOST, so the server can keep nothing.
+ *
+ *  It cannot live in the view's memory: the Apps spec binds a view to ONE tool call (`ui/notifications/tool-input`
+ *  is sent "at most once", and the host renders a fresh iframe when a UI tool is called), so the patch call the
+ *  model makes arrives in a brand-new instance whose memory is empty. localStorage keyed by an id the server hands
+ *  back is the spec's own state-persistence pattern (`_meta.viewUUID` in the Apps docs); here the key is the
+ *  renderId, which the model also carries, so a patch names the widget it means instead of assuming "the last one".
+ */
+
+const PREFIX = 'plitzi.render.';
+const MAX_ENTRIES = 5;
+// A renderId only lives in one conversation's context, so a batch outlives its usefulness the moment that
+// conversation is over — and a conversation the user abandoned would otherwise leave its widget in the host's
+// storage for good. Generous enough that no live conversation loses its widget, short enough to be housekeeping.
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+type Stored = { savedAt: number; operations: unknown[] };
+
+// A sandboxed iframe without allow-same-origin throws on the ACCESS to localStorage, not on the call — so even
+// reading the property has to be guarded. A host that denies storage simply gets no patching.
+const localStore = (): Storage | undefined => {
+  try {
+    return window.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+const parse = (raw: string | null): Stored | undefined => {
+  if (raw === null) {
+    return undefined;
+  }
+
+  try {
+    const value = JSON.parse(raw) as Stored;
+
+    return Array.isArray(value.operations) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const ownKeys = (store: Storage): string[] => {
+  const keys: string[] = [];
+  for (let index = 0; index < store.length; index += 1) {
+    const key = store.key(index);
+    if (key !== null && key.startsWith(PREFIX)) {
+      keys.push(key);
+    }
+  }
+
+  return keys;
+};
+
+const dropStale = (store: Storage, keep: string): void => {
+  const others = ownKeys(store)
+    .filter(key => key !== keep)
+    .map(key => ({ key, savedAt: parse(store.getItem(key))?.savedAt ?? 0 }))
+    .sort((a, b) => b.savedAt - a.savedAt);
+  const expired = Date.now() - MAX_AGE_MS;
+
+  for (const [index, entry] of others.entries()) {
+    if (index >= MAX_ENTRIES - 1 || entry.savedAt < expired) {
+      store.removeItem(entry.key);
+    }
+  }
+};
+
+export const readHeldBatch = (renderId: string, store = localStore()): unknown[] | undefined => {
+  if (!store) {
+    return undefined;
+  }
+
+  const stored = parse(store.getItem(`${PREFIX}${renderId}`));
+  if (!stored || stored.savedAt < Date.now() - MAX_AGE_MS) {
+    return undefined;
+  }
+
+  return stored.operations;
+};
+
+export const writeHeldBatch = (renderId: string, operations: unknown[], store = localStore()): void => {
+  if (!store) {
+    return;
+  }
+
+  const key = `${PREFIX}${renderId}`;
+  const payload = JSON.stringify({ savedAt: Date.now(), operations } satisfies Stored);
+
+  try {
+    dropStale(store, key);
+    store.setItem(key, payload);
+  } catch {
+    // Out of quota: the widget just rendered is the only one still worth patching, so the rest go.
+    for (const other of ownKeys(store)) {
+      if (other !== key) {
+        store.removeItem(other);
+      }
+    }
+
+    try {
+      store.setItem(key, payload);
+    } catch {
+      // Storage is full or refused: patching degrades to "re-send the full batch", never to a wrong widget.
+    }
+  }
+};

package/dist/modules/mcp/apps/shared/assets.js

@@ -0,0 +1,10 @@
+import "node:path";
+//#region src/modules/mcp/apps/shared/assets.ts
+/** The one folder of an app that ships to dist as SOURCE: its browser entry (`view/index.tsx`) and every module
+*  that entry bundles. The server builds it with esbuild at request time, so none of it is in the module graph the
+*  library build compiles — a view-side module that does not travel verbatim is simply missing at runtime, which
+*  the package only finds out when a host asks for the page. Everything else in an app (its definition) compiles
+*  like any other module. */
+var VIEW_DIR = "view";
+//#endregion
+export { VIEW_DIR };

package/dist/modules/mcp/apps/shared/bundle.js

@@ -2,21 +2,22 @@ import { require } from "./resolve.js";
 import { zodEnglishOnly } from "./zodEnglishOnly.js";
 import { build } from "esbuild";
 //#region src/modules/mcp/apps/shared/bundle.ts
+var options = (entry) => ({
+	entryPoints: [entry],
+	bundle: true,
+	write: false,
+	format: "iife",
+	platform: "browser",
+	target: "es2022",
+	jsx: "automatic",
+	minify: true,
+	alias: { "@plitzi/plitzi-sdk": require.resolve("@plitzi/plitzi-sdk") },
+	define: { "process.env.NODE_ENV": "\"production\"" },
+	plugins: [zodEnglishOnly],
+	logLevel: "silent"
+});
 var bundle = async (entry) => {
-	return (await build({
-		entryPoints: [entry],
-		bundle: true,
-		write: false,
-		format: "iife",
-		platform: "browser",
-		target: "es2022",
-		jsx: "automatic",
-		minify: true,
-		alias: { "@plitzi/plitzi-sdk": require.resolve("@plitzi/plitzi-sdk") },
-		define: { "process.env.NODE_ENV": "\"production\"" },
-		plugins: [zodEnglishOnly],
-		logLevel: "silent"
-	})).outputFiles[0].text;
+	return (await build(options(entry))).outputFiles[0].text;
 };
 //#endregion
 export { bundle };

package/dist/modules/mcp/handler.js

@@ -74,7 +74,7 @@ var serveMcp = async (raw, res, server) => {
 		await transport.close();
 	}
 };
-var handleMcp = (raw, res, req, adapters, options = {}) => serveMcp(raw, res, createMcpServer({
+var handleMcp = async (raw, res, req, adapters, options = {}) => serveMcp(raw, res, await createMcpServer({
 	adapters,
 	getSpaceId: () => adapters.getSpaceId?.(req) ?? Promise.resolve(void 0),
 	...options

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

@@ -1,5 +1,6 @@
 //#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 idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id — the idRef is ALSO the runtime wiring key, so a provider source is `<type>_<idRef>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the longhands; style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS refs by label/type/attribute; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
+var widgetsOnlyInstructions = "Plitzi widget server (widgets-only connection). This connection carries NO Plitzi space: nothing can be read or edited in one, and the space tools are not offered here — do not look for them. What it does do is build self-contained UI widgets fully offline, with no backend, account or setup: call plitzi_render to SHOW the user a real rendered layout (card, hero, pricing table, checklist, form, gallery) instead of describing one. Read plitzi://render/guide first — the element/prop table, the style model and a worked example; plitzi://render/types lists every element type you can author (plitzi_read fetches both). To change a widget you already rendered, call plitzi_render again with patch:true and its renderId. If the user wants to edit their real Plitzi space from here, that is a reconnection they make: the integration must be re-authorized and granted a space (the consent screen lists theirs) — you cannot do it from this connection, and no retry will change it.";
 var guideQuickstart = `# Plitzi AI MCP — quickstart
 This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
 
@@ -463,4 +464,4 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
   never omit it "to save a call".
 `;
 //#endregion
-export { guideQuickstart, guideText, serverInstructions };
+export { guideQuickstart, guideText, serverInstructions, widgetsOnlyInstructions };

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

@@ -280,9 +280,21 @@ var pageRefOfElement = (schema, 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";
+/** The code a space-dependent answer carries when the connection reaches no space, so both the agent and a host UI
+*  can tell "this connection cannot do that" from "the call failed". */
+var noSpaceError = "NO_SPACE_ATTACHED";
 var unauthorizedSpaceMessage = "This connection has no space attached (a guest or widgets-only grant, or a token that carries no space), so NOTHING in a space can be read or edited — every other space tool will fail the same way, do not retry them. Use plitzi_render instead: it builds a self-contained widget offline, with no space, backend or account (read plitzi://render/guide). To edit a real space, the user must reconnect the integration and grant access to one.";
+/** Raised when a space-dependent operation runs on a connection that resolves no spaceId. A type of its own so the
+*  host answers it as a STATE of the connection — a plain result the agent reads — instead of letting it surface as
+*  a failed call, which hosts render to the user as "cannot connect to this server". */
+var NoSpaceError = class extends Error {
+	constructor() {
+		super(unauthorizedSpaceMessage);
+		this.name = "NoSpaceError";
+	}
+};
 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, emptySpace, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, indexAddElement, indexAddPage, indexInvalidateDetails, indexReRefElement, indexReRefPage, indexRemoveElements, indexRemovePage, isPageElement, nameOf, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, spaceIndex, strOr, unauthorizedSpaceMessage };
+export { NoSpaceError, cloneSpace, descendantCount, descendantIds, elementById, elementRefOf, emptySpace, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, indexAddElement, indexAddPage, indexInvalidateDetails, indexReRefElement, indexReRefPage, indexRemoveElements, indexRemovePage, isPageElement, nameOf, noSpaceError, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, spaceIndex, strOr, unauthorizedSpaceMessage };

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

@@ -2,13 +2,17 @@ import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
 import { guideText } from "../helpers/guide.js";
 import { resourceErrorMessage } from "./canonical.js";
 import { envelope, jsonContents } from "./envelope.js";
-import { readResource } from "./router.js";
 import { registerRenderResources } from "./renderGuide.js";
+import { readResource } from "./router.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 //#region src/modules/mcp/resources/register.ts
 /** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
-*  loaded lazily via getSpace, so listing resources never touches the store — only reading one does. */
-var registerResources = (server, getSpace, env, log) => {
+*  loaded lazily via getSpace, so listing resources never touches the store — only reading one does.
+*
+*  `hasSpace` is false when the connection reaches no space (a guest / widgets-only grant): the space-dependent
+*  families are then not registered at all, so the catalog the agent browses holds only what it can actually
+*  open — no listing that answers every read with the same refusal. */
+var registerResources = (server, getSpace, env, log, hasSpace) => {
 	const emit = async (uri) => {
 		const start = performance.now();
 		try {
@@ -43,6 +47,7 @@ var registerResources = (server, getSpace, env, log) => {
 		shorthands: cssShorthands
 	}))));
 	registerRenderResources(server, log);
+	if (!hasSpace) return;
 	const fixed = [
 		[
 			"Primer",

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

@@ -161,10 +161,10 @@ and \`patchDefinition\` still changes only some CSS of one class.
 - Lay containers out with flexbox or grid — pick the direction on purpose, see **Fit the panel** below.
 - **You are not styling from zero.** Each type lands on the page with CSS you did not write, and it is the usual
   reason a widget does not look like the definitions say:
-  - The per-type rule the SDK ships — the one that changes layouts is \`container\`, which carries
-    \`min-width: 50px; min-height: 50px\`. A rail, a divider, a dot, a spacer or a narrow cell will NOT go below
-    50px until you say \`"min-width": "0"\` (and/or \`"min-height": "0"\`) on it: a 2px timeline line renders 50px
-    wide otherwise. Any flex child that must be allowed to shrink needs it too.
+  - The per-type CSS the SDK ships imposes **no minimum size**: a rail, a divider, a dot or a narrow cell is
+    exactly as small as you make it, and no \`"min-width": "0"\` escape hatch is needed. The flip side is that an
+    element with no content and no size takes no space at all — give a spacer its own \`height\`. (The 50px box
+    empty containers show on the builder canvas is a drop target, scoped to it; it never reaches a widget.)
   - The BROWSER's own defaults for the rest: \`heading\` keeps its UA font-size and ~0.67em top/bottom margins,
     \`paragraph\` ~1em margins, \`list\` a 40px \`padding-left\`, \`button\` its native chrome, \`image\` its intrinsic
     size, \`link\` its own colour and underline. In a compact widget set these explicitly — usually
@@ -355,6 +355,13 @@ connects that source to a descendant's field.
 The tool returns \`rendered: false\` with \`errors: [{ path, message, hint }]\`. Read the hint, fix that one op, and
 retry — you never lose the rest of the batch.
 `;
+/** The same two documents through the READ path (the router, hence plitzi_read), not only as MCP resources: an
+*  agent that reaches for the batch-read tool — the reflex the guide itself teaches — must not be told its own
+*  authoring guide does not exist. Space-independent, like the core singletons. */
+var readRenderResource = (uri) => {
+	if (uri === "plitzi://render/guide") return envelope(renderGuideText);
+	if (uri === "plitzi://render/types") return envelope(renderTypes());
+};
 var registerRenderResources = (server, log) => {
 	server.registerResource("Render guide", RENDER_GUIDE_URI, {
 		description: "How to author a plitzi_render widget: operations, element types, styling, examples.",
@@ -380,4 +387,4 @@ var registerRenderResources = (server, log) => {
 	});
 };
 //#endregion
-export { RENDER_GUIDE_URI, RENDER_TYPES_URI, registerRenderResources };
+export { RENDER_GUIDE_URI, RENDER_TYPES_URI, readRenderResource, registerRenderResources };

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

@@ -1,11 +1,15 @@
+import { emptySpace } from "../helpers/space.js";
+import "../helpers/uris.js";
 import { canonicalUri } from "./canonical.js";
 import { readCoreResource } from "./core.js";
 import { readPrimerResource } from "./primer.js";
+import { readRenderResource } from "./renderGuide.js";
 import { readSchemaResource } from "./schema.js";
 import { readStyleResource } from "./style.js";
 //#region src/modules/mcp/resources/router.ts
 var resolvers = [
 	(space, _env, uri) => readCoreResource(space, uri),
+	(_space, _env, uri) => readRenderResource(uri),
 	readPrimerResource,
 	readSchemaResource,
 	readStyleResource
@@ -19,7 +23,15 @@ var readResource = (space, env, rawUri) => {
 	}
 	return null;
 };
+/** What a connection carrying NO space (a guest / widgets-only grant) can still read: the space-independent
+*  singletons and the render docs. Undefined for everything else, so the caller says the connection has no space
+*  instead of answering out of an empty one — an empty page list would read as "this space has no pages". */
+var readPublicResource = (env, rawUri) => {
+	const uri = canonicalUri(env, rawUri);
+	if (uri === "plitzi://types") return;
+	return readRenderResource(uri) ?? readCoreResource(emptySpace(), uri);
+};
 /** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
 var resourceVersion = (space, env, uri) => readResource(space, env, uri)?.stateVersion ?? null;
 //#endregion
-export { readResource, resourceVersion };
+export { readPublicResource, readResource, resourceVersion };

package/dist/modules/mcp/server.js

@@ -1,6 +1,6 @@
 import { registerApps } from "./apps/index.js";
-import { emptySpace, emptySpaceMessage, unauthorizedSpaceMessage } from "./helpers/space.js";
-import { serverInstructions } from "./helpers/guide.js";
+import { NoSpaceError, emptySpace, emptySpaceMessage, noSpaceError } from "./helpers/space.js";
+import { serverInstructions, widgetsOnlyInstructions } from "./helpers/guide.js";
 import { createMcpLog } from "./helpers/log.js";
 import { registerResources } from "./resources/register.js";
 import { tools } from "./tools/index.js";
@@ -13,19 +13,20 @@ var asText = (data) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(data)
 }] });
-var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) => {
+var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger }) => {
 	const log = createMcpLog(logger);
-	let spaceIdPromise;
-	const requireSpaceId = () => spaceIdPromise ??= getSpaceId().then((id) => {
-		if (!id) throw new Error(unauthorizedSpaceMessage);
-		return id;
-	});
+	const spaceId = await getSpaceId().catch(() => void 0);
+	const hasSpace = spaceId !== void 0;
+	const requireSpaceId = () => {
+		if (spaceId === void 0) throw new NoSpaceError();
+		return spaceId;
+	};
 	const loadSpace = async () => {
-		const spaceId = await requireSpaceId();
+		const id = requireSpaceId();
 		const [schema, style, catalog] = await Promise.all([
-			adapters.getSchema?.(spaceId, MCP_ENV),
-			adapters.getStyle?.(spaceId, MCP_ENV),
-			adapters.getComponentCatalog?.(spaceId, MCP_ENV).catch(() => void 0)
+			adapters.getSchema?.(id, MCP_ENV),
+			adapters.getStyle?.(id, MCP_ENV),
+			adapters.getComponentCatalog?.(id, MCP_ENV).catch(() => void 0)
 		]);
 		if (!schema || !style) throw new Error(emptySpaceMessage);
 		return {
@@ -36,22 +37,22 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 	};
 	const { saveSchema, saveStyle } = adapters;
 	const persisters = {
-		schema: saveSchema ? async (schema) => saveSchema(await requireSpaceId(), MCP_ENV, schema) : void 0,
-		style: saveStyle ? async (style) => saveStyle(await requireSpaceId(), MCP_ENV, style) : void 0
+		schema: saveSchema ? (schema) => saveSchema(requireSpaceId(), MCP_ENV, schema) : void 0,
+		style: saveStyle ? (style) => saveStyle(requireSpaceId(), MCP_ENV, style) : void 0
 	};
 	let spacePromise;
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.18"
-	}, { instructions: serverInstructions });
-	registerResources(server, getSpace, MCP_ENV, log);
+		version: "0.32.19"
+	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
+	registerResources(server, getSpace, MCP_ENV, log, hasSpace);
 	registerApps(server);
 	const toolContext = async () => ({
 		space: await getSpace(),
 		env: MCP_ENV,
 		persisters,
-		spaceId: await requireSpaceId(),
+		spaceId: requireSpaceId(),
 		preview,
 		screenshot
 	});
@@ -62,16 +63,27 @@ var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) =>
 		preview,
 		screenshot
 	});
+	const behaviorOf = (tool) => {
+		if (tool.spaceless) return (args) => tool.execute(args, spacelessContext());
+		if (hasSpace) return async (args) => tool.execute(args, await toolContext());
+		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
+	};
 	for (const tool of tools) {
 		if (tool.requires === "screenshot" && !screenshot) continue;
+		const behavior = behaviorOf(tool);
+		if (!behavior) continue;
 		const run = async (args) => {
 			const start = performance.now();
 			try {
-				const result = await tool.execute(args, tool.spaceless ? spacelessContext() : await toolContext());
+				const result = await behavior(args);
 				log.toolCall(tool.name, args, performance.now() - start);
 				return isCallToolResult(result) ? result : asText(result);
 			} catch (error) {
 				log.toolCall(tool.name, args, performance.now() - start, error);
+				if (error instanceof NoSpaceError) return asText({
+					error: noSpaceError,
+					message: error.message
+				});
 				throw error;
 			}
 		};

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

@@ -1,5 +1,7 @@
+import { noSpaceError, unauthorizedSpaceMessage } from "../helpers/space.js";
 import { resourceErrorMessage } from "../resources/canonical.js";
-import { readResource } from "../resources/router.js";
+import { RENDER_GUIDE_URI, RENDER_TYPES_URI } from "../resources/renderGuide.js";
+import { readPublicResource, readResource } from "../resources/router.js";
 import { defineTool } from "./shared/tool.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/read.ts
@@ -21,13 +23,29 @@ var read = (input, space, env) => {
 		};
 	}) };
 };
+var publicHint = `Readable on this connection: ${RENDER_GUIDE_URI}, ${RENDER_TYPES_URI}, plitzi://guide, plitzi://css-properties. Everything else lives in a space this connection has none of.`;
+var readPublic = (input, env) => ({ results: input.uris.map((uri) => {
+	const found = readPublicResource(env, uri);
+	if (found) return {
+		uri,
+		stateVersion: found.stateVersion,
+		data: found.data
+	};
+	return {
+		uri,
+		error: noSpaceError,
+		message: unauthorizedSpaceMessage,
+		hint: publicHint
+	};
+}) });
 var readTool = defineTool({
 	name: "plitzi_read",
 	title: "Batch read",
 	description: "Batch-fetch resource content for URIs you ALREADY HOLD (from plitzi_search or a write response) — the tool form of opening MCP resources, for many at once. Pass an array of URIs (pages, elements, definitions, variables) and get them all in one call. NOT for finding things: to locate an element by label/type use plitzi_search; to browse what exists, list the plitzi:// resources. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch. Never hand-build a URI to guess your way to an element — search for it.",
 	inputShape: readShape,
 	access: "read",
-	run: (input, ctx) => read(input, ctx.space, ctx.env)
+	run: (input, ctx) => read(input, ctx.space, ctx.env),
+	runPublic: readPublic
 });
 //#endregion
-export { read, readShape, readTool };
+export { read, readPublic, readShape, readTool };

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

@@ -167,7 +167,7 @@ var toRenderResult = (res, renderId) => {
 var renderTool = defineTool({
 	name: "plitzi_render",
 	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), and never hand-draw a scene in a data: URI — it costs more than the whole widget; use an https image, a flat colour or a gradient.\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). Watch the SDK defaults: every container has min-width/min-height 50px (set them to \"0\" for rails, dividers, dots and any flex child that must shrink), and heading/paragraph 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. 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); on failure it returns teachable errors (path + hint) — read them and retry.",
+	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), and never hand-draw a scene in a data: URI — it costs more than the whole widget; use an https image, a flat colour or a gradient.\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. 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); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,

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

@@ -13,16 +13,21 @@ var imageResult = (images, meta) => ({ content: [{
 /** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
 *  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.
 *  Adding a tool is: call defineTool in its own file and append it to the `tools` registry. */
-var defineTool = (spec) => ({
-	name: spec.name,
-	title: spec.title,
-	description: spec.description,
-	inputShape: spec.inputShape,
-	access: spec.access,
-	requires: spec.requires,
-	spaceless: spec.spaceless,
-	ui: spec.ui,
-	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
-});
+var defineTool = (spec) => {
+	const { runPublic } = spec;
+	const parse = (args) => z.object(spec.inputShape).parse(args);
+	return {
+		name: spec.name,
+		title: spec.title,
+		description: spec.description,
+		inputShape: spec.inputShape,
+		access: spec.access,
+		requires: spec.requires,
+		spaceless: spec.spaceless,
+		ui: spec.ui,
+		execute: (args, ctx) => spec.run(parse(args), ctx),
+		...runPublic ? { executePublic: (args, env) => runPublic(parse(args), env) } : {}
+	};
+};
 //#endregion
 export { defineTool, imageResult };

package/dist/src/modules/mcp/apps/shared/assets.d.ts

@@ -0,0 +1,10 @@
+/** The one folder of an app that ships to dist as SOURCE: its browser entry (`view/index.tsx`) and every module
+ *  that entry bundles. The server builds it with esbuild at request time, so none of it is in the module graph the
+ *  library build compiles — a view-side module that does not travel verbatim is simply missing at runtime, which
+ *  the package only finds out when a host asks for the page. Everything else in an app (its definition) compiles
+ *  like any other module. */
+export declare const VIEW_DIR = "view";
+/** Does this file ship as source? The build's copy step asks it, and `apps.test.ts` asks it of every real input of
+ *  every app's bundle — so a view that grows a sibling module either lives in `view/` or fails the suite, instead
+ *  of failing a deployment. Tests stay behind; the page shell travels with the views it renders. */
+export declare const shipsAsSource: (file: string) => boolean;

package/dist/src/modules/mcp/apps/shared/bundle.d.ts

@@ -1 +1,4 @@
 export declare const bundle: (entry: string) => Promise<string>;
+/** Every file the view pulls in, resolved by the build that serves it. The suite asks for this to check each one
+ *  ships as source: a view-side module the package leaves behind resolves here, in the repo, and nowhere else. */
+export declare const bundleInputs: (entry: string) => Promise<string[]>;

package/dist/src/modules/mcp/apps/shared/index.d.ts

@@ -1,2 +1,3 @@
+export { shipsAsSource, VIEW_DIR } from './assets';
 export { registerApp } from './registerApp';
 export { require } from './resolve';

package/dist/src/modules/mcp/e2e/mcpEndpoint.d.ts

@@ -14,7 +14,12 @@ export interface AppPage {
     mimeType?: string;
     meta?: Record<string, unknown>;
 }
+export interface McpEndpointOptions {
+    /** Attach a space to the connection, the way an authorized connector's token does — the server then offers its
+     *  editing surface. Omitted, the endpoint is the guest one: no space, so only what works without one. */
+    spaceId?: number;
+}
 /** Start the endpoint and connect a real MCP client to it, as a remote connector does. */
-export declare const startMcpEndpoint: () => Promise<McpEndpoint>;
+export declare const startMcpEndpoint: ({ spaceId }?: McpEndpointOptions) => Promise<McpEndpoint>;
 /** Read a ui:// resource. A page that came back as a blob is a bug a host would meet as a blank frame. */
 export declare const readAppPage: (endpoint: McpEndpoint, uri: string) => Promise<AppPage>;

package/dist/src/modules/mcp/helpers/guide.d.ts

@@ -1,3 +1,4 @@
 export declare const serverInstructions: string;
+export declare const widgetsOnlyInstructions: string;
 export declare const guideQuickstart = "# Plitzi AI MCP \u2014 quickstart\nThis is the condensed guide; read `plitzi://guide` for the full reference (every resource, op and example).\n\nA space is **two schemas you edit together in one atomic `plitzi_apply` batch**: the **element schema** (tree of\npages/elements) and the **style schema** (definitions = CSS classes, tokens, theme). To style an element: write a\n**definition** and attach it via the element's `style.base` in the same batch.\n\n**Workflow:** (1) you already have this primer (guide + types + css + page/style summaries). (2) `plitzi_search`\nwith `include:\"detail\"` to find elements \u2014 each hit carries its `uri`, `stateVersion` and full style, so no\nper-element read. (3) `plitzi_apply` with `dryRun:true` to preview. (4) `plitzi_apply` to persist, passing\n`expectedResourceVersions` (uri \u2192 the stateVersion you read) for every resource you change \u2014 omitting it lets a\nconcurrent edit be lost. Use `patchElement`/`patchDefinition` to change only some props/CSS (upsert replaces all).\n\n**Refs & wiring:** a ref is the semantic `idRef` (letters, numbers, hyphens and underscores, **starting with a\nletter \u2014 no dots**) or the raw id. The idRef is the runtime wiring key: a provider's source is `<type>_<idRef>`, and\ninteractions target by it. A dot would split that path; an **underscore is fine** \u2014 the first `_` separates the type\nfrom the idRef (element types have none), so `list_food_item` reads unambiguously as type `list`, idRef `food_item`.\n\n**Styling:** CSS keys are **kebab-case** (`background-color`); `var(--token)` for style vars, `{{name}}` for schema\nvars. **Write plain CSS** \u2014 shorthands (`border`, `padding`, `margin`, `gap`, `overflow`, `flex`, `background`,\n`font`, `transition`, `animation`, `grid`, `grid-row`/`grid-column`, `place-*`, `outline`, `columns`,\n`list-style`, `text-decoration`) are expanded to their longhands for you, so `border: 1px solid red` is stored as\n`border-top-color`/`border-top-width`/`border-top-style`/\u2026 That is also how you read them back. Flex layout is\nstill `display: flex` + `flex-direction`/`align-items`/\u2026, not a `flex` value. Mind a type's `defaultStyle`\n(`text` is `display: inline`). Global styles (`button {\u2026}`) and id styles (`#id`) have their own ops.\n\n**Data bindings** (`upsertBinding`, category attributes|style|initialState): connect a `source` to a `to` field.\nA source `<type>_<idRef>` is scoped to the provider's **DESCENDANTS only** \u2014 bind inside the provider's subtree\n(module sources state/space/navigation/auth/collection are global). `apiContainer.mockData` is builder-only; set a\nreal `query` for production. `transformers: [{action, params}]` post-process the value \u2014 use exact action names\nfrom `plitzi://data-sources`; `twigTemplate` formats it (the value is `{{source}}`, not `{{value}}`). `when` is\na QueryBuilder RuleGroup gating the binding.\n\n**Interactions** (`upsertInteractionFlow`): a `trigger` node first, then callbacks/utilities **in order** (links\ncomputed for you). Node types: `callback` (an element's own callback \u2014 `elementId` is that element), `globalCallback`\n(a source module \u2014 omit `elementId`, the MCP sets it), `utility` (no element). Element `setState`\n(category/key/value/revertOnFinish) \u2260 global `setState` (source `state`, key/type/value). To turn a step off use\n`patchInteractionNode {enabled:false}` \u2014 `deleteInteraction` removes it (destructive; confirm first). Any param\n**value** can be a binding token `{{ source }}` (e.g. notification `content: \"{{ list_<idRef>.item.name }}\"`).\n\n**Pages & navigation:** `upsertPage` \u2014 always set a **relative** `slug` (no leading `/`; the runtime and folder\nslugs prepend the path). A `:name` segment (`\"posts/:postId\"`) is a route param, readable as `{{name}}` and as the\nsource `navigation.routeParams.name` \u2192 build dynamic pages this way. To move between pages **prefer the `Link`\nelement** (a container: `mode` \"page\"/\"internal\"/\"external\") over a `navigate` interaction.\n\n**Touched resources must be malformation-free.** Editing an element/definition also checks its CURRENT stored content\nand BLOCKS the save on any `Pre-existing malformation in <resource>` error (a broken transformer, malformed node,\ninvalid CSS) \u2014 even parts you did not touch. These are NOT from your change (the message says so); fix them in the\nSAME batch and re-apply (the check runs on the result, so the fix unblocks it). `Pre-existing issue` warnings advise\nbut do not block.\n\nRead `plitzi://guide` before anything above is unclear.\n";
 export declare const guideText = "# Plitzi AI MCP \u2014 usage guide\n\nA Plitzi space is **two separate schemas** you edit together:\n- **Element schema** \u2014 the tree of pages and elements (their type, label, props, and which style classes they use).\n- **Style schema** \u2014 reusable **definitions** (CSS classes), design tokens (variables), theme.\n\nThey are stored and persisted independently, but a single `plitzi_apply` batch may touch **both atomically**.\nTo style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**\nit via the element's `style.base` (element schema). Example \u2014 \"rename button X to PEPE and make it red\":\n```json\n{ \"operations\": [\n  { \"type\": \"upsertDefinition\", \"ref\": \"btn-x\", \"desktop\": { \"color\": \"red\" } },\n  { \"type\": \"upsertElement\", \"pageRef\": \"home\",\n    \"element\": { \"ref\": \"X\", \"type\": \"button\", \"label\": \"PEPE\", \"style\": { \"base\": [\"btn-x\"] } } }\n] }\n```\n\nReads are cheap by design \u2014 treat them like a filesystem: **list** to navigate, **read one item** for detail.\nNever download a whole tree you do not need.\n\n## Resources (read)\n- `plitzi://primer/{env}` \u2014 **cold-start bundle**: guide + types + css-properties + page/definition/variable\n  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only \u2014 open a\n  page skeleton or element for its tree/detail.\n- `plitzi://guide` \u2014 this guide.\n- `plitzi://types` \u2014 element types **observed in this space** (ground truth): props, slots, subTypes, plus each\n  type's `label`, `description` (what it is FOR) and `category`, and a `source` (`builtin` | `plugin` | `unknown`).\n  Read the descriptions to pick the right type \u2014 e.g. `apiContainer` fetches backend data into the frontend,\n  `link` navigates between pages, `list` repeats a template over a data array. `plugin` types are custom elements.\n- `plitzi://css-properties` \u2014 valid kebab-case CSS property keys.\n- `plitzi://schema/{env}/pages` \u2014 page **summaries** (ref, label, elementCount, folder). No element trees.\n- `plitzi://folders/{env}` \u2014 page **folders** (the sidebar tree): ref, name, slug, parentId. `/{ref}` for one.\n- `plitzi://schema/{env}/pages/{ref}` \u2014 one page as a **skeleton tree**: each node is `ref/type/label` **plus the\n  style classes it attaches** (`base`, and `slots` for non-base slots) \u2014 names only, no CSS. So you can map every\n  element to its class in a single page read, without opening each element just to learn which class it uses.\n- `plitzi://schema/{env}/pages/{ref}/styles` \u2014 **every style the page uses in one read**: the class definitions its\n  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.\n  Reach for this to recolor/restyle a whole page \u2014 it needs no shared class-name prefix and no per-element reads.\n- `plitzi://schema/{env}/elements/{ref}` \u2014 one element in **full detail** (props, style, parentRef, childRefs).\n  Its `resolvedStyle` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you\n  can see and edit its style without a separate definition read. Its `globalStyles` lists the **global element\n  selectors** that also affect it (the CSS equivalent of `button { \u2026 }`, keyed by the type they target) \u2014 every\n  element of that type inherits them. Edit a global only through the global-style tools (never per element). If the\n  element carries a DOM `id` that an id rule matches, its `idStyle` (`#id`) is inlined too.\n- `plitzi://definitions/{env}` \u2014 the **names** of every style definition.\n- `plitzi://definitions/{env}/{ref}` \u2014 one definition's CSS.\n- `plitzi://global-styles/{env}` \u2014 element **types** that have a site-wide global style. `/{componentType}` for one.\n- `plitzi://id-styles/{env}` \u2014 DOM **ids** that have an id rule (`#id`) targeting a single element. `/{targetId}` for one.\n- `plitzi://style-variables/{env}` \u2014 design tokens by category. `/{category}` for one.\n- `plitzi://schema-variables/{env}` \u2014 space-level values referenced in props as `{{name}}`.\n- `plitzi://settings/{env}` \u2014 space-level settings: the global `customCss` and the state/auth (user-provider) config.\n- `plitzi://interactions/{env}` \u2014 interaction **actions** observed in this space (grouped by node type): the\n  vocabulary for interaction flows.\n- `plitzi://data-sources/{env}` \u2014 data-source **paths** and binding targets observed in this space: the\n  vocabulary for data bindings.\n\nThe style resources also answer under the `plitzi://schema/{env}/\u2026` root as aliases \u2014 `plitzi://schema/{env}/definitions/{ref}`, `plitzi://schema/{env}/style-variables/{category}`, `plitzi://schema/{env}/schema-variables` \u2014 but prefer the ready-made `uri` from search / a write response over hand-building either form.\n\nData resources return `{ stateVersion, data }`. Keep `stateVersion` for optimistic concurrency.\n\n**Reuse what you already know \u2014 don't re-scan an unchanged page.** A page read (`plitzi://schema/{env}/pages/{ref}`)\nreturns a `stateVersion` that is an **aggregate of the whole page**: it changes if and only if some element on the\npage changed. Its skeleton `tree` also carries a `stateVersion` **per node**, identical to the one a direct element\nread or search hit returns for that element. So when you come back to a page you already inspected:\n1. Re-read just the page skeleton and compare its top-level `stateVersion` to the one you held. **Same \u2192 nothing\n   changed since your read; skip re-reading and re-searching the tree** and act on what you already know.\n2. If it differs, diff the per-node `stateVersion`s against the ones you cached and `plitzi_read` **only the nodes\n   that changed** \u2014 never re-search or re-read the whole tree.\n\nThis is a **read-time** shortcut, not a safety guarantee. **Other agents/sub-agents may edit the same space\nconcurrently**, so a version you cached can go stale between your read and your write. Never skip the write-time\ncheck below on the strength of a cached hash \u2014 the guarantee that no concurrent edit is lost comes only from\n`expectedResourceVersions` on `plitzi_apply`, which re-validates against the live data at write time.\n\n## Navigating (files analogy)\nPages and containers are folders; elements are files. **Prefer `plitzi_search` (especially with `include: \"detail\"`)\nover reading elements one by one** \u2014 it jumps straight to elements by label/type/attribute and each hit already\ncarries the element's `uri`, `stateVersion`, `pageUri`, `parentRef` and tree `path`, so you can edit it (with\noptimistic concurrency) **without a follow-up read**. `include: \"detail\"` additionally inlines each hit's props/style\n**and** its `resolvedStyle` (the CSS behind its classes) \u2014 so a search-then-edit is the efficient path and a manual\nelement read is the exception. Search also matches **pages** by name/slug (returned under `pages`, each with its uri +\nstateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under `definitions`.\nWhen you do hold several refs to open (e.g. from a skeleton), read them together with `plitzi_read` rather than one at a time.\n\n## Tools (write)\n- `plitzi_validate` \u2014 check a batch, returns teachable errors/warnings. Writes nothing. Also reports **pre-existing\n  malformations** in any resource the batch touches (see below).\n- `plitzi_apply` \u2014 validate \u2192 apply \u2192 persist atomically. Rejects the whole batch on any error or conflict. Pass\n  `dryRun: true` to apply in memory only and get the same result back (changed versions + full element detail)\n  without persisting \u2014 inspect it, then re-run without `dryRun` to commit.\n- `plitzi_search` \u2014 find elements (and pages/definitions) across the space.\n- `plitzi_read` \u2014 read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the\n  ready-made uris from search / a write response; each result is `{ uri, stateVersion, data }` or a teachable error,\n  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.\n\n## Readers: resources vs plitzi_search vs plitzi_read (do not confuse them)\nThree ways to read, each for a different moment \u2014 pick by what you have in hand:\n- **MCP resources** (the `plitzi://\u2026` catalog above) \u2014 the **browsable index**. List them to discover what exists, or\n  open one by URI when you are exploring. This is the passive catalog, not a tool.\n- **`plitzi_search`** \u2014 you know *what* you want but not its **ref/uri** (\"the hero button\"). Search finds it by\n  label/type/attribute and hands back the uri + stateVersion (and, with `include:\"detail\"`, the full element).\n- **`plitzi_read`** \u2014 you **already hold one or more uris** (from search or a write response) and want their\n  content in one batch. It is the tool form of opening resources, for when you have the addresses.\nRule of thumb: **discover \u2192 resources**, **find a ref \u2192 plitzi_search**, **fetch known uris \u2192 plitzi_read**. Never\nhand-build a URI to guess your way to an element \u2014 search for it instead.\n\nWrite tools return what **changed** (`{ uri, stateVersion }`) plus counts, and the **full detail of every element\nthey created or updated** \u2014 each with its own `uri` and `stateVersion` (`elements: [...]`) so a follow-up edit of\nthe same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only\nuri+stateVersion \u2014 re-read them if you need their new content. The operation shapes are in each tool's input\nschema (discriminated by `type`).\n\n## Addressing\nRefs are the semantic `idRef` (e.g. `\"hero-cta\"`) or the element's **raw id** \u2014 both resolve. Creating an element\nstores the `ref` you chose as its **idRef**.\n\nThe idRef is not just an alias \u2014 it is the **wiring key the runtime uses**. A provider registers its data source as\n`<type>_<idRef>`, so a `source` you write against a ref resolves to that element at runtime with no id translation.\nRules for a **new** ref (both are enforced; a violation fails the batch):\n- Charset `[A-Za-z0-9_-]`, **starting with a letter** (e.g. `\"products-api\"`, `\"food_item\"`). A `.` would split the\n  `<type>_<idRef>.<field>` source path and the interaction target lookup, so **no dots**. An **underscore is\n  allowed**: the FIRST `_` separates `<type>` from `<idRef>` and element types are camelCase with none, so\n  underscores inside the idRef are unambiguous (`list_food_item` \u2192 type `list`, idRef `food_item`).\n- **Unique across the space**; creating a ref that is taken is rejected (address the existing element instead).\n\nAn idRef is **optional** on an element \u2014 one built in the builder may not have it. The consequence is specific: an\nelement without an idRef **publishes no data source** and **holds no interactions**, because the runtime keys\neverything by idRef and the raw id is never a fallback. You do not have to fix this by hand: writing an\ninteraction **mints an idRef for you** \u2014 the element that hosts the flow, and any element a node targets, is given\na free `<type>-<n>` ref if it lacks one, and the flow is wired to it. A node target you write may be a raw id; it\nis normalised to that element's idRef. (To make an element a data-source **provider** to bind against, give it an\nidRef explicitly with `patchElement`, or create it with the `ref` you want \u2014 a created element stores its ref as\nits idRef.)\n\n**Renaming** an idRef moves the wiring key: every binding source and interaction target across the space that\npointed at the old name is repointed with it, so the element stays wired. You do not have to rewrite them.\n\n## Styling (crosses both schemas)\n- **Mind the type's intrinsic default style.** A type renders with a base CSS *before* any class is attached \u2014 read\n  it from `defaultStyle` on the type in `plitzi://types` (the primer includes it). Do not assume `display: block`:\n  `text`, for one, defaults to `display: inline`, so margins/width/vertical padding behave differently. If you need\n  block/flex layout on such an element, set `display` explicitly in your definition rather than relying on a default.\n- **Images: preserve aspect ratio.** Setting only `width` and `height` (or forcing both) distorts an image. Change\n  one dimension and let the other be `auto`, or set `aspect-ratio` with `object-fit: cover`/`contain`, so the\n  image scales without stretching.\n- **Font size and line height move together.** When you change `font-size`, set `line-height` in the same edit\n  (prefer a unitless ratio like `1.5`, which tracks the font size). Changing one without the other leaves cramped or\n  loosely-spaced text \u2014 they are a joint change, not two separate ones.\n- A definition lives in the **style schema**; an element's `style.base` (element schema) is the link that applies\n  it. Styling an element = upsertDefinitions + upsertElement with that ref in `style.base`, in one batch.\n- **Repeating siblings**: when a set of siblings shares a shape and differs only in data (a list, cards, rows,\n  steps), use `repeatElement` \u2014 the template once with `{{item.field}}` placeholders plus `items`, which\n  creates the wrapper and numbers each row's refs (`step-1`, `step-2`\u2026). A list inside each row is the same op:\n  the wrapping node carries `repeat: { items: \"{{item.<list>}}\", template: \u2026 }` and its refs number both levels\n  (`blk-2-3`). Copy-pasting the subtree N times costs N times the tokens and drifts.\n- CSS keys are **kebab-case** (`background-color`). camelCase is rejected \u2014 read `plitzi://css-properties`.\n- **Write normal CSS \u2014 shorthands are accepted and expanded for you.** `border`, `border-{side}`,\n  `border-width`/`-color`/`-style`, `border-radius`, `padding`, `margin`, `inset`, `gap`, `overflow`,\n  `flex`, `flex-flow`, `background`, `font`, `transition`, `animation`, `grid`, `grid-template`,\n  `grid-area`, `grid-row`, `grid-column`, `place-content`, `place-items`, `place-self`, `outline`,\n  `columns`, `list-style`, `text-decoration` \u2014 the full list is in `plitzi://css-properties` under\n  `shorthands`. They **persist as longhand keys** (that is what a read gives back), so a breakpoint/state/variant\n  can still override one property at a time.\n  - `border: 1px solid red` \u2192 `border-top-width: 1px`, `border-top-style: solid`, `border-top-color: red`, \u2026\n    for all four sides. A shorthand also RESETS what it omits, so `border: none` clears a width a previous\n    definition set.\n  - Comma-separated layers are kept per longhand: `transition: opacity 200ms, transform 300ms` \u2192\n    `transition-property: opacity, transform` + `transition-duration: 200ms, 300ms`.\n  - In a **patch**, a shorthand replaces the longhands it controls (`padding: 8px` overwrites a previous\n    `padding-left`), and `\"border\": null` removes all twelve border longhands.\n- **Flex layout is not a `flex` value**: set `display: flex` **plus** `flex-direction`, `align-items`,\n  `justify-content` as separate properties.\n- CSS is grouped by breakpoint: `desktop`, `tablet`, `mobile`.\n- Reference a style variable in CSS as `var(--name)`; a schema variable in a prop as `{{name}}`.\n- `element.style.base` is a **list** of definition refs; other slots go under `element.style.slots`.\n- **An element can attach SEVERAL classes at once, and they all apply.** `style.base` holds a list, and each\n  non-base slot holds its own \u2014 every attached definition contributes CSS, and they **cascade** (a later class, then a\n  global/id rule, overrides an earlier one on the same property). So when a style looks wrong, the culprit may be\n  ANY attached class, not the one you just edited: read the element's `resolvedStyle` (it inlines the CSS of every\n  class it attaches, keyed by ref) together with its `globalStyles`/`idStyle` and the type's `defaultStyle`, and\n  fix the class that actually sets the property \u2014 do not just pile another class on top.\n- **Three kinds of style live in the style schema \u2014 do not confuse them:**\n  - **Definitions** = reusable CSS **classes** (`upsertDefinition`/`patchDefinition`/`deleteDefinition`, keyed by a\n    class `ref`). Attach one to an element via `style.base` to style **that** element (and anything else that opts in).\n    This is the **default** way to style one element. Declaring MORE than one class in a batch? Use\n    `upsertDefinitions` \u2014 one op carrying `{ \"<class>\": { desktop: \u2026 }, \u2026 }`, same result as the run of\n    `upsertDefinition` it replaces, without repeating the envelope once per class.\n  - **Global styles** = the CSS equivalent of a bare element selector like `button { \u2026 }`\n    (`upsertGlobalStyle`/`patchGlobalStyle`/`deleteGlobalStyle`, keyed by `componentType`). They style **every**\n    element of that type at once. Use these for site-wide intent \u2014 e.g. \"all buttons rounded\":\n    `{ \"type\": \"upsertGlobalStyle\", \"componentType\": \"button\", \"desktop\": { \"border-radius\": \"9999px\" } }`.\n  - **Id styles** = the CSS equivalent of an id selector like `#hero { \u2026 }`\n    (`upsertIdStyle`/`patchIdStyle`/`deleteIdStyle`, keyed by `targetId`). They style the **single** element whose\n    DOM `id` attribute equals `targetId` \u2014 so the element must carry that `id` (set it in its props). Prefer a\n    **definition** for one element; reach for an id style only when a specific, uniquely-identified node must be\n    targeted by id: `{ \"type\": \"upsertIdStyle\", \"targetId\": \"hero\", \"desktop\": { \"min-height\": \"100vh\" } }`.\n  - The three share one name space, so an op refuses a name held by another kind (guards against a typo silently\n    rewriting every element of a type, or converting a class into an id rule). If refused, you targeted the wrong\n    kind \u2014 switch tools or rename.\n\n## Style variants & element state\nA **variant** is a named CSS override on a definition (e.g. a button class with a `primary` variant). It takes two\nsteps across the two schemas:\n- **Declare** the variant CSS on the class (style schema): `upsertDefinition`/`patchDefinition` with\n  `variants: { \"primary\": { \"desktop\": { \"background-color\": \"#111\" } } }` (per slot under `slots.<slot>.variants`).\n- **Apply** it to an element (element schema): `initialState.styleVariant` =\n  `{ \"<class-ref>\": { \"base\": \"primary\" } }` \u2014 a slot name instead of `base` targets that slot; an array applies\n  several. Set it via `upsertElement`/`patchElement`.\nAn element read reports `availableVariants` (which variant each attached class offers) and the element's current\n`initialState`, so you can see a button **has** a `primary` variant and whether it uses it. If the user asks for a\nvariant that does not exist yet, **create it (upsertDefinition variants) and apply it in the same batch**.\n- `initialState.visibility` (boolean) sets whether the element starts shown or hidden.\n\n## Data bindings\nConnect a data **source** to an element field. A binding is `{ to, source, transformers?, when?, enabled? }` grouped\nby **category**: `attributes` (a prop), `style` (a style value), `initialState` (an initial-state key).\n- `upsertBinding` adds one, or replaces the binding already feeding the same `to` (or `id`).\n- `patchBinding` edits an existing one (matched by `to`/`id`); `deleteBinding` removes it.\nDiscover valid source paths **and the transformer catalog** in `plitzi://data-sources/{env}`. Example \u2014 feed an API\nlist into a list element:\n`{ \"type\": \"upsertBinding\", \"pageRef\": \"home\", \"ref\": \"myList\", \"category\": \"attributes\",\n  \"binding\": { \"to\": \"items\", \"source\": \"apiContainer_x.data\" } }`.\n\n**Source scope \u2014 a source is visible to the provider's DESCENDANTS only.** An element source named\n`<type>_<idRef>` (e.g. `apiContainer_products`, `list_food-list`) is published by that element into the scope of\nits **subtree**, so **only elements INSIDE the provider can bind to it**. Binding a sibling or an unrelated element\nto it resolves to nothing at runtime. So to consume `apiContainer_products.data`, the bound element must live under\nthat apiContainer; inside a `list`, the repeated `listItem` and its children read the per-row source\n(`list_<idRef>.item.<field>`). Module sources (no `<type>_<idRef>` head \u2014 `state`, `space`, `navigation`,\n`auth`, `collection`) are global and bindable anywhere. Binding an element to an element source outside its\nprovider's subtree is schema-valid but **broken at runtime** (the source is not in scope), so\n`plitzi_validate`/`plitzi_apply` treat it as an **error and reject the batch** \u2014 move the element under the\nprovider, or bind a source that is in scope.\n\n**mockData is builder-only.** An `apiContainer`'s `mockData` prop feeds sample data **while editing in the\nbuilder**; the published runtime fetches the real `query` instead. Never rely on mockData as the production source \u2014\nset a real `query`/`method` so the binding has data at runtime.\n\n**`transformers` \u2014 post-process the value before it reaches the field** (`source \u2192 t\u2081 \u2192 t\u2082 \u2192 field`). An array of\n`{ action, params }`; the runtime runs them in order and resolves each by its `action` alone, so an **unknown\naction is silently skipped** and the raw value passes through. Use the **exact** action names from\n`plitzi://data-sources` (`transformers`). The most common is **`twigTemplate`** to format a value \u2014 the incoming\nvalue is the **`{{source}}`** token (NOT `{{value}}`); `{{sourceTo}}` is the field's previous value. Example \u2014\nshow a number with units:\n`{ \"type\": \"upsertBinding\", \"pageRef\": \"home\", \"ref\": \"food-item-time\", \"category\": \"attributes\",\n  \"binding\": { \"to\": \"content\", \"source\": \"list_food-list.item.cookTimeMinutes\",\n    \"transformers\": [ { \"action\": \"twigTemplate\", \"params\": { \"template\": \"{{source}} min de cocci\u00F3n\" } } ] } }`.\nOther transformers: `dateConverter` (format a date/timestamp), `capitalize`, `stringToArray` (split on a\nseparator), `arrayMap` (remap the keys of each object in an array), `staticValue`. Transformer `params` values are\nstrings. Each transformer also takes an optional `enabled` flag: set `\"enabled\": false` to keep it in the chain but\nskip it at runtime (defaults to true) \u2014 the value passes through untouched, and a disabled transformer is not\nvalidated.\n\n**`when` \u2014 gate the binding** with a QueryBuilder RuleGroup: the binding only applies when the guard passes against\nthe data source. Shape: `{ \"combinator\": \"and\", \"rules\": [ { \"field\": \"<path>\", \"operator\": \"=\", \"value\": \"x\" } ] }`\n(operators: `=`, `!=`, `<`, `>`, `contains`, `beginsWith`, `empty`, `in`, `between`, \u2026; nest RuleGroups for\nand/or). The guard is validated structurally. Example \u2014 only bind when a flag is set:\n`\"when\": { \"combinator\": \"and\", \"rules\": [ { \"field\": \"status\", \"operator\": \"=\", \"value\": \"published\" } ] }`.\n\n## Interactions\nAn interaction **flow** is a **trigger** (an event like `onClick`, `onPageLoad`) followed by the callbacks/utilities\nit runs, in order. You pass the steps **in order** and the stored beforeNode/afterNode/flowId links are computed for\nyou \u2014 never wire them by hand. Each step also has an `enabled` flag (see disable vs delete below).\n\n**Node types & `elementId`** \u2014 a step names which element (or module) provides the callback it runs. Picking the\n**wrong node type for an action** makes the runtime resolve it against nothing, so the step **silently does nothing**:\n- `trigger` \u2014 the event; belongs to the host element. `elementId` defaults to the host.\n- `callback` \u2014 a callback provided by a **specific element**. `elementId` is that element's ref (the flow host by\n  default, or another element to act on); give its ref or raw id and it is normalised to the idRef. Every element\n  registers a built-in **`setState`** callback that changes **its own attribute or state**: params\n  `category` (`\"attribute\"` \u2014 set a prop like `content`/`disabled` \u2014 or `\"state\"` \u2014 `visibility` or a style\n  selector), `key`, `value` (a **scalar** whose type follows the target attribute \u2014 a real boolean `true`/`false`\n  for a boolean attribute, a number for a numeric one, otherwise a string), and **`revertOnFinish`**. Set\n  `revertOnFinish: true` for a **temporary** change (a \"loading\u2026\" label, disabling a button while it works): it is\n  **undone automatically when the flow finishes**, so you do **NOT** add manual restore steps at the end. This element\n  `setState` has **no** `type` param (that belongs to the global one below). An element type may also register its\n  own extra callbacks.\n- `globalCallback` \u2014 a callback provided by a **source module**, NOT by any element: `addNotification` (source\n  `space`), `setState`/`clearState` (`state`), `navigate` (`navigation`), `authLogin`/`authLogout`/\n  `authRefreshDetails` (`auth`), `addCollectionRecord`/`updateCollectionRecord`/`removeCollectionRecord`\n  (`collection`). Its `elementId` is the **source module id**, never the host element \u2014 a node that stored the host\n  idRef here would resolve to nothing at runtime. **Omit `elementId`**: the MCP sets the correct source and fills the\n  builder's **param defaults** (e.g. `addNotification` gets `autoDismiss:true`, `autoDismissTimeout:5000`,\n  `placement:\"top-right\"`, `appeareance:\"success\"`) for any params you leave out. Use **only** the params each\n  callback declares (exact spelling) \u2014 for `addNotification` the visible text goes in `content`; there is **no**\n  `title`/`message`/`type` param, and any unknown key is dropped. See the full param schema for each callback under\n  `globalCallbacks` in `plitzi://interactions/{env}`.\n- **Two `setState`s \u2014 do not mix them:** the **element** `setState` (nodeType `callback`, on an element,\n  category/key/value/revertOnFinish) changes THAT element's attribute/state and is what you want to change a button's\n  label or disabled flag. The **global** `setState` (nodeType `globalCallback`, source `state`, key/type/value)\n  writes `runtime.state.<key>`. They share a name but have different node types AND different params.\n- `utility` \u2014 a built-in utility action (no element/source module); nodeType `utility`. Use the **exact** param\n  names: `delayTime` waits `time` milliseconds (**not** `delay`), `twigTemplate` (`returnMode`, `template`),\n  `webHook` (`url`, `method`, \u2026). See `utilities` in `plitzi://interactions/{env}`.\n\n**A param value can be a data binding.** Any interaction param may hold a `{{ source }}` token instead of a literal \u2014\nit resolves at runtime exactly like a prop binding, using the same source grammar (`<type>_<idRef>.<path>`, or a\nmodule source like `navigation`/`state`). This is how a step reacts to *the data in context*: inside a `listItem`,\na click on a row can show `addNotification` with `content: \"{{ list_<idRef>.item.name }}\"` \u2014 the clicked row's field.\nThe value follows the source's type, so a token is valid even where a param expects a boolean/number. Copy/paste of an\nelement repoints these tokens to the new idRefs automatically, along with the element's bindings.\n\n**Navigating between pages \u2014 prefer the `Link` element over an interaction.** For a plain \"go to page X\" the right\ntool is a `link` element (a container, see *Pages & folders*), not a `navigate` interaction step. Use the\n`navigate` globalCallback only when the navigation is one step of a larger flow (e.g. submit a form, then go).\n\nTools:\n- `upsertInteractionFlow` \u2014 create or replace one flow. The FIRST node must be a `trigger`. Pass `flowId` (the\n  trigger's node id) to replace an existing flow. Example (elementId omitted \u2014 the MCP wires it to `space` and fills\n  the notification defaults):\n  `{ \"type\": \"upsertInteractionFlow\", \"pageRef\": \"home\", \"ref\": \"cta\", \"nodes\": [\n    { \"nodeType\": \"trigger\", \"action\": \"onClick\", \"title\": \"Click\" },\n    { \"nodeType\": \"globalCallback\", \"action\": \"addNotification\", \"title\": \"Notify\",\n      \"params\": { \"content\": \"Saved!\" } } ] }`.\n- `patchInteractionNode` \u2014 change one step in place (by `nodeId`); `params` merge onto the node.\n\n**Disable vs delete a step \u2014 do not confuse them (three different intents):**\n- **Disable / deactivate / turn off a step** (keep it in the flow, just stop it running): `patchInteractionNode`\n  with `{ \"enabled\": false }`. Re-enable with `{ \"enabled\": true }`. This is NOT a deletion \u2014 the step stays.\n- **Remove one step** from a flow: `deleteInteraction` with `nodeId` (its neighbors are re-linked).\n- **Remove the whole flow**: `deleteInteraction` with `flowId` (the trigger node id).\n\nSo \"deactivate the addNotification step\" means `patchInteractionNode { enabled: false }` \u2014 never delete the step, and\nnever delete the flow. `deleteInteraction` is **destructive and not undoable**: only use it when the user asked to\n*remove* something, and **confirm with the user before deleting** a step or a flow.\n\nDiscover valid actions in `plitzi://interactions/{env}`: `actions` = observed, `globalCallbacks` /\n`elementCallbacks` / `utilities` = the built-in vocabularies with their full param schema, so you know the exact\nnode type and valid params per action. An element read lists its flows as ordered nodes (each with its `id` and\n`enabled`), so a follow-up patch/delete needs no extra read.\n\n## Pages & folders\n- **Always set a `slug` when creating a page** (`upsertPage`) \u2014 it is the page's URL path and good practice for a\n  clean, stable route (e.g. `\"pricing\"` or `\"posts/:postId\"`). Omit it and the page ref is used as the slug,\n  and `plitzi_validate`/`plitzi_apply` warn so you remember to set a meaningful one.\n- **A page slug is RELATIVE \u2014 do NOT start it with `/`.** The runtime prepends the leading slash (and any folder\n  path) itself, so a leading slash doubles it. Write `\"pricing\"`, not `\"/pricing\"`. (upsertPage strips a leading\n  slash for you, but write it relative.)\n- **Dynamic pages \u2014 route params.** A slug segment written `:name` (e.g. `\"posts/:postId\"`) is a **route param**,\n  exactly like React Router. On that page it is readable **two ways**: as `{{name}}` inside a prop, and as the\n  data-binding source **`navigation.routeParams.name`** (the `navigation` module source, global \u2014 bindable\n  anywhere). So a blog is a `\"posts\"` list page plus a `\"posts/:postId\"` detail page whose `apiContainer` query\n  binds `navigation.routeParams.postId` to fetch that one post. (`navigation.queryParams.<name>` exposes `?query=`\n  string params the same way.)\n- **Navigate with the `Link` element, not an interaction.** `link` is a **container** \u2014 it wraps any children and\n  navigates on click, so it is the default way to move between pages. Its `mode`: `\"page\"` links to another space\n  page (set `href` to the target page, folder path resolved for you); `\"internal\"` takes a path inside the space and\n  resolves `{{token}}` templates in it, so a row's \"view\" link is `mode:\"internal\", href:\"posts/{{postId}}\"`;\n  `\"external\"` is a full URL. `target` is `self`/`blank`/`parent`/`top`. Reach for the `navigate` globalCallback\n  only when navigation must be **one step inside a larger interaction flow** (e.g. save, then go) \u2014 for a plain link,\n  use `link`.\n\nPages can be grouped into **folders** (the sidebar tree). A folder is `{ ref, name, slug, parentId? }`; its `ref`\n**is its id** (there is no separate idRef), and that id is what a page and a nested folder reference.\n- **Folder slugs PREPEND to the page URL \u2014 this is how nested URLs are built.** The full path is each ancestor\n  folder's slug plus the page slug, joined by `/`: a page at slug `\"1-1-1\"` inside `folder-1` > `folder-1-1`\n  resolves to `/folder-1/folder-1-1/1-1-1`. So a folder slug is part of the route; keep folder slugs relative too.\n- Create/rename/move a folder with `upsertFolder` (the `ref` you pass on create becomes its id \u2014 pick a stable one\n  like `\"blog\"`). Nest it under another with `parentId` (a folder ref); `parentId: null` moves it back to the root.\n- Put a page in a folder with `upsertPage`'s `folder` (a folder ref). A page's `folder` is always either **empty\n  (root)** or an **existing folder id**: `folder: null` or `folder: \"\"` moves it to the root, and any other value\n  must resolve to a folder that already exists or is created earlier in the same batch \u2014 an unknown folder is\n  rejected, never stored.\n- `deleteFolder` removes a folder and **promotes its contents up one level** \u2014 its child folders and its pages move\n  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.\n- **Disable a page** with `upsertPage`'s `enabled: false`; `enabled: true` re-enables it (defaults to enabled, and\n  a page read reports its current `enabled`). Disabling only affects the **published SDK runtime** \u2014 the page stops\n  being routable/accessible to end users. It stays fully **editable here**: you can still read it and apply any op to\n  a disabled page. This does not delete it \u2014 `deletePage` does.\n\n## Settings\nSpace-level configuration lives in `plitzi://settings/{env}` and is edited with a single **`patchSettings`** op\n(merge \u2014 only the fields you pass change):\n- `customCss` \u2014 **raw global CSS** injected for the whole space. Use it only for genuinely site-wide rules\n  (`@keyframes`, `@font-face`, resets). To style an element, write a **definition** and attach it \u2014 never customCss.\n- `keepState` / `stateStorage` \u2014 persist element state across reloads (`localStorage`/`sessionStorage`).\n- **User provider / auth**: `userProvider` (`auth0`|`basic`|`custom`|`\"\"` to disable), `auth0Domain`,\n  `auth0ClientId`, `tokenStorage`, and the `loginUrl`/`userUrl`/`refreshUrl`/`logoutUrl` + `detailsPath`/\n  `tokenPath`/`expirationTimePath` mapping. Example \u2014 inject a keyframe globally:\n  `{ \"type\": \"patchSettings\", \"customCss\": \"@keyframes spin { to { transform: rotate(360deg); } }\" }`.\n\n## Semantics\n- **props are fully replaced** on `upsertElement`: send every prop you want to keep. To change only some props,\n  use **`patchElement`** \u2014 it merges `props`/`style` onto the existing element (listed keys change, `null` unsets\n  a key, everything else is preserved) and never creates. Combined with `plitzi_search` (which returns the ref +\n  stateVersion), a targeted edit is two calls with no read.\n- **definition CSS is fully replaced** on `upsertDefinition`: send every property you want to keep. To change only\n  some declarations, use **`patchDefinition`** \u2014 it merges CSS per breakpoint/state/variant/slot onto the existing\n  definition (listed keys change, `null` removes a property, everything else is preserved) and never creates.\n  Example \u2014 recolor one definition without resending it: `{ \"type\": \"patchDefinition\", \"ref\": \"btn-x\",\n  \"desktop\": { \"background-color\": \"#111\" } }`.\n- **Atomic batches**: if any operation fails, `plitzi_apply` persists nothing.\n- **Every resource you touch must be malformation-free \u2014 pre-existing errors block the save.** When your batch edits\n  an element (or a definition/global/id style), the validator also checks the resource's **current stored content**\n  for malformations \u2014 a broken transformer action, a malformed interaction node, invalid CSS \u2014 even in parts your\n  edit does not touch. Such a finding is reported as a `Pre-existing malformation in <resource>: \u2026` **error**, and\n  `plitzi_apply` rejects the batch until it is fixed. These are **not caused by your change** (the message says so)\n  \u2014 do not be confused; fix them **in the same batch** and re-apply. Because the check runs on the resulting state,\n  including the fix in your batch is exactly what unblocks the save. (Advisory issues \u2014 an unobserved source/action\n  name that may still be a valid plugin, a binding target a plugin manifest does not list \u2014 come back as\n  `Pre-existing issue \u2026` **warnings** and do not block.)\n- **Optimistic concurrency \u2014 read before you write, and prove your read is current.** Editing a resource means you\n  read it first, so you hold its `stateVersion`. **Always pass `expectedResourceVersions`** (URI \u2192 the stateVersion\n  you read) for every resource your batch changes. If another agent edited it in the meantime, the live version no\n  longer matches and apply is **rejected with a conflict** \u2014 nothing persists. Then re-read the reported resources\n  (their new content + version) and retry on top of the fresh state. This is exactly how a file editor forces a\n  re-read after a stale write: it is what keeps concurrent agents from silently overwriting each other's changes, so\n  never omit it \"to save a call\".\n";

package/dist/src/modules/mcp/helpers/space.d.ts

@@ -102,5 +102,14 @@ export declare const pageRefOfElement: (schema: Schema, el: Element) => string;
 /** Total number of descendant elements under a subtree (excluding the root). */
 export declare const descendantCount: (schema: Schema, rootId: string) => number;
 export declare const emptySpaceMessage = "Space data not available";
+/** The code a space-dependent answer carries when the connection reaches no space, so both the agent and a host UI
+ *  can tell "this connection cannot do that" from "the call failed". */
+export declare const noSpaceError = "NO_SPACE_ATTACHED";
 export declare const unauthorizedSpaceMessage: string;
+/** Raised when a space-dependent operation runs on a connection that resolves no spaceId. A type of its own so the
+ *  host answers it as a STATE of the connection — a plain result the agent reads — instead of letting it surface as
+ *  a failed call, which hosts render to the user as "cannot connect to this server". */
+export declare class NoSpaceError extends Error {
+    constructor();
+}
 export declare const generateObjectId: () => string;

package/dist/src/modules/mcp/resources/index.d.ts

@@ -1,6 +1,7 @@
-export { readResource, resourceVersion } from './router';
+export { readPublicResource, readResource, resourceVersion } from './router';
 export { registerResources } from './register';
 export { resourceErrorMessage } from './canonical';
+export { RENDER_GUIDE_URI, RENDER_TYPES_URI } from './renderGuide';
 export { buildTypeRegistry, cssProperties, cssShorthands, expandShorthand, isCssProperty, suggestCssProperty } from '../catalogs';
 export type { TypeInfo, TypePropInfo, TypeRegistry } from '../catalogs';
 export * from '../tools/operations/schema/translator';

package/dist/src/modules/mcp/resources/register.d.ts

@@ -2,5 +2,9 @@ import { McpLog, Space } from '../helpers';
 import { Env } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
- *  loaded lazily via getSpace, so listing resources never touches the store — only reading one does. */
-export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env, log: McpLog) => void;
+ *  loaded lazily via getSpace, so listing resources never touches the store — only reading one does.
+ *
+ *  `hasSpace` is false when the connection reaches no space (a guest / widgets-only grant): the space-dependent
+ *  families are then not registered at all, so the catalog the agent browses holds only what it can actually
+ *  open — no listing that answers every read with the same refusal. */
+export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env, log: McpLog, hasSpace: boolean) => void;

package/dist/src/modules/mcp/resources/renderGuide.d.ts

@@ -1,5 +1,10 @@
 import { McpLog } from '../helpers';
+import { ResourceEnvelope } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
 export declare const RENDER_TYPES_URI = "plitzi://render/types";
+/** The same two documents through the READ path (the router, hence plitzi_read), not only as MCP resources: an
+ *  agent that reaches for the batch-read tool — the reflex the guide itself teaches — must not be told its own
+ *  authoring guide does not exist. Space-independent, like the core singletons. */
+export declare const readRenderResource: (uri: string) => ResourceEnvelope<unknown> | undefined;
 export declare const registerRenderResources: (server: McpServer, log: McpLog) => void;

package/dist/src/modules/mcp/resources/router.d.ts

@@ -2,5 +2,9 @@ import { Space } from '../helpers';
 import { Env, ResourceEnvelope } from '../types';
 /** Resolve a resource URI to its versioned envelope, or null if unknown / not found. */
 export declare const readResource: (space: Space, env: Env, rawUri: string) => ResourceEnvelope<unknown> | null;
+/** What a connection carrying NO space (a guest / widgets-only grant) can still read: the space-independent
+ *  singletons and the render docs. Undefined for everything else, so the caller says the connection has no space
+ *  instead of answering out of an empty one — an empty page list would read as "this space has no pages". */
+export declare const readPublicResource: (env: Env, rawUri: string) => ResourceEnvelope<unknown> | undefined;
 /** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
 export declare const resourceVersion: (space: Space, env: Env, uri: string) => string | null;

package/dist/src/modules/mcp/server.d.ts

@@ -2,10 +2,11 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { PreviewClient, ScreenshotClient } from './types';
 import { SSRAdapters, ServerLogger } from '@plitzi/sdk-shared';
 /** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
- *  space fresh through the adapters — schema and style are two documents, read/written independently. Both the
- *  spaceId and the space itself resolve lazily, so the public surface (handshake, tools-list, resources-list,
- *  and the space-independent guide / css-properties resources) works even when the request carries no auth —
- *  only a space-dependent tool/resource demands a spaceId, failing with `unauthorizedSpaceMessage` if none. */
+ *  space fresh through the adapters — schema and style are two documents, read/written independently. The spaceId
+ *  is resolved once per request, up front, because it decides what this connection IS: with a space, the full
+ *  editing server; without one (no auth, a guest connection, a widgets-only grant), a widget server that offers
+ *  only what works there. The space documents themselves still load lazily — the handshake and the listings never
+ *  touch the store. */
 export interface McpServerContext {
     adapters: SSRAdapters;
     getSpaceId: () => Promise<number | undefined>;
@@ -19,4 +20,4 @@ export interface McpServerContext {
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
     logger?: ServerLogger;
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => McpServer;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => Promise<McpServer>;

package/dist/src/modules/mcp/tools/read.d.ts

@@ -5,4 +5,5 @@ export declare const readShape: {
     uris: z.ZodArray<z.ZodString>;
 };
 export declare const read: (input: ReadInput, space: Space, env: Env) => ReadResponse;
+export declare const readPublic: (input: ReadInput, env: Env) => ReadResponse;
 export declare const readTool: import('.').ToolDef;

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

@@ -39,6 +39,11 @@ export interface ToolSpec<Shape extends ZodRawShape> {
      *  iframe, receiving the tool result). Registered as the tool's `_meta.ui` — see registerAppTool. */
     ui?: McpUiToolMeta;
     run: (input: z.infer<ZodObject<Shape>>, ctx: ToolContext) => unknown;
+    /** What the tool still does on a connection that carries NO space (a guest / widgets-only grant): it keeps only
+     *  the part that needs none — plitzi_read serves the public documents and says so for the rest. A tool that
+     *  defines this stays advertised there; one that does not is not registered at all, so the agent never calls
+     *  something that cannot work. */
+    runPublic?: (input: z.infer<ZodObject<Shape>>, env: Env) => unknown;
 }
 /** What the registry holds and the hosts register from: the same metadata plus a type-erased `execute` that
  *  validates raw args against the shape and delegates to the typed `run`. Produced by `defineTool`. */
@@ -52,6 +57,9 @@ export interface ToolDef {
     spaceless?: boolean;
     ui?: McpUiToolMeta;
     execute: (args: unknown, ctx: ToolContext) => unknown;
+    /** Present when the tool degrades to a space-less connection (see ToolSpec.runPublic); its absence is what tells
+     *  the host not to advertise the tool there. */
+    executePublic?: (args: unknown, env: Env) => unknown;
 }
 /** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
  *  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.18",
+  "version": "0.32.19",
   "license": "AGPL-3.0",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -29,9 +30,9 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@plitzi/plitzi-sdk": "0.32.18",
-    "@plitzi/sdk-schema": "0.32.18",
-    "@plitzi/sdk-shared": "0.32.18",
+    "@plitzi/plitzi-sdk": "0.32.19",
+    "@plitzi/sdk-schema": "0.32.19",
+    "@plitzi/sdk-shared": "0.32.19",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"

package/skills/plitzi-render/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: plitzi-render
+description: >-
+  Show answers as a rendered visual widget instead of plain text, using the Plitzi MCP's plitzi_render tool.
+  Use whenever the reply is naturally visual or structured — a recipe, a comparison, pricing tiers, a profile,
+  a menu, steps/checklist, a product card, a dashboard-like summary — or whenever the user asks to design,
+  build, show, or "make it look nice". Requires the Plitzi MCP server (the plitzi_render tool) to be connected.
+---
+
+# Rendering answers as Plitzi widgets
+
+`plitzi_render` renders a small, self-contained UI widget the user can SEE. It runs the Plitzi SDK offline — no
+backend, no account, no space, so it works even on a connection with no credentials. Prefer **showing** a widget
+over a long text answer whenever the content is naturally visual.
+
+## When to reach for it
+
+- **Something to design or build**: a card, hero, banner, form, pricing table — anything the user asks you to
+  "create / design / build / show / make look nice".
+- **A naturally visual answer**: a recipe → a card with photo + ingredients; a comparison → side-by-side tiles;
+  steps → a checklist; a product, place or person → a profile card; options → a tiled menu.
+
+Keep writing plain text when the answer is genuinely textual — an explanation, code, a discussion. One good widget
+beats a wall of text, but a widget wrapping a paragraph helps no one.
+
+## Before the first call
+
+Read the MCP resource **`plitzi://render/guide`** once per conversation. It is the authoritative authoring model:
+every operation, the element types and their props, the styling system, worked examples. `plitzi://render/types`
+lists every element type with its description. Don't reconstruct the schema from memory — read the guide.
+
+## The shape of a good call
+
+Everything the widget needs travels in ONE call, as `operations`. Three ops carry almost every widget:
+
+- **`upsertDefinitions`** — declare ALL the CSS classes at once, one class per *look* (not per property).
+- **`upsertElement`** — build the whole tree in a single op, nesting with `children` under `pageRef: "render"`.
+- **`repeatElement`** — the moment two siblings differ only in data, write the row ONCE as a template with
+  `{{item.field}}` placeholders and pass `items`. Rows come out numbered (`tile-1`, `tile-2`…). A list inside each
+  row is the same op: give a template node `repeat: { items: "{{item.<field>}}", template: … }`.
+
+```json
+{
+  "operations": [
+    {
+      "type": "upsertDefinitions",
+      "definitions": {
+        "panel": {
+          "desktop": {
+            "display": "flex",
+            "flex-direction": "column",
+            "gap": "12px",
+            "padding": "16px",
+            "min-width": "0",
+            "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))"
+          }
+        },
+        "row": {
+          "desktop": { "display": "flex", "flex-wrap": "wrap", "gap": "12px", "min-width": "0" },
+          "mobile": { "flex-direction": "column" }
+        },
+        "tile": {
+          "desktop": {
+            "flex": "1 1 0%",
+            "min-width": "160px",
+            "padding": "12px",
+            "border-radius": "10px",
+            "border": "1px solid var(--color-border-primary, light-dark(#e2e8f0, #333a48))",
+            "background-color": "var(--color-background-secondary, light-dark(#ffffff, #1f2430))"
+          }
+        },
+        "tile-title": { "desktop": { "margin": "0", "font-size": "15px" } },
+        "tile-price": { "desktop": { "margin": "0", "font-size": "13px", "opacity": "0.75" } }
+      }
+    },
+    {
+      "type": "upsertElement",
+      "pageRef": "render",
+      "element": {
+        "ref": "panel",
+        "type": "container",
+        "style": { "base": ["panel"] },
+        "children": [{ "ref": "title", "type": "heading", "subType": "h3", "props": { "content": "Plans" } }]
+      }
+    },
+    {
+      "type": "repeatElement",
+      "pageRef": "render",
+      "parentRef": "panel",
+      "ref": "plans",
+      "style": { "base": ["row"] },
+      "template": {
+        "ref": "tile",
+        "type": "container",
+        "style": { "base": ["tile"] },
+        "children": [
+          {
+            "ref": "name",
+            "type": "heading",
+            "subType": "h4",
+            "props": { "content": "{{item.name}}" },
+            "style": { "base": ["tile-title"] }
+          },
+          {
+            "ref": "price",
+            "type": "paragraph",
+            "props": { "content": "{{item.price}}" },
+            "style": { "base": ["tile-price"] }
+          }
+        ]
+      },
+      "items": [
+        { "name": "Starter", "price": "$0 / month" },
+        { "name": "Team", "price": "$19 / month" },
+        { "name": "Business", "price": "$49 / month" }
+      ]
+    }
+  ]
+}
+```
+
+## The five things that decide whether it looks good
+
+1. **Width is free, height is scarce.** The widget renders in a side panel. A plain container stacks its children
+   vertically — that is the tall, half-empty default to avoid. Put peers (metrics, plans, options, image + text) in
+   a wrapping row (`display:flex` + `flex-wrap:wrap`, children `flex:1 1 0%` with a `min-width` as the wrap
+   threshold) or a grid with `grid-template-columns: repeat(auto-fit, minmax(160px, 1fr))`. Stack only what reads in
+   order: heading over paragraph, forms, steps, prose.
+2. **The host may be in dark mode.** Never hardcode a light palette. Take colours from the host variables with a
+   `light-dark()` fallback, and always set `color` wherever you set `background-color`.
+3. **Watch the SDK defaults.** Every container has `min-width`/`min-height: 50px` — set them to `0` for rails,
+   dividers, dots and any flex child that must shrink. Headings and paragraphs keep the browser's margins; zero
+   them and space with the parent's `gap`.
+4. **Never hand-draw a scene in a `data:` URI.** An inline SVG illustration costs more tokens than the entire rest
+   of the widget. Use an `https` image, a flat colour, or a CSS gradient.
+5. **Write CSS plainly.** Kebab-case properties, shorthands welcome (`padding: 8px 16px`, `border: 1px solid red`,
+   `font: bold 16px/1.5 Arial`) — they are expanded and stored as longhands, so a breakpoint or state can override
+   one property on its own.
+
+## Iterating on a widget you already rendered
+
+Every render answers with a **`renderId`**. To change that widget, do NOT rebuild it: call again with
+`patch: true`, that `renderId`, and only the operations that differ (`patchElement`, `patchDefinition`,
+`deleteElement`, a new `repeatElement`). Address rows by the refs you already know (`tile-1`, `tile-2`). The widget
+merges the delta into the batch it was built from and reports back what it applied, errors included.
+
+Patch **only** to modify that widget. A different subject, or a different kind of widget, is a fresh render with no
+`patch` — the delta is merged into the previous batch, so patching a new idea leaves the user looking at both at
+once. Rebuilding when you could have patched only costs tokens; patching when you should have rebuilt costs the
+user a wrong widget.
+
+If the answer says the widget could not be recovered (a surface that renders no widgets, a host that keeps no
+storage, a conversation resumed elsewhere), send the whole batch again without `patch`.
+
+## When a call fails
+
+`plitzi_render` answers with `rendered: false` and `errors: [{ path, message, hint }]`, plus `warnings` for smaller
+issues. The `path` names the operation, so fix that one and call again — you never lose the rest of the batch. An
+unknown prop comes back as a warning naming the right one, so probing is safe.
+
+## After it renders
+
+The widget is shown to the user; you get a compact summary. Don't re-describe what they can already see — a short
+caption or a follow-up question is enough.
+
+## Going further
+
+Widgets can be data-driven and interactive, not only static: an `apiContainer` fetches at runtime, `upsertBinding`
+wires that data into elements, and `upsertInteractionFlow` makes them react to clicks. See the "Data &
+interactivity" section of `plitzi://render/guide`.

package/dist/src/modules/mcp/apps/render/heldBatch.d.ts

@@ -1,10 +0,0 @@
-/** Where the batch a widget was built from survives between calls — on the HOST, so the server can keep nothing.
- *
- *  It cannot live in the view's memory: the Apps spec binds a view to ONE tool call (`ui/notifications/tool-input`
- *  is sent "at most once", and the host renders a fresh iframe when a UI tool is called), so the patch call the
- *  model makes arrives in a brand-new instance whose memory is empty. localStorage keyed by an id the server hands
- *  back is the spec's own state-persistence pattern (`_meta.viewUUID` in the Apps docs); here the key is the
- *  renderId, which the model also carries, so a patch names the widget it means instead of assuming "the last one".
- */
-export declare const readHeldBatch: (renderId: string, store?: Storage | undefined) => unknown[] | undefined;
-export declare const writeHeldBatch: (renderId: string, operations: unknown[], store?: Storage | undefined) => void;

package/dist/src/modules/mcp/apps/render/heldBatch.test.d.ts

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

package/dist/src/modules/mcp/apps/render/view.d.ts

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