@plitzi/sdk-mcp 0.38.3 → 0.38.5

package/README.md

@@ -5,10 +5,10 @@ edit a space, the tool engine behind it, the widget renderer, and the draft-prev
 
 Connecting an agent and what it can do once connected: [AI agents and the MCP server](../../docs/en/mcp.md).
 
-It is a sibling of [`@plitzi/sdk-server`](../server/README.md), not a layer on top of it. That package serves
-pages; this one serves agents. They share only the HTTP kernel, which this package imports from
-`@plitzi/sdk-server/kernel` — a narrow entry that carries the dispatcher and the transports and nothing else, so
-a page-only deployment installs none of this and an MCP deployment loads no page renderer.
+It depends on [`@plitzi/sdk-server`](../server/README.md), never the other way round: that package serves pages,
+this one serves agents. It imports only that package's narrow entries — the HTTP kernel (`/kernel`, the dispatcher
+and the transports), OAuth (`/oauth`) and, for draft preview alone, the renderer (`/ssr`) — so a page-only
+deployment installs none of this and a dedicated MCP server loads no page renderer.
 
 ## Installation
 
@@ -75,16 +75,42 @@ The server is stateless: it resolves the space per request and reads and writes
 | `getOfflineData(spaceId, env, rev)` | for preview | Read side of draft-preview. Only the preview endpoint calls it. |
 | `getComponentCatalog(spaceId, env)` | no | The element types the space's plugins add, for the catalog resources. |
 | `getConnectors` / `saveConnector` / `deleteConnector` | for connectors | The space's connector manifests, read and written by the connector operations. |
-| `getActions` / `getActionTasks` / `saveAction` / `deleteAction` | for actions | The space's server actions, and the catalog of tasks a step may run — the deployment's and the space's own functions, each with its `origin`. |
+| `getActions` / `getActionTasks` / `saveAction` / `deleteAction` | for actions | The space's server actions, and the catalog of tasks a step may run — the deployment's, the space's own functions and its plugins' server halves, each with its `origin` (`deployment`, `space` or `plugin`). |
 | `getFunctions` / `saveFunctions` / `tryFunction` | for functions | The space's functions: read for `plitzi://functions/{env}`, saved (built and checked, refused from an older copy) by `upsertFunctionFile` / `deleteFunctionFile`, and run by `plitzi_try_function`. |
+| `getData` / `saveData` | for data | The space's data — JSON its server providers read as `/data/<file>`: read for `plitzi://data/{env}`, saved whole (each file checked, refused from an older copy) by `upsertDataFile` / `deleteDataFile`. |
 
 Schema and style are read as **separate documents** on purpose: `getOfflineData` is SSR-shaped and strips
 `style.platform`, which the style resources need.
 
+`createJsonAdapters({ offlineData })` from `@plitzi/sdk-server` offers `getSchema` and `getStyle` over a
+`{ schema, style }` JSON and — when given a path — `saveSchema` and `saveStyle`, each writing its document back into
+the file, so an MCP can run over it with a `getGrant` of yours beside it. It comes from the package root, which loads
+the page server too; a dedicated MCP that keeps its weight down writes those four itself, as
+[self-hosting/06](../../examples/self-hosting/06-mcp-server) does.
+
 Without a `getGrant` that resolves, the server still answers its public surface — the handshake, the tool list,
 the guide, the CSS-property catalog — and asks for a space only when a tool or resource needs one. A grant that
 resolves with `canWrite: false` reads everything and is refused at every write tool.
 
