@plitzi/sdk-mcp 0.38.13 → 0.38.14

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @plitzi/sdk-mcp
 
+## 0.38.14
+
+### Patch Changes
+
+- 493955a: ## SDK
+
+  - **An embedded space leaves the page's theme alone** (`@plitzi/plitzi-sdk`, `@plitzi/plitzi-builder`): plitzi-ui's
+    `Provider` stamps `dark` on `<html>` by default — and, being `light`, takes it off — so every space mounted with
+    `themeScope: 'container'` turned the page around it light, and nothing put it back. The SDK and the builder now leave
+    the class to their own theme provider (`applyColorModeClass={false}`).
+  - **A space inside a space** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-shared`): one drawn inside another — the `plitziSdk`
+    element, a plugin rendering one, the builder's canvas — knows it (`render.enclosed`). It is `container` unless it
+    says otherwise, wears its theme on its own root and starts from the page's when its own is `system`, keeps its
+    stylesheet to its own root (`@scope` — its `:root` palette and `.dark` rules repainted the outer page, its
+    `.plitzi-sdk` rule restyled the outer root), writes no `<title>` (`ownsHead`) and no `theme` cookie.
+  - **The `plitziSdk` element draws** (`@plitzi/plitzi-sdk`): it rendered in `widget` mode with no page to show, so it
+    drew nothing. A widget with no `currentPageId` now shows the page its home address would. And it takes a space's
+    documents as well as a key: `offlineData`, bound whole (an `apiContainer`'s answer, a runtime's route, what
+    `plitzi_render` returns) or as `offlineData.schema` and `offlineData.style` from two elements — waiting, without an
+    error, for the half that has not answered; one that cannot be drawn is said why, in the console and on the canvas.
+  - **`<PlitziSdk>` inside a plugin draws** (`@plitzi/plitzi-sdk`): it mounted a router of its own inside the page's, and
+    React Router refused it — `routing: 'memory'` or not. A space inside another is a widget: `raw` becomes `widget`
+    there, one page and no router (a frame of its own, `iframe` or `shadow`, is left as asked).
+  - **A space inside another is as tall as what it holds** (`@plitzi/plitzi-sdk`): its root was `min-h-screen`, as a
+    space that IS the page is, so a card of three lines drawn in a panel took the window's height.
+  - **`<PlitziSdk.Plugin component>` takes a component with its own props** (`@plitzi/plitzi-sdk`), as `render()`'s
+    plugins do: typed `ComponentPluginFC`, it refused any component that read its attributes.
+  - **An edited page keeps its address in step** (`@plitzi/plitzi-sdk`): the routes are built from the pages' own
+    elements, and those were read again only when the list of pages changed — an edit to one page (its slug, its flag)
+    leaves that list the same, and the routes kept its old address until something else rebuilt them.
+  - **Packages declare only what they use** (`@plitzi/sdk-dev-tools`, `@plitzi/sdk-shared`): `@plitzi/sdk-plugins`, which
+    the dev tools no longer import, and `terser`, which no build here runs, are no longer dependencies.
+  - **An edited page keeps its route up to date** (`@plitzi/plitzi-sdk`): the routes are built from the pages' own
+    elements, which were read again only when the list of pages changed — an edit to one page (its slug, its flag) left
+    the list the same and the route at the old address. They follow every edit to a page now, and stay the same object
+    while no page changes.
+  - **`@plitzi/sdk-dev-tools` no longer depends on `@plitzi/sdk-plugins`**, which nothing in it imports.
+  - **A dropdown's menu opens inside a card that lifts or clips** (`@plitzi/sdk-elements`, `@plitzi/sdk-shared`): drawn
+    inside the dropdown, an ancestor with a `transform` — a card lifting on hover — made itself the containing block of
+    the menu's `position: fixed`, and one with `overflow: hidden` cut it off: the menu opened and nobody saw it. The open
+    menu and its backdrop are drawn at the space's root (`spaceRootOf`, `@plitzi/sdk-shared/helpers/spaceRoot`); a
+    style written for the popup by an ancestor's selector no longer reaches it — its own classes do.
+  - **A copy button says when it could not copy** (`@plitzi/sdk-elements`, `@plitzi/sdk-shared`,
+    `@plitzi/sdk-interactions`, `@plitzi/sdk-variables`, `@plitzi/sdk-dev-tools`): a page not served over https has no
+    clipboard — a phone opening a development server by its address — and a code block's "Copy" threw there. It reads
+    "Not copied", and says why. `clipboardWriter` and `copyText` (`@plitzi/sdk-shared/helpers/clipboard`) are the one
+    check, the `copyToClipboard` step's too.
+
+  ## Authoring
+  - **`plitziSdk` is authored like any element** (`@plitzi/sdk-authoring`, `@plitzi/sdk-elements`): its declaration moved
+    to `@plitzi/sdk-elements` beside the others, so it has a factory — `plitziSdk({ id, bind: { offlineData: 'view.data'
+} })` —, its attributes typed, and `plitzi explain` knows it.
+  - **A binding may write part of an attribute** (`@plitzi/sdk-authoring`): `offlineData.schema` writes into
+    `offlineData`, as the runtime always did; authoring refused it as an attribute nothing reads.
+  - **`choosesChildren`** (`@plitzi/sdk-shared`, `@plitzi/sdk-authoring`): a plugin that shows only some of the elements
+    put inside it — a dashboard's panels, a wizard's step — says so in its declaration, and the page checks owe none of
+    them on screen; what it draws is still read by the checks of the whole page (images, sideways scroll, legibility).
+    `verify` was red on every such page.
+
+  - **A page says how the document scrolls** (`@plitzi/sdk-elements`, `@plitzi/sdk-authoring`, `@plitzi/sdk-mcp`):
+    `documentScroll: 'locked'` holds the document still while the page is open — a dashboard or a board used with a
+    finger, where the whole page was dragged and bounced back though nothing in it scrolls — and `'noBounce'` keeps the
+    scroll without the rubber band or pull-to-refresh. The page draws the rule itself, so it is in the server's HTML and
+    leaves with the page; never inside a widget, a space drawn in another, or the builder's canvas. A Settings select,
+    `PageSpec.documentScroll`, `upsertPage`'s `documentScroll` (`null` undoes it) and the page read; an unknown value is
+    refused (`attribute-value`). `upsertPage` is now held to the lint of the page it writes, as element writes are.
+
+  ## MCP
+  - **`@plitzi/sdk-mcp/render`** (`@plitzi/sdk-mcp`): `plitzi_render`'s widget render on its own — no MCP server, no SSR,
+    no OAuth — for a project whose own agent draws in its own pages: `render`, `renderWidgetShape` to declare it as a
+    tool, `renderGuideText` for the agent. `base`, the style of the project's space, brings its tokens, classes and fonts
+    to the widget.
+
+  ## Server
+  - **`publicUrl` says where people reach the server** (`@plitzi/sdk-server`): it was `http://127.0.0.1:<port>` whatever
+    the server was. It is `https` once `serverOptions.tls` gives it a certificate, and this machine's network address
+    with `HOST` open to the network (what a tablet opens, what an OAuth provider sends it back to); `PUBLIC_URL` still
+    wins. The network addresses it prints say `https` too.
+  - **A server serving TLS reaches itself** (`@plitzi/sdk-server`): with a local certificate (mkcert) Node trusts nothing
+    the browsers were told to, so a runtime calling its own MCP failed. Its requests to its own address now connect to its
+    listener and are taken when it presents exactly its certificate (`reachOwnServer`, exported from `/runtime`).
+  - **A runtime reads compressed answers again** (`@plitzi/sdk-server`): the dispatcher `reachOwnServer` (and the
+    platform's `reachSpaceInside`) installs reached every other host with an undici connector that offers HTTP/2, and an
+    answer that came back over h2 reached Node's `fetch` without its `content-encoding` — every API that compresses read
+    as Brotli bytes. Other hosts are reached over HTTP/1.1 now, as Node's own `fetch` reaches them.
+  - **A project's server serves HTTPS from `.env`** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): `TLS_CERT` and
+    `TLS_KEY`, the certificate's and the key's paths — what `plitzi cert` writes — with no code of the project's;
+    `serverOptions.tls` still wins. A network address the certificate does not name is said at boot, the machine's
+    `.local` name is printed among the addresses when it is named, and a server on loopback alone says how to open it to
+    the network.
+  - **A session survives a phone on the Wi-Fi** (`@plitzi/sdk-server`): a private network address (`192.168.…`, `10.…`,
+    Tailscale's `100.64/10`, IPv6 unique- and link-local) and a machine's mDNS name (`studio.local`) get the local
+    cookie profile — `SameSite=Lax`, no `Secure`, no `Domain`. They got `SameSite=None; Secure`, which a browser drops
+    over http: nobody could sign in from a tablet. A deployment's own `.local` sub-domains (`app.example.local`) keep the
+    strict profile.
+  - **Hiding the dev tools on a server over HTTPS hydrates** (`@plitzi/sdk-server`): a server with a certificate speaks
+    HTTP/2, which sends no `Host` — only `:authority` — and the cookies named for the origin's port (the dev tools'
+    `plitzi_debug_<port>`, forced flags, painted state) were looked for without it. Shift+F12 hid the dev tools in the
+    browser, the server rendered them back, and the page failed to hydrate. Every one is read off `requestAuthority`.
+  - **A rebuild of plugins says it finished** (`@plitzi/sdk-server`): bundles removed under a running server (`tmp/`
+    deleted) were each a warning, "rebuilding…", and their "ready" at a level a project's terminal does not show. It is
+    one episode now: said when noticed, and again when the last is built — how many, how long, which failed.
+  - **`tmp/dev-server.json` records the scheme** (`@plitzi/sdk-server`): `url` is `https` with a certificate, and the
+    file adds the network addresses and the `publicUrl`.
+  - **`public/` is asked about every time** (`@plitzi/sdk-server`): it was cached for an hour — a `.js` or `.css` in it
+    for a year, `immutable` — so a file a project rewrites while it runs arrived stale. It is `no-cache` now, answered
+    `304` by its `ETag` while unchanged; `immutable` stays for what is versioned (the SDK, the plugins).
+
+  ## CLI
+  - **`check`, `shot`, `verify` and `visual` find a server on HTTPS** (`@plitzi/cli`): they rebuilt
+    `http://127.0.0.1:<port>`, so a project serving a certificate had no page checked. They read the URL `npm start`
+    recorded, and take a local certificate on this machine only. A project's `playwright.config.ts` comes from
+    `plitzi upgrade`.
+  - **`verify` runs the project's tests** (`@plitzi/cli`): a step `test`, after the lint, when `package.json` has a
+    `test` script.
+  - **`tsconfig.json` is the project's** (`@plitzi/cli`): the compiler options moved to `plitzi/tsconfig.base.json`, which
+    the CLI keeps up and `tsconfig.json` extends — so a folder of the project's own (`scripts/`, `tools/`) goes in its
+    `include` without changing a file of the CLI's. `plitzi doctor --fix` makes an older `tsconfig.json` extend it,
+    keeping only the options the project changed.
+  - **`doctor --fix` and `upgrade` write as the project's Prettier does** (`@plitzi/cli`): a repaired `tsconfig.json` or
+    `package.json` left `verify`'s format step red.
+  - **`upgrade` renames `usePlitziServiceContext`** (`@plitzi/cli`): with `PlitziServiceProvider` and
+    `PlitziServiceContextValue`, renamed in 0.38.12 with no alias — import, use and the module path that named it.
+  - **`skills update` compares every file** (`@plitzi/cli`): only `SKILL.md` was, so a change in a reference alone was
+    "up to date".
+  - **`NOTES.md`, the project's notes for agents** (`@plitzi/cli`): `AGENTS.md` and `CLAUDE.md` are the CLI's and
+    `upgrade` replaces them, so what a project's own sessions had to know had nowhere to live. `CLAUDE.md` imports
+    `NOTES.md`, `AGENTS.md` sends every agent to it, and nothing the CLI does touches it; `doctor --fix` writes one for
+    a project that has none.
+
+  - **`start:dev-inspect`** (`@plitzi/cli`): a server project's `start:dev` with Node's inspector open on
+    127.0.0.1:9229, so a debugger (VS Code, `chrome://inspect`) attaches to the server, and again after each restart.
+    `plitzi upgrade` adds it; `plitzi runtime add` has it restart on the runtime too.
+  - **`plitzi cert`** (`@plitzi/cli`): HTTPS while developing, for a phone or a tablet on the Wi-Fi — over http its
+    browser gives a page no microphone, camera or clipboard. A certificate from mkcert's local authority for this machine,
+    its network addresses and its `.local` name, in `tmp/tls/`, named in `.env`; what to install on the phone, said.
+  - **A browser project opens to the network** (`@plitzi/cli`): its `vite.config.ts` reads `HOST`, `TLS_CERT` and
+    `TLS_KEY` from `.env`, as a server project does, and writes `tmp/dev-server.json` — the port Vite took and the scheme
+    — so `page check`, `page shot` and `visual` find it on another port or over HTTPS. `plitzi upgrade` brings it.
+
+  ## Docs
+  - **Two plugins share through `state`** (`@plitzi/sdk-authoring` skill): each plugin is a bundle of its own, so a module
+    both import is two copies, and what one keeps there the other never sees.
+  - **`verify --help`** names the project's tests among its steps.
+
+- Updated dependencies [493955a]
+  - @plitzi/plitzi-sdk@0.38.14
+  - @plitzi/sdk-server@0.38.14
+  - @plitzi/sdk-authoring@0.38.14
+  - @plitzi/sdk-schema@0.38.14
+  - @plitzi/sdk-shared@0.38.14
+  - @plitzi/sdk-style@0.38.14
+
 ## 0.38.13
 
 ### Patch Changes

package/README.md

@@ -133,6 +133,24 @@ hand-build a URI — every write and search response hands back the URI to use n
 The tool functions are exported directly (`apply`, `search`, `read`, `validate`, `tools`), so a consumer can run
 them in-process instead of speaking MCP over HTTP.
 
+### A project's own agent drawing widgets
+
+`plitzi_render` hands its widget to a host that draws `ui://` resources — claude.ai, Desktop. An agent working for a
+project (a voice assistant, a terminal session) draws in the project's own page instead, so the render comes apart:
+
+```ts
+import { render, renderGuideText, renderWidgetShape } from '@plitzi/sdk-mcp/render';
+
+// A tool of the project's own MCP server, its input `renderWidgetShape`, its guide `renderGuideText`.
+const answer = render({ operations }, { base: space.style }); // the project's authored space
+if (answer.rendered) {
+  publish(answer.offlineData); // what a `plitziSdk` element is bound to (`offlineData`)
+}
+```
+
+`base` is the style of the space that shows the widget: its tokens in both themes, its classes and its fonts come
+with it, so the widget looks like the page around it. Left out, the widget starts from nothing, as one in a chat does.
+
 ## Draft preview
 
 The two halves live in different packages, joined by a one-shot token:
@@ -204,6 +222,7 @@ MCP server, [self-hosting/07](../../examples/self-hosting/07-ssr-preview) is the
 |---|---|
 | `@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` and the tool engine. |
+| `@plitzi/sdk-mcp/render` | `plitzi_render`'s widget render alone — no MCP server, no SSR, no OAuth — for a project's own agent. |
 
 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/modules/mcp/helpers/guide.js

@@ -977,6 +977,10 @@ Pages can be grouped into **folders** (the sidebar tree). A folder is \`{ ref, n
   a page read reports its current \`enabled\`). Disabling only affects the **published SDK runtime** — the page stops
   being routable/accessible to end users. It stays fully **editable here**: you can still read it and apply any op to
   a disabled page. This does not delete it — \`deletePage\` does.
+- **A page that fills the window** (a dashboard, a board) takes \`upsertPage\`'s \`documentScroll: "locked"\`: the
+  document holds still and only parts with \`overflow: auto\` scroll, so a finger on a tablet no longer drags and
+  bounces the page. \`"noBounce"\` keeps the scroll without the rubber band; \`null\` undoes either. Never an
+  \`html, body\` rule in \`customCss\`: that holds every page, and the site the space is a widget on.
 
 ## Settings
 Space-level configuration lives in \`plitzi://settings/{env}\` and is edited with a single **\`patchSettings\`** op

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

@@ -3,6 +3,8 @@ import { ResourceEnvelope } from '../types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
 export declare const RENDER_TYPES_URI = "plitzi://render/types";
+/** How a widget is authored: what an agent reads before its first render, whichever server hands it the tool. */
+export declare const renderGuideText: string;
 /** 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. */

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

@@ -34,6 +34,7 @@ var renderTypes = () => {
 		types
 	};
 };
+/** How a widget is authored: what an agent reads before its first render, whichever server hands it the tool. */
 var renderGuideText = `# plitzi_render — authoring guide
 
 \`plitzi_render\` shows the user a live UI widget. You build it as a list of \`operations\` (applied IN ORDER) that
@@ -504,4 +505,4 @@ var registerRenderResources = (server, log) => {
 	});
 };
 //#endregion
-export { RENDER_GUIDE_URI, RENDER_TYPES_URI, readRenderResource, registerRenderResources };
+export { RENDER_GUIDE_URI, RENDER_TYPES_URI, readRenderResource, registerRenderResources, renderGuideText };

package/dist/modules/mcp/server.js

@@ -72,7 +72,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.13"
+		version: "0.38.14"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);

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

@@ -82,6 +82,10 @@ export declare const applyShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            locked: "locked";
+            noBounce: "noBounce";
+        }>>>;
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;

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

@@ -78,6 +78,10 @@ export declare const documentOperation: z.ZodDiscriminatedUnion<readonly [z.ZodO
     layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        locked: "locked";
+        noBounce: "noBounce";
+    }>>>;
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"deletePage">;
@@ -1496,6 +1500,10 @@ export declare const operation: z.ZodDiscriminatedUnion<[z.ZodObject<{
     layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        locked: "locked";
+        noBounce: "noBounce";
+    }>>>;
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"deletePage">;
@@ -3193,6 +3201,10 @@ export declare const operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject
     layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        locked: "locked";
+        noBounce: "noBounce";
+    }>>>;
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"deletePage">;
@@ -4885,6 +4897,10 @@ export declare const documentOperations: z.ZodArray<z.ZodDiscriminatedUnion<read
     layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        locked: "locked";
+        noBounce: "noBounce";
+    }>>>;
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"deletePage">;

package/dist/modules/mcp/tools/operations/schema/operations.d.ts

@@ -81,6 +81,10 @@ export declare const elementOps: {
         layout: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         layoutContainer: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         enabled: import('zod').ZodOptional<import('zod').ZodBoolean>;
+        documentScroll: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodEnum<{
+            locked: "locked";
+            noBounce: "noBounce";
+        }>>>;
         flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
     }, import('zod/v4/core').$strip>;
     deletePage: import('zod').ZodObject<{

package/dist/modules/mcp/tools/operations/schema/pages/upsertPage.d.ts

@@ -11,6 +11,10 @@ export declare const upsertPageOp: z.ZodObject<{
     layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        locked: "locked";
+        noBounce: "noBounce";
+    }>>>;
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type UpsertPage = z.infer<typeof upsertPageOp>;

package/dist/modules/mcp/tools/operations/schema/pages/upsertPage.js

@@ -3,7 +3,7 @@ import { layoutsUri, pageUri, pagesUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
 import { elementFlag } from "../shared.js";
 import { guardNewRef } from "../write.js";
-import { flagGateOf } from "@plitzi/sdk-authoring";
+import { DOCUMENT_SCROLLS, flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schema/pages/upsertPage.ts
 var upsertPageOp = z.object({
@@ -16,6 +16,7 @@ var upsertPageOp = z.object({
 	layout: z.string().nullable().optional().describe("Ref of the layout shell this page renders inside; \"\" or null detaches it. See plitzi://schema/{env}/layouts."),
 	layoutContainer: z.string().nullable().optional().describe("Ref of the container INSIDE that shell where this page body goes — the slot. Must belong to it."),
 	enabled: z.boolean().optional().describe("false disables the page in the published SDK runtime (not routable/accessible to end users); it stays editable here. Defaults to true"),
+	documentScroll: z.enum(DOCUMENT_SCROLLS).nullable().optional().describe("\"locked\": the document never moves, only overflow:auto panels scroll; \"noBounce\": no rubber band"),
 	flag: elementFlag.nullable().optional()
 }).describe("Create a page, or update it when ref already exists (only the fields you pass change).");
 var upsertPage = (space, env, op) => {
@@ -66,6 +67,8 @@ var upsertPage = (space, env, op) => {
 			...layoutValue !== void 0 ? { layout: layoutValue } : {},
 			...slotValue !== void 0 ? { layoutContainer: slotValue } : {}
 		};
+		if (op.documentScroll === null) Reflect.deleteProperty(existing.attributes, "documentScroll");
+		else if (op.documentScroll !== void 0) existing.attributes.documentScroll = op.documentScroll;
 		if (op.flag === null) Reflect.deleteProperty(existing.definition, "flag");
 		else if (op.flag !== void 0) existing.definition.flag = flagGateOf(op.flag, `Page "${op.ref}"`);
 		return {
@@ -90,7 +93,8 @@ var upsertPage = (space, env, op) => {
 			enabled: op.enabled ?? true,
 			folder: folderValue ?? "",
 			layout: layoutValue ?? "",
-			layoutContainer: slotValue ?? ""
+			layoutContainer: slotValue ?? "",
+			...op.documentScroll ? { documentScroll: op.documentScroll } : {}
 		},
 		definition: {
 			rootId: id,

package/dist/modules/mcp/tools/operations/schema/translator.js

@@ -3,7 +3,7 @@ import { descendantCount, elementById, getLayoutElements, getPageElements, nameO
 import { bindingsToAI, flowsFromInteractions } from "../../../helpers/interactions.js";
 import { definitionToAI, globalStylesForType, idStyleToAI } from "../style/translator.js";
 import { descendants } from "@plitzi/sdk-schema/helpers/elementTree";
-import { flagSpecOf, splitNotificationsCss } from "@plitzi/sdk-authoring";
+import { flagSpecOf, isDocumentScroll, splitNotificationsCss } from "@plitzi/sdk-authoring";
 //#region src/modules/mcp/tools/operations/schema/translator.ts
 var splitClasses = (value) => value ? value.split(/\s+/).filter(Boolean) : [];
 var propsOf = (el) => {
@@ -84,6 +84,7 @@ var pageSkeletonToAI = (schema, pageEl, style) => {
 		slug,
 		default: pageEl.attributes.default === true,
 		enabled: pageEl.attributes.enabled !== false,
+		...isDocumentScroll(pageEl.attributes.documentScroll) ? { documentScroll: pageEl.attributes.documentScroll } : {},
 		routeParams: slugRouteParams(slug),
 		tree: orderedChildren(schema, pageEl).map((child) => skeletonNode(schema, child, style))
 	};

package/dist/modules/mcp/tools/render.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { ResourceProxy } from '../proxy';
-import { Operation } from './operations';
-import { OfflineDataRaw } from '@plitzi/sdk-shared';
+import { RenderWidgetInput } from './renderWidget';
 export declare const renderShape: {
+    patch: z.ZodOptional<z.ZodBoolean>;
+    renderId: z.ZodOptional<z.ZodString>;
     operations: z.ZodArray<z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
         type: z.ZodLiteral<"upsertElement">;
         pageRef: z.ZodString;
@@ -80,6 +80,10 @@ export declare const renderShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        documentScroll: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            locked: "locked";
+            noBounce: "noBounce";
+        }>>>;
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
@@ -1421,40 +1425,9 @@ export declare const renderShape: {
         type: z.ZodLiteral<"deleteFont">;
         family: z.ZodString;
     }, z.core.$strict>], "type">>;
-    patch: z.ZodOptional<z.ZodBoolean>;
-    renderId: z.ZodOptional<z.ZodString>;
 };
-export type RenderInput = {
-    operations: Operation[];
+export type RenderInput = RenderWidgetInput & {
     patch?: boolean;
     renderId?: string;
 };
-/** What the render needs from its host beyond the operations. Optional: a host that wires no resource endpoint
- *  still renders a widget — one whose external URLs travel as authored and load only where the surface allows
- *  their origin. */
-export type RenderOptions = {
-    proxy?: ResourceProxy;
-};
-export type RenderResponse = {
-    rendered: false;
-    errors: {
-        path: string;
-        message: string;
-        hint?: string;
-    }[];
-    warnings?: string[];
-} | {
-    rendered: true;
-    rootRef: string;
-    elementCount: number;
-    offlineData: OfflineDataRaw;
-    /** The batch this render was built from, EXPANDED (repeats already unrolled). The view keeps it so a later
-     *  patch has something to merge into; it is never shown to the model. */
-    operations: Operation[];
-    /** One line per interaction flow the widget actually stored — what got wired to what. Absent when the
-     *  widget has no flows, which is most of them. */
-    interactions?: string[];
-    warnings?: string[];
-};
-export declare const render: (input: RenderInput, options?: RenderOptions) => RenderResponse;
 export declare const renderTool: import('.').ToolDef;

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

@@ -1,68 +1,16 @@
 import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
-import { emptySpace } from "../helpers/space.js";
-import { proxifyResources } from "../proxy/rewrite.js";
-import { compactDocumentOperations, documentOperations } from "./operations/index.js";
-import { draftBatch } from "./shared/draftBatch.js";
+import { compactDocumentOperations } from "./operations/index.js";
 import { defineTool } from "./shared/tool.js";
-import { interactionReport } from "./shared/interactionReport.js";
+import { render, renderWidgetShape } from "./renderWidget.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { generateCache } from "@plitzi/sdk-style/StyleHelper";
 //#region src/modules/mcp/tools/render.ts
-var HOST_PAGE_REF = "render";
-var seedSpace = () => {
-	const space = emptySpace();
-	space.schema.definition.name = "Widget";
-	space.schema.flat[HOST_PAGE_REF] = {
-		id: HOST_PAGE_REF,
-		attributes: {
-			slug: "",
-			name: "Render",
-			default: true
-		},
-		definition: {
-			rootId: HOST_PAGE_REF,
-			label: "Page",
-			type: "page",
-			items: [],
-			styleSelectors: { base: "" }
-		}
-	};
-	space.schema.pages = [HOST_PAGE_REF];
-	return space;
-};
-var noWarnings = (warnings) => warnings.length > 0 ? warnings : void 0;
 var renderShape = {
-	operations: documentOperations,
+	...renderWidgetShape,
 	patch: z.boolean().optional().describe("Set true to CHANGE a widget you already rendered instead of rebuilding it: send its `renderId` and ONLY the operations that differ (patchDefinition, patchElement, deleteElement, a new repeatElement…). The widget merges them into the batch it was built from and reports back what it applied. The refs it already has (card-1, blk-2-3) are the ones to address. If that widget cannot be recovered — a surface that renders none, a host that keeps no storage — the answer says so and you re-send the whole batch."),
 	renderId: z.string().optional().describe("Handle returned by a previous render. Required with patch:true; it names the widget being changed.")
 };
-var render = (input, options = {}) => {
-	const result = draftBatch(seedSpace(), "main", input.operations, "widget");
-	if (!result.ok) return {
-		rendered: false,
-		errors: result.errors,
-		warnings: noWarnings(result.warnings)
-	};
-	const { ops, draft: space } = result;
-	const behaviour = interactionReport(space);
-	const warnings = [...result.warnings, ...behaviour.warnings];
-	if (options.proxy) warnings.push(...proxifyResources(space, options.proxy));
-	space.style.cache = generateCache(space.style);
-	return {
-		rendered: true,
-		operations: ops,
-		...behaviour.flows ? { interactions: behaviour.flows } : {},
-		rootRef: HOST_PAGE_REF,
-		elementCount: Object.keys(space.schema.flat).length - 1,
-		offlineData: {
-			schema: space.schema,
-			style: space.style
-		},
-		warnings: noWarnings(warnings)
-	};
-};
 /** A patch is not rendered here — it CANNOT be: this server keeps nothing between calls (no session, no store,
 *  any replica answers any request), so the previous widget only exists on the host side. The delta therefore
 *  travels as a courier result: the model pays for the delta alone, the view recovers the batch that widget was
@@ -156,4 +104,4 @@ var renderTool = defineTool({
 	run: (input, ctx) => input.patch === true ? toPatchResult(input.operations, input.renderId) : toRenderResult(render(input, { proxy: ctx.proxy }), input.renderId ?? newRenderId())
 });
 //#endregion
-export { render, renderShape, renderTool };
+export { renderShape, renderTool };