@plitzi/sdk-server 0.37.1 → 0.37.3

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

@@ -0,0 +1,180 @@
+# Data and visibility
+
+## Bindings
+
+```ts
+heading({ bind: { content: 'posts.title' } })                                     // short form: attributes
+text({ bind: [bindTemplate('content', 'stats.data.total', "{{ source|number_format(0, '.', ',') }} views")] })
+container({ bind: [bindTemplate('width', 'state.xp', '{{ source / 10 }}%', { category: 'style' })] })  // a style
+text({ bind: [{ to: 'content', source: 'posts.title', when: { … } }] })             // full form: anything else
+```
+
+`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)).
+
+**A source names the id you gave the element** — `'posts.title'`, `'postList.item.cover'` — and the prefix is
+completed from what the element publishes (`apiContainer_posts`, `list_postList`; a `form` publishes under
+`apiContainer`). A name nothing answers to, or a prefix that does not match, is refused.
+
+**Inside a template the name is spelled in full**: `{{ apiContainer_stats.data.total }}`, `{{ list_rows.item.id }}`.
+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`),
+`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).
+
+## Values computed once
+
+A value many elements show — a score, a level, a count of what the visitor picked — is declared once on the space and
+read everywhere as `computed.<name>`, instead of repeating its expression in every binding:
+
+```ts
+export const space = {
+  …,
+  computed: {
+    xp: '{{ (state.favourites|length) * 10 + (state.runs ?? 0) * 5 }}',
+    level: '{{ computed.xp // 100 + 1 }}'
+  }
+};
+
+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.
+
+## Providers
+
+```ts
+apiContainer({ id: 'orders', query: '{{apiUrl}}/orders', credentials: 'include', children: [ … ] })
+apiContainer({ id: 'board', runtime: 'server', action: 'queue-board' })          // resolved before the HTML
+```
+
+- 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.
+  `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 }`.
+
+### 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` with Vite) 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.
+
+### Live, cached, refreshed
+
+- **Live:** `refreshSeconds: 15` asks again on its own (either runtime); it pauses in a hidden tab and never
+  overlaps. Use it for queues, feeds, status boards — then mark the panel as live so the reader knows it moves.
+- **Cached:** `cache: true` (and `staleTime` seconds, 30 by default) shares an answer between providers asking the
+  same thing and across page changes.
+- **Refreshed by writes:** a `webHook` that is not a GET refreshes every request to its own site by default
+  (`invalidateQueries: 'origin'`); a `runServerAction` refreshes everything (`'all'`). Narrow it with
+  `'elements'` + `invalidateElements: ['orders']`, or stop it with `'none'`.
+- **Say `'none'` when a refresh would move the page on.** A page that decides where to go from a provider's answer
+  ("profile complete → leave") will act on the refreshed answer in the middle of a multi-step form that saves as it
+  goes, and skip the last step.
+
+## Visibility
+
+```ts
+container({ visible: 'posts.hasPosts', … })     // shown while true
+container({ visible: '!posts.hasPosts', … })    // its inverse
+modalContainer({ visible: false, … })           // starts hidden; a flow opens it
+```
+
+**An element is visible by default.** Which way its condition flips decides how it is written:
+
+| 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 |
+
+`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
+no: `false`, `0`, an empty text, an empty list and nothing at all are a no, anything else a yes. Write the condition
+itself; `? 'true' : 'false'` is not needed:
+
+```ts
+container({
+  id: 'first-steps',
+  visible: {
+    source: 'stats.data.totals',
+    template: '{{ source and not (source.spaces > 0 and source.published > 0) }}'
+  }
+})
+```
+
+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 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.
+- **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.
+
+### Loading, empty, error
+
+Four states, and each has its own element:
+
+| State | How to tell |
+| --- | --- |
+| Loading | `apiContainer_x.isLoading` — or simply nothing: every condition is hidden until data arrives |
+| Empty | the answer ARRIVED and is empty: `{{ source is defined and source is empty }}` over the list |
+| Error | `apiContainer_x.hasError` |
+| Data | the list itself |
+
+`visible: '!provider.data.items'` is NOT an empty state: before the answer, `!undefined` is true and "Nothing here yet"
+shows on every load. Test for "arrived and empty" (`is defined and … is empty`), or bind to `isEmpty` together with
+`not isLoading`.
+
+## Never ask the data for an opposite
+
+Both sides of one question are `visible: 'x'` and `visible: '!x'`, not an `x` and a `notX` in the server's answer.
+`!` reads a boolean that travelled as text (`"false"`, `"0"`) correctly. A three-state condition
+(`Boolean(post) && !canEdit`) still belongs where the data is made.
+
+## State that outlives a reload
+
+`render(…, { state })` seeds `runtime.state` when the page starts — the way a host hands a space what it already knows.
+`settings: { keepState: true, stateStorage: 'localStorage' }` keeps `runtime.state` across reloads, filed under
+whoever is signed in (a guest's state is the browser's; another account never sees it). Keep only what a person would
+expect back — favourites, a chosen theme. Everything else goes in `transientState`, which is never written and never
+brought back:
+
+```ts
+settings: { keepState: true, transientState: ['filter', 'tourStep', 'panelOpen'] }
+```
+
+Do not reset kept state from `onPageLoad` instead: what was kept is restored late — after hydration, once auth knows
+who this is — and lands in the middle of that flow, so half of it is undone. A filter restored on the next visit is a
+page that looks broken. Keeping state is the SPACE's setting; a page does not take `keepState`.
+
+That lateness shows. Kept state is restored after the server's first paint, so anything kept that changes what is
+DRAWN — the tool a toolbar shows as last picked, a name in an avatar, a panel left off — is drawn with its default and
+then swapped. List those keys in `paintedState`: they are kept in a cookie too, the server renders with them, and the
+page starts from the same values.
+
+```ts
+settings: { keepState: true, paintedState: ['shapesPick', 'name', 'color'], transientState: ['panelOpen'] }
+```
+
+Only what the first paint shows, and small values: the cookie travels with every request and holds a few kilobytes
+(over that, the page falls back to the defaults and the dev tools say so). Never a secret — a key, a token — and never
+a key that is also in `transientState` (`authorSpace` refuses it).

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

@@ -0,0 +1,161 @@
+# Elements and styles
+
+## Elements
+
+One factory per element, named after it. Attributes and the authoring fields go in ONE flat object:
+
+```ts
+heading({ content: 'Fieldnotes', subType: 'h2', class: title })
+image({ src: '/fox.jpg', alt: 'A fox', css: { 'aspect-ratio': '3/2' } })
+container({ class: card, children: [ … ] })
+text('Wildlife, close up')          // a string is the content
+container([hero, grid])             // an array is the children
+```
+
+| Authoring field | What it does |
+| --- | --- |
+| `id` | the ONE name this element answers to — its key in the document, a binding's source, a step's target. Unique across the WHOLE space |
+| `class` | a shared class: a `styles()` declaration or a name from the space's `classes`; a list for several. Exclusive with `css` |
+| `css` | rules of this element's own: one set, or one per breakpoint (`{ desktop, tablet, mobile }`) |
+| `states` | `hover`, `focus-visible`, `hidden`… beside the element's own `css` |
+| `variant` | a variant of the class it wears (when the class declares it) or of its type |
+| `slots` | a class for one of the element's OTHER selectors — a form control's `input` |
+| `bind` | where a value comes from |
+| `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` |
+| `children` | the tree |
+| `meta` | `meta.label` is the element's name in the builder's tree |
+
+Anything else in the object is an **attribute** (`authorSpace` warns `unknown-attribute` for one the element never
+reads).
+
+**A link's `href` is a page id.** `link({ href: 'reports' })` finds the page by id, folder included. `mode: 'internal'`
+for a path within the space carrying `{{tokens}}` — a row's own slug (`'/games/{{ list_games.item.slug }}'`), a route
+param, state; `mode: 'external'` for a full URL passed through untouched. A link is an `<a>`: never put a link inside
+another link — make the card the link, or the button, not both.
+
+**Some types hold no children.** A `heading`, `text`, `paragraph`, `image`, `formControl`… renders its own attributes
+and nothing nested in it — `authorSpace` refuses children there. A heading made of parts (a word in another colour, an
+icon, a badge) is a `container` with the heading's tag: `container({ subType: 'h1', class: title, children: [text('Space
+'), text('Gamer', { class: accent })] })` — give the texts `display: inline` in their class.
+
+**A `button` shows its `content` AND its children.** `content` defaults to "Button": a button whose words are children
+says `content: ''` (`default-content-beside-children` warns otherwise). Its accessible name is everything it shows.
+
+**A `formControl` works on its own.** Inside a `form` its value is the form's and it validates on submit; outside one it
+keeps its own value and fires `onChange` with `{ value, name }` on every change — a search box or a select that
+filters a screen needs no form. Bind `defaultValue` to the state it writes and a reset of that state reaches it.
+
+**A `list` is a `<ul>`.** The browser indents it and puts bullets on it; a list of cards needs
+`{ margin: '0px', padding: '0px', 'list-style-type': 'none' }` in its class.
+
+**A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own by default, so its
+children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the
+parent, or give it `attributes: { subType: 'div' }`.
+
+A type this SDK does not ship — a plugin — is authored the same way: `defineElement<Props>({ type, … })`,
+`element<Props>('type', props)`, or `elementsFromManifest(manifest)`. See [plugins](plugins.md).
+
+**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] })"
+```
+
+## CSS
+
+Write CSS as you write CSS, shorthands included — they are expanded to the longhands Plitzi's editor reads. A property
+outside the vocabulary is refused with the key it should have been (`paddingTop` → `padding-top`).
+
+- `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
+  `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.
+- **`backdrop-filter`, `filter` and `transform` make an element the containing block of its `position: fixed`
+  children.** A glass header with a fixed phone dock inside puts the dock at the top of the header, not the screen.
+- **Fonts are declared.** A `font-family` loads only if the space lists the face in `fonts`
+  (`{ source: 'google', family: 'Geist', fallback: 'system-ui, sans-serif', weights: [400, 600], styles: ['normal'] }`).
+
+## Classes
+
+```ts
+const card = styles('card', {
+  css: { padding: '24px', 'border-radius': '12px', 'background-color': 'var(--card)' },
+  states: { hover: { 'border-color': 'var(--primary)' }, 'focus-visible': { outline: '2px solid var(--primary)' } },
+  variants: { active: { 'border-color': 'var(--primary)' } }
+});
+
+container({ class: card, children: [ … ] });
+```
+
+- A flat object is the base rules; `{ css, states, variants, ancestors }` when there is more. Each part may be written
+  per breakpoint.
+- **Share a rule as a class, never as a spread.** Spreading a `const` into each element's `css` shares the source and
+  duplicates the document: one selector per element, so restyling one card in the builder restyles one card.
+- **Build a family from a plain object**, not by layering classes: `styles('button-primary', { ...buttonBase, … })`.
+- One name declared twice with rules that disagree is refused. Declare a class once, in the module that owns it, and
+  import it.
+- `ancestors: { [sidebar.name]: { variants: { collapsed: { display: 'none' } } } }` styles an element by the state or
+  variant of an ancestor class — the way to react to a parent's hover or collapse without a flow.
+- **`hidden` is how an element looks while its `visible` says no** — where it goes as it hides, and where it comes
+  from as it shows. Give the class a transition that includes `display` with `allow-discrete`, and a panel fades or
+  slides instead of blinking; the transition on the base is the way in, the one in `hidden` the way out:
+
+  ```ts
+  const panel = styles('panel', {
+    css: {
+      transition: 'opacity 220ms cubic-bezier(0.2, 0.9, 0.3, 1.2), transform 220ms cubic-bezier(0.2, 0.9, 0.3, 1.2), display 220ms allow-discrete'
+    },
+    states: {
+      hidden: {
+        opacity: '0',
+        transform: 'translateY(-6px) scale(0.98)',
+        transition: 'opacity 120ms ease-in, transform 120ms ease-in, display 120ms allow-discrete'
+      }
+    }
+  });
+  ```
+
+  What is inside follows its container with `ancestors: { [panel.name]: { states: { hidden: { … } } } }` — a
+  different `transition-delay` per item staggers them. A container whose children mount only while it shows
+  (`loadStrategy: 'visible'`) empties before it can leave: use `'lazy'` on one that animates out.
+- **`:hover` is part of the selector, not a rule in `customCss`.** `customCss` is for what no class can say:
+  keyframes, pseudo-elements, a rule across two unrelated elements, the inside of a third-party widget.
+- Per element TYPE defaults go in `elements: { heading: { base, states, variants, slots } }` — a whole type at once.
+- **Slots** are an element's other selectors: a `formControl`'s `input`, `label`, `error`; a `modalContainer`'s
+  `backgroundContainer`, `rootContainer`, `headerContainer`, `headerTitle`, `headerCloseButton`, `bodyContainer`; a
+  `dialogContainer`'s footer and buttons. `elementSlots` lists them all by type. Style one element's with `slots`, a
+  whole type's with `elements.<type>.slots`.
+- A `modalContainer` / `dialogContainer` is fixed to the viewport, as tall as its content up to the screen, and 500px
+  wide up to the screen; theme its look through its slots.
+
+**A variant chosen by the data:** `variantFrom(pill, 'jobs.item.status')`, or with a template when the data does not
+already speak in variant names — `variantFrom(pill, 'runs.item.status', { template: "{{ source == 'completed' ?
+'ok' : 'failed' }}" })`. The binding's key names the CLASS; never write it by hand. For "the current page", see
+`activeOn` in [layouts.md](layouts.md).
+
+## Colours and themes
+
+Every colour is a **variable** with both values, and elements say `var(--name)`:
+
+```ts
+variables: {
+  color: {
+    foreground: { light: '#0c0c14', dark: '#ededf3', default: '#0c0c14' },
+    card: { light: '#ffffff', dark: '#101019', default: '#ffffff' },
+    primary: { light: '#5b3df5', dark: '#6e52f7', default: '#5b3df5' }
+  }
+}
+```
+
+- 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.
+- A tint of a token is `color-mix(in srgb, var(--primary) 12%, transparent)`, which follows the theme for free.
+- `themeToggle()` is the switch; `theme.resolved` (`light`/`dark`) is a global source for anything else that needs it.

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

@@ -0,0 +1,171 @@
+# Flows
+
+```ts
+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', appearance: 'danger' }))
+    ]
+  ]
+});
+```
+
+A flow is a list: a trigger, then steps in order. "Only if" is on the step (`when`, `whenSucceeded`, `whenFailed`),
+never a nested tree. Use the step builders — they fill in where a step runs and what it takes:
+
+- **Where it runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an element
+  callback under an element's id, a utility under nothing. Naming either half wrong is a control that does nothing,
+  with no error — which is why the builders exist.
+- **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 — 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
+
+`named('quote', step)` is how a later step reads an earlier one: `{{ quote.output.total }}`. The trigger too:
+`named('submitted', onSubmit())` → `{{ submitted.values.email }}`. Unnamed steps get ids nothing can refer to.
+
+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 }}' }` 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
+
+`webHook` (not GET) refreshes every request to its own site when it succeeds; `runServerAction` refreshes
+everything. Say what it should refresh — `invalidateQueries: 'elements', invalidateElements: ['orders']` — or
+`'none'` for a step that only reads, or when a refresh would make the page act on the new answer mid-flow.
+
+## Triggers belong to the element that fires them
+
+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):
+
+```ts
+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' })
+  ]
+});
+```
+
+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 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`). 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/layouts.md

@@ -0,0 +1,140 @@
+# Layouts, and not writing anything twice
+
+A space grows by pages, and most of what a page shows is the same on its neighbours: the top bar, the sidebar, the
+footer, the menu, the "ask for help" card. Written into each page, that chrome is a copy per page — sixteen docs pages
+carried the same sidebar sixteen times, around 900 elements whose only difference was which link was highlighted, and
+the copies disagreed the first time one was edited. The tools below remove every one of those copies.
+
+## A layout is the shell, written once
+
+```ts
+export const docsLayout: LayoutSpec = {
+  id: 'docs-layout',
+  label: 'Docs Layout',
+  folder: 'docs',                      // files it beside its pages in the builder; it routes nothing
+  body: [
+    container({
+      id: 'docs-shell',
+      class: shell,
+      children: [
+        topbar(),                      // helpers returning ElementSpec keep the layout readable
+        container({ id: 'docs-body', class: body, children: [sidebar(), container({ id: 'docs-slot', class: slot })] })
+      ]
+    })
+  ]
+};
+
+// in the space
+layouts: [appLayout, docsLayout],
+pages: [{ name: 'Quickstart', slug: 'quickstart', folder: 'docs', layout: { id: 'docs-layout', slot: 'docs-slot' }, body: [ … ] }]
+```
+
+- **The slot** is the element in the layout where the page's body goes. It must be inside the layout (checked).
+- **Not re-mounted on navigation.** Moving between pages of one layout keeps the shell — its scroll, its open menus,
+  its providers, its state — and swaps only the slot. That is also why a layout is cheaper than a copy.
+- **Layouts nest.** `layout: { id: 'app-shell', slot: 'main' }` on a LAYOUT puts a section shell (analytics tabs, docs
+  sidebar) inside the application shell. The page resolves the chain from the outside in.
+- **A provider in a layout serves every page** — the plan in a sidebar, a star count in a top bar. A server provider
+  (`runtime: 'server'`) in a layout is resolved with the page like one in the page.
+- **Ids are shared** between a layout and all its pages. Name layout elements after the layout (`docs-topbar`), and
+  let pages prefix theirs with the page id.
+
+## The menu is data
+
+The pages a menu lists, their titles, their summaries and their order are ONE list, and everything that shows them
+reads it — the sidebar, the page title, the meta description, "previous / next", an index of cards:
+
+```ts
+// nav.ts — the single source
+export const DOCS_NAV = [
+  {
+    id: 'start',
+    title: 'Getting started',
+    icon: 'fas fa-rocket',
+    entries: [
+      { id: 'docs-index', slug: '', title: 'Plitzi for developers', lede: 'What a space is…', icon: 'fas fa-book-open' },
+      { id: 'docs-quickstart', slug: 'quickstart', title: 'Quickstart', lede: 'One command…', icon: 'fas fa-bolt' }
+    ]
+  }
+] as const;
+
+// layout.ts — the sidebar, generated
+const navGroup = (group: DocsGroup): ElementSpec =>
+  container({
+    id: `docs-group-${group.id}`,
+    children: group.entries.map(entry =>
+      link({
+        id: `docs-nav-${entry.id}`,
+        href: entry.id,
+        class: navLink,
+        bind: [activeOn(navLink, entry.id)],
+        children: [text(entry.title, { id: `docs-nav-label-${entry.id}` })]
+      })
+    )
+  });
+```
+
+Adding a page is one entry in the list: the menu, the index and the neighbours' "next" follow.
+
+## The current entry: `activeOn`
+
+A menu in a layout is the same nodes on every page, so it cannot have the right entry styled by hand. It asks which
+page is showing:
+
+```ts
+const navLink = styles('nav-link', {
+  css: { color: 'var(--muted)' },
+  variants: { active: { color: 'var(--foreground)', 'font-weight': '600' } }
+});
+
+link({ href: 'spaces', class: navLink, bind: [activeOn(navLink, ['spaces', 'space-record'])] });
+```
+
+`activeOn(class, pageIds, { variant?, slot? })` binds the class's variant to `navigation.currentPageId`: the `active`
+variant on those pages, `idle` everywhere else. Several ids for one entry — a section and the pages under it. Do not
+write the binding by hand with a `when` rule per page; that is the long form 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:
+
+```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 …`);
+```
+
+Every page is now its content and nothing else, and every page is guaranteed the same structure.
+
+## Styles follow the same rule
+
+- A role used on several pages is ONE class (`panelCard`, `pageTitle`), declared in the module that owns the area and
+  imported — never re-declared per page, never spread into `css`.
+- Layout classes live with the layout; page classes with their page; shared ones in one `styles.ts` per area.
+- A family of looks is a shared base object and one class per member; a state of one element is a variant.
+- If you find yourself copying a `css` block, it is a class. If you find yourself copying an element tree, it is a
+  function, a layout, or a `map` over data.
+
+## When NOT to use a layout
+
+A block that appears on one page belongs to that page. A block on several pages but in different places is a
+function (`communityLinks('docs-help', 'on-surface')`), not a layout. A layout is for what frames the page.