@plitzi/sdk-server 0.37.2 → 0.37.4

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

@@ -4,13 +4,15 @@
 button({
   id: 'cta',
   content: 'Get a quote',
-  flows: [[
-    onClick(),
-    named('quote', runServerAction({ actionId: 'shipping-quote', input: { city: 'Berlin' }, mode: 'await' })),
-    whenSucceeded('quote', setState({ key: 'quote', type: 'text', value: '{{ quote.output.summary }}' })),
-    whenFailed('quote', addNotification({ content: 'Could not reach the courier', appeareance: 'danger' }))
-  ]]
-})
+  flows: [
+    [
+      onClick(),
+      named('quote', runServerAction({ actionId: 'shipping-quote', input: { city: 'Berlin' }, mode: 'await' })),
+      whenSucceeded('quote', setState({ key: 'quote', type: 'text', value: '{{ quote.output.summary }}' })),
+      whenFailed('quote', addNotification({ content: 'Could not reach the courier', appearance: 'danger' }))
+    ]
+  ]
+});
 ```
 
 A flow is a list: a trigger, then steps in order. "Only if" is on the step (`when`, `whenSucceeded`, `whenFailed`),
@@ -22,9 +24,32 @@ never a nested tree. Use the step builders — they fill in where a step runs an
 - **Which `setState`.** `setState({ key })` writes `runtime.state.<key>` and is read as `state.<key>`; never put
   `state.` in the key. `updateElement(…)` changes one element's own attribute or state.
 - **Flip in one step.** `toggleState({ key })` for app state, `toggleElement({ category: 'state', key: 'visibility' },
-  'panel')` to show/hide an element. Never two branches under opposite `when` guards — they read the state as it was
-  when the flow started, a click behind.
+'panel')` to show/hide an element. Never two branches under opposite `when` guards — the second reads what the
+  first just wrote and flips it back. A key never set toggles to `true`, so for something shown by default name the
+  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'`.
+- **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.
 - **Keys are flat names.** A dotted key (`docsClosed.start`) is split into a path; use `docsClosedStart`.
+- **`setState` types**: `text`, `number` (decimals kept), `boolean` (the word or a real boolean), and `json` for an
+  object or a list — `value: '{{ list_rows.item }}'` stores the row itself; JSON text is parsed, and text that is not
+  JSON fails the step (the dev tools log it) instead of storing the text.
+
+## What a trigger hands the flow
+
+Name the trigger (`named('changed', onChange())`) and read its payload as `{{ changed.<field> }}`:
+
+| Trigger                                                                                                | Payload                                                 |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| `onChange` (formControl)                                                                               | `value` (a boolean for a checkbox), `name`              |
+| `onSubmit` (form)                                                                                      | `values` (by control `name`), `actionUrl`, `method`     |
+| `onPageLoad` (page)                                                                                    | `pageId`, `routeParams`, `queryParams`                  |
+| `onApiSuccess` / `onApiError` (apiContainer)                                                           | `url`, `method`, `status`, `data`                       |
+| `onModalOpen` / `onModalClose`, `onDialogOpen` / `onDialogClose` / `onDialogAccept` / `onDialogReject` | `metadata` — what `openModal` / `openDialog` was handed |
+| `onPageChange` (pagination)                                                                            | `page`                                                  |
+| `onThemeChange` (themeToggle)                                                                          | `theme`                                                 |
 
 ## Reading what came before
 
@@ -34,8 +59,13 @@ never a nested tree. Use the step builders — they fill in where a step runs an
 A step's params are templates, evaluated in full (conditions, loops, filters). A source in them is named in full:
 a row's button posts `{ jobId: '{{ list_jobRows.item.id }}' }` — the row that was clicked; the short name is refused.
 
-**Pass objects, not JSON text.** `input: { title: '{{ form.values.title }}' }`, never `input: '{"title": …}'` — a
-value with a quotation mark or a newline makes the text unparseable, and unparseable input posts `{}`.
+**Pass objects, not JSON text.** `input: { title: '{{ form.values.title }}' }` rather than `input: '{"title": …}'`:
+each value keeps its own type, and nothing depends on the quoting. (JSON text works — a value inside one of its strings
+is escaped for it — but an object says the same without the punctuation.)
+
+**A field left empty is not in `values`.** A form sends what was typed, and a field nobody typed in sends nothing —
+so `when({ field: 'sent.values.code', operator: '=', value: '' }, …)` never holds for it. Ask
+`operator: 'empty'` / `'notEmpty'`, which treat missing and `''` alike.
 
 ## Writes and what they refresh
 
