@plitzi/sdk-server 0.38.2 → 0.38.3

package/CHANGELOG.md

@@ -1,5 +1,133 @@
 # @plitzi/sdk-server
 
+## 0.38.3
+
+### Patch Changes
+
+- e047e1d: ## `plitzi upgrade`: a project brought up to its CLI
+
+  A project written by an older CLI had no way up but `plitzi create` in a scratch folder and a file-by-file comparison:
+  `skills update` brought the skills and nothing else, so the `check` and `shot` scripts they teach did not exist.
+  `plitzi upgrade` (also `update`) shows what this CLI writes today for what is the CLI's in the project, and `--write`
+  makes it. One part or several: `plitzi upgrade skills`, `plitzi upgrade files packages`.
+
+  - **`files`:** the CLI's machinery — `author.ts`, `main.ts`, the Playwright, TypeScript and lint configs, AGENTS.md. One
+    nobody changed since the CLI wrote it is replaced, a missing one added; one the project made its own is shown as a
+    diff and left, until `--take <file>` (or `all`). `plitzi create` now records what it wrote, by digest, in
+    `.plitzi/scaffold.json`; a project made before that sees every file that differs as its own.
+  - **`packages`:** `package.json` merged, never replaced — the scripts and dependencies it lacks added, `@plitzi/*`
+    raised to this version, then the install (`--no-install` to leave it). A script of the project's own stays.
+  - **`skills`:** `.claude/skills/plitzi-*` from the packages installed, each replaced whole, and the ones a newer CLI
+    writes added. `plitzi skills update` is `plitzi upgrade skills --write`.
+  - **`renames`:** a name a version renamed with no alias, at its file and line — `canTemplate` → `canSnippet`,
+    `authorTemplate` → `authorSnippet` and its kin (renamed only where imported from `@plitzi/sdk-authoring`) — renamed
+    with `--write`.
+
+  `npm run author` says when the skills or the CLI's files are older than the SDK installed, and `plitzi --version`
+  prints the CLI's.
+
+  ## Page checks that can be the definition of done
+
+  `inspectPage`, `plitzi check` and the scaffold's visual test failed pages that were whole, so an agent learnt to ignore
+  them:
+
+  - **A breakpoint hiding an element on purpose** — the desktop navigation on a phone, a bottom bar only a phone shows —
+    is no longer "not visible": an element whose `display` or `visibility` a breakpoint rule sets is checked at the width
+    it shows at.
+  - **A lazy image out of sight** waits whichever side it is out of: below the fold, as before, or beside the screen in a
+    carousel's track — cut off by any ancestor that clips, as the browser decides when to fetch it.
+  - **A plugin that draws nothing** says so: `drawsNothing: true` in its declaration (a clock that fires a flow), and its
+    handle is `boxless`, so no check waits for it on screen.
+
+  `plitzi check --json` and `PageReport` carry `issues` beside `problems`: each with its `code` (`element-hidden`,
+  `image-not-loaded`, `sideways-scroll`…), the `elementId` it is about and, in `check`, the `width`.
+
+  ## Authoring
+  - **A link's `content` names it.** `control-without-name` read only a link's `label`, so applying the
+    `content-attribute` suggestion as written turned every link into a warning.
+  - **`plitzi fix` writes `content-attribute`** where it has one reading: a button's or link's children that are only
+    `text(…)` and `fontAwesome({ icon })` become its own `content` and `icon` — the words kept as written, an import left
+    unused taken out. A child with an id, options or a class of the space's own stays, and is said. `npm run author`'s
+    `[fix]` line counts these too.
+  - **The recipes, the skill's examples and the catalog template** hold to the suggestions as well as the warnings, and
+    their tests say so: six recipes and the template wrote a link's or a button's words as a child.
+
+  ## Declared motion — in code, in the builder and over MCP
+
+  An element says how it arrives and whether it keeps moving with `motion`, and the SDK's stylesheet plays it — no
+  keyframes to write: `{ enter: 'fade-up', on: 'view' }` arrives as it scrolls into view, `{ enter: 'scale', stagger:
+60 }` brings its children one by one (a grid, a list's rows), `{ loop: 'float' }` keeps it moving. Enters: `fade`,
+  `fade-up`, `fade-down`, `slide-left`, `slide-right`, `scale`; loops: `float`, `pulse`, `spin`, `sway`; `duration`,
+  `delay`, `stagger` in ms. Opacity and the transforms only — an arrival on `translate`/`scale`, so it composes with an
+  element's own `transform` — a loop held until the page is live (`data-hydrated`), and none of it for a visitor who asked
+  for less motion. `view` follows the scroll where the browser has scroll timelines and plays on load where not.
+
+  - **Authoring:** `motion` on any factory; refused where it cannot play (`motion-invalid`, `motion-no-tag`), and carried
+    by `specFromSpace` and `compareSpaces`.
+  - **Builder:** a **Motion** tab in an element's tools: the presets as chips, a stage that plays the one pointed at (a
+    loop shown stronger than the page plays it, and saying so), when and how long, children one by one, and the choices
+    read back as a sentence — laid out side by side once the sidebar is wide enough. The canvas holds motion still while
+    editing; **▶** in the header (or **Play on the canvas** in the tab) plays it from the start, restarting what already
+    played, and an arrival tied to the scroll plays by the clock there, where it is usually in view already.
+  - **MCP:** `motion` on `upsertElement` and `patchElement`, checked the same way; the guide names the presets.
+  - **Schema:** `definition.motion` (`ElementMotion`, `@plitzi/sdk-shared/schema/motion` — the presets, `motionProblems`,
+    `motionAttributes`, `isMotionAnimation`, and each preset's frames, which the stylesheet is tested against), in both
+    init queries. **The platform's GraphQL schema has to declare `SpaceElementMotion`
+    before this version's builder or SDK queries it.**
+
+  ## Dev tools QA: x-ray and motion
+
+  The **QA** tab gains an **X-ray**: every element the document wires something to — bound to data, shown on a condition,
+  running a flow, moving, behind a flag — outlined in its colour and named on the page, read from the space's document by
+  the element's name; its legend counts each kind on the page and picks one to show alone. Beside **Pause**, **Slow**
+  plays every animation at a quarter of its speed and **Replay** plays the declared motion again from the start, without
+  reloading the page.
+
+  ## Plugins that draw
+
+  `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` (`@plitzi/plitzi-sdk`): a canvas sized to the device (at
+  most 2×), followed as it resizes, animating only while somebody can see it move — a live page, no reduced motion, the
+  tab in front, the canvas on screen — and one still frame otherwise (the builder included). `createShaderProgram`
+  compiles and links, and a shader that fails throws a `ShaderError` with the driver's log, printed as
+  `[plugin <type> "<id>"] fragment shader failed: …` instead of an empty canvas; `error` and `ready` say where it is.
+  `useReducedMotion` for the rest.
+
+  ## A space re-authored without a restart
+
+  A project's `npm run start:dev` restarts for its server code and its plugins only: a save to the space is re-authored
+  in a process of its own and every open page loads again (`server.reloadPages()` over an SSE endpoint, on with
+  `createServer({ devReload: true })` — never by `devMode` alone, since every open page holds a connection for it); an
+  edit authoring refuses is printed and the page keeps the last space that authored. A shutdown also ends WebSockets at
+  once (`1001`, going away) rather than waiting out the grace — the ten seconds a restart used to wait on an open page.
+
+  ## Checks and authoring, from the stripe.com experiment
+  - **A component's instance** is found by its own name: its root carries `data-plitzi-instance`, and the instance's
+    handle selects it — `inspectPage` no longer reports every named instance as missing.
+  - **Hidden at this width on purpose** — the burger on a desktop, the desktop menu on a phone — is listed apart
+    (`hiddenAtWidth`, and a dim line under `plitzi check`'s ✓) rather than as a problem.
+  - **An element whose every child is conditional** — four flyouts in one list, each opening on the state that names
+    it — is conditional too: at rest it shows nothing, and that is it working.
+  - **A carousel that scrolls by itself** (`overflow-x: auto`) is not the page scrolling sideways; the page's own pane
+    still is.
+  - **Templates:** `{{ state.faq ?? -1 }}` — a sign on the right of `??` — reads.
+  - **A plugin attribute named as an element field** (`variant`, `class`, `id`…) is warned about
+    (`plugin-attribute-reserved`): a factory never hands it to the plugin. A `variant` no class or type style declares is
+    `unknown-variant`.
+  - **Lists:** a list with `items` renders as the `<ul>` (or `<ol>`) its `subType` says — it was a `<div>` — with no
+    markers and the same spacing, so a page looks as it did; the builder offers the list type for it too. Its rows are
+    `<li>`s: `list-row-not-li` warns of one that is not — a plain container is made one by `fixSpace`, a link or a button
+    is wrapped — and the recipes, the catalog template and the docs write rows as `listItem`.
+  - **CSS:** `mask-size`, `mask-position`, `mask-repeat`, `mask-composite`, `-webkit-mask-image`,
+    `-webkit-background-clip`, `box-decoration-break` and `-webkit-box-decoration-break`.
+  - **`plitzi shot`:** `--clip <element>`, `--scroll-to <element>` and `--viewport`; `--frames` takes the same framing.
+  - **SVG from files:** `svgFile` and `svgFiles` (`@plitzi/sdk-authoring/node`) read a logo or a folder of them,
+    compacted (`compactSvg`, also on the main entry), instead of strings in the space's source.
+  - The plugin scaffolds say that an inline `style` on `RootElement` outranks the element's classes.
+
+- Updated dependencies [e047e1d]
+  - @plitzi/sdk-shared@0.38.3
+  - @plitzi/plitzi-sdk@0.38.3
+
 ## 0.38.2
 
 ### Patch Changes

package/README.md

@@ -167,6 +167,7 @@ runtime, and its files into `public/` — a draft, or any published snapshot (`-
 | `httpVersion` | `1 \| 2 \| 3` | `2` with `tls`, else `1` | HTTP protocol version. Falls back to the nearest available lower version. |
 | `tls` | `{ key, cert, minVersion? }` | — | TLS key and certificate. Required for versions 2 and 3; optional for version 1. |
 | `devMode` | `boolean` | `false` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). Off, the process must run with `NODE_ENV=production` or React renders with its development build; the server says so once, at `error`. |
+| `devReload` | `boolean` | `false` | Every page this server renders listens for `server.reloadPages()` and loads again — for a project that re-authors its space on save (what `plitzi create` writes into `main.ts`). Not turned on by `devMode`: each open page holds a connection for it. |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
 | `cacheTtlMs` | `number` | `300000` | TTL in milliseconds for the SSR render cache. Set to `0` to disable. |
 | `flags` | `Record<string, boolean> \| ({ spaceId, environment }) => Record<string, boolean>` | — | This deployment's say over the spaces' feature flags: above what a space declares, below the SDK's `flags` prop and a tester's dev tools, and only for flags the space declares. A function answers per space. Server actions and RSC resolve with it too. See `docs/en/feature-flags.md` in the workspace. |

package/dist/core/createServer.devReload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/http/stages/devReload.d.ts

@@ -0,0 +1,18 @@
+import { Stage } from '../types';
+/** Where an open page listens for "the space changed: load again", in development. */
+export declare const DEV_RELOAD_PATH = "/__plitzi/reload";
+/**
+ * The page reloading itself when the space it shows changed — the edit loop of a project that authors its space in
+ * code, without restarting the server: `main.ts` re-authors in a process of its own and calls `reloadPages()`, and
+ * every page open on this server loads again.
+ *
+ * Only with `devReload` on: every open page keeps a connection for it, which a server that never calls `reloadPages`
+ * — a published one, or a platform's — would pay for and get nothing from. The template listens only then too.
+ */
+export declare const createDevReload: () => {
+    stage: Stage;
+    /** Every page open on this server loads again. */
+    reload: () => void;
+    /** The streams ended — the server is going away, and each page reconnects to whichever comes up next. */
+    close: () => void;
+};

package/dist/core/http/stages/devReload.js

@@ -0,0 +1,40 @@
+import { openEventStream } from "../sse.js";
+//#region src/core/http/stages/devReload.ts
+/** Where an open page listens for "the space changed: load again", in development. */
+var DEV_RELOAD_PATH = "/__plitzi/reload";
+/**
+* The page reloading itself when the space it shows changed — the edit loop of a project that authors its space in
+* code, without restarting the server: `main.ts` re-authors in a process of its own and calls `reloadPages()`, and
+* every page open on this server loads again.
+*
+* Only with `devReload` on: every open page keeps a connection for it, which a server that never calls `reloadPages`
+* — a published one, or a platform's — would pay for and get nothing from. The template listens only then too.
+*/
+var createDevReload = () => {
+	const listening = /* @__PURE__ */ new Set();
+	const stage = (ctx) => {
+		if (!ctx.config.devReload || ctx.req.path !== "/__plitzi/reload") return Promise.resolve(false);
+		const stream = openEventStream(ctx.rawRes, {
+			onAbort: () => listening.delete(stream),
+			retryMs: 1e3
+		});
+		listening.add(stream);
+		ctx.raw.once("close", () => {
+			listening.delete(stream);
+			stream.close();
+		});
+		return Promise.resolve(true);
+	};
+	return {
+		stage,
+		/** Every page open on this server loads again. */
+		reload: () => listening.forEach((stream) => stream.send("reload", {})),
+		/** The streams ended — the server is going away, and each page reconnects to whichever comes up next. */
+		close: () => {
+			listening.forEach((stream) => stream.close());
+			listening.clear();
+		}
+	};
+};
+//#endregion
+export { DEV_RELOAD_PATH, createDevReload };

package/dist/core/server/baseServer.d.ts

@@ -18,5 +18,7 @@ export interface HttpServerParts {
     /** What the primary does once, before it starts the workers — work each of them would otherwise repeat, or race
      *  the others to do. */
     beforeFork?: () => Promise<void>;
+    /** The open pages told to load again (`SSRServer.reloadPages`) — a page server in `devMode`; nothing elsewhere. */
+    reloadPages?: () => void;
 }
 export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/core/server/baseServer.js

@@ -34,6 +34,7 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 	return {
 		cache: channel && parts.cache ? relayCache(parts.cache, `${channel}.cache`) : parts.cache,
 		plugins: channel && parts.forgetPlugins ? relayPlugins(parts.plugins, parts.forgetPlugins, `${channel}.plugins`, label) : parts.plugins,
+		reloadPages: parts.reloadPages ?? (() => void 0),
 		listen(port, host = "0.0.0.0") {
 			if (plan.requested !== void 0 && role !== "worker") serverLog.warn(label, `${plan.requested} workers asked for, ${plan.count} cores to run them on: starting ${plan.count}`);
 			if (role === "primary") {

package/dist/core/server/drain.d.ts

@@ -10,8 +10,8 @@ export declare const SHUTDOWN_GRACE_MS = 10000;
  * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
  * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
  * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
- * the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
- * answered `graceMs`, and then cuts what remains.
+ * the idle ones, ends every event stream and WebSocket at once (neither has anything left to finish), gives what is
+ * still being answered `graceMs`, and then cuts what remains.
  */
 export declare const watchConnections: (server: PrimaryServer) => {
     drain: (label: string, graceMs?: number) => Promise<void>;

package/dist/core/server/drain.js

@@ -5,6 +5,13 @@ import { serverLog } from "../../helpers/serverLog.js";
 * called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
 */
 var SHUTDOWN_GRACE_MS = 1e4;
+/** A WebSocket close frame, as a server sends it (unmasked): status 1001, "going away". */
+var GOING_AWAY = Buffer.from([
+	136,
+	2,
+	3,
+	233
+]);
 /**
 * Whether a response is an event stream: said by its content type — or, since headers written with `writeHead(status,
 * headers)` are not kept where `getHeader` looks, by what it answers: a GET that asked for one, as an EventSource and
@@ -21,8 +28,8 @@ var isEventStream = (asking, answering) => {
 * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
 * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
 * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
-* the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
-* answered `graceMs`, and then cuts what remains.
+* the idle ones, ends every event stream and WebSocket at once (neither has anything left to finish), gives what is
+* still being answered `graceMs`, and then cuts what remains.
 */
 var watchConnections = (server) => {
 	const sockets = /* @__PURE__ */ new Set();
@@ -35,6 +42,13 @@ var watchConnections = (server) => {
 		sockets.add(socket);
 		socket.once("close", () => sockets.delete(socket));
 	});
+	const websockets = /* @__PURE__ */ new Set();
+	server.on("upgrade", (request, socket) => {
+		if ([request.headers.upgrade].flat().some((value) => value?.toLowerCase() === "websocket")) {
+			websockets.add(socket);
+			socket.once("close", () => websockets.delete(socket));
+		}
+	});
 	server.on("request", (request, response) => {
 		answering.set(response, request);
 		response.once("close", () => {
@@ -61,6 +75,7 @@ var watchConnections = (server) => {
 		answering.forEach((request, response) => {
 			if (isEventStream(request, response)) response.end(closeIdle);
 		});
+		websockets.forEach((socket) => socket.end(GOING_AWAY));
 	}) };
 };
 //#endregion

package/dist/core/server/pageServer.js

@@ -14,6 +14,7 @@ import { DRAFT_STORE_METHODS, createMemoryDraftStore } from "../../modules/ssr/p
 import { compileTemplate } from "../../modules/ssr/template.js";
 import { PluginManager } from "../../plugins/manager.js";
 import { makeHandler } from "../http/dispatcher.js";
+import { createDevReload } from "../http/stages/devReload.js";
 import { buildPagePipeline } from "../services/registry.js";
 //#region src/core/server/pageServer.ts
 /** The page-serving machinery: html/rsc caches, the render template and the plugin manager, driving the page
@@ -49,7 +50,8 @@ var createPageServer = (config, services, extensions) => {
 	};
 	const actions = actionsModuleFor(config);
 	const realtime = realtimeModuleFor(config);
-	const stages = buildPagePipeline(services, extensions);
+	const devReload = config.devReload ? createDevReload() : void 0;
+	const stages = [...devReload ? [devReload.stage] : [], ...buildPagePipeline(services, extensions)];
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
 			raw,
@@ -81,7 +83,11 @@ var createPageServer = (config, services, extensions) => {
 			pluginManager.forget(name, version);
 			invalidatePluginComponentCache();
 		},
-		onClosing: () => realtime?.close(),
+		onClosing: () => {
+			realtime?.close();
+			devReload?.close();
+		},
+		...devReload ? { reloadPages: devReload.reload } : {},
 		onDestroy: async () => {
 			await actions?.jobs?.stop();
 			destroyServerCaches(caches);

package/dist/modules/ssr/prepareRender.js

@@ -228,6 +228,7 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			plugins: templatePlugins,
 			debugMode: debugAuthorized,
 			ssrOnly: config.ssrOnly === true,
+			devReload: config.devReload === true,
 			offlineData: offlineDataStr
 		},
 		cacheable: actionRuns === void 0 && forcedFlags === void 0

package/dist/modules/ssr/views/template.ejs

@@ -139,5 +139,11 @@
       render('plitzi', __plitziParams, __plitziPlugins, <%= locals.debugMode ? true : false %>, true);
     </script>
     <% } %>
+    <% if (locals.devReload) { %>
+    <%# Development only: the server says the space changed (re-authored, `reloadPages`), and the page loads again. %>
+    <script>
+      new EventSource('/__plitzi/reload').addEventListener('reload', () => location.reload());
+    </script>
+    <% } %>
   </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.2",
+  "version": "0.38.3",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -79,8 +79,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.2",
-    "@plitzi/sdk-shared": "0.38.2",
+    "@plitzi/plitzi-sdk": "0.38.3",
+    "@plitzi/sdk-shared": "0.38.3",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -31,15 +31,17 @@ text('Words', { class })                       // also text({ content }); a <div
 heading('Title', { subType: 'h2' })            // h1–h6; holds no children
 paragraph('A paragraph.')
 container([children], { subType: 'section' })  // div, section, nav, header, footer, main, article, li, h1–h6, span…
-link({ href: 'about', children })              // a page id, a '/path', or a URL — the mode follows from the href
+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
 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
 svg('<svg …>…</svg>', { label })               // checked, sanitised; currentColor follows the class
+svg(svgFile(new URL('./logo.svg', import.meta.url)))  // a file, compacted: svgFile/svgFiles from '@plitzi/sdk-authoring/node'
 fontAwesome({ icon: 'fa-solid fa-xmark' })
-list({ id: 'rows', items: 'p.data.rows', row: 'row-card' })    // a <ul>; a component per row (its `item` prop)
-list({ id: 'rows', items: 'p.data.rows', row: r => text({ from: `${r.item}.title` }) })  // or a tree per row
+list({ id: 'rows', items: 'p.data.rows', row: 'row-card' })    // a <ul>; a component per row, its root an <li>
+list({ id: 'rows', items: 'p.data.rows', row: r => listItem({ children: [text({ from: `${r.item}.title` })] }) })
 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

package/skills/plitzi-authoring/SKILL.md

@@ -158,6 +158,7 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | [flows.md](reference/flows.md) | Clicks, submits, page loads, every few seconds, server actions, modals, state |
 | [realtime.md](reference/realtime.md) | Pages that see each other: channels, presence, cursors, a shared board, who may hear a topic |
 | [plugins.md](reference/plugins.md) | A component of your own: props, binding them, writing state, channels, registering, behaving in the builder |
+| [drawing.md](reference/drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL shaders that say why they failed, a loop that stops when nobody sees it |
 | [structure.md](reference/structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
 | [testing.md](reference/testing.md) | Any test: `inspectPage` (one call, every problem), handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
 | [performance.md](reference/performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |

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

@@ -16,7 +16,8 @@ import {
   list,
   onClick,
   styles,
-  text
+  text,
+  listItem
 } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
@@ -74,14 +75,18 @@ export const recipe: SpaceSpec = {
               class: dots,
               items: 'hero.items',
               row: r =>
-                button({
-                  content: '',
-                  class: dot,
-                  bind: [
-                    bindTemplate('title', r.index, 'Slide {{ source + 1 }}'),
-                    activeWhen(dot, `{{ ${r.inTemplate.index} == carousel_hero.index }}`)
-                  ],
-                  flows: [[onClick(), carouselGoTo('hero', `{{ ${r.inTemplate.index} }}`)]]
+                listItem({
+                  children: [
+                    button({
+                      content: '',
+                      class: dot,
+                      bind: [
+                        bindTemplate('title', r.index, 'Slide {{ source + 1 }}'),
+                        activeWhen(dot, `{{ ${r.inTemplate.index} == carousel_hero.index }}`)
+                      ],
+                      flows: [[onClick(), carouselGoTo('hero', `{{ ${r.inTemplate.index} }}`)]]
+                    })
+                  ]
                 })
             })
           ]

package/skills/plitzi-authoring/recipes/detail-page.ts

@@ -3,7 +3,7 @@
  * A page per record: a card links to `/products/<slug>`, and the detail page narrows the same file to the product its
  * address names — with a message, not an empty page, when no product has that name.
  */
-import { apiContainer, heading, link, list, text } from '@plitzi/sdk-authoring';
+import { apiContainer, heading, link, list, text, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -25,10 +25,14 @@ export const recipe: SpaceSpec = {
               id: 'products',
               items: 'catalog.data.products',
               children: [
-                // An attribute reads a name with filters, spelled in full.
-                link({
-                  href: '/products/{{ list_products.item.slug|url_encode }}',
-                  children: [text({ from: 'products.item.title' })]
+                listItem({
+                  children: [
+                    // An attribute reads a name with filters, spelled in full.
+                    link({
+                      href: '/products/{{ list_products.item.slug|url_encode }}',
+                      children: [text({ from: 'products.item.title' })]
+                    })
+                  ]
                 })
               ]
             })
@@ -54,7 +58,7 @@ export const recipe: SpaceSpec = {
                 source: 'catalog-one.data.products',
                 template: "{{ source|find('slug', navigation.routeParams.slug) }}"
               },
-              children: [heading({ subType: 'h1', from: 'this-product.item.title' })]
+              children: [listItem({ children: [heading({ subType: 'h1', from: 'this-product.item.title' })] })]
             }),
             text('No product by that name.', {
               visible: {

package/skills/plitzi-authoring/recipes/every-few-seconds.ts

@@ -18,7 +18,8 @@ import {
   styles,
   text,
   activeWhen,
-  when
+  when,
+  listItem
 } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
@@ -81,7 +82,7 @@ export const recipe: SpaceSpec = {
               id: 'slides',
               items: SLIDES,
               children: [
-                container({
+                listItem({
                   class: slide,
                   visible: { source: 'slides.index', template: '{{ source == (state.slide ?? 0) }}' },
                   children: [heading({ subType: 'h2', from: 'slides.item.title' }), text({ from: 'slides.item.body' })]
@@ -101,12 +102,16 @@ export const recipe: SpaceSpec = {
               class: dots,
               items: SLIDES,
               children: [
-                button({
-                  content: '',
-                  title: 'Show this offer',
-                  class: dot,
-                  bind: [activeWhen(dot, '{{ list_dots.index == (state.slide ?? 0) }}')],
-                  flows: [[onClick(), setState({ key: 'slide', type: 'number', value: '{{ list_dots.index }}' })]]
+                listItem({
+                  children: [
+                    button({
+                      content: '',
+                      title: 'Show this offer',
+                      class: dot,
+                      bind: [activeWhen(dot, '{{ list_dots.index == (state.slide ?? 0) }}')],
+                      flows: [[onClick(), setState({ key: 'slide', type: 'number', value: '{{ list_dots.index }}' })]]
+                    })
+                  ]
                 })
               ]
             }),

package/skills/plitzi-authoring/recipes/filter-a-list.ts

@@ -3,7 +3,7 @@
  * Filter and sort a list: a select writes the chosen category to `state`, and the list is bound through a template
  * that hands over its VALUE — only the matching rows are rendered, with a count and an empty state over the same rows.
  */
-import { apiContainer, formControl, list, named, on, setState, text } from '@plitzi/sdk-authoring';
+import { apiContainer, formControl, list, named, on, setState, text, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -47,7 +47,7 @@ export const recipe: SpaceSpec = {
               id: 'shown',
               from: 'catalog.data.products',
               as: `{{ ${shown} }}`,
-              children: [text({ from: 'shown.item.title' })]
+              children: [listItem({ children: [text({ from: 'shown.item.title' })] })]
             }),
             text('Nothing in that category.', {
               visible: {

package/skills/plitzi-authoring/recipes/forms-and-modals.ts

@@ -5,7 +5,6 @@
 import {
   button,
   closeModal,
-  fontAwesome,
   form,
   formControl,
   modalContainer,
@@ -52,7 +51,7 @@ export const recipe: SpaceSpec = {
             button({
               content: '',
               title: 'Close',
-              children: [fontAwesome({ icon: 'fa-solid fa-xmark' })],
+              icon: 'fa-solid fa-xmark',
               flows: [[onClick(), closeModal('details')]]
             })
           ]

package/skills/plitzi-authoring/recipes/from-tailwind.ts

@@ -45,7 +45,7 @@ export const recipe: SpaceSpec = {
             container({ class: card, children: [heading(name, { subType: 'h3', class: title }), text('…')] })
           )
         }),
-        link({ href: '/start', class: cta, children: [text('Get started')] })
+        link({ href: '/start', class: cta, content: 'Get started' })
       ]
     }
   ]

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

@@ -15,7 +15,7 @@ export const recipe: SpaceSpec = {
       name: 'Home',
       slug: '',
       body: [
-        link({ href: 'home', hash: 'plans', children: [text('See the plans')] }),
+        link({ href: 'home', hash: 'plans', content: 'See the plans' }),
         container({
           id: 'plans-section',
           subType: 'section',
@@ -29,7 +29,7 @@ export const recipe: SpaceSpec = {
       name: 'About',
       slug: 'about',
       // → /#plans
-      body: [link({ href: 'home', hash: 'plans', children: [text('Plans')] })]
+      body: [link({ href: 'home', hash: 'plans', content: 'Plans' })]
     }
   ]
 };

package/skills/plitzi-authoring/recipes/link-with-data.ts

@@ -2,7 +2,7 @@
  * A link built from the row it is in — here "ask about this product" on WhatsApp, with the product's name in the
  * message. An attribute resolves a name with filters, so the text is encoded with `url_encode`.
  */
-import { apiContainer, fontAwesome, link, list, text } from '@plitzi/sdk-authoring';
+import { apiContainer, link, list, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -24,12 +24,17 @@ export const recipe: SpaceSpec = {
               id: 'products',
               items: 'catalog.data.products',
               children: [
-                link({
-                  target: 'blank',
-                  href: 'https://wa.me/34600000000?text={{ list_products.item.title|url_encode }}',
-                  children: [fontAwesome({ icon: 'fa-brands fa-whatsapp' }), text('Ask about it')]
-                }),
-                link({ href: 'mailto:shop@example.com', children: [text('Write to us')] })
+                listItem({
+                  children: [
+                    link({
+                      target: 'blank',
+                      href: 'https://wa.me/34600000000?text={{ list_products.item.title|url_encode }}',
+                      icon: 'fa-brands fa-whatsapp',
+                      content: 'Ask about it'
+                    }),
+                    link({ href: 'mailto:shop@example.com', content: 'Write to us' })
+                  ]
+                })
               ]
             })
           ]

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

@@ -2,7 +2,7 @@
  * A marquee: a row of names that scrolls for ever and stops under the pointer. The items are rendered three times
  * and the keyframe moves the track by a third, so the end meets the start with no jump.
  */
-import { apiContainer, container, list, styles, text } from '@plitzi/sdk-authoring';
+import { apiContainer, container, list, styles, text, listItem } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
 
@@ -45,7 +45,7 @@ export const recipe: SpaceSpec = {
                   class: track,
                   from: 'catalog.data.brands',
                   as: '{{ source|merge(source)|merge(source) }}',
-                  children: [text({ from: 'brands.item' })]
+                  children: [listItem({ children: [text({ from: 'brands.item' })] })]
                 })
               ]
             })

package/skills/plitzi-authoring/recipes/scroll-a-row.ts

@@ -12,7 +12,8 @@ import {
   scrollBy,
   setState,
   styles,
-  text
+  text,
+  listItem
 } from '@plitzi/sdk-authoring';
 
 import type { SpaceSpec } from '@plitzi/sdk-authoring';
@@ -45,10 +46,9 @@ export const recipe: SpaceSpec = {
           children: [
             // Shown until the row says it is at that end: the arrows are there before anybody scrolls.
             button({
-              content: '',
+              content: '‹',
               title: 'Previous categories',
               visible: '!state.rowAtStart',
-              children: [text('‹')],
               flows: [[onClick(), scrollBy('categories', { x: '-80%' })]]
             }),
             list({
@@ -62,13 +62,12 @@ export const recipe: SpaceSpec = {
                   setState({ key: 'rowAtEnd', type: 'boolean', value: '{{ moved.atEnd }}' })
                 ]
               ],
-              children: [text({ class: card, from: 'categories.item' })]
+              children: [listItem({ class: card, children: [text({ from: 'categories.item' })] })]
             }),
             button({
-              content: '',
+              content: '›',
               title: 'More categories',
               visible: '!state.rowAtEnd',
-              children: [text('›')],
               flows: [[onClick(), scrollBy('categories', { x: '80%' })]]
             })
           ]

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

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

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

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

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

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

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

@@ -13,10 +13,10 @@ warns about each case below (`control-without-name`, `image-without-alt`, `click
 button({ content: 'Save' })
 
 // An icon only: `title` is its name, and also its tooltip. The icon is hidden from the tree by itself.
-button({ content: '', title: 'Close', children: [fontAwesome({ icon: 'fa-solid fa-xmark' })] })
+button({ content: '', title: 'Close', icon: 'fa-solid fa-xmark' })
 
 // Words that do not say what it does — a key hint, a count: `label` is read in their place.
-button({ content: '', label: 'Select (V)', title: 'Select — V', children: [fontAwesome({ icon: 'fa-solid fa-arrow-pointer' }), text('V')] })
+button({ content: 'V', label: 'Select (V)', title: 'Select — V', icon: 'fa-solid fa-arrow-pointer' })
 
 // A link around a whole card: without `label` it is announced as every word inside the card.
 link({ href: '/posts/field-notes', label: 'Read “Field notes”', children: [ /* cover, topic, title, byline */ ] })

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

@@ -92,6 +92,8 @@ The space is not written until these are fixed.
 | `loading-slot-unknown` | an `apiContainer`'s `loadingSlot` that is not the id of one of its children | the id of the child to show until the first answer — `loadingSlot: 'catalog-skeleton'` beside that child |
 | `modifier-count` | more than one set of rules in a class list | one set, after the classes: `class: [card, { opacity: '0.5', 'margin-top': '8px' }]` |
 | `modifier-without-id` | rules on top of a class on an element with no `id` — the id names the class they become | `id: 'hero-bg'` |
+| `motion-invalid` | a `motion` with a preset, a trigger or a timing the page cannot play | `motion: { enter: 'fade-up', on: 'view' }` — the message lists the presets |
+| `motion-no-tag` | a `motion` on an element with no tag of its own — nothing to move | the motion on what it wraps, or a `subType` on it |
 | `no-pages` | a space with no pages | `pages: [{ id: 'home', name: 'Home', slug: '', body: [] }]` |
 | `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the fields it lists; a colour or a length, like 'var(--card)' or '12px' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
@@ -172,9 +174,11 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `image-without-alt` | an image that is not `decorative` and has no `alt` | say what it shows, or `decorative: true` |
 | `label-ignored` | a `label` on a container whose tag is named by what it holds (`li`, a heading) | the words inside, or a landmark tag (`nav`, `section`…) |
 | `list-item-key-missing` | a list's `itemKey` that some of its items lack, or two of them share — the rows fall back to `id`, then position | a field every item has, once each |
+| `list-row-not-li` | a row of a list with `items` that is not an `<li>` — that list is a `<ul>` (or `<ol>`), so the row is a box inside a list, no item to a screen reader | `container({ subType: 'li' })` — or the component's root one, or a wrapper for a link or a button |
 | `overlay-never-opened` | a modal or a dialog that starts hidden and that no step opens | a flow with `openModal('id')` / `openDialog('id')` |
 | `overlay-starts-open` | a modal or a dialog open when the page loads | `visible: false`, opened by `openModal` |
 | `painted-state-without-keep-state` | `paintedState` without `keepState` — nothing is kept for the server to draw with | `settings.keepState: true`, or remove `paintedState` |
+| `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 |
@@ -189,6 +193,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `unknown-global-callback` | a global callback no built-in source declares — it runs only if something registers it | the built-in it suggests, or make sure a plugin or module of the space registers it |
 | `unknown-utility` | a utility that is not one of the built-in ones | one of the built-in utilities |
 | `unknown-variable` | a `var(--x)` nothing in the space declares — the property it is in is dropped | declare it under `variables`, fix the name, or give it a fallback: `var(--x, …)` |
+| `unknown-variant` | a variant no class of the element and no style of its type declares — nothing applies | declare it (`styles(name, { variants: { … } })`), or name one that is |
 
 ## Suggested
 

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

@@ -19,6 +19,9 @@
 Only `opacity` and `transform` (`translate`, `scale`, `rotate`) animate off the main thread: they stay smooth while
 the page hydrates and on a slow phone. Everything else repaints, or lays the page out again, on every frame.
 
+- **A preset first:** `motion: { enter: 'fade-up', on: 'view' }` on any element, `stagger: 60` for children one by one,
+  `loop: 'float'` — played by the SDK, cheap and stilled for reduced motion by construction (motion.md lists them).
+
 - **Slide, grow, fade** with `transform` and `opacity` — never `left`, `top`, `width`, `height` or `margin`. Something
   that travels across a box is `transform: translate(%)` on an element as large as the box.
 - **No animated blur:** no `filter: blur()` in an entrance or a loop, no `backdrop-filter` over moving content. A soft

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

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

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

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

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

@@ -66,8 +66,8 @@ says `content: ''` (`default-content-beside-children` warns otherwise). Its acce
 keeps its own value and fires `onChange` with `{ value, name }` on every change — a search box or a select that
 filters a screen needs no form. Bind `defaultValue` to the state it writes and a reset of that state reaches it.
 
-**A `list` is a `<ul>`.** The browser indents it and puts bullets on it; a list of cards needs
-`{ margin: '0px', padding: '0px', 'list-style-type': 'none' }` in its class.
+**A `list` is a `<ul>`, its rows `<li>`s straight inside** — `listItem({ … })`, or `list-row-not-li` warns. It is
+indented with space below it: `{ margin: '0px', padding: '0px' }` on its class takes that off.
 
 **A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own by default, so its
 children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the

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

@@ -8,8 +8,8 @@ list bound to its records (see the provider in data-and-visibility).
 
 ```ts
 list({ id: 'games', class: gameGrid, items: 'catalog.data.games', row: 'game-card' })   // a component per game
-list({ id: 'games', items: 'catalog.data.games', row: r => text({ from: `${r.item}.title` }) })   // or a tree of its own
-list({ id: 'plans', items: ['Free', 'Pro'], children: [text({ from: 'plans.item' })] })  // fixed items
+list({ id: 'games', items: 'catalog.data.games', row: r => listItem({ children: [text({ from: `${r.item}.title` })] }) })
+list({ id: 'plans', items: ['Free', 'Pro'], children: [listItem({ children: [text({ from: 'plans.item' })] })] })  // fixed
 ```
 
 `items` makes a list controlled: an array of its own, or the source its rows come from. `row` is what it renders once
@@ -17,15 +17,20 @@ per item — a component's id (placed with the row bound to its `item` prop, or
 row's names: `r.item` and `r.index` for a binding or `from`, `r.inTemplate.item` for a template
 (`` `/games/{{ ${r.inTemplate.item}.slug }}` ``). A function needs the list's `id`, which names those sources. With
 `items` a typed source's path (`items: site.data.games`, see typed-sources.md), the row is typed too:
-`row: g => text({ from: g.item.title })`, and a field the sample's games lack is a type error.
+`row: g => listItem({ children: [text({ from: g.item.title })] })`, and a field the sample's games lack is a type error.
 
 - Each row publishes **`list_<id>.item`** (the row) and **`list_<id>.index`** (its position, a number from 0 —
   `index + 1` counts, and `==` compares it with text or a number alike). Inside the row,
   bindings read the short form (`'games.item.title'`), templates and attribute tokens the full one
   (`{{ list_games.item.slug }}`).
 - A **nested list** sees the outer row: inside `list_features`, `list_games.item` is still the game.
-- The list is a `<ul>` and its `class` styles that root; each child is rendered straight into it, with no wrapper.
-  A card grid needs `{ margin: '0px', padding: '0px', 'list-style-type': 'none' }` in its class.
+- A list is a `<ul>` (`subType: 'ol'` for a numbered one) and its `class` styles that root; each row is rendered
+  straight into it, with no wrapper — so **a row is an `<li>`**: `listItem({ class, children })`, a
+  `container({ subType: 'li' })`, or a component whose root is one. Anything else is a box inside a list, no item to a
+  screen reader (`list-row-not-li`; `fixSpace` makes a plain container one). A link or a button is wrapped in a
+  `listItem`, which is then what the list lays out: a card that is a link fills its item with `display: 'grid'` on the
+  `listItem`. Every list is indented (40px) with 10px below it, and one without `items` is bulleted too:
+  `{ margin: '0px', padding: '0px' }` on the root takes the space off. A grid of cards is the root's class.
 - Fixed data is `items: [ … ]` on the list itself — no provider needed. Worth it when the rows ARE data — written from
   an array, or rows that come and go (`repeated-shape` points at sibling copies). Three cards a person rewords on the
   canvas are easier to edit as three cards than as a JSON array.
@@ -68,7 +73,7 @@ apiContainer({ id: 'catalog', query: '/data/games.json', cache: true, children:
     source: 'controlled',
     bind: [bindTemplate('items', 'catalog.data.games',
       '{{ source|filter(g => g.slug == navigation.routeParams.slug) }}', { returns: 'value' })],
-    children: [gameDossier()]                       // reads list_game.item
+    children: [listItem({ children: [gameDossier()] })]   // reads list_game.item
   }),
   text('Signal lost — no game by that name.', {
     id: 'game-missing',

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

@@ -107,6 +107,11 @@ const newChart = useFlag('newChart'); // false for a flag the space does not dec
 Gating the whole plugin needs no code: give its element `flag: 'newChart'`. `useFlag` is for a plugin that changes
 inside — a new mode, an extra panel.
 
+## Drawing and animating
+
+A canvas, WebGL or a loop of its own: `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` — see
+[drawing](drawing.md).
+
 ## Registering
 
 A project `plitzi create` wrote registers every folder of `src/plugins` by itself, under the folder's name in

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

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

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

@@ -13,8 +13,11 @@ expect((await inspectPage(page, handles)).problems).toEqual([]);
 It checks the open page and returns EVERY problem at once, one sentence each, naming the element and the reason:
 
 - every element the page owes is present and visible — its own and those of the layouts around it
-  (`heading "hero-title" is on the page but not visible: display:none on "hero"`);
-- every image arrived — an image element that failed says so (`data-plitzi-failed`), though its fallback loads;
+  (`heading "hero-title" is on the page but not visible: display:none on "hero"`). One a breakpoint hides at this
+  width (`mobile: { display: 'none' }`, or shown only at another width) is laid out by width, not missing: listed in
+  `hiddenAtWidth`, and checked at the width it shows at — run the check at each width you author for;
+- every image arrived — an image element that failed says so (`data-plitzi-failed`), though its fallback loads. A lazy
+  image out of sight (below the fold, or beside the screen in a carousel's track) has not been asked for yet, and waits;
 - nothing scrolls sideways (`the page scrolls sideways by 37px — widest: "cards"`);
 - no text is drawn in the colour painted behind it.
 
@@ -33,10 +36,12 @@ the list `inspectPage` holds a page to.
 
 Three flags say what a bare visit cannot promise, and `onScreen` leaves out:
 
-- `conditional` — on screen only under a condition of its own or of an ancestor;
+- `conditional` — on screen only under a condition of its own or of an ancestor, or with every child conditional (a
+  list of flyouts at rest);
 - `repeated` — inside a list row, so rendered once per row: several copies, or none while the list is empty. Address
   one with `.first()` / `.nth(i)`, in a test that knows the data;
-- `boxless` — a provider with no tag, which renders its children and no element of its own.
+- `boxless` — a provider with no tag, which renders its children and no element of its own; or a plugin whose
+  declaration says `drawsNothing: true` — behaviour rather than content, a clock that fires a flow.
 
 A `formControl`'s id names its wrapper: type into `locate('email').locator('input')`.
 

package/skills/plitzi-authoring/reference/typed-sources.md

@@ -9,7 +9,7 @@ const site = source('site', home);
 apiContainer({ id: site.id, query: '/data/home.json', children: [
   heading({ from: site.data.hero.title }),
   text({ content: twig`{{ ${site.data.products}|length }} products` }),
-  list({ id: 'products', items: site.data.products, row: p => text({ from: p.item.title }) })
+  list({ id: 'products', items: site.data.products, row: p => listItem({ children: [text({ from: p.item.title })] }) })
 ] })
 ```
 

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

@@ -47,8 +47,9 @@ bar.
 
 2. **Fix, re-run, until it prints zero warnings.** What has one fix (`author` says how many) is written for you: `npx
    plitzi fix` shows it as a diff of your source, `--write` writes it and keeps it only if the space authors with each
-   fix gone and nothing new — a fix it cannot place, or that would add a problem, is said with the reason. Then
-   typecheck the project.
+   fix gone and nothing new — a fix it cannot place, or that would add a problem, is said with the reason. A
+   suggestion with one reading is written the same way (`content-attribute`: words and an icon held as children become
+   the button's or link's own `content` and `icon`). Then typecheck the project.
 3. **Look at it** — in a browser, at desktop and phone width, in both themes (see [testing](testing.md)). Stage 3 is
    thorough about MEANING and blind to what follows.