@plitzi/sdk-server 0.38.2 → 0.38.4

package/skills/plitzi-authoring/recipes/show-data.ts

@@ -3,18 +3,17 @@
  * Show data with no backend: a JSON file the project serves (`public/data/products.json`), read by a provider — one
  * card per product, a skeleton while it loads, a count, a computed value, and an empty state that never flashes.
  */
-import { apiContainer, container, heading, list, styles, text } from '@plitzi/sdk-authoring';
+import { apiContainer, container, heading, list, styles, text, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
-// A list is a `<ul>`: a grid of cards takes the bullets and the indent off.
+// A list is a `<ul>`, its rows `<li>`s straight inside: the grid is all its class says, the indent taken off.
 const grid = styles('product-grid', {
   display: 'grid',
   'grid-template-columns': 'repeat(auto-fill, minmax(220px, 1fr))',
   gap: '16px',
   margin: '0px',
-  padding: '0px',
-  'list-style-type': 'none'
+  padding: '0px'
 });
 
 const card = styles('product-card', { padding: '16px', 'border-radius': '12px', 'background-color': 'var(--card)' });
@@ -56,9 +55,15 @@ export const recipe: SpaceSpec = {
               class: grid,
               items: 'catalog.data.products',
               children: [
-                // Inside a row, a binding names the row short (`products.item`), a template in full (`list_products`).
-                heading({ subType: 'h3', class: card, from: 'products.item.title' }),
-                text({ from: 'products.item.price', as: 'price' })
+                // One `<li>` per product. Inside a row, a binding names the row short (`products.item`), a template in
+                // full (`list_products`).
+                listItem({
+                  class: card,
+                  children: [
+                    heading({ subType: 'h3', from: 'products.item.title' }),
+                    text({ from: 'products.item.price', as: 'price' })
+                  ]
+                })
               ]
             }),
             // Revealed by the data, so it starts hidden: nothing flashes while the file loads.

package/skills/plitzi-authoring/recipes/style-a-page.ts

@@ -10,7 +10,7 @@ import type { SpaceSpec } from '@plitzi/sdk-authoring';
 const card = styles('card', {
   css: {
     desktop: { display: 'flex', 'flex-direction': 'column', gap: '8px', padding: '24px', 'border-radius': '16px' },
-    // Tablet (48–64rem) and mobile (below 48rem) each inherit from desktop alone: `compact` is both.
+    // Tablet (48–64rem) and mobile (up to 48rem) each inherit from desktop alone: `compact` is both.
     compact: { padding: '16px' }
   },
   states: { hover: { 'border-color': 'var(--primary)' } }

package/skills/plitzi-authoring/recipes/typed-data.ts

@@ -4,7 +4,7 @@
  * `site.data.hero.titel` is a type error, not an empty heading. In a project the sample is the file itself:
  * `import home from '../../public/data/home.json' with { type: 'json' }`.
  */
-import { apiContainer, heading, list, source, styles, text, twig } from '@plitzi/sdk-authoring';
+import { apiContainer, heading, list, source, styles, text, twig, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -50,11 +50,14 @@ export const recipe: SpaceSpec = {
               class: grid,
               items: site.data.products,
               // The row's item is typed as the sample's: every field any product has.
-              row: product => [
-                text({ from: product.item.title }),
-                text({ from: product.item.price, as: 'price' }),
-                text({ from: product.item.badge, visible: product.item.badge })
-              ]
+              row: product =>
+                listItem({
+                  children: [
+                    text({ from: product.item.title }),
+                    text({ from: product.item.price, as: 'price' }),
+                    text({ from: product.item.badge, visible: product.item.badge })
+                  ]
+                })
             })
           ]
         })

package/skills/plitzi-authoring/recipes/usable-without-sight.ts

@@ -3,7 +3,7 @@
  * button, a field keeps its label out of sight rather than dropping it, a picture says what it shows or that it only
  * decorates.
  */
