@plitzi/sdk-server 0.38.8 → 0.38.10

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # @plitzi/sdk-server
 
+## 0.38.10
+
+### Patch Changes
+
+- 200da2f: - **`focus-on-field-box`** (`@plitzi/sdk-authoring`): a warning for a `focus` or `focus-visible` state on a text
+  field's or a select's `input` slot. That slot is the box the field is drawn in, a `<div>` that never takes focus, so
+  the rule was never seen and a keyboard user tabbing to the field found no ring. The fix it names: `'focus-within'` on
+  the same class, or the state on the `field` slot.
+  - **`modalContainer` says how it is laid out** (`@plitzi/sdk-elements`): its description now names its slots and how
+    they sit — the dim layer and the dialog side by side, not one inside the other; the dialog centred by `top`/`left`
+    50% and a `translate`. A space styled the dim layer as a flex container to place the dialog, which moved nothing.
+  - **A field shows where the keyboard is** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`): a text field's or a select's
+    box is ringed (`2px solid currentColor`) while the field inside has keyboard focus, and a textarea while it has. No
+    text field or select showed any focus at all: the box had `outline: none`, and the field inherited it. One class of
+    specificity, so whatever a space writes about the outline wins; never in the builder's canvas, where the selection is
+    the ring. The field no longer inherits the box's outline — the box draws it.
+  - **The dim layer of a modal and a dialog is `rgb(0 0 0 / 50%)`** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`), not
+    black at `opacity: 0.5`: the default looks the same, and a colour a space gives the layer is drawn as it is — it was
+    halved. A space that set its own colour sees it darker: the one it wrote.
+  - **`required-message-unused`** (`@plitzi/sdk-authoring`): a warning for a `requiredMessage` on a field nothing requires —
+    since 0.38.9 a field is optional unless `required: true`, so the message is never shown and an empty answer is sent.
+    The formControl's description, the cheat sheet and the forms recipe say the default.
+  - **A page's title can say its record** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`,
+    `@plitzi/sdk-authoring`): `seoTitle` and `seoDescription` may be templates over the page's `runtime: 'server'`
+    providers (its layouts' too) and `navigation` — `'{{ apiContainer_post.title }} — Blog'`. The server evaluates them
+    as it writes the head, from the answers it already has; the browser evaluates the same over `rsc.data`, so the tab
+    follows a navigation from record to record. One that reads anything else — a browser provider, `state` — is refused
+    (`page-template`): it was written into the head as it was, braces included. A declaration's `serverTemplates` names
+    the attributes the page server evaluates against a context of its own (a page's title and description, a provider's
+    `notFound`): the element runtime leaves them as written — interpolated where the page renders, a `|default(…)`
+    resolved to its fallback before the head could read the providers — and the authoring lint reads the same list.
+  - **A page says when its address shows nothing** (`@plitzi/sdk-server`, `@plitzi/sdk-authoring`): `notFound` on the
+    page, one expression over the same answers its title reads — `"{{ not (apiContainer_feed.topics|find('slug',
+navigation.routeParams.slug)) }}"` — sends it with status 404, rendered as written. A provider's own `notFound` reads
+    only its answer, and one in a layout is every page's: a record read from the layout had no way to say it was not
+    there, and the page answered 200.
+  - **The Export keeps the flows of a plugin hosted by `custom`** (`@plitzi/sdk-authoring`): `specFromSpace` judged such
+    an element by `custom`'s own triggers and callbacks, and dropped a flow on the component's event (`onChange` on an
+    editor) as one "a custom never fires" — the space read back was not the space written.
+  - **`page check` reads every word on the page, in the colour the browser paints it** (`@plitzi/sdk-authoring`): what a
+    plugin draws inside an element of the space is measured too, named by the element and a selector; the measure is
+    WCAG's contrast (under 2:1 is unreadable), not "nearly the same colour"; and a colour the browser answers as
+    `oklch()`, `oklab()` or `color(srgb …)` — every token and every `color-mix()` — is read as that, where it was read as
+    `rgb()` numbers and came out near black. A plugin's dark-on-dark status line passed as "nothing wrong".
+  - **`verify` checks every theme the space can be painted in** (`@plitzi/cli`): light and dark, unless the space says
+    light only — "48 checks at 1440 and 390 px, light and dark". A page unreadable in the dark theme passed in the light
+    one; a failure names the theme it was found in.
+  - **`plitzi upgrade` says where fields became optional** (`@plitzi/cli`): for a project last upgraded before 0.38.9,
+    each `formControl(…)` with no `required`, at its file and line — said, never written. And a `.gitkeep` is asked for
+    only in a folder with nothing else in it: `upgrade` wrote one beside code, and `doctor` called it missing once deleted
+    as AGENTS.md asks ("nothing unused") — the three now say the same.
+  - **`devMode` and `devReload` are the project's** (`@plitzi/sdk-server`): `src/config/serverOptions.ts` may set them,
+    over `NODE_ENV`, which they still follow when left out. A deployment started without `NODE_ENV` (a container's `CMD`)
+    says `devMode: false`, and a public action answers with its output alone.
+  - **`page shot --from load`** (`@plitzi/cli`): `--frames` start as soon as the page's HTML is in, not once it settles —
+    an entrance that plays while the page loads had ended before the first picture.
+  - **`heavy-animation` says where each animation is** (`@plitzi/sdk-authoring`): the class and its variant, state or
+    slot — or the `customCss` rule — and writes the fix against that selector. It said "in `customCss`" for an animation
+    declared on a class's variant, and offered `.glow`, a class no space has.
+  - **`page shot --steps`** (`@plitzi/cli`): an interaction played step by step — `click`, `type`, `press`, `wait`,
+    `wait-for`, `shot [label]`, `frames <n> [ms]`, separated by `;` or written in a file (`@file`) — each picture labelled
+    with its step and the time since the first, and said when nothing changed since the one before. A queue filling, a
+    restart, an opening frame by frame took a Playwright script of the project's own. Targets take Playwright's selectors
+    too (`text=Saved`).
+  - **A space's task may take a `number` param** (`@plitzi/sdk-server`): saved functions refused it ("a type the builder
+    cannot draw") while a project's server ran it, so code that worked self-hosted failed on the platform — and the
+    builder draws one, a callback's. A step's params now arrive as the types the task declares, on every server: a
+    `number` written as text is the number, a `boolean` written `'true'` is `true`, as the browser reads a callback's.
+  - **`page shot --as <username>`** (`@plitzi/cli`): signs in first, as `page check --as` does, the password from
+    `PLITZI_CHECK_PASSWORD` in `.env`. A page for signed-in visitors was pictured as the sign-in page it sent the browser
+    to, without a word; `page shot` now says when the page sent it elsewhere, and that the picture is of that page.
+  - **A capture is of the page at rest** (`@plitzi/sdk-mcp`): the local screenshot client takes every picture with
+    `prefers-reduced-motion: reduce`, as the browser pod now does — the declared motion and a space's own keyframes that
+    honour the query are shown finished. A splash still covering its page, or an arrival caught halfway, was what a
+    thumbnail or a `plitzi_look` showed of a page that animates as it loads.
+  - **The server renders in the visitor's theme, not only the class** (`@plitzi/sdk-shared`): `ThemeProvider` set the
+    starting theme from a layout effect, which never runs on a server, so a page was drawn from the theme store's own
+    start — `{{ theme.resolved }}` was `light` under a `<html class="dark">`, and whatever named the scheme (a picture's
+    address, a `when` rule) was swapped for the other one as the page hydrated. The theme a host supplies (the cookie) is
+    now the server's snapshot of the store, and the hydration's; the shared store is never written on the server.
+- Updated dependencies [200da2f]
+  - @plitzi/plitzi-sdk@0.38.10
+  - @plitzi/sdk-shared@0.38.10
+
+## 0.38.9
+
+### Patch Changes
+
+- 64f4cd6: - **`unusedPort()`** (`@plitzi/sdk-server`): a port the system has just handed out, for a test to listen on. The
+  package's own tests and `@plitzi/sdk-mcp`'s listened on fixed ports in the ephemeral range (393xx), which any
+  outgoing connection of a test running beside them could take: CI failed with `EADDRINUSE` on runs with nothing
+  wrong. Every one now listens on a port the system gives it.
+  - **Brotli at quality 5** (`@plitzi/sdk-server`): `compression.brotliQuality`, for a page rendered for one request, is
+    5 (was 2). At 2 a 220 KB page came out larger than gzip — 36 KB against 31 — and at 5 it is 29 KB, for the CPU gzip
+    spends; on half a core ~0.1 ms a page.
+  - **`verify` checks the pages for signed-in visitors** (`@plitzi/cli`): a page that sends the browser to sign in is
+    checked again signed in as the account `.env` names — `PLITZI_CHECK_USER`, `PLITZI_CHECK_PASSWORD` (the environment
+    wins over `.env`). With none named, `verify` says how. `page check --as` reads the password from `.env` too, and
+    `page check` takes several pages, in one browser.
+  - **An address that shows nothing answers 404** (`@plitzi/sdk-shared`, `@plitzi/plitzi-sdk`, `@plitzi/sdk-server`):
+    one no page answers was sent to the home page with a 302 — every typo read as the home page. A page whose slug is
+    `'*'` is now the space's page for it, sent with status 404 (a folder may have its own; the deepest wins), and a page
+    gated off by a flag shows it too. Never kept in the page cache: an address asked for at random filled it. Only a slug
+    that IS `'*'`: a page answering a subtree by its own (`spaces/:spaceId/update/*`) stays a page like any other.
+  - **`authorSpace` gives a space with no `'*'` page a plain one** (`@plitzi/sdk-authoring`), in the home page's layout,
+    and says so: suggestion `not-found-page`. The project templates carry their own.
+  - **`notFound` on a server provider** (`@plitzi/sdk-elements`, `@plitzi/sdk-server`): an expression against its answer
+    (`{{ source.found == false }}`); when it is true the page is sent with status 404, rendered as written. Refused on a
+    browser provider (`not-found-in-browser`) and when it is not one expression (`not-found-not-a-template`).
+  - **`page check` and `verify` know a page sent with 404** (`@plitzi/cli`): it is said, not failed; the space's `'*'`
+    page is checked at an address no page has, and fails if it is not sent with 404.
+  - **A form field draws no background of its own** (`@plitzi/sdk-elements`): the `<input>` inside a form control's box
+    (`field`) took `background-color: inherit`, and painted a translucent box colour a second time — a darker box inside
+    the padding (Tremor's search). It is `transparent`: the box shows through it.
+  - **`space lint` offers `quiet` only where there is an element to put it on** (`@plitzi/cli`): a suggestion about what
+    the space lacks — `not-found-page` — is answered by writing it.
+  - **`feedback --previous`** (`@plitzi/cli`): the brief says what to do when an earlier report's link no longer opens —
+    say so, and ask the person for the highest id it had.
+  - **`start:prod` runs in production by itself** (`@plitzi/cli`): `NODE_ENV=production node …`. Without the variable a
+    deployed project was a development server — dev tools on, and every public action answering its `steps` and `trace`
+    (each step's result, what the `output` was meant to leave out). `doctor` says a `start:prod` that does not
+    (`start-prod-not-production`); `plitzi upgrade --write` rewrites the script.
+  - **A project's `ActionRefusal` reaches the flow** (`@plitzi/sdk-server`): a functions bundle carries its own copy of the
+    class, so `instanceof` never knew it and the run lost its reason (`{{ x.error }}` empty). Told apart by name now.
+  - **Plugins are not remounted after hydration** (`@plitzi/sdk-elements`): the registry wrapped each plugin again when
+    the host handed it over again, a new component type every time — the server's HTML thrown away, entrances replayed,
+    effects run twice. Each plugin component is wrapped once.
+  - **`start:dev` survives a space that does not author** (`@plitzi/sdk-server`): a restart while the space had an error
+    died, and fixing the space woke nothing. It comes up answering every page with what is wrong (503), and loads the
+    space the first time a save authors.
+  - **`page check` sees what is cut off at the screen's edge** (`@plitzi/sdk-authoring`, `@plitzi/cli`): a link or words an
+    ancestor hides past the viewport, which no sideways scroll shows (`cut-off`).
+  - **`page shot --click <element...> --sheet`** (`@plitzi/cli`): elements clicked in order — a name or a CSS selector,
+    inside a plugin too — pictured after each (`--frames`/`--every`), with how much changed, and every picture on one
+    contact sheet. The dev tools' badge is no longer in a picture: its shadow root is marked (`@plitzi/sdk-dev-tools`).
+  - **`formControl` is optional unless it says `required: true`** (`@plitzi/sdk-elements`), as an HTML field is. A field
+    left without `required` in an older space was required, and is not now.
+  - **`text({ decorative })`, `list({ label })`** (`@plitzi/sdk-elements`); **`writing-mode`, `text-orientation`** in the
+    CSS vocabulary (`@plitzi/sdk-shared`).
+  - **`unused-token` reads the plugins' stylesheets** (`@plitzi/sdk-authoring`): `authorSpace`'s `stylesheets`, which
+    `projectAuthoring` fills with every `.css` under `src/plugins/` — a token only a plugin used was said to be unused.
+  - **`id-taken` on a provider placed on two pages points at the layout they share** (`@plitzi/sdk-authoring`), not at
+    `scope()`, which renamed its source and every template reading it.
+  - **The welcome template's tokens keep their names** (`@plitzi/sdk-authoring`): `satisfies`, not an annotation, so
+    `tokens(variables).card` typechecks as the cheatsheet teaches.
+- Updated dependencies [64f4cd6]
+  - @plitzi/sdk-shared@0.38.9
+  - @plitzi/plitzi-sdk@0.38.9
+
 ## 0.38.8
 
 ### Patch Changes

package/README.md

@@ -400,6 +400,11 @@ Beside the page adapters it offers `getSchema` and `getStyle`, read from the sam
 path, or a function that may answer one — `saveSchema` and `saveStyle`, each writing its document back into the file. So an MCP server
 ([`@plitzi/sdk-mcp`](../mcp/README.md#adapters)) can run over it, with a `getGrant` of yours beside it.
 
+In a test, listen on `await unusedPort()`: a port the system has just handed out, never a fixed number — one in the
+system's ephemeral range can be taken by any outgoing connection of a test running beside it, and the listen fails with
+`EADDRINUSE` on a run with nothing wrong. (`freePort(8080)` is the development server's: the next free one from a port
+people expect.)
+
 ### `JsonAdaptersConfig`
 
 | Option | Type | Description |
@@ -573,7 +578,7 @@ createServer({ compression: false, adapters });
 |---|---|---|---|
 | `encodings` | `('br' \| 'gzip')[]` | `['br', 'gzip']` | What this server offers, most preferred first; the first one the client accepts wins. `[]` disables compression. |
 | `threshold` | `number` | `1024` | Responses smaller than this many bytes go out uncompressed. |
-| `brotliQuality` | `number` | `2` | Brotli quality, 0–11, for a body compressed on every request (a page rendered for that request alone). Measured on a quarter core, 4 cost a tenth of the pages a second to save half a kilobyte each. |
+| `brotliQuality` | `number` | `5` | Brotli quality, 0–11, for a body compressed on every request (a page rendered for that request alone). The first quality under gzip's size for the CPU gzip spends: at 2 a 220 KB page came out larger than gzip (36 KB against 31; 29 at 5). On half a core it costs ~0.1 ms a page — 5–8% of the pages a second of a 6 KB page. |
 | `keptBrotliQuality` | `number` | `6` | Brotli quality for a body compressed once and kept: a cached page, a static file such as the SDK bundle. Paid once; the bundle comes out 10% smaller than at 4, for the same memory. 9 needs ~40 MB more to compress the bundle, which a 128 MB server does not have. |
 | `gzipLevel` | `number` | `6` | Gzip level, 0–9. |
 

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

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

package/dist/core/oauth/consentPage.js

@@ -1,13 +1,5 @@
+import { escapeHtml } from "../../helpers/escapeHtml.js";
 //#region src/core/oauth/consentPage.ts
-var escapeHtml = (value) => value.replace(/[&<>"']/gu, (character) => {
-	switch (character) {
-		case "&": return "&amp;";
-		case "<": return "&lt;";
-		case ">": return "&gt;";
-		case "\"": return "&quot;";
-		default: return "&#39;";
-	}
-});
 var STYLES = `
   :root { color-scheme: light dark; --bg: #f6f7f9; --panel: #ffffff; --ink: #16181d; --muted: #6b7280;
     --line: #e2e5ea; --accent: #2563eb; --danger: #b91c1c; }

package/dist/core/unusedPort.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A port the system has just handed out and nobody holds — what a test listens on. Never a fixed number: one in the
+ * system's ephemeral range (above 32768 on Linux) can be taken by any outgoing connection of a test running beside it,
+ * and the listen fails with `EADDRINUSE` on a run that has nothing wrong with it.
+ */
+export declare const unusedPort: (host?: string) => Promise<number>;

package/dist/core/unusedPort.js

@@ -0,0 +1,20 @@
+import { createServer } from "node:net";
+//#region src/core/unusedPort.ts
+/**
+* A port the system has just handed out and nobody holds — what a test listens on. Never a fixed number: one in the
+* system's ephemeral range (above 32768 on Linux) can be taken by any outgoing connection of a test running beside it,
+* and the listen fails with `EADDRINUSE` on a run that has nothing wrong with it.
+*/
+var unusedPort = (host = "127.0.0.1") => new Promise((resolve, reject) => {
+	const probe = createServer();
+	probe.once("error", reject);
+	probe.listen(0, host, () => {
+		const address = probe.address();
+		probe.close(() => {
+			if (typeof address === "object" && address) resolve(address.port);
+			else reject(/* @__PURE__ */ new Error(`The system gave no port on ${host}`));
+		});
+	});
+});
+//#endregion
+export { unusedPort };

package/dist/helpers/compress.js

@@ -4,7 +4,7 @@ import { brotliCompressSync, constants, gzipSync } from "node:zlib";
 var DEFAULT_COMPRESSION = {
 	encodings: ["br", "gzip"],
 	threshold: 1024,
-	brotliQuality: 2,
+	brotliQuality: 5,
 	keptBrotliQuality: 6,
 	gzipLevel: 6
 };

package/dist/helpers/escapeHtml.d.ts

@@ -0,0 +1,2 @@
+/** Text set inside HTML as text: never markup, whatever it holds. */
+export declare const escapeHtml: (value: string) => string;

package/dist/helpers/escapeHtml.js

@@ -0,0 +1,13 @@
+//#region src/helpers/escapeHtml.ts
+/** Text set inside HTML as text: never markup, whatever it holds. */
+var escapeHtml = (value) => value.replace(/[&<>"']/gu, (character) => {
+	switch (character) {
+		case "&": return "&amp;";
+		case "<": return "&lt;";
+		case ">": return "&gt;";
+		case "\"": return "&quot;";
+		default: return "&#39;";
+	}
+});
+//#endregion
+export { escapeHtml };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { createServer, resolveServices } from './core/createServer';
 export { closeOnSignals } from './core/server/closeOnSignals';
 export { loadFunctions, loadFunctionsSource, readFunctionsDir } from './modules/functions/load';
 export { freePort } from './core/freePort';
+export { unusedPort } from './core/unusedPort';
 export { registerHealthCheck, buildHealthPayload } from './core/health';
 export { consoleLogger, isLogged, logLevelOf, renderLogEvent, serverLog } from './helpers/serverLog';
 export type { HealthCheckApp, HealthIdentity } from './core/health';

package/dist/index.js

@@ -11,6 +11,7 @@ import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { createServer } from "./core/createServer.js";
 import { closeOnSignals } from "./core/server/closeOnSignals.js";
 import { freePort } from "./core/freePort.js";
+import { unusedPort } from "./core/unusedPort.js";
 import { createCloudAdapters } from "./adapters/cloudAdapters.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
 import { createAuthAdapters } from "./adapters/authAdapters.js";
@@ -19,4 +20,4 @@ import { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildc
 import { createSpaceAdapters } from "./adapters/space/index.js";
 import { createLocalFontStore, hostedPathsOf } from "./core/fontStore.js";
 import { createRedisPubSub } from "./modules/realtime/redisPubSub.js";
-export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, freePort, hostedPathsOf, isLogged, loadFunctions, loadFunctionsSource, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };
+export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createMemoryPubSub, createRedisPubSub, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, freePort, hostedPathsOf, isLogged, loadFunctions, loadFunctionsSource, logLevelOf, presentsCredential, readFunctionsDir, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, serverLog, takeDraftOverride, unusedPort, verifiedDomain, wildcardSubdomain, writeConnectorRecord };

package/dist/modules/actions/runtime/errors.d.ts

@@ -26,3 +26,9 @@ export declare class ActionRunError extends Error {
 export declare class ActionRefusal extends Error {
     constructor(message: string);
 }
+/**
+ * Whether an error is a refusal — told apart by its NAME, never by `instanceof`: a functions bundle carries its own copy
+ * of the class (`functions/build.ts`), so a project's code loaded from one throws a refusal this class never made, and
+ * its reason was dropped on the way to the page.
+ */
+export declare const isActionRefusal: (error: unknown) => error is Error;

package/dist/modules/actions/runtime/errors.js

@@ -33,5 +33,11 @@ var ActionRefusal = class extends Error {
 		this.name = "ActionRefusal";
 	}
 };
+/**
+* Whether an error is a refusal — told apart by its NAME, never by `instanceof`: a functions bundle carries its own copy
+* of the class (`functions/build.ts`), so a project's code loaded from one throws a refusal this class never made, and
+* its reason was dropped on the way to the page.
+*/
+var isActionRefusal = (error) => error instanceof Error && error.name === "ActionRefusal";
 //#endregion
-export { ActionRefusal, ActionRunError };
+export { ActionRefusal, ActionRunError, isActionRefusal };

package/dist/modules/actions/runtime/runAction.js

@@ -1,5 +1,5 @@
 import { serverLog } from "../../../helpers/serverLog.js";
-import { ActionRefusal, ActionRunError } from "./errors.js";
+import { ActionRunError, isActionRefusal } from "./errors.js";
 import { runCancelKey } from "./guards.js";
 import { createKvStore } from "./kvStore.js";
 import { resolveLimits } from "./limits.js";
@@ -148,8 +148,22 @@ var stepOf = (node, { status, phase, startTime, endTime, error, logs = [] }) =>
 /** What one step may log: enough to debug with, bounded so a loop that logs cannot fill a run's record. */
 var MAX_LOG_LINES = 100;
 var MAX_LOG_LINE = 1e3;
+/**
+* A value written as text, read as the type its task declares: a `number` param written `5` — or bound to text that says
+* it — arrives as 5, a `boolean` one written `'true'` as `true`, an empty number as nothing (so the default applies). The
+* browser reads a callback's params the same way (`coerceDeclaredParams`): a task's author never writes `Number(…)`.
+*/
+var asDeclared = (type, value) => {
+	if (typeof value !== "string") return value;
+	if (type === "number") {
+		const parsed = Number(value.trim());
+		return value.trim() === "" ? void 0 : Number.isFinite(parsed) ? parsed : value;
+	}
+	return type === "boolean" && (value === "true" || value === "false") ? value === "true" : value;
+};
 var withDefaults = (task, params) => Object.entries(task.params).reduce((acum, [key, param]) => {
-	if (acum[key] === void 0 || acum[key] === "") acum[key] = param.defaultValue ?? "";
+	const value = asDeclared(typeof param.type === "function" ? param.type(acum) : param.type, acum[key]);
+	acum[key] = value === void 0 || value === "" ? param.defaultValue ?? "" : value;
 	return acum;
 }, { ...params });
 var runNode = async (node, scope, registry, buildContext) => {
@@ -464,7 +478,7 @@ var createActionRunner = (config, registryFor, baseFetch = fetch) => {
 				});
 			} else {
 				failure = error instanceof Error ? error.message : String(error);
-				if (error instanceof ActionRefusal) refusal = redact(error.message);
+				if (isActionRefusal(error)) refusal = redact(error.message);
 				trace.push({
 					node: errorNode("error"),
 					status: "failed",

package/dist/modules/functions/manifest.js

@@ -57,6 +57,11 @@ var paramOf = (value) => {
 			type: value.type,
 			...typeof defaultValue === "string" || typeof defaultValue === "number" ? { defaultValue } : {}
 		};
+		case "number": return {
+			...base,
+			type: "number",
+			...typeof defaultValue === "number" ? { defaultValue } : {}
+		};
 		case "codemirror-text":
 		case "codemirror-json": return {
 			...base,
@@ -84,7 +89,7 @@ var paramOf = (value) => {
 				...typeof defaultValue === "string" ? { defaultValue } : {}
 			};
 		}
-		default: return `has a type the builder cannot draw ("${String(value.type)}"): text, textarea, codemirror-text, codemirror-json, boolean, elements or select`;
+		default: return `has a type the builder cannot draw ("${String(value.type)}"): text, number, textarea, codemirror-text, codemirror-json, boolean, elements or select`;
 	}
 };
 /** What each asked limit is, in words a problem is written in. */

package/dist/modules/functions/routes.js

@@ -1,5 +1,5 @@
 import { serverLog } from "../../helpers/serverLog.js";
-import { ActionRefusal } from "../actions/runtime/errors.js";
+import { isActionRefusal } from "../actions/runtime/errors.js";
 import { pluginOfPath } from "./scope.js";
 import { functionContextFor } from "./context.js";
 import { functionLimitsFor } from "./config.js";
@@ -69,7 +69,7 @@ var withoutCookies = (response) => {
 * of anything else the visitor gets that it failed, and the server's log gets why.
 */
 var failed = (visit, key, error) => {
-	if (error instanceof ActionRefusal || error instanceof FunctionFailure && error.reason === "refused") return Response.json({ error: error.message }, { status: 400 });
+	if (isActionRefusal(error) || error instanceof FunctionFailure && error.reason === "refused") return Response.json({ error: error.message }, { status: 400 });
 	serverLog.error("Functions", `route ${key} of space ${String(visit.spaceId)} failed`, error);
 	const stopped = error instanceof FunctionFailure && error.reason !== "error";
 	return Response.json({ error: stopped ? "This route ran out of what it may spend" : "This route failed" }, { status: stopped ? 503 : 500 });

package/dist/modules/project/serveProject.d.ts

@@ -3,11 +3,14 @@ import { ServerConfig } from '../../core/createServer';
 import { ConnectorManifest } from '../connectors';
 import { ActionEntry, SSRServer } from '@plitzi/sdk-shared';
 /** What `serveProject` sets itself, from the project's layout — so never the project's options'. */
-type SetByProject = 'port' | 'devMode' | 'devReload' | 'health' | 'adapters' | 'plugins' | 'publicDir' | 'dataDir' | 'functions' | 'action';
+type SetByProject = 'port' | 'health' | 'adapters' | 'plugins' | 'publicDir' | 'dataDir' | 'functions' | 'action';
 /**
  * What a project's server does besides serving its space — its `src/config/serverOptions.ts`: what `createServer`
  * takes, but for what `serveProject` wires from the project's layout, and an action's `lookups`, which are the
- * project's `src/actions/`. `logLevel` and `logger` are the project's to change; `action.kv` too.
+ * project's `src/actions/`. `logLevel` and `logger` are the project's to change; `action.kv` too. So are `devMode` and
+ * `devReload`, which follow `NODE_ENV` when left out — on unless it is `production`. A deployment started without it (a
+ * container's `CMD`, a process manager with no environment) says `devMode: false` here, and a public action answers
+ * with its output alone, never the trace of every step.
  */
 export type ProjectServerOptions = Partial<Omit<ServerConfig, SetByProject>> & {
     action?: Omit<NonNullable<ServerConfig['action']>, 'lookups'>;

package/dist/modules/project/serveProject.js

@@ -10,12 +10,15 @@ import { createFileKv } from "../actions/runtime/fileKv.js";
 import { loadRuntime, loadRuntimeModule } from "../runtime/bundle.js";
 import { serveRuntime } from "../runtime/stages.js";
 import { projectPlugins, watchProjectPlugins } from "./plugins.js";
+import { createSpaceFailure } from "./spaceFailure.js";
 import { watchSpace } from "./watchSpace.js";
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { assertProjectLayout, layoutFindingText } from "@plitzi/sdk-shared/project/layout";
 import { DATA_DIR, DEV_SERVER_FILE, FUNCTIONS_DIR, KV_FILE, PROJECT_TMP, PUBLIC_DIR, RUNTIME_BUNDLE, RUNTIME_ENTRY } from "@plitzi/sdk-shared/project/paths";
 import { projectModule, projectRoot } from "@plitzi/sdk-shared/project/root";
+import { EMPTY_SCHEMA } from "@plitzi/sdk-shared/schema/schemaConstants";
+import { EMPTY_STYLE_SCHEMA } from "@plitzi/sdk-shared/style/styleConstants";
 //#region src/modules/project/serveProject.ts
 /**
 * The errors whose message is the whole report — every problem, where it is and what to write instead — and whose
@@ -63,14 +66,32 @@ var actionLookups = (actions, connectors) => ({
 	getConnector: (_spaceId, connectorId) => Promise.resolve(connectors.get(connectorId)),
 	listScheduledSpaces: () => Promise.resolve([SPACE_ID])
 });
-/** The space this project serves, authored from its own source — or Plitzi's, named for `/health`. */
-var spaceToServe = async ({ space, cloud }) => {
+/**
+* The space this project serves, authored from its own source — or Plitzi's, named for `/health`.
+*
+* While developing, one that does not author is not the end of the server: it comes up saying why (`spaceFailure`),
+* named after the project's folder, and serves the space the first time a save authors. A deployment refuses to start.
+*/
+var spaceToServe = async ({ space, cloud }, developing, root) => {
 	if (!space) return { name: cloud.name };
-	const authored = await space();
-	return {
-		space: authored,
-		name: authored.schema.definition.permanentUrl
-	};
+	try {
+		const authored = await space();
+		return {
+			space: authored,
+			name: authored.schema.definition.permanentUrl
+		};
+	} catch (error) {
+		if (!developing) throw error;
+		return {
+			failure: isReport(error) ? error.message : error instanceof Error ? error.stack ?? error.message : String(error),
+			name: path.basename(root)
+		};
+	}
+};
+/** What is served of a space that has not authored yet: nothing — every page answers with why (`spaceFailure`). */
+var NOTHING_AUTHORED = {
+	schema: EMPTY_SCHEMA.schema,
+	style: EMPTY_STYLE_SCHEMA
 };
 var startProject = async (options) => {
 	const { actions, connectors = /* @__PURE__ */ new Map(), serverOptions = {} } = options;
@@ -85,16 +106,22 @@ var startProject = async (options) => {
 	const port = process.env.PORT ? Number(process.env.PORT) : developing ? await freePort(8080, host) : 8080;
 	/** Where people reach this server: `PUBLIC_URL` behind a proxy, its own address otherwise. */
 	const publicUrl = (process.env.PUBLIC_URL ?? `http://127.0.0.1:${String(port)}`).replace(/\/+$/, "");
-	const { space, name } = await spaceToServe(options);
+	const { space, failure, name } = await spaceToServe(options, developing, root);
 	const plugins = await projectPlugins(root);
-	const held = space && { documents: {
+	const held = options.space ? { ...space ? { documents: {
 		schema: space.schema,
 		style: space.style
-	} };
+	} } : {} } : void 0;
+	const spaceFailure = createSpaceFailure();
+	if (failure !== void 0) {
+		spaceFailure.fail(failure);
+		console.error(`[author] ${failure}`);
+		console.error("[author] The server is up: fix the space and save, and the page loads it.");
+	}
 	const speaks = !isFleetWorker();
 	for (const warning of speaks ? space?.warnings ?? [] : []) console.warn(`[author] ${warning.message}`);
 	const adapters = held ? createJsonAdapters({
-		offlineData: () => held.documents,
+		offlineData: () => held.documents ?? NOTHING_AUTHORED,
 		deployment: {
 			spaceId: SPACE_ID,
 			environment: "main",
@@ -115,8 +142,8 @@ var startProject = async (options) => {
 		logger: consoleLogger,
 		...serverOptions,
 		port,
-		devMode: developing,
-		devReload: developing,
+		devMode: serverOptions.devMode ?? developing,
+		devReload: serverOptions.devReload ?? serverOptions.devMode ?? developing,
 		health: { name },
 		adapters,
 		plugins: plugins.sources,
@@ -132,7 +159,7 @@ var startProject = async (options) => {
 			...serverOptions.action,
 			...actions ? { lookups: actionLookups(actions, connectors) } : {}
 		}
-	}, { preAuth: runtime ? [runtime.stage] : [] });
+	}, { preAuth: [spaceFailure.stage, ...runtime ? [runtime.stage] : []] });
 	server.listen(port, host);
 	const url = `http://127.0.0.1:${String(port)}`;
 	if (speaks) {
@@ -146,6 +173,7 @@ var startProject = async (options) => {
 	}
 	const watching = developing ? [...held ? [watchSpace(root, (authored) => {
 		held.documents = authored;
+		spaceFailure.clear();
 		server.reloadPages();
 	})] : [], watchProjectPlugins(root, server, plugins)] : [];
 	const close = async () => {

package/dist/modules/project/spaceFailure.d.ts

@@ -0,0 +1,8 @@
+import { Stage } from '../../core/http/types';
+export declare const createSpaceFailure: () => {
+    stage: Stage;
+    /** The space did not author: every page says why, until it does. */
+    fail: (message: string) => void;
+    /** It authored: the pages are the space's again. */
+    clear: () => void;
+};

package/dist/modules/project/spaceFailure.js

@@ -0,0 +1,76 @@
+import { DEV_RELOAD_PATH } from "../../core/http/stages/devReload.js";
+import { escapeHtml } from "../../helpers/escapeHtml.js";
+//#region src/modules/project/spaceFailure.ts
+/**
+* The page a project's server answers with while its space does not author — while developing only.
+*
+* A `start:dev` that restarted on a save to the server's code (`src/functions/`, `src/config/`…) while the space had an
+* error of its own died on it: Node then waits for a change to the server's code, never to `src/space/`, so fixing the
+* space woke nothing and the page was gone with no word in the browser. Up instead, it answers every page with what is
+* wrong, and loads again the moment a save authors — the same reload a page showing the space waits for — or when the
+* server it reached restarts.
+*/
+var pageOf = (message) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>The space does not author</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; padding: 48px 24px; font: 15px/1.5 ui-sans-serif, system-ui, sans-serif; }
+  main { max-width: 860px; margin: 0 auto; display: flex; flex-direction: column; gap: 12px; }
+  pre { margin: 0; padding: 16px; border-radius: 8px; background: color-mix(in srgb, currentColor 8%, transparent);
+    white-space: pre-wrap; overflow-wrap: anywhere; font: 13px/1.5 ui-monospace, monospace; }
+</style>
+</head>
+<body>
+<main>
+<h1>The space does not author</h1>
+<p>Fix it and save: this page loads again the moment it authors. The server is still running.</p>
+<pre>${escapeHtml(message)}</pre>
+</main>
+<script>
+  (() => {
+    let boot;
+    const events = new EventSource(${JSON.stringify(DEV_RELOAD_PATH)});
+    events.addEventListener('reload', () => location.reload());
+    events.addEventListener('hello', event => {
+      const next = JSON.parse(event.data).boot;
+      if (boot !== undefined && next !== boot) {
+        location.reload();
+      }
+
+      boot = next;
+    });
+  })();
+<\/script>
+</body>
+</html>
+`;
+/** A request for a page, as a browser asks for one — not for the server's data, its assets or its reload stream. */
+var asksForPage = (method, accept) => method === "GET" && [accept].flat().some((value) => value?.includes("text/html"));
+var createSpaceFailure = () => {
+	let failure;
+	const stage = (ctx) => {
+		if (failure === void 0 || !asksForPage(ctx.req.method, ctx.req.headers.accept)) return Promise.resolve(false);
+		ctx.res.setStatus(503);
+		ctx.res.setHeader("Content-Type", "text/html; charset=utf-8");
+		ctx.res.setHeader("Cache-Control", "no-store");
+		ctx.res.send(pageOf(failure));
+		return Promise.resolve(true);
+	};
+	return {
+		stage,
+		/** The space did not author: every page says why, until it does. */
+		fail: (message) => {
+			failure = message;
+		},
+		/** It authored: the pages are the space's again. */
+		clear: () => {
+			failure = void 0;
+		}
+	};
+};
+//#endregion
+export { createSpaceFailure };

package/dist/modules/runtime/runner.d.ts

@@ -1,5 +1,6 @@
 import { FunctionsDefinition } from '../functions/contract';
 import { FunctionRunner } from '../functions/protocol';
+/** A refusal, however it was made: the platform's class, or a bundle's own copy of it — known by its name. */
 /**
  * A runtime's functions as a runner: the same protocol as the sandbox's, answered by code loaded in this process. The
  * driver is the sandbox's own (`createFunctionsDriver`), so a task behaves the same in both — its `ctx` is calls to the

package/dist/modules/runtime/runner.js

@@ -1,11 +1,10 @@
-import { ActionRefusal } from "../actions/runtime/errors.js";
+import { ActionRefusal, isActionRefusal } from "../actions/runtime/errors.js";
 import { changeKv } from "../actions/runtime/kvChange.js";
 import { requestFromWire, responseOf, wireResponseFrom, wireResponseOf } from "../functions/capabilities.js";
 import { FunctionFailure } from "../functions/protocol.js";
 import { createFunctionsDriver, describeFunctions } from "../functions/driver.js";
 //#region src/modules/runtime/runner.ts
 /** A refusal, however it was made: the platform's class, or a bundle's own copy of it — known by its name. */
-var isRefusal = (error) => error instanceof Error && error.name === "ActionRefusal";
 /**
 * A runtime's functions as a runner: the same protocol as the sandbox's, answered by code loaded in this process. The
 * driver is the sandbox's own (`createFunctionsDriver`), so a task behaves the same in both — its `ctx` is calls to the
@@ -29,7 +28,7 @@ var createRuntimeRunner = (definition = {}) => ({
 		try {
 			return await driver.invoke(definition, invocation);
 		} catch (error) {
-			if (isRefusal(error)) throw new FunctionFailure("refused", error.message);
+			if (isActionRefusal(error)) throw new FunctionFailure("refused", error.message);
 			throw error;
 		}
 	}

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

@@ -1,2 +1,13 @@
 import { SSRRenderResult, SSRResponseHelpers } from '@plitzi/sdk-shared';
 export declare const applySSRResult: (res: SSRResponseHelpers, result: SSRRenderResult) => boolean;
+/**
+ * Whether a render may be kept and served again: only a page that answered 200. A cached page is sent without the
+ * status it was rendered with, and a "not found" kept per address would let anybody asking for addresses at random
+ * push every real page out of the cache.
+ */
+export declare const isReusable: (result: SSRRenderResult) => boolean;
+/**
+ * A page a server provider said shows nothing (`notFound`) answers 404 — unless the render decided something of its
+ * own first: a redirect, or a status the navigation set.
+ */
+export declare const withNotFound: (result: SSRRenderResult, notFound: boolean) => void;

package/dist/modules/ssr/applySSRResult.js

@@ -10,5 +10,18 @@ var applySSRResult = (res, result) => {
 	if (result.status !== void 0) res.setStatus(result.status);
 	return false;
 };
+/**
+* Whether a render may be kept and served again: only a page that answered 200. A cached page is sent without the
+* status it was rendered with, and a "not found" kept per address would let anybody asking for addresses at random
+* push every real page out of the cache.
+*/
+var isReusable = (result) => result.status === void 0 || result.status === 200;
+/**
+* A page a server provider said shows nothing (`notFound`) answers 404 — unless the render decided something of its
+* own first: a redirect, or a status the navigation set.
+*/
+var withNotFound = (result, notFound) => {
+	if (notFound && result.redirect === void 0 && result.status === void 0) result.status = 404;
+};
 //#endregion
-export { applySSRResult };
+export { applySSRResult, isReusable, withNotFound };

package/dist/modules/ssr/buildBody.js

@@ -1,3 +1,4 @@
+import { withNotFound } from "./applySSRResult.js";
 import Component from "./Component.js";
 import { prepareRender } from "./prepareRender.js";
 import { renderToString } from "react-dom/server";
@@ -12,6 +13,7 @@ var buildBody = async (req, config, spaceId, environment, revision, renderFn, pl
 		ssrResult: result
 	})).trim();
 	metrics?.record("react", Math.round(performance.now() - reactStart));
+	withNotFound(result, prep.notFound);
 	if (result.redirect !== void 0) return {
 		result,
 		cacheable: prep.cacheable

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, pageNotFound, pageServerContext } 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,
@@ -83,7 +84,13 @@ var prepareRender = async (req, config, spaceId, environment, revision, pluginMa
 		loadOfflineData,
 		flagOverrides
 	})) : rscPath ? { serverData: {} } : void 0;
-	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId);
+	const navigation = {
+		routeParams: pageMatch?.routeParams ?? {},
+		queryParams: req.query
+	};
+	const pageContext = pageServerContext(serverElements, rscData?.serverData ?? {}, navigation);
+	const pageSeo = resolvePageSeo(schema, pageMatch?.pageId, pageContext);
+	const notFound = pageMatch !== void 0 && rscData?.serverData !== void 0 ? notFoundProvider(serverElements, rscData.serverData, navigation) !== void 0 || pageNotFound(schema?.flat[pageMatch.pageId]?.attributes.notFound, pageContext) : false;
 	const server = buildServerInfo(req, config, {
 		rscPath,
 		rscData,
@@ -281,7 +288,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/resolvePageSeo.d.ts

@@ -14,5 +14,8 @@ export type PageSeo = {
  * `seoEnabled: false` returns nothing rather than a default, so the deployment's own title stays in charge of a
  * page that opted out. Blank strings are treated as absent for the same reason — the builder writes one for a
  * field the author cleared, and an empty <title> is worse than a generic one.
+ *
+ * Either may be a template over the page's server providers and the address (`pageServerContext`): a detail page says
+ * the title of the record it shows, in the HTML a crawler reads. One that does not evaluate is nothing, as a blank is.
  */
-export declare const resolvePageSeo: (schema: Schema | undefined, pageId: string | undefined) => PageSeo;
+export declare const resolvePageSeo: (schema: Schema | undefined, pageId: string | undefined, context?: Record<string, unknown>) => PageSeo;

package/dist/modules/ssr/resolvePageSeo.js

@@ -1,3 +1,4 @@
+import { pageSeoText } from "@plitzi/sdk-shared/schema/serverElements";
 //#region src/modules/ssr/resolvePageSeo.ts
 /**
 * The title and description the addressed page declares for itself.
@@ -10,13 +11,16 @@
 * `seoEnabled: false` returns nothing rather than a default, so the deployment's own title stays in charge of a
 * page that opted out. Blank strings are treated as absent for the same reason — the builder writes one for a
 * field the author cleared, and an empty <title> is worse than a generic one.
+*
+* Either may be a template over the page's server providers and the address (`pageServerContext`): a detail page says
+* the title of the record it shows, in the HTML a crawler reads. One that does not evaluate is nothing, as a blank is.
 */
-var resolvePageSeo = (schema, pageId) => {
+var resolvePageSeo = (schema, pageId, context = {}) => {
 	if (!schema || !pageId) return {};
 	const page = schema.flat[pageId];
 	if (!page?.attributes.seoEnabled) return {};
-	const title = page.attributes.seoPageTitle?.trim();
-	const description = page.attributes.seoPageDescription?.trim();
+	const title = pageSeoText(page.attributes.seoPageTitle, context);
+	const description = pageSeoText(page.attributes.seoPageDescription, context);
 	return {
 		...title ? { title } : {},
 		...description ? { description } : {}

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.8",
+  "version": "0.38.10",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.8",
-    "@plitzi/sdk-shared": "0.38.8",
+    "@plitzi/plitzi-sdk": "0.38.10",
+    "@plitzi/sdk-shared": "0.38.10",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/CHEATSHEET.md

@@ -50,7 +50,7 @@ apiContainer({ id: 'p', query: '/data/x.json', runtime: 'server', children }) //
 apiContainer({ id: 'p', action: 'report', runtime: 'server', children })     // the action's output at p's root: p.rows
                                                // loadingSlot: 'p-skeleton' — a child shown until it answers
 form({ id, managedByInteractions: true, flows, children })
-formControl({ name: 'email', label: 'Email', subType: 'email' })          // select: options: [{ label, value }]
+formControl({ name: 'email', label: 'Email', subType: 'email', required: true })   // optional without required; select: options: [{ label, value }]
 modalContainer({ id, visible: false, title, children })
 component('card', { props: { title }, children: { body: [ … ] } })
 custom({ renderType: 'myPlugin' }); defineElement<Props>(declaration)      // a plugin

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/filter-a-list.ts

@@ -31,8 +31,6 @@ export const recipe: SpaceSpec = {
             { label: 'Graphics cards', value: 'gpu' }
           ],
           defaultValue: 'all',
-          // A filter always has an answer: the select is not a question that must be filled in.
-          required: false,
           flows: [
             [named('picked', on('onChange')), setState({ key: 'category', type: 'text', value: '{{ picked.value }}' })]
           ]

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

@@ -38,7 +38,8 @@ export const recipe: SpaceSpec = {
             [named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]
           ],
           children: [
-            formControl({ name: 'email', label: 'Email', subType: 'email' }),
+            // Optional unless it says so, as an HTML field is: a sign-up without an address is no sign-up.
+            formControl({ name: 'email', label: 'Email', subType: 'email', required: true }),
             button({ content: 'Sign up', subType: 'submit' })
           ]
         }),

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

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`, a provider's or a page's, that is not one `{{ expression }}` — 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 |
@@ -108,6 +110,7 @@ The space is not written until these are fixed.
 | `page-route-taken` | two pages at one address for the same visitors | another slug — or `accessLevel` `'public'` on one and `'authenticated'` on the other |
 | `page-target-unknown` | a link or `navigate` to a page id that does not exist | an existing page id, or a path with its slash (`'/about'`) |
 | `page-target-url` | a URL, `mailto:` or `tel:` in a link left in page mode | `mode: 'external'` |
+| `page-template` | a template in a page's `seoTitle`, `seoDescription` or `notFound` that reads what is not there when the server answers — anything but the page's `runtime: 'server'` providers and `navigation` — or cannot be read | read the record from a provider with `runtime: 'server'` on the page or its layout — `'{{ apiContainer_post.title }} — Blog'` — or words of its own |
 | `page-without-slug` | a page with no `slug` | `slug: ''` for the home page, its path for any other: `'about'`, `'blog/:slug'` |
 | `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 |
@@ -183,6 +186,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `embed-without-title` | an `embed` with no `title` — a frame a screen reader cannot describe | say what it shows in `title` |
 | `flag-rule-empty` | a flag rule with no conditions — skipped, never read as "always" | give it a condition, or set the flag's `value` instead |
 | `flag-unused` | a declared flag nothing gates on and no template reads | gate what it switches (`flag: 'x'`), or remove it once the feature has shipped |
+| `focus-on-field-box` | a `focus` or `focus-visible` state on a text field's or a select's `input` slot — the box the field is drawn in, which never takes focus, so no ring is ever shown | `'focus-within'` on the same class, or the state on the `field` slot |
 | `FORM_SUBMIT_UNMANAGED` | a form the browser would submit itself, reloading the page | `managedByInteractions: true` |
 | `form-control-name-taken` | two controls in one form with one name — one overwrites the other | a name each |
 | `form-control-unnamed` | a control in a form with no `name` — its value never reaches `values` | `formControl({ name: 'email', … })` |
@@ -200,6 +204,7 @@ The space renders, and renders something you probably did not mean. Fix every on
 | `path-not-in-data` | a binding onto a provider whose answer the author could read (`data`), through a path that answer does not have | the path the message lists the keys for — `p.data.plans`, not `p.data.landing.plans` |
 | `plugin-attribute-reserved` | a plugin attribute named as one of the element’s own fields — a factory never hands it to the plugin | rename it in the plugin (`variant` → `kind`) |
 | `provider-without-source` | an `apiContainer` that asks nothing | a `query` (or `action`, `connector`, `resource`) |
+| `required-message-unused` | a `requiredMessage` on a field nothing requires — fields are optional unless `required: true`, so it is never shown and an empty answer is sent | `required: true` on the field, or no message |
 | `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 — `connector`, `action` or `query` — in a space that turns server data off (`rsc: { enabled: false }`) | drop `rsc: { enabled: false }`: server data is on unless a space turns it off |
 | `span-holds-block` | a `container` with `subType: 'span'` or `'p'` holding a heading, a paragraph, a list, a form or prose | a `div` (leave `subType` out), or words and inline elements: a `text`, a `link` |
@@ -229,6 +234,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/flows.md

@@ -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
 

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

@@ -124,6 +124,26 @@ 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. When the record comes from a
+  provider of its layout, which every page shares, the page says it: `notFound` on the page reads its server providers
+  by name — `"{{ not (apiContainer_feed.products|find('slug', navigation.routeParams.slug)) }}"`. 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/recipes.md

@@ -9,7 +9,7 @@ Each is a whole file that authors with no warning — CI holds it to that. Copy
 | 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) |
+| 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) |

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

@@ -93,7 +93,9 @@ pages: [
 
 Adding a page is adding an entry; two entries of one id or slug are refused as any two pages are. For one shape over
 records a visitor browses — a product, a post — a single page with a route param (`slug: 'posts/:postId'`) reading
-the record is the answer instead: one page, as many addresses as records.
+the record is the answer instead: one page, as many addresses as records. Its `seoTitle` can say the record —
+`'{{ apiContainer_post.title }} — Blog'` — read from a provider on the page with `runtime: 'server'`, or from
+`navigation`: the server writes the head with it, so a link preview shows it. Anything else is refused (`page-template`).
 
 ## Names