@plitzi/sdk-server 0.37.1 → 0.37.3

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

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

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

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

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

@@ -0,0 +1,167 @@
+# Plugins
+
+A plugin is a React component of the project's own — a chart, a map, a game — hosted in the space by a `custom`
+element that names it by `renderType`:
+
+```ts
+custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best: 'state.arcadeBest' } })
+```
+
+## Creating one
+
+The CLI writes it, in the shape Plitzi's own elements are written in:
+
+```bash
+npx @plitzi/cli add plugin seat-picker legend # elements of this project (src/plugins/<Name> in a CLI project)
+npx @plitzi/cli create seat-picker --plugin   # a package of its own, with a preview
+npx @plitzi/cli pack plugin                   # built, with its manifest and the zip the builder takes
+```
+
+One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
+`callbacks` it answers to, and the element the builder adds — data only), `Settings.tsx` (its panel in the builder), and
+`index.ts` (`Object.assign(Component, declaration, { pluginSettings: Settings })`). An event or an action is declared in
+`declaration.ts` and registered by the component from there, never only in the component.
+
+A plugin fires its events with `interactionsManager.interactionTrigger(id, action, payload)` whenever it has news —
+from its first effect too: a flow starts once the page has finished mounting, so the `setState` it calls is there. No
+`queueMicrotask` or delay of your own. An event that REPORTS a state, and may fire again before its flow ends (as a
+component reads its real value right after mounting), wants `whileRunning('queue', …)` on the flow: by default a firing
+while the flow runs is dropped, and the stale first report would stick.
+
+## Props
+
+**The host element's attributes ARE the component's props.** Whatever the space writes on the `custom` element arrives
+by the same name, and so does whatever a binding writes — which is what makes a plugin live: bind an attribute to
+`state`, a provider or a row, and the component re-renders with the answer. Prefer this to anything else.
+
+`settings` is the other channel: a JSON string whose keys are merged into the props too. It is what the builder's
+panel edits for a plugin it has no controls for; from code, write attributes. A `settings` that is not JSON renders
+"Settings Malformed" in the page.
+
+Every prop is optional and has a default: an attribute not authored yet, or a binding whose source has not answered,
+is `undefined`, and a plugin that renders nothing then is a hole in the page.
+
+## The component
+
+```tsx
+import { RootElement } from '@plitzi/plitzi-sdk';
+
+const NebulaRun = ({ shipColor = 'amber', best = 0, className }: NebulaRunProps) => (
+  <RootElement className={className}>…</RootElement>
+);
+```
+
+- **Render `RootElement`**, not a `div`: it carries the element's id, classes and `data-plitzi-el`, so the CSS
+  authored on the element applies, the builder can select it and a test can find it.
+- **Render the same thing on the server and on the first client pass.** A clock, a random number or anything read from
+  `window` belongs in an effect; a hydration mismatch discards the whole tree, not the plugin.
+- **Borrow colours.** `currentColor` and the space's `var(--…)` tokens follow the theme; a hard-coded colour is
+  invisible in one of them. A canvas reads them with `getComputedStyle(element).getPropertyValue('--accent')` and
+  again when `theme.resolved` changes (bind it as a prop).
+
+## Writing to the space
+
+A plugin that produces something the page shows — a score, a selection — writes it to `runtime.state`, where every
+binding reads it:
+
+```ts
+import { getStateManager } from '@plitzi/plitzi-sdk';
+
+const state = getStateManager();
+state.setStateByKey('arcadeBest', Math.max(score, Number(state.state.arcadeBest ?? 0)));
+const stop = state.subscribe(next => save(next));      // called after every change; call `stop()` to leave
+```
+
+`state` is the current value, `setState` replaces it (or takes an updater), `setStateByKey` writes one key,
+`clearState` empties it, `subscribe` listens. Bindings on `state.*` re-render at once.
+
+## Talking to other pages
+
+A plugin that moves at the speed of a cursor reads a realtime channel through `useChannel` rather than through flows —
+messages arrive through a callback and re-render nothing:
+
+```tsx
+import { useChannel } from '@plitzi/plitzi-sdk';
+
+const room = useChannel(roomTopic, { onMessage: message => move(message.from, message.data) });
+room.publish('pointer', { x, y });   // throttle it: ~20 a second, the latest position each time
+room.members;                        // who is here, with the state each announced
+```
+
+Take the topic as a prop (`bindTemplate('roomTopic', 'board.id', 'room:{{ source }}')`) so the space names its
+channels, and trust a message you act on only when `message.from === 'server'`. The page has one connection and is one
+member per topic, however many elements and plugins listen.
+
+## Registering
+
+A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in
+camelCase (`StatCard` → `statCard`). Anywhere else, the entry registers the component under its `renderType`: the
+third argument to `render()`, `<PlitziSdk.Plugin>` in a React application, `plugins` on a page server of your own. A `renderType` nothing registered
+renders "Custom Component … Not Found", and a page server logs the missing `renderType` at `error` once per
+space: on a server, register it in `plugins` AND name it in the deployment's `pluginNames`.
+
+A plugin PACKAGE, loaded by a space from its `plugin-manifest.json`, is an element TYPE of its own rather than a
+`custom` host — it is how the builder adds one somebody dropped. Author it with a typed factory:
+`defineElement<SeatPickerAttributes>(declaration)` from the plugin's own `declaration.ts`, or
+`elementsFromManifest<{ seatPicker: SeatPickerAttributes }>(manifest)` from what it published — or untyped,
+`element('seatPicker', { id: 'seats', start: 3 })`.
+
+## Checked like a built-in element
+
+Hand `authorSpace` the plugin's DECLARATION — the `declaration.ts` beside the component, or a manifest's
+`pluginSchema` entry:
+
+```ts
+import declaration from './plugins/SeatPicker/declaration';
+
+authorSpace(space, { plugins: [declaration] });
+```
+
+It is then held to what it declares, whether it is authored as its own type or hosted by `custom({ renderType:
+'seatPicker' })`: a flow on an event it never fires, a step sent to an action it does not answer, an attribute it does
+not read — each is refused with the name it should have been. (`pluginTypes: ['seatPicker']` only tells the linter the
+type exists; nothing about how the space uses it is checked.) A `custom` host whose component is NOT handed over is not
+judged on its events at all — nothing here knows them.
+
+Its events and actions have builders typed from the same declaration, so a name it does not declare is a compile error:
+
+```ts
+seats({ id: 'seats', flows: [[named('picked', declaredTrigger(declaration, 'onPick')), setState({ key: 'seat', type: 'text', value: '{{ picked.seat }}' })]] })
+button({ content: 'Clear', flows: [[onClick(), declaredCallback(declaration, 'reset', { on: 'seats' })]] })
+```
+
+A plugin says what HAPPENED through its events (`onPick`, with the seat in the payload) and lets the space's flows
+decide what that means — write `state`, open a modal, call a server action. Prefer that to writing `state` from inside
+the component: the flow is visible in the space, the builder shows it, and the same act can come from a button too.
+
+## Components that draw into DOM they do not render
+
+A map, a chart library, anything that positions its own markers or popups: its roots are the library's to place. Never
+give them a class that sets `position` — the element falls into the page's flow, offset by every marker before it. Put
+the look in the plugin's own stylesheet (imported CSS ships beside the bundle) and take colours from custom properties
+the space sets (`--seat-accent: var(--accent)` in `customCss`); a canvas or WebGL layer resolves them through a probe
+element with `getComputedStyle(probe).color`, again whenever `theme.resolved` changes (bind it as a prop).
+
+## Components that draw a lot
+
+A canvas with thousands of shapes on it — a whiteboard, a diagram, a map of points — is judged on a slower machine than
+yours: sixty frames a second here says nothing about a four-year-old laptop. What keeps one fast is doing work in
+proportion to what CHANGED, not to what is there:
+
+- **Two layers.** Paint what stands still on one canvas and leave it; clear and draw the one over it every frame, with
+  only what moves: the cursor, the selection, what is being dragged.
+- **Repaint the part that changed.** Something added, edited or removed repaints the area it was and is in, clipped,
+  with whatever reaches into it — not the whole board. A pan moves the picture already painted by whole device pixels
+  and paints the edges it uncovers.
+- **Draw a dragged group once.** Everything picked up moves by the same amount at every step: draw it to a canvas of its
+  own when the drag begins and copy that into place after.
+- **Cache per object, not per frame.** Treat elements as immutable and key what is derived from one — its bounds, its
+  shape, a resolved connector — on the object itself (a `WeakMap`), so nothing is worked out twice for the same thing.
+- **Hand the space outcomes, not motion.** A stroke finished, a selection changed: a trigger each. Firing one at every
+  pointer move runs a flow and renders the page at every pointer move.
+- **Measure with a bench, throttled.** A script that drives the real thing in a browser with the CPU slowed
+  (`Emulation.setCPUThrottlingRate`) and reports script time per frame, not only frames per second — and a test that
+  counts WORK (full repaints, strokes drawn during a drag), which holds on any machine where a timing does not.
+
+Pizarra, the collaborative whiteboard on the platform (`pizarra.plitzi.app`), does all of it on a board of thousands
+of elements.

