@plitzi/sdk-server 0.38.7 → 0.38.9

package/dist/modules/ssr/handler.js

@@ -1,6 +1,6 @@
 import { buildHtmlCacheKey } from "../../helpers/cache/keys.js";
 import { draftSessionCookie, takeDraftOverride } from "./preview.js";
-import { applySSRResult } from "./applySSRResult.js";
+import { applySSRResult, isReusable } from "./applySSRResult.js";
 import { buildBody } from "./buildBody.js";
 import { streamBody } from "./streamBody.js";
 import { RequestMetrics } from "../../helpers/metrics.js";
@@ -63,7 +63,7 @@ var renderSSR = async (req, res, config, renderFn, pluginManager, caches) => {
 		metrics.log(`${req.method} ${req.path}`);
 	}
 	if (applySSRResult(res, result)) return;
-	if (htmlCache && cacheKey && body !== void 0 && cacheable) {
+	if (htmlCache && cacheKey && body !== void 0 && cacheable && isReusable(result)) {
 		const page = {
 			html: body,
 			compressed: {}

package/dist/modules/ssr/prepareRender.d.ts

@@ -11,5 +11,7 @@ export type RenderPrep = {
     };
     /** False for a render that must not be served to anybody else from a cache: it carries this request's own runs. */
     cacheable: boolean;
+    /** A server provider of the page said its address shows nothing (`notFound`): sent with status 404. */
+    notFound: boolean;
 };
 export declare const prepareRender: (req: SSRRequest, config: SSRPageServerConfig, spaceId: number, environment: Environment, revision: number, pluginManager: PluginManager, offlineDataCache?: TtlCache<string>, metrics?: RequestMetrics, offlineDataOverride?: OfflineDataRaw) => Promise<RenderPrep>;

package/dist/modules/ssr/prepareRender.js

@@ -20,7 +20,7 @@ import { sdkAssetVersion } from "../../core/sdkAssets.js";
 import { buildServerInfo } from "../../helpers/buildServerInfo.js";
 import { resolveDebugMode } from "../../helpers/resolveDebugMode.js";
 import { flagUserFromSSR, flagValues, resolveFlags } from "@plitzi/sdk-shared/flags";
-import { hasServerElements } from "@plitzi/sdk-shared/schema/serverElements";
+import { collectServerElements, notFoundProvider } from "@plitzi/sdk-shared/schema/serverElements";
 import { debugCookieName } from "@plitzi/sdk-shared/devTools";
 import { themeFromCookies } from "@plitzi/sdk-shared/theme";
 import { paintedKeys, paintedStateFor } from "@plitzi/sdk-shared/state/paintedState";
@@ -74,7 +74,8 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		queryParams: req.query,
 		user: flagUserFromSSR(req.ctx.user)
 	}, flagOverrides)) : void 0;
