@plitzi/sdk-server 0.37.1 → 0.37.3

package/skills/plitzi-authoring/SKILL.md

@@ -1,283 +1,173 @@
 ---
 name: plitzi-authoring
 description: >-
-  Write a Plitzi space or a publishable template in TypeScript — pages, elements, CSS, data bindings and flows —
-  instead of hand-writing schema JSON. Use whenever the task is to create, extend or re-theme a space: adding a
-  page or a section, styling one, binding an element to server data, wiring what happens on click, authoring a
-  template to host, or turning an exported JSON into something maintainable.
+  Write or change a Plitzi space or template in TypeScript with @plitzi/sdk-authoring — pages, layouts, elements,
+  CSS classes, data bindings, providers and flows — instead of hand-writing schema JSON. Use whenever the task is to
+  create, extend, restyle or fix a space: adding a page or a section, sharing a header across pages, binding an
+  element to data, showing or hiding something, wiring what happens on click, or turning an exported JSON into code.
 ---
 
 # Authoring Plitzi spaces
 
-A Plitzi space is two documents — a schema and a style — of deeply cross-referenced ids. **Do not write them by
-hand.** Every id, class name, parent/root link, breakpoint map and interaction chain is derived from a much
-smaller declaration, and the surface that derives them also refuses a declaration that would not render.
+A space is two JSON documents — a schema and a style — full of cross-referenced ids. **Never write them by hand.**
+`@plitzi/sdk-authoring` derives every id, class name, parent link, breakpoint map and flow chain from a small
+declaration, and refuses a declaration that would not render.
 
 ```ts
-import { authorSpace, container, heading, text } from '@plitzi/sdk-authoring';
+import { authorSpace, container, heading, styles, text } from '@plitzi/sdk-authoring';
 
-const { schema, style, warnings } = authorSpace({
+const page = styles('page', { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' });
+
+export const space = {
   name: 'My space',
   permanentUrl: 'my-space',
-  classes: { page: { desktop: { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' } } },
-  pages: [
-    { name: 'Home', slug: '', class: 'page', body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }
-  ]
-});
-```
-
-Serve it with the adapters the page server already takes:
+  pages: [{ name: 'Home', slug: '', class: page, body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }]
+};
 
-```ts
-createServer({ port: 3001, adapters: createJsonAdapters({ offlineData: { schema, style } }) });
+const { schema, style, warnings } = authorSpace(space);
 ```
 
