@plitzi/sdk-server 0.37.1 → 0.37.2

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

@@ -0,0 +1,107 @@
+# Elements and styles
+
+## Elements
+
+One factory per element, named after it. Attributes and the authoring fields go in ONE flat object:
+
+```ts
+heading({ content: 'Fieldnotes', subType: 'h2', class: title })
+image({ src: '/fox.jpg', alt: 'A fox', css: { 'aspect-ratio': '3/2' } })
+container({ class: card, children: [ … ] })
+text('Wildlife, close up')          // a string is the content
+container([hero, grid])             // an array is the children
+```
+
+| Authoring field | What it does |
+| --- | --- |
+| `id` | the ONE name this element answers to — its key in the document, a binding's source, a step's target. 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`… beside the element's own `css` |
+| `variant` | a variant of the class it wears (when the class declares it) or of its type |
+| `slots` | a class for one of the element's OTHER selectors — a form control's `input` |
+| `bind` | where a value comes from |
+| `visible` | a condition (`'src'`, `'!src'`), or `false` to start hidden |
+| `flows` | what happens on click, on submit, on load |
+| `runtime` | `'server'` resolves this provider's data on the server |
+| `children` | the tree |
+| `meta` | `meta.label` is the element's name in the builder's tree |
+
+Anything else in the object is an **attribute** (`authorSpace` warns `unknown-attribute` for one the element never
+reads).
+
+**A link's `href` is a page id.** `link({ href: 'reports' })` finds the page by id, folder included. `mode: 'internal'`
+for a path within the space carrying `{{tokens}}`; `mode: 'external'` for a full URL passed through untouched. A link
+is an `<a>`: never put a link inside another link — make the card the link, or the button, not both.
+
+**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 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
+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)`.
+
+## CSS
+
+Write CSS as you write CSS, shorthands included — they are expanded to the longhands Plitzi's editor reads. A property
+outside the vocabulary is refused with the key it should have been (`paddingTop` → `padding-top`).
+
+- `column(gap, extra?)`, `row(gap, extra?)`, `grid(columns, gap, extra?)` for the three layouts every space repeats.
+- **Breakpoints are ranges, not a cascade.** `tablet` is 48–64rem, `mobile` below 48rem, and each inherits only from
+  `desktop` — a rule for `tablet` never reaches a phone. Write it in both; `authorSpace` warns
+  `tablet-rule-skips-mobile`.
+- **Fonts are declared.** A `font-family` loads only if the space lists the face in `fonts`
+  (`{ source: 'google', family: 'Geist', fallback: 'system-ui, sans-serif', weights: [400, 600], styles: ['normal'] }`).
+
+## Classes
+
+```ts
+const card = styles('card', {
+  css: { padding: '24px', 'border-radius': '12px', 'background-color': 'var(--card)' },
+  states: { hover: { 'border-color': 'var(--primary)' }, 'focus-visible': { outline: '2px solid var(--primary)' } },
+  variants: { active: { 'border-color': 'var(--primary)' } }
+});
+
+container({ class: card, children: [ … ] });
+```
+
+- A flat object is the base rules; `{ css, states, variants, ancestors }` 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.
+- **Build a family from a plain object**, not by layering classes: `styles('button-primary', { ...buttonBase, … })`.
+- 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.
+- **`: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.
+
+**A variant chosen by the data:** `variantFrom(pill, 'jobs.item.status')`, or with a template when the data does not
+already speak in variant names — `variantFrom(pill, 'runs.item.status', { template: "{{ source == 'completed' ?
+'ok' : 'failed' }}" })`. The binding's key names the CLASS; never write it by hand. For "the current page", see
+`activeOn` in [layouts.md](layouts.md).
+
+## Colours and themes
+
+Every colour is a **variable** with both values, and elements say `var(--name)`:
+
+```ts
+variables: {
+  color: {
+    foreground: { light: '#0c0c14', dark: '#ededf3', default: '#0c0c14' },
+    card: { light: '#ffffff', dark: '#101019', default: '#ffffff' },
+    primary: { light: '#5b3df5', dark: '#6e52f7', default: '#5b3df5' }
+  }
+}
+```
+
+- Choose each value against its own background: a colour picked on white is not the same colour on near-black.
+- Fixed colours are only for surfaces that are fixed in both themes (a brand panel that is always dark) — and then
+  the text on them is fixed too. Theme-following text on a fixed background is the bug.
+- A tint of a token is `color-mix(in srgb, var(--primary) 12%, transparent)`, which follows the theme for free.
+- `themeToggle()` is the switch; `theme.resolved` (`light`/`dark`) is a global source for anything else that needs it.

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

