@plitzi/sdk-server 0.38.3 → 0.38.4

package/CHANGELOG.md

@@ -1,5 +1,202 @@
 # @plitzi/sdk-server
 
+## 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-shared@0.38.4
+  - @plitzi/plitzi-sdk@0.38.4
+
 ## 0.38.3
 
 ### Patch Changes

package/README.md

@@ -158,7 +158,8 @@ serve it — worth running over anything that arrives as a file.
 A space on Plitzi comes out whole, as a project wired to this server: `npx @plitzi/cli create my-site --from <space>`
 writes its pages as authoring code, its actions as `defineAction` code, its functions, the source of its plugins and
 runtime, and its files into `public/` — a draft, or any published snapshot (`--environment`, `--revision`) — and
-`plitzi pull` keeps it in step. See `docs/en/projects-from-spaces.md` in the workspace.
+`plitzi pull` keeps it in step, and `plitzi push` puts what changed in it back on the space. See
+`docs/en/projects-from-spaces.md` in the workspace.
 
 ## Configuration
 
@@ -176,11 +177,11 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `signIn` | `SSRSignInConfig` | — | Sign visitors in by redirect through an OAuth 2.1 authorization server: `GET /auth/sign-in?return=/x` registers this host as a client, sends the browser out with PKCE (state in a `__Host-` cookie), and `/auth/sign-in/callback` redeems the code server to server and hands the token to `exchangeCredential`, which makes the session here. Needs the `exchangeCredential` adapter. |
 | `templateFn` | `SSRTemplateFn` | built-in EJS template | Custom render function. Receives all template params and returns an HTML string. |
 | `plugins` | `Record<string, PluginSource>` | — | Named plugin definitions. Compiled or copied on first use and cached for `pluginsTtlMs`. |
