@plitzi/sdk-server 0.37.2 → 0.37.4

package/skills/plitzi-authoring/SKILL.md

@@ -28,17 +28,22 @@ const { schema, style, warnings } = authorSpace(space);
 ```
 
 The published `.d.ts` is the reference for every factory, field and step builder
-(`node_modules/@plitzi/sdk-authoring/dist/index.d.ts`) — read it instead of guessing a name or a param.
+(`node_modules/@plitzi/sdk-authoring/dist/index.d.ts`) — read it instead of guessing a name or a param. For one element
+type, the exported catalogues answer faster (`elementDefaultAttributes`, `elementTriggers`, `elementSlots`… — see
+[elements and styles](reference/elements-and-styles.md)).
 
 ## How to work
 
 1. **Read before you write.** Open `src/space.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`. A refusal
-   is an error that names the element and the fix — fix the declaration, never work around the check.
+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).
 3. **Read every warning.** Each one names something written that will not do what it says. Zero warnings is the bar.
-4. **Look at it.** `npm run visual` opens the page in a browser. Check desktop, tablet and mobile, light and dark,
-   and the page while its data is still loading — not only the finished frame.
+4. **Look at it.** `npm run shot -- /about --width 390 --scheme dark` saves a picture of one page; `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.
 
@@ -59,20 +64,93 @@ The published `.d.ts` is the reference for every factory, field and step builder
    loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
    is folded), it keeps the default and an absent flag must leave it shown. See
    [data and visibility](reference/data-and-visibility.md).
-5. **Know where a template is evaluated.** A binding's `twigTemplate` and a step's params evaluate full Twig. An
-   ATTRIBUTE only resolves a name with filters (`{{ post.slug|url_encode }}`); a condition there is used as written.
-   Inside any template a source is spelled in full — `apiContainer_stats`, `list_rows` — never by the element's short
-   id. See [templates](reference/templates.md).
+5. **Know where a template is evaluated.** A binding's template (`bindTemplate`) and a step's params evaluate full
+   Twig. An ATTRIBUTE resolves a name with filters (`{{ list_games.item.slug }}`, `{{ post.slug|url_encode }}`) against
+   the sources around the element; a condition there is used as written. Inside any template a source is spelled in
+   full — `apiContainer_stats`, `list_rows` — and a query param is `navigation.queryParams.x`. A template that feeds a
+   list its `items` hands over its value (`returns: 'value'`). `authorSpace` refuses a template it cannot read and a
+   name nothing answers to. See [templates](reference/templates.md).
 6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
    checked from the first commit.
 7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
    a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
 8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (below 48rem) each inherit only from `desktop`; a rule
-   meant for both is written in both.
+   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.
+   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).
 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