-	const rscData = rscEnabled && pageMatch !== void 0 && hasServerElements(schema, pageMatch.pageId, pageFlags) && config.adapters.getRscData ? await m("rsc", () => config.adapters.getRscData?.({
+	const serverElements = rscEnabled && pageMatch !== void 0 ? collectServerElements(schema, pageMatch.pageId, void 0, pageFlags) : [];
+	const rscData = serverElements.length > 0 && config.adapters.getRscData ? await m("rsc", () => config.adapters.getRscData?.({
 		req,
 		spaceId: req.ctx.spaceDeployment?.spaceId ?? spaceId,
 		environment: req.ctx.spaceDeployment?.environment ?? environment,
@@ -84,6 +85,10 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		flagOverrides
 	})) : rscPath ? { serverData: {} } : void 0;
 	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId);
+	const notFound = pageMatch !== void 0 && rscData?.serverData !== void 0 ? notFoundProvider(serverElements, rscData.serverData, {
+		routeParams: pageMatch.routeParams,
+		queryParams: req.query
+	}) !== void 0 : false;
 	const server = buildServerInfo(req, config, {
 		rscPath,
 		rscData,
@@ -281,7 +286,8 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 			devReload: config.devReload === true,
 			offlineData: offlineDataStr
 		},
-		cacheable: actionRuns === void 0 && forcedFlags === void 0
+		cacheable: actionRuns === void 0 && forcedFlags === void 0,
+		notFound
 	};
 };
 //#endregion

package/dist/modules/ssr/streamBody.js

@@ -1,4 +1,4 @@
-import { applySSRResult } from "./applySSRResult.js";
+import { applySSRResult, isReusable, withNotFound } from "./applySSRResult.js";
 import Component from "./Component.js";
 import { prepareRender } from "./prepareRender.js";
 import { renderToPipeableStream } from "react-dom/server";
@@ -30,7 +30,7 @@ var streamBody = async (req, res, config, spaceId, environment, revision, render
 				const tailBuf = Buffer.from(tail, "utf-8");
 				res.write(tailBuf);
 				res.end();
-				if (chunks && cacheKey && htmlCache) htmlCache.set(cacheKey, {
+				if (chunks && cacheKey && htmlCache && isReusable(result)) htmlCache.set(cacheKey, {
 					html: head + Buffer.concat(chunks).toString("utf-8") + tail,
 					compressed: {}
 				});
@@ -49,6 +49,7 @@ var streamBody = async (req, res, config, spaceId, environment, revision, render
 					res.setHeader("Server-Timing", metrics.toServerTimingHeader());
 					metrics.log(`${req.method} ${req.path}`);
 				}
+				withNotFound(result, prep.notFound);
 				if (applySSRResult(res, result)) {
 					abort();
 					resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.7",
+  "version": "0.38.9",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.7",
-    "@plitzi/sdk-shared": "0.38.7",
+    "@plitzi/plitzi-sdk": "0.38.9",
+    "@plitzi/sdk-shared": "0.38.9",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/SKILL.md

@@ -9,174 +9,59 @@ description: >-
 
 # Authoring Plitzi spaces
 
-A space is two JSON documents — a schema and a style — full of cross-referenced ids. **Never write them by hand.**
-`@plitzi/sdk-authoring` derives every id, class name, parent link, breakpoint map and flow chain from a small
-declaration, and refuses a declaration that would not render.
+A space is two JSON documents full of cross-referenced ids — **never write them by hand**. `@plitzi/sdk-authoring`
+derives them from a small declaration, and refuses one that would not render.
 
 ```ts
-import { authorSpace, container, heading, styles, text } from '@plitzi/sdk-authoring';
+import { heading, styles, text } from '@plitzi/sdk-authoring';
 
-const page = styles('page', { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' });
+const page = styles('page', { display: 'flex', 'flex-direction': 'column', gap: '16px' });
 
 export const space = {
   name: 'My space',
   permanentUrl: 'my-space',
   pages: [{ name: 'Home', slug: '', class: page, body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }]
 };
-
-const { schema, style, warnings } = authorSpace(space);
 ```
 
-**Start with [the cheatsheet](CHEATSHEET.md)** — the factories, fields, steps and the problems met most, on one page —
-and open a reference below only when the task names its subject. What an element takes, a step's params, what a
-trigger hands its flow: `npx @plitzi/cli explain <name>` answers in a few lines (over MCP, `plitzi://explain/<name>`).
-The published `.d.ts` documents the rest — search it by name, never read it whole.
-
-This skill writes a space that lives in code. One that lives on Plitzi — edited in the builder, published from there —
-is edited through the Plitzi MCP server instead, never both on one space; `plitzi create --from <space>` turns the
-second into the first. If the MCP asks for a sign-in nobody can give, a project in code needs no account.
+A space on Plitzi — edited in the builder — is edited through the Plitzi MCP server instead, never both on one space.
 
 ## How to work
 
-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 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]`) 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
-   (`--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.
+1. **Find, then write.** `npx plitzi element where <id|class|words>` answers the file, the line and the call: edit there, and
+   extend what the space already has. People move files — never keep a note of where something is.
+2. **Author.** `npm run author`. A refusal says what to write instead: do exactly that. Every problem comes at once —
+   fix them all before running again. Zero warnings; take the suggestions, the biggest first.
+3. **Look.** `npm run check -- /path --width 1440,390` says in text whether the page is whole; `npm run shot` only
+   when the text is not enough.
+4. **Before saying done:** `npm run lint:space` clean, and the [review checklist](reference/review-checklist.md).
 
-## The rules that matter most
+What a name means — an element, a step, a trigger, a code, any export (`pageFamily`, `SpaceSpec`): `npx plitzi explain
+<name>`, in a few lines. Never read the `.d.ts`.
 
-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-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 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
-   never changes is its own class.
-4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
-   the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
-   `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
-   loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
-   is folded), it keeps the default and an absent flag must leave it shown. See
-   [data and visibility](reference/data-and-visibility.md). What a PERSON switches on — a feature in beta, a rollout —
-   is a feature flag, not a visibility: gated off, it is not rendered at all. See [feature flags](reference/feature-flags.md).
-5. **Know where a template is evaluated.** A binding's template (`bindTemplate`) and a step's params evaluate full
-   Twig. An ATTRIBUTE resolves a name with filters (`{{ list_games.item.slug }}`, `{{ post.slug|url_encode }}`) against
-   the sources around the element; a condition there is used as written. Inside any template a source is spelled in
-   full — `apiContainer_stats`, `list_rows` — and a query param is `navigation.queryParams.x`. A template that feeds a
-   list its `items` hands over its value (`returns: 'value'`). `authorSpace` refuses a template it cannot read and a
-   name nothing answers to. See [templates](reference/templates.md).
-6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
-   checked from the first commit.
-7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
-   a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
-8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (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 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
-    named for the default (`showPlates`, on by default) takes a first click to do nothing: name it `platesOff`, and read
-    every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
-    anybody touches it.
-12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
-    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
-    [plugins](reference/plugins.md).
-13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
-    accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`
-    (`hideLabel: true` hides it and keeps the name), every image an `alt` or `decorative: true`. Clicks go on a
-    `button` — it holds children, so a whole card can be one — or a `link`, never on a container. See
-    [accessibility](reference/accessibility.md).
-14. **Motion that stays smooth.** Animate `opacity` and `transform` only; no animated blur, shadow or size. See
-    [motion](reference/colours-and-motion.md).
+## Five rules authoring cannot check for you
 
-## Recipes
+1. **Name what is referred to.** An `id` for every element a binding, a flow or a test addresses; ids are one namespace,
+   so a helper that runs twice builds inside `scope('promos', ref => …)`.
+2. **Share, never copy.** A look used twice is a class; chrome on several pages a layout; a block placed again with
+   other content a component; rows of data one `list`.
+3. **What is revealed starts hidden** (`visible: 'source'`), so it never flashes while its data loads.
+4. **Know where a template runs.** A binding and a step's params are full Twig; an attribute resolves a name with
+   filters. A source is spelled in full: `apiContainer_stats`.
+5. **Tokens, not colours** — a variable with a `light` and a `dark` value.
 
-Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
+The rest, and why: [rules](reference/rules.md).
 
-| To… | Open |
-| --- | --- |
-| Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](recipes/show-data.ts) |
-| Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](recipes/typed-data.ts) |
-| Data read by the page server (`--mode server`) | [recipes/server-data.ts](recipes/server-data.ts) |
-| An accordion, one answer open at a time | [recipes/accordion.ts](recipes/accordion.ts) |
-| Filter and sort a list from a select | [recipes/filter-a-list.ts](recipes/filter-a-list.ts) |
-| A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](recipes/detail-page.ts) |
-| Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](recipes/link-to-a-section.ts) |
-| A carousel: slides with arrows, dots and autoplay; a marquee; a row that swipes | [recipes/carousel.ts](recipes/carousel.ts) |
-| Do something every few seconds — a ticker, a poll, a slideshow by hand | [recipes/every-few-seconds.ts](recipes/every-few-seconds.ts) |
-| A marquee that scrolls for ever and stops under the pointer | [recipes/marquee.ts](recipes/marquee.ts) |
-| A row that scrolls sideways, with arrows that hide at its ends | [recipes/scroll-a-row.ts](recipes/scroll-a-row.ts) |
-| A link built from a row: WhatsApp with the product's name, `mailto:` | [recipes/link-with-data.ts](recipes/link-with-data.ts) |
-| React to a click or a submit; a modal; a switch | [recipes/forms-and-modals.ts](recipes/forms-and-modals.ts) |
-| A feature behind a flag | [recipes/feature-flag.ts](recipes/feature-flag.ts) |
-| An element of your own (a plugin), checked | [recipes/plugin.ts](recipes/plugin.ts) |
-| Controls a screen reader and a browser agent can use | [recipes/usable-without-sight.ts](recipes/usable-without-sight.ts) |
-| Tokens, a shared class, "the class plus one thing", tablet and phone at once | [recipes/style-a-page.ts](recipes/style-a-page.ts) |
-| A design in Tailwind classes, kept as classes the builder edits | [recipes/from-tailwind.ts](recipes/from-tailwind.ts) |
-| A page from elsewhere in a frame (`embed`: a map, a player) and a drawing of your own (`svg`) | [recipes/embed-and-svg.ts](recipes/embed-and-svg.ts) |
+## What to read
 