@@ -45,12 +75,20 @@ everything. Say what it should refresh — `invalidateQueries: 'elements', inval
 
 ## Triggers belong to the element that fires them
 
-Every element fires `onClick`, `onLoad`, `onHover`, `onMouseEnter`/`onMouseLeave`, `onFocus`/`onBlur` and the ends of a
+Every element fires `onClick`, `onPointerDown` (the press, before it is a click — where a drag away from it starts),
+`onLoad`, `onHover`, `onMouseEnter`/`onMouseLeave`, `onFocus`/`onBlur` and the ends of a
 server action it started (`onFlowEnd`, `onFlowError`, `onFlowProgress`). A `page` fires `onPageLoad`, a `form`
 `onSubmit`, a `formControl` `onChange`, an `apiContainer` `onApiSuccess`/`onApiError` (each answer, either runtime,
 each refresh), a `modalContainer` `onModalOpen`/`onModalClose`, a `pagination` `onPageChange`. A flow on an element
 that never fires its trigger is refused, naming the type that does.
 
+**Keyboard shortcuts** are a trigger every element has: `onKey('f')`, `onKey('shift+f')`, `onKey('mod+k')` (⌘ on a
+Mac, Ctrl elsewhere), several with commas (`onKey('plus, =')`). Heard on the whole page while the element is mounted,
+so put it on the element whose flows it drives — `onKey('plus'), declaredCallback(map, 'zoomIn', { on: 'map' })` — or
+on the page. A press while typing in a field is the field's, unless Ctrl/⌘/Alt is held or the key is Escape.
+`{{ <step>.key }}` is the key pressed (`shift+f`). A shortcut that cannot fire (`'ctrl+shift'`, `'arrowupp'`) is refused
+where it is written.
+
 **A form's flow goes on the `form`**, which hands its submit over with `managedByInteractions: true`
 (`FORM_SUBMIT_UNMANAGED` otherwise — the browser submits it natively and `onSubmit` never fires):
 
@@ -58,23 +96,76 @@ that never fires its trigger is refused, naming the type that does.
 form({
   id: 'signup',
   managedByInteractions: true,
-  flows: [[named('submitted', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ submitted.values.email }}' })]],
-  children: [formControl({ id: 'email', name: 'email', label: 'Email', subType: 'email' }), button({ content: 'Sign up', subType: 'submit' })]
-})
+  flows: [
+    [named('submitted', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ submitted.values.email }}' })]
+  ],
+  children: [
+    formControl({ id: 'email', name: 'email', label: 'Email', subType: 'email' }),
+    button({ content: 'Sign up', subType: 'submit' })
+  ]
+});
 ```
 
 A `formControl` is `required` by default: an optional field says `required: false`, or an empty one stops the submit
 without a word.
 
+## Notifications
+
+`addNotification({ content: 'Saved', appearance: 'success' })` — `appearance` is `success`, `danger`, `warning` or
+`info`. They follow the page's theme and font; their colours are the space's `notifications`:
+`notifications: { background: 'var(--card)', text: 'var(--foreground)', success: 'var(--accent)', radius: '12px' }`.
+
 ## Modals, dropdowns, tabs
 
 - A modal or dialog is declared `visible: false` and driven with `openModal('credits')` / `closeModal('credits')`
-  (`openDialog` / `closeDialog`). `openModal`'s second argument is read inside as `{{ modalContainer_credits.content }}`.
+  (`openDialog` / `closeDialog`). `openModal`'s second argument is the modal's data: a JSON object is read by its
+  fields (`{{ modalContainer_credits.title }}`); anything else — a row's id, a number, a word — as
+  `{{ modalContainer_credits.content }}`. The close control is a real button, reachable by keyboard.
 - A `dropdown`'s label is a child and its `dropdownPopup` sits inside it; a `tabContainer`'s header and body are held
   inside it too. Outside, they are refused.
 