-import { button, fontAwesome, formControl, image, setState, styles, text, onClick } from '@plitzi/sdk-authoring';
+import { button, formControl, image, setState, styles, text, onClick } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -23,7 +23,7 @@ export const recipe: SpaceSpec = {
       name: 'Home',
       slug: '',
       body: [
-        button({ content: '', title: 'Search', children: [fontAwesome({ icon: 'fa-solid fa-magnifying-glass' })] }),
+        button({ content: '', title: 'Search', icon: 'fa-solid fa-magnifying-glass' }),
         button({
           content: '',
           class: card,

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

@@ -4,7 +4,8 @@ A screen reader and a browser agent (Claude in Chrome) read a page the same way.
 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.
+`dropdown-without-control`, `heading-level-skipped`, `label-ignored`, `control-in-decorative`, `embed-without-title`,
+`controls-no-anchor`). Fix them the same way you fix any other warning.
 
 ## Controls have words
 
@@ -13,10 +14,10 @@ warns about each case below (`control-without-name`, `image-without-alt`, `click
 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' })] })
+button({ content: '', title: 'Close', 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')] })
+button({ content: 'V', label: 'Select (V)', title: 'Select — V', icon: 'fa-solid fa-arrow-pointer' })
 
 // A link around a whole card: without `label` it is announced as every word inside the card.
 link({ href: '/posts/field-notes', label: 'Read “Field notes”', children: [ /* cover, topic, title, byline */ ] })
@@ -75,7 +76,10 @@ button({ content: 'Grid', bind: { ariaPressed: 'computed.gridOn' }, class: chip
 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.
+An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both. A button that
+opens a panel also names it — `controls: 'menu-panel'`, the panel's id (authoring gives the panel the anchor
+`aria-controls` needs; [recipes/accordion.ts](../recipes/accordion.ts)). Words that change while somebody is on the page
+— a count, a total, a status — sit in `container({ live: 'polite', … })`, so a screen reader says them when they change.
 
 ## The page has an outline
 

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

@@ -59,6 +59,7 @@ The space is not written until these are fixed.
 | `computed-not-template` | a computed value that is not a template | `'{{ state.x * 2 }}'` |
 | `computed-reads-element` | a computed value reading an element's source — no element is around the whole space | compute it from the globals and the variables, or bind it on the element |
 | `computed-unknown` | a computed value read before it is declared, or never declared | declare it in `computed`, above the one that reads it |
+| `controls-unknown` | a button's `controls` naming no element of the space | the id of the element it shows and hides: `controls: 'faq-answer'` |
 | `css-property-twice` | one property written twice in a rule set — `paddingTop` beside `'padding-top'` — so one would silently win | keep one |
 | `css-property-unknown` | a CSS property that does not exist | the property it suggests; a custom property starts with `--` |
 | `css-value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
@@ -84,7 +85,7 @@ The space is not written until these are fixed.
 | `global-callback-undeclared` | a global-callback step builder naming an action no source declares | one of the actions it lists |
 | `id-invalid` | an id a binding, a template or a test cannot name | a letter first, then letters, digits, `-` and `_`: `'hero-title'` |
 | `id-shadows-global` | an element named like a global data source (`state`, `navigation`, `auth`…) | another id |
-| `id-taken` | two elements with one id — ids are one namespace for the whole space | wrap what a helper builds in `scope('promos', ref => …)`: every id inside is prefixed, `ref('slides')` names one |
+| `id-taken` | two elements with one id — ids are one namespace for the whole space | a name taken by a page or a layout: a name of its own; a helper called twice: `scope('promos', ref => …)`, every id inside prefixed |
 | `layout-slot-unknown` | a layout `slot` that is not an element inside that layout | the id of the element in the shell where the body goes |
 | `layout-undeclared` | a page or a layout inside a layout the space does not declare | the layout's id, or declare it in `layouts` |
 | `list-items-ignored` | a list whose items nothing reads — `source: 'none'` renders its children once | `source: 'controlled'` |
@@ -92,6 +93,8 @@ The space is not written until these are fixed.
 | `loading-slot-unknown` | an `apiContainer`'s `loadingSlot` that is not the id of one of its children | the id of the child to show until the first answer — `loadingSlot: 'catalog-skeleton'` beside that child |
 | `modifier-count` | more than one set of rules in a class list | one set, after the classes: `class: [card, { opacity: '0.5', 'margin-top': '8px' }]` |
 | `modifier-without-id` | rules on top of a class on an element with no `id` — the id names the class they become | `id: 'hero-bg'` |
+| `motion-invalid` | a `motion` with a preset, a trigger or a timing the page cannot play | `motion: { enter: 'fade-up', on: 'view' }` — the message lists the presets |
+| `motion-no-tag` | a `motion` on an element with no tag of its own — nothing to move | the motion on what it wraps, or a `subType` on it |
 | `no-pages` | a space with no pages | `pages: [{ id: 'home', name: 'Home', slug: '', body: [] }]` |
 | `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the fields it lists; a colour or a length, like 'var(--card)' or '12px' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
@@ -107,6 +110,7 @@ The space is not written until these are fixed.
 | `prop-unknown` | a prop the component does not declare, handed in or read | the prop it suggests, or declare it: `props: { name: { type: 'text' } }` |
 | `prop-value` | a prop handed in with a value its declaration does not take | a value of the declared type, or one of its options |
 | `props-outside-component` | `props.x` read outside a component | read the source it would have come from |
+| `quiet-unknown` | an element's `quiet` naming something that is not a suggestion's code — a problem is never quieted | the code of the suggestion it was offered: `quiet: ['repeated-shape']` |
 | `redirect-target-unknown` | a page that sends visitors it is not for to a page the space does not have | a page's id or slug (`''` is the home page), or a full URL |
 | `row-and-children` | a list with a `row` and `children` — the row is what it renders | one of the two |
 | `row-component` | a list's `row` naming a component the space does not declare, or one with no prop to take the row | a declared component with an `item` prop — or a single prop — for the row |
@@ -115,6 +119,7 @@ The space is not written until these are fixed.
 | `rule-set-mixed` | a style that writes its rules beside `states`, `variants` or `ancestors` instead of under `css` | `{ css: { desktop: { … } }, states: { hover: { … } } }` — the rules under `css`, each of the others beside it |
 | `selector-invalid` | a `selector` that is not a CSS class name | letters, digits, `-` and `_` |
 | `selector-taken` | a `selector` that is a declared class, or another element's | `class` to share rules; a selector of an element's own is its alone |
+| `server-provider-in-component` | a `runtime: 'server'` element inside a component: the page server resolves a page's and its layouts', never a component's | put the provider on the page, around the instance, and hand the component its rows as a prop |
 | `setting-misplaced` | `settings.computed` or `settings.channels` written inside `settings` | `computed` and `channels` at the top of the space |
 | `slot-children` | children handed to an instance outside its slots | `children: { slotName: [ … ] }`; a component with no slots takes no children |
 | `slot-unknown` | a component slot that is not an element of its tree | the id of an element inside the component — usually an empty container |
@@ -159,6 +164,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `condition-starts-visible` | a computed visibility that shows until its data answers | `visible: { source, template }` |
 | `control-in-decorative` | a control inside a `decorative` container — Tab lands on something nothing announces | move it out of the illustration |
 | `control-without-name` | a button or a link with no words, or a field nothing names | `title` on the button, `label` on the link, `label` (with `hideLabel: true`) on the field |
+| `controls-no-anchor` | a button's `controls` naming no anchor — `aria-controls` points at nothing | an `anchor` on the element it shows and hides, and `controls` naming it |
 | `default-content-beside-children` | a button printing its default "Button" beside its children | `content: ''` |
 | `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) |
 | `embed-without-title` | an `embed` with no `title` — a frame a screen reader cannot describe | say what it shows in `title` |
@@ -172,13 +178,16 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `image-without-alt` | an image that is not `decorative` and has no `alt` | say what it shows, or `decorative: true` |
 | `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`…) |
 | `list-item-key-missing` | a list's `itemKey` that some of its items lack, or two of them share — the rows fall back to `id`, then position | a field every item has, once each |
+| `list-row-not-li` | a row of a list with `items` that is not an `<li>` — that list is a `<ul>` (or `<ol>`), so the row is a box inside a list, no item to a screen reader | `container({ subType: 'li' })` — or the component's root one, or a wrapper for a link or a button |
 | `overlay-never-opened` | a modal or a dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
 | `overlay-starts-open` | a modal or a dialog open when the page loads | `visible: false`, opened by `openModal` |
 | `painted-state-without-keep-state` | `paintedState` without `keepState` — nothing is kept for the server to draw with | `settings.keepState: true`, or remove `paintedState` |
+| `path-not-in-data` | a binding onto a provider whose answer the author could read (`data`), through a path that answer does not have | the path the message lists the keys for — `p.data.plans`, not `p.data.landing.plans` |
+| `plugin-attribute-reserved` | a plugin attribute named as one of the element’s own fields — a factory never hands it to the plugin | rename it in the plugin (`variant` → `kind`) |
 | `provider-without-source` | an `apiContainer` that asks nothing | a `query` (or `action`, `connector`, `resource`) |
 | `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` |
-| `server-data-without-rsc` | a `runtime: 'server'` provider with a `connector` or `action` in a space that does not turn server data on | `rsc: { enabled: true }` on the space |
-| `span-holds-block` | a `container({ subType: 'span' })` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words: a `text` with `display: inline` in its class |
+| `server-data-without-rsc` | a `runtime: 'server'` provider — `connector`, `action` or `query` — in a space that turns server data off (`rsc: { enabled: false }`) | drop `rsc: { enabled: false }`: server data is on unless a space turns it off |
+| `span-holds-block` | a `container` with `subType: 'span'` or `'p'` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words and inline elements: a `text`, a `link` |
 | `state-key-has-runtime-prefix` | a state key written with `runtime.state.` in front — the state callbacks already write below it | `key: 'cart'`, not `'runtime.state.cart'` |
 | `state-toggled-in-branches` | two `setState` 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 |
 | `STYLE_WITHOUT_TAG` | style on a provider that renders no element of its own | `subType: 'div'` on the provider, or style its parent |
@@ -189,6 +198,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `unknown-global-callback` | a global callback no built-in source declares — it runs only if something registers it | the built-in it suggests, or make sure a plugin or module of the space registers it |
 | `unknown-utility` | a utility that is not one of the built-in ones | one of the built-in utilities |
 | `unknown-variable` | a `var(--x)` nothing in the space declares — the property it is in is dropped | declare it under `variables`, fix the name, or give it a fallback: `var(--x, …)` |
+| `unknown-variant` | a variant no class of the element and no style of its type declares — nothing applies | declare it (`styles(name, { variants: { … } })`), or name one that is |
 
 ## Suggested
 

package/skills/plitzi-authoring/reference/colours-and-motion.md

@@ -19,6 +19,11 @@
 Only `opacity` and `transform` (`translate`, `scale`, `rotate`) animate off the main thread: they stay smooth while
 the page hydrates and on a slow phone. Everything else repaints, or lays the page out again, on every frame.
 
+- **A preset first:** `motion: { enter: 'fade-up', on: 'view' }` on any element, `stagger: 60` for children one by one,
+  `loop: 'float'` — played by the SDK, cheap and stilled for reduced motion by construction (`npx plitzi explain motion` lists them; `MOTION_ENTERS` and `MOTION_LOOPS` in code).
+  `on: 'view'` plays once, the first time the element comes into view, and it stays; `on: 'scroll'` follows the scroll
+  both ways — it goes back out as the reader scrolls up past it — so keep it for an effect that is about the scroll.
+
 - **Slide, grow, fade** with `transform` and `opacity` — never `left`, `top`, `width`, `height` or `margin`. Something
   that travels across a box is `transform: translate(%)` on an element as large as the box.
 - **No animated blur:** no `filter: blur()` in an entrance or a loop, no `backdrop-filter` over moving content. A soft
@@ -28,6 +33,8 @@ the page hydrates and on a slow phone. Everything else repaints, or lays the pag
 - **Main-thread decoration waits for hydration:** a sweep on a custom property, a `background-position` seam — start
   it paused, run it once the SDK's root says `data-hydrated`:
   `'.glow { animation: glow 8s linear infinite paused; } [data-hydrated] .glow { animation-play-state: running; }'`.
+  That is for loops. An entrance of your own that plays once — `transform`/`opacity` only — plays from the first paint
+  with `backwards`, as the presets do: gated on `[data-hydrated]` it jumps when the page goes live.
 - **Entrances:** `opacity` + a small `translateY`, under ~600ms, staggered by tens of ms.
 - **One ambient loop per screen**, slow — not one per card. `infinite` runs on every visitor's battery for as long
   as the page is open.

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

@@ -56,7 +56,8 @@ pages: [{ name: 'Shop', slug: 'shop', body: [
   a `json` prop `item`, read as `{{ props.item.name }}`.
 - **Slots** are elements of the component's tree that an instance fills. `children: [ … ]` fills a component with one
   slot; `children: { '<slot>': [ … ] }` names the slot for each. What fills a slot is the instance's, not the
-  component's: it is authored on the page and sees the page's sources.
+  component's: it is authored on the page and sees the page's sources. A prop's value is read as a template on the
+  instance, so words that show `{{ … }}` as text (docs, a tutorial) go in a slot — a `markdown` child — not in a prop.
 - **Closed.** Inside, nothing but `props` and the globals (`state`, `auth`, `navigation`, `theme`, `variables`,
   `computed`). A binding inside a component onto a provider of the page is refused — "nothing in this component answers
   to …" — because the component would render differently wherever it was placed. Put the provider inside the component,

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

@@ -50,7 +50,7 @@ text('', { bind: [bindTemplate('content', 'computed.level', 'Level {{ source }}'
 
 A computed value reads the globals (`state`, `auth`, `navigation`, `variables`, `theme`, `host`) and the ones declared
 above it — not an element's source: bind that on the element. One `{{ expression }}` gives its value (a number, a
-list); anything else gives text. `authorSpace` refuses a name read before it is declared, or never.
+list); anything else gives text. `authorSpace` refuses a name read before it is declared.
 
 ## Providers
 
@@ -61,12 +61,16 @@ apiContainer({ id: 'board', runtime: 'server', action: 'queue-board' })
 
 - A provider's source is readable by its **descendants** only. Wrap what reads it; a sibling cannot see it.
 - It publishes `data` plus `isLoading`, `isEmpty`, `hasError`, `errorMessage` — bind a state to those, not to guesses.
+  A `query`'s body is `data` in **either runtime** (`p.data.plans`), so moving a provider to the server changes no
+  binding. A connector publishes `records` (or `record`), an action its output.
   `isEmpty` reads what arrived: a `query`'s body when it is missing, `null`, `''`, `[]` or `{}`; a connector list by
   its `records`; a `singleRecord` provider by its `record`. It is also true before the first answer, so pair it with
   `not isLoading` for an empty state.
 - A query that depends on state is a binding on `query`; it answers `''` (and fetches nothing) until the state exists:
   `"{{ source ? apiUrl ~ '/workspaces/' ~ source ~ '/stats' : '' }}"` with `source: 'state.workspace.id'`.
-- A space with any `runtime: 'server'` provider needs `rsc: { enabled: true }`.
+- `runtime: 'server'` is resolved by the page server — server data is on unless a space says `rsc: { enabled: false }`.
+  Only a page and its layouts are resolved — never inside a component: keep the provider on the page and hand the
+  component its rows as a prop ([recipes/server-data.ts](../recipes/server-data.ts)).
 
 ### Typed by a sample
 
@@ -81,11 +85,15 @@ An offline project (`offlineMode`) still never invents data: the content lives i
 backend, so swapping the file for a real endpoint later changes one `query`. `mockData` is what the BUILDER shows while
 editing; it is not a data source for the running page. Say on the page that demo content is demo content.
 
-**In a server project (`create --mode server`), put the provider on the server** — `runtime: 'server'`, with
-`rsc: { enabled: true }` on the space — and the page server reads the file from `public/` itself: the page arrives
-with those sections in it (and their anchors in place) instead of fetching them once the browser has the page. A
-browser provider leaves the server-rendered HTML without them. A `query` with `{{tokens}}` is still read in the
-browser, against the visitor's route and state.
+**`public/` is on the internet.** Every file in it is served to anyone who asks, as it is, once the project is deployed —
+and so is everything the space's documents hold (pages, variables, attributes, `mockData`): they reach every visitor's
+browser. Never put a secret, a key, a private document or data only some visitors may read in either. A secret is a
+credential that an action or a connector names; data for some visitors only comes from a server action whose `access`
+checks who is asking, or a `runtime: 'server'` provider behind one.
+
+**In a server project (`create --mode server`), put the provider on the server** — `runtime: 'server'` — and the page
+server reads the file from `public/` itself: the page arrives with those sections (and their anchors) in it. A `query`
+with `{{tokens}}` is still read in the browser, against the visitor's route and state.
 
 ### Live, cached, refreshed
 
@@ -116,7 +124,7 @@ modalContainer({ visible: false, … })           // starts hidden; a flow opens
 | The logic… | Example | Write |
 | --- | --- | --- |
 | reveals it: hidden until the data says so | empty state, "get started", admin-only panel, error note | `visible: 'src'`, or `visible: false` + a computed binding |
-| hides it: shown unless a flag says otherwise | sidebar labels until the sidebar is folded, a banner until dismissed | a binding with no `visible`; an absent flag must leave it shown |
+| hides it: shown unless a flag says otherwise | sidebar labels until the sidebar is folded, a banner until dismissed | `visible: '!state.folded'` — on screen while nobody has set it |
 
 `visible` starts the element **hidden**, and it appears when its data says so. A revealing condition you have to
 compute is `visible: { source, template }` — it starts hidden too, and the template's value is read as a yes or a
@@ -135,17 +143,19 @@ container({
 
 Rules for a condition's template:
 
-- **A revealing condition starts hidden** — `visible: { source, template }` does that for you. A visibility binding
-  written by hand in `bind` keeps the element on screen until it answers — right for a hiding flag, a flash for a
-  condition on data. `authorSpace` warns `condition-starts-visible` when a computed one on a provider starts on screen.
+- **A visibility binding written by hand in `bind` keeps the element on screen until it answers** — a flash for a
+  condition on data (`condition-starts-visible` warns); `visible` starts it hidden.
 - **A hidden element stays in the DOM** (`plitzi-component--hidden`), its subtree mounted. `loadStrategy: 'visible'`
   mounts the subtree only while it is shown, and `'lazy'` from the first time it is shown (modals do that already).
   Use it on heavy panels that are usually hidden; leave the default on what is usually on screen.
-- **`'true'` shows, `'false'` hides, `''` writes nothing** and leaves the element as it is. Visibility hides only on
-  an explicit false.
-- **Answer what "not known yet" should mean.** For a revealing condition that is `'false'` (`source ? … : 'false'`);
-  for a hiding flag it is `''` — nothing written, the default stays. A sidebar that answered `'false'` for a
-  "folded" state nobody had set yet hid every label of the menu for everybody.
+- **Once its source has a value, the answer is a yes or a no**: `false`, `0`, `''` and an empty list hide it,
+  anything else shows it.
+- **While its source has no value, only a definite answer is written.** `!source` is `true` — shown; a template's
+  `'true'` or `'false'` is written as it says. A plain source, or a template that answers nothing (`''`), writes
+  nothing: the element stays as it started — hidden for `visible`, shown for a binding written by hand.
+- **So a hiding flag is `visible: '!state.folded'`** (or a binding with no `visible`): on screen before anybody has set
+  it. A condition that answers "not known yet" with `'false'` from a value that IS there — a "folded" read off
+  something always set — hid every label of a sidebar for everybody.
 - **Hide the element itself.** Never wrap it in a container that is shown while the inner one is hidden: an empty
   visible wrapper still takes a slot in its parent's `gap`, and leaves a hole in the page.
 

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

@@ -0,0 +1,22 @@
+# Drawing and animating in a plugin
+
+A plugin that draws on a canvas — a WebGL hero, a field of particles — takes the canvas from `useCanvas2d`, `useWebGL`
+or `useWebGL2`, and writes only `setup` (once per context) and `draw` (each frame, in CSS pixels):
+
+```tsx
+import { createShaderProgram, RootElement, useWebGL } from '@plitzi/plitzi-sdk';
+
+const { ref, ready, error } = useWebGL({
+  setup: gl => ({ program: createShaderProgram(gl, { vertex: VERTEX, fragment: FRAGMENT }) }),
+  draw: (gl, { time, state }) => { gl.useProgram(state.program); /* uniforms, drawArrays */ }
+});
+return <RootElement className={className}>{!ready && <img src={still} alt="" />}<canvas ref={ref} /></RootElement>;
+```
+
+It sizes the canvas to the device (at most 2× — `maxPixelRatio`), follows its size, and animates only while somebody
+can see it move: on a live page (in the builder it draws one still frame), for a visitor who did not ask for less
+motion, with the tab in front and the canvas on screen; `paused` holds it (bind it to a hover). A shader that does not
+compile — GLSL ES 1.0 wants `196.0`, not `196` — throws a `ShaderError` with the driver's log, printed as
+`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi check` lists it under the console) and `error` says it;
+show the still image meanwhile, as above. `useAnimationFrame(onFrame, { target })` is the same loop for motion that
+is not a canvas.

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

@@ -19,6 +19,15 @@ const { warnings, suggestions } = authorSpace(space);
 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.
 
+Left on purpose, say so where it is written — `quiet` on an element it is about, and it is not offered again, in the
+builder or over MCP either (it is kept in the document):
+
+```ts
+const includes = (words: string) => container({ class: row, quiet: ['repeated-shape'], children: [tick, text(words)] });
+```
+
+Only a suggestion's code: a problem is never quieted (`quiet-unknown`).
+
 ## The long way, and the short one
 
 | Written the long way | The short way | Suggestion |
@@ -26,7 +35,7 @@ reason is usually that the copies are about to diverge. `npx @plitzi/cli explain
 | 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` |
+| 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. Copies that read different sources or write different state keys are controls written alike, and not offered | `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` |

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

@@ -25,7 +25,7 @@ container([hero, grid])             // an array is the children
 | `visible` | a condition (`'src'`, `'!src'`, `{ source, template }`), or `false` to start hidden |
 | `flows` | what happens on click, on submit, on load |
 | `runtime` | `'server'` resolves this provider's data on the server |
-| `loadStrategy` | when the contents mount relative to visibility: `eager` (default), `lazy`, `visible` |
+| `loadStrategy` | when the contents mount relative to visibility: `eager`, `lazy`, `visible`. Left out, the type decides — `eager`, `lazy` for a modal or a dialog |
 | `children` | the tree |
 | `meta` | `meta.label` is the element's name in the builder's tree |
 
@@ -44,7 +44,7 @@ another link — make the card the link, or the button, not both.
 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 element's `id` is not its HTML id.** It reaches the DOM as `data-plitzi-el`. 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
@@ -66,8 +66,8 @@ says `content: ''` (`default-content-beside-children` warns otherwise). Its acce
 keeps its own value and fires `onChange` with `{ value, name }` on every change — a search box or a select that
 filters a screen needs no form. Bind `defaultValue` to the state it writes and a reset of that state reaches it.
 
-**A `list` is a `<ul>`.** The browser indents it and puts bullets on it; a list of cards needs
-`{ margin: '0px', padding: '0px', 'list-style-type': 'none' }` in its class.
+**A `list` is a `<ul>`, its rows `<li>`s straight inside** — `listItem({ … })`, or `list-row-not-li` warns. It is
+indented with space below it: `{ margin: '0px', padding: '0px' }` on its class takes that off.
 
 **A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own by default, so its
 children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the
@@ -78,12 +78,8 @@ A type this SDK does not ship — a plugin — is authored the same way: `define
 
 **What a type takes, answered by the package** instead of the 7,000-line `.d.ts`: every catalogue is exported, keyed by
 type — `elementCatalog` (what it is for), `elementDefaultAttributes`, `elementAttributeNames`, `elementTriggers`,
-`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS`. One line
-prints any of them:
-
-```bash
-node --input-type=module -e "import * as a from '@plitzi/sdk-authoring'; const t = 'formControl'; console.log({ attributes: a.elementDefaultAttributes[t], triggers: a.elementTriggers[t], slots: a.elementSlots[t] })"
-```
+`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS` — and
+`npx @plitzi/cli explain formControl` prints them for one type.
 
 ## CSS
 
@@ -92,7 +88,7 @@ kebab-case or camelCase (`paddingTop`, as a React style object), and a bare numb
 `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
+- **Breakpoints are ranges, not a cascade.** `tablet` is 48–64rem, `mobile` up to 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.

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

@@ -8,24 +8,29 @@ list bound to its records (see the provider in data-and-visibility).
 
 ```ts
 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
+list({ id: 'games', items: 'catalog.data.games', row: r => listItem({ children: [text({ from: `${r.item}.title` })] }) })
+list({ id: 'plans', items: ['Free', 'Pro'], children: [listItem({ children: [text({ from: 'plans.item' })] })] })  // fixed
 ```
 
-`items` makes a list controlled: an array of its own, or the source its rows come from. `row` is what it renders once
+`items` (or `from`) 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.
+`row: g => listItem({ children: [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.
+- A list is a `<ul>` (`subType: 'ol'` for a numbered one) and its `class` styles that root; each row is rendered
+  straight into it, with no wrapper — so **a row is an `<li>`**: `listItem({ class, children })`, a
+  `container({ subType: 'li' })`, or a component whose root is one. Anything else is a box inside a list, no item to a
+  screen reader (`list-row-not-li`; `fixSpace` makes a plain container one). A link or a button is wrapped in a
+  `listItem`, which is then what the list lays out: a card that is a link fills its item with `display: 'grid'` on the
+  `listItem`. Every list is indented (40px) with 10px below it, and one without `items` is bulleted too:
+  `{ margin: '0px', padding: '0px' }` on the root takes the space off. A grid of cards is the root's class.
 - 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.
@@ -68,7 +73,7 @@ apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children:
     source: 'controlled',
     bind: [bindTemplate('items', 'catalog.data.games',
       '{{ source|filter(g => g.slug == navigation.routeParams.slug) }}', { returns: 'value' })],
-    children: [gameDossier()]                       // reads list_game.item
+    children: [listItem({ children: [gameDossier()] })]   // reads list_game.item
   }),
   text('Signal lost — no game by that name.', {
     id: 'game-missing',

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

@@ -107,6 +107,11 @@ const newChart = useFlag('newChart'); // false for a flag the space does not dec
 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.
 
+## Drawing and animating
+
+A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — see
+[drawing](drawing.md).
+
 ## Registering
 
 A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in

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

@@ -7,7 +7,8 @@ of it; each line is something that has shipped broken before.
 
 - [ ] `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).
+      person rewords on the canvas) — and then quieted where it is written, `quiet: ['repeated-shape']`, so it stops
+      burying the ones that matter. The ones your change opened up first — [efficiency.md](efficiency.md).
 - [ ] No console errors on any page you touched.
 
 ## Nothing flashes, nothing jumps
@@ -39,7 +40,8 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
       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`.
+- [ ] A toggle binds `ariaPressed`, a button that opens something `ariaExpanded` and names it with `controls`; words
+      that change on their own are in a `live` container.
 - [ ] 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.
@@ -66,6 +68,16 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
 - [ ] What only an administrator may read is shown only to administrators — and the check is a real boolean, not
       a template left as text.
 
+## Nothing left behind
+
+- [ ] Nothing you made and no longer use is still there — a page, a component, a class, a token, a data file, an
+      import, a plugin folder. No commented-out code, no debug `console.log`, no copy of a file kept "just in case".
+- [ ] Scratch work — a one-off script, a dump, a picture to look at — went in `tmp/` (never committed) and is gone from
+      everywhere else.
+- [ ] Nothing secret, and nothing only some visitors may read, is in `public/` or in the space's documents: both reach
+      every visitor.
+- [ ] `typecheck`, `lint` and `format` are clean.
+
 ## Proven
 
 - [ ] You looked at it: the visual check ran, on the pages you changed, in both themes.

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

@@ -31,8 +31,8 @@ Never rewrite an exported space by hand. `specFromSpace({ schema, style })` read
 A server action reads back the same way: `actionSpecFromEntry({ id, document })` gives the `defineAction` spec that writes
 it — only when that spec writes the very same document, otherwise `reason` says why and it stays JSON — and
 `actionToSource(spec)` writes the module. For the whole space as a project — pages, actions, functions, the source of
-its plugins and runtime, its files — use `plitzi create --from <space>` (and `plitzi pull` later) rather than exporting
-the parts by hand.
+its plugins and runtime, its files — use `plitzi create --from <space>` (then `plitzi pull` to bring the space's changes in, and
+`plitzi push` to put the project's back) rather than exporting the parts by hand.
 
 For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
 `validateSpace({ schema, style })`.

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

@@ -39,7 +39,7 @@ export const panel = (params: { id: string; title: string; sub?: string; link?:
           children: [
             heading(params.title, { id: 'title', subType: 'h3', class: panelTitle }),
             ...(params.sub ? [text(params.sub, { id: 'sub', class: panelSub })] : []),
-            ...(params.link ? [link({ id: 'link', href: params.link.href, class: panelLink, children: [text(params.link.label)] })] : [])
+            ...(params.link ? [link({ id: 'link', href: params.link.href, class: panelLink, content: params.link.label })] : [])
           ]
         }),
         ...params.children

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

@@ -6,7 +6,7 @@ Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}`
 
 | 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 binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value — undefined until it has one: `{{ source|default('…') }}`), `sourceTo` (the attribute's value before it), 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 }}`) |