+    named for the default (`showPlates`, on by default) takes a first click to do nothing: name it `platesOff`, and read
+    every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
+    anybody touches it.
+12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
+    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
+    [plugins](reference/plugins.md).
+13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
+    accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`
+    (`hideLabel: true` hides it and keeps the name), every image an `alt` or `decorative: true`. Clicks go on a
+    `button` — it holds children, so a whole card can be one — or a `link`, never on a container. See
+    [accessibility](reference/accessibility.md).
+
+## Recipes
+
+Copy the one that fits, then change the names. Each is the shape `authorSpace` accepts on the first try.
+
+```ts
+// Data with no backend: a JSON file the project serves (public/data/games.json), read by a provider.
+apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children: [ /* reads catalog.data.… */ ] })
+
+// A list of rows from that data. Inside a row: short form in bindings, full name in templates and attributes.
+list({ id: 'games', source: 'controlled', bind: { items: 'catalog.data.games' }, children: [
+  link({ mode: 'internal', href: '/games/{{ list_games.item.slug }}', children: [
+    text('', { bind: { content: 'games.item.title' } })
+  ] })
+] })
+
+// A filtered list: a template that hands over its VALUE.
+list({ id: 'shown', source: 'controlled',
+  bind: [bindTemplate('items', 'catalog.data.games', "{{ source|filter(g => g.genre == state.genre) }}", { returns: 'value' })],
+  children: [ … ] })
+
+// Text computed from data.
+text('', { bind: [bindTemplate('content', 'catalog.data.games', '{{ source|length }} games')] })
+
+// Shown only when a computed condition says so (starts hidden, no flash).
+text('Nothing here yet', { visible: { source: 'catalog.data.games', template: '{{ source is defined and source|length == 0 }}' } })
+
+// A value used in many places: declare it once in the space, read it anywhere as computed.xp.
+computed: { xp: '{{ (state.favourites|length) * 10 }}' }
+
+// A button that does something: a flow is [trigger, steps…].
+button({ content: 'Save', flows: [[onClick(), setState({ key: 'saved', type: 'boolean', value: true })]] })
+
+// A form: the flow goes on the form, which manages its own submit.
+form({ id: 'signup', managedByInteractions: true,
+  flows: [[named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]],
+  children: [formControl({ name: 'email', label: 'Email', subType: 'email' }), button({ content: 'Sign up', subType: 'submit' })] })
+
+// A modal: hidden until a flow opens it.
+modalContainer({ id: 'details', visible: false, title: 'Details', children: [ … ] })
+button({ content: 'Open', flows: [[onClick(), openModal('details')]] })
+
+// A plugin: author it from its own declaration, flow on its events, call its actions — all checked.
+const seats = defineElement<SeatPickerAttributes>(declaration);
+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' })]] })
+authorSpace(space, { plugins: [declaration] })
+
+// Usable without sight: an icon-only button says what it does; a clickable card IS a button; a field keeps its label
+// out of sight rather than dropping it; a picture says what it shows, or that it only decorates.
+button({ content: '', title: 'Close', children: [fontAwesome({ icon: 'fa-solid fa-xmark' })], flows: [[onClick(), closeModal('details')]] })
+button({ content: '', class: card, children: [text('Pro'), text('12 € a month')], flows: [[onClick(), setState({ key: 'plan', type: 'text', value: 'pro' })]] })
+formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder: 'Search…' })
+image({ src: '/team.jpg', alt: 'The team at the 2026 offsite' }); image({ src: '/grain.png', decorative: true })
+
+// A link: to a page by its id, to a path with mode 'internal', to anything else with mode 'external'.
+link({ href: 'about' }); link({ href: '/games/nebula', mode: 'internal' }); link({ href: 'mailto:hi@x.com', mode: 'external' })
+```
 
 ## References
 
@@ -80,10 +158,16 @@ The published `.d.ts` is the reference for every factory, field and step builder
 | --- | --- |
 | [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
 | [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
-| [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, loading/empty/error states, live data, caching, showing and hiding |
+| [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
+| [lists.md](reference/lists.md) | Rendering rows, filtering and sorting them, a detail page for one record |
+| [validation.md](reference/validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
+| [authoring-errors.md](reference/authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
 | [templates.md](reference/templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
-| [flows.md](reference/flows.md) | Clicks, submits, page loads, server actions, modals, state |
+| [flows.md](reference/flows.md) | Clicks, submits, page loads, server actions, realtime channels, modals, state |
+| [plugins.md](reference/plugins.md) | A component of your own: props, binding them, writing state, channels, registering |
 | [structure.md](reference/structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
-| [testing.md](reference/testing.md) | Handles, visual checks, catching a flash from the first frame |
+| [testing.md](reference/testing.md) | Any test: `inspectPage` (one call, every problem), handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
+| [performance.md](reference/performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |
 | [templates-and-export.md](reference/templates-and-export.md) | Publishing a template; turning an exported JSON into code |
+| [accessibility.md](reference/accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
 | [review-checklist.md](reference/review-checklist.md) | Before you say it is done |

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

@@ -0,0 +1,111 @@
+# Usable without sight
+
+A screen reader and a browser agent (Claude in Chrome) read a page the same way. They use the **accessibility
+tree** the browser builds from the markup, where every control is a role and a name. If a control has no name, or a
+click sits on a box that is not a control, those readers can't find it, even though the page looks fine. The linter
+warns about each case below (`control-without-name`, `image-without-alt`, `click-on-static-element`,
+`heading-level-skipped`, `label-ignored`). Fix them the same way you fix any other warning.
+
+## Controls have words
+
+```ts
+// Words of its own: nothing to add.
+button({ content: 'Save' })
+
+// An icon only: `title` is its name, and also its tooltip. The icon is hidden from the tree by itself.
+button({ content: '', title: 'Close', children: [fontAwesome({ icon: 'fa-solid fa-xmark' })] })
+
+// Words that do not say what it does — a key hint, a count: `label` is read in their place.
+button({ content: '', label: 'Select (V)', title: 'Select — V', children: [fontAwesome({ icon: 'fa-solid fa-arrow-pointer' }), text('V')] })
+
+// A link around a whole card: without `label` it is announced as every word inside the card.
+link({ href: '/posts/field-notes', mode: 'internal', label: 'Read “Field notes”', children: [ /* cover, topic, title, byline */ ] })
+
+// A field whose design says what it is: the label stays, out of sight.
+formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder: 'Search…' })
+formControl({ name: 'tint', subType: 'color', label: 'Highlight colour', hideLabel: true })
+```
+
+A `placeholder` names only a field you type into, and only until something is typed. A swatch, a date, a select or a
+checkbox always needs its `label`.
+
+## Pictures say what they show, or that they only decorate
+
+```ts
+image({ src: '/team.jpg', alt: 'The team at the 2026 offsite' })   // what it shows, for this page
+image({ src: '/grain.png', decorative: true })                      // an ornament: left out of the tree
+image({ decorative: true, bind: { src: 'post.record.cover' } })     // a cover under its own headline adds nothing
+image({ bind: { src: 'row.item.cover', alt: 'row.item.title' } })   // …unless it is alone in a link: then it names it
+fontAwesome({ icon: 'fa-solid fa-triangle-exclamation', label: 'Overdue' })  // an icon that says something alone
+```
+
+## Clicks go on controls
+
+A `button` holds children, so a clickable card is a button with the card's class:
+
+```ts
+button({
+  content: '',
+  class: planCard,
+  children: [text('Pro', { class: planName }), text('12 € a month', { class: planPrice })],
+  flows: [[onClick(), setState({ key: 'plan', type: 'text', value: 'pro' })]]
+})
+```
+
+Never put a click on a `container`, `text`, `image` or list item. A keyboard can't reach it, and a browser agent
+won't find it among the page's controls. A button's children are its name, so keep headings, links and other
+buttons out of it. If a card needs any of those, make its title a link and let the rest of the card be plain
+content. An empty backdrop that closes a panel is fine, because the panel's close button and Escape are the ways
+everyone has.
+
+A filter chip, a tab you built yourself, a row that selects: all of them are buttons. Remember that a class starts
+with the SDK button look (padding, radius), so reset what you don't want.
+
+A dropdown opens from a button too: put one among its children, outside the popup. The dropdown marks it
+(`aria-haspopup`, `aria-expanded`) and moves the focus into the menu and back out.
+
+```ts
+dropdown({ children: [dropdownPopup({ children: [ /* menu entries: buttons or links */ ] }), button({ content: '', title: 'Account', children: [avatar] })] })
+```
+
+## State is said, not only styled
+
+```ts
+button({ content: 'Grid', bind: { ariaPressed: 'computed.gridOn' }, class: chip })        // a toggle
+button({ content: 'Menu', bind: { ariaExpanded: 'state.menuOpen' }, flows: [[onClick(), toggleState({ key: 'menuOpen' })]] })
+```
+
+An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both.
+
+## The page has an outline
+
+- Headings go down one level at a time: h1, then h2, then h3. The class sets the size, so an `h2` can look small.
+- Landmarks are containers with a tag: `header`, `nav`, `main`, `aside`, `footer`. When a page has two of one kind,
+  give each a `label`: `container({ subType: 'nav', label: 'Docs sections' })`. A `section` with a `label` becomes a
+  region an assistant can jump to.
+
+## Illustrations
+
+A mock of a page, a diagram, some art built from elements: `container({ decorative: true, children: [ … ] })`. The
+readers skip it, and the linter asks nothing of what is inside, except that nothing in it can be tabbed to
+(`control-in-decorative`). Whatever it lets a mouse do needs a real control somewhere else.
+
+## Built in, nothing to add
+
+Modals and dialogs (named by their title; they take the focus, keep Tab inside and close on Escape), tabs (arrow
+keys), a field's error (marked invalid and described by its message), the pager's current page, and the theme
+toggle's pressed option.
+
+## A canvas or a plugin
+
+Anything drawn on a canvas is one picture to these readers. Render what it shows as elements too: a list with a
+named button per action. Keep that list visible when someone asks for it, because an agent clicks by position and
+can't click something that only appears on focus. See `docs/en/accessibility.md` and Pizarra's List view.
+
+## Checking
+
+- `authorSpace` warnings: zero, as always.
+- In a test, `page.getByRole('button', { name: 'Close' })` fails when the name is missing.
+  `expect(locator).toMatchAriaSnapshot(…)` pins the whole outline.
+- Through MCP, `plitzi_screenshot` with `view: "accessibility"` returns the page's tree and lists everything that has
+  no name.

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

@@ -0,0 +1,70 @@
+# When `authorSpace` refuses
+
+`authorSpace` checks the whole declaration before it writes anything, and stops at the first thing that would not
+render as written. The message names the element (`Element "text" (price) at shop/home/0/2`) and what to write
+instead. **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.
+
+The one exception is a TEST fixture whose subject is the break itself — how the runtime copes with a document no author
+would write. It names that break, and only that one: `authorSpace(spec, { allow: [{ code, element, why }] })`. See
+[testing](testing.md#spaces-written-for-a-test). A space anybody visits never has an `allow`.
+
+## Refused
+
+| The message says | What was wrong | Write instead |
+| --- | --- | --- |
+| `has "x", which it does not take` | a field the space, a page, an element, a binding or a step does not have | the field it suggests; an element's attribute goes inside the factory's props (`button({ content })`) |
+| `sets "x", which a "button" never reads` | an attribute the element does not have | one it lists; an event (`onClick`) is a flow: `flows: [[onClick(), …]]` |
+| `` `subType` is "h7" … It is one of `` | a value outside the attribute's list | one of the listed values |
+| `reads it as true or false` / `as a list` | text where a flag or a list is read | `disabled: true`, not `'true'`; `items: [ … ]` |
+| `holds none` | children on a type that renders only its own attributes | a `container` (for a heading made of parts, `container({ subType: 'h1', children })`) |
+| `the template … cannot be read as written` | a template with an operator, filter or function that does not exist, or broken syntax | see [templates](templates.md) for what exists; `matches` never does |
+| `reads "x", which nothing here answers to` | a name in a template that is not a source, a variable or a route param | the full source name (`list_rows.item`), `navigation.queryParams.x` for a query param, `source` for the bound value |
+| `is not around it` | a source read by an element that is not inside the element publishing it | move the element inside it, or share the value through `state` |
+| `lands on "x", which a "text" never reads` | a binding onto an attribute the element does not have — the value arrives and nothing shows it | one it lists (`content`); to follow data with a class, bind `styleSelectors.base` in `initialState` |
+| `no element answers to the name "x"` | a binding whose source names an element that does not exist | the id of the element that publishes it |
+| `renders text — and "items" holds a list` | a text template feeding a list | `bindTemplate('items', src, '{{ … }}', { returns: 'value' })` |
+| `which a "x" never fires` / `never answers to it` | a flow on an event, or a step to an action, the element does not have | the element that fires it (the message names it); for a plugin, a name its declaration has — `declaredTrigger` / `declaredCallback` make a wrong one a compile error |
+| `does not start with its trigger` | a flow whose first step is not the event that runs it | `[onClick(), setState(…)]` |
+| `step "x" has the param "y"` / `"type" is "string"` | a step param that does not exist or a value outside its options | the params and values it lists |
+| `step "setState" sets "x" on "y", which a "z" never reads` | an element `setState`/`toggleState` writing a field the element does not have | an attribute it lists, or for `category: 'state'` `visibility` / `styleSelectors.<selector>` |
+| `names the page "x", and no page has that id` | a link or `navigate` to a page id that does not exist | an existing page id, or a path with its slash (`'/about'`) |
+| `a full URL, in page mode` | a URL, `mailto:` or `tel:` in a link left in page mode | `mode: 'external'` |
+| `is a controlled list with no items` | a list with nothing to render | `items: [ … ]` or `bind: { items: 'provider.data.rows' }` |
+| `` has items, but its `source` is "none" `` | a list whose items nothing reads — it renders its children once | `source: 'controlled'` |
+| `answers at /x for the same visitors as page` | two pages at one address | another slug — or `accessLevel` `'public'` on one and `'authenticated'` on the other |
+| `is not one CSS value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
+| `computed … declared after it` / `does not compute` | a computed value read before it is declared, or never declared | declare it in `computed`, above the one that reads it |
+
+## Warned
+
+A warning means the space renders, and renders something you probably did not mean. Fix every one.
+
+| Code | Meaning | Fix |
+| --- | --- | --- |
+| `condition-starts-visible` | a computed visibility shows until its data answers | `visible: { source, template }` |
+| `template-never-resolved` | a condition in an attribute, used as written | move it into `bindTemplate` |
+| `tablet-rule-skips-mobile` | a tablet rule phones never get | write it under `compact` |
+| `default-content-beside-children` | a button prints "Button" beside its children | `content: ''` |
+| `overlay-starts-open` | a modal or dialog is open when the page loads | `visible: false`, opened by `openModal` |
+| `provider-without-source` | an `apiContainer` asks nothing | give it a `query` (or `action`, `connector`, `resource`) |
+| `unknown-element-type` | a type no built-in element has | the built-in it suggests; a plugin's DECLARATION goes in `authorSpace(space, { plugins: [declaration] })`, which also checks its events, actions and attributes |
+| `colour-without-dark` | a colour token with no dark value | `{ light, dark, default }` |
+| `FORM_SUBMIT_UNMANAGED` | a form the browser would submit itself | `managedByInteractions: true` |
+| `STYLE_WITHOUT_TAG` | style on a provider that renders no element | `subType: 'div'` on the provider, or style its parent |
+| `server-data-without-rsc` | a `runtime: 'server'` provider with a `connector` or `action` in a space that does not turn server data on — it renders its mock data | `rsc: { enabled: true }` on the space |
+| `route-param-undeclared` | `navigation.routeParams.x` read on a page whose slug has no `:x` — always empty | add `:x` to the slug, or read `navigation.queryParams.x` |
+| `form-control-unnamed` | a control in a form with no `name` — its value never reaches `values` | `formControl({ name: 'email', … })` |
+| `form-control-name-taken` | two controls in one form with one name — one overwrites the other | a name each |
+| `while-running` | `whileRunning` on a step that is not the trigger, or a value other than `skip`, `parallel`, `queue` | `[whileRunning('queue', onClick()), …]` |
+| `trigger-keys` | an `onKey` flow whose `keys` cannot fire: two keys in one shortcut, only modifiers, or a name that is not a key | `onKey('f')`, `onKey('shift+f')`, `onKey('mod+k, escape')` |
+| `state-toggled-in-branches` | two `setState` steps of one key, each under a `when` on that key — the second flips back what the first wrote | `toggleState({ key })`; for something shown by default, a key named for hiding it |
+| `form-value-compared-to-blank` | a `when` asking whether a submitted field (`….values.x`) `=` or `!=` `""` — a field nobody typed in is not sent, so it never matches | `operator: 'empty'` / `'notEmpty'` |
+| `overlay-never-opened` | a modal or dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
+| `control-without-name` | a button or link with no words (an icon, a picture without `alt`, nothing), or a field nothing names — a screen reader says just "button", a browser agent cannot find it | `title` on the button, `label` on the link, `label` (with `hideLabel: true`) on the field — see [accessibility](accessibility.md) |
+| `image-without-alt` | an image that is not `decorative` and has no `alt` | say what it shows, or `decorative: true` |
+| `click-on-static-element` | a click flow on a container, text, heading, image or list item — no keyboard reaches it, no agent finds it | the flow on a `button` (it holds children) or a `link` |
+| `heading-level-skipped` | an `h4` right after an `h2` on a page — the outline misses a level | the next level down; size it with its class |
+| `label-ignored` | a `label` on a container whose tag is named by what it holds (`li`, a heading) | the words inside, or a landmark tag (`nav`, `section`, …) |
+| `dropdown-without-control` | a dropdown opened from a box or an icon — no keyboard opens it | a `button` as what opens it (`title` if it is only an icon) |
+| `control-in-decorative` | a control inside a `decorative` container — Tab lands on something nothing announces | move it out of the illustration |

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

