@plitzi/sdk-server 0.38.3 → 0.38.5

package/dist/plugins/watch.d.ts

@@ -0,0 +1,12 @@
+import { PluginManager } from './manager';
+/**
+ * Calls `onChange(key)` when a file a built plugin was built from changes: what a development server rebuilds and
+ * hands to the open pages (`devReload`), without restarting the process that serves them.
+ *
+ * The FOLDERS are watched, not the files. An editor that saves through a temporary file renames it over the old one,
+ * and a watcher on the old file hears nothing after the first save. Which files matter comes from the build itself
+ * (`PluginManager.onSources`), so a file one plugin imports from another's folder belongs to both.
+ *
+ * Returns the function that stops watching.
+ */
+export declare const watchPluginSources: (manager: PluginManager, onChange: (key: string) => void) => (() => void);

package/dist/plugins/watch.js

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { watch } from "node:fs";
+//#region src/plugins/watch.ts
+/** How long a burst of writes — an editor saving, formatting, saving again — is waited out before one rebuild. */
+var SETTLE_MS = 80;
+/**
+* Calls `onChange(key)` when a file a built plugin was built from changes: what a development server rebuilds and
+* hands to the open pages (`devReload`), without restarting the process that serves them.
+*
+* The FOLDERS are watched, not the files. An editor that saves through a temporary file renames it over the old one,
+* and a watcher on the old file hears nothing after the first save. Which files matter comes from the build itself
+* (`PluginManager.onSources`), so a file one plugin imports from another's folder belongs to both.
+*
+* Returns the function that stops watching.
+*/
+var watchPluginSources = (manager, onChange) => {
+	/** File → the plugins built from it. */
+	const owners = /* @__PURE__ */ new Map();
+	/** Plugin → the files it was built from, to take its claim back when a build names others. */
+	const claims = /* @__PURE__ */ new Map();
+	const folders = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	const changed = (key) => {
+		clearTimeout(pending.get(key));
+		pending.set(key, setTimeout(() => {
+			pending.delete(key);
+			onChange(key);
+		}, SETTLE_MS));
+	};
+	const watchFolder = (folder) => {
+		if (folders.has(folder)) return;
+		try {
+			const watcher = watch(folder, { persistent: false }, (_event, name) => {
+				if (!name) return;
+				owners.get(path.join(folder, name))?.forEach(changed);
+			});
+			watcher.on("error", () => {
+				watcher.close();
+				folders.delete(folder);
+			});
+			folders.set(folder, watcher);
+		} catch {}
+	};
+	const unwatchUnused = () => {
+		const used = new Set([...owners.keys()].map((file) => path.dirname(file)));
+		folders.forEach((watcher, folder) => {
+			if (!used.has(folder)) {
+				watcher.close();
+				folders.delete(folder);
+			}
+		});
+	};
+	const stopListening = manager.onSources((key, inputs) => {
+		(claims.get(key) ?? []).forEach((file) => {
+			const keys = owners.get(file);
+			keys?.delete(key);
+			if (keys?.size === 0) owners.delete(file);
+		});
+		claims.set(key, inputs);
+		inputs.forEach((file) => {
+			owners.set(file, (owners.get(file) ?? /* @__PURE__ */ new Set()).add(key));
+			watchFolder(path.dirname(file));
+		});
+		unwatchUnused();
+	});
+	return () => {
+		stopListening();
+		pending.forEach((timer) => {
+			clearTimeout(timer);
+		});
+		pending.clear();
+		folders.forEach((watcher) => {
+			watcher.close();
+		});
+		folders.clear();
+	};
+};
+//#endregion
+export { watchPluginSources };

package/dist/runtime.d.ts

@@ -8,7 +8,7 @@ export { defineRuntime, endpointFor, endpointProblem } from './modules/runtime/c
 export type { SpaceRuntime, SpaceRuntimeContext, SpaceRuntimeEndpoint, SpaceRuntimeParts } from './modules/runtime/contract';
 export { RUNTIME_DESCRIBE_PATH, startSpaceRuntime } from './modules/runtime/host';
 export type { SpaceRuntimeDescription, SpaceRuntimeHost, SpaceRuntimeHostOptions } from './modules/runtime/host';
-export { inspectRuntime, loadRuntime, MAX_RUNTIME_BUNDLE_BYTES, packRuntime, runtimeBundleId } from './modules/runtime/bundle';
+export { inspectRuntime, loadRuntime, loadRuntimeModule, MAX_RUNTIME_BUNDLE_BYTES, packRuntime, runtimeBundleId } from './modules/runtime/bundle';
 export { reachSpaceInside } from './modules/runtime/inside';
 export { createRuntimeRunner } from './modules/runtime/runner';
 export { createRuntimeProxyStage, runtimeEndpointsStage, serveRuntime } from './modules/runtime/stages';

