npm - @plitzi/sdk-server - Versions diffs - 0.32.18 → 0.32.20 - Mend

@plitzi/sdk-server 0.32.18 → 0.32.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/dist/modules/mcp/apps/shared/registerApp.js CHANGED Viewed

@@ -11,7 +11,7 @@ var DEFAULT_CSP = {
 };
 /** Serves the app as a self-contained page: no import map, no asset mounts, no cross-origin fetches, so the
 *  strictest host sandbox runs it and no deployment has to serve anything extra. */
-var registerApp = (server, app) => {
+var registerApp = (server, app, settings) => {
 	const meta = { ui: { csp: app.csp ?? DEFAULT_CSP } };
 	registerAppResource(server, app.name, app.uri, {
 		description: app.description,
@@ -19,7 +19,7 @@ var registerApp = (server, app) => {
 	}, async () => ({ contents: [{
 		uri: app.uri,
 		mimeType: RESOURCE_MIME_TYPE,
-		text: await page(app),
+		text: await page(app, settings),
 		_meta: meta
 	}] }));
 };

package/dist/modules/mcp/apps/shared/shell.ejs CHANGED Viewed

@@ -47,6 +47,11 @@
   <body>
     <div id="app"></div>
+    <%# Deployment switches, before the app so the view reads them as it mounts. They ride in the page, not the
+        bundle, so a server serving both settings still builds the browser bundle once. -%>
+    <script id="plitzi-view-settings">
+      window.__PLITZI_VIEW__ = <%- settings %>;
+    </script>
     <script>
 <%- app %>
     </script>

package/dist/modules/mcp/handler.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -10,6 +10,8 @@ var RENDER_TYPE_CATEGORIES = /* @__PURE__ */ new Set([
 	"form",
 	"provider"
 ]);
+var RENDER_RAW_HTML_TYPE = "blockHtml";
+var rawHtmlDescription = "Renders a raw HTML string (props.content) — in a widget, the way to draw an inline <svg>: a logo, an icon, a sparkline, a decorative shape. Use fill/stroke \"currentColor\" so it takes the host theme. Markup only: <script>, javascript: URLs and inline on* handlers are rejected.";
 var renderTypesNote = "The built-in element types you can put in a plitzi_render widget, grouped by category. Pick by `description`. For the props of each type and the full authoring model, read plitzi://render/guide. Types that need a backend (providers) or a plugin are omitted because the widget renders offline.";
 var renderTypes = () => {
 	const types = {};
@@ -18,6 +20,12 @@ var renderTypes = () => {
 		category: info.category,
 		description: info.description
 	};
+	const rawHtml = BUILTIN_COMPONENTS[RENDER_RAW_HTML_TYPE];
+	if (rawHtml) types[RENDER_RAW_HTML_TYPE] = {
+		label: rawHtml.label,
+		category: rawHtml.category,
+		description: rawHtmlDescription
+	};
 	return {
 		note: renderTypesNote,
 		types
@@ -161,10 +169,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
@@ -256,24 +264,61 @@ The host publishes its palette as CSS variables on the page, so use them for eve
 | \`video\` | embedded video | \`props.src\` |
 | \`list\` / \`listItem\` | \`<ul>\` / \`<li>\` | nesting only |
 | \`markdown\` | rendered markdown | \`props.content\` |
+| \`blockHtml\` | a raw HTML string, as written | \`props.content\` — how you draw an inline \`<svg>\`, see below |
 \`subType\` is an element-level field (not a prop). Guessing is safe: an unknown prop for a type comes back as a
 **warning naming the right one**, not an error. This table covers the everyday types; the resource
 **plitzi://render/types** lists every built-in type you can use (with descriptions) — read it when you need one
 that is not here (lists, tabs, dialogs, forms, icons…).
-\`image\`/\`video\` \`src\` accepts any \`https\` URL, or a \`data:\`/\`blob:\` URI for a fully self-contained graphic
-(e.g. an inline SVG icon or a base64 image) — both render with no extra setup.
+\`image\`/\`video\` \`src\` accepts any \`https\` URL, or a \`data:\`/\`blob:\` URI for a fully self-contained graphic (a
+base64 raster) — both render with no extra setup. For a **vector** graphic do not encode a \`data:\` URI: draw it
+inline, as below.
+## Draw with inline SVG
+A widget can draw its own graphics, and it is often the difference between a plain block of text and something
+worth showing: a brand mark, a sparkline or donut, a badge, an empty-state glyph, a wave or blob behind a header,
+an arrow between two steps. Put the SVG **inline** in a \`blockHtml\` element — its \`props.content\` is rendered as
+written, so the markup needs no escaping, and the element is styled and laid out like any other box.
+\`\`\`json
+{
+  "operations": [
+    { "type": "upsertDefinitions", "definitions": {
+        "mark": { "desktop": { "display": "flex", "width": "32px", "height": "32px", "color": "var(--color-text-primary, light-dark(#0f172a, #e8eaed))" } }
+    } },
+    { "type": "upsertElement", "pageRef": "render", "element": {
+        "ref": "trend", "type": "blockHtml", "style": { "base": ["mark"] },
+        "props": { "content": "<svg viewBox='0 0 24 24' width='100%' height='100%' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round'><path d='M3 17l6-6 4 4 8-8'/><path d='M21 7v6h-6'/></svg>" }
+    } }
+  ]
+}
+\`\`\`
+- **Size from the class, not the drawing**: keep a \`viewBox\` and set \`width\`/\`height\` to \`100%\`, then the
+  \`blockHtml\`'s own \`width\`/\`height\` decide how big it renders — one drawing, any size.
+- **Colour with \`currentColor\`** (\`fill\` and/or \`stroke\`) and set \`color\` on the class from a host variable. A hex
+  buried inside the path is the same mistake as a hardcoded light palette: it cannot follow the theme.
+- **Single quotes inside the markup** keep the JSON free of \`\\"\` escapes, as above.
+- **Markup only.** \`<script>\`, \`javascript:\` URLs and inline \`on*\` handlers are rejected with an error — a widget
+  runs inside the host's UI. Animate with CSS (a \`states\` block, a \`transition\`) and wire behaviour with
+  interaction flows.
+**The budget.** Every path is text you write, so an SVG earns its place only while it stays small: a handful of
+paths, a few hundred characters, drawn ONCE and reused (same class, same content, or a \`repeatElement\` row) rather
+than redrawn per card. Skip it entirely when something cheaper does the job — a \`fontAwesome\` icon, an emoji in a
+\`text\`, an \`https\` image the user gave you, a CSS gradient or a \`border-radius\` shape. And a full illustration or
+a photo-real scene (a castle, a skyline, a detailed mascot) is still the wrong trade: it costs more than the entire
+rest of the widget and renders worse than the image it is imitating.
 ## Keep the call small
 Everything in \`operations\` is text you write, and a widget that takes two calls because the first ran long is a
 widget the user waits twice for. Two habits pay for themselves:
-- **Do not draw pictures in \`data:\` URIs.** A hand-written SVG scene (a castle, a skyline, a logo) costs more than
-  the entire rest of the widget and renders worse than nothing at all. Use an \`https\` image the user gave you, a
-  flat colour or a two-stop \`linear-gradient\` as a banner, an emoji or an \`fontAwesome\` icon for a glyph — or drop
-  the decoration. A small self-contained \`data:\` SVG is fine for a **simple** shape (a check, an arrow, a dot).
+- **Keep a drawing to a drawing.** Inline SVG is allowed and often worth it (see above), but a graphic that runs
+  longer than the widget around it has stopped paying for itself: a handful of paths, drawn once and reused rather
+  than redrawn per card, and an \`https\` image, a flat colour or a two-stop \`linear-gradient\` for anything bigger.
 - **One class per look, not per property.** Classes like \`tone-blue\` + \`tone-blue-text\` + \`tone-blue-bg\` for the
   same card triple the declarations and the attachments. Put everything the look needs in one class, add a second
   only for the part that genuinely varies between siblings (a colour), and reuse it — the whole point of a class.
@@ -355,6 +400,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 +432,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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, renderStreaming = true }) => {
 	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);
-	registerApps(server);
+		version: "0.32.20"
+	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
+	registerResources(server, getSpace, MCP_ENV, log, hasSpace);
+	registerApps(server, { streaming: renderStreaming });
 	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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,3 +1,4 @@
+import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
 import { emptySpace } from "../helpers/space.js";
 import { operations } from "./operations/index.js";
@@ -48,7 +49,7 @@ var render = (input) => {
 		errors: expansion.errors
 	};
 	const ops = expansion.operations;
-	const validation = validateOperations(space, ops);
+	const validation = validateOperations(space, ops, "widget");
 	if (!validation.valid) return {
 		rendered: false,
 		errors: validation.errors,
@@ -136,6 +137,8 @@ var toPatchResult = (ops, renderId) => {
 	};
 };
 var newRenderId = () => `r${randomUUID().slice(0, 8)}`;
+var ICON_TYPE = "fontAwesome";
+var drawsIcons = (offlineData) => Object.values(offlineData.schema.flat).some((element) => element.definition.type === ICON_TYPE);
 var toRenderResult = (res, renderId) => {
 	if (!res.rendered) return { content: [{
 		type: "text",
@@ -160,14 +163,15 @@ var toRenderResult = (res, renderId) => {
 		structuredContent: {
 			...summary,
 			offlineData: res.offlineData,
-			operations: res.operations
+			operations: res.operations,
+			...drawsIcons(res.offlineData) ? { iconCss: iconFontCss() } : {}
 		}
 	};
 };
 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.\n2a. GRAPHICS — a logo, a sparkline, a badge, a decorative shape: draw it as an INLINE <svg> in a blockHtml element (props.content), keeping a viewBox with width/height \"100%\" so its class sizes it, and fill/stroke \"currentColor\" so it follows the host theme. Budget it: a handful of paths, drawn once and reused, never a data: URI and never a full illustration — a photo-real scene costs more than the whole widget, so use an https image, a flat colour or a gradient for that. Markup only: scripts and on* handlers are rejected.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. 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 CHANGED Viewed

@@ -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/modules/mcp/tools/shared/validator/elements.js CHANGED Viewed

@@ -32,7 +32,17 @@ var checkVariantApplication = (initialState, path, ctx) => {
 		}
 	}
 };
+var EXECUTABLE_MARKUP = /<script\b|\son[a-z]+\s*=|javascript:/i;
+var checkRawMarkup = (type, props, path, ctx) => {
+	if (ctx.mode !== "widget" || !props || !RAW_CODE_TYPES.has(type)) return;
+	for (const [key, value] of Object.entries(props)) if (typeof value === "string" && EXECUTABLE_MARKUP.test(value)) ctx.errors.push({
+		path: `${path}.props.${key}`,
+		message: `Executable markup in a "${type}" prop is not allowed in a widget`,
+		hint: "A widget renders inside the host UI, so <script>, javascript: URLs and inline on* handlers are rejected. Keep the markup inert (an inline <svg> is what this type is for) and wire behaviour with upsertInteractionFlow."
+	});
+};
 var checkElementProps = (element, path, ctx) => {
+	checkRawMarkup(element.type, element.props, path, ctx);
 	if (!element.props || RAW_CODE_TYPES.has(element.type)) return;
 	for (const [key, value] of Object.entries(element.props)) if (typeof value === "string") checkVarRefs(value, `${path}.props.${key}`, ctx);
 	checkTypeProps(element.type, element.props, path, ctx);
@@ -55,4 +65,4 @@ var checkElementInput = (element, path, ctx, seen) => {
 	element.children?.forEach((child, i) => checkElementInput(child, `${path}.children[${i}]`, ctx, seen));
 };
 //#endregion
-export { checkElementInput, checkTypeProps, checkVariantApplication };
+export { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication };

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

@@ -8,7 +8,7 @@ import { checkObservedName, checkVarRefs, warnOnce } from "./context.js";
 import { checkBindingSourceScope, checkBindingTarget, checkBindingTransformers } from "./bindings.js";
 import { checkSlotCss } from "./css.js";
 import { checkRef } from "./refs.js";
-import { checkElementInput, checkTypeProps, checkVariantApplication } from "./elements.js";
+import { checkElementInput, checkRawMarkup, checkTypeProps, checkVariantApplication } from "./elements.js";
 import { checkInteractionNode } from "./interactions.js";
 //#region src/modules/mcp/tools/shared/validator/index.ts
 var STYLE_CATEGORIES = [
@@ -35,9 +35,10 @@ var buildTypeMeta = (catalog) => {
 };
 /** The shared validation context, derived from a space (+ the batch's ops, for batch-declared names). Extracted so
 *  the post-apply resource audit (auditResources) can run the same checks against the resulting draft. */
-var buildValidationCtx = (space, ops) => {
+var buildValidationCtx = (space, ops, mode = "space") => {
 	const registry = buildTypeRegistry(space.schema, space.catalog);
 	return {
+		mode,
 		errors: [],
 		warnings: [],
 		warned: /* @__PURE__ */ new Set(),
@@ -57,11 +58,11 @@ var buildValidationCtx = (space, ops) => {
 		observedSources: observedDataSources(space.schema)
 	};
 };
-var validateOperations = (space, ops) => {
+var validateOperations = (space, ops, mode = "space") => {
 	const batchPages = batchDeclaredPages(ops);
 	const batchFolders = batchDeclaredFolders(ops);
 	const folderRefs = () => pageFoldersOf(space.schema).map((f) => f.id);
-	const ctx = buildValidationCtx(space, ops);
+	const ctx = buildValidationCtx(space, ops, mode);
 	if (ops.length > 1e3) ctx.errors.push({
 		path: "operations",
 		message: `Batch has ${ops.length} operations (max ${MAX_OPS})`,
@@ -91,7 +92,10 @@ var validateOperations = (space, ops) => {
 				const target = page ? resolveRef(space.schema, page, op.ref) : void 0;
 				if (op.props) {
 					for (const [key, value] of Object.entries(op.props)) if (typeof value === "string") checkVarRefs(value, `${base}.props.${key}`, ctx);
-					if (target && target.id !== page?.id) checkTypeProps(target.definition.type, op.props, base, ctx);
+					if (target && target.id !== page?.id) {
+						checkRawMarkup(target.definition.type, op.props, base, ctx);
+						checkTypeProps(target.definition.type, op.props, base, ctx);
+					}
 				}
 				checkVariantApplication(op.initialState, `${base}.initialState`, ctx);
 				break;

package/dist/src/modules/mcp/apps/index.d.ts CHANGED Viewed

@@ -1,8 +1,11 @@
-import { McpApp } from '../types';
+import { McpApp, McpViewSettings } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** What a view gets when the deployment says nothing: streaming on, because a host that streams no arguments
+ *  paints exactly what it painted before. */
+export declare const DEFAULT_VIEW_SETTINGS: McpViewSettings;
 /** Every MCP App this server serves. A new one is a folder beside `render/` (its definition + its view) and one
  *  line here — the tool that opens it points at its `uri` through `ui: { resourceUri }`. Start from `example/`,
  *  which is that same shape stripped to the minimum. */
 export declare const apps: McpApp[];
-export declare const registerApps: (server: McpServer) => void;
-export { RENDER_APP_URI } from './render';
+export declare const registerApps: (server: McpServer, settings?: McpViewSettings) => void;
+export { iconFontCss, RENDER_APP_URI } from './render';

package/dist/src/modules/mcp/apps/render/index.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
 import { McpApp } from '../../types';
 export declare const RENDER_APP_URI = "ui://plitzi/render.html";
 export declare const renderApp: McpApp;
+export { iconFontCss } from './styles';

package/dist/src/modules/mcp/apps/render/styles.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/** Lifts every @font-face block out of a stylesheet. Brace counting rather than a CSS parser: a @font-face body is
+ *  plain declarations, and base64 payloads and url() values carry no braces of their own. */
+export declare const splitFontFaces: (css: string) => {
+    base: string;
+    fonts: string;
+};
+/** What the page shell inlines: the SDK stylesheet without the icon fonts. */
+export declare const widgetCss: () => string;
+/** The icon fonts, for the renders that draw one. */
+export declare const iconFontCss: () => string;