@plitzi/sdk-mcp 0.38.2 → 0.38.4

package/CHANGELOG.md

@@ -1,5 +1,342 @@
 # @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
+
+- e047e1d: ## `plitzi upgrade`: a project brought up to its CLI
+
+  A project written by an older CLI had no way up but `plitzi create` in a scratch folder and a file-by-file comparison:
+  `skills update` brought the skills and nothing else, so the `check` and `shot` scripts they teach did not exist.
+  `plitzi upgrade` (also `update`) shows what this CLI writes today for what is the CLI's in the project, and `--write`
+  makes it. One part or several: `plitzi upgrade skills`, `plitzi upgrade files packages`.
+
+  - **`files`:** the CLI's machinery — `author.ts`, `main.ts`, the Playwright, TypeScript and lint configs, AGENTS.md. One
+    nobody changed since the CLI wrote it is replaced, a missing one added; one the project made its own is shown as a
+    diff and left, until `--take <file>` (or `all`). `plitzi create` now records what it wrote, by digest, in
+    `.plitzi/scaffold.json`; a project made before that sees every file that differs as its own.
+  - **`packages`:** `package.json` merged, never replaced — the scripts and dependencies it lacks added, `@plitzi/*`
+    raised to this version, then the install (`--no-install` to leave it). A script of the project's own stays.
+  - **`skills`:** `.claude/skills/plitzi-*` from the packages installed, each replaced whole, and the ones a newer CLI
+    writes added. `plitzi skills update` is `plitzi upgrade skills --write`.
+  - **`renames`:** a name a version renamed with no alias, at its file and line — `canTemplate` → `canSnippet`,
+    `authorTemplate` → `authorSnippet` and its kin (renamed only where imported from `@plitzi/sdk-authoring`) — renamed
+    with `--write`.
+
+  `npm run author` says when the skills or the CLI's files are older than the SDK installed, and `plitzi --version`
+  prints the CLI's.
+
+  ## Page checks that can be the definition of done
+
+  `inspectPage`, `plitzi check` and the scaffold's visual test failed pages that were whole, so an agent learnt to ignore
+  them:
+
+  - **A breakpoint hiding an element on purpose** — the desktop navigation on a phone, a bottom bar only a phone shows —
+    is no longer "not visible": an element whose `display` or `visibility` a breakpoint rule sets is checked at the width
+    it shows at.
+  - **A lazy image out of sight** waits whichever side it is out of: below the fold, as before, or beside the screen in a
+    carousel's track — cut off by any ancestor that clips, as the browser decides when to fetch it.
+  - **A plugin that draws nothing** says so: `drawsNothing: true` in its declaration (a clock that fires a flow), and its
+    handle is `boxless`, so no check waits for it on screen.
+
+  `plitzi check --json` and `PageReport` carry `issues` beside `problems`: each with its `code` (`element-hidden`,
+  `image-not-loaded`, `sideways-scroll`…), the `elementId` it is about and, in `check`, the `width`.
+
+  ## Authoring
+  - **A link's `content` names it.** `control-without-name` read only a link's `label`, so applying the
+    `content-attribute` suggestion as written turned every link into a warning.
+  - **`plitzi fix` writes `content-attribute`** where it has one reading: a button's or link's children that are only
+    `text(…)` and `fontAwesome({ icon })` become its own `content` and `icon` — the words kept as written, an import left
+    unused taken out. A child with an id, options or a class of the space's own stays, and is said. `npm run author`'s
+    `[fix]` line counts these too.
+  - **The recipes, the skill's examples and the catalog template** hold to the suggestions as well as the warnings, and
+    their tests say so: six recipes and the template wrote a link's or a button's words as a child.
+
+  ## Declared motion — in code, in the builder and over MCP
+
+  An element says how it arrives and whether it keeps moving with `motion`, and the SDK's stylesheet plays it — no
+  keyframes to write: `{ enter: 'fade-up', on: 'view' }` arrives as it scrolls into view, `{ enter: 'scale', stagger:
+60 }` brings its children one by one (a grid, a list's rows), `{ loop: 'float' }` keeps it moving. Enters: `fade`,
+  `fade-up`, `fade-down`, `slide-left`, `slide-right`, `scale`; loops: `float`, `pulse`, `spin`, `sway`; `duration`,
+  `delay`, `stagger` in ms. Opacity and the transforms only — an arrival on `translate`/`scale`, so it composes with an
+  element's own `transform` — a loop held until the page is live (`data-hydrated`), and none of it for a visitor who asked
+  for less motion. `view` follows the scroll where the browser has scroll timelines and plays on load where not.
+
+  - **Authoring:** `motion` on any factory; refused where it cannot play (`motion-invalid`, `motion-no-tag`), and carried
+    by `specFromSpace` and `compareSpaces`.
+  - **Builder:** a **Motion** tab in an element's tools: the presets as chips, a stage that plays the one pointed at (a
+    loop shown stronger than the page plays it, and saying so), when and how long, children one by one, and the choices
+    read back as a sentence — laid out side by side once the sidebar is wide enough. The canvas holds motion still while
+    editing; **▶** in the header (or **Play on the canvas** in the tab) plays it from the start, restarting what already
+    played, and an arrival tied to the scroll plays by the clock there, where it is usually in view already.
+  - **MCP:** `motion` on `upsertElement` and `patchElement`, checked the same way; the guide names the presets.
+  - **Schema:** `definition.motion` (`ElementMotion`, `@plitzi/sdk-shared/schema/motion` — the presets, `motionProblems`,
+    `motionAttributes`, `isMotionAnimation`, and each preset's frames, which the stylesheet is tested against), in both
+    init queries. **The platform's GraphQL schema has to declare `SpaceElementMotion`
+    before this version's builder or SDK queries it.**
+
+  ## Dev tools QA: x-ray and motion
+
+  The **QA** tab gains an **X-ray**: every element the document wires something to — bound to data, shown on a condition,
+  running a flow, moving, behind a flag — outlined in its colour and named on the page, read from the space's document by
+  the element's name; its legend counts each kind on the page and picks one to show alone. Beside **Pause**, **Slow**
+  plays every animation at a quarter of its speed and **Replay** plays the declared motion again from the start, without
+  reloading the page.
+
+  ## Plugins that draw
+
+  `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` (`@plitzi/plitzi-sdk`): a canvas sized to the device (at
+  most 2×), followed as it resizes, animating only while somebody can see it move — a live page, no reduced motion, the
+  tab in front, the canvas on screen — and one still frame otherwise (the builder included). `createShaderProgram`
+  compiles and links, and a shader that fails throws a `ShaderError` with the driver's log, printed as
+  `[plugin <type> "<id>"] fragment shader failed: …` instead of an empty canvas; `error` and `ready` say where it is.
+  `useReducedMotion` for the rest.
+
+  ## A space re-authored without a restart
+
+  A project's `npm run start:dev` restarts for its server code and its plugins only: a save to the space is re-authored
+  in a process of its own and every open page loads again (`server.reloadPages()` over an SSE endpoint, on with
+  `createServer({ devReload: true })` — never by `devMode` alone, since every open page holds a connection for it); an
+  edit authoring refuses is printed and the page keeps the last space that authored. A shutdown also ends WebSockets at
+  once (`1001`, going away) rather than waiting out the grace — the ten seconds a restart used to wait on an open page.
+
+  ## Checks and authoring, from the stripe.com experiment
+  - **A component's instance** is found by its own name: its root carries `data-plitzi-instance`, and the instance's
+    handle selects it — `inspectPage` no longer reports every named instance as missing.
+  - **Hidden at this width on purpose** — the burger on a desktop, the desktop menu on a phone — is listed apart
+    (`hiddenAtWidth`, and a dim line under `plitzi check`'s ✓) rather than as a problem.
+  - **An element whose every child is conditional** — four flyouts in one list, each opening on the state that names
+    it — is conditional too: at rest it shows nothing, and that is it working.
+  - **A carousel that scrolls by itself** (`overflow-x: auto`) is not the page scrolling sideways; the page's own pane
+    still is.
+  - **Templates:** `{{ state.faq ?? -1 }}` — a sign on the right of `??` — reads.
+  - **A plugin attribute named as an element field** (`variant`, `class`, `id`…) is warned about
+    (`plugin-attribute-reserved`): a factory never hands it to the plugin. A `variant` no class or type style declares is
+    `unknown-variant`.
+  - **Lists:** a list with `items` renders as the `<ul>` (or `<ol>`) its `subType` says — it was a `<div>` — with no
+    markers and the same spacing, so a page looks as it did; the builder offers the list type for it too. Its rows are
+    `<li>`s: `list-row-not-li` warns of one that is not — a plain container is made one by `fixSpace`, a link or a button
+    is wrapped — and the recipes, the catalog template and the docs write rows as `listItem`.
+  - **CSS:** `mask-size`, `mask-position`, `mask-repeat`, `mask-composite`, `-webkit-mask-image`,
+    `-webkit-background-clip`, `box-decoration-break` and `-webkit-box-decoration-break`.
+  - **`plitzi shot`:** `--clip <element>`, `--scroll-to <element>` and `--viewport`; `--frames` takes the same framing.
+  - **SVG from files:** `svgFile` and `svgFiles` (`@plitzi/sdk-authoring/node`) read a logo or a folder of them,
+    compacted (`compactSvg`, also on the main entry), instead of strings in the space's source.
+  - The plugin scaffolds say that an inline `style` on `RootElement` outranks the element's classes.
+
+- Updated dependencies [e047e1d]
+  - @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-shared@0.38.3
+  - @plitzi/sdk-style@0.38.3
+  - @plitzi/plitzi-sdk@0.38.3
+  - @plitzi/sdk-server@0.38.3
+
 ## 0.38.2
 
 ### 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,
@@ -616,7 +642,9 @@ reads \`list_<name>.item.values.<field>\`), \`.pageInfo\` (\`page\`, \`pageCount
 instead of \`.records\` — that is what a **detail page** uses. Bind an empty-state block's visibility to \`.isEmpty\`
 and an error block's to \`.hasError\`; they are ordinary bindings, no special mechanism.
 
-**A list page** — provider, then a \`list\` inside it bound to the records, then the row template reading the item:
+**A list page** — provider, then a \`list\` inside it bound to the records, then the row template reading the item
+(a \`list\` is a \`<ul>\`, or \`<ol>\` by \`subType\`; its row a \`listItem\`, an \`<li>\` — any other row is warned
+\`list-row-not-li\`):
 \`\`\`json
 { "operations": [
   { "type": "upsertElement", "pageRef": "blog", "element": {
@@ -922,7 +950,13 @@ Space-level configuration lives in \`plitzi://settings/{env}\` and is edited wit
   \`{ "type": "patchSettings", "customCss": "@keyframes spin { to { transform: rotate(360deg); } }" }\`.
 
 ## Motion — good practices
-Keyframes go in \`customCss\` (\`patchSettings\`), a definition names them (\`animation\`). Only \`opacity\` and
+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. \`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
 page's scripts run.
@@ -934,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
@@ -956,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.2"
+		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

@@ -56,6 +56,8 @@ 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

@@ -52,6 +52,8 @@ 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;
@@ -836,6 +838,8 @@ 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;
@@ -1892,6 +1896,8 @@ 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;
@@ -2943,6 +2949,8 @@ 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

@@ -24,6 +24,8 @@ 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,10 +1,11 @@
 import { findRootByRef, invalidateIndex, resolveRef } from "../../../../helpers/space.js";
 import { pageUri } from "../../../../helpers/uris.js";
 import { empty, fail } from "../../../../helpers/opResult.js";
-import { elementAnchor, elementFlag, 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";
+import { isMotion } from "@plitzi/sdk-shared/schema/motion";
 import { repointIds } from "@plitzi/sdk-schema/helpers/elementId";
 //#region src/modules/mcp/tools/operations/schema/elements/patchElement.ts
 var patchElementOp = z.object({
@@ -19,7 +20,9 @@ var patchElementOp = z.object({
 	initialState: initialStateInput.optional().describe("Merged onto existing initialState: styleVariant overlays per class/selector, visibility overrides"),
 	runtime: elementRuntime.optional(),
 	flag: elementFlag.nullable().optional(),
-	anchor: elementAnchor.nullable().optional().describe("null removes it")
+	anchor: elementAnchor.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);
@@ -55,6 +58,10 @@ var patchElement = (space, env, op) => {
 	else if (op.flag !== void 0) el.definition.flag = flagGateOf(op.flag, `Element "${op.ref}"`);
 	if (op.anchor === null) Reflect.deleteProperty(el.definition, "anchor");
 	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

@@ -5,6 +5,7 @@ import { elementInput, position } from "../shared.js";
 import { DROP_POSITION, collectInputRefs, createElement, guardNewRef, writeInitialState } from "../write.js";
 import { flagGateOf } from "@plitzi/sdk-authoring";
 import { z } from "zod";
+import { isMotion } from "@plitzi/sdk-shared/schema/motion";
 //#region src/modules/mcp/tools/operations/schema/elements/upsertElement.ts
 var upsertElementOp = z.object({
 	type: z.literal("upsertElement"),
@@ -35,6 +36,8 @@ var upsertElement = (space, env, op) => {
 		if (op.element.runtime !== void 0) existing.definition.runtime = op.element.runtime;
 		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/motion.test.d.ts

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

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

@@ -52,6 +52,8 @@ 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

@@ -20,6 +20,9 @@ export interface ElementInput {
     runtime?: ElementRuntime;
     flag?: string;
     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<{
@@ -39,6 +42,16 @@ export declare const elementRuntime: z.ZodEnum<{
 export declare const elementFlag: z.ZodString;
 /** The element's `id` in the DOM, so `/page#anchor` lands on it — the one pattern every writer holds it to. */
 export declare const elementAnchor: z.ZodString;
+/**
+ * How an element arrives and whether it keeps moving — the presets the SDK's stylesheet plays, and nothing else.
+ *
+ * An open object, checked by `motionProblems`, rather than its fields spelled out: this schema is in every tool that
+ * carries the op union, and spelled out it cost the listing more than its budget had room for. A wrong preset is
+ * 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>;
@@ -64,6 +77,8 @@ 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,6 +1,8 @@
+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";
+import { motionProblems } from "@plitzi/sdk-shared/schema/motion";
 //#region src/modules/mcp/tools/operations/schema/shared.ts
 var combinator = z.enum(["and", "or"]);
 var operator = z.enum([
@@ -70,6 +72,26 @@ var elementRuntime = z.enum([
 var elementFlag = z.string().regex(FLAG_GATE_PATTERN).describe("Feature flag: `name` renders only while on, `!name` only while off");
 /** The element's `id` in the DOM, so `/page#anchor` lands on it — the one pattern every writer holds it to. */
 var elementAnchor = z.string().regex(ANCHOR_PATTERN).describe("Its DOM id, for `/page#anchor` and the `hash` of a link; one per page");
+/**
+* How an element arrives and whether it keeps moving — the presets the SDK's stylesheet plays, and nothing else.
+*
+* An open object, checked by `motionProblems`, rather than its fields spelled out: this schema is in every tool that
+* carries the op union, and spelled out it cost the listing more than its budget had room for. A wrong preset is
+* refused with the list of right ones, and the guide's Motion section names them all.
+*/
+var elementMotion = z.record(z.string(), z.unknown()).superRefine((motion, ctx) => {
+	for (const problem of motionProblems(motion)) ctx.addIssue({
+		code: "custom",
+		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")
@@ -84,7 +106,9 @@ var elementShape = {
 	initialState: initialStateInput.optional().describe("Applied style variant(s) and initial visibility (see plitzi://guide styling)"),
 	runtime: elementRuntime.optional(),
 	flag: elementFlag.optional(),
-	anchor: elementAnchor.optional()
+	anchor: elementAnchor.optional(),
+	motion: elementMotion.optional(),
+	quiet: elementQuiet.optional()
 };
 var elementInput = z.lazy(() => z.object({
 	...elementShape,
@@ -141,4 +165,4 @@ var interactionNode = z.object({
 	preview: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
-export { bindingCategory, bindingInput, elementAnchor, elementFlag, elementInput, 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

@@ -3,6 +3,7 @@ import { folderUri, foldersUri, layoutsUri, pageUri, pagesUri, schemaVarsUri, se
 import { fail } from "../../../helpers/opResult.js";
 import { flagGateOf } from "@plitzi/sdk-authoring";
 import { documentIds } from "@plitzi/sdk-schema/helpers/components";
+import { isMotion } from "@plitzi/sdk-shared/schema/motion";
 import { elementIdConflict, isValidElementId } from "@plitzi/sdk-schema/helpers/elementId";
 import FlatMap from "@plitzi/sdk-schema/helpers/FlatMap";
 //#region src/modules/mcp/tools/operations/schema/write.ts
@@ -67,7 +68,9 @@ var createElement = (space, page, input, anchorId, drop) => {
 			styleSelectors,
 			...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 }
+			...input.anchor === void 0 ? {} : { anchor: input.anchor },
+			...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, 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
@@ -25,6 +25,8 @@ var SHARED_SCHEMAS = [
 	[elementInput, "Element"],
 	[elementFlag, "ElementFlag"],
 	[elementAnchor, "ElementAnchor"],
+	[elementMotion, "ElementMotion"],
+	[elementQuiet, "ElementQuiet"],
 	[ruleGroup, "RuleGroup"],
 	[styleRefs, "StyleRefs"],
 	[initialStateInput, "InitialState"],

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

@@ -52,6 +52,8 @@ 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

@@ -54,6 +54,8 @@ 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

@@ -52,6 +52,8 @@ 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

@@ -53,6 +53,8 @@ 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.2",
+  "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.2",
-    "@plitzi/sdk-authoring": "0.38.2",
-    "@plitzi/sdk-elements": "0.38.2",
-    "@plitzi/sdk-interactions": "0.38.2",
-    "@plitzi/sdk-schema": "0.38.2",
-    "@plitzi/sdk-server": "0.38.2",
-    "@plitzi/sdk-shared": "0.38.2",
-    "@plitzi/sdk-style": "0.38.2",
+    "@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"