@plitzi/sdk-server 0.38.6 → 0.38.8

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

@@ -0,0 +1,75 @@
+# Signing people in
+
+## Where they sign in
+
+A page signs in with one provider: the space's `settings.userProvider`, or — when it declares none — the one the server
+that rendered it serves.
+
+| The space runs… | Declare |
+| --- | --- |
+| on the Plitzi platform, visitors signing in with their Plitzi account | `userProvider: 'server'` — and `visitorRoles` |
+| on a self-hosted server with `auth` (`createServer({ auth })`; in a project, `src/config/serverOptions.ts`) | nothing: the server tells its pages where they sign in |
+| against an API of your own over HTTP+JSON | `userProvider: 'basic'`, `loginUrl`, `userUrl`, `refreshUrl`, `logoutUrl`, and `sessionHintCookie` when it writes one |
+
+What the space declares wins, setting by setting; a space naming another provider than the server's ignores the
+server's altogether. A page with no provider at all offers no auth actions, and an `authLogin` there says why in the
+console (`[plitzi] auth.login: …`) — read it before suspecting the form.
+
+On the platform, `userProvider: 'server'` signs in by leaving the page: a `link` with `mode: 'external'` to
+`/auth/sign-in?return=/` sends the visitor to sign in and back, signed in on the space's own host.
+
+## The steps
+
+```ts
+form({
+  id: 'signIn',
+  managedByInteractions: true,
+  flows: [
+    [
+      named('sent', onSubmit()),
+      named('signedIn', authLogin({ username: '{{ sent.values.username }}', password: '{{ sent.values.password }}' })),
+      when({ field: 'signedIn.ok', operator: '=', value: true }, navigate({ urlType: 'page', url: 'dashboard' })),
+      when(
+        { field: 'signedIn.reason', operator: '=', value: 'unverified' },
+        addNotification({ content: 'Confirm your address first — the link is in your inbox', appearance: 'warning' })
+      )
+    ]
+  ],
+  children: [
+    formControl({ name: 'username', label: 'Username' }),
+    formControl({ name: 'password', label: 'Password', subType: 'password' }),
+    button({ content: 'Sign in', subType: 'submit' })
+  ]
+});
+```
+
+- `authLogin(params)` — `{ username, password }`; `{ mode: 'token', token }` adopts a credential obtained elsewhere,
+  checked against `userUrl`; `{ mode: 'mfa', mfaToken, code }` completes a sign-in that owed a second factor.
+- What it answers: `ok`; when not, `reason` (`unverified`, `inactive`, `network`, `missing`…) and, for `reason: 'mfa'`,
+  `mfaToken` — the challenge `mode: 'mfa'` completes. Test it on `<step>.ok` with `when`, never `whenSucceeded` /
+  `whenFailed`, which are a server action's ([flows](flows.md)).
+- `authLogout()` ends the session; `authRefreshDetails()` reloads who is signed in.
+
+## Who is signed in
+
+The `auth` source: `{{ auth.isAuthenticated }}`, `{{ auth.status }}` (`init` … `authenticated` | `guest`, while it is
+being found out), `{{ auth.details.username }}` — `details` carries `id`, `username`, `email`, `verified`, `roles` and
+`permissions`. Show a signed-in part with `visible: 'auth.isAuthenticated'`; never bind a token into the page.
+
+## Pages for one kind of visitor
+
+A page's `accessLevel`: `'authenticated'` (signed in), `'public'` (signed OUT only — the sign-in page), or nothing
+(everybody). A lone `public` page vanishes the moment anyone signs in, so leave it out unless the page has a signed-in
+twin on the same slug. `unauthorizedRedirect` names where a visitor the page is not for goes — a page's id or slug
+(`''` is the home page), or a URL; without it they are answered 403.
+
+## What a visitor may do
+
+`settings.visitorRoles` — `{ author: ['postPublish'] }` — is what each role gives. A visitor holds exactly the
+permissions of their roles in this space; who holds a role is given by email in the builder, never written here. A page
+reads them in `auth.details.permissions`, a plugin asks `can('postPublish')` of the auth context.
+
+A server action's trigger says who may run it: `access: { mode: 'public' }`, `{ mode: 'session' }` (signed in) or
+`{ mode: 'role', permissions: ['postPublish'] }`. The page hiding a button is not the check — the trigger is. Inside,
+its steps read who asked as `{{ user.id }}`, and a function as `ctx.user` (`id`, `username`, `email`, `verified`,
+`roles`, `permissions`) — never their session.

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

