@plitzi/sdk-server 0.37.0 → 0.37.2

package/dist/mongo.d.ts

@@ -0,0 +1,25 @@
+/** Job queue and key/value helpers for a deployment that runs Mongo. Import them as `@plitzi/sdk-server/mongo`.
+ *
+ *  The scheduler and the workers are the package's; WHERE the jobs wait is the deployment's — `action.jobs.queue`
+ *  and `action.kv` are adapters, and the defaults keep everything in one process's memory. That is right for one
+ *  replica and wrong for two: each gets its own copy of every schedule, and the jobs a replica was holding go with it
+ *  when it stops. These are those adapters, already written for Mongo, over a database the deployment connects to
+ *  and owns:
+ *
+ *  ```ts
+ *  import { MongoClient } from 'mongodb';
+ *  import { createServer } from '@plitzi/sdk-server';
+ *  import { createMongoJobQueue, createMongoKv } from '@plitzi/sdk-server/mongo';
+ *
+ *  const db = new MongoClient(process.env.MONGO_URL).db('app');
+ *
+ *  createServer({
+ *    adapters,
+ *    action: { lookups, kv: createMongoKv({ db }), jobs: { queue: createMongoJobQueue({ db }) } }
+ *  });
+ *  ```
+ *
+ *  The package holds no connection and keeps no data of its own: it creates the indexes its queries need, in the
+ *  collections it is told to use. `mongodb` is an optional peer dependency, used for its types alone. */
+export { createMongoJobQueue, createMongoKv } from './modules/mongo';
+export type { MongoDbSource, MongoJobQueue, MongoJobQueueOptions, MongoKvOptions } from './modules/mongo';

package/dist/mongo.js

@@ -0,0 +1,3 @@
+import { createMongoJobQueue } from "./modules/mongo/jobQueue.js";
+import { createMongoKv } from "./modules/mongo/kv.js";
+export { createMongoJobQueue, createMongoKv };

package/dist/mysql.d.ts

@@ -22,5 +22,16 @@
  *  The tables are documented in `docs/auth/mysql-schema.md` — what each one is for, and what a deployment mapping
  *  its existing schema onto the adapters has to be able to answer. */
 export { createMysqlStore, mysqlSchemaStatements } from './modules/mysql';
+/**
+ *  The job queue and the key/value store server actions run on, for a deployment that keeps them in MySQL rather than
+ *  in one process's memory — which is what running more than one replica needs. They borrow connections from a pool
+ *  the deployment opened (`store.pool` works) and create their three tables on first use:
+ *
+ *  ```ts
+ *  createServer({ action: { lookups, kv: createMysqlKv({ pool }), jobs: { queue: createMysqlJobQueue({ pool }) } } });
+ *  ```
+ */
+export { createMysqlJobQueue, createMysqlKv, mysqlJobSchemaStatements } from './modules/mysql/jobs';
+export type { MysqlJobQueue, MysqlJobQueueOptions, MysqlKvOptions } from './modules/mysql/jobs';
 export { SCHEMA_VERSION, TABLE_NAMES, tableNames } from './modules/mysql';
 export type { AccountSeed, MysqlAdmin, MysqlConfig, IdentityStore, LinkedIdentity, MysqlStore, SessionStore, SessionSummary, SpaceTokenSeed, TableKey, Tables } from './modules/mysql';

package/dist/mysql.js

@@ -1,4 +1,7 @@
 import { TABLE_NAMES, tableNames } from "./modules/mysql/config.js";
 import { SCHEMA_VERSION } from "./modules/mysql/schema.js";
 import { createMysqlStore, mysqlSchemaStatements } from "./modules/mysql/index.js";
-export { SCHEMA_VERSION, TABLE_NAMES, createMysqlStore, mysqlSchemaStatements, tableNames };
+import { mysqlJobSchemaStatements } from "./modules/mysql/jobs/schema.js";
+import { createMysqlJobQueue } from "./modules/mysql/jobs/jobQueue.js";
+import { createMysqlKv } from "./modules/mysql/jobs/kv.js";
+export { SCHEMA_VERSION, TABLE_NAMES, createMysqlJobQueue, createMysqlKv, createMysqlStore, mysqlJobSchemaStatements, mysqlSchemaStatements, tableNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -35,6 +35,11 @@
       "import": "./dist/mysql.js",
       "default": "./dist/mysql.js"
     },
