@plitzi/sdk-mcp 0.38.3 → 0.38.4

package/CHANGELOG.md

@@ -1,5 +1,208 @@
 # @plitzi/sdk-mcp
 
+## 0.38.4
+
+### Patch Changes
+
+- 6ae4161: ## `plitzi push`: a self-hosted project back on its space
+
+  `plitzi create --from` and `plitzi pull` took a space out as a project and kept it in step; nothing put the project's
+  own changes back but a command per part, and no command at all for its pages. `plitzi push` is the way back
+  (`docs/en/projects-from-spaces.md`):
+
+  - **What changed, or what is named.** `plitzi push` sends what changed since the project last had the space — at a
+    terminal, offered as a ticked list to choose from (`↑/↓`, space, Enter); `plitzi push space functions` sends only
+    those parts: `space`, `functions`, `runtime`, `plugins`.
+  - **In order:** each changed plugin packed and uploaded (`pack plugin` + `upload plugin`, `--cdn`/`--bucket`), the
+    functions, the runtime, then the space — `src/space.ts` authored, the actions `src/actions.ts` serves and the manifests
+    in `src/connectors/` — as the space's draft. Never a published environment.
+  - **Never over the builder's work unseen.** The export now carries which state the draft is in (`SpaceExport.draft`),
+    recorded in `.plitzi/space.json` by `create --from` and `pull`; a push names it, and a draft edited since is refused
+    until `--force`. A project that never had the space may take one nobody has worked on; one holding work takes
+    `--force`.
+  - **Then `pull` follows it.** `.plitzi/space.json` records what was sent — only that, so a builder's change to a part
+    not pushed is still the next pull's — and a project that started on its own works with `pull` from then on.
+  - `@plitzi/sdk-shared/source`: `SpaceImport` / `SpaceImportResult` (`SPACE_IMPORT_FORMAT`), the push's one shape for
+    both ends, beside `SpaceExport`, which gains `draft`.
+  - `functions push`, `runtime push` and `upload plugin` keep their behaviour; their cores are what `push` runs.
+
+  ## A project's folders: `tmp/` for what it writes, `.plitzi/` committed, `public/` said to be public
+  - **`tmp/` is what a project writes for itself.** `@plitzi/sdk-server` keeps the plugins it builds in `tmp/.sdk-plugins`
+    and resized pictures in `tmp/images` by default (were `.sdk-plugins` and `.plitzi/images`). A project the CLI writes
+    puts the port it took (`tmp/dev-server.json`), the space as last authored while developing (`tmp/space.json`) and
+    Playwright's output (`tmp/visual`) there too, and its `.gitignore` ignores `tmp` — one line for all of it.
+  - **`.plitzi/` is committed.** The scaffold ignored it whole, so a clone lost `space.json`, `functions.json` and
+    `scaffold.json` — what `pull`, `push`, `functions push` and `upgrade` stand on. Now it holds only what the CLI records.
+    `npx plitzi upgrade --write` brings an existing project's `.gitignore` up.
+  - **No `space/offline-data.json`.** `npm run author` checks the space and writes nothing; the server asks it for the
+    documents with `--out tmp/space.json` while developing. The space is `src/space.ts`, and nothing beside it says
+    otherwise.
+  - **`public/` is on the internet.** The generated `README.md` and `AGENTS.md`, the CLI and authoring skills, the MCP
+    guide, `@plitzi/sdk-server`'s README and the docs now say so where data goes: never a secret, a key or data only
+    some visitors may read — in `public/`, or in a space's documents, which reach every visitor too.
+
+  ## An agent leaves the project clean
+
+  `AGENTS.md` gains **Keep the project clean** — nothing unused left behind, scratch work in `tmp/`, one of everything,
+  files a reader can find, and `author`, `typecheck`, `lint`, `format` and `check` passing — and the authoring skill's
+  review checklist a **Nothing left behind** section.
+
+  ## The dev tools' X-ray is the outlines too
+
+  The QA tab had **Outlines** (every element's box, its type and id when pointed at) and **X-ray** (the same boxes,
+  fainter, with what is wired to each). They are one tool now: the X-ray draws every box with its type and id, and marks
+  the wiring picked — all of it, one kind, or **Boxes only**.
+
+  ## A new space that says where to go
+
+  The space a new account and `plitzi create` start from keeps its welcome, and gains the three ways to change it — the
+  builder, code (with the command to run) and an agent — before the guides, which are shorter. Header, navigation, main
+  and footer are landmarks; the grid behind the top fades out instead of ending at an edge; the footer's line spans the
+  content; the links say their words and icon themselves, with no suggestion left.
+
+  ## Server data reads the same everywhere
+  - **One shape for a provider with a `query`.** A `runtime: 'server'` provider that only reads a JSON file the server
+    serves answered the body itself, while the same provider in the browser publishes `{ status, data }` — so moving it
+    to the server broke every binding. `publicFileResolver` and the builder's mock now answer `{ status, data }` too:
+    `<source>.data.<field>` whichever runtime.
+  - **Server data is on unless a space turns it off.** The page render read a missing `rsc` as on and the connector
+    resolver as off, so a server provider in a space the builder or the MCP made (neither writes `rsc`) resolved to
+    nothing, silently. Both read it as on now; only `rsc: { enabled: false }` turns it off (and is warned with a server
+    element). `authorSpace` writes `enabled: true` for a space that has one.
+  - **Never inside a component.** The page server resolves a page's tree and its layouts only, so a server provider in a
+    component rendered nothing, silently. Refused now (`server-provider-in-component`), with the fix: the provider on
+    the page, the rows handed in as a prop.
+  - **Bindings held to the data.** `authorSpace` takes `data` — what a provider's `query` answers — and
+    `publicData(folder)` (`@plitzi/sdk-authoring/node`) reads it from `public/`. A binding onto a path the file does not
+    have is warned (`path-not-in-data`) with the keys it does have. Generated projects pass it.
+  - **`plitzi check` reads the data too.** A binding that reads a path its provider's answer lacks, a provider that
+    failed (once, not as every element it left empty) and the rows each list rendered (`dataIssues`). `--ssr` names what
+    the server's HTML lacks that the hydrated page has. The dev tools' badge and panel (`data-plitzi-devtools`) are hidden
+    while `check` and `shot` look.
+
+  ## Authoring, clearer where agents tripped
+  - **`controls` on a button** (`aria-controls`): named by the element's id; authoring gives that element the anchor and
+    refuses an id the space lacks (`controls-unknown`); a saved document naming no anchor is warned
+    (`controls-no-anchor`). The accordion recipe uses it.
+  - **`live` on a container** (`aria-live`, `polite` or `assertive`) for words that change while a visitor reads them.
+  - **`subType: 'p'`** for a paragraph made of parts; `span-holds-block` covers it.
+  - **`formControl` types `search`, `url` and `tel`.**
+  - **Images:** no `src` draws the SDK's own placeholder (the CDN one answered 404); `resize: false` keeps a picture as
+    written; an SVG is never resized — `/_plitzi/img` redirects to it (`307`) instead of refusing it.
+  - **Messages:** an id taken by another page or layout names it and the id to write; a hyphenated source in a template
+    (`list_study-plans`) is explained as valid; an unknown CSS property says to write it in `customCss`; an unknown
+    variant on `custom` says it is never a prop of the component it hosts.
+  - **`plitzi explain` knows the helpers** — `bindTemplate`, `visibleWhen`, `variantFrom`, `activeOn`, `activeWhen`,
+    `when`, `named`, `scope`, `source`, `twig` — and `motion`, from the presets the SDK plays (`MOTION_ENTERS`,
+    `MOTION_TRIGGERS`, `MOTION_LOOPS`, now exported). `--list helpers` lists them.
+  - **`plitzi shot`** writes to `tmp/shots/` by default, and a full page shows the arrivals tied to the scroll as they
+    end. `inspectPage` no longer reports an image a hidden ancestor hides.
+  - **Style inspector:** `container-type` in Size.
+  - **New recipes:** `server-data.ts`, `accordion.ts`.
+
+  ## Matching a page to another, measured
+  - **A whole page is the whole page.** The SDK scrolls a pane of its own, so `shot`'s full-page picture was one
+    screen; the pane is unrolled now (`unrollPage`) — the viewport untouched, so a `100vh` hero stays one screen.
+  - **`plitzi shot --compare` says why, not only how much.** Every lazy picture on both pages is loaded before they are
+    taken (`loadImages`), so a section no longer swings between 23 % and 40 % on how many covers had arrived. Each section
+    is compared where it is on the other page (`alignPictures` over row profiles): a page 400 px longer is said once, with
+    the section the drift starts at, instead of a footer with the same styles reading 100 %. And the texts both pages
+    have are paired (`pageTexts`, `compareTexts`), each with what it does differently there —
+    `h1 "Learn CSS" — font-size 68px → 60px · y +19px` — position less the drift of its section. `comparePictures` takes
+    its options as an object now (`{ regions, tolerance, align }`).
+  - **`--scheme` is the space's theme.** A space whose default is dark painted dark under `--scheme light`, and the file
+    said light. `check` and `shot` now set the `theme` cookie a visitor's toggle writes; left out, the space's default is
+    pictured and the file is named by the theme actually painted.
+
+  ## `motion: { on: 'view' }` arrives once
+
+  `view` was tied to the scroll both ways: cards faded out again as the reader scrolled back up. Now it plays once, the
+  first time the element comes into view, with its `duration`, and stays — `revealOnView` (`@plitzi/sdk-shared/schema/
+motionReveal`), one observer under the SDK's root, marks it `data-motion-seen`. The scroll-driven arrival is
+  `on: 'scroll'`. A page read without scripts shows them as they end (`@media (scripting: none)`); the builder's previews
+  and the MCP's local screenshots hold motion at its end. The builder's Motion tab has the three.
+
+  The builder's preview plays motion as the published page does. It held everything at its end, and nothing marked
+  the canvas `data-hydrated`, so neither the loops nor a space's own `[data-hydrated]` animations ever started there.
+  Now an arrival plays as it comes into view, and the loops and keyframes run; **▶** on the canvas being edited runs the
+  space's own `[data-hydrated]` loops too. The motion guide adds the rule this needs from a space: `[data-hydrated]` is for
+  loops; an entrance of its own that plays once (`transform`/`opacity` only) plays from the first paint with
+  `backwards`, as the presets do — gated on hydration it jumps when the page goes live, and a canvas that never goes
+  live holds it on its first frame.
+
+  ## Thirteen ways in, nine loops
+
+  `motion` grows from six arrivals and four loops to thirteen and nine, all still `opacity` and the transforms:
+
+  - **Bold arrivals:** `slide-up` (from well below), `zoom-in` (from 60%), `zoom-out` (settling from 125%), `tilt`
+    (rising as it turns straight), `spin-in` (half a turn as it grows).
+  - **Springy arrivals:** `pop` overshoots and settles; `bounce-in` falls into place and bounces.
+  - **Loops:** `bounce`, `wobble`, `orbit` (a slow circle round where it is), `heartbeat`, `drift`.
+
+  An arrival is now a list of frames (`MOTION_ENTER_FRAMES` in `@plitzi/sdk-shared/schema/motion`; `MOTION_ENTER_FROM`
+  is its first), and so is a loop (`MOTION_LOOP_FRAMES[name].frames`, replacing `transform`/`at`). Arrivals move the
+  individual `translate`, `scale` and `rotate`, so they still compose with an element's own `transform` and with a loop.
+  The builder's Motion tab previews every frame; authoring, the MCP, `explain motion` and GraphQL read the same lists.
+
+  An arrival from the side no longer scrolls the page sideways. `slide-left` starts 32px to the right of where it lands,
+  past a phone's 16px gutter, and until it had played the page could be dragged sideways. The SDK's root clips that way
+  now (`overflow-x: clip`, which keeps the window the scroller: sticky bars and scroll timelines are untouched), and the
+  builder's preview does the same. Content wider than the page is cut rather than scrolling the page — give it a box of
+  its own with `overflow-x: auto`.
+
+  **3D and the transform parts are style properties.** `transform-style`, `perspective-origin`, `backface-visibility`,
+  `translate`, `rotate` and `scale` join the vocabulary (they were refused as `css-property-unknown` and had to go in
+  `customCss`); `scale: 0.94` is a factor, not pixels.
+
+  **The builder's placeholder for an empty element is 24px** (was 50px), one size for every element that has one. It
+  is a minimum, so it also grew empty shapes with a size of their own — a dot, a planet — while editing; 24px is still
+  a box to see, pick and drop into.
+
+  The desktop app's window was blank: authoring, run in the renderer to build the rail, asked Vite's `process` shim for
+  a working directory it does not have. It reads one only where there is one now — and only when a class conflict is
+  reported, rather than for every element of every space it writes.
+
+  ## Authoring advice that knows where and when
+  - **`class-conflict` says where both declarations are:** `styles('md-menu-button') at src/components/dropdown.ts:12,
+used by button at …, and styles('md-menu-button') at src/site/layout.ts:8, used by …` — `styles()` records its line as
+    an element factory does.
+  - **`repeated-shape` leaves controls alone.** Siblings that read different sources or write different state keys — a
+    menu for the language, one for the level — are not offered as a list.
+  - **`quiet: ['repeated-shape']`** on an element says a suggestion was left on purpose, and it is not offered again.
+    Only suggestions' codes (`quiet-unknown`). It is saved on the element (`definition.quiet`), so the builder's problems
+    panel, the MCP's `upsertElement`/`patchElement` and a project pulled back with `plitzi pull` all leave it alone.
+
+  ## What the docs say is what the code does
+
+  A pass across authoring's own messages, the skills, the MCP guide, `docs/en`, the CLI's README and the website, so an
+  agent reading two of them is never told two things:
+
+  - **A binding's `source` is the bound value, and only that.** With no value yet it fell back to the attribute's
+    current one — `sourceTo` — so `{{ source|default('…') }}` never took its default and `{{ source ? … }}` read an
+    element's placeholder ("Text") as an answer. It is `undefined` until the source has a value now; `sourceTo` is still
+    the value before.
+  - **`explain` writes a step the way its builder is called:** `delay(ms)`, `openModal('modal-id', data?)`,
+    `scrollBy('row-id', { x: '80%' })` — not `delay(…)` above the document's param names, which read as `delay({ time })`.
+  - **A page field nobody takes is told what it was probably for** — `seo` → `seoTitle` and `seoDescription` — instead of a
+    hint about keeping state appended to every one.
+  - Docs set straight: an element's id is `data-plitzi-el` in the page (`data-id` is the builder's, with debugging on);
+    a visibility condition writes nothing while its source has no value and is a yes or a no once it has one; `mobile`
+    is up to and including 48rem; `loadStrategy` defaults by type (`lazy` for a modal); the accessibility codes listed
+    in full everywhere (`embed-without-title`, `dropdown-without-control`, `controls-no-anchor`); the generated
+    `AGENTS.md` says a repeated block is a component and rows of data a list, as the skill does; `plitzi runtime` is
+    documented in the CLI's README, its skill and the website, which no longer says state across requests needs a
+    server of your own.
+
+- Updated dependencies [6ae4161]
+  - @plitzi/sdk-authoring@0.38.4
+  - @plitzi/sdk-elements@0.38.4
+  - @plitzi/sdk-interactions@0.38.4
+  - @plitzi/sdk-schema@0.38.4
+  - @plitzi/sdk-shared@0.38.4
+  - @plitzi/sdk-style@0.38.4
+  - @plitzi/plitzi-sdk@0.38.4
+  - @plitzi/sdk-server@0.38.4
+
 ## 0.38.3
 
 ### Patch Changes

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(", ");
@@ -88,6 +88,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
@@ -234,7 +240,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 +249,9 @@ 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.
+\`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 +278,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 +290,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 +422,9 @@ 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. Both add \`.isLoading\`, \`.isEmpty\`,
 \`.hasError\` and \`.errorMessage\`.
 
 **Source scope — a source is visible to the provider's DESCENDANTS only.** An element source named
@@ -435,7 +447,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",
@@ -538,6 +550,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,
@@ -926,8 +952,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 +968,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 +991,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/localScreenshotClient.d.ts

@@ -37,6 +37,9 @@ type Page = {
         value: string;
     }[]) => Promise<void>;
     evaluate: <T>(fn: () => T) => Promise<T>;
+    addStyleTag: (options: {
+        content: string;
+    }) => Promise<unknown>;
     screenshot: (options: Record<string, unknown>) => Promise<Buffer | Uint8Array>;
     /** Playwright's: the page's accessibility tree, already written as an outline. */
     locator?: (selector: string) => {

package/dist/modules/mcp/localScreenshotClient.js

@@ -1,5 +1,6 @@
 import { outlineOfSnapshot, outlineOfTree } from "./accessibilityOutline.js";
 import { PREVIEW_TOKEN_PARAM } from "@plitzi/sdk-server/kernel";
+import { MOTION_STILL_CSS } from "@plitzi/sdk-shared/schema/motion";
 //#region src/modules/mcp/localScreenshotClient.ts
 /**
 * Grow the window to whatever actually scrolls before shooting.
@@ -90,6 +91,7 @@ var createLocalScreenshotClient = async ({ renderBaseUrl, ignoreHttpsErrors = tr
 					message: `The page answered ${response.status()}.`
 				};
 				await page.evaluate(FONTS_READY);
+				await page.addStyleTag({ content: MOTION_STILL_CSS });
 				if (fullPage) {
 					const height = Math.min(await page.evaluate(CONTENT_HEIGHT), MAX_HEIGHT);
 					if (height > viewport.height) await setViewport(page, {

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

@@ -11,7 +11,7 @@ var explainResource = (uri) => {
 		names: explainList(kind)
 	};
 	const explanations = explain(name);
-	if (explanations.length === 0) throw new Error(`"${name}" is no element, step, trigger, code or transformer. List what there is: ${Object.values(EXPLAIN_KINDS).map((plural) => `${PREFIX}${plural}`).join(", ")}.`);
+	if (explanations.length === 0) throw new Error(`"${name}" is no element, step, trigger, code, transformer or helper. List what there is: ${Object.values(EXPLAIN_KINDS).map((plural) => `${PREFIX}${plural}`).join(", ")}.`);
 	return {
 		name,
 		explanations,

package/dist/modules/mcp/server.js

@@ -69,7 +69,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.3"
+		version: "0.38.4"
 	}, { 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

@@ -57,6 +57,7 @@ export declare const applyShape: {
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;

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

@@ -53,6 +53,7 @@ export declare const documentOperation: z.ZodDiscriminatedUnion<readonly [z.ZodO
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"deleteElement">;
     pageRef: z.ZodString;
@@ -838,6 +839,7 @@ export declare const operation: z.ZodDiscriminatedUnion<[z.ZodObject<{
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"deleteElement">;
     pageRef: z.ZodString;
@@ -1895,6 +1897,7 @@ export declare const operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"deleteElement">;
     pageRef: z.ZodString;
@@ -2947,6 +2950,7 @@ export declare const documentOperations: z.ZodArray<z.ZodDiscriminatedUnion<read
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"deleteElement">;
     pageRef: z.ZodString;

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

@@ -25,6 +25,7 @@ export declare const patchElementOp: z.ZodObject<{
     flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 export type PatchElement = z.infer<typeof patchElementOp>;
 export declare const patchElement: (space: Space, env: Env, op: PatchElement) => OpResult;

package/dist/modules/mcp/tools/operations/schema/elements/patchElement.js

@@ -1,7 +1,7 @@
 import { findRootByRef, invalidateIndex, resolveRef } from "../../../../helpers/space.js";
 import { pageUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
-import { elementAnchor, elementFlag, elementMotion, elementRuntime, initialStateInput, styleRefs } from "../shared.js";
+import { elementAnchor, elementFlag, elementMotion, elementQuiet, elementRuntime, initialStateInput, styleRefs } from "../shared.js";
 import { guardNewRef, writeInitialState } from "../write.js";
 import { flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
@@ -21,7 +21,8 @@ var patchElementOp = z.object({
 	runtime: elementRuntime.optional(),
 	flag: elementFlag.nullable().optional(),
 	anchor: elementAnchor.nullable().optional().describe("null removes it"),
-	motion: elementMotion.nullable().optional().describe("null removes it")
+	motion: elementMotion.nullable().optional().describe("null removes it"),
+	quiet: elementQuiet.nullable().optional()
 }).describe("Partially update an EXISTING element: only the fields you pass change (props/style/initialState are merged, not replaced). Never creates — fails if ref does not resolve. Use upsertElement to create or fully replace.");
 var patchElement = (space, env, op) => {
 	const page = findRootByRef(space.schema, op.pageRef);
@@ -59,6 +60,8 @@ var patchElement = (space, env, op) => {
 	else if (op.anchor !== void 0) el.definition.anchor = op.anchor;
 	if (op.motion === null) Reflect.deleteProperty(el.definition, "motion");
 	else if (isMotion(op.motion)) el.definition.motion = op.motion;
+	if (op.quiet === null) Reflect.deleteProperty(el.definition, "quiet");
+	else if (op.quiet !== void 0) el.definition.quiet = op.quiet;
 	return {
 		...empty(),
 		updated: 1,

package/dist/modules/mcp/tools/operations/schema/elements/upsertElement.js

@@ -37,6 +37,7 @@ var upsertElement = (space, env, op) => {
 		if (op.element.flag !== void 0) existing.definition.flag = flagGateOf(op.element.flag, `Element "${op.element.ref}"`);
 		if (op.element.anchor !== void 0) existing.definition.anchor = op.element.anchor;
 		if (isMotion(op.element.motion)) existing.definition.motion = op.element.motion;
+		if (op.element.quiet !== void 0) existing.definition.quiet = op.element.quiet;
 		return {
 			...empty(),
 			updated: 1,

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

@@ -53,6 +53,7 @@ export declare const elementOps: {
         flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         anchor: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         motion: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnknown>>>;
+        quiet: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodArray<import('zod').ZodString>>>;
     }, import('zod/v4/core').$strip>;
     deleteElement: import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteElement">;

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

@@ -22,6 +22,7 @@ export interface ElementInput {
     anchor?: string;
     /** Checked by `motionProblems`: what arrives here is one, which `isMotion` narrows it to where it is written. */
     motion?: Record<string, unknown>;
+    quiet?: string[];
     children?: ElementInput[];
 }
 export declare const styleRefs: z.ZodObject<{
@@ -49,6 +50,8 @@ export declare const elementAnchor: z.ZodString;
  * refused with the list of right ones, and the guide's Motion section names them all.
  */
 export declare const elementMotion: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** Suggestions' codes an element is not offered, written that way on purpose; never a problem's code. */
+export declare const elementQuiet: z.ZodArray<z.ZodString>;
 export declare const initialStateInput: z.ZodObject<{
     styleVariant: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>>;
     visibility: z.ZodOptional<z.ZodBoolean>;
@@ -75,6 +78,7 @@ export declare const elementShape: {
     flag: z.ZodOptional<z.ZodString>;
     anchor: z.ZodOptional<z.ZodString>;
     motion: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    quiet: z.ZodOptional<z.ZodArray<z.ZodString>>;
 };
 export declare const elementInput: z.ZodType<ElementInput>;
 export declare const position: z.ZodEnum<{

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

@@ -1,3 +1,4 @@
+import { isSuggestionCode } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 import { FLAG_GATE_PATTERN } from "@plitzi/sdk-shared/flags";
 import { ANCHOR_PATTERN } from "@plitzi/sdk-shared/schema/anchor";
@@ -84,6 +85,13 @@ var elementMotion = z.record(z.string(), z.unknown()).superRefine((motion, ctx)
 		message: problem
 	});
 }).describe("{enter,on,duration,delay,stagger,loop} — guide: Motion");
+/** Suggestions' codes an element is not offered, written that way on purpose; never a problem's code. */
+var elementQuiet = z.array(z.string()).superRefine((codes, ctx) => {
+	for (const code of codes.filter((code) => !isSuggestionCode(code))) ctx.addIssue({
+		code: "custom",
+		message: `"${code}" is no suggestion's code`
+	});
+}).describe("Suggestion codes not offered on it, e.g. [\"repeated-shape\"]");
 var initialStateInput = z.object({
 	styleVariant: styleVariantInput.optional().describe("Variant each attached class uses: { className: { base|slot: variantName | [names] } }"),
 	visibility: z.boolean().optional().describe("Initial visibility of the element")
@@ -99,7 +107,8 @@ var elementShape = {
 	runtime: elementRuntime.optional(),
 	flag: elementFlag.optional(),
 	anchor: elementAnchor.optional(),
-	motion: elementMotion.optional()
+	motion: elementMotion.optional(),
+	quiet: elementQuiet.optional()
 };
 var elementInput = z.lazy(() => z.object({
 	...elementShape,
@@ -156,4 +165,4 @@ var interactionNode = z.object({
 	preview: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
-export { bindingCategory, bindingInput, elementAnchor, elementFlag, elementInput, elementMotion, elementRuntime, elementShape, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };
+export { bindingCategory, bindingInput, elementAnchor, elementFlag, elementInput, elementMotion, elementQuiet, elementRuntime, elementShape, initialStateInput, interactionNode, interactionNodeType, position, ruleGroup, scalar, styleRefs, styleVariantInput };

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

@@ -69,7 +69,8 @@ var createElement = (space, page, input, anchorId, drop) => {
 			...input.runtime === void 0 ? {} : { runtime: input.runtime },
 			...input.flag === void 0 ? {} : { flag: flagGateOf(input.flag, `Element "${input.ref}"`) },
 			...input.anchor === void 0 ? {} : { anchor: input.anchor },
-			...isMotion(input.motion) ? { motion: input.motion } : {}
+			...isMotion(input.motion) ? { motion: input.motion } : {},
+			...input.quiet === void 0 ? {} : { quiet: input.quiet }
 		}
 	};
 	if (!new FlatMap({ flat: space.schema.flat }).addElement(el, anchorId, drop)) return false;

package/dist/modules/mcp/tools/operations/schemaIds.js

@@ -1,6 +1,6 @@
 import { actionAccess, actionField, actionLimits, actionNode, actionTriggerParams } from "./actions/document.js";
 import { connectorConnection, readEndpoint, writeEndpoint } from "./connectors/manifest.js";
-import { bindingInput, elementAnchor, elementFlag, elementInput, elementMotion, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
+import { bindingInput, elementAnchor, elementFlag, elementInput, elementMotion, elementQuiet, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
 import { ancestors, ancestorsPatch, cssMap, cssPatchMap, definitionSlot, definitionSlotPatch, displayModeCss, displayModeCssPatch, themeValue } from "./style/shared.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schemaIds.ts
@@ -26,6 +26,7 @@ var SHARED_SCHEMAS = [
 	[elementFlag, "ElementFlag"],
 	[elementAnchor, "ElementAnchor"],
 	[elementMotion, "ElementMotion"],
+	[elementQuiet, "ElementQuiet"],
 	[ruleGroup, "RuleGroup"],
 	[styleRefs, "StyleRefs"],
 	[initialStateInput, "InitialState"],

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

@@ -53,6 +53,7 @@ export declare const previewShape: {
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;

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

@@ -55,6 +55,7 @@ export declare const renderShape: {
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;

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

@@ -53,6 +53,7 @@ export declare const screenshotShape: {
         flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         motion: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        quiet: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;

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

@@ -54,6 +54,7 @@ export declare const validateShape: {
         flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         anchor: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         motion: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnknown>>>;
+        quiet: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodArray<import('zod').ZodString>>>;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteElement">;
         pageRef: import('zod').ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.38.3",
+  "version": "0.38.4",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,14 +30,14 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "@plitzi/plitzi-sdk": "0.38.3",
-    "@plitzi/sdk-authoring": "0.38.3",
-    "@plitzi/sdk-elements": "0.38.3",
-    "@plitzi/sdk-interactions": "0.38.3",
-    "@plitzi/sdk-schema": "0.38.3",
-    "@plitzi/sdk-server": "0.38.3",
-    "@plitzi/sdk-shared": "0.38.3",
-    "@plitzi/sdk-style": "0.38.3",
+    "@plitzi/plitzi-sdk": "0.38.4",
+    "@plitzi/sdk-authoring": "0.38.4",
+    "@plitzi/sdk-elements": "0.38.4",
+    "@plitzi/sdk-interactions": "0.38.4",
+    "@plitzi/sdk-schema": "0.38.4",
+    "@plitzi/sdk-server": "0.38.4",
+    "@plitzi/sdk-shared": "0.38.4",
+    "@plitzi/sdk-style": "0.38.4",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"