-| `pluginsCacheDir` | `string` | `.sdk-plugins` | Directory where compiled plugin files are stored. |
+| `pluginsCacheDir` | `string` | `tmp/.sdk-plugins` | Directory where compiled plugin files are stored — under `tmp/`, with everything else the server writes for itself. |
 | `pluginsTtlMs` | `number` | `604800000` | TTL in milliseconds for compiled plugins (default: 1 week). |
 | `autoLoadSchemaPlugins` | `boolean` | `true` | Auto-download and cache plugins declared in the schema's `offlineData.plugins` list. A type the deployment registers itself (`plugins`, named in `pluginNames`) is never looked for there: its own build is the one rendered. Set to `false` to manage plugin loading manually. |
 | `allowPrivatePluginHosts` | `boolean` | `false` | Read a schema plugin from a private address (`localhost`, this server's own network). A plugin's address is typed by whoever edits a space, so leave it off anywhere but a development machine whose bucket is local. |
-| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. |
+| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. **Everything in it is public:** served to anyone who asks, with no check. |
 | `static` | `Record<string, string>` | — | URL prefix → filesystem path mappings for static file serving. |
 | `images` | `{ domains, cacheDir? }` | — | Pictures from other sites resized at `/_plitzi/img`, for an `image` to offer as a `srcset` (see [Images](#images)). |
 | `ssrOnly` | `boolean` | `false` | Omit client-side JS from the rendered page. Useful for verifying SSR HTML without hydration. |
@@ -397,11 +398,13 @@ createServer({ images: { domains: ['images.example.com', '*.cdn.example.com'] },
 
 An `image` whose `src` is another site's then offers the browser a `srcset` of widths this server makes (320 to 1920
 px) at `/_plitzi/img?url=…&w=…`, in AVIF or WebP when the browser takes them. Everything is kept on disk (`cacheDir`,
-default `.plitzi/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
+default `tmp/images`): each original is downloaded once, and each size is made once from it. A week on, the kept
 files keep answering while the original is asked for with its `ETag` / `Last-Modified` — unchanged, nothing is resized
 again; changed, its sizes are made anew. A picture that could not be fetched is not asked for again for five minutes.
 Only the listed hosts are fetched, every redirect is held to the same
-list and to the rule every outbound request follows (no private network), and SVG is refused. Resizing needs `sharp`
+list and to the rule every outbound request follows (no private network). An SVG is never resized nor served from
+this origin: the proxy answers it with a redirect to its own address (`307`), so the picture still shows. An `image`
+with `resize: false` keeps its `src` as written. Resizing needs `sharp`
 (an optional peer): without it pictures are passed through and kept, and the server says so once.
 
 ### Public directory
@@ -417,6 +420,10 @@ createServer({
 
 The lookup order for a request is: `publicDir` → `static` prefix routes → SSR renderer.
 
+**Everything in `publicDir` is on the internet.** A file there is served to anyone who asks for it, as it is — no
+session, no permission, no check. Never put a secret, a key, an `.env`, a private document, a database dump or data only
+some visitors may read in it: that is served by a server action whose `access` checks who is asking.
+
 `/.well-known/` paths follow the same lookup order: served from `publicDir` if a matching file exists, otherwise `404 Not Found`. They are never handled by the SSR renderer.
 
 ## Compression
@@ -518,7 +525,7 @@ const server = createServer({
     // From a source file — compiled to ESM with esbuild
     'my-chart': {
       js: '/abs/path/to/MyChart.tsx',
-      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to .sdk-plugins
+      css: '/abs/path/to/MyChart.css',  // filesystem path — copied to tmp/.sdk-plugins
       version: '1.2.0'
     },
     // Pre-compiled local file — copied as-is (version defaults to '1.0.0')
@@ -671,7 +678,9 @@ The SSR server includes a lightweight RSC endpoint that delivers server-side dat
 
 ### Schema setup
 
-Enable RSC at the top level of your schema:
+Server data is on unless the schema turns it off with `"rsc": { "enabled": false }` — the page render and the
+default `getRscData` (`connectorRscData`) read a missing `rsc` alike. `authorSpace` writes it out for a space with a
+server provider:
 
 ```json
 {

package/dist/core/http/stages/images.js

@@ -15,7 +15,7 @@ var proxyFor = (images) => {
 		if (!transform) serverLog.warn("IMAGES", "sharp is not installed: pictures are passed through and kept, not resized (npm i sharp).");
 		return createImageProxy({
 			domains: images.domains,
-			cacheDir: path.resolve(images.cacheDir ?? ".plitzi/images"),
+			cacheDir: path.resolve(images.cacheDir ?? "tmp/images"),
 			fetch: globalThis.fetch,
 			transform
 		});

package/dist/modules/images/imageProxy.js

@@ -45,6 +45,19 @@ var Refusal = class extends Error {
 	}
 };
 var refuse = (status, message) => new Refusal(answer(status, message));
+/**
+* A vector picture is sent back to where it is: there is no size of it to make, and an SVG served from this origin is a
+* document that can run script. The browser loads it from its own host, as it would without this endpoint.
+*/
+var toOriginal = (source) => new Refusal({
+	status: 307,
+	headers: {
+		Location: source.href,
+		"Cache-Control": CACHE_CONTROL
+	},
+	body: ""
+});
+var isVector = (pathname) => /\.svgz?$/i.test(pathname);
 /** One of each at a time: a second request for what is being made waits for the first. */
 var oneAtATime = () => {
 	const running = /* @__PURE__ */ new Map();
@@ -142,6 +155,10 @@ var createImageProxy = (options) => {
 			return { changed: false };
 		}
 		const type = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+		if (response.ok && type === "image/svg+xml") {
+			await response.body?.cancel();
+			throw toOriginal(source);
+		}
 		if (!response.ok || !Object.hasOwn(SOURCE_TYPES, type)) {
 			await response.body?.cancel();
 			throw refuse(502, response.ok ? `Not a picture this endpoint serves (${type || "no type"}).` : "The picture could not be fetched.");
@@ -205,7 +222,7 @@ var createImageProxy = (options) => {
 				await keepOriginal(urlKey, fetched, meta);
 				return fetched;
 			} catch (error) {
-				failedUntil.set(urlKey, now() + FAILED_MS);
+				if (!(error instanceof Refusal && error.answer.status === 307)) failedUntil.set(urlKey, now() + FAILED_MS);
 				throw error;
 			}
 		});
@@ -238,6 +255,7 @@ var createImageProxy = (options) => {
 		const requested = Number(width);
 		if (!isImageWidth(requested)) return answer(400, `\`w\` is one of ${IMAGE_WIDTHS.join(", ")}.`);
 		if (!isAllowedImageHost(domains, source.hostname)) return answer(403, `${source.hostname} is not one of the hosts this server takes pictures from.`);
+		if (isVector(source.pathname)) return toOriginal(source).answer;
 		const format = transform ? negotiate(accept) : "original";
 		const urlKey = sha(source.href);
 		try {

package/dist/modules/rsc/connectorRscData.js

@@ -37,7 +37,7 @@ var connectorRscData = ({ connectors, actions, publicDir, elementTimeoutMs }) =>
 	};
 	return async ({ req, spaceId, environment, user, ids, loadOfflineData, flagOverrides }) => {
 		const offlineData = await loadOfflineData();
-		if (!offlineData?.schema.rsc?.enabled) return {};
+		if (!offlineData || offlineData.schema.rsc?.enabled === false) return {};
 		return resolveRscData({
 			schema: offlineData.schema,
 			req,

package/dist/modules/rsc/publicFileResolver.d.ts

@@ -9,5 +9,8 @@ import { RscElementResolver } from './resolveRscData';
  *
  * Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
  * in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
+ *
+ * Answered in the shape a browser request publishes — `{ status, data }`, the body under `data` — so a provider reads
+ * `<source>.data.<field>` whichever runtime it has, and moving it to the server changes no binding.
  */
 export declare const publicFileResolver: (publicDir: string) => RscElementResolver;

package/dist/modules/rsc/publicFileResolver.js

@@ -11,6 +11,9 @@ import { readFile } from "node:fs/promises";
 *
 * Only a plain path inside `publicDir`: a URL, one that climbs out of the folder, or one with `{{tokens}}` (resolved
 * in the browser against the visitor's route and state) is not this resolver's, and the element is left as it was.
+*
+* Answered in the shape a browser request publishes — `{ status, data }`, the body under `data` — so a provider reads
+* `<source>.data.<field>` whichever runtime it has, and moving it to the server changes no binding.
 */
 var publicFileResolver = (publicDir) => {
 	const root = path.resolve(publicDir);
@@ -26,10 +29,13 @@ var publicFileResolver = (publicDir) => {
 		const file = path.resolve(root, `.${pathname}`);
 		if (!file.startsWith(`${root}${path.sep}`)) return;
 		try {
-			return JSON.parse(await readFile(file, {
-				encoding: "utf8",
-				signal
-			}));
+			return {
+				status: 200,
+				data: JSON.parse(await readFile(file, {
+					encoding: "utf8",
+					signal
+				}))
+			};
 		} catch {
 			return null;
 		}

package/dist/plugins/manager.js

@@ -10,7 +10,7 @@ import fs from "node:fs/promises";
 //#region src/plugins/manager.ts
 var META_FILE = "meta.json";
 var DEFAULT_TTL_MS = 6048e5;
-var DEFAULT_CACHE_DIR = ".sdk-plugins";
+var DEFAULT_CACHE_DIR = "tmp/.sdk-plugins";
 /** One hash over every input's path and content — a file gone counts as changed, like a file edited. */
 var digestOf = async (files) => {
 	const hash = createHash("sha256");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.3",
+  "version": "0.38.4",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -79,8 +79,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.3",
-    "@plitzi/sdk-shared": "0.38.3",
+    "@plitzi/plitzi-sdk": "0.38.4",
+    "@plitzi/sdk-shared": "0.38.4",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -33,7 +33,7 @@ paragraph('A paragraph.')
 container([children], { subType: 'section' })  // div, section, nav, header, footer, main, article, li, h1–h6, span…
 link({ href: 'about', content: 'About' })      // a page id, a '/path', or a URL — the mode follows from the href
 link({ href: 'home', hash: 'plans' })          // → /#plans, onto the element with anchor: 'plans'
-container({ motion: { enter: 'fade-up', on: 'view' }, children })  // arrives as it scrolls in; stagger, loop too
+container({ motion: { enter: 'fade-up', on: 'view' }, children })  // arrives once as it comes into view; stagger, loop too
 button({ content: 'Save', flows })             // holds children too: then content: ''
 image({ src, alt })                            // or decorative: true
 embed({ src, title })                          // a map, a player: another page in a frame
@@ -45,6 +45,7 @@ list({ id: 'rows', items: 'p.data.rows', row: r => listItem({ children: [text({
 carousel({ id: 'hero', items: 'p.data.slides', autoplay: 5000, row: 'slide-card', children: [/* carouselNext('hero') arrows */] })
                                                // rows follow their item's `id`, or `itemKey: 'slug'`
 apiContainer({ id: 'p', query: '/data/x.json', cache: true, children })   // publishes p.data; no box of its own
+apiContainer({ id: 'p', query: '/data/x.json', runtime: 'server', children }) // read by the page server: still p.data
                                                // loadingSlot: 'p-skeleton' — a child shown until it answers
 form({ id, managedByInteractions: true, flows, children })
 formControl({ name: 'email', label: 'Email', subType: 'email' })          // select: options: [{ label, value }]
@@ -64,7 +65,7 @@ container({ id: 'hero', class: [card, { opacity: '0.5' }] });  // …plus one th
 container({ css: { padding: '8px' } });                        // rules of its own — never with `class`
 ```
 
-Breakpoints: `desktop` (base), `tablet` (48–64rem), `mobile` (<48rem), `compact` (tablet AND mobile). Each inherits
+Breakpoints: `desktop` (base), `tablet` (48–64rem), `mobile` (≤48rem), `compact` (tablet AND mobile). Each inherits
 from `desktop` alone. States: `hover`, `focus`, `focus-visible`, `active`, `disabled`…. An ancestor's state:
 `ancestors: { [card.name]: { states: { hover: { … } } } }`.
 
@@ -87,7 +88,8 @@ visible: false                                                 // hidden until a
 
 Inside a list row: `rows.item` in a binding, `{{ list_rows.item.x }}` in a template or an attribute,
 `list_rows.index` is a number from 0. A provider's source in a template is `apiContainer_p`… —
-spelled in full, as the element publishes it. Globals: `state`, `navigation` (`routeParams`, `queryParams`),
+spelled in full, as the element publishes it; an id with a `-` keeps it (`list_study-plans`: a minus takes spaces,
+`a - b`). Globals: `state`, `navigation` (`routeParams`, `queryParams`),
 `auth`, `variables`, `computed`, `flags`, `theme`, `host`.
 
 ## Flows

package/skills/plitzi-authoring/SKILL.md

@@ -61,7 +61,7 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
 1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
    namespace for the whole space — layouts and every page share it — so a helper that runs more than once builds inside
    `scope('promos', ref => …)`: every id in it is prefixed (`promos-panel`), and `ref('slides')` names one in full. An `id` is the element's name in the
-   space (`data-id` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
+   space (`data-plitzi-el` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
 2. **Share with classes, layouts and components, never with copies.** A look used twice is a `styles()` class.
    Chrome shown on several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A block
    placed many times with different content — a product card, a testimonial — is a **component** placed with
@@ -91,11 +91,12 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
    checked from the first commit.
 7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
    a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
-8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (below 48rem) each inherit only from `desktop`; a rule
+8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (up to 48rem) each inherit only from `desktop`; a rule
    meant for both is written under `compact`.
 9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
    an empty state, not a placeholder figure. With no backend, the data is JSON the project serves
    (`public/data/*.json`) read by an `apiContainer` — see [data and visibility](reference/data-and-visibility.md).
+   `public/` is public: never a secret there.
 10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
     `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
 11. **A switch is named for how it leaves its default.** `toggleState` turns a key nobody has set yet ON, so a key
@@ -121,6 +122,8 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | --- | --- |
 | Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](recipes/show-data.ts) |
 | Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](recipes/typed-data.ts) |
+| Data read by the page server (`--mode server`) | [recipes/server-data.ts](recipes/server-data.ts) |
+| An accordion, one answer open at a time | [recipes/accordion.ts](recipes/accordion.ts) |
 | Filter and sort a list from a select | [recipes/filter-a-list.ts](recipes/filter-a-list.ts) |
 | A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](recipes/detail-page.ts) |
 | Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](recipes/link-to-a-section.ts) |

package/skills/plitzi-authoring/recipes/accordion.ts

@@ -0,0 +1,58 @@
+/**
+ * An accordion — questions whose answers open one at a time — written once and mapped over the questions: the open one
+ * is a key in `state`, and each question reads it the same way. The button says whether its answer is open
+ * (`ariaExpanded`) and which panel it opens (`controls`, by the panel's id), so a screen reader follows it; the panel is
+ * revealed by the state, so it starts hidden.
+ */
+import { bindTemplate, button, container, onClick, paragraph, setState, styles } from '@plitzi/sdk-authoring';
+
+import type { ElementSpec, SpaceSpec } from '@plitzi/sdk-authoring';
+
+const QUESTIONS = [
+  { id: 'shipping', question: 'How long does shipping take?', answer: 'Three working days, anywhere in Europe.' },
+  { id: 'returns', question: 'Can I return an order?', answer: 'Within thirty days, unopened, at no cost.' },
+  { id: 'warranty', question: 'Is there a warranty?', answer: 'Two years on every product we sell.' }
+];
+
+const question = styles('faq-question', {
+  css: {
+    display: 'flex',
+    'justify-content': 'space-between',
+    width: '100%',
+    padding: '16px 0px',
+    border: 'none',
+    'background-color': 'transparent',
+    'font-size': '16px',
+    'font-weight': '600',
+    cursor: 'pointer'
+  },
+  states: { 'focus-visible': { outline: '2px solid currentColor', 'outline-offset': '2px' } }
+});
+
+const answer = styles('faq-answer', { 'padding-bottom': '16px', margin: '0px' });
+
+/** One question: the button that opens it — closing the one open, or this one again — and the answer it opens. */
+const faqItem = ({ id, question: words, answer: text }: (typeof QUESTIONS)[number]): ElementSpec[] => [
+  button({
+    id: `${id}-question`,
+    content: words,
+    class: question,
+    // Named by the panel's id: authoring gives the panel the anchor the page needs for `aria-controls`.
+    controls: `${id}-answer`,
+    ariaExpanded: false,
+    bind: [bindTemplate('ariaExpanded', 'state.faq', `{{ source == '${id}' }}`, { returns: 'value' })],
+    flows: [[onClick(), setState({ key: 'faq', type: 'text', value: `{{ state.faq == '${id}' ? '' : '${id}' }}` })]]
+  }),
+  // Revealed by the state, so it starts hidden: nothing flashes open before the page knows which one is.
+  container({
+    id: `${id}-answer`,
+    visible: { source: 'state.faq', template: `{{ source == '${id}' }}` },
+    children: [paragraph({ content: text, class: answer })]
+  })
+];
+
+export const recipe: SpaceSpec = {
+  name: 'Questions',
+  permanentUrl: 'questions',
+  pages: [{ id: 'home', name: 'Home', slug: '', body: QUESTIONS.flatMap(faqItem) }]
+};

package/skills/plitzi-authoring/recipes/link-to-a-section.ts

@@ -1,6 +1,6 @@
 /**
  * Link to a section: the section carries an `anchor` — its id in the page; an element's `id` is only its name in the
- * space, `data-id` in the DOM — and a link's `hash` lands on it, from any page, even when the section renders late.
+ * space, `data-plitzi-el` in the DOM — and a link's `hash` lands on it, from any page, even when the section renders late.
  */
 import { container, heading, link, text } from '@plitzi/sdk-authoring';
 

package/skills/plitzi-authoring/recipes/server-data.ts

@@ -0,0 +1,65 @@
+/**
+ * Data in a server project (`create --mode server`): a JSON file the project serves (`public/data/plans.json`), read
+ * by the page server before it answers — so the page arrives with the plans in its HTML, their anchors in place, and
+ * nothing to fetch once the browser has it.
+ *
+ * - `runtime: 'server'` on the provider is the whole switch: server data is on unless a space turns it off.
+ * - The answer is read exactly as in the browser — `plans.data.…` — so moving a provider between runtimes changes no
+ *   binding.
+ * - The page server resolves what a page and its layouts hold, never inside a component: the provider stays on the page
+ *   and each row reaches the card component as a prop.
+ * - `mockData` is what the builder shows while editing; the running page always reads the file.
+ */
+import { apiContainer, heading, list, listItem, styles, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const grid = styles('plan-grid', {
+  display: 'grid',
+  'grid-template-columns': 'repeat(auto-fill, minmax(220px, 1fr))',
+  gap: '16px',
+  margin: '0px',
+  padding: '0px'
+});
+
+const card = styles('plan-card', { padding: '16px', 'border-radius': '12px', 'background-color': 'var(--card)' });
+
+export const recipe: SpaceSpec = {
+  name: 'Pricing',
+  permanentUrl: 'pricing',
+  variables: { color: { card: { light: '#ffffff', dark: '#16161d', default: '#ffffff' } } },
+  components: [
+    {
+      id: 'plan-card',
+      props: { item: { type: 'json', description: 'The plan: name and price' } },
+      // The row of the list: an `<li>` reading the plan it was handed.
+      root: listItem({
+        id: 'plan-item',
+        class: card,
+        children: [heading({ subType: 'h3', from: 'props.item.name' }), text({ from: 'props.item.price' })]
+      })
+    }
+  ],
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: 'plans',
+          query: '/data/plans.json',
+          runtime: 'server',
+          mockData: { plans: [{ name: 'Starter', price: '$0' }] },
+          children: [
+            // `plans.data.plans` — the file's `plans` — in either runtime.
+            list({ id: 'plan-list', class: grid, items: 'plans.data.plans', row: 'plan-card' }),
+            text('No plans yet.', {
+              visible: { source: 'plans.data.plans', template: '{{ source is defined and source|length == 0 }}' }
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/style-a-page.ts

@@ -10,7 +10,7 @@ import type { SpaceSpec } from '@plitzi/sdk-authoring';
 const card = styles('card', {
   css: {
     desktop: { display: 'flex', 'flex-direction': 'column', gap: '8px', padding: '24px', 'border-radius': '16px' },
-    // Tablet (48–64rem) and mobile (below 48rem) each inherit from desktop alone: `compact` is both.
+    // Tablet (48–64rem) and mobile (up to 48rem) each inherit from desktop alone: `compact` is both.
     compact: { padding: '16px' }
   },
   states: { hover: { 'border-color': 'var(--primary)' } }

package/skills/plitzi-authoring/reference/accessibility.md

@@ -4,7 +4,8 @@ A screen reader and a browser agent (Claude in Chrome) read a page the same way.
 tree** the browser builds from the markup, where every control is a role and a name. If a control has no name, or a
 click sits on a box that is not a control, those readers can't find it, even though the page looks fine. The linter
 warns about each case below (`control-without-name`, `image-without-alt`, `click-on-static-element`,
-`heading-level-skipped`, `label-ignored`). Fix them the same way you fix any other warning.
+`dropdown-without-control`, `heading-level-skipped`, `label-ignored`, `control-in-decorative`, `embed-without-title`,
+`controls-no-anchor`). Fix them the same way you fix any other warning.
 
 ## Controls have words
 
@@ -75,7 +76,10 @@ button({ content: 'Grid', bind: { ariaPressed: 'computed.gridOn' }, class: chip
 button({ content: 'Menu', bind: { ariaExpanded: 'state.menuOpen' }, flows: [[onClick(), toggleState({ key: 'menuOpen' })]] })
 ```
 
-An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both.
+An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both. A button that
+opens a panel also names it — `controls: 'menu-panel'`, the panel's id (authoring gives the panel the anchor
+`aria-controls` needs; [recipes/accordion.ts](../recipes/accordion.ts)). Words that change while somebody is on the page
+— a count, a total, a status — sit in `container({ live: 'polite', … })`, so a screen reader says them when they change.
 
 ## The page has an outline
 

package/skills/plitzi-authoring/reference/authoring-errors.md

@@ -59,6 +59,7 @@ The space is not written until these are fixed.
 | `computed-not-template` | a computed value that is not a template | `'{{ state.x * 2 }}'` |
 | `computed-reads-element` | a computed value reading an element's source — no element is around the whole space | compute it from the globals and the variables, or bind it on the element |
 | `computed-unknown` | a computed value read before it is declared, or never declared | declare it in `computed`, above the one that reads it |
+| `controls-unknown` | a button's `controls` naming no element of the space | the id of the element it shows and hides: `controls: 'faq-answer'` |
 | `css-property-twice` | one property written twice in a rule set — `paddingTop` beside `'padding-top'` — so one would silently win | keep one |
 | `css-property-unknown` | a CSS property that does not exist | the property it suggests; a custom property starts with `--` |
 | `css-value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
@@ -84,7 +85,7 @@ The space is not written until these are fixed.
 | `global-callback-undeclared` | a global-callback step builder naming an action no source declares | one of the actions it lists |
 | `id-invalid` | an id a binding, a template or a test cannot name | a letter first, then letters, digits, `-` and `_`: `'hero-title'` |
 | `id-shadows-global` | an element named like a global data source (`state`, `navigation`, `auth`…) | another id |
-| `id-taken` | two elements with one id — ids are one namespace for the whole space | wrap what a helper builds in `scope('promos', ref => …)`: every id inside is prefixed, `ref('slides')` names one |
+| `id-taken` | two elements with one id — ids are one namespace for the whole space | a name taken by a page or a layout: a name of its own; a helper called twice: `scope('promos', ref => …)`, every id inside prefixed |
 | `layout-slot-unknown` | a layout `slot` that is not an element inside that layout | the id of the element in the shell where the body goes |
 | `layout-undeclared` | a page or a layout inside a layout the space does not declare | the layout's id, or declare it in `layouts` |
 | `list-items-ignored` | a list whose items nothing reads — `source: 'none'` renders its children once | `source: 'controlled'` |
@@ -109,6 +110,7 @@ The space is not written until these are fixed.
 | `prop-unknown` | a prop the component does not declare, handed in or read | the prop it suggests, or declare it: `props: { name: { type: 'text' } }` |
 | `prop-value` | a prop handed in with a value its declaration does not take | a value of the declared type, or one of its options |
 | `props-outside-component` | `props.x` read outside a component | read the source it would have come from |
+| `quiet-unknown` | an element's `quiet` naming something that is not a suggestion's code — a problem is never quieted | the code of the suggestion it was offered: `quiet: ['repeated-shape']` |
 | `redirect-target-unknown` | a page that sends visitors it is not for to a page the space does not have | a page's id or slug (`''` is the home page), or a full URL |
 | `row-and-children` | a list with a `row` and `children` — the row is what it renders | one of the two |
 | `row-component` | a list's `row` naming a component the space does not declare, or one with no prop to take the row | a declared component with an `item` prop — or a single prop — for the row |
@@ -117,6 +119,7 @@ The space is not written until these are fixed.
 | `rule-set-mixed` | a style that writes its rules beside `states`, `variants` or `ancestors` instead of under `css` | `{ css: { desktop: { … } }, states: { hover: { … } } }` — the rules under `css`, each of the others beside it |
 | `selector-invalid` | a `selector` that is not a CSS class name | letters, digits, `-` and `_` |
 | `selector-taken` | a `selector` that is a declared class, or another element's | `class` to share rules; a selector of an element's own is its alone |
+| `server-provider-in-component` | a `runtime: 'server'` element inside a component: the page server resolves a page's and its layouts', never a component's | put the provider on the page, around the instance, and hand the component its rows as a prop |
 | `setting-misplaced` | `settings.computed` or `settings.channels` written inside `settings` | `computed` and `channels` at the top of the space |
 | `slot-children` | children handed to an instance outside its slots | `children: { slotName: [ … ] }`; a component with no slots takes no children |
 | `slot-unknown` | a component slot that is not an element of its tree | the id of an element inside the component — usually an empty container |
@@ -161,6 +164,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `condition-starts-visible` | a computed visibility that shows until its data answers | `visible: { source, template }` |
 | `control-in-decorative` | a control inside a `decorative` container — Tab lands on something nothing announces | move it out of the illustration |
 | `control-without-name` | a button or a link with no words, or a field nothing names | `title` on the button, `label` on the link, `label` (with `hideLabel: true`) on the field |
+| `controls-no-anchor` | a button's `controls` naming no anchor — `aria-controls` points at nothing | an `anchor` on the element it shows and hides, and `controls` naming it |
 | `default-content-beside-children` | a button printing its default "Button" beside its children | `content: ''` |
 | `dropdown-without-control` | a dropdown opened from a box or an icon — no keyboard opens it | a `button` as what opens it (`title` if it is only an icon) |
 | `embed-without-title` | an `embed` with no `title` — a frame a screen reader cannot describe | say what it shows in `title` |
@@ -178,11 +182,12 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `overlay-never-opened` | a modal or a dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
 | `overlay-starts-open` | a modal or a dialog open when the page loads | `visible: false`, opened by `openModal` |
 | `painted-state-without-keep-state` | `paintedState` without `keepState` — nothing is kept for the server to draw with | `settings.keepState: true`, or remove `paintedState` |
+| `path-not-in-data` | a binding onto a provider whose answer the author could read (`data`), through a path that answer does not have | the path the message lists the keys for — `p.data.plans`, not `p.data.landing.plans` |
 | `plugin-attribute-reserved` | a plugin attribute named as one of the element’s own fields — a factory never hands it to the plugin | rename it in the plugin (`variant` → `kind`) |
 | `provider-without-source` | an `apiContainer` that asks nothing | a `query` (or `action`, `connector`, `resource`) |
 | `route-param-undeclared` | `navigation.routeParams.x` read on a page whose slug has no `:x` — always empty | add `:x` to the slug, or read `navigation.queryParams.x` |
-| `server-data-without-rsc` | a `runtime: 'server'` provider with a `connector` or `action` in a space that does not turn server data on | `rsc: { enabled: true }` on the space |
-| `span-holds-block` | a `container({ subType: 'span' })` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words: a `text` with `display: inline` in its class |
+| `server-data-without-rsc` | a `runtime: 'server'` provider — `connector`, `action` or `query` — in a space that turns server data off (`rsc: { enabled: false }`) | drop `rsc: { enabled: false }`: server data is on unless a space turns it off |
+| `span-holds-block` | a `container` with `subType: 'span'` or `'p'` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words and inline elements: a `text`, a `link` |
 | `state-key-has-runtime-prefix` | a state key written with `runtime.state.` in front — the state callbacks already write below it | `key: 'cart'`, not `'runtime.state.cart'` |
 | `state-toggled-in-branches` | two `setState` of one key, each under a `when` on that key — the second flips back what the first wrote | `toggleState({ key })`; for something shown by default, a key named for hiding it |
 | `STYLE_WITHOUT_TAG` | style on a provider that renders no element of its own | `subType: 'div'` on the provider, or style its parent |

package/skills/plitzi-authoring/reference/colours-and-motion.md

@@ -20,7 +20,9 @@ Only `opacity` and `transform` (`translate`, `scale`, `rotate`) animate off the
 the page hydrates and on a slow phone. Everything else repaints, or lays the page out again, on every frame.
 
 - **A preset first:** `motion: { enter: 'fade-up', on: 'view' }` on any element, `stagger: 60` for children one by one,
-  `loop: 'float'` — played by the SDK, cheap and stilled for reduced motion by construction (motion.md lists them).
+  `loop: 'float'` — played by the SDK, cheap and stilled for reduced motion by construction (`npx plitzi explain motion` lists them; `MOTION_ENTERS` and `MOTION_LOOPS` in code).
+  `on: 'view'` plays once, the first time the element comes into view, and it stays; `on: 'scroll'` follows the scroll
+  both ways — it goes back out as the reader scrolls up past it — so keep it for an effect that is about the scroll.
 
 - **Slide, grow, fade** with `transform` and `opacity` — never `left`, `top`, `width`, `height` or `margin`. Something
   that travels across a box is `transform: translate(%)` on an element as large as the box.
@@ -31,6 +33,8 @@ the page hydrates and on a slow phone. Everything else repaints, or lays the pag
 - **Main-thread decoration waits for hydration:** a sweep on a custom property, a `background-position` seam — start
   it paused, run it once the SDK's root says `data-hydrated`:
   `'.glow { animation: glow 8s linear infinite paused; } [data-hydrated] .glow { animation-play-state: running; }'`.
+  That is for loops. An entrance of your own that plays once — `transform`/`opacity` only — plays from the first paint
+  with `backwards`, as the presets do: gated on `[data-hydrated]` it jumps when the page goes live.
 - **Entrances:** `opacity` + a small `translateY`, under ~600ms, staggered by tens of ms.
 - **One ambient loop per screen**, slow — not one per card. `infinite` runs on every visitor's battery for as long
   as the page is open.

package/skills/plitzi-authoring/reference/data-and-visibility.md

@@ -50,7 +50,7 @@ text('', { bind: [bindTemplate('content', 'computed.level', 'Level {{ source }}'
 
 A computed value reads the globals (`state`, `auth`, `navigation`, `variables`, `theme`, `host`) and the ones declared
 above it — not an element's source: bind that on the element. One `{{ expression }}` gives its value (a number, a
-list); anything else gives text. `authorSpace` refuses a name read before it is declared, or never.
+list); anything else gives text. `authorSpace` refuses a name read before it is declared.
 
 ## Providers
 
@@ -61,12 +61,16 @@ apiContainer({ id: 'board', runtime: 'server', action: 'queue-board' })
 
 - A provider's source is readable by its **descendants** only. Wrap what reads it; a sibling cannot see it.
 - It publishes `data` plus `isLoading`, `isEmpty`, `hasError`, `errorMessage` — bind a state to those, not to guesses.
+  A `query`'s body is `data` in **either runtime** (`p.data.plans`), so moving a provider to the server changes no
+  binding. A connector publishes `records` (or `record`), an action its output.
   `isEmpty` reads what arrived: a `query`'s body when it is missing, `null`, `''`, `[]` or `{}`; a connector list by
   its `records`; a `singleRecord` provider by its `record`. It is also true before the first answer, so pair it with
   `not isLoading` for an empty state.
 - A query that depends on state is a binding on `query`; it answers `''` (and fetches nothing) until the state exists:
   `"{{ source ? apiUrl ~ '/workspaces/' ~ source ~ '/stats' : '' }}"` with `source: 'state.workspace.id'`.
-- A space with any `runtime: 'server'` provider needs `rsc: { enabled: true }`.
+- `runtime: 'server'` is resolved by the page server — server data is on unless a space says `rsc: { enabled: false }`.
+  Only a page and its layouts are resolved — never inside a component: keep the provider on the page and hand the
+  component its rows as a prop ([recipes/server-data.ts](../recipes/server-data.ts)).
 
 ### Typed by a sample
 
@@ -81,11 +85,15 @@ An offline project (`offlineMode`) still never invents data: the content lives i
 backend, so swapping the file for a real endpoint later changes one `query`. `mockData` is what the BUILDER shows while
 editing; it is not a data source for the running page. Say on the page that demo content is demo content.
 
-**In a server project (`create --mode server`), put the provider on the server** — `runtime: 'server'`, with
-`rsc: { enabled: true }` on the space — and the page server reads the file from `public/` itself: the page arrives
-with those sections in it (and their anchors in place) instead of fetching them once the browser has the page. A
-browser provider leaves the server-rendered HTML without them. A `query` with `{{tokens}}` is still read in the
-browser, against the visitor's route and state.
+**`public/` is on the internet.** Every file in it is served to anyone who asks, as it is, once the project is deployed —
+and so is everything the space's documents hold (pages, variables, attributes, `mockData`): they reach every visitor's
+browser. Never put a secret, a key, a private document or data only some visitors may read in either. A secret is a
+credential that an action or a connector names; data for some visitors only comes from a server action whose `access`
+checks who is asking, or a `runtime: 'server'` provider behind one.
+
+**In a server project (`create --mode server`), put the provider on the server** — `runtime: 'server'` — and the page
+server reads the file from `public/` itself: the page arrives with those sections (and their anchors) in it. A `query`
+with `{{tokens}}` is still read in the browser, against the visitor's route and state.
 
 ### Live, cached, refreshed
 
@@ -116,7 +124,7 @@ modalContainer({ visible: false, … })           // starts hidden; a flow opens
 | The logic… | Example | Write |
 | --- | --- | --- |
 | reveals it: hidden until the data says so | empty state, "get started", admin-only panel, error note | `visible: 'src'`, or `visible: false` + a computed binding |
-| hides it: shown unless a flag says otherwise | sidebar labels until the sidebar is folded, a banner until dismissed | a binding with no `visible`; an absent flag must leave it shown |
+| hides it: shown unless a flag says otherwise | sidebar labels until the sidebar is folded, a banner until dismissed | `visible: '!state.folded'` — on screen while nobody has set it |
 
 `visible` starts the element **hidden**, and it appears when its data says so. A revealing condition you have to
 compute is `visible: { source, template }` — it starts hidden too, and the template's value is read as a yes or a
@@ -135,17 +143,19 @@ container({
 
 Rules for a condition's template:
 
-- **A revealing condition starts hidden** — `visible: { source, template }` does that for you. A visibility binding
-  written by hand in `bind` keeps the element on screen until it answers — right for a hiding flag, a flash for a
-  condition on data. `authorSpace` warns `condition-starts-visible` when a computed one on a provider starts on screen.
+- **A visibility binding written by hand in `bind` keeps the element on screen until it answers** — a flash for a
+  condition on data (`condition-starts-visible` warns); `visible` starts it hidden.
 - **A hidden element stays in the DOM** (`plitzi-component--hidden`), its subtree mounted. `loadStrategy: 'visible'`
   mounts the subtree only while it is shown, and `'lazy'` from the first time it is shown (modals do that already).
   Use it on heavy panels that are usually hidden; leave the default on what is usually on screen.
-- **`'true'` shows, `'false'` hides, `''` writes nothing** and leaves the element as it is. Visibility hides only on
-  an explicit false.
-- **Answer what "not known yet" should mean.** For a revealing condition that is `'false'` (`source ? … : 'false'`);
-  for a hiding flag it is `''` — nothing written, the default stays. A sidebar that answered `'false'` for a
-  "folded" state nobody had set yet hid every label of the menu for everybody.
+- **Once its source has a value, the answer is a yes or a no**: `false`, `0`, `''` and an empty list hide it,
+  anything else shows it.
+- **While its source has no value, only a definite answer is written.** `!source` is `true` — shown; a template's
+  `'true'` or `'false'` is written as it says. A plain source, or a template that answers nothing (`''`), writes
+  nothing: the element stays as it started — hidden for `visible`, shown for a binding written by hand.
+- **So a hiding flag is `visible: '!state.folded'`** (or a binding with no `visible`): on screen before anybody has set
+  it. A condition that answers "not known yet" with `'false'` from a value that IS there — a "folded" read off
+  something always set — hid every label of a sidebar for everybody.
 - **Hide the element itself.** Never wrap it in a container that is shown while the inner one is hidden: an empty
   visible wrapper still takes a slot in its parent's `gap`, and leaves a hole in the page.
 

package/skills/plitzi-authoring/reference/efficiency.md

@@ -19,6 +19,15 @@ const { warnings, suggestions } = authorSpace(space);
 is a bug to fix; a suggestion is a shorter way to the same page — take it unless you have a reason not to, and the
 reason is usually that the copies are about to diverge. `npx @plitzi/cli explain repeated-on-pages` explains any code.
 
+Left on purpose, say so where it is written — `quiet` on an element it is about, and it is not offered again, in the
+builder or over MCP either (it is kept in the document):
+
+```ts
+const includes = (words: string) => container({ class: row, quiet: ['repeated-shape'], children: [tick, text(words)] });
+```
+
+Only a suggestion's code: a problem is never quieted (`quiet-unknown`).
+
 ## The long way, and the short one
 
 | Written the long way | The short way | Suggestion |
@@ -26,7 +35,7 @@ reason is usually that the copies are about to diverge. `npx @plitzi/cli explain
 | The same header, footer or sidebar in every page | A **layout** holding it once; each page names it (`layout: { id, slot }`) — [layouts](layouts.md) | `repeated-on-pages` |
 | A header copied per page so one link can be styled "active" | The link marks its own page: `states: { current: { … } }` on its class; `activeOn` for an entry lit on several pages | `repeated-on-pages` |
 | The same card, row or tile written again with other words | A **component** with props, placed with `component(id, { props })` — [components](components.md) | `repeated-shape` |
-| Rows of data written one by one, side by side | One `list` over the rows — `items: [ … ]` fixed, or bound to a source — with its row written once — [lists](lists.md). Data is the test: three cards a person rewords on the canvas read better as three cards | `repeated-shape` |
+| Rows of data written one by one, side by side | One `list` over the rows — `items: [ … ]` fixed, or bound to a source — with its row written once — [lists](lists.md). Data is the test: three cards a person rewords on the canvas read better as three cards. Copies that read different sources or write different state keys are controls written alike, and not offered | `repeated-shape` |
 | `button({ children: [text('Save')] })`, `link({ children: [text('Docs'), fontAwesome({ icon })] })` | `button({ content: 'Save' })`, `link({ href, content: 'Docs', icon, iconPlacement: 'after' })` — the icon's class on the `icon` slot; what the text's class adds (`whiteSpace: 'nowrap'`) moves to the box's class — never the class itself, whose `inherit` would then point past the box and whose `pointerEvents: 'none'` would switch the box off | `content-attribute` |
 | `.card:hover { … }`, `.card .icon { … }` in `customCss` | The class's own `states` and `ancestors` | `custom-css-class` |
 | A reduced-motion reset, or rules showing one icon of the theme toggle, in `customCss` | Nothing: the SDK does both for every space | `custom-css-sdk-default` |

package/skills/plitzi-authoring/reference/elements-and-styles.md

@@ -25,7 +25,7 @@ container([hero, grid])             // an array is the children
 | `visible` | a condition (`'src'`, `'!src'`, `{ source, template }`), or `false` to start hidden |
 | `flows` | what happens on click, on submit, on load |
 | `runtime` | `'server'` resolves this provider's data on the server |
-| `loadStrategy` | when the contents mount relative to visibility: `eager` (default), `lazy`, `visible` |
+| `loadStrategy` | when the contents mount relative to visibility: `eager`, `lazy`, `visible`. Left out, the type decides — `eager`, `lazy` for a modal or a dialog |
 | `children` | the tree |
 | `meta` | `meta.label` is the element's name in the builder's tree |
 
@@ -44,7 +44,7 @@ another link — make the card the link, or the button, not both.
 link to the page being shown is `aria-current="page"`; its class's `current` state styles it, so one header in a
 layout lights the right item everywhere.
 
-**An element's `id` is not its HTML id.** It reaches the DOM as `data-id`. For a section a URL can land on, give it
+**An element's `id` is not its HTML id.** It reaches the DOM as `data-plitzi-el`. For a section a URL can land on, give it
 an `anchor` (`anchor: 'plans'` → `id="plans"`: lowercase, digits, `-`) and link to it with `hash`:
 `link({ href: 'home', hash: 'plans' })` goes to `/#plans` and scrolls there, waiting for a section that renders once
 its data arrives. One anchor per page, layouts included; never inside a list row or a component, which would repeat
@@ -78,12 +78,8 @@ A type this SDK does not ship — a plugin — is authored the same way: `define
 
 **What a type takes, answered by the package** instead of the 7,000-line `.d.ts`: every catalogue is exported, keyed by
 type — `elementCatalog` (what it is for), `elementDefaultAttributes`, `elementAttributeNames`, `elementTriggers`,
-`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS`. One line
-prints any of them:
-
-```bash
-node --input-type=module -e "import * as a from '@plitzi/sdk-authoring'; const t = 'formControl'; console.log({ attributes: a.elementDefaultAttributes[t], triggers: a.elementTriggers[t], slots: a.elementSlots[t] })"
-```
+`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS` — and
+`npx @plitzi/cli explain formControl` prints them for one type.
 
 ## CSS
 
@@ -92,7 +88,7 @@ kebab-case or camelCase (`paddingTop`, as a React style object), and a bare numb
 `fontWeight: 800`, `opacity: 0.5` stay numbers). A property outside the vocabulary is refused.
 
 - `column(gap, extra?)`, `row(gap, extra?)`, `grid(columns, gap, extra?)` for the three layouts every space repeats.
-- **Breakpoints are ranges, not a cascade.** `tablet` is 48–64rem, `mobile` below 48rem, and each inherits only from
+- **Breakpoints are ranges, not a cascade.** `tablet` is 48–64rem, `mobile` up to 48rem, and each inherits only from
   `desktop` — a rule for `tablet` never reaches a phone (`authorSpace` warns `tablet-rule-skips-mobile`). A rule for
   everything narrower than a desktop is `compact`, written to both: `css: { desktop: { … }, compact: { 'grid-template-columns':
   '1fr' }, mobile: { gap: '8px' } }` — what `tablet` or `mobile` say for themselves wins.

package/skills/plitzi-authoring/reference/lists.md

@@ -12,7 +12,7 @@ list({ id: 'games', items: 'catalog.data.games', row: r => listItem({ children:
 list({ id: 'plans', items: ['Free', 'Pro'], children: [listItem({ children: [text({ from: 'plans.item' })] })] })  // fixed
 ```
 
-`items` makes a list controlled: an array of its own, or the source its rows come from. `row` is what it renders once
+`items` (or `from`) makes a list controlled: an array of its own, or the source its rows come from. `row` is what it renders once
 per item — a component's id (placed with the row bound to its `item` prop, or its only prop), or a function handed the
 row's names: `r.item` and `r.index` for a binding or `from`, `r.inTemplate.item` for a template
 (`` `/games/{{ ${r.inTemplate.item}.slug }}` ``). A function needs the list's `id`, which names those sources. With

package/skills/plitzi-authoring/reference/review-checklist.md

@@ -7,7 +7,8 @@ of it; each line is something that has shipped broken before.
 
 - [ ] `authorSpace` returns **zero warnings**. Each one is written code that will not do what it says.
 - [ ] Every **suggestion** is taken, or left for a reason you can say (the copies are about to diverge; three cards a
-      person rewords on the canvas). The ones your change opened up first — [efficiency.md](efficiency.md).
+      person rewords on the canvas) — and then quieted where it is written, `quiet: ['repeated-shape']`, so it stops
+      burying the ones that matter. The ones your change opened up first — [efficiency.md](efficiency.md).
 - [ ] No console errors on any page you touched.
 
 ## Nothing flashes, nothing jumps
@@ -39,7 +40,8 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
       a `label` (`hideLabel: true` when the design shows what it is).
 - [ ] Every image has an `alt` saying what it shows, or `decorative: true`.
 - [ ] Every click is on a `button` or a `link`; the whole page can be worked from the keyboard.
-- [ ] A toggle binds `ariaPressed`, a button that opens something `ariaExpanded`.
+- [ ] A toggle binds `ariaPressed`, a button that opens something `ariaExpanded` and names it with `controls`; words
+      that change on their own are in a `live` container.
 - [ ] Headings step down one level at a time; parts of the page a person jumps to are landmarks (`nav`, `main`, a
       labelled `section`).
 - [ ] What a canvas or a plugin draws is also there as elements, with a visible way to reach them.
@@ -66,6 +68,16 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
 - [ ] What only an administrator may read is shown only to administrators — and the check is a real boolean, not
       a template left as text.
 
+## Nothing left behind
+
+- [ ] Nothing you made and no longer use is still there — a page, a component, a class, a token, a data file, an
+      import, a plugin folder. No commented-out code, no debug `console.log`, no copy of a file kept "just in case".
+- [ ] Scratch work — a one-off script, a dump, a picture to look at — went in `tmp/` (never committed) and is gone from
+      everywhere else.
+- [ ] Nothing secret, and nothing only some visitors may read, is in `public/` or in the space's documents: both reach
+      every visitor.
+- [ ] `typecheck`, `lint` and `format` are clean.
+
 ## Proven
 
 - [ ] You looked at it: the visual check ran, on the pages you changed, in both themes.

package/skills/plitzi-authoring/reference/snippets-and-export.md

@@ -31,8 +31,8 @@ Never rewrite an exported space by hand. `specFromSpace({ schema, style })` read
 A server action reads back the same way: `actionSpecFromEntry({ id, document })` gives the `defineAction` spec that writes
 it — only when that spec writes the very same document, otherwise `reason` says why and it stays JSON — and
 `actionToSource(spec)` writes the module. For the whole space as a project — pages, actions, functions, the source of
-its plugins and runtime, its files — use `plitzi create --from <space>` (and `plitzi pull` later) rather than exporting
-the parts by hand.
+its plugins and runtime, its files — use `plitzi create --from <space>` (then `plitzi pull` to bring the space's changes in, and
+`plitzi push` to put the project's back) rather than exporting the parts by hand.
 
 For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
 `validateSpace({ schema, style })`.

package/skills/plitzi-authoring/reference/templates.md

@@ -6,7 +6,7 @@ Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}`
 
 | Written in | What is evaluated | What it can read |
 | --- | --- | --- |
-| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value), `sourceTo`, the globals, the variables by bare name, and every source around the element |
+| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value — undefined until it has one: `{{ source|default('…') }}`), `sourceTo` (the attribute's value before it), the globals, the variables by bare name, and every source around the element |
 | a flow step's params | the whole template | the trigger's payload and earlier steps by name, the globals, sources around the element |
 | an ATTRIBUTE (`href`, `src`, `content`…) | only `{{ name }}` tokens (a filter after the name is allowed) | the globals, the variables and the page's route params by bare name (`{{ apiUrl }}`, `{{ slug }}`), and every source around the element (`{{ list_games.item.slug }}`) |
 

package/skills/plitzi-authoring/reference/testing.md

@@ -87,7 +87,7 @@ One code on one element; it comes back in `warnings` with the reason, and an ent
 
 ## What to check
 
-- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (below 48rem); `colorScheme: 'dark'` as well
+- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (up to 48rem); `colorScheme: 'dark'` as well
   as light.
 - **No horizontal scroll on a phone.** A column child grows to its content unless its parent stretches it; a code
   block or a wide table is what finds out.