@plitzi/sdk-server 0.37.8 → 0.37.10

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

@@ -0,0 +1,53 @@
+# Efficiency: the same page with fewer elements
+
+Every element is a node the page renders, the builder lists, the document stores and the next reader has to read. A
+space written the long way still renders — nothing in it is wrong — but it is two or three times the size it needs,
+and every copy is a place the next edit has to be made again. The platform has a short way for each of the long ones
+below. Use it from the start; `authorSpace` points out the ones you missed.
+
+## Read the suggestions
+
+`authorSpace` returns `suggestions` beside `warnings` — the ones that save the most elements first, each with its code,
+what to write instead, the elements it is about and how many it would save:
+
+```ts
+const { warnings, suggestions } = authorSpace(space);
+// [{ code: 'repeated-on-pages', saves: 57, at: 'src/pages/docs.ts:291', elementIds: [...], message: '4 pages carry…' }]
+```
+
+`npm run author` prints them under the warnings (`[suggest]`), and `npm run author -- --json` carries them. A warning
+is a bug to fix; a suggestion is a shorter way to the same page — take it unless you have a reason not to, and the
+reason is usually that the copies are about to diverge. `npx @plitzi/cli explain repeated-on-pages` explains any code.
+
+## The long way, and the short one
+
+| Written the long way | The short way | Suggestion |
+| --- | --- | --- |
+| The same header, footer or sidebar in every page | A **layout** holding it once; each page names it (`layout: { id, slot }`) — [layouts](layouts.md) | `repeated-on-pages` |
+| A header copied per page so one link can be styled "active" | The link marks its own page: `states: { current: { … } }` on its class; `activeOn` for an entry lit on several pages | `repeated-on-pages` |
+| The same card, row or tile written again with other words | A **component** with props, placed with `component(id, { props })` — [components](components.md) | `repeated-shape` |
+| Rows of data written one by one, side by side | One `list` over the rows — `items: [ … ]` fixed, or bound to a source — with its row written once — [lists](lists.md). Data is the test: three cards a person rewords on the canvas read better as three cards | `repeated-shape` |
+| `button({ children: [text('Save')] })`, `link({ children: [text('Docs'), fontAwesome({ icon })] })` | `button({ content: 'Save' })`, `link({ href, content: 'Docs', icon, iconPlacement: 'after' })` — the icon's class on the `icon` slot; what the text's class adds (`whiteSpace: 'nowrap'`) moves to the box's class — never the class itself, whose `inherit` would then point past the box and whose `pointerEvents: 'none'` would switch the box off | `content-attribute` |
+| `.card:hover { … }`, `.card .icon { … }` in `customCss` | The class's own `states` and `ancestors` | `custom-css-class` |
+| A reduced-motion reset, or rules showing one icon of the theme toggle, in `customCss` | Nothing: the SDK does both for every space | `custom-css-sdk-default` |
+| `.Toastify__toast { font-family: …; border: … }` in `customCss` | `notifications: { font, fontSize, border, shadow, padding, … }` | `custom-css-notifications` |
+| Keyframes animating `width`, `top`, `filter: blur()`, `box-shadow`, a colour in a loop | `opacity` and `transform`; decoration held until `[data-hydrated]` — [motion](colours-and-motion.md) | `heavy-animation` |
+
+And a few the suggestions do not count, because they cost styles rather than elements:
+
+- **A look used twice is a class**, written once with `styles()`; every element of a TYPE dressed the same way is the
+  space's `elements` defaults (`elements: { heading: { color: 'var(--fg)' } }`), not a class on each.
+- **Inner parts are slots.** A form control's input, a modal's backdrop, a theme toggle's icons: style them with
+  `slots: { input: inputClass }` on the element, or the type's `slots` in `elements` — never a `customCss` rule reaching
+  into the element.
+- **A container with one child and nothing of its own** — no class, no flow, no condition — is an element for nothing:
+  put what it was for on the child.
+- **A wrapper that only marks where something goes** inside a parent that lays its children out takes
+  `css: { display: 'contents' }` (a layout's slot, a layout itself in a page that is a column): no box, so the layout
+  around it is what it was.
+
+## Measured
+
+On the seeded spaces, taking these suggestions removed a third of a restaurant site (2,533 → 1,697 elements: header
+and footer into a layout), two fifths of a blog (353 → 210: the per-page header provider into the layout) and of a
+sign-in space (848 → 530: the split screen into a layout) — and rendered every page pixel for pixel the same.

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

@@ -7,6 +7,7 @@ One factory per element, named after it. Attributes and the authoring fields go
 ```ts
 heading({ content: 'Fieldnotes', subType: 'h2', class: title })
 image({ src: '/fox.jpg', alt: 'A fox', css: { 'aspect-ratio': '3/2' } })
+image({ src: 'https://cdn.shop.com/p.jpg', alt: '…', sizes: '360px', width: 1200, height: 800 })   // resized by the page server
 container({ class: card, children: [ … ] })
 text('Wildlife, close up')          // a string is the content
 container([hero, grid])             // an array is the children
@@ -17,7 +18,7 @@ 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`, `hidden`… beside the element's own `css` |
+| `states` | `hover`, `focus-visible`, `current` (a link to the page shown), `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 |
@@ -31,15 +32,32 @@ container([hero, grid])             // an array is the children
 Anything else in the object is an **attribute** (`authorSpace` warns `unknown-attribute` for one the element never
 reads).
 
-**A link's `href` is a page id.** `link({ href: 'reports' })` finds the page by id, folder included. `mode: 'internal'`
-for a path within the space carrying `{{tokens}}` — a row's own slug (`'/games/{{ list_games.item.slug }}'`), a route
-param, state; `mode: 'external'` for a full URL passed through untouched. A link is an `<a>`: never put a link inside
+**A link says where by its `href`:** a page id (`link({ href: 'reports' })`, folder included), a path within the space
+— with `{{tokens}}` if it needs them, a row's own slug (`'/games/{{ list_games.item.slug }}'`) — or a full URL
+(`https:`, `mailto:`, `tel:`), passed through untouched. `mode` follows from it; write it only to say otherwise. A link
+that opens another tab (`target: 'blank'`) gets `rel="noopener noreferrer"`. A link is an `<a>`: never put a link inside
 another link — make the card the link, or the button, not both.
 
+**A link's words are its `content`** and an icon its `icon`, as a button's (`link({ href: 'pricing', content:
+'Pricing', icon: 'fa-solid fa-arrow-right', iconPlacement: 'after' })`, its class on the `icon` slot) — never a
+`text` or `fontAwesome` inside. The
+link to the page being shown is `aria-current="page"`; its class's `current` state styles it, so one header in a
+layout lights the right item everywhere.
+
+**An element's `id` is not its HTML id.** It reaches the DOM as `data-id`. For a section a URL can land on, give it
+an `anchor` (`anchor: 'plans'` → `id="plans"`: lowercase, digits, `-`) and link to it with `hash`:
+`link({ href: 'home', hash: 'plans' })` goes to `/#plans` and scrolls there, waiting for a section that renders once
+its data arrives. One anchor per page, layouts included; never inside a list row or a component, which would repeat
+it — `authorSpace` refuses each, and a `hash` no element on that page carries (`anchor-missing`). Under a fixed
+header, give the section `scroll-margin-top` (the header's height) so it does not land beneath it.
+
 **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 piece that sits in a line of text without breaking it — a dot before a title, a badge — is
+`container({ subType: 'span', … })`: inline by default. It holds words and inline pieces, never a heading or a
+paragraph (`span-holds-block`).
 
 **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.
@@ -69,14 +87,17 @@ node --input-type=module -e "import * as a from '@plitzi/sdk-authoring'; const t
 
 ## CSS
 
-Write CSS as you write CSS, shorthands included — they are expanded to the longhands Plitzi's editor reads. A property
-outside the vocabulary is refused with the key it should have been (`paddingTop` → `padding-top`).
+Write CSS as you write CSS, shorthands included — they are expanded to the longhands Plitzi's editor reads. Keys in
+kebab-case or camelCase (`paddingTop`, as a React style object), and a bare number on a length is pixels (`gap: 16`;
+`fontWeight: 800`, `opacity: 0.5` stay numbers). A property outside the vocabulary is refused.
 
 - `column(gap, extra?)`, `row(gap, extra?)`, `grid(columns, gap, extra?)` for the three layouts every space repeats.
 - **Breakpoints are ranges, not a cascade.** `tablet` is 48–64rem, `mobile` below 48rem, and each inherits only from
   `desktop` — a rule for `tablet` never reaches a phone (`authorSpace` warns `tablet-rule-skips-mobile`). A rule for
   everything narrower than a desktop is `compact`, written to both: `css: { desktop: { … }, compact: { 'grid-template-columns':
   '1fr' }, mobile: { gap: '8px' } }` — what `tablet` or `mobile` say for themselves wins.
+- **One property that changes, in place:** `{ fontSize: { desktop: '24px', mobile: '18px' }, fontWeight: 800 }` — the
+  rest of the rule stays desktop-only, without splitting it by breakpoint. Both forms mix.
 - **`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`
@@ -125,6 +146,9 @@ container({ class: card, children: [ … ] });
   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.
+- **The navigation of a site goes in a layout, once.** A link to the page being shown marks itself, and its class
+  dresses it with `states: { current: { … } }` — never a class picked per page, which forces a copy of the header into
+  every page.
 - **`: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.
@@ -137,25 +161,16 @@ container({ class: card, children: [ … ] });
 
 **A variant chosen by the data:** `variantFrom(pill, 'jobs.item.status')`, or with a template when the data does not
 already speak in variant names — `variantFrom(pill, 'runs.item.status', { template: "{{ source == 'completed' ?
-'ok' : 'failed' }}" })`. The binding's key names the CLASS; never write it by hand. For "the current page", see
-`activeOn` in [layouts.md](layouts.md).
+'ok' : 'failed' }}" })`. The binding's key names the CLASS; never write it by hand. A variant while a condition holds
+— the dot of the slide on screen — is `activeWhen(dot, '{{ list_dots.index == state.slide }}')` (`active`, else
+`idle`); for "the current page", `activeOn` in [layouts.md](layouts.md).
 
