@plitzi/sdk-server 0.32.17 → 0.32.19

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+
+- v0.32.18
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.18
+  - @plitzi/sdk-schema@0.32.18
+  - @plitzi/sdk-shared@0.32.18
+
 ## 0.32.17
 
 ### 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/render/view/index.tsx

@@ -0,0 +1,212 @@
+/* eslint-disable react-refresh/only-export-components -- one bundled entry: components cannot move out. */
+import { useApp, useHostStyles } from '@modelcontextprotocol/ext-apps/react';
+import PlitziSdk from '@plitzi/plitzi-sdk';
+import { Component, useEffect, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { readHeldBatch, writeHeldBatch } from './heldBatch';
+
+import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { OfflineDataRaw } from '@plitzi/sdk-shared';
+import type { ReactNode } from 'react';
+
+/** The view for plitzi_render: the entry the server bundles (React, the MCP Apps runtime and the Plitzi SDK
+ *  included) and inlines in the shared ui:// page shell — which is what lets it run in a sandbox that can fetch
+ *  nothing. It mounts on `#app`, the shell's root. */
+
+const panelStyle = { padding: 16, font: '13px/1.5 system-ui, sans-serif', color: '#b91c1c' } as const;
+
+// Every failure ends up here: an iframe left on its placeholder would hide the reason in the sandbox's console.
+const ErrorPanel = ({ title, details }: { title: string; details: string }) => (
+  <div style={panelStyle}>
+    <strong>{title}</strong>
+    <pre style={{ margin: '8px 0 0', whiteSpace: 'pre-wrap', color: '#7f1d1d', fontSize: 12 }}>{details}</pre>
+  </div>
+);
+
+class RenderBoundary extends Component<{ children: ReactNode }, { error?: Error }> {
+  state: { error?: Error } = {};
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  render() {
+    if (this.state.error) {
+      return <ErrorPanel title="Widget failed to render" details={this.state.error.message} />;
+    }
+
+    return this.props.children;
+  }
+}
+
+/** The batch the widget on screen was built from. It lives on the HOST side — this ref plus localStorage — because
+ *  the server keeps nothing between calls, which is what lets any replica (or an edge deployment) answer any
+ *  request. A patch is merged into it and sent back through `callServerTool`, so the full batch never enters the
+ *  model's context. The ref alone would not do: the host gives each tool call its own view, so a patch usually
+ *  starts from an empty instance and reads the batch back from storage by renderId (see heldBatch.ts). */
+type Held = { renderId?: string; operations: unknown[] };
+
+const summarise = (result: CallToolResult): string => {
+  const text = result.content.find(entry => entry.type === 'text');
+
+  return text?.text ?? 'no summary';
+};
+
+const RenderApp = () => {
+  const [result, setResult] = useState<CallToolResult | null>(null);
+  const [cancelled, setCancelled] = useState<string | undefined>(undefined);
+  const [context, setContext] = useState<McpUiHostContext | undefined>(undefined);
+  const held = useRef<Held>({ operations: [] });
+  const appRef = useRef<App | null>(null);
+
+  // A patch carries only what changed. Merging it onto the held batch and re-calling the tool is what keeps the
+  // server stateless: it re-renders the WHOLE widget (so refs, integrity and the audit are all checked as usual)
+  // from a payload that travelled host↔server, and the model hears the outcome through updateModelContext.
+  const applyPatch = async (renderId: string, delta: unknown[]): Promise<void> => {
+    const app = appRef.current;
+    if (!app) {
+      return;
+    }
+
+    const base = held.current.renderId === renderId ? held.current.operations : (readHeldBatch(renderId) ?? []);
+    if (base.length === 0) {
+      await app.updateModelContext({
+        content: [
+          {
+            type: 'text',
+            text: `The widget ${renderId} could not be recovered, so nothing was patched. Call plitzi_render again with the complete batch and without \`patch\`.`
+          }
+        ]
+      });
+
+      return;
+    }
+
+    const merged = [...base, ...delta];
+    // The round trip can fail on its own: a host that forwards no tool calls, a connection dropped mid-patch, a
+    // view torn down while the answer is in flight. Unreported it would surface as an unhandled rejection inside
+    // the sandbox and the model would wait forever for a widget that is never coming.
+    try {
+      const rendered = await app.callServerTool({
+        name: 'plitzi_render',
+        arguments: { operations: merged, renderId }
+      });
+      const offlineData = rendered.structuredContent?.offlineData;
+      if (offlineData) {
+        const applied = (rendered.structuredContent?.operations as unknown[] | undefined) ?? merged;
+        held.current = { renderId, operations: applied };
+        writeHeldBatch(renderId, applied);
+        setResult(rendered);
+      }
+
+      await app.updateModelContext({
+        content: [
+          {
+            type: 'text',
+            text: offlineData
+              ? `Widget updated: ${summarise(rendered)}`
+              : `The patch did not apply, the widget is unchanged: ${summarise(rendered)}`
+          }
+        ]
+      });
+    } catch (reason) {
+      await app
+        .updateModelContext({
+          content: [
+            {
+              type: 'text',
+              text: `The patch could not be delivered (${reason instanceof Error ? reason.message : String(reason)}), so the widget is unchanged. Re-send the full batch without \`patch\` if it needs to change.`
+            }
+          ]
+        })
+        .catch(() => undefined);
+    }
+  };
+
+  // useApp creates the App, runs onAppCreated so every handler is in place BEFORE the handshake, and connects.
+  const { app, error } = useApp({
+    appInfo: { name: 'Plitzi Widget', version: '1.0.0' },
+    capabilities: {},
+    onAppCreated: instance => {
+      appRef.current = instance;
+      instance.ontoolresult = toolResult => {
+        const renderId = toolResult.structuredContent?.renderId as string | undefined;
+        if (toolResult.structuredContent?.patch === true && renderId) {
+          void applyPatch(renderId, (toolResult.structuredContent.operations as unknown[] | undefined) ?? []);
+
+          return;
+        }
+
+        // A result carrying no widget is a failed render or a refused patch. The model already reads its reasons
+        // as text, so it must not blank a widget that is on screen — nor drop the batch that widget was built
+        // from, which is the only copy of it anywhere. With nothing on screen yet, the error IS the view.
+        if (!toolResult.structuredContent?.offlineData && held.current.operations.length > 0) {
+          return;
+        }
+
+        const operations = (toolResult.structuredContent?.operations as unknown[] | undefined) ?? [];
+        held.current = { renderId, operations };
+        if (renderId && operations.length > 0) {
+          writeHeldBatch(renderId, operations);
+        }
+
+        setResult(toolResult);
+      };
+      instance.ontoolcancelled = params => setCancelled(params.reason ?? 'The host cancelled the render.');
+      instance.onhostcontextchanged = params => setContext(previous => ({ ...previous, ...params }));
+      instance.onteardown = () => ({});
+    }
+  });
+
+  // The context the host sent in its initialize result predates any change notification.
+  useEffect(() => {
+    if (app) {
+      setContext(app.getHostContext());
+    }
+  }, [app]);
+
+  useHostStyles(app, context);
+
+  const failure = error?.message ?? cancelled;
+  if (failure) {
+    return <ErrorPanel title="Could not render the widget" details={failure} />;
+  }
+
+  // Still connecting, or connected and waiting for the result: the page's CSS placeholder covers both.
+  if (!result) {
+    return null;
+  }
+
+  // The payload rides in structuredContent, which the protocol types as unknown-valued; plitzi_render is the one
+  // guaranteeing the shape, and the SDK validates it again when it renders.
+  const offlineData = result.structuredContent?.offlineData as OfflineDataRaw | undefined;
+  if (!offlineData) {
+    // A failed render answers with its (already compact) reasons as the tool's JSON text summary.
+    const text = result.content.find(entry => entry.type === 'text');
+
+    return <ErrorPanel title="Render failed" details={text?.text ?? 'The tool returned no widget data.'} />;
+  }
+
+  const insets = context?.safeAreaInsets;
+
+  return (
+    <div
+      style={{
+        padding: `${insets?.top ?? 0}px ${insets?.right ?? 0}px ${insets?.bottom ?? 0}px ${insets?.left ?? 0}px`
+      }}
+    >
+      <RenderBoundary>
+        <PlitziSdk offlineData={offlineData} offlineMode environment="main" renderMode="raw" />
+      </RenderBoundary>
+    </div>
+  );
+};
+
+const root = document.getElementById('app');
+if (root) {
+  // The SDK styles its tree from this container class down.
+  root.className = 'plitzi-root-container';
+  createRoot(root).render(<RenderApp />);
+}

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).
 