-One package, and it installs nothing: `@plitzi/sdk-authoring` has an empty dependency tree, no React and nothing
-that touches a browser, so a seed, a migration, a build script or a project that only publishes templates depends
-on it alone.
-
-## The types are the reference
-
-Every factory, spec field and step builder carries its documentation in the published `.d.ts`. Read it rather
-than guessing — `node_modules/@plitzi/sdk-authoring/dist/index.d.ts` is the whole surface in one file. Attribute
-types come from each element's own component, so an editor completes them and a wrong value is a compile error.
-
-## Elements
-
-One factory per element, named after it. Attributes and the authoring fields go in ONE flat object:
+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. 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`. 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 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.
+
+## The rules that matter most
+
+1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
+   namespace for the whole space — layouts and every page share it — so an element built by a helper that runs more
+   than once gets its id prefixed by what it is for: `` `${pageId}-foot` ``.
+2. **Share with classes and layouts, never with copies.** A look used twice is a `styles()` class. Chrome shown on
+   several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A menu, a card grid,
+   a list of steps is DATA mapped to elements (`entries.map(entry => link(…))`), not a block pasted per item. See
+   [layouts and duplication](reference/layouts.md).
+3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
+   refuses the pair. A look that never changes is its own class.
+4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
+   the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
+   `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
+   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 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 under `compact`.
+9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
+   an empty state, not a placeholder figure. With no backend, the data is JSON the project serves
+   (`public/data/*.json`) read by an `apiContainer` — see [data and visibility](reference/data-and-visibility.md).
+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
-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
+// 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' })
 ```
 
-| 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. **Name anything something else refers to**: a derived `<type>-<n>` is positional |
-| `class` | a shared class: a name from the space's `classes`, or a `styles()` declaration. Exclusive with `css` |
-| `css` | rules of this element's own: one set, or one per breakpoint (`{ desktop, tablet, mobile }`) |
-| `variant` | a style variant of the element's own vocabulary |
-| `slots` | a class for one of the element's OTHER selectors — a form control's `input`, `label`, `error` |
-| `bind` | where a value comes from |
-| `visible` | show it only while this source is true; `!source` for the inverse |
-| `flows` | what happens on click, on submit, on load |
-| `runtime` | `'server'` resolves this element's data on the server |
-| `children` | the tree |
-| `meta` | `meta.label` is the element's name in the builder's tree |
-
-Anything else in the object is an **attribute**. `label` belongs to the attribute (a link and a form control both
-have one); the builder's name for the element is `meta.label`.
-
-A type this SDK does not ship — a plugin, one the deployment brings — is authored the same way:
-
-```ts
-const speciesStatus = defineElement<{ status?: string }>({ type: 'speciesStatus', content: { … } });
-element<{ status?: string }>('speciesStatus', { status: 'vulnerable' });   // or one at a time
-elementsFromManifest(manifest);                                            // or a whole plugin manifest
-```
-
-## Style
-
-Write CSS the way you write CSS, shorthands included — they are expanded before they reach the document, because
-Plitzi's style editor reads a closed list of longhand properties:
-
-```ts
-css({ padding: '96px 24px', border: '1px solid var(--line)', 'border-radius': '12px' })
-```
-
-You rarely call `css` yourself: `authorSpace` runs every rule set through it. What you get is the refusal — a
-property outside the vocabulary is an error naming the correct key (`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 and `mobile` is below 48rem, and each inherits
-  only from `desktop` — a rule written for `tablet` never reaches a phone. A grid that collapses to one column at
-  tablet and should stay collapsed says so in `mobile` too. `authorSpace` warns (`tablet-rule-skips-mobile`) when it
-  does not.
-- **Fonts are declared, not assumed.** A `font-family` loads only if the space lists the face in `fonts`
-  (`{ source: 'google', family: 'Fraunces', fallback: 'Georgia, serif', weights: [400, 600], styles: ['normal'] }`);
-  the page server writes exactly that list into the document, and anything else renders in the fallback.
-- Per element TYPE defaults go in `elements: { heading: { base: …, states: { … }, variants: { … }, slots: { … } } }`
-  — `slots` dresses the type's other selectors (a modal's `rootContainer`) for every element of the type.
-- **`:hover` is part of the selector, not a rule in `customCss`.** `styles('card', { css: { … }, states: { hover: { … } },
-  variants: { active: { … } } })`, and `states` beside an element's own `css`. Written in `customCss` it renders and
-  then cannot be read back or edited per breakpoint.
-
-**Share a rule as a class, never as a spread.** Writing a rule set once in a `const` and spreading it into each
-element's `css` shares the source and duplicates the document — one selector per element, so re-theming the card
-in the builder re-themes one card. `styles()` declares the class where it is used and writes it once:
-
-```ts
-const card = styles('card', { padding: '24px', 'border-radius': '12px', 'background-color': 'var(--surface)' });
-
-container({ class: card, children: [ … ] });
-```
-
-Accepted anywhere a class name is — `class`, a `slot`, a page's `class` — and collected from wherever the tree
-names it. One name declared twice with rules that disagree is refused. `classes` at the top of the space is the
-same mechanism for what describes the space rather than one section of it.
-
-An element has exactly ONE base selector, so a look that never changes is its own class over a shared plain object
-(`styles('button-primary', { ...base, … })`), never two classes layered on top of each other. A class's `variants`
-are for what the page switches while it runs — a binding with the `styleVariant` transformer picks one.
-
-**Shells go in `layouts`.** A header or a sidebar every page shows is a layout the pages name —
-`layout: { id: 'app-shell', slot: 'main' }`, the slot being the element in the shell where the body goes — never a
-copy on each page. `visible: false` starts an element hidden for a flow to reveal.
-
-## Data
-
-```ts
-heading({ bind: { content: 'posts.title' } })            // short form: attributes
-paragraph({ visible: 'posts.hasPosts' })                // on screen only while this is true
-paragraph({ visible: '!posts.hasPosts' })               // …and its inverse
-container({ bind: [{ to: 'content', source: 'x.y', transformers: [ … ] }] })   // full form
-```
-
-**A source names the id you gave the element** — `'posts.title'`, `'postList.item.cover'` — and the prefix is
-filled in. Only half of a source name is yours: the other half is the kind of source the ELEMENT publishes, and it
-is not always the word you can see (a `form` publishes under `apiContainer`). The four globals — `variables`,
-`navigation`, `auth`, `state` — are named as themselves. A full name still works and is checked the same way: a
-prefix that does not match the element, or a name nothing answers to, is refused when the space is authored. It
-is the quietest failure a space can carry.
-
-Server-resolved sections are an `apiContainer` with `runtime: 'server'` naming a connector or an action, and a
-space that has any needs `rsc: { enabled: true }`.
-
-**A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own while its
-`subType` is empty — the default, the builder's "Container Tag: None" — so its children sit directly in the parent's
-layout. That is usually what you want (the provider stays invisible to the layout), and it means a `class` or `css`
-on it styles nothing: the `gap` you wrote between its sections is simply not there. Put the layout on the parent, or
-give the provider a tag (`attributes: { subType: 'div' }`) when it should be the box. `validateSpace` — and so
-`authorSpace` and the MCP — warns with `STYLE_WITHOUT_TAG`.
-
-**Never ask the data for a field's opposite.** Both sides of one question are `visible: 'x'` and `visible: '!x'` —
-not an `x` and a `notX` beside it in the server's answer. The `!` is the `not` transformer, which reads a boolean
-that travelled as text (`"false"`, `"0"`) and treats an empty array as false; an empty object is true. Only for a
-real inverse — a three-state condition (`Boolean(post) && !canEdit`) still belongs where the data is made.
+## References
 