-## Colours and themes
+## From Tailwind classes
 
-Every colour is a **variable** with both values, and elements say `var(--name)`:
+A design written in Tailwind classes becomes classes the builder edits with `styles('pill', tw('…'))` — see
+[tailwind.md](tailwind.md).
 
-```ts
-variables: {
-  color: {
-    foreground: { light: '#0c0c14', dark: '#ededf3', default: '#0c0c14' },
-    card: { light: '#ffffff', dark: '#101019', default: '#ffffff' },
-    primary: { light: '#5b3df5', dark: '#6e52f7', default: '#5b3df5' }
-  }
-}
-```
+## Colours, themes and motion
 
-- Choose each value against its own background: a colour picked on white is not the same colour on near-black.
-- Fixed colours are only for surfaces that are fixed in both themes (a brand panel that is always dark) — and then
-  the text on them is fixed too. Theme-following text on a fixed background is the bug.
-- A tint of a token is `color-mix(in srgb, var(--primary) 12%, transparent)`, which follows the theme for free.
-- `themeToggle()` is the switch; `theme.resolved` (`light`/`dark`) is a global source for anything else that needs it.
+Every colour is a token with a light and a dark value, read as `var(--name)` (or `tokens(variables)`); keyframes go in
+`customCss` — see [colours-and-motion.md](colours-and-motion.md).