@@ -202,7 +203,12 @@ pointed at the old name is repointed with it, so the element stays wired. You do
   (prefer a unitless ratio like \`1.5\`, which tracks the font size). Changing one without the other leaves cramped or
   loosely-spaced text — they are a joint change, not two separate ones.
 - A definition lives in the **style schema**; an element's \`style.base\` (element schema) is the link that applies
-  it. Styling an element = upsertDefinition + upsertElement with that ref in \`style.base\`, in one batch.
+  it. Styling an element = upsertDefinitions + upsertElement with that ref in \`style.base\`, in one batch.
+- **Repeating siblings**: when a set of siblings shares a shape and differs only in data (a list, cards, rows,
+  steps), use \`repeatElement\` — the template once with \`{{item.field}}\` placeholders plus \`items\`, which
+  creates the wrapper and numbers each row's refs (\`step-1\`, \`step-2\`…). A list inside each row is the same op:
+  the wrapping node carries \`repeat: { items: "{{item.<list>}}", template: … }\` and its refs number both levels
+  (\`blk-2-3\`). Copy-pasting the subtree N times costs N times the tokens and drifts.
 - CSS keys are **kebab-case** (\`background-color\`). camelCase is rejected — read \`plitzi://css-properties\`.
 - **Write normal CSS — shorthands are accepted and expanded for you.** \`border\`, \`border-{side}\`,
   \`border-width\`/\`-color\`/\`-style\`, \`border-radius\`, \`padding\`, \`margin\`, \`inset\`, \`gap\`, \`overflow\`,
@@ -232,7 +238,9 @@ pointed at the old name is repointed with it, so the element stays wired. You do
 - **Three kinds of style live in the style schema — do not confuse them:**
   - **Definitions** = reusable CSS **classes** (\`upsertDefinition\`/\`patchDefinition\`/\`deleteDefinition\`, keyed by a
     class \`ref\`). Attach one to an element via \`style.base\` to style **that** element (and anything else that opts in).
-    This is the **default** way to style one element.
+    This is the **default** way to style one element. Declaring MORE than one class in a batch? Use
+    \`upsertDefinitions\` — one op carrying \`{ "<class>": { desktop: … }, … }\`, same result as the run of
+    \`upsertDefinition\` it replaces, without repeating the envelope once per class.
   - **Global styles** = the CSS equivalent of a bare element selector like \`button { … }\`
     (\`upsertGlobalStyle\`/\`patchGlobalStyle\`/\`deleteGlobalStyle\`, keyed by \`componentType\`). They style **every**
     element of that type at once. Use these for site-wide intent — e.g. "all buttons rounded":
@@ -456,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",