@@ -3,11 +3,16 @@
 ## Bindings
 
 ```ts
-heading({ bind: { content: 'posts.title' } })                     // short form: attributes
-text({ bind: [{ to: 'content', source: 'stats.data.total',        // full form: anything else
-  transformers: [{ action: 'twigTemplate', params: { template: "{{ source|number_format(0, '.', ',') }} views" } }] }] })
+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.
@@ -17,8 +22,29 @@ The binding's `source` is completed for you; its template is read as written, so
 
 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) and `theme`
-(`mode`, `resolved`).
+`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
 
@@ -29,10 +55,21 @@ 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.
+  `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
@@ -62,28 +99,28 @@ modalContainer({ visible: false, … })           // starts hidden; a flow opens
 | 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: false` — so it waits hidden — plus a visibility binding with a template:
+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: false,
-  bind: [{
-    to: 'visibility',
+  visible: {
     source: 'stats.data.totals',
-    category: 'initialState',
-    transformers: [{ action: 'twigTemplate', params: {
-      template: "{{ source ? (source.spaces > 0 and source.published > 0 ? 'false' : 'true') : 'false' }}"
-    } }]
-  }]
+    template: '{{ source and not (source.spaces > 0 and source.published > 0) }}'
+  }
 })
 ```
 
 Rules for a condition's template:
 
-- **A revealing condition starts hidden with `visible: false`.** A visibility binding alone 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 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'`);
@@ -99,7 +136,7 @@ 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 ? 'true' : 'false' }}` over the list |
+| 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 |
 
@@ -112,3 +149,32 @@ shows on every load. Test for "arrived and empty" (`is defined and … is empty`
 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

@@ -17,13 +17,14 @@ container([hero, grid])             // an array is the children
 | `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`… beside the element's own `css` |
+| `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'`), or `false` to start hidden |
+| `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 |
 
@@ -31,8 +32,21 @@ Anything else in the object is an **attribute** (`authorSpace` warns `unknown-at
 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}}`; `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.
+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.
@@ -42,7 +56,16 @@ children sit in the parent's layout and a `class` on it styles nothing (`STYLE_W
 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)`.
+`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
 
@@ -51,8 +74,11 @@ outside the vocabulary is refused with the key it should have been (`paddingTop`
 
 - `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. Write it in both; `authorSpace` warns
-  `tablet-rule-skips-mobile`.
+  `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'] }`).
 
@@ -77,9 +103,37 @@ container({ class: card, children: [ … ] });
   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' ?