package/skills/plitzi-authoring/reference/feature-flags.md

@@ -0,0 +1,78 @@
+# Feature flags
+
+A flag turns a part of the space on or off without editing it: a feature still being built, a version for beta users,
+the old checkout kept until the new one ships. It is **not a visibility**. A hidden element is still rendered — its
+markup is in the page, its subtree mounted. An element gated off by a flag is not rendered at all: not on the server,
+not in the browser, not its children, and its server data is not resolved. Use `visible` for what the page's own state
+shows and hides; use a flag for what a person decides is switched on.
+
+**A flag is not a secret.** The space's document — gated elements included — still reaches the browser, as it always
+does, so the other side can appear without a reload when a flag changes. Content a visitor must never receive belongs
+behind a server action or a connector.
+
+## Declaring one
+
+```ts
+authorSpace({
+  name: 'Shop',
+  permanentUrl: 'shop',
+  flags: {
+    newCheckout: {
+      description: 'The one-step checkout',
+      value: false,                                   // the answer when no rule matches
+      rules: [                                        // read top to bottom; the first that matches decides
+        { when: { combinator: 'and', rules: [{ field: 'environment', operator: '=', value: 'staging' }] }, value: true },
+        { when: { combinator: 'and', rules: [{ field: 'user.roles', operator: 'contains', value: 'beta' }] }, value: true }
+      ]
+    }
+  },
+  pages: [ … ]
+});
+```
+
+A rule's `when` sees `environment` (`main`, `development`, `staging`, `production`), `hostname`, `routeParams.<name>`,
+`queryParams.<name>` and the visitor: `user.authenticated`, `user.email`, `user.username`, `user.roles` (a list — use
+`contains`). A group with no rules is skipped, never read as "always" (`flag-rule-empty` warns).
+
+The name is what a template reads, so it is a template key: letters, digits and `_`, starting with a letter or `_`.
+
+## Gating an element or a page
+
+```ts
+container({ id: 'checkout', flag: 'newCheckout', children: [ … ] })     // only while the flag is on
+container({ id: 'legacyCheckout', flag: '!newCheckout', children: [ … ] }) // only while it is off
+{ name: 'Labs', slug: 'labs', flag: 'labs', body: [ … ] }               // a page: 404 while the flag is off
+```
+
+Put the two sides of a rollout next to each other — the new one on `flag`, the old one on `!flag` — so exactly one is
+there whatever the flag says. A gate on a flag the space does not declare is an error (`flag-undeclared`): an
+undeclared flag is off, so the element would never render.
+
+## Reading one
+
+`flags` is a global source like `state` or `theme`: `{{ flags.newCheckout }}` is `true` or `false` in a binding, a
+step's `when`, a computed value — and in a server action's steps, resolved on the server for the visitor who started
+it. A plugin reads one with `useFlag('newCheckout')` from `@plitzi/plitzi-sdk`. Reading a flag the space does not
+declare is an error (`flag-unknown`).
+
+Prefer a gate to `visible: 'flags.x'`: a visibility bound to a flag still renders the hidden half and ships it in the
+HTML. Reach for the source only for what a gate cannot say — a label that changes, a step that branches.
+
+## Who decides
+
+The space's declaration answers first. Above it, in order, each may override a flag — only one the space declares:
+
+1. the server rendering the page — `createServer({ flags })` in a self-hosted deployment;
+2. the SDK embedding the space — `<PlitziSdk flags={{ newCheckout: true }} />` or `render(…, { flags })`;
+3. a tester with the dev tools — the **Flags** tab forces one for that browser, only where debugging is authorized.
+
+The draft (`main`) applies its flags as they are. Flags are **not served from a snapshot**: each environment has one set,
+shared by every snapshot it serves. Publishing a snapshot sends the draft's flags with it; the builder's *Publish flags*
+sends only them, with no new snapshot; rolling a snapshot back keeps the environment's flags. Each snapshot keeps a copy
+of the flags it was published with, used only when the environment's own cannot be read (after a Redis copy of them),
+and a self-hosted server keeps the last ones it fetched — so a published site keeps its flags with Plitzi unreachable.
+
+## When the feature ships
+
+Remove the gate from what stays, delete what it replaced, and remove the flag. A declared flag nothing reads is a
+warning (`flag-unused`): it is a switch nobody can see the effect of.

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

