@plitzi/sdk-mcp 0.38.7 → 0.38.8

package/CHANGELOG.md

@@ -1,5 +1,197 @@
 # @plitzi/sdk-mcp
 
+## 0.38.8
+
+### Patch Changes
+
+- 1b45aae: ## The CLI's commands are named after what they act on
+
+  Every command sits under the thing it acts on — `plitzi element move`, never a bare `move` that could mean anything —
+  and only what acts on the project as a whole or the account stays at the top:
+
+  | Before                                       | Now                                                                |
+  | -------------------------------------------- | ------------------------------------------------------------------ |
+  | `where`, `edit`, `remove`, `move`            | `element where`, `element edit`, `element remove`, `element move`  |
+  | `check`, `shot`, `import`                    | `page check`, `page shot`, `page import`                           |
+  | `space`, `pull`, `push`, `lint`, `fix`       | `space use`, `space pull`, `space push`, `space lint`, `space fix` |
+  | `add plugin`, `pack plugin`, `upload plugin` | `plugin add`, `plugin pack`, `plugin upload`                       |
+  | `add runtime`                                | `runtime add`                                                      |
+  | `pack source`                                | `source pack`                                                      |
+  | `update` (alias of `upgrade`)                | `upgrade`                                                          |
+
+  `create`, `verify`, `doctor`, `upgrade`, `explain`, `feedback`, `login`, `logout` and `whoami` stay at the top, beside
+  `functions`, `runtime`, `data` and `skills`. There are no aliases: a name asked for at the top that is a group's command
+  answers where it is — `There is no plitzi push: it is one of plitzi space push, plitzi runtime push, plitzi functions
+push` — read off the commands themselves. A project's scripts (`lint:space`, `check`, `shot`) call the new names;
+  `plitzi upgrade --write` updates the ones the CLI wrote.
+
+  ## Agents load less to do the same (RFC 0025)
+  - **The MCP lists the operations vocabulary once.** A connection with a space listed ~69k tokens of tools before an
+    agent did anything — the operations schema five times. `plitzi_apply` carries it; `plitzi_render` lists only its
+    operations' types beside it (and keeps the whole schema on a guest connection, where it is alone). The listing is
+    now ~18k tokens.
+  - **`plitzi_validate` is `plitzi_apply`'s `dryRun`**, which already answered the same; the `validate` function, its
+    `validateShape` and `ValidateInput` are gone from `@plitzi/sdk-mcp`.
+  - **`plitzi_apply` looks at the page it would leave**: `look: 'html' | 'image' | 'accessibility' | 'both'` (with
+    `pageRef`, `viewport`, `fullPage`) renders it — with `dryRun`, as the batch would leave it, nothing saved; without, as
+    saved. Check, look and save with the operations written twice, not four times.
+  - **`plitzi_look` is the one way to see a saved page** — its accessibility outline (the default: text, cheap), its HTML
+    or a PNG; `plitzi_preview` and `plitzi_screenshot` are gone. It is always offered: without a browser service it answers
+    the HTML and says so.
+  - **`plitzi_describe_operation { type }`** answers one operation's schema, or every type there is; a type that does not
+    exist is answered with the nearest one.
+  - `closest` is exported from `@plitzi/sdk-authoring`: the nearest of a closed list of names.
+  - **`plitzi element where <id | class | words>`** answers where the project's code writes an element — the file, the line and
+    the call itself — asked of the code as it is now, so it follows an element wherever somebody moved it. A class is
+    found by its name or by the variable that holds it (`nav-link`, `navLink`).
+  - **`plitzi element edit <id> --set key=value --remove key`** writes attributes in that call (`content` where the factory takes
+    it first), keeping each one's kind, formatted as the project formats, and keeps the change only if the space still
+    authors with every value there. Behind both, `locateElements` in `@plitzi/sdk-authoring`: every element with the call
+    that wrote it.
+  - A generated project's `AGENTS.md` says to ask `where` instead of keeping a note of where things are.
+  - **`plitzi doctor` says one fact once**: packages installed from the same place, and packages behind the same version,
+    are one line each — on a project installed from local tarballs, ~1,050 tokens of output became ~330.
+  - **A mistake costs one line.** An operation type that does not exist is answered with the nearest one; a field an
+    operation, an element, a binding or a flow step does not have is refused naming the one meant — it used to be dropped,
+    and `prop` for `props` answered success having applied nothing. An element type spelt with other capitals
+    (`Heading`) is read as the catalog spells it and said in `warnings`.
+  - **The same batch refused twice is not run a third time** (`REPEATED_BATCH`), and the second refusal says so; `plitzi
+edit` does the same, kept in the project's `tmp/refusals.json`.
+  - **`plitzi_apply`'s `look` renders a batch through the path a save takes** (`draftBatch`): a
+    `repeatElement` expanded, what has one reading read, the same refusals.
+  - **Each skill is a core an agent reads every time, and references it opens when the task names one.** The core —
+    what it is for, the rules that go wrong most, a table routing each task to its one file — is held to 1,500 tokens:
+    `plitzi-authoring` went from ~4,000 to ~920 (every rule kept in `reference/rules.md`, the recipes indexed in
+    `reference/recipes.md`, every reference in `reference/index.md`), `plitzi-cli` from ~4,000 to ~820 (projects,
+    plugins and troubleshooting are references of their own), `plitzi-render` from ~3,100 to ~1,050.
+  - **Intent tools on the MCP**: `plitzi_set_attributes`, `plitzi_set_classes` (classes added or removed, the rest
+    kept), `plitzi_bind_attribute`, `plitzi_place_component`, `plitzi_add_page` — a few parameters, the element by its ref alone (the
+    page is found, a ref that does not exist answered with the nearest), checked and saved as `plitzi_apply` saves, and
+    answered in a line with the next step.
+  - **An element may only wear a class the space has, or the batch declares**: `plitzi_apply` used to save one nothing
+    defines — rendered unstyled, said by nobody. It is refused naming the nearest class.
+  - **`plitzi explain` answers any export of `@plitzi/sdk-authoring`** — `pageFamily`, `styles`, `SpaceSpec` — with its
+    signature and the first paragraph of its doc, read from the `.d.ts` the project installed: a few dozen tokens where an
+    agent used to search ~180k of published types.
+  - **`plitzi element where --by id|class|text`** reads a query one way; without it, the first reading that matches is answered
+    and every other one that matched is said with its count and the command for it — a query that means two things is
+    never answered as one. `plitzi element edit` reads its element by id alone.
+  - **A helper written once and called for many elements** is told apart: `locateElements` answers each element's
+    `through` — the calls of the author's code that led to the one that wrote it — so `plitzi element where` says which other
+    elements the same call writes and the call that leads to this one alone, and `plitzi element edit` changes a value the helper
+    is handed where it is handed (`pageHead('about-head', 'About us')`), refuses an edit of a call that writes several
+    elements unless `--every` says so, and never writes `content` beside words given as the factory's first argument.
+  - `plitzi explain` of a name that is the project's own says where to read it.
+  - **Nothing a write does is silent.** `plitzi_apply` answers `effects`: every change the batch made, read off the space
+    before and after it (elements added or removed by subtree, attributes, classes, moves, styles, settings, connectors,
+    actions), with a note where a changed attribute is one a binding computes; a batch that changed nothing says so, and
+    a store with no persister leads the warnings as `NOT saved: …`. The intent tools answer those `effects`, whether it
+    was `saved` and what was already so, refuse to take off a class the element does not wear and to write a value under
+    a binding. `plitzi element edit` reads the whole space before and after the edit (`plitzi element readings`, in a fresh process),
+    prints every change, and puts the files back when anything changed that was not asked, naming it; it refuses an
+    attribute a binding computes, and `plitzi element where` marks those `Bound`. `canonicalJson` (`@plitzi/sdk-shared`) is
+    what every before-and-after comparison is made with. Authoring keeps deep enough a call stack (64 frames) that a
+    helper inside a helper is still told apart.
+  - `locateElements` answers the parts of every component too, in the component (`rootId` is its id): `plitzi element where`
+    and `plitzi element edit` reach an element inside a component as they reach one on a page or a layout.
+
+  ## Fixed
+  - **A layout no longer mounts twice when the page hydrates.** An element with `runtime: 'server'` was wrapped in its
+    static shell while hydrating and handed back without it — under another key — on the next render, so React tore
+    down everything under it and built it again. With a server provider around a layout (an `apiContainer` that draws
+    no markup of its own), the whole layout's DOM was replaced on every page, and every `motion` arrival in it played
+    twice: a visible flicker on load. The shell now stays around the element on both sides of hydration, under the same
+    key, and only stops freezing (`frozen`).
+  - **A component's instance is written somewhere.** `component(…)` — and each child it places in a slot — rebuilt its
+    spec with a spread and lost the marker of where the author wrote it: `plitzi element where` could not place an instance and
+    `plitzi element edit` refused it. The original marker is carried (`carryWrittenAt`); `where` finds the words an instance
+    hands its component, and `edit` writes an instance's props.
+  - `plitzi element edit` follows a value read off a list the call is repeated for (`item.question` in
+    `QUESTIONS.flatMap(item => …)`) to the one entry that holds it, in the file the list is written in; when the shared
+    value is not a literal it says where it comes from instead of offering `--every`.
+  - **`plitzi page check --element` says which class wins.** Each property more than one of the element's classes sets, at
+    rest: the value shown, the class it comes from and what the others say — or that they all set it so. Which wins is
+    asked of the page, each class taken off for a moment; a style change is verified in text, not with a picture.
+  - **`plitzi element where` reads more.** By words it finds every word an element says (`words` on `WrittenElement`: content,
+    `label`, `title`, `alt`, `placeholder`, binding templates, an instance's props); by class it says where the class
+    is declared (`locateClasses` in `@plitzi/sdk-authoring`); an element repeated over a list says which list, and its
+    file; a page or a layout is placed at the object it is declared as.
+  - **`plitzi element edit` edits a page** by the attributes `where` shows (`seoPageTitle` written as `seoTitle`;
+    `PAGE_SPEC_FIELDS` in `@plitzi/sdk-authoring`), refusing `layout` and `seoEnabled`, which are no field of their own;
+    and a value read in more than one place (a list entry a nav and a menu both draw) changes them all only with
+    `--every`, each named.
+  - **A component prop of a type that does not exist is refused** (`prop-type-unknown`, with the types there are):
+    `type: 'string'` was accepted at run time, offered by no editor and checked against nothing. `BUILTIN_PARAM_TYPES`
+    in `@plitzi/sdk-shared` is the list, and `BuiltinParamType` is derived from it.
+  - **`plitzi element remove <id>` and `plitzi element move <id> --before|--after <id>`** take an element out of the code that writes
+    it, or reorder it among its siblings — following a section a helper returns to the helper's call — checked as
+    `edit` is: a removal may take only the element and what it holds, a move only reorder its parent, or the file goes
+    back. Styles and imports only the removed call used go with it, named; a helper left unread is said.
+  - **`plitzi verify`** runs the project's checks — author (no warning), lint:space, typecheck, lint, format — and every
+    page with no parameter, and prints only what fails; a page it could not open is said as not checked. Generated
+    projects get `npm run verify`, and their `AGENTS.md` names it as the way to leave the project passing.
+  - **A component's refusal says where it is written** (by its root's call).
+  - **`check --element`** says a class changes nothing on the element only when every property it sets stays without
+    it, and names the other elements the class is on: changing the class changes them; taking it off this element does
+    not.
+  - **An element's generated selector and binding ids are named after its id**, under its parent's place, not after its
+    position among its siblings: a move renames nothing. Every space written in code gets new generated names once —
+    the same rules, so nothing a visitor sees changes.
+  - A change of an element's children is said as what came, went or moved (`faq moved — now after hero, before pricing`).
+  - **`plitzi page check --click <id>`** clicks one element and says what changed — flows run and how each step ended, the
+    page it went to, what scrolled, what is shown now and what no longer is, the state — or that nothing did, in those words; a flow that
+    succeeded while nothing on the page changed is said as that. A click that could not be made, or a flow that failed,
+    fails the check.
+  - **A refusal of the authored space's gate says where**: each of the validator's errors (`UNRESOLVED_INTERACTION_TARGET`,
+    `UNRESOLVED_BINDING_SOURCE`, …) carries the file and line of the element it is about, and a name nothing answers to is
+    offered the nearest element that answers the step it was for (`openModal('search')` → `search-modal`, not the
+    `search-q` field), or the few that do. `SchemaValidationError` gains `missing` and `wantedBy` (`@plitzi/sdk-schema`).
+  - **`plitzi element where` finds the words a list's rows show** when the list is handed them as data (`items:
+[...PLANS]`), and says the list they are the entries of and its file (`Its rows are the entries of PLANS
+(src/space/enterprise/content.ts)`).
+  - `plitzi page check --click` says what is **shown** now and what no longer is (drawn, wherever the page is scrolled),
+    not "on screen".
+  - `plitzi upgrade` says packages installed locally in one line past three, and a skill rewritten within the same
+    version as that, not `0.38.7 → 0.38.7`.
+  - **What `element edit`, `remove` and `move` read back goes through the gate `npm run author` does**: a change that
+    leaves the space refused — a flow still opening a modal that was removed — is put back, the refusal said with where.
+    `element remove` refuses before writing when another element's flows act on what it takes away, and says what it
+    took once, by the outermost element (`search-modal removed, with 18 inside`). Moving an element beside itself is
+    refused as nothing to do.
+  - **An id, a plugin folder or a data file written a letter off is offered the nearest one** (`element where`, `edit`,
+    `remove`, `move`, `plugin pack`, `data describe`).
+  - **A project file that does not load is said at its file and line** — `src/space/hero.ts:139: Expected ','` — by the
+    server, `npm run author` and every CLI command, never as a stack (`ProjectModuleError` and `moduleProblem` in
+    `@plitzi/sdk-authoring/node`).
+  - **`plitzi verify` stops at the first failure** — one broken file fails every later step the same way — and says the
+    rest as not run (`--keep-going` runs them anyway); `--no-pages` no longer fails a run that passed.
+  - **`plitzi space fix` no longer drops attributes written one level too deep**: `attributes: { value: 5 }` where
+    `value: 5` was meant is put in its place (a new `unwrap` fix), not removed with what it said.
+  - **`plitzi explain <type>` explains the project's own elements** (`src/plugins/`), and `plugin add` prints how to place
+    one with the attributes it was declared with.
+  - **`plitzi data describe` says an object keyed by data once**, as a map of one shape with how many keys, so a file of
+    five hundred articles reads as one.
+  - **`plitzi page check` says a path no page answers before opening it**, with the paths the pages do answer — never a
+    redirect home read as a page for signed-in visitors.
+  - **`copyToClipboard(text)`**, a utility step (`@plitzi/sdk-interactions`, built with `copyToClipboard` in
+    `@plitzi/sdk-authoring`): a "Copy link" button had no step to write with. A browser that gives the page no clipboard
+    fails the step, so a toast after it is never said of a copy that was not made.
+  - **`plitzi explain` lists the values a param takes only when it is a choice** (`select`): `setState`'s `value` read
+    as `'true' | 'false'`, the examples of a free value taken for its only ones.
+  - **`plitzi page check --click` says what the page said** — a toast or an alert, `said: "Link copied"` — and **a form
+    the browser held back**, with the field and the browser's reason, never as a click that changed nothing.
+  - **`plitzi page check --click <id> --fill <id>=<value>`** fills fields before the click as a visitor does (typed, an
+    option chosen, a box ticked), so a form's success flow is checked, not only its refusal when empty. A container of
+    several fields is refused with their ids; a field filled inside another element says whose it is.
+
+- Updated dependencies [1b45aae]
+  - @plitzi/sdk-authoring@0.38.8
+  - @plitzi/sdk-schema@0.38.8
+  - @plitzi/sdk-shared@0.38.8
+  - @plitzi/plitzi-sdk@0.38.8
+  - @plitzi/sdk-server@0.38.8
+  - @plitzi/sdk-style@0.38.8
+
 ## 0.38.7
 
 ### Patch Changes

package/README.md

@@ -69,7 +69,7 @@ The server is stateless: it resolves the space per request and reads and writes
 | `getGrant(req)` | yes | The space this request operates on **and whether the caller may change it** (`{ spaceId, scope, userId?, canWrite }`), decoded from the verified `Authorization` bearer. You own the JWT secret and the authorization model, so both are decided on your side. Return `undefined` for a missing or invalid token. |
 | `getSchema(spaceId, env)` | yes | The element schema the tools read and mutate. |
 | `getStyle(spaceId, env)` | yes | The full style document, including `platform`/`mode`. |
-| `saveSchema(spaceId, env, schema)` | for writes | Persist a mutated schema. Without it, `plitzi_apply` reports `persisted: false`. |
+| `saveSchema(spaceId, env, schema)` | for writes | Persist a mutated schema. Without it, `plitzi_apply` reports `persisted: false` and leads its warnings with what was NOT saved. |
 | `saveStyle(spaceId, env, style)` | for writes | Persist a mutated style document. |
 | `getChanges(spaceId, env, query)` | no | The space's change history, for the `plitzi://changes` resources. Writes arrive with an `SSRWriteContext` (`userId`, one `batch` per tool call) so a consumer can record them. |
 | `getOfflineData(spaceId, env, rev)` | for preview | Read side of draft-preview. Only the preview endpoint calls it. |
