@plitzi/sdk-server 0.38.8 → 0.38.9

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @plitzi/sdk-server
 
+## 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";
@@ -464,7 +464,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/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.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",
@@ -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 } 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.8",
+  "version": "0.38.9",
   "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.9",
+    "@plitzi/sdk-shared": "0.38.9",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

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/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` 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 |
@@ -229,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/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,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/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) |