@plitzi/sdk-server 0.38.3 → 0.38.5

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.
@@ -58,7 +62,9 @@ variables: {
 - **`tokens(variables)`** names them for a rule: declare the variables once (`satisfies SpaceSpec['variables']`), hand
   the same object to the space, and `const t = tokens(variables)` gives `t.primary === 'var(--primary)'` — a name the
   space does not declare is a type error. A `var(--x)` written by hand that nothing declares is warned
-  `unknown-variable`; one that may be missing on purpose takes a fallback, `var(--x, 8px)`.
+  `unknown-variable`; one that may be missing on purpose takes a fallback, `var(--x, 8px)`. The other way round, a token
+  nothing reads is suggested `unused-token`, and a class painted from the palette that types one of its colours out
+  `literal-colour` — see [efficiency](efficiency.md#what-it-declares-and-never-uses).
 - Choose each value against its own background: a colour picked on white is not the same colour on near-black.
 - Fixed colours are only for surfaces that are fixed in both themes (a brand panel that is always dark) — and then
   the text on them is fixed too. Theme-following text on a fixed background is the bug.

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

@@ -13,8 +13,8 @@ text({ bind: [{ to: 'content', source: 'posts.title', when: { … } }] })
 
 `from` binds what the type shows — a text's, heading's, paragraph's or button's `content`, an image's `src`, a link's
 `href`, a list's `items` — and leaves it empty until the data answers. `as` shows it through a template (`source` is
-the value), or a format the space names once in `formats: { price: "{{ source|currency('USD') }}" }` (filters
-`currency` and `percent` are there for exactly this). `bind` is for every other attribute;
+the value), or a format the space names once in `formats: { price: "{{ source|currency('USD') }}" }` (the
+`currency` and `percent` filters). `bind` is for every other attribute;
 `bindTemplate(to, source, template, { category?, returns? })` is the computed attribute — a template over the value
 at `source`. `returns: 'value'` hands over what a single `{{ expression }}` evaluates to instead of its text: a list's
 `items`, a number, a flag (see [lists](lists.md)).