@@ -16,7 +16,9 @@ button({
 ```
 
 A flow is a list: a trigger, then steps in order. "Only if" is on the step (`when`, `whenSucceeded`, `whenFailed`),
-never a nested tree. Use the step builders — they fill in where a step runs and what it takes:
+never a nested tree. A step that belongs to a feature still behind a [feature flag](feature-flags.md) reads it like any
+source — `when({ field: 'flags.newCheckout', operator: '=', value: true }, …)` — and a server action's steps see the
+same flags, decided on the server. Use the step builders — they fill in where a step runs and what it takes:
 
 - **Where it runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an element
   callback under an element's id, a utility under nothing. Naming either half wrong is a control that does nothing,
@@ -39,7 +41,7 @@ never a nested tree. Use the step builders — they fill in where a step runs an
 
 ## What a trigger hands the flow
 
-Name the trigger (`named('changed', onChange())`) and read its payload as `{{ changed.<field> }}`:
+Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{{ changed.<field> }}`:
 
 | Trigger                                                                                                | Payload                                                 |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
@@ -89,6 +91,22 @@ on the page. A press while typing in a field is the field's, unless Ctrl/⌘/Alt
 `{{ <step>.key }}` is the key pressed (`shift+f`). A shortcut that cannot fire (`'ctrl+shift'`, `'arrowupp'`) is refused
 where it is written.
 
+**Something every few seconds** — an autoplay, a clock — is `onInterval(ms)`, a trigger every element has:
+`[[onInterval(5000), cycleState({ key: 'slide', length: 4 })]]`. It
+ticks while the element is mounted and the tab is in view, never in the builder outside preview, at least every 250 ms
+(`trigger-interval` otherwise). To pause it, give its steps a condition — a state that `on('onMouseEnter')` sets and
+`on('onMouseLeave')` clears. `{{ <step>.count }}` is how many times it has ticked. No plugin needed.
+
+**A number that goes round, or stops:** `cycleState({ key: 'slide', length: 4 })` is "next" — after the last the first
+— and `by: -1` "previous"; `stepState({ key: 'shown', by: 40, max: 'apiContainer_site.data.total' })` adds and stops
+at the bound. Each is the `setState` it stands for, with the arithmetic written once.
+
+**Scrolling** is a step on the element whose box scrolls (`overflow-x: auto` on a row of cards): `scrollBy('cards',
+{ x: '80%' })` moves it by most of what it shows (`'-80%'` back, `'240'` pixels), `scrollTo('cards', { x: 'end' })`
+to an end or a place, and `scrollIntoView('answer', { block: 'center' })` brings an element into view. `onScroll()`
+fires as the box moves and once on mount, with `{ x, y, atStart, atEnd }` — what an arrow that hides at the end reads
+(recipes/scroll-a-row.ts). A link to a section needs none of this: an `anchor` and a link's `hash`.
+
 **A form's flow goes on the `form`**, which hands its submit over with `managedByInteractions: true`
 (`FORM_SUBMIT_UNMANAGED` otherwise — the browser submits it natively and `onSubmit` never fires):
 
@@ -112,8 +130,11 @@ without a word.
 ## Notifications
 
 `addNotification({ content: 'Saved', appearance: 'success' })` — `appearance` is `success`, `danger`, `warning` or
-`info`. They follow the page's theme and font; their colours are the space's `notifications`:
-`notifications: { background: 'var(--card)', text: 'var(--foreground)', success: 'var(--accent)', radius: '12px' }`.
+`info`. They follow the page's theme; how they look is the space's `notifications` — colours (`background`, `text`,
+`success`, `danger`, `warning`, `info`) and shape (`radius`, `font`, `fontSize`, `border`, `shadow`, `padding`):
+`notifications: { background: 'var(--card)', text: 'var(--foreground)', success: 'var(--accent)', radius: '12px',
+font: 'var(--font-sans)', border: '1px solid var(--border)', shadow: 'var(--shadow-lg)' }`. The toast carries no class
+of the space's, so this — not a `.Toastify__toast` rule in `customCss` — is where it is dressed.
 
 ## Modals, dropdowns, tabs
 
@@ -126,39 +147,7 @@ without a word.
 
 ## Realtime channels
 
-Pages that see each other — cursors, presence, a shared board — need a channel. Declare its topic pattern on the space,
-then subscribe with a `channel` element; a topic no pattern matches is refused, naming the patterns:
-
-```ts
-channels: {
-  'board:{id}': { access: { mode: 'public' }, publish: 'server' },           // only `realtime.publish` speaks
-  'room:{id}': { access: { mode: 'public' }, presence: true }                // pages speak directly
-}
-
-channel({ id: 'room', topic: 'room:{{ id }}', keep: 0, bind: { presence: 'computed.me' }, children: [...] })
-```
-
-Its descendants bind `room.members`, `room.connected`, `room.last`; flows use `on('onMessage')` (`type`, `data`,
-`from`), `onJoin`/`onLeave` (`from`, `user` and the `state` the member announced — `onJoin` only for who came after
-this page), `publishOn('room', 'reaction', data)` and `announceOn('room', state)`. State everyone must
-agree on goes through a server action whose last step is `realtime.publish` — validated and saved first, announced
-after. `docs/en/realtime.md` is the whole of it.
-
-A topic only some visitors may hear — a room behind a password, a customer's order — goes on a channel declared
-`grant: true`. The action that decides they may be there ends with `realtime.grant` and answers the grant; the
-element binds it, or the server refuses the topic every time (`channel-grant`). `realtime.revoke { topic, grant }`
-takes one back — or every grant for the topic, naming none — and lets go whoever is on it with it:
-
-```ts
-channels: { 'order:{id}': { access: { mode: 'session' }, grant: true } }
-
-// steps: [ …decide…, { id: 'let', task: 'realtime.grant', params: { topic: 'order:{{ input.order }}' } } ]
-channel({ id: 'order', topic: 'order:{{ id }}', bind: { grant: 'state.follow.grant' }, children: [...] })
-```
-
-Two people writing the same thing at once: `kv.setIf` writes only if the value is still the one the flow read (empty
-`expected` = only if nothing is there yet — claim a seat, a username), `list.put`/`list.range` keep an ordered list
-(latest first, a leaderboard), and `flow.rateLimit` first in a public action that writes.
+Pages that see each other — cursors, presence, a shared board — talk over a channel: see [realtime](realtime.md).
 
 ## Lists as state
 

package/skills/plitzi-authoring/reference/kept-state.md

@@ -0,0 +1,28 @@
+# 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/layouts.md

@@ -36,6 +36,13 @@ pages: [{ name: 'Quickstart', slug: 'quickstart', folder: 'docs', layout: { id:
   sidebar) inside the application shell. The page resolves the chain from the outside in.
 - **A provider in a layout serves every page** — the plan in a sidebar, a star count in a top bar. A server provider
   (`runtime: 'server'`) in a layout is resolved with the page like one in the page.
+- **The layout is a box between the page and its shell.** The page's own class styles the page's root, which holds the
+  layout, which holds your shell — so a page that is a column stretching its content to the window's height
+  (`min-height: 100vh` with a `flex-grow: 1` child) no longer reaches the shell: the footer lifts off the bottom. Give
+  the layout `css: { display: 'contents' }` and the chain is what it was. A slot that only marks where the page goes,
+  inside a parent that lays its children out, takes the same.
+- **The slot can be a role, not only a place.** A split screen's form half is the slot itself (`class: formPane`), so
+  each page is just its card.
 - **Ids are shared** between a layout and all its pages. Name layout elements after the layout (`docs-topbar`), and
   let pages prefix theirs with the page id.
 
@@ -90,9 +97,19 @@ const navLink = styles('nav-link', {
 link({ href: 'spaces', class: navLink, bind: [activeOn(navLink, ['spaces', 'space-record'])] });
 ```
 
-`activeOn(class, pageIds, { variant?, slot? })` binds the class's variant to `navigation.currentPageId`: the `active`
-variant on those pages, `idle` everywhere else. Several ids for one entry — a section and the pages under it. Do not
-write the binding by hand with a `when` rule per page; that is the long form this replaces.
+A link to ONE page needs nothing of this: it marks itself — `aria-current="page"`, which a screen reader announces — and
+its class dresses it with the `current` state:
+
+```ts
+const navLink = styles('nav-link', { css: { color: 'var(--muted)' }, states: { current: { color: 'var(--foreground)' } } });
+
+link({ href: '/pricing', mode: 'internal', class: navLink });
+```
+
+`activeOn(class, pageIds, { variant?, slot? })` is for an entry lit on SEVERAL pages — a section and the pages under it,
+a journal and its articles: it binds the class's variant to `navigation.currentPageId`, the `active` variant on those
+pages and `idle` everywhere else. Do not write the binding by hand with a `when` rule per page; that is the long form
+this replaces.
 
 ## Pages from a factory
 

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

@@ -7,36 +7,44 @@ its children once as a plain `<ul>` and never looks at `items`, so a list with i
 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
-})
+list({ id: 'games', class: gameGrid, items: 'catalog.data.games', row: 'game-card' })   // a component per game
+list({ id: 'games', items: 'catalog.data.games', row: r => text({ from: `${r.item}.title` }) })   // or a tree of its own
+list({ id: 'plans', items: ['Free', 'Pro'], children: [text({ from: 'plans.item' })] })  // fixed items
 ```
 
-- Each row publishes **`list_<id>.item`** (the row) and **`list_<id>.index`** (its position, as text). Inside the row,
+`items` makes a list controlled: an array of its own, or the source its rows come from. `row` is what it renders once
+per item — a component's id (placed with the row bound to its `item` prop, or its only prop), or a function handed the
+row's names: `r.item` and `r.index` for a binding or `from`, `r.inTemplate.item` for a template
+(`` `/games/{{ ${r.inTemplate.item}.slug }}` ``). A function needs the list's `id`, which names those sources. With
+`items` a typed source's path (`items: site.data.games`, see typed-sources.md), the row is typed too:
+`row: g => text({ from: g.item.title })`, and a field the sample's games lack is a type error.
+
+- Each row publishes **`list_<id>.item`** (the row) and **`list_<id>.index`** (its position, a number from 0 —
+  `index + 1` counts, and `==` compares it with text or a number alike). 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.
+- Fixed data is `items: [ … ]` on the list itself — no provider needed. Worth it when the rows ARE data — written from
+  an array, or rows that come and go (`repeated-shape` points at sibling copies). Three cards a person rewords on the
+  canvas are easier to edit as three cards than as a JSON array.
 - Everything inside a row is `repeated` in the handles: a test addresses one copy with `.first()` / `.nth()`.
+- **A row is its item's by its `id`** when every item has a different one, else by its position: filtered or
+  reordered, a row's state (an open detail, a field's text) follows its item. Items named by another field say so —
+  `itemKey: 'slug'` (`list-item-key-missing` warns when fixed items lack it). A row whose item changes mounts again,
+  so a one-row list showing "the current slide" replays the slide's entrance animation.
 
 ## Filtering and sorting
 
-Bind `items` through a template that hands over its **value**:
+Feed the list through a template — `from` with `as` hands a list its template's **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()]
+  from: 'catalog.data.games',
+  as: "{{ source|filter(g => (state.genre ?? '') == '' or g.genre == state.genre)|sort((a, b) => b.score - a.score) }}",
+  row: 'game-card'
 })
 ```
 
@@ -71,4 +79,25 @@ apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children:
 ```
 
 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 }}' })`.
+`link({ href: '/games/{{ list_games.item.slug }}' })`.
+
+## Carousels
+
+```ts
+carousel({ id: 'hero', label: 'Featured', items: 'site.data.slides', autoplay: 5000, row: 'slide-card', children: [
+  button({ content: '›', title: 'Next slide', flows: [[onClick(), carouselNext('hero')]] })
+] })
+```
+
+A `carousel` takes `items` and a `row` as a list does, and writes the row into a `carouselTrack`; its other children are
+its controls, which read `carousel_hero.index`, `.count`, `.item` and `.items` (`list({ id: 'dots', items: 'hero.items',
+… })` for dots, `activeWhen(dot, '{{ list_dots.index == carousel_hero.index }}')` for the current one). Steps:
+`carouselNext`, `carouselPrevious`, `carouselGoTo(id, index)`, `carouselPlay`, `carouselPause`; it fires `onChange`.
+
+- `mode: 'slide'` (one at a time, `transition` `slide`/`fade`/`none`, back enters from the left), `'marquee'` (`speed` px/s,
+  no seam), `'scroll'` (a row that snaps and swipes; next moves a slide). Several slides at once: the carousel's class
+  sets `--plitzi-carousel-slide-width` and `--plitzi-carousel-gap`.
+- Autoplay holds still under the pointer (`pauseOnHover`), with keyboard focus inside, in a hidden tab and for reduced
+  motion. In the builder it stands on its first slide. `label` names it for a screen reader.
+
+See recipes/carousel.ts.

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

@@ -92,6 +92,21 @@ Take the topic as a prop (`bindTemplate('roomTopic', 'board.id', 'room:{{ source
 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.
 
+## Feature flags
+
+A plugin that ships a feature behind one of the space's [feature flags](feature-flags.md) asks with `useFlag` — the
+answer every layer gave (the space's rules, the server, the SDK, a tester forcing it), and it renders again when it
+changes:
+
+```tsx
+import { useFlag } from '@plitzi/plitzi-sdk';
+
+const newChart = useFlag('newChart'); // false for a flag the space does not declare
+```
+
+Gating the whole plugin needs no code: give its element `flag: 'newChart'`. `useFlag` is for a plugin that changes
+inside — a new mode, an extra panel.
+
 ## Registering
 
 A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in
@@ -134,6 +149,18 @@ A plugin says what HAPPENED through its events (`onPick`, with the seat in the p
 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.
 
+## Behaving in the builder
+
+The builder draws the element on its canvas while somebody edits the page: a click selects it, a drag moves it, a key
+belongs to the editor.
+
+- **Outside preview, do nothing on your own.** `usePlitziServiceContext().settings.previewMode` is `false` while the
+  page is edited. Declared interactions are already held back then; your own click handlers, timers, global listeners,
+  permission prompts and map gestures are not — gate them on `previewMode`, and still render something to select.
+- **Never the global `window` or `document`.** The canvas is a frame of its own and the code runs in the builder's
+  window: listen, measure and go full screen through the node's own page (`ref.current.ownerDocument`, its
+  `defaultView`) or `usePlitziServiceContext().utils.getWindow()`. An `instanceof` check takes its class from there 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

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

@@ -0,0 +1,35 @@
+# Realtime channels
+
+Pages that see each other — cursors, presence, a shared board — need a channel. Declare its topic pattern on the space,
+then subscribe with a `channel` element; a topic no pattern matches is refused, naming the patterns:
+
+```ts
+channels: {
+  'board:{id}': { access: { mode: 'public' }, publish: 'server' },           // only `realtime.publish` speaks
+  'room:{id}': { access: { mode: 'public' }, presence: true }                // pages speak directly
+}
+
+channel({ id: 'room', topic: 'room:{{ id }}', keep: 0, bind: { presence: 'computed.me' }, children: [...] })
+```
+
+Its descendants bind `room.members`, `room.connected`, `room.last`; flows use `on('onMessage')` (`type`, `data`,
+`from`), `onJoin`/`onLeave` (`from`, `user` and the `state` the member announced — `onJoin` only for who came after
+this page), `publishOn('room', 'reaction', data)` and `announceOn('room', state)`. State everyone must
+agree on goes through a server action whose last step is `realtime.publish` — validated and saved first, announced
+after.
+
+A topic only some visitors may hear — a room behind a password, a customer's order — goes on a channel declared
+`grant: true`. The action that decides they may be there ends with `realtime.grant` and answers the grant; the
+element binds it, or the server refuses the topic every time (`channel-grant`). `realtime.revoke { topic, grant }`
+takes one back — or every grant for the topic, naming none — and lets go whoever is on it with it:
+
+```ts
+channels: { 'order:{id}': { access: { mode: 'session' }, grant: true } }
+
+// steps: [ …decide…, { id: 'let', task: 'realtime.grant', params: { topic: 'order:{{ input.order }}' } } ]
+channel({ id: 'order', topic: 'order:{{ id }}', bind: { grant: 'state.follow.grant' }, children: [...] })
+```
+
+Two people writing the same thing at once: `kv.setIf` writes only if the value is still the one the flow read (empty
+`expected` = only if nothing is there yet — claim a seat, a username), `list.put`/`list.range` keep an ordered list
+(latest first, a leaderboard), and `flow.rateLimit` first in a public action that writes.

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

@@ -6,6 +6,8 @@ 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.
+- [ ] Every **suggestion** is taken, or left for a reason you can say (the copies are about to diverge; three cards a
+      person rewords on the canvas). The ones your change opened up first — [efficiency.md](efficiency.md).
 - [ ] No console errors on any page you touched.
 
 ## Nothing flashes, nothing jumps
@@ -15,6 +17,8 @@ of it; each line is something that has shipped broken before.
 - [ ] 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.
+- [ ] A feature still being built is gated by a [feature flag](feature-flags.md) (`flag: 'x'` / `'!x'`), not hidden
+      with `visible` — and checked with the flag on AND off. A flag whose feature shipped is removed, gate and all.
 - [ ] 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.
 
@@ -23,7 +27,8 @@ of it; each line is something that has shipped broken before.
 - [ ] 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.
+- [ ] Focus is visible on everything clickable (`focus-visible`). Animations and transitions stop by themselves for
+  `prefers-reduced-motion`; a hover that moves something is turned off there too (`transform: none`).
 
 ## Usable without sight
 
@@ -44,8 +49,8 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
 - [ ] 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.
+- [ ] No positional ids (`container-45`) in what you wrote; every referenced element is named, and a helper that
+      runs more than once builds inside `scope()`.
 
 ## True, and in the right place