+    "./mongo": {
+      "types": "./dist/mongo.d.ts",
+      "import": "./dist/mongo.js",
+      "default": "./dist/mongo.js"
+    },
     "./handlers": {
       "types": "./dist/handlers.d.ts",
       "import": "./dist/handlers.js",
@@ -58,19 +63,23 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.37.0",
-    "@plitzi/sdk-shared": "0.37.0",
+    "@plitzi/plitzi-sdk": "0.37.2",
+    "@plitzi/sdk-shared": "0.37.2",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",
     "nodemailer": "^10.0.10"
   },
   "peerDependencies": {
+    "mongodb": "^6 || ^7",
     "mysql2": "^3",
     "react": "^19",
     "react-dom": "^19"
   },
   "peerDependenciesMeta": {
+    "mongodb": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     }
@@ -78,20 +87,21 @@
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@types/nodemailer": "^8.0.2",
     "@types/react": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
     "@vitest/coverage-v8": "^5.0.1",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",
+    "mongodb": "^7.6.0",
     "mysql2": "^3.24.4",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "tsx": "^4.23.13",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
     "vite": "^8.3.0",
-    "vite-plugin-dts": "^5.1.0",
+    "vite-plugin-dts": "^5.1.1",
     "vitest": "^5.0.1"
   },
   "scripts": {

package/skills/plitzi-authoring/SKILL.md

@@ -1,283 +1,89 @@
 ---
 name: plitzi-authoring
 description: >-
-  Write a Plitzi space or a publishable template in TypeScript — pages, elements, CSS, data bindings and flows —
-  instead of hand-writing schema JSON. Use whenever the task is to create, extend or re-theme a space: adding a
-  page or a section, styling one, binding an element to server data, wiring what happens on click, authoring a
-  template to host, or turning an exported JSON into something maintainable.
+  Write or change a Plitzi space or template in TypeScript with @plitzi/sdk-authoring — pages, layouts, elements,
+  CSS classes, data bindings, providers and flows — instead of hand-writing schema JSON. Use whenever the task is to
+  create, extend, restyle or fix a space: adding a page or a section, sharing a header across pages, binding an
+  element to data, showing or hiding something, wiring what happens on click, or turning an exported JSON into code.
 ---
 
 # Authoring Plitzi spaces
 
-A Plitzi space is two documents — a schema and a style — of deeply cross-referenced ids. **Do not write them by
-hand.** Every id, class name, parent/root link, breakpoint map and interaction chain is derived from a much
-smaller declaration, and the surface that derives them also refuses a declaration that would not render.
+A space is two JSON documents — a schema and a style — full of cross-referenced ids. **Never write them by hand.**
+`@plitzi/sdk-authoring` derives every id, class name, parent link, breakpoint map and flow chain from a small
+declaration, and refuses a declaration that would not render.
 
 ```ts
-import { authorSpace, container, heading, text } from '@plitzi/sdk-authoring';
+import { authorSpace, container, heading, styles, text } from '@plitzi/sdk-authoring';
 
-const { schema, style, warnings } = authorSpace({
+const page = styles('page', { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' });
+
+export const space = {
   name: 'My space',
   permanentUrl: 'my-space',
-  classes: { page: { desktop: { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' } } },
-  pages: [
-    { name: 'Home', slug: '', class: 'page', body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }
-  ]
-});
-```
-
-Serve it with the adapters the page server already takes:
+  pages: [{ name: 'Home', slug: '', class: page, body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }]
+};
 
-```ts
-createServer({ port: 3001, adapters: createJsonAdapters({ offlineData: { schema, style } }) });
+const { schema, style, warnings } = authorSpace(space);
 ```
 
