@plitzi/sdk-server 0.38.4 → 0.38.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.4",
+  "version": "0.38.5",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -40,6 +40,11 @@
       "import": "./dist/mongo.js",
       "default": "./dist/mongo.js"
     },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js",
+      "default": "./dist/sqlite.js"
+    },
     "./handlers": {
       "types": "./dist/handlers.d.ts",
       "import": "./dist/handlers.js",
@@ -79,8 +84,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.4",
-    "@plitzi/sdk-shared": "0.38.4",
+    "@plitzi/plitzi-sdk": "0.38.5",
+    "@plitzi/sdk-shared": "0.38.5",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -18,7 +18,8 @@ const space: SpaceSpec = {
   components: [{ id, props, slots, root }],    // a block placed many times with different content
   pages: [{ id, name, slug: '', layout: { id: 'shell', slot: 'main' }, body: [] }]   // slot: where the body goes
 };                                             // slug '' is home; 'products/:slug' takes a param
-const { schema, style, warnings } = authorSpace(space, { plugins: [declaration] });
+pageFamily({ folder, layout, seoTitle, body: entry => [...] }, ENTRIES)   // pages of one shape, from data; ids scoped per page
+const { schema, style, warnings, suggestions } = authorSpace(space, { plugins: [declaration] });
 ```
 
 ## Elements
@@ -46,6 +47,7 @@ carousel({ id: 'hero', items: 'p.data.slides', autoplay: 5000, row: 'slide-card'
                                                // 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
+apiContainer({ id: 'p', action: 'report', runtime: 'server', children })     // the action's output at p's root: p.rows
                                                // 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 }]
@@ -109,7 +111,7 @@ A flow is `[trigger, …steps]`, in an element's `flows`.
 [onClick(), navigate({ urlType: 'page', url: 'about' })]
 [onClick(), runServerAction({ actionId: 'checkout', input: { id: '{{ list_rows.item.id }}' } })]
 [onClick(), when({ field: 'state.step', operator: '=', value: '2' }, setState({ … }))]
-[whileRunning('queue', onClick()), delay(1000), …]
+[whileRunning('queue', onClick()), delay(1000), …]      // 'latest': a new firing stops the running one
 [named('picked', declaredTrigger(declaration, 'onPick')), …]; declaredCallback(declaration, 'reset', { on: 'seats' })
 ```
 

package/skills/plitzi-authoring/SKILL.md

@@ -38,21 +38,21 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
 
 ## How to work
 
-1. **Read before you write.** Open `src/space.ts` (and whatever it imports) and find the layout, the classes and the
+1. **Read before you write.** Open `src/space/index.ts` (and whatever it imports) and find the layout, the classes and the
    helpers already there. Extend them; do not add a second way of doing something the space already does.
-2. **Change the declaration, then author it.** `npm run author` (or restart the server) runs `authorSpace`. It checks
-   everything — every field, value, template, name, param and page link — and a refusal says what to write instead:
-   do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape it. The first
-   refusals come one at a time; the linter's come as ONE list — fix every line of it before running again. How it
-   checks, a one-file author script for any project, and what it cannot see: [validation](reference/validation.md).
+2. **Change the declaration, then author it.** `npm run author` (or a restart) runs `authorSpace` — not `doctor`, which
+   is the project's. It checks every field, value, template, name, param and page link, and a refusal says what to
+   write instead: do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape
+   it. The linter's problems come as ONE list — fix every line before running again. How it checks, and what it
+   cannot see: [validation](reference/validation.md).
 3. **Read every warning, then every suggestion.** A warning names something written that will not do what it says —
-   zero warnings is the bar. A suggestion (`[suggest]`, `suggestions` in `authorSpace`'s result) names a shorter way to
-   the same page: a layout for chrome on every page, a component or a `list` for copies, a button's own `content`. Take
-   them, the ones that save the most first. See [efficiency](reference/efficiency.md).
+   zero warnings is the bar. A suggestion (`[suggest]`) names a shorter way to the same page — a layout, a component,
+   a `list`, a button's own `content` — or what nothing uses. Take them, the ones that save the most first
+   ([efficiency](reference/efficiency.md)). Then `npm run lint:space`: how the source is written — long files, rows of
+   data inline, colours that are not tokens — at file:line. Leave both clean.
 4. **Look at it.** `npm run check -- /about --width 1440,390` says in text whether the page is whole — every element on
-   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture, for
-   when it says something is wrong (`--frames 4` shows what moves); `npm run visual`
-   runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
+   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture
+   (`--frames 4` shows what moves); `npm run visual` runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
 5. **Go through the [review checklist](reference/review-checklist.md) before saying it is done.** It is the feedback a
    reviewer gives on every change, written down so you do not need to hear it.
 
@@ -66,10 +66,11 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
    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
    `component(id, { props })`. A menu, a card grid, a list of steps is DATA, never a block pasted per item: a short
-   menu mapped in code (`entries.map(entry => link({ href, content: entry.title }))`) is fine; rows — cards, dishes,
-   tiles — are one `list` over them (`items: [ … ]`) whose row is written once. A link or a button says its words as
-   its own `content`, not through a `text` inside it. See [layouts and duplication](reference/layouts.md),
-   [components](reference/components.md) and [efficiency](reference/efficiency.md).
+   menu mapped in code is fine; rows — cards, dishes, tiles — are one `list` (`items: [ … ]`) whose row is written
+   once. A link or a button says its words as
+   its own `content`, not through a `text` inside it. Pages of one shape are one `pageFamily` over data. See
+   [layouts](reference/layouts.md), [components](reference/components.md), [structure](reference/structure.md) and
+   [efficiency](reference/efficiency.md).
 3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
    refuses the pair. "This class plus one thing" is the class with rules on top, last in the list:
    `class: [cover, { opacity: '0.25' }]` (needs the element's `id`; it becomes the class `<id>--own`). A look that
@@ -94,9 +95,9 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
 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.
+   an empty state, not a placeholder figure. With no backend, the data is JSON read by an `apiContainer`: a server
+   project's `src/data/*.json`, read on the server and never served; with no server, `public/data/*.json`, which is
+   public — see [data and visibility](reference/data-and-visibility.md).
 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

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

@@ -24,7 +24,7 @@ const declaration = {
 
 const seatPicker = defineElement<{ rows?: number }>(declaration);
 
-// `authorSpace(recipe, { plugins })` — in a project, `src/plugins/declarations.ts` lists them all.
+// `authorSpace(recipe, { plugins })` — in a project, every `src/plugins/<Name>/declaration.ts`, found by folder.
 export const plugins: PluginDeclarationData[] = [declaration];
 
 export const recipe: SpaceSpec = {

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

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * Data in a server project (`create --mode server`): a JSON file of the project's own (`src/data/plans.json`, answering
+ * `/data/plans.json`), read by the page server before it answers and never served — 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

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

@@ -1,7 +1,8 @@
 /* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
 /**
- * Show data with no backend: a JSON file the project serves (`public/data/products.json`), read by a provider — one
- * card per product, a skeleton while it loads, a count, a computed value, and an empty state that never flashes.
+ * Show data with no backend, in a project with no server: a JSON file the browser fetches (`public/data/products.json`,
+ * public), read by a provider — one card per product, a skeleton while it loads, a count, a computed value, and an
+ * empty state that never flashes. A server project reads its `src/data/` on the server instead (`server-data.ts`).
  */
 import { apiContainer, container, heading, list, styles, text, listItem } from '@plitzi/sdk-authoring';
 

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

@@ -2,7 +2,7 @@
 /**
  * Data typed by a sample of it: `source()` turns the JSON the page reads into names the editor completes and checks —
  * `site.data.hero.titel` is a type error, not an empty heading. In a project the sample is the file itself:
- * `import home from '../../public/data/home.json' with { type: 'json' }`.
+ * `import home from '../data/home.json' with { type: 'json' }` — `src/data/`, or `public/data/` with no server.
  */
 import { apiContainer, heading, list, source, styles, text, twig, listItem } from '@plitzi/sdk-authoring';
 

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

@@ -6,7 +6,7 @@ Search this page for the code in brackets — `[class-and-css]` — rather than
 `npx @plitzi/cli explain class-and-css`.
 
 `authorSpace` reports everything it cannot write in one run, as a `SpaceRefusedError` whose `refusals` each carry
-a `code`, the line of your code that wrote the element (`src/site/home.ts:417`) and the nearest named element
+a `code`, the line of your code that wrote the element (`src/space/pages/home.ts:417`) and the nearest named element
 (`"store-footer" › container[1]`). **Do what the message says.** Never cast past a check, silence it, or move the
 logic into a plugin to avoid it — the check exists because that declaration renders something other than what it says.
 
@@ -119,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-data-in-browser` | a provider asking for the project's own data (`/data/…`, read by its server from `src/data/` and never served) from the browser | `runtime: 'server'` on the provider: the page arrives with the data in it |
 | `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 |
@@ -151,7 +152,7 @@ The space is not written until these are fixed.
 | `utility-module` | a utility sent to a module — a utility takes none | drop the `on` |
 | `visibility-as-attribute` | `visibility` bound as an attribute, which no element reads | `visible: { source, template }` |
 | `visitor-roles` | `settings.visitorRoles` written in a shape the runtime does not read | the shape the message gives |
-| `while-running` | `whileRunning` on a step that is not the trigger, or a mode other than `skip`, `parallel`, `queue` | `[whileRunning('queue', onClick()), …]` |
+| `while-running` | `whileRunning` on a step that is not the trigger, or a mode other than `skip`, `parallel`, `queue`, `latest` | `[whileRunning('queue', onClick()), …]` |
 
 ## Warned
 
@@ -159,6 +160,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 
 | Code | What was wrong | Write instead |
 | --- | --- | --- |
+| `action-output-path` | a read of `.data` on a provider fed by a server action — it publishes the action’s output at its root, and `.data` is a `query` provider’s answer | the output’s own field — `apiContainer_feed.stories`, not `apiContainer_feed.data.stories` |
 | `click-on-static-element` | a click flow on a container, text, heading, image or list item — no keyboard reaches it | the flow on a `button` (it holds children) or a `link` |
 | `colour-without-dark` | a colour token with no dark value | `{ light, dark, default }` |
 | `condition-starts-visible` | a computed visibility that shows until its data answers | `visible: { source, template }` |
@@ -211,8 +213,12 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 | `custom-css-notifications` | the toasts dressed with `.Toastify__toast` rules in `customCss` | `notifications: { font, fontSize, border, shadow, padding, background, text, radius }` |
 | `custom-css-sdk-default` | `customCss` repeating what the SDK already does for every space — less motion when asked, the theme toggle showing one icon | nothing: remove it |
 | `heavy-animation` | keyframes animating what the browser repaints or lays out again on every frame — a size, a position, a blur, a shadow, or a colour in a loop — which stutters whenever the page is busy, most of all while it loads | `opacity` and `transform`: a size or a position is `translate`/`scale`, a blur or a shadow is the `opacity` of a layer carrying it; a loop that must animate anything else starts `paused` and runs under `[data-hydrated]` |
+| `literal-colour` | a colour written out in a class where the space has a token of that value — it stays put in the dark scheme | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both |
 | `repeated-on-pages` | the same block — a header, a footer, a side panel — written into several pages | a layout holding it once (`layouts`, and `layout: { id, slot }` on each page) — a component when only some pages of a layout carry it; a link marks its own page with the `current` state |
 | `repeated-shape` | the same structure written again and again with different words — cards, rows, tiles | a component with props (`components`, `component(id, { props })`), or one `list` when they are rows of data side by side — a few cards a person rewords on the canvas can stay cards |
+| `unused-class` | a class declared in `classes` that no element, binding, flow or other class names | remove it from `classes` — or wear it where it was meant to go |
+| `unused-component` | a component no page, layout or other component places | remove it from `components`, or place it where it was meant to go |
+| `unused-token` | a token of `variables` no `var(--…)` reads — not a class, an element, `customCss` nor another token | remove it, or write it where its colour is written out |
 
 ## UPPER_CASE codes
 

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

@@ -62,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).
 
@@ -60,14 +61,19 @@ 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.
+- 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'`.
+  `"{{ 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)).
@@ -79,21 +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.
-
-**`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.
+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.
+
+- **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
 

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,8 +19,9 @@ 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):
+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)] });
@@ -42,6 +43,22 @@ Only a suggestion's code: a problem is never quieted (`quiet-unknown`).
 | `.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/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/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

@@ -9,6 +9,8 @@ of it; each line is something that has shipped broken before.
 - [ ] 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) — 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