@@ -27,7 +27,7 @@ The space is not written until these are fixed.
 | `action-without-entry` | an action with no way in, so nothing can start it | a `trigger` — `{ type: 'call', access }`, or `render`, `webhook`, `custom`, `schedule` |
 | `action-without-steps` | an action with no steps | the steps it runs |
 | `active-when-constant` | an `activeWhen` condition that reads nothing — always or never true | name what it depends on: `'{{ list_dots.index == state.slide }}'` |
-| `ancestor-not-class` | an ancestor condition keyed by something that is not a class name | `[card.name]` for a `styles()` declaration |
+| `ancestor-not-class` | an ancestor condition keyed by something that is neither a class name nor `'>'` (the parent) | `[card.name]` for a `styles()` declaration, or `'>'` for the parent whatever it wears |
 | `anchor-duplicate` | one anchor on two elements of the same page (layouts included) | rename all but one |
 | `anchor-invalid` | an `anchor` or a link's `hash` that is not lowercase letters, digits and `-` | `anchor: 'plans'`, `hash: 'plans'` — no `#` |
 | `anchor-missing` | a link whose `hash` no element on the page it goes to carries — it would land at the top | the anchor the message lists, or give the section that `anchor` |
@@ -59,20 +59,23 @@ 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 |
+| `condition-field-unpublished` | a `when` asking a step of its flow for a key it never publishes — `whenSucceeded` / `whenFailed` on anything but `runServerAction` | a key the step publishes (`explain <step>`): after `authLogin`, `when({ field: 'signedIn.ok', operator: '=', value: true }, …)` |
 | `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 |
+| `element-ids-target` | a step refreshing containers by id (`invalidateElements`, `invalidateQueries({ elements })`) naming one the space does not have, or one that is not an `apiContainer` | the id of the `apiContainer` whose data the step changes: `invalidateElements: ['posts']` |
 | `element-load-strategy` | a `loadStrategy` the element does not take | one of the values the message lists |
 | `element-rejected` | an element the schema refused to hold | the problem listed with it |
 | `element-runtime` | a `runtime` the element does not run in | one of the values the message lists |
 | `element-shape` | an element that is not an object with a `type`, `attributes` and a list of `children` | build elements with their factories — `text(…)`, `container(…)` |
+| `element-slot-unknown` | a `slots` key the element type does not have — its class would dress nothing | one of the slots `plitzi explain <type>` lists; the element itself takes `class` |
 | `flag-gate` | an element's or a page's `flag` that is not a flag name | `flag: 'newCheckout'`, or `flag: '!newCheckout'` for "only while off" |
 | `flag-name` | a flag whose name a template cannot read as `flags.x` | letters, digits and `_` |
 | `flag-rule-shape` | a flag rule that is not `{ when, value }`, or whose `value` is not `true` or `false` | `{ when: { … }, value: true }` |
 | `flag-shape` | a flag whose `value` is not `true` or `false` | `{ value: false, rules: [] }` |
 | `flag-undeclared` | a gate on a flag the space does not declare — it reads as off, so the element never (or always) renders | declare it in `flags`, or remove the gate |
-| `flag-unknown` | a template reading a flag the space does not declare | the declared name it suggests, or declare it |
+| `flag-unknown` | a template, a binding or a `when` reading a flag the space does not declare | the declared name it suggests, or declare it |
 | `flow-empty` | a flow with no steps | `[onClick(), setState({ … })]` |
 | `flow-without-trigger` | a flow whose first step is not the event that runs it | `[onClick(), setState(…)]` |
 | `folder-cycle` | a page folder inside itself | a `parent` that leads to the top |
@@ -83,9 +86,11 @@ The space is not written until these are fixed.
 | `from-without-attribute` | `from` on a type with no one attribute that shows its data (a container, a form) | bind the attribute you mean: `bind: { attribute: 'source' }` |
 | `global-callback-module` | a global callback sent to a module other than the one that registers it | the step builder, which knows the module |
 | `global-callback-undeclared` | a global-callback step builder naming an action no source declares | one of the actions it lists |
+| `global-field-unknown` | a binding, a template or a `when` reading a field `navigation`, `auth` or `theme` never has — `auth.authenticated` | the field it suggests: `auth.isAuthenticated`, `auth.details.username`, `navigation.queryParams.next`, `theme.resolved` |
 | `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 | 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 |