-One package, and it installs nothing: `@plitzi/sdk-authoring` has an empty dependency tree, no React and nothing
-that touches a browser, so a seed, a migration, a build script or a project that only publishes templates depends
-on it alone.
-
-## The types are the reference
-
-Every factory, spec field and step builder carries its documentation in the published `.d.ts`. Read it rather
-than guessing — `node_modules/@plitzi/sdk-authoring/dist/index.d.ts` is the whole surface in one file. Attribute
-types come from each element's own component, so an editor completes them and a wrong value is a compile error.
-
-## 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 |
+The published `.d.ts` is the reference for every factory, field and step builder
+(`node_modules/@plitzi/sdk-authoring/dist/index.d.ts`) — read it instead of guessing a name or a param.
+
+## How to work
+
+1. **Read before you write.** Open `src/space.ts` (and whatever it imports) and find the layout, the classes and the
+   helpers already there. Extend them; do not add a second way of doing something the space already does.
+2. **Change the declaration, then author it.** `npm run author` (or restart the server) runs `authorSpace`. A refusal
+   is an error that names the element and the fix — fix the declaration, never work around the check.
+3. **Read every warning.** Each one names something written that will not do what it says. Zero warnings is the bar.
+4. **Look at it.** `npm run visual` opens the page in a browser. Check desktop, tablet and mobile, light and dark,
+   and the page while its data is still loading — not only the finished frame.
+5. **Go through the [review checklist](reference/review-checklist.md) before saying it is done.** It is the feedback a
+   reviewer gives on every change, written down so you do not need to hear it.
+
+## The rules that matter most
+
+1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
+   namespace for the whole space — layouts and every page share it — so an element built by a helper that runs more
+   than once gets its id prefixed by what it is for: `` `${pageId}-foot` ``.
+2. **Share with classes and layouts, never with copies.** A look used twice is a `styles()` class. Chrome shown on
+   several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A menu, a card grid,
+   a list of steps is DATA mapped to elements (`entries.map(entry => link(…))`), not a block pasted per item. See
+   [layouts and duplication](reference/layouts.md).
+3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
+   refuses the pair. A look that never changes is its own class.
+4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
+   the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
+   `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
+   loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
+   is folded), it keeps the default and an absent flag must leave it shown. See
+   [data and visibility](reference/data-and-visibility.md).
+5. **Know where a template is evaluated.** A binding's `twigTemplate` and a step's params evaluate full Twig. An
+   ATTRIBUTE only resolves a name with filters (`{{ post.slug|url_encode }}`); a condition there is used as written.
+   Inside any template a source is spelled in full — `apiContainer_stats`, `list_rows` — never by the element's short
+   id. See [templates](reference/templates.md).
+6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
+   checked from the first commit.
+7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
+   a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
+8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (below 48rem) each inherit only from `desktop`; a rule
+   meant for both is written in both.
+9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
+   an empty state, not a placeholder figure.
+10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
+    `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
+
+## References
+
+| Read | When |
 | --- | --- |