@@ -0,0 +1,80 @@
+# Flows
+
+```ts
+button({
+  id: 'cta',
+  content: 'Get a quote',
+  flows: [[
+    onClick(),
+    named('quote', runServerAction({ actionId: 'shipping-quote', input: { city: 'Berlin' }, mode: 'await' })),
+    whenSucceeded('quote', setState({ key: 'quote', type: 'text', value: '{{ quote.output.summary }}' })),
+    whenFailed('quote', addNotification({ content: 'Could not reach the courier', appeareance: 'danger' }))
+  ]]
+})
+```
+
+A flow is a list: a trigger, then steps in order. "Only if" is on the step (`when`, `whenSucceeded`, `whenFailed`),
+never a nested tree. Use the step builders — they fill in where a step runs and what it takes:
+
+- **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.
+- **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' },
+  'panel')` to show/hide an element. Never two branches under opposite `when` guards — they read the state as it was
+  when the flow started, a click behind.
+- **Keys are flat names.** A dotted key (`docsClosed.start`) is split into a path; use `docsClosedStart`.
+
+## Reading what came before
+
+`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.
+
+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.
+
+**Pass objects, not JSON text.** `input: { title: '{{ form.values.title }}' }`, never `input: '{"title": …}'` — a
+value with a quotation mark or a newline makes the text unparseable, and unparseable input posts `{}`.
+
+## 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
+`'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
+
+Every element fires `onClick`, `onLoad`, `onHover`, `onMouseEnter`/`onMouseLeave`, `onFocus`/`onBlur` and the ends of a
+server action it started (`onFlowEnd`, `onFlowError`, `onFlowProgress`). A `page` fires `onPageLoad`, a `form`
+`onSubmit`, a `formControl` `onChange`, an `apiContainer` `onApiSuccess`/`onApiError` (each answer, either runtime,
+each refresh), a `modalContainer` `onModalOpen`/`onModalClose`, a `pagination` `onPageChange`. A flow on an element
+that never fires its trigger is refused, naming the type that does.
+
+**A form's flow goes on the `form`**, which hands its submit over with `managedByInteractions: true`
+(`FORM_SUBMIT_UNMANAGED` otherwise — the browser submits it natively and `onSubmit` never fires):
+
+```ts
+form({
+  id: 'signup',
+  managedByInteractions: true,
+  flows: [[named('submitted', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ submitted.values.email }}' })]],
+  children: [formControl({ id: 'email', name: 'email', label: 'Email', subType: 'email' }), button({ content: 'Sign up', subType: 'submit' })]
+})
+```
+
+A `formControl` is `required` by default: an optional field says `required: false`, or an empty one stops the submit
+without a word.
+
+## Modals, dropdowns, tabs
+
+- A modal or dialog is declared `visible: false` and driven with `openModal('credits')` / `closeModal('credits')`
+  (`openDialog` / `closeDialog`). `openModal`'s second argument is read inside as `{{ modalContainer_credits.content }}`.
+- A `dropdown`'s label is a child and its `dropdownPopup` sits inside it; a `tabContainer`'s header and body are held
+  inside it too. Outside, they are refused.
+
+## Lists as state
+
+`toggleInState({ key: 'picks', value })` keeps a list; `when({ field: 'state.picks', operator: 'contains', value })`
+asks it. `appendState({ key, value, withId: true })` stores `{ id, value }` — bind `.value`, address by `.id`.
+`whenFailed` matches every outcome that is not `completed` (also `skipped`, `aborted`).

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

@@ -0,0 +1,140 @@
+# Layouts, and not writing anything twice
+
+A space grows by pages, and most of what a page shows is the same on its neighbours: the top bar, the sidebar, the
+footer, the menu, the "ask for help" card. Written into each page, that chrome is a copy per page — sixteen docs pages
+carried the same sidebar sixteen times, around 900 elements whose only difference was which link was highlighted, and
+the copies disagreed the first time one was edited. The tools below remove every one of those copies.
+
+## A layout is the shell, written once
+
+```ts
+export const docsLayout: LayoutSpec = {
+  id: 'docs-layout',
+  label: 'Docs Layout',
+  folder: 'docs',                      // files it beside its pages in the builder; it routes nothing
+  body: [
+    container({
+      id: 'docs-shell',
+      class: shell,
+      children: [
+        topbar(),                      // helpers returning ElementSpec keep the layout readable
+        container({ id: 'docs-body', class: body, children: [sidebar(), container({ id: 'docs-slot', class: slot })] })
+      ]
+    })
+  ]
+};
+
+// in the space
+layouts: [appLayout, docsLayout],
+pages: [{ name: 'Quickstart', slug: 'quickstart', folder: 'docs', layout: { id: 'docs-layout', slot: 'docs-slot' }, body: [ … ] }]
+```
+
+- **The slot** is the element in the layout where the page's body goes. It must be inside the layout (checked).
+- **Not re-mounted on navigation.** Moving between pages of one layout keeps the shell — its scroll, its open menus,
+  its providers, its state — and swaps only the slot. That is also why a layout is cheaper than a copy.
+- **Layouts nest.** `layout: { id: 'app-shell', slot: 'main' }` on a LAYOUT puts a section shell (analytics tabs, docs
+  sidebar) inside the application shell. The page resolves the chain from the outside in.
+- **A provider in a layout serves every page** — the plan in a sidebar, a star count in a top bar. A server provider
+  (`runtime: 'server'`) in a layout is resolved with the page like one in the page.
+- **Ids are shared** between a layout and all its pages. Name layout elements after the layout (`docs-topbar`), and
+  let pages prefix theirs with the page id.
+
+## The menu is data
+
+The pages a menu lists, their titles, their summaries and their order are ONE list, and everything that shows them
+reads it — the sidebar, the page title, the meta description, "previous / next", an index of cards:
+
+```ts
+// nav.ts — the single source
+export const DOCS_NAV = [
+  {
+    id: 'start',
+    title: 'Getting started',
+    icon: 'fas fa-rocket',
+    entries: [
+      { id: 'docs-index', slug: '', title: 'Plitzi for developers', lede: 'What a space is…', icon: 'fas fa-book-open' },
+      { id: 'docs-quickstart', slug: 'quickstart', title: 'Quickstart', lede: 'One command…', icon: 'fas fa-bolt' }
+    ]
+  }
+] as const;
+
+// layout.ts — the sidebar, generated
+const navGroup = (group: DocsGroup): ElementSpec =>
+  container({
+    id: `docs-group-${group.id}`,
+    children: group.entries.map(entry =>
+      link({
+        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}` })]
+      })
+    )
+  });
+```
+
+Adding a page is one entry in the list: the menu, the index and the neighbours' "next" follow.
+
+## The current entry: `activeOn`
+
+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:
+
+```ts
+const navLink = styles('nav-link', {
+  css: { color: 'var(--muted)' },
+  variants: { active: { color: 'var(--foreground)', 'font-weight': '600' } }
+});
+
+link({ href: 'spaces', class: navLink, bind: [activeOn(navLink, ['spaces', 'space-record'])] });
+```
+
+`activeOn(class, pageIds, { variant?, slot? })` binds the class's variant to `navigation.currentPageId`: the `active`
+variant on those pages, `idle` everywhere else. Several ids for one entry — a section and the pages under it. Do not
+write the binding by hand with a `when` rule per page; that is the long form this replaces.
+
+## Pages from a factory
+
+When pages share a shape — a heading, a lede, content, a footer — the shape is a function and each page is its data:
+
+```ts
+export const docsPage = (id: string, markdownSource: string): PageSpec => {
+  const entry = docsEntry(id);                          // title, slug, lede from nav.ts
+
+  return {
+    id,
+    name: entry.title,
+    slug: entry.slug,
+    seoTitle: `${entry.title} — Docs`,
+    seoDescription: entry.lede,
+    folder: 'docs',
+    layout: { id: 'docs-layout', slot: 'docs-slot' },
+    body: [
+      container({
+        id: `${id}-main`,                                 // prefixed: this function runs once per page
+        class: main,
+        children: [heading(entry.title, { id: `${id}-title`, class: title }), markdown(markdownSource, { id: `${id}-md` }), ...footer(id)]
+      })
+    ]
+  };
+};
+
+export const quickstart = docsPage('docs-quickstart', `## One command …`);
+```
+
+Every page is now its content and nothing else, and every page is guaranteed the same structure.
+
+## Styles follow the same rule
+
+- A role used on several pages is ONE class (`panelCard`, `pageTitle`), declared in the module that owns the area and
+  imported — never re-declared per page, never spread into `css`.
+- Layout classes live with the layout; page classes with their page; shared ones in one `styles.ts` per area.
+- A family of looks is a shared base object and one class per member; a state of one element is a variant.
+- If you find yourself copying a `css` block, it is a class. If you find yourself copying an element tree, it is a
+  function, a layout, or a `map` over data.
+
+## When NOT to use a layout
+
+A block that appears on one page belongs to that page. A block on several pages but in different places is a
+function (`communityLinks('docs-help', 'on-surface')`), not a layout. A layout is for what frames the page.

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

@@ -0,0 +1,50 @@
+# Before you say it is done
+
+The feedback a reviewer gives on almost every change to a space, so you can give it to yourself first. Go through all
+of it; each line is something that has shipped broken before.
+
+## It renders, and says so
+
+- [ ] `authorSpace` returns **zero warnings**. Each one is written code that will not do what it says.
+- [ ] No console errors on any page you touched.
+
+## Nothing flashes, nothing jumps
+
+- [ ] Nothing appears only to be taken away while data loads: a condition that REVEALS an element starts hidden and
+      answers `'false'` until its source arrives. Checked from the FIRST frame, not a screenshot at the end.
+- [ ] Nothing that is on screen by default disappears because a flag has not been set yet (a sidebar until it is
+      folded). Checked on a fresh visit, with no state kept from before.
+- [ ] Empty states show only when the answer arrived and is empty — never while loading.
+- [ ] No hidden element leaves a hole: the element itself is hidden, not a wrapper around it.
+- [ ] Nothing shifts when the data lands: a loading area keeps its size, numbers use tabular figures.
+
+## Every screen, every theme
+
+- [ ] Desktop, tablet and mobile — and nothing scrolls sideways on a phone. Tablet rules are repeated for mobile when
+      phones should keep them.
+- [ ] Light AND dark. Every colour is a token with both values; no theme-following text on a fixed background.
+- [ ] Focus is visible on everything clickable (`focus-visible`), and `prefers-reduced-motion` stops what moves.
+
+## No copies
+
+- [ ] Chrome shared by pages is a layout; the current menu entry comes from `activeOn`, not per-page styling.
+- [ ] A look used twice is a class; a tree used twice is a function or a `map` over data; a list of pages, links or
+      plans is ONE array everything reads.
+- [ ] No positional ids (`container-45`) in what you wrote; every referenced element is named, prefixed when a
+      helper runs more than once.
+
+## True, and in the right place
+
+- [ ] Every number, name and status on screen comes from a source. No placeholder figures, no invented logos or
+      testimonials. A panel with nothing true to show is an empty state.
+- [ ] Times are formatted with an explicit zone and say which (`… 06:00 UTC`).
+- [ ] Logic lives in binding templates or on the server, not in an attribute (where a condition is never evaluated).
+- [ ] Writes refresh what they changed — and only that (`invalidateQueries`); a multi-step form does not refresh the
+      provider that decides whether to leave.
+- [ ] What only an administrator may read is shown only to administrators — and the check is a real boolean, not
+      a template left as text.
+
+## Proven
+
+- [ ] You looked at it: the visual check ran, on the pages you changed, in both themes.
+- [ ] Both sides of each condition were seen: the empty account and the full one, the admin and the member.

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

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

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

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

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

@@ -0,0 +1,69 @@
+# Templates
+
+Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}` does depends on WHERE it is written.
+
+## Where a template runs
+
+| Written in | What is evaluated | Use it for |
+| --- | --- | --- |
+| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | anything computed — this is where logic goes |
+| a flow step's params | the whole template | values a step sends or stores |
+| an ATTRIBUTE (`href`, `src`, `content`…) | only `{{ name }}` and `{{ name|filter }}` tokens | dropping a value into a string |
+
+An attribute holding only a condition — `href: "/x/{{ on ? 'a' : 'b' }}"` — is used **as written** (`authorSpace` warns
+`template-never-resolved`). Move the expression into a binding:
+
+```ts
+link({ href: '/', bind: [{ to: 'href', source: 'state.workspace.id',
+  transformers: [{ action: 'twigTemplate', params: { template: "{{ source ? '/workspace/' ~ source : '/' }}" } }] }] })
+```
+
+In a binding, `source` is the value at the binding's `source`; everything else in scope is a source named in full.
+
+## Naming sources inside a template
+
+Always the full name — the element's kind, an underscore, its id: `apiContainer_stats`, `list_rows`,
+`modalContainer_credits`. The globals (`state`, `auth`, `navigation`, `variables`, `theme`) are named as themselves. In
+a flow, an earlier step is read by the name given with `named('quote', …)`: `{{ quote.output.total }}`.
+
+A list publishes one scope per row: inside a row, `list_rows.item` is THAT row.
+
+## The language
+
+- Operators: `~` (concat), `+ - * / %`, `== != < > <= >=`, `and or not`, `in`, `a ? b : c`, `a ?? b`.
+- Access: `a.b`, `a.0`, `a[i]`, `(expr).key`, `(expr)[i]`.
+- Blocks: `{% set x = … %}`, `{% if %}…{% elseif %}…{% else %}…{% endif %}`, `{% for item in list %}…{% endfor %}`.
+- Arrow functions in filters: `rows|sort(r => r.at)|first`, `rows|filter(r => r.active)`, `rows|map(r => r.name)`.
+- Tests: `is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd`, and their `is not` forms.
+- Functions: `range`, `min`, `max`, `cycle`.
+
+Filters: `default upper lower trim capitalize title camelize kebab snake ltrim rtrim pad replace slice split join
+reverse length first last contains startswith endswith number number_format round abs format sort batch chunk map
+reduce merge keys values filter column find pluck unique flatten sum without only index_by group_by url_encode
+striptags spaceless json_encode to_json raw date year month day hours minutes seconds weekday random`.
+
+A lookup across two sources — a row joined to the stats around it:
+
+```ts
+"{% set s = apiContainer_stats.data.spaces|find('id', list_spaces.item.id) %}{{ s ? s.traffic.views|number_format(0, '.', ',') ~ ' views' : '—' }}"
+// or, in one expression:
+"{{ (apiContainer_stats.data.spaces|find('id', list_spaces.item.id)).traffic.views ?? 0 }}"
+```
+
+## Values to be careful with
+
+- **An empty list is false**, like an absent one. To tell "arrived and empty" from "not arrived":
+  `{{ items is defined and items is empty }}`.
+- **`json_encode` of a string is the string**, unquoted. Do not build JSON by interpolating text a visitor typed —
+  pass objects as step params instead.
+- **Numbers**: `number_format(decimals, point, thousands)`; `round(precision)`.
+- **A template that renders a number hands on a number** in step params (`'1'` → `1`).
+
+## Dates
+
+- `|date(format, zone)` — tokens `Y m n d j H G i s l F M N w U`. **Always pass a zone** (`'UTC'`) and print it: with
+  no zone the date is formatted in the local time of whoever renders it — the server's for the HTML, the visitor's
+  after hydration — and the two disagree.
+- A timestamp can be seconds or milliseconds, a number or a string of digits — all read.
+- For "3 minutes ago", the `dateConverter` transformer with `{ asAge: true }`; give it `isUnix: false` for an ISO
+  string. Its checkbox params accept real booleans (and `'true'`/`'false'`).

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

@@ -0,0 +1,52 @@
+# Testing what you authored
+
+## Handles
+
+`authorSpace` returns `handles`: every element by id, with the selector that finds it in the rendered page
+(`[data-plitzi-el="<id>"]`). `handles.element(id)` throws on a name that does not exist, and `locate(page, handles)`
+turns an id into a Playwright locator. Pages are in `handles.pages` (each with its `path` and `elements`); a layout's
+elements are in `handles.layouts` and render on every page that names the layout.
+
+An element marked `conditional` is on screen only under a condition of its own or of an ancestor — skip it in an
+"every named element is visible" check. A `formControl`'s id names its wrapper: type into
+`locate('email').locator('input')`.
+
+Select by `data-plitzi-el`, never by a generated class name: authoring derives `<type>-<hash>` for an element's own
+rules, and that name changes when the rules do.
+
+## What to check
+
+- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (below 48rem); `colorScheme: 'dark'` as well
+  as light.
+- **No horizontal scroll on a phone.** A column child grows to its content unless its parent stretches it; a code
+  block or a wide table is what finds out.
+- **The loading frame, not only the finished one.** A screenshot after the page settles cannot see an element that
+  flashed and went. Watch from the first frame:
+
+```ts
+await page.addInitScript(ids => {
+  const painted: string[] = [];
+  (window as unknown as { __painted: string[] }).__painted = painted;
+  const watch = (): void => {
+    for (const id of ids) {
+      const element = document.querySelector(`[data-plitzi-el="${id}"]`);
+      if (element && element.getClientRects().length > 0 && !painted.includes(id)) {
+        painted.push(id);
+      }
+    }
+
+    requestAnimationFrame(watch);
+  };
+  requestAnimationFrame(watch);
+}, ['empty-state', 'first-steps']);
+
+await page.goto('/', { waitUntil: 'load' });
+// … wait for the data to be on screen …
+expect(await page.evaluate(() => (window as unknown as { __painted: string[] }).__painted)).toEqual([]);
+```
+
+- **Both sides of every condition.** An account that has done everything must not see "get started"; a new one must.
+  An empty list shows its empty state; a full one does not.
+- **Navigation lands on the new page's content.** After `waitForURL`, wait for an element of the NEW page before typing:
+  for a frame the previous page is still mounted, and a form field with the same name there takes the keystrokes.
+- **Console errors are failures.** Collect them and assert the list is empty.