+| `keyframes-shape` | keyframes with a name CSS does not accept or the SDK keeps for itself, or a frame that is not an offset | a plain name (`slide-in`), frames keyed `from`, `to` or a percentage (`'50%'`, `'0%, 100%'`) |
 | `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'` |
@@ -96,7 +101,7 @@ The space is not written until these are fixed.
 | `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' |
+| `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the field it suggests, or one it lists; one CSS value, like 'var(--card)', '12px' or '500' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
 | `page-access-level` | an `accessLevel` that is not one the router reads | one of the values the message lists |
 | `page-route-reserved` | a page under `/fn`, where the space's functions answer | another slug |
@@ -107,6 +112,7 @@ The space is not written until these are fixed.
 | `part-missing` | a compound element — a carousel, a tab container, a dropdown — without a part it renders through | the part the message names, inside it (`carousel()` writes its own track) |
 | `prop-missing` | an instance without a prop its component requires | `component('card', { props: { name: … } })`, or bind it |
 | `prop-name` | a prop whose name a template cannot read as `props.x` | letters, digits and `_` |
+| `prop-type-unknown` | a prop declared with a type no editor offers and nothing checks a value against | one of text, textarea, select, boolean, number, scalar, json, elementIds — words are `text` |
 | `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 |
@@ -131,6 +137,10 @@ The space is not written until these are fixed.
 | `step-name` | a step name a later step cannot read as `{{ name.field }}` | a letter first, then letters, digits, `-` and `_` |
 | `step-params` | a step param that does not exist, or a value outside its options | the params and values it lists |
 | `step-type` | a step `type` that does not exist | the step builders — `setState(…)`, `navigate(…)` — write it |
+| `style-condition-unknown` | a condition a class's rules cannot hold under | `motion-reduce`, `motion-safe`, or a container width — `container (max-width: 30rem)`, `container card (min-width: 480px)` |
+| `style-pseudo-content` | a `content` CSS cannot read — text without its quotes draws nothing — or a `before`/`after` with no `content`, which is not there at all | the text in quotes inside the string — `content: '"→"'`, `'""'` for an empty box — or a function such as `counter(step)` |
+| `style-pseudo-property` | a property the pseudo-element ignores — the browser drops it without a word | one it honours (`::selection` paints, `::marker` and `::placeholder` take text and font), or style the element |
+| `style-pseudo-unknown` | a pseudo-element a class cannot dress | one of `before`, `after`, `marker`, `placeholder`, `first-letter`, `first-line`, `selection` — without the `::` |
 | `style-state-unknown` | a state a selector does not react to | one of the states it lists (`hover`, `focus`, `active`…) |
 | `svg-not-svg` | an `svg` whose `content` is not one `<svg>…</svg>` — it draws nothing | the SVG markup alone; HTML around it goes in a `blockHtml` |
 | `template-short-source` | a source named without its prefix inside a template or a step | the full name: `apiContainer_stats`, `list_rows` |
@@ -161,6 +171,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | Code | What was wrong | Write instead |
 | --- | --- | --- |
 | `action-output-path` | a read of `.data` on a provider fed by a server action — it publishes the action’s output at its root, and `.data` is a `query` provider’s answer | the output’s own field — `apiContainer_feed.stories`, not `apiContainer_feed.data.stories` |
+| `animation-name-unknown` | `animation-name` naming keyframes the space does not declare — nothing plays | declare them in the space's `keyframes`, or name one it has |
 | `click-on-static-element` | a click flow on a container, text, heading, image or list item — no keyboard reaches it | the flow on a `button` (it holds children) or a `link` |
 | `colour-without-dark` | a colour token with no dark value | `{ light, dark, default }` |
 | `condition-starts-visible` | a computed visibility that shows until its data answers | `visible: { source, template }` |
@@ -176,9 +187,11 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `form-control-name-taken` | two controls in one form with one name — one overwrites the other | a name each |
 | `form-control-unnamed` | a control in a form with no `name` — its value never reaches `values` | `formControl({ name: 'email', … })` |
 | `form-value-compared-to-blank` | a `when` comparing a submitted field to `""` — a field nobody typed in is not sent | `operator: 'empty'` / `'notEmpty'` |
+| `heading-level-overridden` | a markdown's or richText's `heading` slot and a level's (`heading3`) both setting one property, the general class written later in the stylesheet — the level's value is lost | set the property on one of the two: the level slot for that level alone, `heading` for every heading |
 | `heading-level-skipped` | an `h4` right after an `h2` — the outline misses a level | the next level down; size it with its class |
 | `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`…) |
+| `link-current-section` | `current: 'section'` on a link that is never current (an external one) or current everywhere (to `/`) | leave `current` out — `'section'` is for a link to a section's own page, `/automations/runs` |
 | `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')` |