+## Realtime channels
+
+Pages that see each other — cursors, presence, a shared board — need a channel. Declare its topic pattern on the space,
+then subscribe with a `channel` element; a topic no pattern matches is refused, naming the patterns:
+
+```ts
+channels: {
+  'board:{id}': { access: { mode: 'public' }, publish: 'server' },           // only `realtime.publish` speaks
+  'room:{id}': { access: { mode: 'public' }, presence: true }                // pages speak directly
+}
+
+channel({ id: 'room', topic: 'room:{{ id }}', keep: 0, bind: { presence: 'computed.me' }, children: [...] })
+```
+
+Its descendants bind `room.members`, `room.connected`, `room.last`; flows use `on('onMessage')` (`type`, `data`,
+`from`), `onJoin`/`onLeave` (`from`, `user` and the `state` the member announced — `onJoin` only for who came after
+this page), `publishOn('room', 'reaction', data)` and `announceOn('room', state)`. State everyone must
+agree on goes through a server action whose last step is `realtime.publish` — validated and saved first, announced
+after. `docs/en/realtime.md` is the whole of it.
+
+A topic only some visitors may hear — a room behind a password, a customer's order — goes on a channel declared
+`grant: true`. The action that decides they may be there ends with `realtime.grant` and answers the grant; the
+element binds it, or the server refuses the topic every time (`channel-grant`). `realtime.revoke { topic, grant }`
+takes one back — or every grant for the topic, naming none — and lets go whoever is on it with it:
+
+```ts
+channels: { 'order:{id}': { access: { mode: 'session' }, grant: true } }
+
+// steps: [ …decide…, { id: 'let', task: 'realtime.grant', params: { topic: 'order:{{ input.order }}' } } ]
+channel({ id: 'order', topic: 'order:{{ id }}', bind: { grant: 'state.follow.grant' }, children: [...] })
+```
+
+Two people writing the same thing at once: `kv.setIf` writes only if the value is still the one the flow read (empty
+`expected` = only if nothing is there yet — claim a seat, a username), `list.put`/`list.range` keep an ordered list
+(latest first, a leaderboard), and `flow.rateLimit` first in a public action that writes.
+
 ## Lists as state
 
 `toggleInState({ key: 'picks', value })` keeps a list; `when({ field: 'state.picks', operator: 'contains', value })`
 asks it. `appendState({ key, value, withId: true })` stores `{ id, value }` — bind `.value`, address by `.id`.
-`whenFailed` matches every outcome that is not `completed` (also `skipped`, `aborted`).
+`whenFailed` matches every outcome that is not `completed` (also `skipped`, `aborted`). A failed run gives `reason`,
+and `error` only when the server or a step wrote one for the caller (a task throwing `ActionRefusal`, `flow.fail` with
+`tellCaller`) — so show `{{ saved.error ? saved.error : "…" }}`, never the bare `error`.
+
+`when(rule, step)` around a step that already has a `when` adds to it: both must hold.

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