-## Flows
-
-```ts
-button({
-  id: 'cta',
-  content: 'Get a quote',
-  flows: [[
-    onClick(),
-    named('quote', runServerAction({ actionId: 'shipping-quote', input: '{"city":"Berlin"}', mode: 'await' })),
-    setState({ key: 'quote', type: 'text', value: '{{quote.output.summary}}' })
-  ]]
-})
-```
-
-Use the step builders — they answer the three things that go wrong silently:
-
-- **Where a step runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an
-  element callback under an element's id, a utility under nothing. The builders fill it in; a trigger and an
-  untargeted `updateElement` are filled with the element the flow was declared on.
-- **Which `setState`.** `setState(…)` writes `runtime.state.<key>`; `updateElement(…)` changes one element's own
-  attribute or state. Different params, different node kind. Each has a flip-it counterpart storing the opposite
-  of what is there, which is how expand/collapse is ONE step on ONE trigger: `toggleState({ key })` for app state,
-  and `toggleElement({ category: 'state', key: 'visibility' }, 'panel')` to show/hide an element (the second
-  argument is the element it acts on; omitted, it acts on the one the flow is declared on). Never two branches
-  under opposite `when` guards — those read the state as it was when the flow STARTED, so they run a click behind.
-- **What it takes.** Params are typed from the same declaration the builder's own panel is drawn from.
-
-`named(id, step)` is how a later step reads an earlier one — the flow scope is keyed by node id, so
-`{{quote.output.summary}}` resolves only when that step is called `quote`. `mode: 'await'` is what puts a run's
-answer in the scope at all, and it is the default.
-
-**Pass `input` as an object, not as a line of JSON text.** Both are accepted, and the text form fails silently: an
-interpolated value carrying a quotation mark or a newline — a post body, a comment — makes it unparseable, and
-unparseable input posts `{}` rather than refusing.
-
-A flow is a list and never a tree, so "only if" is expressed on the step:
-
-```ts
-whenSucceeded('quote', navigate({ urlType: 'internal', url: '{{quote.output.url}}' })),
-whenFailed('quote', setState({ key: 'notice', type: 'text', value: '{{quote.reason}}' })),
-when({ field: 'state.count', operator: '>', value: 3 }, addNotification({ content: 'Enough' }))
-```
-
-`whenFailed` matches every outcome that is not `completed` — a run also comes back `skipped` or `aborted`, and
-matching only `failed` is how those two end up doing nothing.
-
-## What gets refused
-
-`authorSpace` throws rather than hand back a space that would not render:
-
-- a CSS property the style editor could not read back
-- a `class` or a `slot` naming a class the space does not declare (the error names the one you probably meant)
-- an element asking for a shared class AND rules of its own — an element has one base selector
-- one class name declared twice with rules that disagree
-- a binding source naming an element nothing answers to, or one whose prefix is not what that element publishes
-- a name that shadows a global data source (`variables`, `navigation`, `auth`, `state`)
-- a step target naming an element that is not there
-- two elements answering to one name, a broken flow chain, an orphan, a cycle
-- a global callback on the wrong module — or on none — and a utility given one. A global callback registers under
-  its SOURCE MODULE (`auth`, `state`, `actions`), and the pair is what the runtime resolves a step by, so naming
-  either half wrong is a control that does nothing at all with no error anywhere. An action no built-in source
-  declares comes back in `warnings` instead of throwing, because a plugin may register a module of its own.
-
-Those last checks need the vocabulary, which only the composed package has. Import `authorSpace` from
-`@plitzi/sdk-authoring` — not straight from `@plitzi/sdk-schema` — and you get them.
-
-For documents you did not author here — an export from the builder, a JSON edited by hand — run the same gate
-before serving it:
-
-```ts
-const { valid, errors, warnings } = validateSpace({ schema, style });
-```
-
-## Templates
-
-A template is not a space: it is ONE subtree, the style that dresses it and a name, published as a JSON someone
-fetches by URL and drags onto a canvas you will never see.
-
-```ts
-import { authorTemplate } from '@plitzi/sdk-authoring';
-
-const { template, warnings } = authorTemplate({
-  name: 'Pricing card',
-  description: 'A price, a list of features and a call to action.',
-  classes: { card: { padding: '24px', 'border-radius': '12px', 'background-color': 'var(--surface)' } },
-  root: container({ class: 'card', children: [heading('$19', { subType: 'h3' }), button({ content: 'Start' })] })
-});
-
-await writeFile('pricing-card.json', JSON.stringify(template, null, 2));
-```
-
-Host that file and add it to a space's resources as an `application/json` — nothing else is required of you.
-
-Everything a space is held to still applies, and two more things apply because a template LEAVES its space:
-
-- **Everything it names, it carries.** A class declared in the space it was cut from does not travel; the element
-  keeps the class name, finds no rules wherever it is dropped, and renders unstyled. Declare in `classes` (or with
-  `styles()`) every rule the subtree names — `validateTemplate` warns about a name the manifest does not carry.
-- **A binding may not point outside the subtree.** A source names an element by id, so binding to a provider
-  that stayed behind is dead on arrival — refused. Bring the provider (the `apiContainer`, the `form`) into the
-  template, or bind to one of the globals: `variables`, `navigation`, `auth`, `state`.
-
-`validateTemplate(template)` runs the same gate over a manifest you did not author here — one exported by the
-builder, or edited by hand — before you publish it.
-
-## From an exported JSON
-
-Never rewrite an exported space by hand. `specFromSpace({ schema, style })` reads it into the spec that authors it,
-repairing what an older builder left behind and listing each repair in `corrections`; `specToSource(spec,
-{ exportName })` writes that spec as factory calls; `compareSpaces(original, authorSpace(spec))` must list nothing but
-what `corrections` explains. The builder's **Export** (and `POST /utils/transform-to-authoring`) does all three. Edit
-the code it writes from then on, not the JSON.
-
-## Rules
-
-1. **Never hand-write `flat`, element ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`.** They are derived.
-   Writing them is how a space half-renders with nothing reporting why.
-2. **Name what is referred to.** `id` on any element a binding, a step or a pager addresses.
-3. **Read the error.** Every refusal above names the element, the class or the property at fault; it is a bug in
-   the declaration, not a reason to work around the check.
-4. **Ids are stable.** They are hashes of the path that produced them, so re-authoring an unchanged space writes
-   byte-identical documents — a seed can re-run and a diff stays readable.
-5. **`warnings` is returned, not printed.** Read it if the space is generated in a build.
+| Read | When |
+| --- | --- |
+| [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, 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, 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) | 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 |