@@ -208,10 +221,12 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 
 | Code | Written the long way | The short way |
 | --- | --- | --- |
+| `class-overrides-class` | one class's shorthand erasing the longhand another class on the same element writes out — `padding` over `padding-top` — because the stylesheet writes it later: classes in the order they are first met, a breakpoint's rules after the base, never the order of a class list | the longhands the shorthand means instead of it (`padding-left`, `padding-right`), so it leaves the other class's alone — or `quiet: ['class-overrides-class']` when the shorthand is meant to win |
 | `content-attribute` | a button or a link whose children are only its words and an icon — a `text`, a `fontAwesome` — elements more than it needs | its own `content` and `icon` (`link({ href, content: 'Docs', icon: 'fa-solid fa-arrow-right', iconPlacement: 'after' })`); the icon's class goes on the `icon` slot, and what the text's class adds on the box's class, never the class itself |
 | `custom-css-class` | a `customCss` rule a class can hold — `.card:hover`, `.panel .icon` | the class's own `states` or `ancestors`, where the style editor reads it back and a breakpoint can change it |
-| `custom-css-notifications` | the toasts dressed with `.Toastify__toast` rules in `customCss` | `notifications: { font, fontSize, border, shadow, padding, background, text, radius }` |
+| `custom-css-notifications` | the toasts or their icon, close button or progress bar dressed with `.Toastify__*` rules in `customCss` | `notifications: { font, fontSize, fontWeight, minHeight, iconSize, closeColor, progressHeight, … }` |
 | `custom-css-sdk-default` | `customCss` repeating what the SDK already does for every space — less motion when asked, the theme toggle showing one icon | nothing: remove it |
+| `custom-css-slot` | a part of a built-in element dressed in `customCss` by the SDK's markup — a form control's `<input>`, a pager's buttons, a heading inside a markdown | a class on the slot of that part — `slots: { field: input }`, `elements.<type>.slots` — with its states |
 | `heavy-animation` | keyframes animating what the browser repaints or lays out again on every frame — a size, a position, a blur, a shadow, or a colour in a loop — which stutters whenever the page is busy, most of all while it loads | `opacity` and `transform`: a size or a position is `translate`/`scale`, a blur or a shadow is the `opacity` of a layer carrying it; a loop that must animate anything else starts `paused` and runs under `[data-hydrated]` |
 | `literal-colour` | a colour written out in a class where the space has a token of that value — it stays put in the dark scheme | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both |
 | `repeated-on-pages` | the same block — a header, a footer, a side panel — written into several pages | a layout holding it once (`layouts`, and `layout: { id, slot }` on each page) — a component when only some pages of a layout carry it; a link marks its own page with the `current` state |

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

@@ -2,8 +2,9 @@
 
 ## Animations
 
-- **Keyframes go in the space's `customCss`** (`'@keyframes marquee { to { transform: translateX(-50%); } }'`) and
-  the class names them: `animation: 'marquee 30s linear infinite'`.
+- **Keyframes go in the space's `keyframes`** (`keyframes: { marquee: { to: { transform: 'translateX(-50%)' } } }`)
+  and the class names them: `animation: 'marquee 30s linear infinite'`. A name no keyframes declare is warned
+  (`animation-name-unknown`).
 - **An element hidden by `visible` is `display: none`**, so an animation in its class runs again every time it is
   shown — the way to animate a slide in (see recipes/every-few-seconds.ts).
 - **Pause on hover** from the element around it: `ancestors: { [band.name]: { states: { hover:

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

@@ -17,7 +17,7 @@ It sizes the canvas to the device (at most 2× — `maxPixelRatio`), follows its
 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;
+`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi page 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