+## Options
+
+What MCP itself serves is `McpOptions` (`src/options.ts`), the **second** argument — to `createServer` here, and to
+`mcpExtensions(options)` for a page server — never a section of the server config, which a page-only deployment
+types its renderer with.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `path` | `/mcp` | Where MCP answers inside a server that also serves pages. A dedicated MCP server owns its whole origin and ignores it. |
+| `renderStreaming` | `true` | Whether the `plitzi_render` view paints from the tool arguments while the host still streams them. `false` keeps the view blank until the finished widget arrives. |
+| `proxy` | off | `McpProxyOptions`: with a `secret`, every external URL a render authored is rewritten to this server's signed endpoint (`path`, default `/__proxy`) and fetched here — the origins a widget needs cannot be declared ahead. `baseUrl`, `maxBytes` (8 MiB), `ttl` (7 days), `tools` (`['plitzi_render']`), `enabled`. |
+| `previewClient` | off | `{ url, secret? }`: the SSR `/preview` endpoint, for an MCP server that runs apart from the renderer. Without it the preview tools report `PREVIEW_UNAVAILABLE`. |
+| `screenshot` | off | `{ serviceUrl, renderBaseUrl }`: the browser service `plitzi_screenshot` renders through, and the SSR base it navigates to. Without it the tool is not registered. |
+| `oauth` | off | OAuth 2.1 for remote connectors — see [OAuth](#oauth). |
+
+```ts
+createServer({ adapters }, { screenshot: { serviceUrl, renderBaseUrl }, proxy: { secret } });
+```
+
 ## Tools
 
 | Tool | Access | What it does |
@@ -98,11 +124,14 @@ resolves with `canWrite: false` reads everything and is refused at every write t
 | `plitzi_render` | read | Render a self-contained UI widget, offline, with no space |
 | `plitzi_try_function` | write | Run one task of the space's functions against the draft, in the sandbox: its value, logs and error |
 
+The server advertises each tool's access as its `readOnlyHint` annotation, so a host can run a read without asking
+and ask before a write.
+
 Reads follow a filesystem model: list cheap, read one item in detail on demand. Agents are told never to
 hand-build a URI — every write and search response hands back the URI to use next.
 
 The tool functions are exported directly (`apply`, `search`, `read`, `validate`, `tools`), so a consumer can run
-them in-process and wrap them as its own agent's tools instead of speaking MCP over HTTP.
+them in-process instead of speaking MCP over HTTP.
 
 ## Draft preview
 
@@ -118,16 +147,13 @@ engine's job, not the renderer's.
 
 ## OAuth
 
-Opt-in and inert unless configured. With `oauth` set, an unauthenticated JSON-RPC call gets a `401` plus a
+Opt-in and inert unless configured. With `oauth` set (an [option](#options), not part of the server config), an unauthenticated JSON-RPC call gets a `401` plus a
 `WWW-Authenticate` challenge pointing at the discovery document — which is what makes a host such as Claude
 Desktop start the flow. Without it, the server stays anonymous, discovery answers `404`, and every caller reaches
 the public surface.
 
 ```ts
-createServer({
-  adapters,
-  oauth: { adapters: oauthAdapters, issuer, guest: { target: widgetsOnlyTarget } }
-});
+createServer({ adapters }, { oauth: { adapters: oauthAdapters, issuer, guest: { target: widgetsOnlyTarget } } });
 ```
 
 Publish the connector URL **with a path** (`https://host/mcp`), not the bare origin.
@@ -177,7 +203,7 @@ MCP server, [self-hosting/07](../../examples/self-hosting/07-ssr-preview) is the
 | Import | Carries |
 |---|---|
 | `@plitzi/sdk-mcp/server` | The dedicated MCP server and its clients. What an MCP deployment wires. |
-| `@plitzi/sdk-mcp` | Everything above plus the pipeline stages, `createPreview`, the tool engine and the AI engine. |
+| `@plitzi/sdk-mcp` | Everything above plus the pipeline stages, `createPreview` and the tool engine. |
 
 The split is about weight, not taste: ESM re-exports load eagerly, so the barrel pulls the draft-preview path and
 the renderer it reaches into. A `no-restricted-imports` rule and a test in `src/packageBoundary.test.ts` keep this

package/dist/createServer.d.ts

@@ -1,6 +1,6 @@
 import { McpOptions } from './options';
 import { SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
-/** The server this package makes: the lean mcp-ai pipeline over the bare context — no render template, caches
+/** The server this package makes: the lean MCP pipeline over the bare context — no render template, caches
  *  or plugin manager. `config` is the HTTP server's (port, TLS, health, logger, adapters); `options` is what MCP
  *  itself serves, and lives here rather than in that config because the server does not need to know. Pair it with
  *  the MCP adapters (getGrant + getSchema/getStyle/saveSchema/saveStyle) — the page adapters are not required, and

package/dist/createServer.js

@@ -5,7 +5,7 @@ var noPlugins = {
 	register: () => void 0,
 	invalidate: () => Promise.resolve()
 };
-/** The server this package makes: the lean mcp-ai pipeline over the bare context — no render template, caches
+/** The server this package makes: the lean MCP pipeline over the bare context — no render template, caches
 *  or plugin manager. `config` is the HTTP server's (port, TLS, health, logger, adapters); `options` is what MCP
 *  itself serves, and lives here rather than in that config because the server does not need to know. Pair it with
 *  the MCP adapters (getGrant + getSchema/getStyle/saveSchema/saveStyle) — the page adapters are not required, and

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-/** Everything this package offers: the MCP server, the tool engine that backs it, the AI engine a consumer wraps
- *  its own agent around, and the stages that mount all of it inside somebody else's page server.
+/** Everything this package offers: the MCP server, the tool engine that backs it, and the stages that mount all of
+ *  it inside somebody else's page server.
  *
  *  A dedicated MCP deployment wants `@plitzi/sdk-mcp/server` instead — this barrel also pulls the draft-preview
  *  endpoint, which reaches into the SSR renderer. */
@@ -10,8 +10,7 @@ export { createOAuthGuardStage, createOAuthStage } from '@plitzi/sdk-server/oaut
 export { previewStage } from './stages/preview';
 export { createWidgetProxyStage } from './stages/proxy';
 export { createPreview } from './preview/createPreview';
-export { AIEngine, toolResponseOk, toolResponseErr, zodToJsonSchema, getAllowedModes, bindTools, isToolActive, resolveToolHandler, isCallToolResult, toolResponseFromResult } from './modules/ai';
-export { createMcpServer, handleMcp, serveMcp, readMcpBody, buildAgentGuide, createHttpPreviewClient, createHttpScreenshotClient, createLocalScreenshotClient, resolveLocalBrowser, outlineOfSnapshot, outlineOfTree, unnamedControls } from './modules/mcp';
+export { createMcpServer, handleMcp, serveMcp, readMcpBody, createHttpPreviewClient, createHttpScreenshotClient, createLocalScreenshotClient, resolveLocalBrowser, outlineOfSnapshot, outlineOfTree, unnamedControls } from './modules/mcp';
 export { apply, search, read, validate, applyShape, searchShape, readShape, validateShape, operation, tools } from './modules/mcp/tools';
 export type { McpServerContext, McpRequestOptions, PreviewClient, PreviewRequestBody, PreviewResult, HttpPreviewClientConfig, ScreenshotClient, ScreenshotImage, ScreenshotResult, AccessibilityNode, AccessibilityOutline, CaptureView, UnnamedControl, Viewport, HttpScreenshotClientConfig } from './modules/mcp';
 export type { ApplyInput, SearchInput, SearchResponse, SearchHit, ReadInput, ReadResponse, ReadHit, ValidateInput, WriteResponse, WriteElement, Persisters, Operation, ToolDef, ToolContext } from './modules/mcp/tools';

package/dist/index.js

@@ -1,4 +1,3 @@
-import { buildAgentGuide } from "./modules/mcp/helpers/agentPrompt.js";
 import { operation } from "./modules/mcp/tools/operations/index.js";
 import { apply, applyShape } from "./modules/mcp/tools/apply/index.js";
 import { read, readShape } from "./modules/mcp/tools/read.js";
@@ -6,7 +5,6 @@ import { outlineOfSnapshot, outlineOfTree, unnamedControls } from "./modules/mcp
 import { search, searchShape } from "./modules/mcp/tools/search.js";
 import { validate, validateShape } from "./modules/mcp/tools/validate.js";
 import { tools } from "./modules/mcp/tools/index.js";
-import { bindTools, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema } from "./modules/ai/toolkit.js";
 import { createMcpServer } from "./modules/mcp/server.js";
 import { handleMcp, readMcpBody, serveMcp } from "./modules/mcp/handler.js";
 import { createHttpPreviewClient } from "./modules/mcp/previewClient.js";
@@ -17,7 +15,6 @@ import { previewStage } from "./stages/preview.js";
 import { createWidgetProxyStage } from "./stages/proxy.js";
 import { buildMCPPipeline, mcpExtensions } from "./pipeline.js";
 import { createServer } from "./createServer.js";
-import AIEngine from "./modules/ai/AIEngine.js";
 import { createLocalScreenshotClient, resolveLocalBrowser } from "./modules/mcp/localScreenshotClient.js";
 import { createOAuthGuardStage, createOAuthStage } from "@plitzi/sdk-server/oauth";
-export { AIEngine, apply, applyShape, bindTools, buildAgentGuide, buildMCPPipeline, createHttpPreviewClient, createHttpScreenshotClient, createLocalScreenshotClient, createMcpOnlyStage, createMcpServer, createMcpStage, createOAuthGuardStage, createOAuthStage, createPreview, createServer, createWidgetProxyStage, getAllowedModes, handleMcp, isCallToolResult, isToolActive, mcpExtensions, operation, outlineOfSnapshot, outlineOfTree, previewStage, read, readMcpBody, readShape, resolveLocalBrowser, resolveToolHandler, search, searchShape, serveMcp, toolResponseErr, toolResponseFromResult, toolResponseOk, tools, unnamedControls, validate, validateShape, zodToJsonSchema };
+export { apply, applyShape, buildMCPPipeline, createHttpPreviewClient, createHttpScreenshotClient, createLocalScreenshotClient, createMcpOnlyStage, createMcpServer, createMcpStage, createOAuthGuardStage, createOAuthStage, createPreview, createServer, createWidgetProxyStage, handleMcp, mcpExtensions, operation, outlineOfSnapshot, outlineOfTree, previewStage, read, readMcpBody, readShape, resolveLocalBrowser, search, searchShape, serveMcp, tools, unnamedControls, validate, validateShape };

package/dist/modules/mcp/apps/render/styles.d.ts

@@ -1,10 +1,6 @@
-/** 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. */
+/** The icon sheet with each font it names inlined: the widget's sandbox reaches no origin to fetch one from. */
+export declare const inlineIconFonts: (css: string, readFont: (file: string) => Buffer) => string;
+/** What the page shell inlines. */
 export declare const widgetCss: () => string;
-/** The icon fonts, for the renders that draw one. */
+/** Font Awesome, fonts and all, for the renders that draw an icon. */
 export declare const iconFontCss: () => string;

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

@@ -2,53 +2,22 @@ import { require } from "../shared/resolve.js";
 import path from "node:path";
 import { readFileSync } from "node:fs";
 //#region src/modules/mcp/apps/render/styles.ts
-/** The SDK stylesheet, split in two.
+/** The SDK's stylesheets, as a widget gets them.
 *
 *  Everything the page shell inlines is paid for by EVERY widget: the host loads the ui:// page into a fresh
-*  sandboxed iframe and parses it whole before anything paints, which is the "Rendering…" the user waits through.
-*  Three of those @font-face blocks are Font Awesome shipped as base64 woff2 — ~330 KB, close to a fifth of the
-*  page — and only a widget that authored a `fontAwesome` element has any use for them.
-*
-*  So the shell takes the base, and the fonts travel in the tool result of the renders that actually draw an icon
-*  (see tools/render.ts). A widget without icons never downloads a glyph; one with icons looks exactly the same as
-*  before. */
-/** Where the closing brace of the block opened at `open` is, so a nested one cannot end it early. Returns the
-*  string's length when the CSS is truncated mid-block, which drops that tail rather than mixing it into the base. */
-var blockEnd = (css, open) => {
-	let depth = 0;
-	for (let at = open; at < css.length; at++) if (css[at] === "{") depth++;
-	else if (css[at] === "}") {
-		depth--;
-		if (depth === 0) return at + 1;
-	}
-	return css.length;
-};
-/** 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. */
-var splitFontFaces = (css) => {
-	const base = [];
-	const fonts = [];
-	let cursor = 0;
-	for (let at = css.indexOf("@font-face", cursor); at !== -1; at = css.indexOf("@font-face", cursor)) {
-		const open = css.indexOf("{", at);
-		if (open === -1) break;
-		const end = blockEnd(css, open);
-		base.push(css.slice(cursor, at));
-		fonts.push(css.slice(at, end));
-		cursor = end;
-	}
-	base.push(css.slice(cursor));
-	return {
-		base: base.join(""),
-		fonts: fonts.join("")
-	};
-};
-var stylesheet = () => readFileSync(path.join(path.dirname(require.resolve("@plitzi/plitzi-sdk")), "plitzi-sdk.css"), "utf-8");
-var split;
-var sdkStyles = () => split ??= splitFontFaces(stylesheet());
-/** What the page shell inlines: the SDK stylesheet without the icon fonts. */
-var widgetCss = () => sdkStyles().base;
-/** The icon fonts, for the renders that draw one. */
-var iconFontCss = () => sdkStyles().fonts;
+*  sandboxed iframe and parses it whole before anything paints, which is the "Rendering…" the user waits through. So
+*  the shell takes only `plitzi-sdk.css`, and Font Awesome — its rules in `plitzi-sdk-icons.css`, its fonts files
+*  beside it — travels in the tool result of the renders that actually draw an icon (see tools/render.ts). A widget
+*  without icons never downloads a glyph. */
+var sdkDist = () => path.dirname(require.resolve("@plitzi/plitzi-sdk"));
+var FONT_URL = /url\((webfonts\/[\w.-]+\.woff2)\)/g;
+/** The icon sheet with each font it names inlined: the widget's sandbox reaches no origin to fetch one from. */
+var inlineIconFonts = (css, readFont) => css.replace(FONT_URL, (_match, file) => `url(data:font/woff2;base64,${readFont(file).toString("base64")})`);
+var base;
+var icons;
+/** What the page shell inlines. */
+var widgetCss = () => base ??= readFileSync(path.join(sdkDist(), "plitzi-sdk.css"), "utf-8");
+/** Font Awesome, fonts and all, for the renders that draw an icon. */
+var iconFontCss = () => icons ??= inlineIconFonts(readFileSync(path.join(sdkDist(), "plitzi-sdk-icons.css"), "utf-8"), (file) => readFileSync(path.join(sdkDist(), file)));
 //#endregion
-export { iconFontCss, splitFontFaces, widgetCss };
+export { iconFontCss, inlineIconFonts, widgetCss };

package/dist/modules/mcp/apps/render/view/index.tsx

@@ -34,7 +34,7 @@ const ErrorPanel = ({ title, details }: { title: string; details: string }) => (
  *  wholesale when the result lands. A host that streams nothing paints none of this and keeps the static text. */
 const SKELETON_BAR_WIDTHS = ['92%', '78%', '85%', '64%', '88%', '72%'];
 
-// The deployment's own switch (mcpAi.renderStreaming), handed over by the page. Absent means on: a page built
+// The deployment's own switch (McpOptions.renderStreaming), handed over by the page. Absent means on: a page built
 // before the setting existed carries none, and a host that streams no arguments paints the same either way.
 const streamingEnabled =
   (globalThis as { __PLITZI_VIEW__?: { streaming?: boolean } }).__PLITZI_VIEW__?.streaming !== false;

package/dist/modules/mcp/catalogs/index.js

@@ -1,4 +1,4 @@
 import { buildDataSourceCatalog, buildInteractionCatalog, observedDataSources, observedInteractionActions } from "./observed.js";
 import { buildTypeRegistry } from "./registry.js";
-import { BUILTIN_ELEMENT_CALLBACKS as BUILTIN_ELEMENT_CALLBACKS$1, BUILTIN_GLOBAL_CALLBACKS as BUILTIN_GLOBAL_CALLBACKS$1, BUILTIN_UTILITIES as BUILTIN_UTILITIES$1, applyBuiltinCallback, applyElementCallback, applyUtility, cssProperties as cssProperties$1, cssShorthands, elementCatalog as elementCatalog$1, elementTypeNames, expandShorthand, expandShorthandPatch, getElementCallback, getGlobalCallback, getUtility, hiddenParams, isCssProperty, reconcileParams, suggestCssProperty } from "@plitzi/sdk-authoring";
-export { BUILTIN_ELEMENT_CALLBACKS$1 as BUILTIN_ELEMENT_CALLBACKS, BUILTIN_GLOBAL_CALLBACKS$1 as BUILTIN_GLOBAL_CALLBACKS, BUILTIN_UTILITIES$1 as BUILTIN_UTILITIES, applyBuiltinCallback, applyElementCallback, applyUtility, buildDataSourceCatalog, buildInteractionCatalog, buildTypeRegistry, cssProperties$1 as cssProperties, cssShorthands, elementCatalog$1 as elementCatalog, elementTypeNames, expandShorthand, expandShorthandPatch, getElementCallback, getGlobalCallback, getUtility, hiddenParams, isCssProperty, observedDataSources, observedInteractionActions, reconcileParams, suggestCssProperty };
+import { applyBuiltinCallback, applyElementCallback, applyUtility, cssProperties as cssProperties$1, cssShorthands, elementCatalog as elementCatalog$1, elementTypeNames, expandShorthand, expandShorthandPatch, getElementCallback, getGlobalCallback, getUtility, hiddenParams, isCssProperty, reconcileParams, suggestCssProperty } from "@plitzi/sdk-authoring";
+export { applyBuiltinCallback, applyElementCallback, applyUtility, buildDataSourceCatalog, buildInteractionCatalog, buildTypeRegistry, cssProperties$1 as cssProperties, cssShorthands, elementCatalog$1 as elementCatalog, elementTypeNames, expandShorthand, expandShorthandPatch, getElementCallback, getGlobalCallback, getUtility, hiddenParams, isCssProperty, observedDataSources, observedInteractionActions, reconcileParams, suggestCssProperty };

package/dist/modules/mcp/catalogs/pluginCatalog.js

@@ -10,8 +10,8 @@
 *
 * The BUILT-IN types are not here: their structural half (attributes, style selectors, default styles) comes from
 * `@plitzi/sdk-elements`, which this package deliberately does not depend on — a React element library is the
-* heaviest possible import for a server that renders nothing. Deployments merge those in themselves; the curated
-* semantics for them live in `builtinComponents.ts`.
+* heaviest possible import for a server that renders nothing. Deployments merge those in themselves; what each one is
+* for is `elementCatalog`, read off the declarations by `@plitzi/sdk-authoring`.
 */
 var MANIFEST_TTL_MS = 6e5;
 var manifestCache = /* @__PURE__ */ new Map();

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

@@ -18,7 +18,8 @@ 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;
-    /** The deployment switch a consumer sets as `mcpAi.renderStreaming`. Omitted, the server's own default stands. */
+    /** The deployment switch a consumer sets as `McpOptions.renderStreaming`. Omitted, the server's own default
+     *  stands. */
     renderStreaming?: boolean;
 }
 /** Start the endpoint and connect a real MCP client to it, as a remote connector does. */

package/dist/modules/mcp/handler.d.ts

@@ -10,9 +10,9 @@ export type McpRequestOptions = {
     preview?: PreviewClient;
     screenshot?: ScreenshotClient;
     logger?: ServerLogger;
-    /** Deployment switch for the plitzi_render view (see `mcpAi.renderStreaming`). Defaults to true. */
+    /** Deployment switch for the plitzi_render view (see `McpOptions.renderStreaming`). Defaults to true. */
     renderStreaming?: boolean;
-    /** Where a rendered widget loads everything external from (see `mcpAi.proxy`). Absent → the URLs an agent
+    /** Where a rendered widget loads everything external from (see `McpOptions.proxy`). Absent → the URLs an agent
      *  authored travel to the host exactly as written. */
     proxy?: ResourceProxy;
 };

package/dist/modules/mcp/helpers/callToolResult.d.ts

@@ -0,0 +1,2 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const isCallToolResult: (result: unknown) => result is CallToolResult;

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

@@ -0,0 +1,4 @@
+//#region src/modules/mcp/helpers/callToolResult.ts
+var isCallToolResult = (result) => typeof result === "object" && result !== null && Array.isArray(result.content);
+//#endregion
+export { isCallToolResult };

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

@@ -1,4 +1,4 @@
-import { BUILTIN_TRANSFORMERS, GLOBAL_SOURCES } from "@plitzi/sdk-authoring";
+import { BUILTIN_TRANSFORMERS, GLOBAL_SOURCES, MOTION_ENTERS, MOTION_LOOPS } from "@plitzi/sdk-authoring";
 //#region src/modules/mcp/helpers/guide.ts
 var GLOBALS = GLOBAL_SOURCES.map((source) => `\`${source}\``).join(", ");
 var OTHER_TRANSFORMERS = Object.keys(BUILTIN_TRANSFORMERS).filter((action) => action !== "twigTemplate").map((action) => `\`${action}\``).join(", ");
@@ -61,7 +61,8 @@ computed for you). Node types: \`callback\` (an element's own callback — \`ele
 (category/key/value/revertOnFinish) ≠ global \`setState\` (source \`state\`, key/type/value). To turn a step off use
 \`patchInteractionNode {enabled:false}\` — \`deleteInteraction\` removes it (destructive; confirm first). Any param
 **value** can be a binding token \`{{ source }}\` (e.g. notification \`content: "{{ list_<name>.item.name }}"\`).
-Steps read the page as it is when they run; a refiring trigger is ignored unless \`whileRunning: "queue"\`; keyboard
+Steps read the page as it is when they run; a refiring trigger is ignored unless \`whileRunning: "queue"\` (or
+\`"latest"\`: the newest firing stops the running one); keyboard
 shortcuts are the \`onKey\` trigger (\`keys: "shift+f, escape"\`).
 
 **CMS / API integrations** (\`upsertConnector\`): a **connector** is a manifest declaring a provider's base URL,
@@ -88,6 +89,12 @@ button/link needs words (an icon-only button a \`title\`), every field a \`label
 image an \`alt\` or \`decorative: true\`; clicks go on a \`button\`/\`link\`, never a container; headings step down one
 level at a time. \`plitzi_screenshot view:"accessibility"\` shows the tree and what has no name.
 
+**Everything the space holds is public.** Its pages, variables, attributes, flow params and mock data ship to every
+visitor's browser, and a file on a public bucket of its CDN is served to anyone who has its address. A key, a token or
+data only some visitors may read never goes in any of them: a secret is a credential the owner attaches (a connector, an
+action or a function names it, never carries it), and data for some visitors only comes from a \`runtime: "server"\`
+provider or an action that checks who is asking.
+
 **Touched elements must be malformation-free.** Editing an element also checks its CURRENT stored content and BLOCKS
 the save on any \`Pre-existing malformation in element …\` error (a broken transformer, a malformed step, an attribute
 it never reads) — even parts you did not touch. These are NOT from your change (the message says so); fix them in the
@@ -172,6 +179,8 @@ Never download a whole tree you do not need.
   action may be built from.
 - \`plitzi://functions/{env}\` — the space's **functions**, its own server code: which files, and the tasks, routes and
   hosts they declare. \`plitzi://functions/{env}/{+path}\` reads one file whole. See *Functions* below.
+- \`plitzi://data/{env}\` — the space's **data**: JSON files its server providers read, never served.
+  \`plitzi://data/{env}/{+path}\` reads one, parsed. See *Data* below.
 - \`plitzi://changes/{env}\` — the space's **change history**, read-only and newest first: who made each change (a
   person in the builder, an agent, the autofix), when, and every element, class, token or font it touched, whole, before
   and after. \`/{id}\` for the history of one of them — how you find what changed an element you are asked about, or
@@ -234,7 +243,8 @@ space already had is not repeated on every batch — and none of them blocks any
   page being shown: the \`current\` state marks it (see *Pages & folders*).
 - \`repeated-shape\` — one structure written again with other words: a **component** with props
   (\`upsertComponent { fromRef }\` turns one copy into it), or, for sibling rows of data, one \`repeatElement\`/\`list\`.
-  A few cards a person rewords by hand can stay cards.
+  A few cards a person rewords by hand can stay cards; siblings that read different data or keep different state are
+  controls written alike, and are not offered.
 - \`content-attribute\` — a \`button\` or \`link\` whose children are only a \`text\` and/or a \`fontAwesome\`: its words
   are its own \`content\` and the icon its \`icon\`. What the text's class adds (\`white-space: nowrap\`) moves to the
   box's class — never the class itself; the icon's class goes in the \`icon\` slot.
@@ -242,7 +252,14 @@ space already had is not repeated on every batch — and none of them blocks any
   \`states\`/\`ancestors\`, the SDK (reduced motion, the theme toggle's icons) or the space's notification look says.
 - \`heavy-animation\` — keyframes that animate a size, a position, a blur, a shadow, or a colour in a loop: they stutter
   while the page loads. Lighter, not shorter — see **Motion — good practices**.
-\`plitzi://explain/<code>\` explains each. Take one unless the copies are about to diverge.
+- \`unused-class\`, \`unused-token\`, \`unused-component\` — declared and read by nothing: remove it
+  (\`deleteDefinition\`, \`deleteStyleVariable\`, \`deleteComponent\`), or use it where it was meant to go. Said
+  when a batch leaves one behind.
+- \`literal-colour\` — a class painted from the palette typing out a token's light value: \`var(--token)\` when it
+  should follow the scheme; a token of one value when it must stay the same in both.
+\`plitzi://explain/<code>\` explains each. Take one unless the copies are about to diverge; one left on purpose is
+quieted on an element it names — \`quiet: ["repeated-shape"]\` on \`upsertElement\`/\`patchElement\` (\`null\` removes it)
+— and is not offered again, here, in the builder or in authoring. Suggestions' codes only.
 
 ## Readers: resources vs plitzi_search vs plitzi_read (do not confuse them)
 Three ways to read, each for a different moment — pick by what you have in hand:
@@ -269,7 +286,7 @@ runtime wires by it — there is no second key and nothing to translate. Creatin
 That name is the **wiring key**: a provider registers its data source as \`<type>_<name>\`, so a \`source\` you write
 against a name resolves to that element at runtime. Rules for a **new** name (both enforced; a violation fails the
 batch):
-- Charset \`[A-Za-z0-9_-]\`, **starting with a letter** (e.g. \`"products-api"\`, \`"food_item"\`). A \`.\` would split
+- Charset \`[A-Za-z0-9_-]\`, **starting with a letter** and not ending in \`-\` (e.g. \`"products-api"\`, \`"food_item"\`). A \`.\` would split
   the \`<type>_<name>.<field>\` source path and the interaction target lookup, so **no dots**. An **underscore is
   allowed**: the FIRST \`_\` separates \`<type>\` from the name and element types are camelCase with none, so
   underscores inside a name are unambiguous (\`list_food_item\` → type \`list\`, name \`food_item\`).
@@ -281,7 +298,8 @@ batch):
 **Where an element renders** is its \`runtime\`, settable on \`upsertElement\`/\`patchElement\`: \`"shared"\` (the
 default, both sides), \`"client"\` (browser only) or \`"server"\` (SSR only). It matters for one thing above all — an
 \`apiContainer\` reads through a **connector** only when it is \`"server"\` (see *Connectors*). An element read
-reports it only when it is set.
+reports it only when it is set. The page server resolves \`"server"\` elements of a page and its layouts only, never
+inside a component — one there is refused; put the provider on the page and hand the component its rows as a prop.
 
 **Renaming** (\`patchElement\` with \`rename\`) moves the one key: the parent's child list, every binding source and
 every interaction target across the space that named the old one is repointed with it, so nothing comes unwired.
@@ -412,7 +430,10 @@ provider's records into a list element:
 **What an \`apiContainer\` publishes** depends on where it reads. Through a connector (\`runtime: "server"\`) it is the
 fixed shape under *Connectors* — \`.records\` or \`.record\`, \`.pageInfo\`, … With a browser \`query\` it is the
 response: \`.data\` (the parsed body — an API answering \`{ "items": [...] }\` is read as
-\`apiContainer_<name>.data.items\`) and \`.status\` (the HTTP status). Both add \`.isLoading\`, \`.isEmpty\`,
+\`apiContainer_<name>.data.items\`) and \`.status\` (the HTTP status) — and a \`"server"\` provider with only a
+\`query\` (a JSON file the deployment serves) answers in that same shape, so moving it to the server changes no
+binding. Fed by a server **action**, it is the action's output at the root (\`apiContainer_<name>.items\`, never
+\`.data.items\`). All add \`.isLoading\` (true while asked again too), \`.isEmpty\`,
 \`.hasError\` and \`.errorMessage\`.
 
 **Source scope — a source is visible to the provider's DESCENDANTS only.** An element source named
@@ -435,7 +456,7 @@ the API needs a token or the content should be in the HTML), or a browser-side \
 \`{ action, params }\`; the runtime runs them in order and resolves each by its \`action\` alone, so an **unknown
 action is silently skipped** and the raw value passes through. Use the **exact** action names from
 \`plitzi://data-sources\` (\`transformers\`). The most common is **\`twigTemplate\`** to format a value — the incoming
-value is the **\`{{source}}\`** token (NOT \`{{value}}\`); \`{{sourceTo}}\` is the field's previous value. Example —
+value is the **\`{{source}}\`** token (NOT \`{{value}}\`) — undefined until the source has a value, so \`{{ source|default('…') }}\` covers the wait; \`{{sourceTo}}\` is the field's previous value. Example —
 show a number with units:
 \`{ "type": "upsertBinding", "pageRef": "home", "ref": "food-item-time", "category": "attributes",
   "binding": { "to": "content", "source": "list_food-list.item.cookTimeMinutes",
@@ -459,7 +480,8 @@ you — never wire them by hand. Each step also has an \`enabled\` flag (see dis
 **Each step reads the page as it is when it runs**: a \`when\` or a \`{{ state.x }}\` after a \`setState\` sees the new
 value, and one after a \`delay\` sees what changed meanwhile. To act on the value from BEFORE a write, put the reading
 step first. **A trigger fired again while its flow runs is ignored** (no double submit); set \`"whileRunning": "queue"\`
-on the trigger node for a stream of events that must each run in order (\`"parallel"\` runs them at once).
+on the trigger node for a stream of events that must each run in order (\`"parallel"\` runs them at once,
+\`"latest"\` stops the running flow — its server action or request too — for a search as you type).
 **Keyboard shortcuts** are a trigger every element has: \`onKey\` with param \`keys\` — \`"f"\`, \`"shift+f"\`,
 \`"mod+k"\` (⌘ on a Mac, Ctrl elsewhere), \`"plus, ="\`, \`"escape"\`. Heard on the whole page while the element is
 mounted, ignored while someone types in a field; the flow reads the key pressed as \`{{ <trigger id>.key }}\`.
@@ -538,6 +560,20 @@ Discover valid actions in \`plitzi://interactions/{env}\`: \`actions\` = observe
 node type and valid params per action. An element read lists its flows as ordered nodes (each with its \`id\` and
 \`enabled\`), so a follow-up patch/delete needs no extra read.
 
+## What is public — and where a secret goes
+A space is served to anyone who opens it, and everything it is made of goes with it:
+
+- **The documents.** Every page, layout and component, every schema and style variable, every attribute, binding,
+  flow param and \`mockData\` reaches the visitor's browser with the page. Hiding an element (\`visible: false\`, a
+  flag, a condition) does not remove it from what is sent.
+- **The files.** A file on one of the space's public buckets is on the internet at its address, signed in or not —
+  for pictures, fonts and data every visitor may see.
+
+So a secret — an API key, a token, a password — never goes in a document or a public file. It is a **credential**,
+created by the space owner in the builder, which a connector, an action or a function **names** and never carries.
+Data only some visitors may read comes from a \`runtime: "server"\` provider or a server action whose \`access\` checks
+who is asking — never from a public file or a document the page filters on the client.
+
 ## Connectors — CMS and API integrations
 A **connector** is how a space reads real content from Strapi, WordPress, Contentful, Directus or any REST service.
 It is **a manifest, not code**: you declare the base URL, the endpoints, the auth template and the filter operators,
@@ -647,7 +683,7 @@ returns **no records** rather than the whole collection — a URL that addressed
 **Paging** is the \`pagination\` prop: \`"none"\`, \`"url"\` (the page number rides the query string, so pages are
 shareable and indexable — prefer it) or \`"append"\` (a "load more" list). Give each list on a page its own
 \`pageParam\` so two lists page independently. The provider also offers the \`loadMore\` and \`goToPage\` callbacks to
-interaction flows, and \`performQuery\` to refetch.
+interaction flows, \`performQuery\` to refetch, and \`cancelQuery\` to drop a request in flight (a STOP).
 
 **Writing back** (a form, a "delete" button): declare the endpoint under \`endpoints.write\`, then call the provider's
 **\`writeRecord\`** callback from an interaction flow — nodeType \`callback\`, \`elementId\` the apiContainer's ref,
@@ -706,6 +742,19 @@ any other (\`<namespace>.<action>\`), listed in \`plitzi://actions/{env}/tasks\`
   The live site runs what the space was last published with, never the draft. Running functions is part of the paid
   plans: on another plan they save, and a run answers why it did not start — tell the user rather than work around it.
 
+## Data
+JSON the space's pages read on the server and never serve — a catalog, prices, a menu: what a page needs whole and
+nobody edits element by element.
+
+- **Read** it as a provider does: \`apiContainer\` with \`runtime: "server"\` and \`query: "/data/products.json"\` reads
+  \`products.json\` of \`plitzi://data/{env}\`, and the page arrives with it. A browser provider reading \`/data/…\` is
+  refused — the data is the server's.
+- **Write** it with \`upsertDataFile { path, content }\` (the whole file, as JSON text; \`deleteDataFile { path }\`
+  removes one): a path of plain segments ending in \`.json\`. Saved whole, with the batch: a newer copy (somebody saved
+  since you read it) refuses it — read it again.
+- **What a provider reads is in the page it renders**: data a page must not carry belongs in a server action, which
+  answers only what is shown. The live site reads what the space was last published with, never the draft.
+
 ## Realtime channels
 Pages that see each other — cursors, presence, a shared board, a game. Three parts, all needed:
 
@@ -926,8 +975,10 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
 ## Motion — good practices
 A preset first: an element's \`motion\` field (\`upsertElement\`/\`patchElement\`) —
 \`{ "enter": "fade-up", "on": "view" }\`, \`"stagger": 60\` for its children one by one, \`"loop": "float"\` — is
-played by the SDK, cheap and stilled for reduced motion. Enters: fade, fade-up, fade-down, slide-left, slide-right,
-scale; loops: float, pulse, spin, sway. Beyond them, keyframes go in \`customCss\` (\`patchSettings\`), a
+played by the SDK, cheap and stilled for reduced motion. \`on\`: \`load\` (default), \`view\` (once, the first time it
+comes into view, then it stays) or \`scroll\` (follows the scroll both ways — it fades back out as the reader scrolls
+up past it; only for an effect that is about the scroll itself). Enters: ${MOTION_ENTERS.join(", ")}; loops:
+${MOTION_LOOPS.join(", ")}. Beyond them, keyframes go in \`customCss\` (\`patchSettings\`), a
 definition names them (\`animation\`). Only \`opacity\` and
 \`transform\` (\`translate\`, \`scale\`, \`rotate\`) animate off the main thread: they stay smooth while the page
 hydrates and on a slow phone. Anything else repaints or lays the page out again on every frame, and freezes while the
@@ -940,7 +991,8 @@ page's scripts run.
   pulsing glow is a static gradient whose \`opacity\` or \`scale\` changes.
 - Decoration that must animate something else (a custom property, \`background-position\`) starts paused and runs
   once the page is hydrated: \`.glow { animation: glow 8s linear infinite paused; } [data-hydrated] .glow {
-  animation-play-state: running; }\` in \`customCss\`.
+  animation-play-state: running; }\` in \`customCss\`. That is for loops: an entrance of its own that plays once
+  (\`transform\`/\`opacity\` only) plays from the first paint with \`backwards\`, never gated on \`[data-hydrated]\`.
 - Entrances: \`opacity\` + a small \`translateY\`, under ~600ms, staggered by tens of ms.
 - One slow ambient loop per screen at most — not one per card: \`infinite\` runs on every visitor's battery.
 - Name what transitions (\`transition: transform 200ms, opacity 200ms\`), never \`all\`; \`will-change\` only on the
@@ -962,7 +1014,9 @@ tree names nothing is invisible to both, however it looks. So build every page t
   no agent finds them. An empty backdrop that closes a panel is the exception (the panel's close button and Escape
   are the ways everyone has).
 - **State is said, not only styled.** A toggle sets \`ariaPressed\`, a button that opens a panel \`ariaExpanded\`
-  (bind them like any attribute) — an "active" class alone is invisible to both readers.
+  (bind them like any attribute) — an "active" class alone is invisible to both readers. A button that shows and
+  hides a panel names it in \`controls\` (\`aria-controls\`, the panel's anchor), and words that change while a
+  visitor reads them — a count, a total, a status — sit in a \`container\` with \`live: "polite"\` (\`aria-live\`).
 - **A dropdown opens from a \`button\`** among its children, outside the popup (an avatar, a "⋯": the button holds it and
   has a \`title\`). The dropdown marks it and moves the focus in and out; a box or an icon alone opens nothing from a
   keyboard.

package/dist/modules/mcp/helpers/index.d.ts

@@ -1,4 +1,4 @@
-export * from './agentPrompt';
+export * from './callToolResult';
 export * from './components';
 export * from './computeVersion';
 export * from './space';

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

@@ -1,5 +1,5 @@
 import { AIElementDetail } from '../types';
-import { ActionEntry, ActionTaskDescriptor, ComponentCatalog, ConnectorEntry, Element, FunctionsDraft, PageFolder, Schema, Style } from '@plitzi/sdk-shared';
+import { ActionEntry, ActionTaskDescriptor, ComponentCatalog, ConnectorEntry, DataDraft, Element, FunctionsDraft, PageFolder, Schema, Style } from '@plitzi/sdk-shared';
 /** The working view the tools read and mutate: the two Plitzi schemas (elements + style), which the platform
  *  stores and persists as separate documents (Space model / Style model), plus the space's `connectors` — a third
  *  store (one row per connector) that a provider element points into by identifier. `catalog` is read-only
@@ -16,6 +16,9 @@ export interface Space {
     /** The space's own functions — their source files, which copy of them this is, and what they declare. Absent when
      *  the deployment offers no functions: then there is nothing to read and every function op is refused. */
     functions?: FunctionsDraft;
+    /** The space's own data — JSON its server providers read (`/data/<file>`), never served — and which copy of it this
+     *  is. Absent when the deployment offers no data: then there is nothing to read and every data op is refused. */
+    data?: DataDraft;
     catalog?: ComponentCatalog;
     /**
      * The whole document, when `schema` is a view of one tree of it — a component's, which an op addressed to a

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

@@ -6,6 +6,7 @@ var cloneSpace = (space) => ({
 	connectors: structuredClone(space.connectors),
 	actions: structuredClone(space.actions),
 	...space.functions ? { functions: structuredClone(space.functions) } : {},
+	...space.data ? { data: structuredClone(space.data) } : {},
 	...space.actionTasks ? { actionTasks: space.actionTasks } : {},
 	...space.catalog ? { catalog: space.catalog } : {}
 });

package/dist/modules/mcp/helpers/uris.d.ts

@@ -28,6 +28,8 @@ export declare const actionUri: (env: Env, ref: string) => string;
 export declare const actionTasksUri: (env: Env) => string;
 export declare const functionsUri: (env: Env) => string;
 export declare const functionFileUri: (env: Env, path: string) => string;
+export declare const dataUri: (env: Env) => string;
+export declare const dataFileUri: (env: Env, path: string) => string;
 export declare const foldersUri: (env: Env) => string;
 export declare const folderUri: (env: Env, ref: string) => string;
 export declare const defsUri: (env: Env) => string;

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

@@ -28,6 +28,8 @@ var actionUri = (env, ref) => `plitzi://actions/${env}/${ref}`;
 var actionTasksUri = (env) => `plitzi://actions/${env}/tasks`;
 var functionsUri = (env) => `plitzi://functions/${env}`;
 var functionFileUri = (env, path) => `plitzi://functions/${env}/${path}`;
+var dataUri = (env) => `plitzi://data/${env}`;
+var dataFileUri = (env, path) => `plitzi://data/${env}/${path}`;
 var foldersUri = (env) => `plitzi://folders/${env}`;
 var folderUri = (env, ref) => `plitzi://folders/${env}/${ref}`;
 var defsUri = (env) => `plitzi://definitions/${env}`;
@@ -62,4 +64,4 @@ var itemTemplates = (env) => [
 *  family and extracts its ref in one step, without repeating the prefix string for both the startsWith and slice. */
 var afterPrefix = (uri, prefix) => uri.startsWith(prefix) ? uri.slice(prefix.length) : void 0;
 //#endregion
-export { actionTasksUri, actionUri, actionsUri, afterPrefix, aliasedRoots, changesUri, componentsUri, connectorPresetsUri, connectorUri, connectorsUri, cssPropertiesUri, dataSourcesUri, defUri, defsUri, elementUri, flagsUri, folderUri, foldersUri, fontUri, fontsUri, functionFileUri, functionsUri, globalUri, globalsUri, guideUri, idUri, idsUri, interactionsUri, itemTemplates, layoutsUri, pageUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarUri, styleVarsUri, typesUri };
+export { actionTasksUri, actionUri, actionsUri, afterPrefix, aliasedRoots, changesUri, componentsUri, connectorPresetsUri, connectorUri, connectorsUri, cssPropertiesUri, dataFileUri, dataSourcesUri, dataUri, defUri, defsUri, elementUri, flagsUri, folderUri, foldersUri, fontUri, fontsUri, functionFileUri, functionsUri, globalUri, globalsUri, guideUri, idUri, idsUri, interactionsUri, itemTemplates, layoutsUri, pageUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarUri, styleVarsUri, typesUri };

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

@@ -1,7 +1,7 @@
 export { createMcpServer, handleMcp, serveMcp, readMcpBody } from './handler';
 export { readResource, resourceVersion, registerResources, buildTypeRegistry, cssProperties } from './resources';
 export { apply, validate, search, read, validateOperations, operation, tools } from './tools';
-export { computeVersion, buildAgentGuide } from './helpers';
+export { computeVersion } from './helpers';
 export { createHttpPreviewClient } from './previewClient';
 export { createLocalScreenshotClient, resolveLocalBrowser } from './localScreenshotClient';
 export { createHttpScreenshotClient } from './screenshotClient';