@@ -0,0 +1,74 @@
+# Lists
+
+A `list` renders its children once per item. Its rows come from its `items` — an array written or bound on the list:
+a provider's answer, `state`, a fixed set. **Only `source: 'controlled'` reads them.** The default, `'none'`, renders
+its children once as a plain `<ul>` and never looks at `items`, so a list with items and any other source is refused
+(`list-items-ignored`). A CMS collection arrives the same way: a provider with its `connector` around the list, and the
+list bound to its records (see the provider in data-and-visibility).
+
+```ts
+list({
+  id: 'games',
+  source: 'controlled',
+  class: gameGrid,
+  bind: { items: 'catalog.data.games' },          // an array from the provider around it
+  children: [gameCard()]                          // rendered once per game
+})
+```
+
+- Each row publishes **`list_<id>.item`** (the row) and **`list_<id>.index`** (its position, as text). Inside the row,
+  bindings read the short form (`'games.item.title'`), templates and attribute tokens the full one
+  (`{{ list_games.item.slug }}`).
+- A **nested list** sees the outer row: inside `list_features`, `list_games.item` is still the game.
+- The list is a `<ul>` and its `class` styles that root; each child is rendered straight into it, with no wrapper.
+  A card grid needs `{ margin: '0px', padding: '0px', 'list-style-type': 'none' }` in its class.
+- Fixed data is `items: [ … ]` on the list itself — no provider needed.
+- Everything inside a row is `repeated` in the handles: a test addresses one copy with `.first()` / `.nth()`.
+
+## Filtering and sorting
+
+Bind `items` through a template that hands over its **value**:
+
+```ts
+list({
+  id: 'shown',
+  source: 'controlled',
+  bind: [bindTemplate('items', 'catalog.data.games',
+    "{{ source|filter(g => (state.genre ?? '') == '' or g.genre == state.genre)|sort((a, b) => b.score - a.score) }}",
+    { returns: 'value' })],
+  children: [gameCard()]
+})
+```
+
+Only the rows that match are rendered. A counter and an empty state read the same predicate over the same source:
+`{{ source|filter(…)|length }}` as text, and `visible: { source: 'catalog.data.games', template: "{{ source is defined
+and source|filter(…)|length == 0 }}" }`.
+
+Hiding rows one by one with a visibility binding also works, but every hidden row stays in the DOM (with its whole
+subtree unless the row says `loadStrategy: 'visible'`). Filter the items instead.
+
+## A detail page
+
+A page with a route param (`slug: 'games/{{slug}}'`) shows one record. With a server provider, `singleRecord` and
+`filters` fetch just that one. In the browser — an offline project, a `query` returning the whole collection — narrow
+the list to the record the route names:
+
+```ts
+apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children: [
+  list({
+    id: 'game',
+    source: 'controlled',
+    bind: [bindTemplate('items', 'catalog.data.games',
+      '{{ source|filter(g => g.slug == navigation.routeParams.slug) }}', { returns: 'value' })],
+    children: [gameDossier()]                       // reads list_game.item
+  }),
+  text('Signal lost — no game by that name.', {
+    id: 'game-missing',
+    visible: { source: 'catalog.data.games',
+      template: "{{ source is defined and not (source|find('slug', navigation.routeParams.slug)) }}" }
+  })
+] })
+```
+
+A link to it from a card is an attribute token read inside the card's row:
+`link({ mode: 'internal', href: '/games/{{ list_games.item.slug }}' })`.

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