@@ -34,13 +34,13 @@ Only a suggestion's code: a problem is never quieted (`quiet-unknown`).
 | 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` |
+| A header copied per page so one link can be styled "active" | The link marks its own page: `states: { current: { … } }` on its class; `current: 'section'` for an entry lit on the pages under it | `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. 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` |
-| `.Toastify__toast { font-family: …; border: … }` in `customCss` | `notifications: { font, fontSize, border, shadow, padding, … }` | `custom-css-notifications` |
+| `.Toastify__toast { font-family: …; border: … }`, `.Toastify__toast-icon { width: … }` in `customCss` | `notifications: { font, fontSize, border, iconSize, closeColor, progressHeight, … }` | `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` |
 
 ## What it declares and never uses
@@ -63,6 +63,9 @@ And a few the suggestions do not count, because they cost styles rather than ele
 
 - **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.
+- **A shorthand in a class says every side.** On an element wearing two classes, one's `padding` erases the
+  `padding-top` the other writes out wherever the stylesheet writes it later; write the longhands it means
+  (`class-overrides-class` — a suggestion, quieted like the rest).
 - **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.

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

@@ -18,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`, `current` (a link to the page shown), `hidden`… beside the element's own `css` |
+| `states` | `hover`, `focus-visible`, `current` (the chosen link, toggle, tab), `expanded`, `first`/`last`/`odd`/`even`, `hidden`… |
 | `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 |
@@ -73,13 +73,9 @@ indented with space below it: `{ margin: '0px', padding: '0px' }` on its class t
 children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the
 parent, or give it `attributes: { subType: 'div' }`.
 
-A type this SDK does not ship — a plugin — is authored the same way: `defineElement<Props>({ type, … })`,
-`element<Props>('type', props)`, or `elementsFromManifest(manifest)`. See [plugins](plugins.md).
+A plugin's type is authored the same way: `defineElement<Props>({ type, … })` — see [plugins](plugins.md).
 
-**What a type takes, answered by the package** instead of the 7,000-line `.d.ts`: every catalogue is exported, keyed by
-type — `elementCatalog` (what it is for), `elementDefaultAttributes`, `elementAttributeNames`, `elementTriggers`,
-`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS` — and
-`npx @plitzi/cli explain formControl` prints them for one type.
+**What a type takes:** `npx @plitzi/cli explain formControl`, or the exported catalogues ([validation.md](validation.md)).
 
 ## CSS
 
@@ -111,15 +107,20 @@ const card = styles('card', {
 container({ class: card, children: [ … ] });
 ```
 
-- A flat object is the base rules; `{ css, states, variants, ancestors }` when there is more. Each part may be written
+- A flat object is the base rules; `{ css, states, variants, ancestors, pseudos, conditions }` when there is more. Each part may be written
   per breakpoint.
-- **Share a rule as a class, never as a spread.** Spreading a `const` into each element's `css` shares the source and
-  duplicates the document: one selector per element, so restyling one card in the builder restyles one card.
+- **Share a rule as a class, never as a spread** into each element's `css`: that is one selector per element, so
+  restyling one card in the builder restyles one card.
 - **Build a family from a plain object**, not by layering classes: `styles('button-primary', { ...buttonBase, … })`.
+- Of two classes on an element, the one the stylesheet writes later wins (first met; a breakpoint's after the base),
+  not the list's last: write the longhands a class means (`class-overrides-class`).
 - One name declared twice with rules that disagree is refused. Declare a class once, in the module that owns it, and
   import it.
 - `ancestors: { [sidebar.name]: { variants: { collapsed: { display: 'none' } } } }` styles an element by the state or
-  variant of an ancestor class — the way to react to a parent's hover or collapse without a flow.
+  variant of an ancestor class — the way to react to a parent's hover or collapse without a flow; `'>'` is the parent,
+  whatever it wears (a component's part: `{ '>': { states: { expanded: … } } }`).
+- `pseudos: { after: { content: '"→"' } }` (`before`/`after` need a quoted `content`; also `selection`, `marker`,
+  `placeholder`, `first-letter`, `first-line`). `conditions: { 'motion-reduce': …, 'container (max-width: 30rem)': … }`.
 - **`hidden` is how an element looks while its `visible` says no** — where it goes as it hides, and where it comes
   from as it shows. Give the class a transition that includes `display` with `allow-discrete`, and a panel fades or
   slides instead of blinking; the transition on the base is the way in, the one in `hidden` the way out:
@@ -142,16 +143,15 @@ 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.
-- **Slots** are an element's other selectors: a `formControl`'s `input`, `label`, `error`; a `modalContainer`'s
-  `backgroundContainer`, `rootContainer`, `headerContainer`, `headerTitle`, `headerCloseButton`, `bodyContainer`; a
-  `dialogContainer`'s footer and buttons. `elementSlots` lists them all by type. Style one element's with `slots`, a
-  whole type's with `elements.<type>.slots`.
+- **The navigation goes in a layout, once:** a link to the page shown dresses itself with its class's
+  `states: { current: { … } }` — never a class picked per page, which copies the header into every page.
+- **`:hover` is part of the selector, not a rule in `customCss`.** `customCss` is for what no class can say: a rule
+  across two unrelated elements, the inside of a third-party widget.
+- Per element TYPE defaults go in `elements: { heading: { base, states, variants, pseudos, slots } }` — a whole type.
+- **Slots** are an element's parts (not `customCss`): a `formControl`'s `input` (the box), `field` (its `<input>`),
+  `label`, `requiredMark`, `error`; a `markdown`'s or `richText`'s `heading`, `heading2`, `link`, `codeBlockFrame`…;
+  a `pagination`'s `page` (the one shown: its `current` state). `plitzi explain <type>` lists them. Style one
+  element's with `slots`, a type's with `elements.<type>.slots`.
 - A `modalContainer` / `dialogContainer` is fixed to the viewport, as tall as its content up to the screen, and 500px
   wide up to the screen; theme its look through its slots.
 
@@ -159,7 +159,7 @@ container({ class: card, children: [ … ] });
 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. 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).
+`idle`); for "the current page", `current` in [layouts.md](layouts.md).
 
 ## From Tailwind classes
 