-| `id` | the ONE name this element answers to — its key in the document, a binding's source, a step's target. **Name anything something else refers to**: a derived `<type>-<n>` is positional |
-| `class` | a shared class: a name from the space's `classes`, or a `styles()` declaration. Exclusive with `css` |
-| `css` | rules of this element's own: one set, or one per breakpoint (`{ desktop, tablet, mobile }`) |
-| `variant` | a style variant of the element's own vocabulary |
-| `slots` | a class for one of the element's OTHER selectors — a form control's `input`, `label`, `error` |
-| `bind` | where a value comes from |
-| `visible` | show it only while this source is true; `!source` for the inverse |
-| `flows` | what happens on click, on submit, on load |
-| `runtime` | `'server'` resolves this element'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**. `label` belongs to the attribute (a link and a form control both
-have one); the builder's name for the element is `meta.label`.
-
-A type this SDK does not ship — a plugin, one the deployment brings — is authored the same way:
-
-```ts
-const speciesStatus = defineElement<{ status?: string }>({ type: 'speciesStatus', content: { … } });
-element<{ status?: string }>('speciesStatus', { status: 'vulnerable' });   // or one at a time
-elementsFromManifest(manifest);                                            // or a whole plugin manifest
-```
-
-## Style
-
-Write CSS the way you write CSS, shorthands included — they are expanded before they reach the document, because
-Plitzi's style editor reads a closed list of longhand properties:
-
-```ts
-css({ padding: '96px 24px', border: '1px solid var(--line)', 'border-radius': '12px' })
-```
-
-You rarely call `css` yourself: `authorSpace` runs every rule set through it. What you get is the refusal — a
-property outside the vocabulary is an error naming the correct key (`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 and `mobile` is below 48rem, and each inherits
-  only from `desktop` — a rule written for `tablet` never reaches a phone. A grid that collapses to one column at
-  tablet and should stay collapsed says so in `mobile` too. `authorSpace` warns (`tablet-rule-skips-mobile`) when it
-  does not.
-- **Fonts are declared, not assumed.** A `font-family` loads only if the space lists the face in `fonts`
-  (`{ source: 'google', family: 'Fraunces', fallback: 'Georgia, serif', weights: [400, 600], styles: ['normal'] }`);
-  the page server writes exactly that list into the document, and anything else renders in the fallback.
-- Per element TYPE defaults go in `elements: { heading: { base: …, states: { … }, variants: { … }, slots: { … } } }`
-  — `slots` dresses the type's other selectors (a modal's `rootContainer`) for every element of the type.
-- **`:hover` is part of the selector, not a rule in `customCss`.** `styles('card', { css: { … }, states: { hover: { … } },
-  variants: { active: { … } } })`, and `states` beside an element's own `css`. Written in `customCss` it renders and
-  then cannot be read back or edited per breakpoint.
-
-**Share a rule as a class, never as a spread.** Writing a rule set once in a `const` and spreading it into each
-element's `css` shares the source and duplicates the document — one selector per element, so re-theming the card
-in the builder re-themes one card. `styles()` declares the class where it is used and writes it once:
-
-```ts
-const card = styles('card', { padding: '24px', 'border-radius': '12px', 'background-color': 'var(--surface)' });
-
-container({ class: card, children: [ … ] });
-```
-
-Accepted anywhere a class name is — `class`, a `slot`, a page's `class` — and collected from wherever the tree
-names it. One name declared twice with rules that disagree is refused. `classes` at the top of the space is the
-same mechanism for what describes the space rather than one section of it.
-
-An element has exactly ONE base selector, so a look that never changes is its own class over a shared plain object
-(`styles('button-primary', { ...base, … })`), never two classes layered on top of each other. A class's `variants`
-are for what the page switches while it runs — a binding with the `styleVariant` transformer picks one.
-
-**Shells go in `layouts`.** A header or a sidebar every page shows is a layout the pages name —
-`layout: { id: 'app-shell', slot: 'main' }`, the slot being the element in the shell where the body goes — never a
-copy on each page. `visible: false` starts an element hidden for a flow to reveal.
-
-## Data
-
-```ts
-heading({ bind: { content: 'posts.title' } })            // short form: attributes
-paragraph({ visible: 'posts.hasPosts' })                // on screen only while this is true
-paragraph({ visible: '!posts.hasPosts' })               // …and its inverse
-container({ bind: [{ to: 'content', source: 'x.y', transformers: [ … ] }] })   // full form
-```
-
-**A source names the id you gave the element** — `'posts.title'`, `'postList.item.cover'` — and the prefix is
-filled in. Only half of a source name is yours: the other half is the kind of source the ELEMENT publishes, and it
-is not always the word you can see (a `form` publishes under `apiContainer`). The four globals — `variables`,
-`navigation`, `auth`, `state` — are named as themselves. A full name still works and is checked the same way: a
-prefix that does not match the element, or a name nothing answers to, is refused when the space is authored. It
-is the quietest failure a space can carry.
-
-Server-resolved sections are an `apiContainer` with `runtime: 'server'` naming a connector or an action, and a
-space that has any needs `rsc: { enabled: true }`.
-
-**A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own while its
-`subType` is empty — the default, the builder's "Container Tag: None" — so its children sit directly in the parent's
-layout. That is usually what you want (the provider stays invisible to the layout), and it means a `class` or `css`
-on it styles nothing: the `gap` you wrote between its sections is simply not there. Put the layout on the parent, or
-give the provider a tag (`attributes: { subType: 'div' }`) when it should be the box. `validateSpace` — and so
-`authorSpace` and the MCP — warns with `STYLE_WITHOUT_TAG`.
-
-**Never ask the data for a field's opposite.** Both sides of one question are `visible: 'x'` and `visible: '!x'` —
-not an `x` and a `notX` beside it in the server's answer. The `!` is the `not` transformer, which reads a boolean
-that travelled as text (`"false"`, `"0"`) and treats an empty array as false; an empty object is true. Only for a
-real inverse — a three-state condition (`Boolean(post) && !canEdit`) still belongs where the data is made.
-
-## Flows
-
-```ts
-button({
-  id: 'cta',
-  content: 'Get a quote',
-  flows: [[
-    onClick(),
-    named('quote', runServerAction({ actionId: 'shipping-quote', input: '{"city":"Berlin"}', mode: 'await' })),
-    setState({ key: 'quote', type: 'text', value: '{{quote.output.summary}}' })
-  ]]
-})
-```
-
-Use the step builders — they answer the three things that go wrong silently:
-
-- **Where a step runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an
-  element callback under an element's id, a utility under nothing. The builders fill it in; a trigger and an
-  untargeted `updateElement` are filled with the element the flow was declared on.
-- **Which `setState`.** `setState(…)` writes `runtime.state.<key>`; `updateElement(…)` changes one element's own
-  attribute or state. Different params, different node kind. Each has a flip-it counterpart storing the opposite
-  of what is there, which is how expand/collapse is ONE step on ONE trigger: `toggleState({ key })` for app state,
-  and `toggleElement({ category: 'state', key: 'visibility' }, 'panel')` to show/hide an element (the second
-  argument is the element it acts on; omitted, it acts on the one the flow is declared on). Never two branches
-  under opposite `when` guards — those read the state as it was when the flow STARTED, so they run a click behind.
-- **What it takes.** Params are typed from the same declaration the builder's own panel is drawn from.
-
-`named(id, step)` is how a later step reads an earlier one — the flow scope is keyed by node id, so
-`{{quote.output.summary}}` resolves only when that step is called `quote`. `mode: 'await'` is what puts a run's
-answer in the scope at all, and it is the default.
-
-**Pass `input` as an object, not as a line of JSON text.** Both are accepted, and the text form fails silently: an
-interpolated value carrying a quotation mark or a newline — a post body, a comment — makes it unparseable, and
-unparseable input posts `{}` rather than refusing.
-
-A flow is a list and never a tree, so "only if" is expressed on the step:
-
-```ts
-whenSucceeded('quote', navigate({ urlType: 'internal', url: '{{quote.output.url}}' })),
-whenFailed('quote', setState({ key: 'notice', type: 'text', value: '{{quote.reason}}' })),
-when({ field: 'state.count', operator: '>', value: 3 }, addNotification({ content: 'Enough' }))
-```
-
-`whenFailed` matches every outcome that is not `completed` — a run also comes back `skipped` or `aborted`, and
-matching only `failed` is how those two end up doing nothing.
-
-## What gets refused
-
-`authorSpace` throws rather than hand back a space that would not render:
-
-- a CSS property the style editor could not read back
-- a `class` or a `slot` naming a class the space does not declare (the error names the one you probably meant)
-- an element asking for a shared class AND rules of its own — an element has one base selector
-- one class name declared twice with rules that disagree
-- a binding source naming an element nothing answers to, or one whose prefix is not what that element publishes
-- a name that shadows a global data source (`variables`, `navigation`, `auth`, `state`)
-- a step target naming an element that is not there
-- two elements answering to one name, a broken flow chain, an orphan, a cycle
-- a global callback on the wrong module — or on none — and a utility given one. A global callback registers under
-  its SOURCE MODULE (`auth`, `state`, `actions`), and the pair is what the runtime resolves a step by, so naming
-  either half wrong is a control that does nothing at all with no error anywhere. An action no built-in source
-  declares comes back in `warnings` instead of throwing, because a plugin may register a module of its own.
-
-Those last checks need the vocabulary, which only the composed package has. Import `authorSpace` from
-`@plitzi/sdk-authoring` — not straight from `@plitzi/sdk-schema` — and you get them.
-
-For documents you did not author here — an export from the builder, a JSON edited by hand — run the same gate
-before serving it:
-
-```ts
-const { valid, errors, warnings } = validateSpace({ schema, style });
-```
-
-## Templates
-
-A template is not a space: it is ONE subtree, the style that dresses it and a name, published as a JSON someone
-fetches by URL and 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' })] })
-});
-
-await writeFile('pricing-card.json', JSON.stringify(template, null, 2));
-```
-
-Host that file and add it to a space's resources as an `application/json` — nothing else is required of you.
-
-Everything a space is held to still applies, and two more things apply because a template LEAVES its space:
-
-- **Everything it names, it carries.** A class declared in the space it was cut from does not travel; the element
-  keeps the class name, finds no rules wherever it is dropped, and renders unstyled. Declare in `classes` (or with
-  `styles()`) every rule the subtree names — `validateTemplate` warns about a name the manifest does not carry.
-- **A binding may not point outside the subtree.** A source names an element by id, so binding to a provider
-  that stayed behind is dead on arrival — refused. Bring the provider (the `apiContainer`, the `form`) into the
-  template, or bind to one of the globals: `variables`, `navigation`, `auth`, `state`.
-
-`validateTemplate(template)` runs the same gate over a manifest you did not author here — one exported by the
-builder, or edited by hand — before you publish it.
-
-## From an exported JSON
-
-Never rewrite an exported space by hand. `specFromSpace({ schema, style })` reads it into the spec that authors it,
-repairing what an older builder left behind and listing each repair in `corrections`; `specToSource(spec,
-{ exportName })` writes that spec as factory calls; `compareSpaces(original, authorSpace(spec))` must list nothing but
-what `corrections` explains. The builder's **Export** (and `POST /utils/transform-to-authoring`) does all three. Edit
-the code it writes from then on, not the JSON.
-
-## Rules
-
-1. **Never hand-write `flat`, element ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`.** They are derived.
-   Writing them is how a space half-renders with nothing reporting why.
-2. **Name what is referred to.** `id` on any element a binding, a step or a pager addresses.
-3. **Read the error.** Every refusal above names the element, the class or the property at fault; it is a bug in
-   the declaration, not a reason to work around the check.
-4. **Ids are stable.** They are hashes of the path that produced them, so re-authoring an unchanged space writes
-   byte-identical documents — a seed can re-run and a diff stays readable.
-5. **`warnings` is returned, not printed.** Read it if the space is generated in a build.
+| [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
+| [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
+| [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, loading/empty/error states, live data, caching, showing and hiding |
+| [templates.md](reference/templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
+| [flows.md](reference/flows.md) | Clicks, submits, page loads, server actions, modals, state |
+| [structure.md](reference/structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
+| [testing.md](reference/testing.md) | Handles, visual checks, catching a flash from the first frame |
+| [templates-and-export.md](reference/templates-and-export.md) | Publishing a template; turning an exported JSON into code |
+| [review-checklist.md](reference/review-checklist.md) | Before you say it is done |

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

@@ -0,0 +1,114 @@
+# Data and visibility
+
+## Bindings
+
+```ts
+heading({ bind: { content: 'posts.title' } })                     // short form: attributes
+text({ bind: [{ to: 'content', source: 'stats.data.total',        // full form: anything else
+  transformers: [{ action: 'twigTemplate', params: { template: "{{ source|number_format(0, '.', ',') }} views" } }] }] })
+```
+
+**A source names the id you gave the element** — `'posts.title'`, `'postList.item.cover'` — and the prefix is
+completed from what the element publishes (`apiContainer_posts`, `list_postList`; a `form` publishes under
+`apiContainer`). A name nothing answers to, or a prefix that does not match, is refused.
+
+**Inside a template the name is spelled in full**: `{{ apiContainer_stats.data.total }}`, `{{ list_rows.item.id }}`.
+The binding's `source` is completed for you; its template is read as written, so the short name there is refused.
+
+An element re-renders when anything it reads changes: the first part of each binding's `source` and every source its
+templates name. The globals are `variables`, `navigation` (`routeParams`, `queryParams`, `origin`, `currentPageId`),
+`auth` (who is signed in, `status` while that is being found out), `state` (what flows wrote) and `theme`
+(`mode`, `resolved`).
+
+## Providers
+
+```ts
+apiContainer({ id: 'orders', query: '{{apiUrl}}/orders', credentials: 'include', children: [ … ] })
+apiContainer({ id: 'board', runtime: 'server', action: 'queue-board' })          // resolved before the HTML
+```
+
+- 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 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 }`.
+
+### Live, cached, refreshed
+
+- **Live:** `refreshSeconds: 15` asks again on its own (either runtime); it pauses in a hidden tab and never
+  overlaps. Use it for queues, feeds, status boards — then mark the panel as live so the reader knows it moves.
+- **Cached:** `cache: true` (and `staleTime` seconds, 30 by default) shares an answer between providers asking the
+  same thing and across page changes.
+- **Refreshed by writes:** a `webHook` that is not a GET refreshes every request to its own site by default
+  (`invalidateQueries: 'origin'`); a `runServerAction` refreshes everything (`'all'`). Narrow it with
+  `'elements'` + `invalidateElements: ['orders']`, or stop it with `'none'`.
+- **Say `'none'` when a refresh would move the page on.** A page that decides where to go from a provider's answer
+  ("profile complete → leave") will act on the refreshed answer in the middle of a multi-step form that saves as it
+  goes, and skip the last step.
+
+## Visibility
+
+```ts
+container({ visible: 'posts.hasPosts', … })     // shown while true
+container({ visible: '!posts.hasPosts', … })    // its inverse
+modalContainer({ visible: false, … })           // starts hidden; a flow opens it
+```
+
+**An element is visible by default.** Which way its condition flips decides how it is written:
+
+| 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 |
+
+`visible` starts the element **hidden**, and it appears when its data says so. A revealing condition you have to
+compute is `visible: false` — so it waits hidden — plus a visibility binding with a template:
+
+```ts
+container({
+  id: 'first-steps',
+  visible: false,
+  bind: [{
+    to: 'visibility',
+    source: 'stats.data.totals',
+    category: 'initialState',
+    transformers: [{ action: 'twigTemplate', params: {
+      template: "{{ source ? (source.spaces > 0 and source.published > 0 ? 'false' : 'true') : 'false' }}"
+    } }]
+  }]
+})
+```
+
+Rules for a condition's template:
+
+- **A revealing condition starts hidden with `visible: false`.** A visibility binding alone 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.
+- **`'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.
+- **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.
+
+### Loading, empty, error
+
+Four states, and each has its own element:
+
+| State | How to tell |
+| --- | --- |
+| Loading | `apiContainer_x.isLoading` — or simply nothing: every condition is hidden until data arrives |
+| Empty | the answer ARRIVED and is empty: `{{ source is defined and source is empty ? 'true' : 'false' }}` over the list |
+| Error | `apiContainer_x.hasError` |
+| Data | the list itself |
+
+`visible: '!provider.data.items'` is NOT an empty state: before the answer, `!undefined` is true and "Nothing here yet"
+shows on every load. Test for "arrived and empty" (`is defined and … is empty`), or bind to `isEmpty` together with
+`not isLoading`.
+
+## Never ask the data for an opposite
+
+Both sides of one question are `visible: 'x'` and `visible: '!x'`, not an `x` and a `notX` in the server's answer.
+`!` reads a boolean that travelled as text (`"false"`, `"0"`) correctly. A three-state condition
+(`Boolean(post) && !canEdit`) still belongs where the data is made.