@plitzi/sdk-server 0.38.7 → 0.38.9

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @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
+
+- Updated dependencies [1b45aae]
+  - @plitzi/sdk-shared@0.38.8
+  - @plitzi/plitzi-sdk@0.38.8
+
 ## 0.38.7
 
 ### Patch Changes

package/README.md

@@ -159,7 +159,7 @@ serve it — worth running over anything that arrives as a file.
 A space on Plitzi comes out whole, as a project wired to this server: `npx @plitzi/cli create my-site --from <space>`
 writes its pages as authoring code, its actions as `defineAction` code, its functions, the source of its plugins and
 runtime, and its files into `public/` — a draft, or any published snapshot (`--environment`, `--revision`) — and
-`plitzi pull` keeps it in step, and `plitzi push` puts what changed in it back on the space. See
+`plitzi space pull` keeps it in step, and `plitzi space push` puts what changed in it back on the space. See
 `docs/en/projects-from-spaces.md` in the workspace.
 
 ## Projects
@@ -221,7 +221,7 @@ What it wires from the project:
 - **Its files.** `public/` served as it is, `src/data/` read and never served (`dataDir`), the `kv` in `state/kv.json`
   (`createFileKv`), `PLITZI_SIGNING_SECRET` what `ctx.sign` signs with.
 - **Where it is.** `/health` answers with the space's permanent URL (or the cloud `name`), and `tmp/dev-server.json`
-  records the name, the port and the URL for `plitzi check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
+  records the name, the port and the URL for `plitzi page check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
 
 While developing — `NODE_ENV` other than `production` — `devMode` and `devReload` are on, and:
 
@@ -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 |
@@ -541,7 +546,7 @@ createServer({ dataDir: path.join(PROJECT_ROOT, 'src/data'), adapters: { ... } }
 ```
 
 The data is read through one lookup, `action.lookups.getData(spaceId, at)` — the space's own data as its files' text by
-path, as of the version being rendered or run: what a cloud deployment keeps for a space (`plitzi push`). Given none,
+path, as of the version being rendered or run: what a cloud deployment keeps for a space (`plitzi space push`). Given none,
 `createServer` derives it from `dataDir` (its `.json` files, read again once they change), so the folder and the
 platform are read the same way.
 
@@ -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. |
 
@@ -642,7 +647,7 @@ All fields are optional and combined with AND logic. Calling `invalidate()` with
 
 Plugins are React component bundles that extend the Plitzi schema renderer. They are defined globally at server config level, compiled or copied on first use, and cached on disk for one week. The `getSpaceDeployment` adapter controls which plugins each space gets access to via `pluginNames`.
 
-A compiled plugin is one module and its stylesheet, built as `plitzi pack plugin` builds it: React and the SDK kept out, and everything else inside — images and fonts as data URIs, and a file imported whole the way Vite imports it (`worker.js?raw` for its text, `engine.wasm?inline` for a data URI).
+A compiled plugin is one module and its stylesheet, built as `plitzi plugin pack` builds it: React and the SDK kept out, and everything else inside — images and fonts as data URIs, and a file imported whole the way Vite imports it (`worker.js?raw` for its text, `engine.wasm?inline` for a data URI).
 
 Whatever stylesheet the server writes for a plugin — compiled, copied or downloaded — goes into the `plitzi-sdk-plugin` cascade layer (`inPluginLayer` from `@plitzi/sdk-shared/style`), below the space's own: a space's classes and `customCss` win over what the plugin shipped, whatever the specificity. A `css` given as a web path (`/builder-assets/…`) is linked as it is.
 

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/projectData.js

@@ -1,7 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 //#region src/modules/actions/runtime/projectData.ts
-/** What a project keeps in its data folder: JSON, the only files `plitzi push` sends as the space's data. */
+/** What a project keeps in its data folder: JSON, the only files `plitzi space push` sends as the space's data. */
 var DATA_EXTENSION = ".json";
 /**
 * A data folder as the lookup a deployment would otherwise write — what a self-hosted server derives from `dataDir`, so

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/plugins.d.ts

@@ -23,7 +23,7 @@ export declare const projectPlugins: (root: string) => Promise<ProjectPlugins>;
 /**
  * A plugin edited while developing is built again by the server, and the open pages swap it where it is drawn — the
  * rest of the page, its state included, stays as it was (`devReload`). Its server half (`functions/`) is loaded again
- * here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi add plugin` writes — is registered
+ * here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi plugin add` writes — is registered
  * here, and the pages load again to render it; one removed is turned off. A folder the server cannot build, or whose
  * server half has no entry, is said in the terminal as the layout check says it at boot — once, until it changes — and
  * the server goes on. Answers what stops watching.

package/dist/modules/project/plugins.js

@@ -39,7 +39,7 @@ var folderFunctions = async (root, folder) => {
 	const functions = path.join(root, PLUGINS_DIR, folder, PLUGIN_FUNCTIONS_DIR);
 	return existsSync(path.join(functions, "index.ts")) ? (await loadFunctions(functions)).at(0) : void 0;
 };
-/** A plugin of `vendor/plugins`, from the manifest `plitzi pack plugin` wrote beside its bundle when it was published. */
+/** A plugin of `vendor/plugins`, from the manifest `plitzi plugin pack` wrote beside its bundle when it was published. */
 var builtPlugin = (root, type) => {
 	const read = readVendorPlugin(root, type);
 	if ("problem" in read) throw new Error(read.problem.message);
@@ -88,7 +88,7 @@ var projectPlugins = async (root) => {
 /**
 * A plugin edited while developing is built again by the server, and the open pages swap it where it is drawn — the
 * rest of the page, its state included, stays as it was (`devReload`). Its server half (`functions/`) is loaded again
-* here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi add plugin` writes — is registered
+* here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi plugin add` writes — is registered
 * here, and the pages load again to render it; one removed is turned off. A folder the server cannot build, or whose
 * server half has no entry, is said in the terminal as the layout check says it at boot — once, until it changes — and
 * the server goes on. Answers what stops watching.

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/bundle.d.ts

@@ -19,7 +19,7 @@ export declare const inspectRuntime: (bytes: Uint8Array) => {
 };
 /**
  * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
- * or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+ * or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
  */
 export declare const loadRuntimeModule: (file: string) => Promise<SpaceRuntime | undefined>;
 /**

package/dist/modules/runtime/bundle.js

@@ -93,7 +93,7 @@ var runtimeOf = (loaded) => {
 };
 /**
 * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
-* or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+* or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
 */
 var loadRuntimeModule = async (file) => {
 	try {

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