@@ -169,4 +169,4 @@ A design written in Tailwind classes becomes classes the builder edits with `sty
 ## Colours, themes and motion
 
 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).
+the space's `keyframes` — see [colours-and-motion.md](colours-and-motion.md).

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

@@ -21,8 +21,8 @@ source — `when({ field: 'flags.newCheckout', operator: '=', value: true }, …
 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,
-  with no error — which is why the builders exist.
+  callback under an element's id, a utility under nothing. Either half named wrong is a control that silently does
+  nothing.
 - **Which `setState`.** `setState({ key })` writes `runtime.state.<key>` and is read as `state.<key>`; never put
   `state.` in the key. `updateElement(…)` changes one element's own attribute or state.
 - **Flip in one step.** `toggleState({ key })` for app state, `toggleElement({ category: 'state', key: 'visibility' },
@@ -48,7 +48,7 @@ Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{
 
 | Trigger                                                                                                | Payload                                                 |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| `onChange` (formControl)                                                                               | `value` (a boolean for a checkbox), `name`              |
+| `onChange` (formControl)                                                                               | `value` (a boolean for a checkbox or switch), `name`    |
 | `onSubmit` (form)                                                                                      | `values` (by control `name`), `actionUrl`, `method`     |
 | `onPageLoad` (page)                                                                                    | `pageId`, `routeParams`, `queryParams`                  |
 | `onApiSuccess` / `onApiError` (apiContainer)                                                           | `url`, `method`, `status`, `data`                       |
@@ -61,6 +61,10 @@ Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{
 `named('quote', step)` is how a later step reads an earlier one: `{{ quote.output.total }}`. The trigger too:
 `named('submitted', onSubmit())` → `{{ submitted.values.email }}`. Unnamed steps get ids nothing can refer to.
 
+`whenSucceeded` / `whenFailed` read a server action's `status` (`runServerAction` only); any other step is asked what
+it publishes (`npx @plitzi/cli explain login` lists it) — after `named('signedIn', authLogin(…))`,
+`when({ field: 'signedIn.ok', operator: '=', value: true }, …)`.
+
 A step's params are templates, evaluated in full (conditions, loops, filters). A source in them is named in full:
 a row's button posts `{ jobId: '{{ list_jobRows.item.id }}' }` — the row that was clicked; the short name is refused.
 
@@ -75,7 +79,7 @@ so `when({ field: 'sent.values.code', operator: '=', value: '' }, …)` never ho
 ## Writes and what they refresh
 
 `webHook` (not GET) refreshes every request to its own site when it succeeds; `runServerAction` refreshes
-everything. Say what it should refresh — `invalidateQueries: 'elements', invalidateElements: ['orders']` — or
+everything, server-driven providers included. Say what it should refresh — `invalidateQueries: 'elements', invalidateElements: ['orders']` — or
 `'none'` for a step that only reads, or when a refresh would make the page act on the new answer mid-flow.
 
 ## Triggers belong to the element that fires them
@@ -134,10 +138,13 @@ without a word.
 
 `addNotification({ content: 'Saved', appearance: 'success' })` — `appearance` is `success`, `danger`, `warning` or
 `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.
+`success`, `danger`, `warning`, `info`), shape (`radius`, `font`, `fontSize`, `fontWeight`, `lineHeight`, `minHeight`,
+`border`, `shadow`, `padding`) and the parts inside (`iconSize`, `iconGap`, `closeColor`, `closeOpacity`,
+`progressHeight`), one CSS value each: `notifications: { background: 'var(--card)', radius: '12px', iconSize: '18px' }`.
+The toast carries no class of the space's, so this — not a `.Toastify__*` rule in `customCss` — is where it is
+dressed.
+
+Copy link: `copyToClipboard('{{ navigation.href }}')`, then the toast — it fails with no clipboard.
 
 ## Modals, dropdowns, tabs
 

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