@@ -0,0 +1,67 @@
+# Performance: what renders, and what it costs
+
+A page that does the right thing can still do it by rendering everything, and nothing shows it but the frame rate — on
+somebody else's slower machine. Measure it (`inspectRenders`, below) instead of guessing, and write the page so that a
+change renders what shows it.
+
+## What makes an element render
+
+An element renders again when something it READS changes, and only then:
+
+- **A binding, a `when` rule or an attribute template subscribes to each path it names** — `computed.tool`, not all of
+  `computed`; `state.cart.count`, not all of `state`. Name what you show: a template that reads `state.cart` renders on
+  every change to anything in the cart.
+- **A computed value is evaluated again whenever the state, the variables, the route, the session, the host or the
+  theme changes.** A value that comes out the same keeps its object, so what reads it does not render — but the work of
+  evaluating it is done every time. Keep computed values cheap: a filter over a list of five thousand rows belongs in
+  the binding of the list that shows them (`bindTemplate(…, { returns: 'value' })`) or in the provider, where it runs
+  when the list changes and not on every keystroke anywhere on the page.
+- **A parent rendering does not render its children** unless it hands them something new. What an element's own
+  bindings change is its own.
+
+## What a flow costs
+
+- **Synchronous steps are one change.** A `setState` after a `setState` after a `toggleState` renders once, when the
+  flow gives the page back — at its end, or at the first step that waits (a request, a `delay`), which renders what
+  came before it.
+- **A trigger that fires on every pointer move or keystroke is a flow per event.** For a stream of events, keep the
+  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.
+
+## What mounts
+
+- **A hidden element stays mounted** with its whole subtree — a modal's form, a closed panel's lists. `loadStrategy:
+  'visible'` mounts the contents only while it is shown, `'lazy'` from the first time it is shown. Use it for heavy
+  subtrees that start hidden.
+- **Every list row is a subtree.** Filter the items the list is given; a row hidden by a condition is still a row.
+
+## Measuring it: `inspectRenders`
+
+Render the space with `debugMode` (the SDK profiles every element then), and ask what an interaction rendered:
+
+```ts
+import { inspectRenders } from '@plitzi/sdk-authoring';
+
+const report = await inspectRenders(page, () => page.click('[data-plitzi-el="save"]'), { max: 10 });
+expect(report.problems).toEqual([]);
+```
+
+`report.elements` lists every element that rendered, how often, and what changed for it (`attributes`, `elementState`,
+a prop's name); `report.causes` the store paths written meanwhile. `max` turns it into an assertion: over it,
+`problems` names the elements that rendered most. A test that holds an interaction to its budget is how a regression
+is caught before anybody feels it.
+
+## When something is slow: where to look
+
+1. **Count before changing anything.** `inspectRenders` around the interaction that feels slow. Hundreds of elements
+   for one click is the problem; three is not, and the cost is somewhere else (a plugin, a large list mounting).
+2. **Read `changed` for the elements that rendered most.** Their own `attributes` or `elementState` changed: find what
+   they read in `causes` — a template naming more than it shows, a computed value that reads it. `nothing of its own`:
+   its context or its parent carried it; look at the element above it that did change.
+3. **Read `causes`.** A path you did not expect written — a flow writing on every pointer move, a provider refetching —
+   is the change to stop at its source.
+4. **Only then the browser's profiler**, for what a render costs rather than how many there are: a plugin drawing, a
+   list of thousands mounting at once.

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

@@ -0,0 +1,167 @@
+# Plugins
+
+A plugin is a React component of the project's own — a chart, a map, a game — hosted in the space by a `custom`
+element that names it by `renderType`:
+
+```ts
+custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best: 'state.arcadeBest' } })
+```
+
+## 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
+```
+
+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
+`index.ts` (`Object.assign(Component, declaration, { pluginSettings: Settings })`). An event or an action is declared in
+`declaration.ts` and registered by the component from there, never only in the component.
+
+A plugin fires its events with `interactionsManager.interactionTrigger(id, action, payload)` whenever it has news —
+from its first effect too: a flow starts once the page has finished mounting, so the `setState` it calls is there. No
+`queueMicrotask` or delay of your own. An event that REPORTS a state, and may fire again before its flow ends (as a
+component reads its real value right after mounting), wants `whileRunning('queue', …)` on the flow: by default a firing
+while the flow runs is dropped, and the stale first report would stick.
+
+## Props
+
+**The host element's attributes ARE the component's props.** Whatever the space writes on the `custom` element arrives
+by the same name, and so does whatever a binding writes — which is what makes a plugin live: bind an attribute to
+`state`, a provider or a row, and the component re-renders with the answer. Prefer this to anything else.
+
+`settings` is the other channel: a JSON string whose keys are merged into the props too. It is what the builder's
+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.
+
+## The component
+
+```tsx
+import { RootElement } from '@plitzi/plitzi-sdk';
+
+const NebulaRun = ({ shipColor = 'amber', best = 0, className }: NebulaRunProps) => (
+  <RootElement className={className}>…</RootElement>
+);
+```
+
+- **Render `RootElement`**, not a `div`: it carries the element's id, classes and `data-plitzi-el`, so the CSS
+  authored on the element applies, the builder can select it and a test can find it.
+- **Render the same thing on the server and on the first client pass.** A clock, a random number or anything read from
+  `window` belongs in an effect; a hydration mismatch discards the whole tree, not the plugin.
+- **Borrow colours.** `currentColor` and the space's `var(--…)` tokens follow the theme; a hard-coded colour is
+  invisible in one of them. A canvas reads them with `getComputedStyle(element).getPropertyValue('--accent')` and
+  again when `theme.resolved` changes (bind it as a prop).
+
+## Writing to the space
+
+A plugin that produces something the page shows — a score, a selection — writes it to `runtime.state`, where every
+binding reads it:
+
+```ts
+import { getStateManager } from '@plitzi/plitzi-sdk';
+
+const state = getStateManager();
+state.setStateByKey('arcadeBest', Math.max(score, Number(state.state.arcadeBest ?? 0)));
+const stop = state.subscribe(next => save(next));      // called after every change; call `stop()` to leave
+```
+
+`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.
+
+## Talking to other pages
+
+A plugin that moves at the speed of a cursor reads a realtime channel through `useChannel` rather than through flows —
+messages arrive through a callback and re-render nothing:
+
+```tsx
+import { useChannel } from '@plitzi/plitzi-sdk';
+
+const room = useChannel(roomTopic, { onMessage: message => move(message.from, message.data) });
+room.publish('pointer', { x, y });   // throttle it: ~20 a second, the latest position each time
+room.members;                        // who is here, with the state each announced
+```
+
+Take the topic as a prop (`bindTemplate('roomTopic', 'board.id', 'room:{{ source }}')`) so the space names its
+channels, and trust a message you act on only when `message.from === 'server'`. The page has one connection and is one
+member per topic, however many elements and plugins listen.
+
+## Registering
+
+A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in
+camelCase (`StatCard` → `statCard`). Anywhere else, the entry registers the component under its `renderType`: the
+third argument to `render()`, `<PlitziSdk.Plugin>` in a React application, `plugins` on a page server of your own. A `renderType` nothing registered
+renders "Custom Component … Not Found", and a page server logs the missing `renderType` at `error` once per
+space: on a server, register it in `plugins` AND name it in the deployment's `pluginNames`.
+
+A plugin PACKAGE, loaded by a space from its `plugin-manifest.json`, is an element TYPE of its own rather than a
+`custom` host — it is how the builder adds one somebody dropped. Author it with a typed factory:
+`defineElement<SeatPickerAttributes>(declaration)` from the plugin's own `declaration.ts`, or
+`elementsFromManifest<{ seatPicker: SeatPickerAttributes }>(manifest)` from what it published — or untyped,
+`element('seatPicker', { id: 'seats', start: 3 })`.
+
+## Checked like a built-in element
+
+Hand `authorSpace` the plugin's DECLARATION — the `declaration.ts` beside the component, or a manifest's
+`pluginSchema` entry:
+
+```ts
+import declaration from './plugins/SeatPicker/declaration';
+
+authorSpace(space, { plugins: [declaration] });
+```
+
+It is then held to what it declares, whether it is authored as its own type or hosted by `custom({ renderType:
+'seatPicker' })`: a flow on an event it never fires, a step sent to an action it does not answer, an attribute it does
+not read — each is refused with the name it should have been. (`pluginTypes: ['seatPicker']` only tells the linter the
+type exists; nothing about how the space uses it is checked.) A `custom` host whose component is NOT handed over is not
+judged on its events at all — nothing here knows them.
+
+Its events and actions have builders typed from the same declaration, so a name it does not declare is a compile error:
+
+```ts
+seats({ id: 'seats', flows: [[named('picked', declaredTrigger(declaration, 'onPick')), setState({ key: 'seat', type: 'text', value: '{{ picked.seat }}' })]] })
+button({ content: 'Clear', flows: [[onClick(), declaredCallback(declaration, 'reset', { on: 'seats' })]] })
+```
+
+A plugin says what HAPPENED through its events (`onPick`, with the seat in the payload) and lets the space's flows
+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.
+
+## 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
+give them a class that sets `position` — the element falls into the page's flow, offset by every marker before it. Put
+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

@@ -20,11 +20,25 @@ of it; each line is something that has shipped broken before.
 
 ## Every screen, every theme
 
-- [ ] Desktop, tablet and mobile — and nothing scrolls sideways on a phone. Tablet rules are repeated for mobile when
-      phones should keep them.
+- [ ] Desktop, tablet and mobile — and nothing scrolls sideways on a phone. A rule for tablets and phones alike is
+      written under `compact`.
 - [ ] Light AND dark. Every colour is a token with both values; no theme-following text on a fixed background.
 - [ ] Focus is visible on everything clickable (`focus-visible`), and `prefers-reduced-motion` stops what moves.
 
+## Usable without sight
+
+Screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree. See
+[accessibility](accessibility.md).
+
+- [ ] Every button and link has words — an icon-only button a `title`, a link around a card a `label` — and every field
+      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`.
+- [ ] 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.
+
 ## No copies
 
 - [ ] Chrome shared by pages is a layout; the current menu entry comes from `activeOn`, not per-page styling.
@@ -39,6 +53,9 @@ of it; each line is something that has shipped broken before.
       testimonials. A panel with nothing true to show is an empty state.
 - [ ] Times are formatted with an explicit zone and say which (`… 06:00 UTC`).
 - [ ] Logic lives in binding templates or on the server, not in an attribute (where a condition is never evaluated).
+- [ ] A filtered or sorted list binds its `items` to a template that returns its value — its rows are not hidden one
+      by one.
+- [ ] Every link you wrote was followed at least once: an `href` built from a row goes where it says.
 - [ ] Writes refresh what they changed — and only that (`invalidateQueries`); a multi-step form does not refresh the
       provider that decides whether to leave.
 - [ ] What only an administrator may read is shown only to administrators — and the check is a real boolean, not