package/dist/runtime.js

@@ -2,6 +2,6 @@ import { defineRuntime, endpointFor, endpointProblem } from "./modules/runtime/c
 import { reachSpaceInside } from "./modules/runtime/inside.js";
 import { createRuntimeRunner } from "./modules/runtime/runner.js";
 import { RUNTIME_DESCRIBE_PATH, startSpaceRuntime } from "./modules/runtime/host.js";
-import { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, packRuntime, runtimeBundleId } from "./modules/runtime/bundle.js";
+import { MAX_RUNTIME_BUNDLE_BYTES, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, runtimeBundleId } from "./modules/runtime/bundle.js";
 import { createRuntimeProxyStage, runtimeEndpointsStage, serveRuntime } from "./modules/runtime/stages.js";
-export { MAX_RUNTIME_BUNDLE_BYTES, RUNTIME_DESCRIBE_PATH, createRuntimeProxyStage, createRuntimeRunner, defineRuntime, endpointFor, endpointProblem, inspectRuntime, loadRuntime, packRuntime, reachSpaceInside, runtimeBundleId, runtimeEndpointsStage, serveRuntime, startSpaceRuntime };
+export { MAX_RUNTIME_BUNDLE_BYTES, RUNTIME_DESCRIBE_PATH, createRuntimeProxyStage, createRuntimeRunner, defineRuntime, endpointFor, endpointProblem, inspectRuntime, loadRuntime, loadRuntimeModule, packRuntime, reachSpaceInside, runtimeBundleId, runtimeEndpointsStage, serveRuntime, startSpaceRuntime };

package/dist/sqlite.d.ts

@@ -0,0 +1,17 @@
+/** A key/value store in a SQLite file, for a deployment with no database. Import it as `@plitzi/sdk-server/sqlite`.
+ *
+ *  What server actions keep in `kv` — saved layouts, counters, the single-flight keys a run guard takes — lives in one
+ *  process's memory by default, and goes with it. `createFileKv` (`@plitzi/sdk-server/actions`) keeps it in a JSON
+ *  file for ONE process; this keeps it in SQLite, which every process on the file shares safely:
+ *
+ *  ```ts
+ *  import { createServer } from '@plitzi/sdk-server';
+ *  import { createSqliteKv } from '@plitzi/sdk-server/sqlite';
+ *
+ *  createServer({ adapters, action: { lookups, kv: createSqliteKv({ file: 'data/kv.sqlite' }) } });
+ *  ```
+ *
+ *  Its own entry because it loads `node:sqlite`, which needs Node 22.13 or later and prints an `ExperimentalWarning`
+ *  when it loads: a deployment that does not use it never loads it. */
+export { createSqliteKv } from './modules/sqlite/kv';
+export type { SqliteKvOptions } from './modules/sqlite/kv';

package/dist/sqlite.js

@@ -0,0 +1,2 @@
+import { createSqliteKv } from "./modules/sqlite/kv.js";
+export { createSqliteKv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.3",
+  "version": "0.38.5",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -40,6 +40,11 @@
       "import": "./dist/mongo.js",
       "default": "./dist/mongo.js"
     },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js",