package/skills/plitzi-authoring/reference/review-checklist.md

@@ -0,0 +1,67 @@
+# Before you say it is done
+
+The feedback a reviewer gives on almost every change to a space, so you can give it to yourself first. Go through all
+of it; each line is something that has shipped broken before.
+
+## It renders, and says so
+
+- [ ] `authorSpace` returns **zero warnings**. Each one is written code that will not do what it says.
+- [ ] No console errors on any page you touched.
+
+## Nothing flashes, nothing jumps
+
+- [ ] Nothing appears only to be taken away while data loads: a condition that REVEALS an element starts hidden and
+      answers `'false'` until its source arrives. Checked from the FIRST frame, not a screenshot at the end.
+- [ ] Nothing that is on screen by default disappears because a flag has not been set yet (a sidebar until it is
+      folded). Checked on a fresh visit, with no state kept from before.
+- [ ] Empty states show only when the answer arrived and is empty — never while loading.
+- [ ] No hidden element leaves a hole: the element itself is hidden, not a wrapper around it.
+- [ ] Nothing shifts when the data lands: a loading area keeps its size, numbers use tabular figures.
+
+## Every screen, every theme
+
+- [ ] Desktop, tablet and mobile — and nothing scrolls sideways on a phone. A rule for tablets and phones alike is
+      written under `compact`.
+- [ ] Light AND dark. Every colour is a token with both values; no theme-following text on a fixed background.
+- [ ] Focus is visible on everything clickable (`focus-visible`), and `prefers-reduced-motion` stops what moves.
+
+## Usable without sight
+
+Screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree. See
+[accessibility](accessibility.md).
+
+- [ ] Every button and link has words — an icon-only button a `title`, a link around a card a `label` — and every field
+      a `label` (`hideLabel: true` when the design shows what it is).
+- [ ] Every image has an `alt` saying what it shows, or `decorative: true`.
+- [ ] Every click is on a `button` or a `link`; the whole page can be worked from the keyboard.
+- [ ] A toggle binds `ariaPressed`, a button that opens something `ariaExpanded`.
+- [ ] Headings step down one level at a time; parts of the page a person jumps to are landmarks (`nav`, `main`, a
+      labelled `section`).
+- [ ] What a canvas or a plugin draws is also there as elements, with a visible way to reach them.
+
+## No copies
+
+- [ ] Chrome shared by pages is a layout; the current menu entry comes from `activeOn`, not per-page styling.
+- [ ] A look used twice is a class; a tree used twice is a function or a `map` over data; a list of pages, links or
+      plans is ONE array everything reads.
+- [ ] No positional ids (`container-45`) in what you wrote; every referenced element is named, prefixed when a
+      helper runs more than once.
+
+## True, and in the right place
+
+- [ ] Every number, name and status on screen comes from a source. No placeholder figures, no invented logos or
+      testimonials. A panel with nothing true to show is an empty state.
+- [ ] Times are formatted with an explicit zone and say which (`… 06:00 UTC`).
+- [ ] Logic lives in binding templates or on the server, not in an attribute (where a condition is never evaluated).
+- [ ] A filtered or sorted list binds its `items` to a template that returns its value — its rows are not hidden one
+      by one.
+- [ ] Every link you wrote was followed at least once: an `href` built from a row goes where it says.
+- [ ] Writes refresh what they changed — and only that (`invalidateQueries`); a multi-step form does not refresh the
+      provider that decides whether to leave.
+- [ ] What only an administrator may read is shown only to administrators — and the check is a real boolean, not
+      a template left as text.
+
+## Proven
+
+- [ ] You looked at it: the visual check ran, on the pages you changed, in both themes.
+- [ ] Both sides of each condition were seen: the empty account and the full one, the admin and the member.

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