@@ -103,8 +103,8 @@ types its renderer with.
 | `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. |
+| `previewClient` | off | `{ url, secret? }`: the SSR `/preview` endpoint, for an MCP server that runs apart from the renderer. Without it `plitzi_look` and `plitzi_apply`'s `look` report `PREVIEW_UNAVAILABLE`. |
+| `screenshot` | off | `{ serviceUrl, renderBaseUrl }`: the browser service a look renders an image or an accessibility outline through, and the SSR base it navigates to. Without it a look answers the HTML, and says so. |
 | `oauth` | off | OAuth 2.1 for remote connectors — see [OAuth](#oauth). |
 
 ```ts
@@ -117,10 +117,10 @@ createServer({ adapters }, { screenshot: { serviceUrl, renderBaseUrl }, proxy: {
 |---|---|---|
 | `plitzi_search` | read | Find elements, pages, styles and bindings; returns ready-made URIs |
 | `plitzi_read` | read | Read one or more resources in detail by URI |
-| `plitzi_validate` | read | Dry-run a batch of operations: what would fail, what is warned, and suggestions for a shorter way to the same page |
-| `plitzi_apply` | write | Apply a batch of operations and persist; answers with the batch's suggestions too |
-| `plitzi_preview` | read | Render a draft to HTML through an SSR server |
-| `plitzi_screenshot` | read | Render a draft to a PNG (desktop, mobile or both) through the screenshot service |
+| `plitzi_apply` | write | Apply a batch of operations and persist; answers with its `effects` — every change it made, read off the space before and after — and its suggestions. `dryRun` checks it without saving, and `look` renders the page as the batch leaves it (HTML, a PNG or the accessibility outline) |
+| `plitzi_set_attributes`, `plitzi_set_classes`, `plitzi_bind_attribute`, `plitzi_place_component`, `plitzi_add_page` | write | One change by its intention — an element's attributes, classes added or removed, a binding, a component placed, a page — by the element's ref alone, saved as `plitzi_apply` saves it, answered with its `effects`, whether it was `saved`, and what was already so |
+| `plitzi_describe_operation` | read | One operation's schema by its type, or the list of every type |
+| `plitzi_look` | read | See a saved page: its accessibility outline (default), its HTML, or a PNG (desktop, mobile or both) |
 | `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 |
 
@@ -164,8 +164,8 @@ This package ships an [Agent Skill](https://agentskills.io/) for `plitzi_render`
 a widget instead of writing prose, the shape of a good call, the layout and theme traps that make a widget look
 wrong in a chat panel, and how to iterate on one it already rendered.
 
-It lives in [`skills/plitzi-render`](./skills/plitzi-render/SKILL.md) as a plain `SKILL.md`, so it installs by
-copying that folder into your agent's skills directory (Claude Code, VS Code / Copilot, Codex, Gemini CLI, Cline,
+It lives in [`skills/plitzi-render`](./skills/plitzi-render/SKILL.md): a short `SKILL.md` an agent reads every time,
+and a `reference/` it opens when the task names one. It installs by copying that folder into your agent's skills directory (Claude Code, VS Code / Copilot, Codex, Gemini CLI, Cline,
 Goose…):
 
 ```bash

package/dist/index.d.ts

@@ -11,9 +11,9 @@ export { previewStage } from './stages/preview';
 export { createWidgetProxyStage } from './stages/proxy';
 export { createPreview } from './preview/createPreview';
 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 { apply, search, read, applyShape, searchShape, readShape, 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';
+export type { ApplyInput, SearchInput, SearchResponse, SearchHit, ReadInput, ReadResponse, ReadHit, WriteResponse, WriteElement, Persisters, Operation, ToolDef, ToolContext } from './modules/mcp/tools';
 export type { Space } from './modules/mcp/helpers';
 export type { Env } from './modules/mcp/types';
 export type { McpOptions, McpProxyOptions } from './options';

package/dist/index.js

@@ -1,9 +1,8 @@
 import { operation } from "./modules/mcp/tools/operations/index.js";
+import { outlineOfSnapshot, outlineOfTree, unnamedControls } from "./modules/mcp/accessibilityOutline.js";
 import { apply, applyShape } from "./modules/mcp/tools/apply/index.js";
 import { read, readShape } from "./modules/mcp/tools/read.js";
-import { outlineOfSnapshot, outlineOfTree, unnamedControls } from "./modules/mcp/accessibilityOutline.js";
 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 { createMcpServer } from "./modules/mcp/server.js";
 import { handleMcp, readMcpBody, serveMcp } from "./modules/mcp/handler.js";
@@ -17,4 +16,4 @@ import { buildMCPPipeline, mcpExtensions } from "./pipeline.js";
 import { createServer } from "./createServer.js";
 import { createLocalScreenshotClient, resolveLocalBrowser } from "./modules/mcp/localScreenshotClient.js";
 import { createOAuthGuardStage, createOAuthStage } from "@plitzi/sdk-server/oauth";
-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 };
+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 };

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

@@ -2,7 +2,7 @@ import { BUILTIN_TRANSFORMERS, GLOBAL_SOURCES, MOTION_ENTERS, MOTION_LOOPS } fro
 //#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(", ");
-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 a quickstart of 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. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<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 elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". 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). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_screenshot view:\"accessibility\" to check. 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 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 a quickstart of 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. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<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 elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". 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). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_look (its accessibility outline, the default view) to check. 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).
@@ -51,8 +51,8 @@ a QueryBuilder RuleGroup gating the binding.
 as \`icon\` (\`iconPlacement\` before/after, its class on the \`icon\` slot) — never a \`text\` or \`fontAwesome\` child;
 a text child also ignores the box's colour and hover. Chrome on several pages is a **layout**; the nav item of the page being shown is marked by the
 \`current\` state of its class, not by a copy of the header per page. Sibling rows of data are one \`repeatElement\`; a
-block repeated with other words is a **component** (\`upsertComponent { fromRef }\`). \`plitzi_validate\` and
-\`plitzi_apply\` answer with **\`suggestions\`** for what the batch could have written shorter, each with the elements
+block repeated with other words is a **component** (\`upsertComponent { fromRef }\`). \`plitzi_apply\` (with or
+without \`dryRun\`) answers with **\`suggestions\`** for what the batch could have written shorter, each with the elements
 it saves — never blocking; take them unless the copies are about to diverge.
 
 **Interactions** (\`upsertInteractionFlow\`): a \`trigger\` node first, then callbacks/utilities **in order** (links
@@ -87,7 +87,7 @@ element or page — not \`visible\`. Read anywhere as \`{{ flags.x }}\`.
 **Accessible by default:** screen readers and browser agents (Claude in Chrome) read the accessibility tree, so every
 button/link needs words (an icon-only button a \`title\`), every field a \`label\` (\`hideLabel: true\` hides it), every
 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.
+level at a time. \`plitzi_look\` 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
@@ -217,25 +217,40 @@ stateVersion) and returns any **style definitions** whose name matches the query
 When you do hold several refs to open (e.g. from a skeleton), read them together with \`plitzi_read\` rather than one at a time.
 
 ## Tools
-- \`plitzi_validate\` — check a batch, returns teachable errors/warnings. Writes nothing. Also reports **pre-existing
-  malformations** in any resource the batch touches (see below), and \`suggestions\` (see *Suggestions*).
-- \`plitzi_apply\` — validate → apply → persist atomically. Rejects the whole batch on any error or conflict. Pass
-  \`dryRun: true\` to apply in memory only and get the same result back (changed versions + full element detail)
-  without persisting — inspect it, then re-run without \`dryRun\` to commit. Its answer carries \`suggestions\` too.
+- \`plitzi_apply\` — validate → apply → persist atomically. Rejects the whole batch on any error or conflict, and
+  reports **pre-existing malformations** in any resource the batch touches (see below) and \`suggestions\` (see
+  *Suggestions*). Pass \`dryRun: true\` to check and apply in memory only — the same answer, nothing persisted — and
+  \`look\` (\`"html"\`, \`"image"\`, \`"accessibility"\` or \`"both"\`, with \`pageRef\` and \`viewport\`) to see the page
+  as the batch leaves it in the same call. Check and look with \`dryRun\`, then send the same operations without it.
+  \`effects\` is what the batch did, read off the space before and after it — every element, attribute, class and
+  setting it changed, one line each: read it, not your batch, for what is now so. \`Nothing changed\` and \`NOT saved\`
+  lead the warnings when they are so.
+- **By intention**, a few parameters and the element named by its ref alone — the page is found, the operations
+  written, the batch checked and saved as \`plitzi_apply\` saves it, and the answer its \`effects\`, whether it was
+  \`saved\`, and what was already so:
+  \`plitzi_set_attributes { ref, set, unset }\`, \`plitzi_set_classes { ref, add, remove }\` (the classes it wears and
+  you do not name stay), \`plitzi_bind_attribute { ref, to, source }\`, \`plitzi_place_component { component, ref, into,
+  props }\`, \`plitzi_add_page { ref, slug, layout }\`. One of them when it says the whole change; anything else is one
+  batch of \`plitzi_apply\`.
+- \`plitzi_describe_operation\` — one operation's schema by its \`type\` (every field, which are required); without a
+  type, every operation type there is. Ask for the one you are writing instead of guessing a field: a field an
+  operation does not have is refused naming the one meant (\`"prop" (did you mean "props"?)\`), and a type spelt with
+  other capitals is read as the catalog spells it and said in \`warnings\`. The same batch refused twice is not run a
+  third time (\`REPEATED_BATCH\`) — change what the errors name, or ask the person.
 - \`plitzi_search\` — find elements (and pages/definitions) across the space.
 - \`plitzi_read\` — read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the
   ready-made uris from search / a write response; each result is \`{ uri, stateVersion, data }\` or a teachable error,
   so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.
-- \`plitzi_preview\` — render a page to HTML, optionally with unsaved \`operations\` applied, to check structure.
-- \`plitzi_screenshot\` — render a page to a PNG (desktop, mobile or \`both\`), optionally with unsaved \`operations\`:
-  the way to SEE overflow, misalignment and broken layout before you commit. \`view: "accessibility"\` reads the same
-  page as a screen reader and a browser agent (Claude in Chrome) do — its accessibility tree as an outline of roles and
-  names, with every control and picture that has no name listed in \`unnamed\` — as text, far cheaper than an image
-  (\`"both"\` returns both). Both need the SSR render service; where it is missing they answer \`PREVIEW_UNAVAILABLE\`.
+- \`plitzi_look { pageRef, view, viewport }\` — see a saved page. \`view\`: \`"accessibility"\` (default) reads it as a
+  screen reader and a browser agent (Claude in Chrome) do — an outline of roles and names, every control and picture
+  with no name listed in \`unnamed\`, as text and far cheaper than an image; \`"html"\` its markup; \`"image"\` a PNG,
+  the way to SEE overflow and misalignment (desktop, mobile or \`both\`); \`"both"\` image and outline. A change not
+  saved yet is seen with \`plitzi_apply\`'s \`dryRun\` and \`look\`, the same views. It needs the SSR render service
+  (\`PREVIEW_UNAVAILABLE\` without it); without a browser, an image or an outline falls back to the HTML, said.
 - \`plitzi_render\` — a different job: show the user a self-contained widget built offline. It never touches the space.
 
 ## Suggestions — the same page with fewer elements
-\`plitzi_validate\` and \`plitzi_apply\` answer with \`suggestions\`: lines like \`[content-attribute] … (saves 4
+\`plitzi_apply\` (with or without \`dryRun\`) answers with \`suggestions\`: lines like \`[content-attribute] … (saves 4
 elements)\`, each naming a shorter way to what the batch just wrote. Only what THIS batch opened up is said — what the
 space already had is not repeated on every batch — and none of them blocks anything: the page renders as written.
 - \`repeated-on-pages\` — the same block at the edge of several pages: put it in a **layout** once (a block only some
@@ -457,7 +472,7 @@ that apiContainer; inside a \`list\`, the repeated \`listItem\` and its children
 (\`list_<name>.item.<field>\`). The global sources — ${GLOBALS} — have no \`<type>_<name>\` head and are
 bindable anywhere. Binding an element to an element source outside its
 provider's subtree is schema-valid but **broken at runtime** (the source is not in scope), so
-\`plitzi_validate\`/\`plitzi_apply\` treat it as an **error and reject the batch** — move the element under the
+\`plitzi_apply\` treats it as an **error and rejects the batch** — move the element under the
 provider, or bind a source that is in scope.
 
 **mockData is builder-only.** An \`apiContainer\`'s \`mockData\` prop feeds sample data **while editing in the
@@ -537,7 +552,8 @@ mounted, ignored while someone types in a field; the flow reads the key pressed
   nothing outside the element needs to know it is open; pick the state one when something else binds to it.
 - \`utility\` — a built-in utility action (no element/source module); nodeType \`utility\`. Use the **exact** param
   names: \`delayTime\` waits \`time\` milliseconds (**not** \`delay\`), \`twigTemplate\` (\`returnMode\`, \`template\`),
-  \`webHook\` (\`url\`, \`method\`, …). See \`utilities\` in \`plitzi://interactions/{env}\`.
+  \`webHook\` (\`url\`, \`method\`, …), \`copyToClipboard\` (\`text\`). See \`utilities\` in
+  \`plitzi://interactions/{env}\`.
 
 **A param value can be a data binding.** Any interaction param may hold a \`{{ source }}\` token instead of a literal —
 it resolves at runtime exactly like a prop binding, using the same source grammar (\`<type>_<name>.<path>\`, or a
@@ -901,14 +917,14 @@ the component reads \`{{ props.item.name }}\`.
     "children": [ { "ref": "lamp-buy", "type": "button", "props": { "content": "Buy", "slot": "product-card-actions" } } ] } }
 \`\`\`
 A required prop left out, a prop the component does not declare, a value of the wrong kind or a child naming a slot
-the component does not have is reported by \`plitzi_validate\` — fix it before applying.
+the component does not have is reported by \`plitzi_apply\`'s \`dryRun\` — fix it before applying.
 
 ## Pages & folders
 - **A page behind a feature flag**: \`upsertPage { flag: "labs" }\` answers 404 while the flag is off (see **Feature
   flags**); \`flag: null\` removes it.
 - **Always set a \`slug\` when creating a page** (\`upsertPage\`) — it is the page's URL path and good practice for a
   clean, stable route (e.g. \`"pricing"\` or \`"posts/:postId"\`). Omit it and the page ref is used as the slug,
-  and \`plitzi_validate\`/\`plitzi_apply\` warn so you remember to set a meaningful one.
+  and \`plitzi_apply\` warns so you remember to set a meaningful one.
 - **A page slug is RELATIVE — do NOT start it with \`/\`.** The runtime prepends the leading slash (and any folder
   path) itself, so a leading slash doubles it. Write \`"pricing"\`, not \`"/pricing"\`. (upsertPage strips a leading
   slash for you, but write it relative.)
@@ -1057,7 +1073,7 @@ tree names nothing is invisible to both, however it looks. So build every page t
 The linter warns about these (\`control-without-name\`, \`image-without-alt\`, \`click-on-static-element\`,
 \`dropdown-without-control\`, \`heading-level-skipped\`, \`label-ignored\`, \`control-in-decorative\`) on every element
 you touch; fix them in the same batch. Then look:
-\`plitzi_screenshot\` with \`view: "accessibility"\` shows the page as those readers get it, and lists what has no name.
+\`plitzi_look\` shows the page as those readers get it, and lists what has no name.
 
 ## Semantics
 - **props are fully replaced** on \`upsertElement\`: send every prop you want to keep. To change only some props,

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

@@ -1,6 +1,6 @@
 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 { apply, search, read, validateOperations, operation, tools } from './tools';
 export { computeVersion } from './helpers';
 export { createHttpPreviewClient } from './previewClient';
 export { createLocalScreenshotClient, resolveLocalBrowser } from './localScreenshotClient';
@@ -12,6 +12,6 @@ export type { LocalScreenshotClientConfig } from './localScreenshotClient';
 export type { HttpScreenshotClientConfig } from './screenshotClient';
 export type { AccessibilityNode, UnnamedControl } from './accessibilityOutline';
 export type { McpServerContext } from './server';
-export type { ApplyInput, WriteResponse, Persisters, SearchInput, ReadInput, ReadResponse, ValidateInput, Operation, ToolDef, ToolContext } from './tools';
+export type { ApplyInput, WriteResponse, Persisters, SearchInput, ReadInput, ReadResponse, Operation, ToolDef, ToolContext } from './tools';
 export type { Space } from './helpers';
 export type * from './types';

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

@@ -11,11 +11,11 @@ import { SSRAdapters, ServerLogger, SSRGrant } from '@plitzi/sdk-shared';
 export interface McpServerContext {
     adapters: SSRAdapters;
     getGrant: () => Promise<SSRGrant | undefined>;
-    /** How the visual-preview tools (plitzi_preview / plitzi_screenshot) reach the renderer. Absent → those tools
-     *  report PREVIEW_UNAVAILABLE, so an MCP-only deployment without a renderer still runs every other tool. */
+    /** How a look (plitzi_look, plitzi_apply's `look`) reaches the renderer. Absent → it reports PREVIEW_UNAVAILABLE, so an
+     *  MCP-only deployment without a renderer still runs every other tool. */
     preview?: PreviewClient;
-    /** The dedicated browser service for plitzi_screenshot. Absent → the tool is not registered (only the HTML
-     *  plitzi_preview is offered). */
+    /** The dedicated browser service a look takes an image or an accessibility outline with. Absent → a look answers
+     *  the HTML, and says so. */
     screenshot?: ScreenshotClient;
     /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */

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.7"
+		version: "0.38.8"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);
@@ -103,10 +103,15 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 		if (hasSpace) return async (args) => tool.execute(args, await toolContext(tool.name));
 		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
 	};
-	for (const tool of tools) {
-		if (tool.requires === "screenshot" && !screenshot) continue;
+	const listed = tools.flatMap((tool) => {
 		const behavior = behaviorOf(tool);
-		if (!behavior) continue;
+		return behavior ? [{
+			tool,
+			behavior
+		}] : [];
+	});
+	const operationsCarried = listed.some(({ tool }) => tool.carriesOperations);
+	for (const { tool, behavior } of listed) {
 		const run = async (args) => {
 			const start = performance.now();
 			try {
@@ -129,7 +134,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 		const config = {
 			title: tool.title,
 			description: tool.description,
-			inputSchema: tool.inputShape,
+			inputSchema: operationsCarried && tool.compactInputShape ? tool.compactInputShape : tool.inputShape,
 			annotations: { readOnlyHint: tool.access === "read" }
 		};
 		if (tool.ui) {

package/dist/modules/mcp/tests/cheapMistakes.test.d.ts

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

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

@@ -1,6 +1,6 @@
 import { Space } from '../helpers';
 import { Operation } from '../tools';
-import { Persisters } from '../types';
+import { Persisters, ValidationResult } from '../types';
 declare const buildSpace: () => Space;
 declare const capturing: (space: Space) => {
     persisters: Persisters;
@@ -10,4 +10,11 @@ declare const spaceWithRoute: () => Space;
 declare const varOp: (pageRef: string, type: string, value: string) => Operation;
 declare const scopeSpace: () => Space;
 declare const malformedSpace: () => Space;
-export { buildSpace, capturing, spaceWithRoute, varOp, scopeSpace, malformedSpace };
+/**
+ * What `plitzi_apply`'s dryRun answers of a batch, as one result to assert on: the same `draftBatch` it runs before
+ * anything is saved, so a refusal here is the one an agent meets.
+ */
+declare const checkBatch: (input: {
+    operations: Operation[];
+}, space: Space) => ValidationResult;
+export { buildSpace, capturing, checkBatch, spaceWithRoute, varOp, scopeSpace, malformedSpace };

package/dist/modules/mcp/tests/intents.test.d.ts

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

package/dist/modules/mcp/tests/look.test.d.ts

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