+      "default": "./dist/sqlite.js"
+    },
     "./handlers": {
       "types": "./dist/handlers.d.ts",
       "import": "./dist/handlers.js",
@@ -79,8 +84,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.3",
-    "@plitzi/sdk-shared": "0.38.3",
+    "@plitzi/plitzi-sdk": "0.38.5",
+    "@plitzi/sdk-shared": "0.38.5",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -18,7 +18,8 @@ const space: SpaceSpec = {
   components: [{ id, props, slots, root }],    // a block placed many times with different content
   pages: [{ id, name, slug: '', layout: { id: 'shell', slot: 'main' }, body: [] }]   // slot: where the body goes
 };                                             // slug '' is home; 'products/:slug' takes a param
-const { schema, style, warnings } = authorSpace(space, { plugins: [declaration] });
+pageFamily({ folder, layout, seoTitle, body: entry => [...] }, ENTRIES)   // pages of one shape, from data; ids scoped per page
+const { schema, style, warnings, suggestions } = authorSpace(space, { plugins: [declaration] });
 ```
 
 ## Elements
@@ -33,7 +34,7 @@ paragraph('A paragraph.')
 container([children], { subType: 'section' })  // div, section, nav, header, footer, main, article, li, h1–h6, span…
 link({ href: 'about', content: 'About' })      // a page id, a '/path', or a URL — the mode follows from the href
 link({ href: 'home', hash: 'plans' })          // → /#plans, onto the element with anchor: 'plans'
-container({ motion: { enter: 'fade-up', on: 'view' }, children })  // arrives as it scrolls in; stagger, loop too
+container({ motion: { enter: 'fade-up', on: 'view' }, children })  // arrives once as it comes into view; stagger, loop too
 button({ content: 'Save', flows })             // holds children too: then content: ''
 image({ src, alt })                            // or decorative: true
 embed({ src, title })                          // a map, a player: another page in a frame
@@ -45,6 +46,8 @@ list({ id: 'rows', items: 'p.data.rows', row: r => listItem({ children: [text({
 carousel({ id: 'hero', items: 'p.data.slides', autoplay: 5000, row: 'slide-card', children: [/* carouselNext('hero') arrows */] })
                                                // rows follow their item's `id`, or `itemKey: 'slug'`
 apiContainer({ id: 'p', query: '/data/x.json', cache: true, children })   // publishes p.data; no box of its own
+apiContainer({ id: 'p', query: '/data/x.json', runtime: 'server', children }) // read by the page server: still p.data
+apiContainer({ id: 'p', action: 'report', runtime: 'server', children })     // the action's output at p's root: p.rows
                                                // loadingSlot: 'p-skeleton' — a child shown until it answers
 form({ id, managedByInteractions: true, flows, children })
 formControl({ name: 'email', label: 'Email', subType: 'email' })          // select: options: [{ label, value }]
@@ -64,7 +67,7 @@ container({ id: 'hero', class: [card, { opacity: '0.5' }] });  // …plus one th
 container({ css: { padding: '8px' } });                        // rules of its own — never with `class`
 ```
 
-Breakpoints: `desktop` (base), `tablet` (48–64rem), `mobile` (<48rem), `compact` (tablet AND mobile). Each inherits
+Breakpoints: `desktop` (base), `tablet` (48–64rem), `mobile` (≤48rem), `compact` (tablet AND mobile). Each inherits
 from `desktop` alone. States: `hover`, `focus`, `focus-visible`, `active`, `disabled`…. An ancestor's state:
 `ancestors: { [card.name]: { states: { hover: { … } } } }`.
 
@@ -87,7 +90,8 @@ visible: false                                                 // hidden until a
 
 Inside a list row: `rows.item` in a binding, `{{ list_rows.item.x }}` in a template or an attribute,
 `list_rows.index` is a number from 0. A provider's source in a template is `apiContainer_p`… —
-spelled in full, as the element publishes it. Globals: `state`, `navigation` (`routeParams`, `queryParams`),
+spelled in full, as the element publishes it; an id with a `-` keeps it (`list_study-plans`: a minus takes spaces,
+`a - b`). Globals: `state`, `navigation` (`routeParams`, `queryParams`),
 `auth`, `variables`, `computed`, `flags`, `theme`, `host`.
 
 ## Flows
@@ -107,7 +111,7 @@ A flow is `[trigger, …steps]`, in an element's `flows`.
 [onClick(), navigate({ urlType: 'page', url: 'about' })]
 [onClick(), runServerAction({ actionId: 'checkout', input: { id: '{{ list_rows.item.id }}' } })]
 [onClick(), when({ field: 'state.step', operator: '=', value: '2' }, setState({ … }))]
-[whileRunning('queue', onClick()), delay(1000), …]
+[whileRunning('queue', onClick()), delay(1000), …]      // 'latest': a new firing stops the running one
 [named('picked', declaredTrigger(declaration, 'onPick')), …]; declaredCallback(declaration, 'reset', { on: 'seats' })
 ```
 

package/skills/plitzi-authoring/SKILL.md

@@ -38,21 +38,21 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
 
 ## How to work
 
-1. **Read before you write.** Open `src/space.ts` (and whatever it imports) and find the layout, the classes and the
+1. **Read before you write.** Open `src/space/index.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`. It checks
-   everything — every field, value, template, name, param and page link — and a refusal says what to write instead:
-   do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape it. The first
-   refusals come one at a time; the linter's come as ONE list — fix every line of it before running again. How it
-   checks, a one-file author script for any project, and what it cannot see: [validation](reference/validation.md).
+2. **Change the declaration, then author it.** `npm run author` (or a restart) runs `authorSpace` — not `doctor`, which
+   is the project's. It checks every field, value, template, name, param and page link, and a refusal says what to
+   write instead: do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape
+   it. The linter's problems come as ONE list — fix every line before running again. How it checks, and what it
+   cannot see: [validation](reference/validation.md).
 3. **Read every warning, then every suggestion.** A warning names something written that will not do what it says —
-   zero warnings is the bar. A suggestion (`[suggest]`, `suggestions` in `authorSpace`'s result) names a shorter way to
-   the same page: a layout for chrome on every page, a component or a `list` for copies, a button's own `content`. Take
-   them, the ones that save the most first. See [efficiency](reference/efficiency.md).
+   zero warnings is the bar. A suggestion (`[suggest]`) names a shorter way to the same page — a layout, a component,
+   a `list`, a button's own `content` — or what nothing uses. Take them, the ones that save the most first
+   ([efficiency](reference/efficiency.md)). Then `npm run lint:space`: how the source is written — long files, rows of
+   data inline, colours that are not tokens — at file:line. Leave both clean.
 4. **Look at it.** `npm run check -- /about --width 1440,390` says in text whether the page is whole — every element on
-   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture, for
-   when it says something is wrong (`--frames 4` shows what moves); `npm run visual`
-   runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
+   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture
+   (`--frames 4` shows what moves); `npm run visual` runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
 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.
 
@@ -61,15 +61,16 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
 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 a helper that runs more than once builds inside
    `scope('promos', ref => …)`: every id in it is prefixed (`promos-panel`), and `ref('slides')` names one in full. An `id` is the element's name in the
-   space (`data-id` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
+   space (`data-plitzi-el` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
 2. **Share with classes, layouts and components, 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 block
    placed many times with different content — a product card, a testimonial — is a **component** placed with
    `component(id, { props })`. A menu, a card grid, a list of steps is DATA, never a block pasted per item: a short
-   menu mapped in code (`entries.map(entry => link({ href, content: entry.title }))`) is fine; rows — cards, dishes,
-   tiles — are one `list` over them (`items: [ … ]`) whose row is written once. A link or a button says its words as
-   its own `content`, not through a `text` inside it. See [layouts and duplication](reference/layouts.md),
-   [components](reference/components.md) and [efficiency](reference/efficiency.md).
+   menu mapped in code is fine; rows — cards, dishes, tiles — are one `list` (`items: [ … ]`) whose row is written
+   once. A link or a button says its words as
+   its own `content`, not through a `text` inside it. Pages of one shape are one `pageFamily` over data. See
+   [layouts](reference/layouts.md), [components](reference/components.md), [structure](reference/structure.md) and
+   [efficiency](reference/efficiency.md).
 3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
    refuses the pair. "This class plus one thing" is the class with rules on top, last in the list:
    `class: [cover, { opacity: '0.25' }]` (needs the element's `id`; it becomes the class `<id>--own`). A look that
@@ -91,11 +92,12 @@ second into the first. If the MCP asks for a sign-in nobody can give, a project
    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
+8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (up to 48rem) each inherit only from `desktop`; a rule
    meant for both is written under `compact`.
 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. With no backend, the data is JSON the project serves
-   (`public/data/*.json`) read by an `apiContainer` — see [data and visibility](reference/data-and-visibility.md).
+   an empty state, not a placeholder figure. With no backend, the data is JSON read by an `apiContainer`: a server
+   project's `src/data/*.json`, read on the server and never served; with no server, `public/data/*.json`, which is
+   public — see [data and visibility](reference/data-and-visibility.md).
 10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
     `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
 11. **A switch is named for how it leaves its default.** `toggleState` turns a key nobody has set yet ON, so a key
@@ -121,6 +123,8 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | --- | --- |
 | 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) |

package/skills/plitzi-authoring/recipes/accordion.ts

@@ -0,0 +1,58 @@
+/**
+ * An accordion — questions whose answers open one at a time — written once and mapped over the questions: the open one
+ * is a key in `state`, and each question reads it the same way. The button says whether its answer is open
+ * (`ariaExpanded`) and which panel it opens (`controls`, by the panel's id), so a screen reader follows it; the panel is
+ * revealed by the state, so it starts hidden.
+ */
+import { bindTemplate, button, container, onClick, paragraph, setState, styles } from '@plitzi/sdk-authoring';
+
+import type { ElementSpec, SpaceSpec } from '@plitzi/sdk-authoring';
+
+const QUESTIONS = [
+  { id: 'shipping', question: 'How long does shipping take?', answer: 'Three working days, anywhere in Europe.' },
+  { id: 'returns', question: 'Can I return an order?', answer: 'Within thirty days, unopened, at no cost.' },
+  { id: 'warranty', question: 'Is there a warranty?', answer: 'Two years on every product we sell.' }
+];
+
+const question = styles('faq-question', {
+  css: {
+    display: 'flex',
+    'justify-content': 'space-between',
+    width: '100%',
+    padding: '16px 0px',
+    border: 'none',
+    'background-color': 'transparent',
+    'font-size': '16px',
+    'font-weight': '600',
+    cursor: 'pointer'
+  },
+  states: { 'focus-visible': { outline: '2px solid currentColor', 'outline-offset': '2px' } }
+});
+
+const answer = styles('faq-answer', { 'padding-bottom': '16px', margin: '0px' });
+
+/** One question: the button that opens it — closing the one open, or this one again — and the answer it opens. */
+const faqItem = ({ id, question: words, answer: text }: (typeof QUESTIONS)[number]): ElementSpec[] => [
+  button({
+    id: `${id}-question`,
+    content: words,
+    class: question,
+    // Named by the panel's id: authoring gives the panel the anchor the page needs for `aria-controls`.
+    controls: `${id}-answer`,
+    ariaExpanded: false,
+    bind: [bindTemplate('ariaExpanded', 'state.faq', `{{ source == '${id}' }}`, { returns: 'value' })],
+    flows: [[onClick(), setState({ key: 'faq', type: 'text', value: `{{ state.faq == '${id}' ? '' : '${id}' }}` })]]
+  }),
+  // Revealed by the state, so it starts hidden: nothing flashes open before the page knows which one is.
+  container({
+    id: `${id}-answer`,
+    visible: { source: 'state.faq', template: `{{ source == '${id}' }}` },
+    children: [paragraph({ content: text, class: answer })]
+  })
+];
+
+export const recipe: SpaceSpec = {
+  name: 'Questions',
+  permanentUrl: 'questions',
+  pages: [{ id: 'home', name: 'Home', slug: '', body: QUESTIONS.flatMap(faqItem) }]
+};

package/skills/plitzi-authoring/recipes/link-to-a-section.ts

@@ -1,6 +1,6 @@
 /**
  * Link to a section: the section carries an `anchor` — its id in the page; an element's `id` is only its name in the
- * space, `data-id` in the DOM — and a link's `hash` lands on it, from any page, even when the section renders late.
+ * space, `data-plitzi-el` in the DOM — and a link's `hash` lands on it, from any page, even when the section renders late.
  */
 import { container, heading, link, text } from '@plitzi/sdk-authoring';
 

package/skills/plitzi-authoring/recipes/plugin.ts

@@ -24,7 +24,7 @@ const declaration = {
 
 const seatPicker = defineElement<{ rows?: number }>(declaration);
 
-// `authorSpace(recipe, { plugins })` — in a project, `src/plugins/declarations.ts` lists them all.
+// `authorSpace(recipe, { plugins })` — in a project, every `src/plugins/<Name>/declaration.ts`, found by folder.
 export const plugins: PluginDeclarationData[] = [declaration];
 
 export const recipe: SpaceSpec = {

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

@@ -0,0 +1,65 @@
+/**
+ * Data in a server project (`create --mode server`): a JSON file of the project's own (`src/data/plans.json`, answering
+ * `/data/plans.json`), read by the page server before it answers and never served — so the page arrives with the plans
+ * in its HTML, their anchors in place, and nothing to fetch once the browser has it.
+ *
+ * - `runtime: 'server'` on the provider is the whole switch: server data is on unless a space turns it off.
+ * - The answer is read exactly as in the browser — `plans.data.…` — so moving a provider between runtimes changes no
+ *   binding.
+ * - The page server resolves what a page and its layouts hold, never inside a component: the provider stays on the page
+ *   and each row reaches the card component as a prop.
+ * - `mockData` is what the builder shows while editing; the running page always reads the file.
+ */
+import { apiContainer, heading, list, listItem, styles, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const grid = styles('plan-grid', {
+  display: 'grid',
+  'grid-template-columns': 'repeat(auto-fill, minmax(220px, 1fr))',
+  gap: '16px',
+  margin: '0px',
+  padding: '0px'
+});
+
+const card = styles('plan-card', { padding: '16px', 'border-radius': '12px', 'background-color': 'var(--card)' });
+
+export const recipe: SpaceSpec = {
+  name: 'Pricing',
+  permanentUrl: 'pricing',
+  variables: { color: { card: { light: '#ffffff', dark: '#16161d', default: '#ffffff' } } },
+  components: [
+    {
+      id: 'plan-card',
+      props: { item: { type: 'json', description: 'The plan: name and price' } },
+      // The row of the list: an `<li>` reading the plan it was handed.
+      root: listItem({
+        id: 'plan-item',
+        class: card,
+        children: [heading({ subType: 'h3', from: 'props.item.name' }), text({ from: 'props.item.price' })]
+      })
+    }
+  ],
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: 'plans',
+          query: '/data/plans.json',
+          runtime: 'server',
+          mockData: { plans: [{ name: 'Starter', price: '$0' }] },
+          children: [
+            // `plans.data.plans` — the file's `plans` — in either runtime.
+            list({ id: 'plan-list', class: grid, items: 'plans.data.plans', row: 'plan-card' }),
+            text('No plans yet.', {
+              visible: { source: 'plans.data.plans', template: '{{ source is defined and source|length == 0 }}' }
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

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

@@ -1,7 +1,8 @@
 /* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
 /**
- * Show data with no backend: a JSON file the project serves (`public/data/products.json`), read by a provider — one
- * card per product, a skeleton while it loads, a count, a computed value, and an empty state that never flashes.
+ * Show data with no backend, in a project with no server: a JSON file the browser fetches (`public/data/products.json`,
+ * public), read by a provider — one card per product, a skeleton while it loads, a count, a computed value, and an
+ * empty state that never flashes. A server project reads its `src/data/` on the server instead (`server-data.ts`).
  */
 import { apiContainer, container, heading, list, styles, text, listItem } from '@plitzi/sdk-authoring';
 

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

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

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

@@ -2,7 +2,7 @@
 /**
  * Data typed by a sample of it: `source()` turns the JSON the page reads into names the editor completes and checks —
  * `site.data.hero.titel` is a type error, not an empty heading. In a project the sample is the file itself:
- * `import home from '../../public/data/home.json' with { type: 'json' }`.
+ * `import home from '../data/home.json' with { type: 'json' }` — `src/data/`, or `public/data/` with no server.
  */
 import { apiContainer, heading, list, source, styles, text, twig, listItem } from '@plitzi/sdk-authoring';
 

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

@@ -4,7 +4,8 @@ A screen reader and a browser agent (Claude in Chrome) read a page the same way.
 tree** the browser builds from the markup, where every control is a role and a name. If a control has no name, or a
 click sits on a box that is not a control, those readers can't find it, even though the page looks fine. The linter
 warns about each case below (`control-without-name`, `image-without-alt`, `click-on-static-element`,
-`heading-level-skipped`, `label-ignored`). Fix them the same way you fix any other warning.
+`dropdown-without-control`, `heading-level-skipped`, `label-ignored`, `control-in-decorative`, `embed-without-title`,
+`controls-no-anchor`). Fix them the same way you fix any other warning.
 
 ## Controls have words
 
@@ -75,7 +76,10 @@ button({ content: 'Grid', bind: { ariaPressed: 'computed.gridOn' }, class: chip
 button({ content: 'Menu', bind: { ariaExpanded: 'state.menuOpen' }, flows: [[onClick(), toggleState({ key: 'menuOpen' })]] })
 ```
 
-An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both.
+An "active" variant is for the eyes. `ariaPressed` and `ariaExpanded` are for everyone else. Use both. A button that
+opens a panel also names it — `controls: 'menu-panel'`, the panel's id (authoring gives the panel the anchor
+`aria-controls` needs; [recipes/accordion.ts](../recipes/accordion.ts)). Words that change while somebody is on the page
+— a count, a total, a status — sit in `container({ live: 'polite', … })`, so a screen reader says them when they change.
 
 ## The page has an outline
 

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

@@ -6,7 +6,7 @@ Search this page for the code in brackets — `[class-and-css]` — rather than
 `npx @plitzi/cli explain class-and-css`.
 
 `authorSpace` reports everything it cannot write in one run, as a `SpaceRefusedError` whose `refusals` each carry
-a `code`, the line of your code that wrote the element (`src/site/home.ts:417`) and the nearest named element
+a `code`, the line of your code that wrote the element (`src/space/pages/home.ts:417`) and the nearest named element
 (`"store-footer" › container[1]`). **Do what the message says.** Never cast past a check, silence it, or move the
 logic into a plugin to avoid it — the check exists because that declaration renders something other than what it says.
 
@@ -59,6 +59,7 @@ The space is not written until these are fixed.
 | `computed-not-template` | a computed value that is not a template | `'{{ state.x * 2 }}'` |
 | `computed-reads-element` | a computed value reading an element's source — no element is around the whole space | compute it from the globals and the variables, or bind it on the element |
 | `computed-unknown` | a computed value read before it is declared, or never declared | declare it in `computed`, above the one that reads it |
+| `controls-unknown` | a button's `controls` naming no element of the space | the id of the element it shows and hides: `controls: 'faq-answer'` |
 | `css-property-twice` | one property written twice in a rule set — `paddingTop` beside `'padding-top'` — so one would silently win | keep one |
 | `css-property-unknown` | a CSS property that does not exist | the property it suggests; a custom property starts with `--` |
 | `css-value` | an empty CSS value, or one with `;` or `{}` | one value per property; leave a property out instead of writing it empty |
@@ -84,7 +85,7 @@ The space is not written until these are fixed.
 | `global-callback-undeclared` | a global-callback step builder naming an action no source declares | one of the actions it lists |
 | `id-invalid` | an id a binding, a template or a test cannot name | a letter first, then letters, digits, `-` and `_`: `'hero-title'` |
 | `id-shadows-global` | an element named like a global data source (`state`, `navigation`, `auth`…) | another id |
-| `id-taken` | two elements with one id — ids are one namespace for the whole space | wrap what a helper builds in `scope('promos', ref => …)`: every id inside is prefixed, `ref('slides')` names one |
+| `id-taken` | two elements with one id — ids are one namespace for the whole space | a name taken by a page or a layout: a name of its own; a helper called twice: `scope('promos', ref => …)`, every id inside prefixed |
 | `layout-slot-unknown` | a layout `slot` that is not an element inside that layout | the id of the element in the shell where the body goes |
 | `layout-undeclared` | a page or a layout inside a layout the space does not declare | the layout's id, or declare it in `layouts` |
 | `list-items-ignored` | a list whose items nothing reads — `source: 'none'` renders its children once | `source: 'controlled'` |
@@ -109,6 +110,7 @@ The space is not written until these are fixed.
 | `prop-unknown` | a prop the component does not declare, handed in or read | the prop it suggests, or declare it: `props: { name: { type: 'text' } }` |
 | `prop-value` | a prop handed in with a value its declaration does not take | a value of the declared type, or one of its options |
 | `props-outside-component` | `props.x` read outside a component | read the source it would have come from |
+| `quiet-unknown` | an element's `quiet` naming something that is not a suggestion's code — a problem is never quieted | the code of the suggestion it was offered: `quiet: ['repeated-shape']` |
 | `redirect-target-unknown` | a page that sends visitors it is not for to a page the space does not have | a page's id or slug (`''` is the home page), or a full URL |
 | `row-and-children` | a list with a `row` and `children` — the row is what it renders | one of the two |
 | `row-component` | a list's `row` naming a component the space does not declare, or one with no prop to take the row | a declared component with an `item` prop — or a single prop — for the row |
@@ -117,6 +119,8 @@ The space is not written until these are fixed.
 | `rule-set-mixed` | a style that writes its rules beside `states`, `variants` or `ancestors` instead of under `css` | `{ css: { desktop: { … } }, states: { hover: { … } } }` — the rules under `css`, each of the others beside it |
 | `selector-invalid` | a `selector` that is not a CSS class name | letters, digits, `-` and `_` |
 | `selector-taken` | a `selector` that is a declared class, or another element's | `class` to share rules; a selector of an element's own is its alone |
+| `server-data-in-browser` | a provider asking for the project's own data (`/data/…`, read by its server from `src/data/` and never served) from the browser | `runtime: 'server'` on the provider: the page arrives with the data in it |
+| `server-provider-in-component` | a `runtime: 'server'` element inside a component: the page server resolves a page's and its layouts', never a component's | put the provider on the page, around the instance, and hand the component its rows as a prop |
 | `setting-misplaced` | `settings.computed` or `settings.channels` written inside `settings` | `computed` and `channels` at the top of the space |
 | `slot-children` | children handed to an instance outside its slots | `children: { slotName: [ … ] }`; a component with no slots takes no children |
 | `slot-unknown` | a component slot that is not an element of its tree | the id of an element inside the component — usually an empty container |
@@ -148,7 +152,7 @@ The space is not written until these are fixed.
 | `utility-module` | a utility sent to a module — a utility takes none | drop the `on` |
 | `visibility-as-attribute` | `visibility` bound as an attribute, which no element reads | `visible: { source, template }` |
 | `visitor-roles` | `settings.visitorRoles` written in a shape the runtime does not read | the shape the message gives |
-| `while-running` | `whileRunning` on a step that is not the trigger, or a mode other than `skip`, `parallel`, `queue` | `[whileRunning('queue', onClick()), …]` |
+| `while-running` | `whileRunning` on a step that is not the trigger, or a mode other than `skip`, `parallel`, `queue`, `latest` | `[whileRunning('queue', onClick()), …]` |
 
 ## Warned
 
@@ -156,11 +160,13 @@ 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` |
 | `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 }` |
 | `control-in-decorative` | a control inside a `decorative` container — Tab lands on something nothing announces | move it out of the illustration |
 | `control-without-name` | a button or a link with no words, or a field nothing names | `title` on the button, `label` on the link, `label` (with `hideLabel: true`) on the field |
+| `controls-no-anchor` | a button's `controls` naming no anchor — `aria-controls` points at nothing | an `anchor` on the element it shows and hides, and `controls` naming it |
 | `default-content-beside-children` | a button printing its default "Button" beside its children | `content: ''` |
 | `dropdown-without-control` | a dropdown opened from a box or an icon — no keyboard opens it | a `button` as what opens it (`title` if it is only an icon) |
 | `embed-without-title` | an `embed` with no `title` — a frame a screen reader cannot describe | say what it shows in `title` |
@@ -178,11 +184,12 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `overlay-never-opened` | a modal or a dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
 | `overlay-starts-open` | a modal or a dialog open when the page loads | `visible: false`, opened by `openModal` |
 | `painted-state-without-keep-state` | `paintedState` without `keepState` — nothing is kept for the server to draw with | `settings.keepState: true`, or remove `paintedState` |
+| `path-not-in-data` | a binding onto a provider whose answer the author could read (`data`), through a path that answer does not have | the path the message lists the keys for — `p.data.plans`, not `p.data.landing.plans` |
 | `plugin-attribute-reserved` | a plugin attribute named as one of the element’s own fields — a factory never hands it to the plugin | rename it in the plugin (`variant` → `kind`) |
 | `provider-without-source` | an `apiContainer` that asks nothing | a `query` (or `action`, `connector`, `resource`) |
 | `route-param-undeclared` | `navigation.routeParams.x` read on a page whose slug has no `:x` — always empty | add `:x` to the slug, or read `navigation.queryParams.x` |
-| `server-data-without-rsc` | a `runtime: 'server'` provider with a `connector` or `action` in a space that does not turn server data on | `rsc: { enabled: true }` on the space |
-| `span-holds-block` | a `container({ subType: 'span' })` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words: a `text` with `display: inline` in its class |
+| `server-data-without-rsc` | a `runtime: 'server'` provider — `connector`, `action` or `query` — in a space that turns server data off (`rsc: { enabled: false }`) | drop `rsc: { enabled: false }`: server data is on unless a space turns it off |
+| `span-holds-block` | a `container` with `subType: 'span'` or `'p'` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words and inline elements: a `text`, a `link` |
 | `state-key-has-runtime-prefix` | a state key written with `runtime.state.` in front — the state callbacks already write below it | `key: 'cart'`, not `'runtime.state.cart'` |
 | `state-toggled-in-branches` | two `setState` of one key, each under a `when` on that key — the second flips back what the first wrote | `toggleState({ key })`; for something shown by default, a key named for hiding it |
 | `STYLE_WITHOUT_TAG` | style on a provider that renders no element of its own | `subType: 'div'` on the provider, or style its parent |
@@ -206,8 +213,12 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 | `custom-css-notifications` | the toasts dressed with `.Toastify__toast` rules in `customCss` | `notifications: { font, fontSize, border, shadow, padding, background, text, radius }` |
 | `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 |
 | `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 |
 | `repeated-shape` | the same structure written again and again with different words — cards, rows, tiles | a component with props (`components`, `component(id, { props })`), or one `list` when they are rows of data side by side — a few cards a person rewords on the canvas can stay cards |
+| `unused-class` | a class declared in `classes` that no element, binding, flow or other class names | remove it from `classes` — or wear it where it was meant to go |
+| `unused-component` | a component no page, layout or other component places | remove it from `components`, or place it where it was meant to go |
+| `unused-token` | a token of `variables` no `var(--…)` reads — not a class, an element, `customCss` nor another token | remove it, or write it where its colour is written out |
 
 ## UPPER_CASE codes