@@ -27,7 +27,8 @@ completed from what the element publishes (`apiContainer_posts`, `list_postList`
 The binding's `source` is completed for you; its template is read as written, so the short name there is refused.
 
 An element re-renders when anything it reads changes: the first part of each binding's `source` and every source its
-templates name. The globals are `variables`, `navigation` (`routeParams`, `queryParams`, `origin`, `currentPageId`),
+templates name. The globals are `variables`, `navigation` (`routeParams`, `queryParams`, `origin`, `currentPageId`,
+`pending` / `pendingLocation` while a link waits for its page's server data),
 `auth` (who is signed in, `status` while that is being found out), `state` (what flows wrote), `theme`
 (`mode`, `resolved`), `host` (the `hostData` an application embedding the space hands the SDK) and `computed` (below).
 
@@ -50,7 +51,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
 
@@ -60,13 +61,22 @@ 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.
+- It publishes its answer 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 publishes its output at the root**:
+  `apiContainer_board.columns`, never `.data.columns` (warned `action-output-path`).
   `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 }`.
+  `"{{ source ? apiUrl ~ '/workspaces/' ~ source ~ '/stats' : '' }}"` with `source: 'state.workspace.id'`. A server
+  provider's bound `input` (`bindTemplate('input', 'state.c', '{{ { country: source } }}', { returns: 'value' })`)
+  asks again on every change; `reloadApi('p', { … })` asks once.
+- `isLoading` is true while it is asked again, in either runtime. A newer ask drops the older one; `cancelApi('p')` is a
+  STOP: what is shown stays.
+- `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
 
@@ -75,17 +85,17 @@ see [typed-sources.md](typed-sources.md).
 
 ### Data in a project with no backend
 
-An offline project (`offlineMode`) still never invents data: the content lives in JSON files the project serves
-(`public/data/games.json`, served in either mode) and a provider reads them like any API — `apiContainer({ id: 'catalog', query:
-'/data/games.json', cache: true, children: [ … ] })`. The page binds to `catalog.data.…` exactly as it would to a live
-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.
+Content lives in JSON files read like any API — `apiContainer({ id: 'catalog', query: '/data/games.json', children:
+[ … ] })` — so a real endpoint later changes one `query`. `mockData` is only what the BUILDER shows. Say demo is demo.
 
-**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.
+- **Server project:** `src/data/games.json` answers `/data/games.json`, read by the server, never served. The provider
+  is `runtime: 'server'` (the page arrives with it); a browser one is refused (`server-data-in-browser`).
+- **No server:** `public/data/`, fetched — public.
+
+**`public/` is on the internet**, and so is everything the space's documents hold (pages, variables, attributes,
+`mockData`) and what a provider reads into a page: never a secret, a key or data only some visitors may read. A secret
+is a credential an action or a connector names; data for some visitors, or fields a page must not carry, comes from a
+server action answering only what is shown, its `access` checking who asks.
 
 ### Live, cached, refreshed
 
@@ -116,7 +126,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 +145,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/drawing.md

@@ -20,3 +20,27 @@ compile — GLSL ES 1.0 wants `196.0`, not `196` — throws a `ShaderError` with
 `[plugin <type> "<id>"] fragment shader failed: …` (`plitzi check` lists it under the console) and `error` says it;
 show the still image meanwhile, as above. `useAnimationFrame(onFrame, { target })` is the same loop for motion that
 is not a canvas.
+
+## Drawing a lot
+
+A canvas with thousands of shapes on it — a whiteboard, a diagram, a map of points — is judged on a slower machine than
+yours: sixty frames a second here says nothing about a four-year-old laptop. What keeps one fast is doing work in
+proportion to what CHANGED, not to what is there:
+
+- **Two layers.** Paint what stands still on one canvas and leave it; clear and draw the one over it every frame, with
+  only what moves: the cursor, the selection, what is being dragged.
+- **Repaint the part that changed.** Something added, edited or removed repaints the area it was and is in, clipped,
+  with whatever reaches into it — not the whole board. A pan moves the picture already painted by whole device pixels
+  and paints the edges it uncovers.
+- **Draw a dragged group once.** Everything picked up moves by the same amount at every step: draw it to a canvas of its
+  own when the drag begins and copy that into place after.
+- **Cache per object, not per frame.** Treat elements as immutable and key what is derived from one — its bounds, its
+  shape, a resolved connector — on the object itself (a `WeakMap`), so nothing is worked out twice for the same thing.
+- **Hand the space outcomes, not motion.** A stroke finished, a selection changed: a trigger each. Firing one at every
+  pointer move runs a flow and renders the page at every pointer move.
+- **Measure with a bench, throttled.** A script that drives the real thing in a browser with the CPU slowed
+  (`Emulation.setCPUThrottlingRate`) and reports script time per frame, not only frames per second — and a test that
+  counts WORK (full repaints, strokes drawn during a drag), which holds on any machine where a timing does not.
+
+Pizarra, the collaborative whiteboard on the platform (`pizarra.plitzi.app`), does all of it on a board of thousands
+of elements.

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

@@ -19,6 +19,16 @@ 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 (a component's instance too:
+`component(id, { quiet })`), 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,13 +36,29 @@ 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` |
 | `.Toastify__toast { font-family: …; border: … }` in `customCss` | `notifications: { font, fontSize, border, shadow, padding, … }` | `custom-css-notifications` |
 | Keyframes animating `width`, `top`, `filter: blur()`, `box-shadow`, a colour in a loop | `opacity` and `transform`; decoration held until `[data-hydrated]` — [motion](colours-and-motion.md) | `heavy-animation` |
 
+## What it declares and never uses
+
+A big space gathers what nothing reads any more: the class kept after the last element wearing it went, the token
+nobody points at, the component no page places — and the colour typed out where its token was meant. Each is one more
+thing the next reader has to check is safe to change. `authorSpace` names them too:
+
+| What it found | What to do | Suggestion |
+| --- | --- | --- |
+| A class in `classes` that no element, binding, flow or other class's `ancestors` names | Remove it — or wear it where it was meant to go | `unused-class` |
+| A token in `variables` that no `var(--…)` reads — not a class, an element, `customCss` nor another token | Remove it, or write it where its colour is typed out | `unused-token` |
+| A component that no page, layout or other component places | Remove it, or place it where it was meant to go | `unused-component` |
+| A colour typed out in a class painted from the palette, equal to a token's light value | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both (dark words on a light chip) | `literal-colour` |
+
+They are read generously, so they are never wrong: a name counts as used wherever it appears as a word, and a class
+written all in literals — a sticker's paper and ink, a swatch — is a palette of its own and not named.
+
 And a few the suggestions do not count, because they cost styles rather than elements:
 
 - **A look used twice is a class**, written once with `styles()`; every element of a TYPE dressed the same way is the

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/flows.md

@@ -31,6 +31,9 @@ same flags, decided on the server. Use the step builders — they fill in where
   key for hiding it (`sidebarCollapsed`).
 - **A trigger fired again while its flow runs is IGNORED** (`skip`, the default — no double submit). For a stream of
   events that must each run, wrap the trigger: `whileRunning('queue', on('onArrival'))` (in order) or `'parallel'`.
+  Where only the newest firing matters — a search as you type — `whileRunning('latest', …)`: the run in progress
+  stops (no further step; its server action or request is cancelled) and the new one runs. With a `delay(450)` first
+  it is a debounce: each firing stops the one still waiting, and only the last gets past the wait.
 - **Each step reads the page as it is when it runs.** A `when` or a `{{ state.x }}` after a `setState` sees the new
   value, and one after a `delay` or a server action sees whatever changed meanwhile. To act on the value from BEFORE
   a write, put the step that reads it first.

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

@@ -113,31 +113,16 @@ this replaces.
 
 ## Pages from a factory
 
-When pages share a shape — a heading, a lede, content, a footer — the shape is a function and each page is its data:
+When pages share a shape — a heading, a lede, content, a footer — the shape is written once and each page is its data,
+with `pageFamily`: it gives every page its id, slug, titles, folder and this layout, and prefixes the ids each body
+gives (see [structure](structure.md#pages-of-one-shape-are-a-family)):
 
 ```ts
-export const docsPage = (id: string, markdownSource: string): PageSpec => {
-  const entry = docsEntry(id);                          // title, slug, lede from nav.ts
-
-  return {
-    id,
-    name: entry.title,
-    slug: entry.slug,
-    seoTitle: `${entry.title} — Docs`,
-    seoDescription: entry.lede,
-    folder: 'docs',
-    layout: { id: 'docs-layout', slot: 'docs-slot' },
-    body: [
-      container({
-        id: `${id}-main`,                                 // prefixed: this function runs once per page
-        class: main,
-        children: [heading(entry.title, { id: `${id}-title`, class: title }), markdown(markdownSource, { id: `${id}-md` }), ...footer(id)]
-      })
-    ]
-  };
-};
-
-export const quickstart = docsPage('docs-quickstart', `## One command …`);
+pages: pageFamily(
+  { folder: 'docs', layout: { id: 'docs-layout', slot: 'docs-slot' }, seoTitle: entry => `${entry.title} — Docs`,
+    body: entry => [container({ id: 'main', class: main, children: [heading({ id: 'title', content: entry.title, class: title }), markdown(entry.source, { id: 'md' })] })] },
+  DOCS   // [{ id: 'docs-quickstart', title, slug, description, source }] — the same list the sidebar reads
+)
 ```
 
 Every page is now its content and nothing else, and every page is guaranteed the same structure.

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/performance.md

@@ -28,8 +28,8 @@ An element renders again when something it READS changes, and only then:
   moment-to-moment state inside a plugin and hand the space the outcome (`onCommit`, `onSelectionChange`), not every
   step of it.
 - **`whileRunning`** decides what a trigger fired again does while its flow runs: `skip` (the default) drops it,
-  `queue` runs it after, `parallel` alongside. A burst of events queued behind a slow request is a burst of renders
-  later.
+  `queue` runs it after, `parallel` alongside, `latest` stops the one running. A burst of events queued behind a slow
+  request is a burst of renders later — for a search, `latest`.
 
 ## What mounts
 

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

@@ -9,13 +9,8 @@ custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best
 
 ## Creating one
 
-The CLI writes it, in the shape Plitzi's own elements are written in:
-
-```bash
-npx @plitzi/cli add plugin seat-picker legend # elements of this project (src/plugins/<Name> in a CLI project)
-npx @plitzi/cli create seat-picker --plugin   # a package of its own, with a preview
-npx @plitzi/cli pack plugin                   # built, with its manifest and the zip the builder takes
-```
+The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli add plugin seat-picker` (a
+package of its own and packing it: the CLI skill).
 
 One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
 `callbacks` it answers to, and the element the builder adds — data only), `Settings.tsx` (its panel in the builder), and
@@ -38,8 +33,7 @@ by the same name, and so does whatever a binding writes — which is what makes
 panel edits for a plugin it has no controls for; from code, write attributes. A `settings` that is not JSON renders
 "Settings Malformed" in the page.
 
-Every prop is optional and has a default: an attribute not authored yet, or a binding whose source has not answered,
-is `undefined`, and a plugin that renders nothing then is a hole in the page.
+Every prop is optional with a default: an attribute not authored yet, or a binding not answered yet, is `undefined`.
 
 ## The component
 
@@ -73,7 +67,36 @@ const stop = state.subscribe(next => save(next));      // called after every cha
 ```
 
 `state` is the current value, `setState` replaces it (or takes an updater), `setStateByKey` writes one key,
-`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once.
+`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once. With the space's `keepState`
+on ([kept state](kept-state.md)), what a plugin writes there — its layout, a choice — is back after a reload too.
+
+## Laying out the space's elements
+
+A plugin that arranges elements — a dock, tabs, a masonry — HOLDS them: they are its children in the space
+(`custom({ renderType: 'dock', children: [feed, tools] })`, or dropped into it in the builder), and the component
+places each in a box of its own, by the id it was authored under:
+
+```tsx
+import { elementChildren } from '@plitzi/plitzi-sdk';
+
+{elementChildren(children).map(({ id, node }) => <section key={id} style={placed[id]}>{node}</section>)}
+```
+
+Never write `style` onto an element the plugin does not render: nothing promises to keep it. Its boxes share one
+stacking context, the plugin's. `useDisplayMode()` names the breakpoint showing — `desktop`, `tablet` or `mobile` — at
+the widths the space's styles use, instead of a width of the plugin's own.
+
+## Its own server code
+
+`plitzi add plugin board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
+under `/fn/plugins/board/`; the component names them, with nothing for the space to wire:
+
+```tsx
+const route = usePluginRoute('board'); // from '@plitzi/plitzi-sdk'
+const url = route('/layout'); // undefined where no server runs code (the canvas)
+```
+
+Its `ctx.kv` is the plugin's own; the space's credentials and channels are not.
 
 ## Talking to other pages
 
@@ -104,13 +127,12 @@ import { useFlag } from '@plitzi/plitzi-sdk';
 const newChart = useFlag('newChart'); // false for a flag the space does not declare
 ```
 
-Gating the whole plugin needs no code: give its element `flag: 'newChart'`. `useFlag` is for a plugin that changes
-inside — a new mode, an extra panel.
+Gating the whole plugin needs no code: give its element `flag: 'newChart'`.
 
 ## Drawing and animating
 
-A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — see
-[drawing](drawing.md).
+A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — and keeping one
+with thousands of shapes fast — see [drawing](drawing.md).
 
 ## Registering
 
@@ -154,6 +176,10 @@ A plugin says what HAPPENED through its events (`onPick`, with the seat in the p
 decide what that means — write `state`, open a modal, call a server action. Prefer that to writing `state` from inside
 the component: the flow is visible in the space, the builder shows it, and the same act can come from a button too.
 
+- A param declared `number` or `boolean` arrives as one, written or bound; any other arrives as written.
+- To act when another element appears, `useElementVisible('tools')` (`@plitzi/plitzi-sdk`) — never watch classes.
+- A name for screen readers is a prop of its own: declare `label`, write it as the root's `aria-label`.
+
 ## Behaving in the builder
 
 The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
@@ -162,10 +188,21 @@ belongs to the editor.
 - **Outside preview, do nothing on your own.** `usePlitziServiceContext().settings.previewMode` is `false` while the
   page is edited. Declared interactions are already held back then; your own click handlers, timers, global listeners,
   permission prompts and map gestures are not — gate them on `previewMode`, and still render something to select.
+- **A drag lives in state, not in refs read while rendering** (the project's lint refuses that): keep the gesture
+  in `useState`, mirror the latest props into a ref inside an effect, and attach `pointermove` on `pointerdown`.
 - **Never the global `window` or `document`.** The canvas is a frame of its own and the code runs in the builder's
   window: listen, measure and go full screen through the node's own page (`ref.current.ownerDocument`, its
   `defaultView`) or `usePlitziServiceContext().utils.getWindow()`. An `instanceof` check takes its class from there too.
 
+## The plugin's stylesheet and the space's CSS
+
+A plugin's stylesheet ships in a layer below the space's (`plitzi-sdk-plugin`, written by the build): the space's
+classes and `customCss` win over it whatever their specificity, as over a built-in element's defaults.
+
+A file a library needs whole is imported as Vite imports it, and travels inside the bundle: `worker.js?raw` is its
+text (a worker, started from `URL.createObjectURL(new Blob([source]))`), `engine.wasm?inline` a data URI. Images and
+fonts a stylesheet names are carried the same way.
+
 ## Components that draw into DOM they do not render
 
 A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never
@@ -173,27 +210,3 @@ give them a class that sets `position` — the element falls into the page's flo
 the look in the plugin's own stylesheet (imported CSS ships beside the bundle) and take colours from custom properties
 the space sets (`--seat-accent: var(--accent)` in `customCss`); a canvas or WebGL layer resolves them through a probe
 element with `getComputedStyle(probe).color`, again whenever `theme.resolved` changes (bind it as a prop).
-
-## Components that draw a lot
-
-A canvas with thousands of shapes on it — a whiteboard, a diagram, a map of points — is judged on a slower machine than
-yours: sixty frames a second here says nothing about a four-year-old laptop. What keeps one fast is doing work in
-proportion to what CHANGED, not to what is there:
-
-- **Two layers.** Paint what stands still on one canvas and leave it; clear and draw the one over it every frame, with
-  only what moves: the cursor, the selection, what is being dragged.
-- **Repaint the part that changed.** Something added, edited or removed repaints the area it was and is in, clipped,
-  with whatever reaches into it — not the whole board. A pan moves the picture already painted by whole device pixels
-  and paints the edges it uncovers.
-- **Draw a dragged group once.** Everything picked up moves by the same amount at every step: draw it to a canvas of its
-  own when the drag begins and copy that into place after.
-- **Cache per object, not per frame.** Treat elements as immutable and key what is derived from one — its bounds, its
-  shape, a resolved connector — on the object itself (a `WeakMap`), so nothing is worked out twice for the same thing.
-- **Hand the space outcomes, not motion.** A stroke finished, a selection changed: a trigger each. Firing one at every
-  pointer move runs a flow and renders the page at every pointer move.
-- **Measure with a bench, throttled.** A script that drives the real thing in a browser with the CPU slowed
-  (`Emulation.setCPUThrottlingRate`) and reports script time per frame, not only frames per second — and a test that
-  counts WORK (full repaints, strokes drawn during a drag), which holds on any machine where a timing does not.
-
-Pizarra, the collaborative whiteboard on the platform (`pizarra.plitzi.app`), does all of it on a board of thousands
-of elements.

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

@@ -7,7 +7,10 @@ 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).
+- [ ] `npm run lint:space` is clean — no file past 400 lines, no rows of data inline, no colour that is not a token —
+      or each departure says why where it is ([structure.md](structure.md#checked-for-you)).
 - [ ] No console errors on any page you touched.
 
 ## Nothing flashes, nothing jumps
@@ -39,7 +42,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 +70,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/structure.md

@@ -1,6 +1,6 @@
 # Structuring a space that grows
 
-A one-screen space fits in `src/space.ts`. Past a few pages, split it by what changes together — a file per part, short
+A one-screen space fits in `src/space/index.ts`. Past a few pages, split it by what changes together — a file per part, short
 enough to read whole — and keep every repeated thing in exactly one place. `npx @plitzi/cli create shop --template
 catalog` writes a complete small site in this shape (tokens, a layout, a card component, typed data, a page per file)
 to read before writing one.
@@ -71,6 +71,30 @@ container({ id: 'quick', class: quickGrid, children: QUICK.map(item => quickCard
 When items differ in ONE detail (one link needs a binding), put that detail in the item's data as an optional field
 — never an `if (item.id === 'team')` inside the map.
 
+## Pages of one shape are a family
+
+Docs pages, a menu's sections, a team's profiles: the same shape, different words. Write the shape once and the pages
+as data with `pageFamily` — it gives each page its id, slug, titles, folder and layout, and builds each body inside
+`scope(entry.id, …)`, so the ids two pages of the family give are never one:
+
+```ts
+import { pageFamily, heading, markdown } from '@plitzi/sdk-authoring';
+import { SECTIONS } from '../data/sections';   // [{ id: 'starters', title: 'Starters', slug: 'starters', description, body }]
+
+pages: [
+  home,
+  ...pageFamily(
+    { folder: 'menu', layout: { id: 'site', slot: 'site-slot' }, seoTitle: entry => `${entry.title} — Menu`,
+      body: entry => [heading({ id: 'title', content: entry.title }), markdown(entry.body, { id: 'body' })] },
+    SECTIONS
+  )
+]
+```
+
+Adding a page is adding an entry; two entries of one id or slug are refused as any two pages are. For one shape over
+records a visitor browses — a product, a post — a single page with a route param (`slug: 'posts/:postId'`) reading
+the record is the answer instead: one page, as many addresses as records.
+
 ## Names
 
 - **Ids:** `area-role` in kebab-case — `hm-traffic-title`, `docs-nav-docs-data`. Never the builder's positional
@@ -90,3 +114,10 @@ per page. It renders; it is not maintainable. When you work on such a file, leav
 
 Each of those is safe to do on its own: authoring refuses anything that would not render, and the visual check shows
 the rest.
+
+## Checked for you
+
+`npm run lint:space` (`plitzi lint`) reads the source for what this page asks — a file past 400 lines, pages in one
+file, rows of data inline, a colour that is not a token, CSS copied three times, a row singled out by its id inside a
+`map`, a minted id, a file nothing imports — at file:line, beside authoring's suggestions. Leave it clean; a departure
+on purpose says why where it is: `// plitzi-lint-disable-next-line <code> -- why`.