@@ -0,0 +1,33 @@
+# Every reference, and when to read it
+
+Read one only when the task names its subject.
+
+| Read | When |
+| --- | --- |
+| [rules.md](rules.md) | Every rule of writing a space, with its why |
+| [recipes.md](recipes.md) | A whole working file for a common task, to copy and rename |
+| [elements-and-styles.md](elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
+| [colours-and-motion.md](colours-and-motion.md) | Colours for both themes, tokens, keyframes, and motion that stays smooth (good practices) |
+| [tailwind.md](tailwind.md) | A design written in Tailwind classes: `tw()`, its breakpoints and states, what it refuses |
+| [layouts.md](layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
+| [efficiency.md](efficiency.md) | The same page with fewer elements: the suggestions `authorSpace` makes, and the short way for each long one |
+| [components.md](components.md) | One block placed many times — a card, a tier, a testimonial: props, slots, binding a row into one, why it is closed |
+| [data-and-visibility.md](data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
+| [kept-state.md](kept-state.md) | State that outlives a reload: `keepState`, transient and painted keys |
+| [auth.md](auth.md) | Signing people in: providers, `authLogin`, `auth.*`, visitor roles |
+| [feature-flags.md](feature-flags.md) | Switching a part of the space on or off — a beta, a rollout, the old version kept until the new one ships |
+| [lists.md](lists.md) | Rendering rows, filtering and sorting them, a detail page for one record, carousels |
+| [typed-sources.md](typed-sources.md) | Data typed by a sample of it: `source()`, typed rows, `twig` for templates |
+| [validation.md](validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
+| [authoring-errors.md](authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
+| [templates.md](templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
+| [flows.md](flows.md) | Clicks, submits, page loads, every few seconds, server actions, modals, state |
+| [realtime.md](realtime.md) | Pages that see each other: channels, presence, cursors, a shared board, who may hear a topic |
+| [plugins.md](plugins.md) | A component of your own: props, binding them, writing state, channels, registering, behaving in the builder |
+| [drawing.md](drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL, a loop that stops when unseen |
+| [structure.md](structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
+| [testing.md](testing.md) | Any test: `inspectPage`, handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
+| [performance.md](performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |
+| [snippets-and-export.md](snippets-and-export.md) | Publishing a snippet; turning an exported JSON — or a server action — into code |
+| [accessibility.md](accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
+| [review-checklist.md](review-checklist.md) | Before you say it is done |

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

@@ -74,7 +74,6 @@ const navGroup = (group: DocsGroup): ElementSpec =>
         id: `docs-nav-${entry.id}`,
         href: entry.id,
         class: navLink,
-        bind: [activeOn(navLink, entry.id)],
         children: [text(entry.title, { id: `docs-nav-label-${entry.id}` })]
       })
     )
@@ -83,33 +82,31 @@ const navGroup = (group: DocsGroup): ElementSpec =>
 
 Adding a page is one entry in the list: the menu, the index and the neighbours' "next" follow.
 
-## The current entry: `activeOn`
+## The current entry
 
-A menu in a layout is the same nodes on every page, so it cannot have the right entry styled by hand. It asks which
-page is showing:
+A menu in a layout is the same nodes on every page, so it cannot have the right entry styled by hand — and does not
+need to. A link to the page being shown marks itself: `aria-current="page"`, which a screen reader announces, and its
+class's `current` state dresses it:
 
 ```ts
-const navLink = styles('nav-link', {
-  css: { color: 'var(--muted)' },
-  variants: { active: { color: 'var(--foreground)', 'font-weight': '600' } }
-});
+const navLink = styles('nav-link', { css: { color: 'var(--muted)' }, states: { current: { color: 'var(--foreground)' } } });
 
-link({ href: 'spaces', class: navLink, bind: [activeOn(navLink, ['spaces', 'space-record'])] });
+link({ href: '/pricing', mode: 'internal', class: navLink });
 ```
 
-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:
+An entry lit for a SECTION — a journal and its articles, `/automations/runs` while on `/automations/runs/42` — says
+`current: 'section'`: current on its page and on every page under its path, at a `/` (`/runs` holds `/runs/42`, not
+`/runsx`), announced there as the current entry (`aria-current="true"`); the same `current` state dresses it. A link to
+`/` holds every page, so authoring warns (`link-current-section`):
 
 ```ts
-const navLink = styles('nav-link', { css: { color: 'var(--muted)' }, states: { current: { color: 'var(--foreground)' } } });
-
-link({ href: '/pricing', mode: 'internal', class: navLink });
+link({ href: 'runs', class: navLink, current: 'section' });
 ```
 
-`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.
+`activeOn(class, pageIds, { variant?, slot? })` is for an entry lit on pages NOT under its path — `['spaces',
+'space-record']` when a record lives at `/s/:id`: 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/plugins.md

@@ -9,7 +9,7 @@ custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best
 
 ## Creating one
 
-The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli add plugin seat-picker` (a
+The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli plugin add seat-picker` (a
 package of its own and packing it: the CLI skill).
 
 One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
@@ -88,7 +88,7 @@ the widths the space's styles use, instead of a width of the plugin's own.
 
 ## Its own server code
 
-`plitzi add plugin board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
+`plitzi plugin add board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
 under `/fn/plugins/board/`; the component names them, with nothing for the space to wire:
 
 ```tsx
@@ -96,7 +96,7 @@ const route = usePluginRoute('board'); // from '@plitzi/plitzi-sdk'
 const url = route('/layout'); // undefined where no server runs code (the canvas)
 ```
 
-Its `ctx.kv` is the plugin's own; the space's credentials and channels are not.
+Its `ctx.kv` is the plugin's own; the space's credentials, channels and data are not.
 
 ## Talking to other pages
 

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

@@ -0,0 +1,25 @@
+# Recipes
+
+Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
+
+| To… | Open |
+| --- | --- |
+| Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](../recipes/show-data.ts) |
+| Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](../recipes/typed-data.ts) |
+| Data read by the page server (`--mode server`) | [recipes/server-data.ts](../recipes/server-data.ts) |
+| An accordion, one answer open at a time | [recipes/accordion.ts](../recipes/accordion.ts) |
+| Filter and sort a list from a select | [recipes/filter-a-list.ts](../recipes/filter-a-list.ts) |
+| A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](../recipes/detail-page.ts) |
+| Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](../recipes/link-to-a-section.ts) |
+| A carousel: slides with arrows, dots and autoplay; a marquee; a row that swipes | [recipes/carousel.ts](../recipes/carousel.ts) |
+| Do something every few seconds — a ticker, a poll, a slideshow by hand | [recipes/every-few-seconds.ts](../recipes/every-few-seconds.ts) |
+| A marquee that scrolls for ever and stops under the pointer | [recipes/marquee.ts](../recipes/marquee.ts) |
+| A row that scrolls sideways, with arrows that hide at its ends | [recipes/scroll-a-row.ts](../recipes/scroll-a-row.ts) |
+| A link built from a row: WhatsApp with the product's name, `mailto:` | [recipes/link-with-data.ts](../recipes/link-with-data.ts) |
+| React to a click or a submit; a modal; a switch | [recipes/forms-and-modals.ts](../recipes/forms-and-modals.ts) |
+| A feature behind a flag | [recipes/feature-flag.ts](../recipes/feature-flag.ts) |
+| An element of your own (a plugin), checked | [recipes/plugin.ts](../recipes/plugin.ts) |
+| Controls a screen reader and a browser agent can use | [recipes/usable-without-sight.ts](../recipes/usable-without-sight.ts) |
+| Tokens, a shared class, "the class plus one thing", tablet and phone at once | [recipes/style-a-page.ts](../recipes/style-a-page.ts) |
+| A design in Tailwind classes, kept as classes the builder edits | [recipes/from-tailwind.ts](../recipes/from-tailwind.ts) |
+| A page from elsewhere in a frame (`embed`: a map, a player) and a drawing of your own (`svg`) | [recipes/embed-and-svg.ts](../recipes/embed-and-svg.ts) |

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

@@ -50,7 +50,8 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
 
 ## No copies
 
-- [ ] Chrome shared by pages is a layout; the current menu entry comes from `activeOn`, not per-page styling.
+- [ ] Chrome shared by pages is a layout; the current menu entry marks itself (`current` state, `current: 'section'`),
+      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, and a helper that