@@ -0,0 +1,83 @@
+# Structuring a space that grows
+
+A one-screen space fits in `src/space.ts`. Past a few pages, split it by what changes together — and keep every
+repeated thing in exactly one place.
+
+```text
+src/space/
+  index.ts          the SpaceSpec: name, variables, fonts, layouts, pages — assembly only
+  tokens.ts         colour, shadow and radius variables, each with light and dark
+  styles.ts         classes shared across areas (buttons, panels, page titles)
+  components.ts     functions returning ElementSpec: panel(), statCard(), emptyState()
+  layouts/app.ts    the application shell (+ its own classes)
+  docs/
+    nav.ts          the section's pages as data: id, slug, title, lede, order
+    layout.ts       the section shell, generated from nav.ts
+    page.ts         docsPage(id, content) — the shape every page of the section shares
+  pages/
+    home.ts         one file per page, or per page family
+```
+
+## Components are functions
+
+The same block in two places is a function with parameters. Its ids come from a parameter, because ids are one
+namespace for the whole space:
+
+```ts
+export const panel = (params: { id: string; title: string; sub?: string; link?: { href: string; label: string }; children: ElementSpec[] }): ElementSpec =>
+  container({
+    id: params.id,
+    class: panelCard,
+    children: [
+      container({
+        id: `${params.id}-head`,
+        class: panelHead,
+        children: [
+          heading(params.title, { id: `${params.id}-title`, subType: 'h3', class: panelTitle }),
+          ...(params.sub ? [text(params.sub, { id: `${params.id}-sub`, class: panelSub })] : []),
+          ...(params.link ? [link({ id: `${params.id}-link`, href: params.link.href, class: panelLink, children: [text(params.link.label)] })] : [])
+        ]
+      }),
+      ...params.children
+    ]
+  });
+```
+
+A page then reads as what it shows: `panel({ id: 'hm-traffic', title: 'Traffic', link: { href: 'analytics', label:
+'Open analytics →' }, children: [chart] })`.
+
+## Lists are data
+
+Four quick links, three pricing plans, a sidebar menu, the steps of an onboarding: an array and a `map`.
+
+```ts
+const QUICK = [
+  { id: 'team', icon: 'fas fa-user-plus', title: 'Invite your team', href: 'workspace' },
+  { id: 'docs', icon: 'fas fa-book-open', title: 'Quickstart', href: 'docs-quickstart' }
+] as const;
+
+container({ id: 'quick', class: quickGrid, children: QUICK.map(item => quickCard(item)) });
+```
+
+When items differ in ONE detail (one link needs a binding), put that detail in the item's data as an optional field
+— never an `if (item.id === 'team')` inside the map.
+
+## Names
+
+- **Ids:** `area-role` in kebab-case — `hm-traffic-title`, `docs-nav-docs-data`. Never the builder's positional
+  `container-45` in code you maintain: rename them when you touch the code.
+- **Classes:** named after the role, not the look — `panel-title`, not `bold-16`.
+- **State keys:** flat and descriptive — `docsClosedStart`, `onboardingDetails`.
+
+## Code that came from an export
+
+`specFromSpace` writes what the builder saved, faithfully: every element's own `css`, positional ids, `when` rules
+per page. It renders; it is not maintainable. When you work on such a file, leave it better:
+
+- repeated `css` blocks → one class;
+- a nav with a hand-styled current entry per page → a layout and `activeOn`;
+- the same tree pasted per item → a function and a `map`;
+- `container-45` → a name.
+
+Each of those is safe to do on its own: authoring refuses anything that would not render, and the visual check shows
+the rest.