-## References
+Start with [the cheatsheet](CHEATSHEET.md), then only what the task names:
 
-| Read | When |
+| The task | Read |
 | --- | --- |
-| [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
-| [colours-and-motion.md](reference/colours-and-motion.md) | Colours for both themes, tokens, keyframes, and motion that stays smooth (good practices) |
-| [tailwind.md](reference/tailwind.md) | A design written in Tailwind classes: `tw()`, its breakpoints and states, what it refuses |
-| [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
-| [efficiency.md](reference/efficiency.md) | The same page with fewer elements: the suggestions `authorSpace` makes, and the short way for each long one |
-| [components.md](reference/components.md) | One block placed many times — a card, a tier, a testimonial: props, slots, binding a row into one, why it is closed |
-| [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
-| [kept-state.md](reference/kept-state.md) | State that outlives a reload: `keepState`, transient and painted keys |
-| [auth.md](reference/auth.md) | Signing people in: providers, `authLogin`, `auth.*`, visitor roles |
-| [feature-flags.md](reference/feature-flags.md) | Switching a part of the space on or off — a beta, a rollout, the old version kept until the new one ships |
-| [lists.md](reference/lists.md) | Rendering rows, filtering and sorting them, a detail page for one record, carousels |
-| [typed-sources.md](reference/typed-sources.md) | Data typed by a sample of it: `source()`, typed rows, `twig` for templates |
-| [validation.md](reference/validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
-| [authoring-errors.md](reference/authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
-| [templates.md](reference/templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
-| [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, a loop that stops when unseen |
-| [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`, 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 |
-| [snippets-and-export.md](reference/snippets-and-export.md) | Publishing a snippet; turning an exported JSON — or a server action — into code |
-| [accessibility.md](reference/accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
-| [review-checklist.md](reference/review-checklist.md) | Before you say it is done |
-
-**What to read for a kind of task** — the cheatsheet, then only these:
-
-- A site — landing, catalogue, blog: elements-and-styles, layouts, components, lists.
-- An app with state and actions: data-and-visibility, templates, flows — realtime when pages see each other.
-- A component of your own: plugins.
-- A refusal or a warning: search authoring-errors.md for its code — never read it whole.
-- Tests: testing.
-
-Nothing else needs reading up front.
+| A site — landing, catalogue, blog | [elements-and-styles](reference/elements-and-styles.md), [layouts](reference/layouts.md), [components](reference/components.md), [lists](reference/lists.md) |
+| An app with state and actions | [data-and-visibility](reference/data-and-visibility.md), [templates](reference/templates.md), [flows](reference/flows.md) |
+| A component of your own | [plugins](reference/plugins.md) |
+| A whole working file to copy | [recipes](reference/recipes.md) |
+| A refusal or a warning | `npx plitzi explain <code>` |
+| Tests | [testing](reference/testing.md) |
+| Anything else | [the index](reference/index.md): every reference, and when |

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

@@ -1,7 +1,8 @@
 /* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
 /**
  * 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.
+ * address names — with a message, not an empty page, when no product has that name, and status 404: the provider is
+ * resolved on the server, and `notFound` says when its answer holds nothing for this address.
  */
 import { apiContainer, heading, link, list, text, listItem } from '@plitzi/sdk-authoring';
 
@@ -48,7 +49,8 @@ export const recipe: SpaceSpec = {
         apiContainer({
           id: 'catalog-one',
           query: '/data/products.json',
-          cache: true,
+          runtime: 'server',
+          notFound: "{{ not (source.data.products|find('slug', navigation.routeParams.slug)) }}",
           children: [
             list({
               id: 'this-product',

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

@@ -1,5 +1,5 @@
 /**
- * An element of your own (a plugin): authored from its declaration — the one `plitzi add plugin` writes — so a flow on
+ * An element of your own (a plugin): authored from its declaration — the one `plitzi plugin add` writes — so a flow on
  * its events, a step to its actions and its attributes are all checked. Hand the declaration to `authorSpace` too.
  */
 import {

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

@@ -38,6 +38,8 @@ image({ src: '/grain.png', decorative: true })                      // an orname
 image({ decorative: true, bind: { src: 'post.record.cover' } })     // a cover under its own headline adds nothing
 image({ bind: { src: 'row.item.cover', alt: 'row.item.title' } })   // …unless it is alone in a link: then it names it
 fontAwesome({ icon: 'fa-solid fa-triangle-exclamation', label: 'Overdue' })  // an icon that says something alone
+text('福', { decorative: true })                                     // a seal or a mark drawn for the look alone
+list({ label: 'Kinds of capsule', … })                               // a group of options is named, as a group
 ```
 
 ## Clicks go on controls
@@ -111,5 +113,4 @@ can't click something that only appears on focus.
 - `authorSpace` warnings: zero, as always.
 - In a test, `page.getByRole('button', { name: 'Close' })` fails when the name is missing.
   `expect(locator).toMatchAriaSnapshot(…)` pins the whole outline.
-- Through MCP, `plitzi_screenshot` with `view: "accessibility"` returns the page's tree and lists everything that has
-  no name.
+- Through MCP, `plitzi_look` returns the page's tree (its default view) and lists everything that has no name.

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

@@ -101,6 +101,8 @@ The space is not written until these are fixed.
 | `motion-invalid` | a `motion` with a preset, a trigger or a timing the page cannot play | `motion: { enter: 'fade-up', on: 'view' }` — the message lists the presets |
 | `motion-no-tag` | a `motion` on an element with no tag of its own — nothing to move | the motion on what it wraps, or a `subType` on it |
 | `no-pages` | a space with no pages | `pages: [{ id: 'home', name: 'Home', slug: '', body: [] }]` |
+| `not-found-in-browser` | `notFound` on a provider asked from the browser — its answer arrives after the page was sent with its status | `runtime: 'server'` on the provider, or `visible` on the page's "not found" part instead |
+| `not-found-not-a-template` | `notFound` that is not one `{{ expression }}` against the answer — never `true`, so never a 404 | `notFound: '{{ source.found == false }}'` |
 | `notifications-shape` | `notifications` with a field it does not have, or a value that is not one CSS value | the field it suggests, or one it lists; one CSS value, like 'var(--card)', '12px' or '500' |
 | `outside-ancestor` | an element that reads the state of an element it is not inside | nest it in the element the message names |
 | `page-access-level` | an `accessLevel` that is not one the router reads | one of the values the message lists |
@@ -112,6 +114,7 @@ The space is not written until these are fixed.
 | `part-missing` | a compound element — a carousel, a tab container, a dropdown — without a part it renders through | the part the message names, inside it (`carousel()` writes its own track) |
 | `prop-missing` | an instance without a prop its component requires | `component('card', { props: { name: … } })`, or bind it |
 | `prop-name` | a prop whose name a template cannot read as `props.x` | letters, digits and `_` |
+| `prop-type-unknown` | a prop declared with a type no editor offers and nothing checks a value against | one of text, textarea, select, boolean, number, scalar, json, elementIds — words are `text` |
 | `prop-unknown` | a prop the component does not declare, handed in or read | the prop it suggests, or declare it: `props: { name: { type: 'text' } }` |
 | `prop-value` | a prop handed in with a value its declaration does not take | a value of the declared type, or one of its options |
 | `props-outside-component` | `props.x` read outside a component | read the source it would have come from |
@@ -228,6 +231,7 @@ Nothing is wrong: the page renders as written. Each is a shorter way to the same
 | `custom-css-slot` | a part of a built-in element dressed in `customCss` by the SDK's markup — a form control's `<input>`, a pager's buttons, a heading inside a markdown | a class on the slot of that part — `slots: { field: input }`, `elements.<type>.slots` — with its states |
 | `heavy-animation` | keyframes animating what the browser repaints or lays out again on every frame — a size, a position, a blur, a shadow, or a colour in a loop — which stutters whenever the page is busy, most of all while it loads | `opacity` and `transform`: a size or a position is `translate`/`scale`, a blur or a shadow is the `opacity` of a layer carrying it; a loop that must animate anything else starts `paused` and runs under `[data-hydrated]` |
 | `literal-colour` | a colour written out in a class where the space has a token of that value — it stays put in the dark scheme | `var(--token)` when it should follow the scheme; a token of one value of its own when it must stay the same in both |
+| `not-found-page` | a space with no page of its own for an address no other page answers — a plain one was added, in the home page’s layout, sent with status 404 | a page whose slug is `'*'`: `{ id: 'not-found', name: 'Not found', slug: '*', layout: …, body: [...] }` |
 | `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 |

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

@@ -17,7 +17,7 @@ It sizes the canvas to the device (at most 2× — `maxPixelRatio`), follows its
 can see it move: on a live page (in the builder it draws one still frame), for a visitor who did not ask for less
 motion, with the tab in front and the canvas on screen; `paused` holds it (bind it to a hover). A shader that does not
 compile — GLSL ES 1.0 wants `196.0`, not `196` — throws a `ShaderError` with the driver's log, printed as
-`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi check` lists it under the console) and `error` says it;
+`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi page check` lists it under the console) and `error` says it;
 show the still image meanwhile, as above. `useAnimationFrame(onFrame, { target })` is the same loop for motion that
 is not a canvas.
 

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

@@ -21,8 +21,8 @@ source — `when({ field: 'flags.newCheckout', operator: '=', value: true }, …
 same flags, decided on the server. Use the step builders — they fill in where a step runs and what it takes:
 
 - **Where it runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an element
-  callback under an element's id, a utility under nothing. Naming either half wrong is a control that does nothing,
-  with no error — which is why the builders exist.
+  callback under an element's id, a utility under nothing. Either half named wrong is a control that silently does
+  nothing.
 - **Which `setState`.** `setState({ key })` writes `runtime.state.<key>` and is read as `state.<key>`; never put
   `state.` in the key. `updateElement(…)` changes one element's own attribute or state.
 - **Flip in one step.** `toggleState({ key })` for app state, `toggleElement({ category: 'state', key: 'visibility' },
@@ -131,8 +131,8 @@ form({
 });
 ```
 
-A `formControl` is `required` by default: an optional field says `required: false`, or an empty one stops the submit
-without a word.
+A `formControl` is optional unless it says `required: true`, as an HTML field is. A required field that is empty stops
+the submit, and the browser says which.
 
 ## Notifications
 
@@ -144,6 +144,8 @@ without a word.
 The toast carries no class of the space's, so this — not a `.Toastify__*` rule in `customCss` — is where it is
 dressed.
 
+Copy link: `copyToClipboard('{{ navigation.href }}')`, then the toast — it fails with no clipboard.
+
 ## Modals, dropdowns, tabs
 
 - A modal or dialog is declared `visible: false` and driven with `openModal('credits')` / `closeModal('credits')`

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

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

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

@@ -124,6 +124,24 @@ pages: pageFamily(
 
 Every page is now its content and nothing else, and every page is guaranteed the same structure.
 
+## The page for an address nothing answers
+
+```ts
+{ id: 'not-found', name: 'Not found', slug: '*', layout: { id: 'site', slot: 'site-main' }, body: [ … ] }
+```
+
+- **`slug: '*'`** is the page of every address no other page answers — a mistyped link, a page taken down — sent with
+  status 404, in the layout you give it, so the visitor is still on the site with a way back. Its own address answers
+  404 too.
+- **One per folder, if a section wants its own.** In a folder (`folder: 'docs'`) it answers that folder's unknown
+  addresses; the deepest folder's wins, the space's takes the rest. A page whose `flag` is off shows it too.
+- **A space with none is given a plain one** — a title and a link home, in the home page's layout — and `author`
+  suggests writing your own (`not-found-page`): say it in the space's words.
+- **A page that exists but finds nothing** — `/products/:slug` for a slug no product has — is sent with 404 too when
+  its server provider says so: `notFound: "{{ not (source.data.products|find('slug', navigation.routeParams.slug)) }}"`,
+  one expression against its answer, on a `runtime: 'server'` provider of the page (not of its layout, which every
+  page shares). The page renders as written: show its "not found" part with `visible`.
+
 ## Styles follow the same rule
 
 - A role used on several pages is ONE class (`panelCard`, `pageTitle`), declared in the module that owns the area and

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

@@ -9,7 +9,7 @@ custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best
 
 ## Creating one
 
-The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli add plugin seat-picker` (a
+The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli plugin add seat-picker` (a
 package of its own and packing it: the CLI skill).
 
 One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
@@ -88,7 +88,7 @@ the widths the space's styles use, instead of a width of the plugin's own.
 
 ## Its own server code
 
-`plitzi add plugin board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
+`plitzi plugin add board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
 under `/fn/plugins/board/`; the component names them, with nothing for the space to wire:
 
 ```tsx

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

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