package/skills/plitzi-authoring/reference/templates-and-export.md

@@ -0,0 +1,54 @@
+# Templates, exports, and what authoring refuses
+
+## Publishing a template
+
+A template is ONE subtree, the style that dresses it and a name, published as a JSON someone 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' })] })
+});
+```
+
+- **Everything it names, it carries.** A class declared in the space it was cut from does not travel: declare every
+  rule the subtree names (`validateTemplate` warns about one it does not carry).
+- **A binding may not point outside the subtree.** Bring the provider into the template, or bind to a global.
+
+## From an exported JSON
+
+Never rewrite an exported space by hand. `specFromSpace({ schema, style })` reads it into the spec that authors it
+(listing each repair in `corrections`); `specToSource(spec, { exportName })` writes that spec as code;
+`compareSpaces(original, authorSpace(spec))` must list nothing but what `corrections` explains. The builder's
+**Export** does all three. Edit the code from then on — and tidy it as you go ([structure.md](structure.md)).
+
+For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
+`validateSpace({ schema, style })`.
+
+## What authoring refuses
+
+`authorSpace` throws rather than hand back a space that would not render. Each error names the element and the fix:
+
+- a CSS property the editor cannot read back; a class or slot the space does not declare (with the likely name)
+- an element with a shared `class` AND rules of its own; one class declared twice with rules that disagree
+- a binding source nothing answers to, or with the wrong prefix
+- a source written by its short name inside a flow's params or a binding's template (`stats.x` for `apiContainer_stats.x`)
+- a name that shadows a global (`variables`, `navigation`, `auth`, `state`, `theme`)
+- two elements with one id — the error says where the first one is
+- a step target that is not there; a broken flow chain, an orphan, a cycle
+- a flow on a trigger its element never fires (`onSubmit` on a button), an element callback sent to a type that
+  does not answer it (`openModal` to a container)
+- a `dropdownPopup` outside a `dropdown`, a tab container's parts outside a `tabContainer`
+- a global callback on the wrong module, a utility given one
+
+And it WARNS — returned in `warnings`, printed by `npm run author` — for what is written and will not do what it
+says: `unknown-attribute`, `template-never-resolved`, `condition-starts-visible`, `state-key-has-runtime-prefix`,
+`FORM_SUBMIT_UNMANAGED`, `STYLE_WITHOUT_TAG`, `tablet-rule-skips-mobile`. Treat a warning as a bug.
+
+Ids are hashes of the path that produced them: re-authoring an unchanged space writes byte-identical documents, so a
+seed can re-run and a diff stays readable.

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

@@ -0,0 +1,109 @@
+# Templates
+
+Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}` does depends on WHERE it is written.
+
+## Where a template runs
+
+| Written in | What is evaluated | What it can read |
+| --- | --- | --- |
+| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value), `sourceTo`, the globals, the variables by bare name, and every source around the element |
+| a flow step's params | the whole template | the trigger's payload and earlier steps by name, the globals, sources around the element |
+| an ATTRIBUTE (`href`, `src`, `content`…) | only `{{ name }}` tokens (a filter after the name is allowed) | the globals, the variables and the page's route params by bare name (`{{ apiUrl }}`, `{{ slug }}`), and every source around the element (`{{ list_games.item.slug }}`) |
+
+A **query parameter** is `navigation.queryParams.<name>` everywhere — never a bare name.
+
+An attribute holding a condition — `href: "/x/{{ on ? 'a' : 'b' }}"` — is used **as written** (`authorSpace` warns
+`template-never-resolved`). Move the expression into a binding with `bindTemplate`:
+
+```ts
+link({ href: '/', mode: 'internal', bind: [bindTemplate('href', 'state.workspace.id', "{{ source ? '/workspace/' ~ source : '/' }}")] })
+```
+
+A value that came from a BINDING is data, never a template: a comment reading `{{ auth.accessToken }}` prints those
+characters. Only what you authored is interpolated.
+
+### A template's value, not its text
+
+A binding's template renders TEXT by default. For an attribute that holds a list, a number or a flag — a list's
+`items` above all — hand over the VALUE with `returns: 'value'` (`returnMode: 'value'` on the transformer). The
+template must be a single `{{ expression }}`:
+
+```ts
+list({ id: 'shown', source: 'controlled',
+  bind: [bindTemplate('items', 'games.data.games', '{{ source|filter(g => state.genre == "" or g.genre == state.genre) }}', { returns: 'value' })],
+  children: [ … ] })
+```
+
+A text template feeding `items` is refused: the list would receive the array written out as JSON and render nothing.
+
+## Naming sources inside a template
+
+Always the full name — the element's kind, an underscore, its id: `apiContainer_stats`, `list_rows`,
+`modalContainer_credits`. The globals (`state`, `auth`, `navigation`, `variables`, `host`, `theme`, `computed`) are named
+as themselves. In a flow, an earlier step is read by the name given with `named('quote', …)`: `{{ quote.output.total }}`.
+
+An id with a hyphen is one name inside a template — `{{ apiContainer_tn-data.data.total }}` reads that provider. So
+subtraction is written with spaces: `{{ total - used }}`, never `total-used`.
+
+A source reaches only the elements **inside** the element that publishes it (a layout's providers reach every page in
+it). A list publishes one scope per row: inside a row, `list_rows.item` is THAT row and `list_rows.index` its position;
+a nested list's rows still see the outer row.
+
+`authorSpace` refuses a name nothing answers to, a short name where the full one is needed, and a source read from
+outside the element that publishes it — each with the name it should have been.
+
+## The language
+
+- Operators: `~` (concat), `+ - * / // % **`, `== != < > <= >=`, `and or not`, `in`, `starts with`, `ends with`,
+  `a ? b : c`, `a ? b` (empty when false), `a ?: b` (a when truthy), `a ?? b` (a when defined).
+- Access: `a.b`, `a.0`, `a[i]`, `(expr).key`, `(expr)[i]`, `['x', 'y'][i]`, `{ k: 1 }.k`.
+- Blocks: `{% set x = … %}`, `{% if %}…{% elseif %}…{% else %}…{% endif %}`, `{% for item in list %}…{% endfor %}`,
+  `{% apply upper %}…{% endapply %}`, `{% break %}`, `{% continue %}`.
+- Arrow functions in filters, closing over `{% set %}` variables: `rows|sort(r => r.at)|first`,
+  `rows|sort((a, b) => b.score - a.score)`, `rows|filter(r => r.score >= min)`, `rows|map(r => r.name)`.
+- Tests: `is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd`, `is same as(x)` (strict: `false` is
+  not `'false'`, `0` or an unset value), `is divisible by(n)`, and their `is not` forms. `null` and `none` are literals.
+- Functions: `range`, `min`, `max`, `cycle`.
+- **Not supported**: `matches` (no regular expressions are evaluated — use `starts with`, `ends with`, `in`), macros,
+  `include`/`extends`, and any filter or function not listed here. `authorSpace` refuses them, and anything else the
+  interpreter would read past, rather than letting a template render a value nobody wrote.
+
+Filters: `default upper lower trim capitalize title camelize kebab snake ltrim rtrim pad padRight replace slice split
+join reverse length first last contains startswith endswith number number_format round abs format sort batch chunk map
+reduce merge keys values filter column find pluck unique flatten sum without only index_by group_by url_encode nl2br
+striptags spaceless json_encode to_json object_as_json raw date base64_encode base64_decode md5 random`.
+
+`format` is sprintf: `'%02d'|format(n)` → `05`, `'%.1f'|format(x)`, `'%-8s'|format(name)`, `'%+d'|format(delta)`. A bare
+`%f` keeps the number's own digits.
+
+A lookup across two sources — a row joined to the stats around it:
+
+```ts
+"{% set s = apiContainer_stats.data.spaces|find('id', list_spaces.item.id) %}{{ s ? s.traffic.views|number_format(0, '.', ',') ~ ' views' : '—' }}"
+// or, in one expression:
+"{{ (apiContainer_stats.data.spaces|find('id', list_spaces.item.id)).traffic.views ?? 0 }}"
+```
+
+## Values to be careful with
+
+- **An empty list is false**, like an absent one. To tell "arrived and empty" from "not arrived":
+  `{{ items is defined and items is empty }}`.
+- **`json_encode` prints JSON for any value** — a string quoted and escaped, nothing as `null` — so a JSON document
+  is built by encoding each value: `'{ "board": {{ id|json_encode }}, "timer": {{ timer|json_encode }} }'`. In a flow
+  step's params and an action's output, `"{{ text }}"` in quotes is safe too — a value inside a string literal of a
+  param written as a JSON document is escaped for it. Anywhere else (an attribute, a binding's template) it is not:
+  encode.
+- **Numbers**: `number_format(decimals, point, thousands)`; `round(precision)`.
+- **A step param that is one `{{ expression }}` is that value, with its type**: a number stays a number, and a
+  string stays a string however it looks — a password typed `1234` arrives as `"1234"`. Nothing is guessed from the
+  text: to convert, declare the type where the value lands (`setState`'s `type`, the action's input field). Text around
+  the tokens is text, unless it makes a JSON object or array — then it is that document (see `json_encode` above).
+
+## Dates
+
+- `|date(format, zone)` — tokens `Y y m n d j H G h g A a i s l D F M N w U`; a backslash prints the next character
+  as it is (`\T`). **Always pass a zone** (`'UTC'`) and print it: with no zone the date is formatted in the local time
+  of whoever renders it — the server's for the HTML, the visitor's after hydration — and the two disagree.
+- A timestamp can be seconds or milliseconds, a number or a string of digits — all read.
+- For "3 minutes ago", the `dateConverter` transformer with `{ asAge: true }`; give it `isUnix: false` for an ISO
+  string. Its checkbox params accept real booleans (and `'true'`/`'false'`).