@mostra/protocol 0.0.0-stage → 0.1.0

package/dist/diagnostics/codes/console.js

@@ -0,0 +1,30 @@
+//#region src/diagnostics/codes/console.ts
+/** The codes of the CONSOLE area, in the order they were added. */
+const consoleDiagnosticCodes = ["MOSTRA_CONSOLE_ERROR", "MOSTRA_CONSOLE_WARNING"];
+/** The CONSOLE area's catalog entries. */
+const consoleDiagnostics = {
+	MOSTRA_CONSOLE_ERROR: {
+		severity: "error",
+		phase: "console",
+		title: "Error logged to the console",
+		hint: "Fix what the logged error describes; React logs errors its boundaries catch here too.",
+		docs: {
+			explanation: "The page logged an error with `console.error` while verify rendered it or used its controls. Errors caught by React error boundaries, the root's included, are logged this way. A viewer's page would log the same.",
+			fix: "Read the message and fix its cause in the artifact's code. Errors logged by a library usually name what it was given."
+		}
+	},
+	MOSTRA_CONSOLE_WARNING: {
+		severity: "hint",
+		phase: "console",
+		title: "Warning logged to the console",
+		hint: "Read the warning; nothing is broken by it.",
+		docs: {
+			explanation: "The page logged a warning with `console.warn`. Warnings are often a library's advice, so they are hints.",
+			fix: "Nothing is required."
+		}
+	}
+};
+//#endregion
+export { consoleDiagnosticCodes, consoleDiagnostics };
+
+//# sourceMappingURL=console.js.map

package/dist/diagnostics/codes/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","names":[],"sources":["../../../src/diagnostics/codes/console.ts"],"sourcesContent":["/**\n * Diagnostic codes of the CONSOLE area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the CONSOLE area, in the order they were added. */\nexport const consoleDiagnosticCodes = [\n  \"MOSTRA_CONSOLE_ERROR\",\n  \"MOSTRA_CONSOLE_WARNING\",\n  // gen:codes\n] as const;\n\n/** The codes of the CONSOLE area. */\nexport type ConsoleDiagnosticCode = (typeof consoleDiagnosticCodes)[number];\n\n/** The CONSOLE area's catalog entries. */\nexport const consoleDiagnostics: AreaCatalog<ConsoleDiagnosticCode> = {\n  MOSTRA_CONSOLE_ERROR: {\n    severity: \"error\",\n    phase: \"console\",\n    title: \"Error logged to the console\",\n    hint: \"Fix what the logged error describes; React logs errors its boundaries catch here too.\",\n    docs: {\n      explanation:\n        \"The page logged an error with `console.error` while verify rendered it or used its controls. Errors caught by React error boundaries, the root's included, are logged this way. A viewer's page would log the same.\",\n      fix: \"Read the message and fix its cause in the artifact's code. Errors logged by a library usually name what it was given.\",\n    },\n  },\n  MOSTRA_CONSOLE_WARNING: {\n    severity: \"hint\",\n    phase: \"console\",\n    title: \"Warning logged to the console\",\n    hint: \"Read the warning; nothing is broken by it.\",\n    docs: {\n      explanation:\n        \"The page logged a warning with `console.warn`. Warnings are often a library's advice, so they are hints.\",\n      fix: \"Nothing is required.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,yBAAyB,CACpC,wBACA,wBAEF;;AAMA,MAAa,qBAAyD;CACpE,sBAAsB;EACpB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,wBAAwB;EACtB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

package/dist/diagnostics/codes/dep.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/dep.d.ts
+/** The codes of the DEP area, in the order they were added. */
+export declare const depDiagnosticCodes: readonly ["MOSTRA_DEP_MISSING", "MOSTRA_DEP_NOT_FOUND", "MOSTRA_DEP_OFFLINE", "MOSTRA_DEP_TIMEOUT", "MOSTRA_DEP_INSTALL_FAILED", "MOSTRA_DEP_WARM_CONFLICT", "MOSTRA_DEP_SPEC_INVALID"];
+/** The codes of the DEP area. */
+export type DepDiagnosticCode = (typeof depDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=dep.d.ts.map

package/dist/diagnostics/codes/dep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep.d.ts","names":[],"sources":["../../../src/diagnostics/codes/dep.ts"],"mappings":";;;qBAMa;;YAYD,4BAA4B"}

package/dist/diagnostics/codes/dep.js

@@ -0,0 +1,88 @@
+//#region src/diagnostics/codes/dep.ts
+/** The codes of the DEP area, in the order they were added. */
+const depDiagnosticCodes = [
+	"MOSTRA_DEP_MISSING",
+	"MOSTRA_DEP_NOT_FOUND",
+	"MOSTRA_DEP_OFFLINE",
+	"MOSTRA_DEP_TIMEOUT",
+	"MOSTRA_DEP_INSTALL_FAILED",
+	"MOSTRA_DEP_WARM_CONFLICT",
+	"MOSTRA_DEP_SPEC_INVALID"
+];
+/** The DEP area's catalog entries. */
+const depDiagnostics = {
+	MOSTRA_DEP_MISSING: {
+		severity: "error",
+		phase: "compile",
+		title: "Package not added",
+		hint: "Run the `mostra add` command in this diagnostic's fix, then publish again.",
+		docs: {
+			explanation: "The artifact imports a package that is neither in Mostra's warm set nor in the artifact's lockfile, and the host has set the dependency policy to `explicit`. Under that policy a package enters an artifact's lockfile only when it is added on purpose, so Mostra installs nothing on its own. The location points at the first import of the package, and the fix carries the exact command that adds every missing package.",
+			fix: "Run the command from the fix (`mostra add <package…> --artifact <path>`, or the host protocol method `deps/add`), then publish again. To use a package from the warm set instead, change the import."
+		}
+	},
+	MOSTRA_DEP_NOT_FOUND: {
+		severity: "error",
+		phase: "compile",
+		title: "Package not found",
+		hint: "Check the package name and version against the npm registry, then fix the import or the spec.",
+		docs: {
+			explanation: "The registry has no package by that name, or no version that matches the requested one. A spec without an exact version only matches releases at least a day old, so a package whose every release is newer than that isn't found either. The message names the package and what the registry answered.",
+			fix: "Correct the package name in the import or in the `mostra add` spec. To use a release less than a day old, add it at its exact version: `mostra add <package>@<version>`."
+		}
+	},
+	MOSTRA_DEP_OFFLINE: {
+		severity: "error",
+		phase: "compile",
+		title: "Package unavailable offline",
+		hint: "Connect to the network and publish again, or import a package the home already holds.",
+		docs: {
+			explanation: "Mostra is offline (`MOSTRA_OFFLINE` is set, no network interface is up, or the registry can't be reached), and the artifact needs a package that the home's package store doesn't hold yet. Everything the store holds keeps working offline, including rebuilds of published versions. The message names the missing package.",
+			fix: "Publish again once the registry is reachable; the package then stays in the store for later offline use. Otherwise remove the import, or use a package from the warm set."
+		}
+	},
+	MOSTRA_DEP_TIMEOUT: {
+		severity: "error",
+		phase: "compile",
+		title: "Package install timed out",
+		hint: "Check the network and the registry, then publish again.",
+		docs: {
+			explanation: "Installing the artifact's packages took longer than 300 seconds and was stopped. A slow registry, a stalled download or a lifecycle script that never ends are the usual causes. Nothing was published, and packages already in the store stay there.",
+			fix: "Publish again; packages that finished downloading aren't fetched twice. When a package's install script hangs, use another version of the package or another package."
+		}
+	},
+	MOSTRA_DEP_INSTALL_FAILED: {
+		severity: "error",
+		phase: "compile",
+		title: "Package install failed",
+		hint: "Read the installer's output in the message, then fix the package spec or choose another version.",
+		docs: {
+			explanation: "The package installer failed for a reason other than a missing package or the network: most often a package's lifecycle script (`preinstall`, `install`, `postinstall`) exited with an error, or a downloaded package didn't match its integrity hash. Lifecycle scripts run in an install child in the artifact's directory with the artifact's environment. The message carries the end of the installer's output.",
+			fix: "Fix what the output names. For a failing install script, check what it needs (a compiler, a system library) or use another version of the package."
+		}
+	},
+	MOSTRA_DEP_WARM_CONFLICT: {
+		severity: "error",
+		phase: "compile",
+		title: "Warm package version requested",
+		hint: "Add the package without a version, or with one the warm set's version satisfies.",
+		docs: {
+			explanation: "The package is part of Mostra's warm set, which every artifact resolves at one fixed version so that React and the other shared packages exist exactly once. The requested version doesn't match the warm one, and an artifact can't replace a warm package.",
+			fix: "Drop the version from the spec (`mostra add react`), or request a range the warm version satisfies. The message names the warm version."
+		}
+	},
+	MOSTRA_DEP_SPEC_INVALID: {
+		severity: "error",
+		phase: "host",
+		title: "Invalid package spec",
+		hint: "Write the spec as `name`, `name@version`, `name@range` or `name@tag`.",
+		docs: {
+			explanation: "A package spec given to `mostra add` (`deps/add`) isn't an npm registry spec. Mostra adds packages from the registry by name, optionally with a version, a semver range or a dist-tag; scoped names such as `@scope/name@1.2.3` work too. Git URLs, local paths and tarball URLs aren't registry specs.",
+			fix: "Correct the spec, for example `mostra add three@0.186.1` or `mostra add @xyflow/react`."
+		}
+	}
+};
+//#endregion
+export { depDiagnosticCodes, depDiagnostics };
+
+//# sourceMappingURL=dep.js.map

package/dist/diagnostics/codes/dep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep.js","names":[],"sources":["../../../src/diagnostics/codes/dep.ts"],"sourcesContent":["/**\n * Diagnostic codes of the DEP area: the packages an artifact imports (D20, D43, D95).\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the DEP area, in the order they were added. */\nexport const depDiagnosticCodes = [\n  \"MOSTRA_DEP_MISSING\",\n  \"MOSTRA_DEP_NOT_FOUND\",\n  \"MOSTRA_DEP_OFFLINE\",\n  \"MOSTRA_DEP_TIMEOUT\",\n  \"MOSTRA_DEP_INSTALL_FAILED\",\n  \"MOSTRA_DEP_WARM_CONFLICT\",\n  \"MOSTRA_DEP_SPEC_INVALID\",\n  // gen:codes\n] as const;\n\n/** The codes of the DEP area. */\nexport type DepDiagnosticCode = (typeof depDiagnosticCodes)[number];\n\n/** The DEP area's catalog entries. */\nexport const depDiagnostics: AreaCatalog<DepDiagnosticCode> = {\n  MOSTRA_DEP_MISSING: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Package not added\",\n    hint: \"Run the `mostra add` command in this diagnostic's fix, then publish again.\",\n    docs: {\n      explanation:\n        \"The artifact imports a package that is neither in Mostra's warm set nor in the artifact's lockfile, and the host has set the dependency policy to `explicit`. Under that policy a package enters an artifact's lockfile only when it is added on purpose, so Mostra installs nothing on its own. The location points at the first import of the package, and the fix carries the exact command that adds every missing package.\",\n      fix: \"Run the command from the fix (`mostra add <package…> --artifact <path>`, or the host protocol method `deps/add`), then publish again. To use a package from the warm set instead, change the import.\",\n    },\n  },\n  MOSTRA_DEP_NOT_FOUND: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Package not found\",\n    hint: \"Check the package name and version against the npm registry, then fix the import or the spec.\",\n    docs: {\n      explanation:\n        \"The registry has no package by that name, or no version that matches the requested one. A spec without an exact version only matches releases at least a day old, so a package whose every release is newer than that isn't found either. The message names the package and what the registry answered.\",\n      fix: \"Correct the package name in the import or in the `mostra add` spec. To use a release less than a day old, add it at its exact version: `mostra add <package>@<version>`.\",\n    },\n  },\n  MOSTRA_DEP_OFFLINE: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Package unavailable offline\",\n    hint: \"Connect to the network and publish again, or import a package the home already holds.\",\n    docs: {\n      explanation:\n        \"Mostra is offline (`MOSTRA_OFFLINE` is set, no network interface is up, or the registry can't be reached), and the artifact needs a package that the home's package store doesn't hold yet. Everything the store holds keeps working offline, including rebuilds of published versions. The message names the missing package.\",\n      fix: \"Publish again once the registry is reachable; the package then stays in the store for later offline use. Otherwise remove the import, or use a package from the warm set.\",\n    },\n  },\n  MOSTRA_DEP_TIMEOUT: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Package install timed out\",\n    hint: \"Check the network and the registry, then publish again.\",\n    docs: {\n      explanation:\n        \"Installing the artifact's packages took longer than 300 seconds and was stopped. A slow registry, a stalled download or a lifecycle script that never ends are the usual causes. Nothing was published, and packages already in the store stay there.\",\n      fix: \"Publish again; packages that finished downloading aren't fetched twice. When a package's install script hangs, use another version of the package or another package.\",\n    },\n  },\n  MOSTRA_DEP_INSTALL_FAILED: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Package install failed\",\n    hint: \"Read the installer's output in the message, then fix the package spec or choose another version.\",\n    docs: {\n      explanation:\n        \"The package installer failed for a reason other than a missing package or the network: most often a package's lifecycle script (`preinstall`, `install`, `postinstall`) exited with an error, or a downloaded package didn't match its integrity hash. Lifecycle scripts run in an install child in the artifact's directory with the artifact's environment. The message carries the end of the installer's output.\",\n      fix: \"Fix what the output names. For a failing install script, check what it needs (a compiler, a system library) or use another version of the package.\",\n    },\n  },\n  MOSTRA_DEP_WARM_CONFLICT: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Warm package version requested\",\n    hint: \"Add the package without a version, or with one the warm set's version satisfies.\",\n    docs: {\n      explanation:\n        \"The package is part of Mostra's warm set, which every artifact resolves at one fixed version so that React and the other shared packages exist exactly once. The requested version doesn't match the warm one, and an artifact can't replace a warm package.\",\n      fix: \"Drop the version from the spec (`mostra add react`), or request a range the warm version satisfies. The message names the warm version.\",\n    },\n  },\n  MOSTRA_DEP_SPEC_INVALID: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Invalid package spec\",\n    hint: \"Write the spec as `name`, `name@version`, `name@range` or `name@tag`.\",\n    docs: {\n      explanation:\n        \"A package spec given to `mostra add` (`deps/add`) isn't an npm registry spec. Mostra adds packages from the registry by name, optionally with a version, a semver range or a dist-tag; scoped names such as `@scope/name@1.2.3` work too. Git URLs, local paths and tarball URLs aren't registry specs.\",\n      fix: \"Correct the spec, for example `mostra add three@0.186.1` or `mostra add @xyflow/react`.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,qBAAqB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,iBAAiD;CAC5D,oBAAoB;EAClB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,sBAAsB;EACpB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,oBAAoB;EAClB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,oBAAoB;EAClB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

package/dist/diagnostics/codes/env.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/env.d.ts
+/** The codes of the ENV area, in the order they were added. */
+export declare const envDiagnosticCodes: readonly ["MOSTRA_ENV_WARM_MISSING", "MOSTRA_ENV_PORT_TAKEN", "MOSTRA_ENV_BIND_FAILED", "MOSTRA_ENV_SHELL_MISSING", "MOSTRA_ENV_SERVICE_FAILED", "MOSTRA_ENV_BROWSER_MISSING", "MOSTRA_ENV_RUNTIME_MISSING", "MOSTRA_ENV_BUNDLE_INVALID", "MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", "MOSTRA_ENV_BUNDLE_UNAVAILABLE", "MOSTRA_ENV_NODE_UNSUPPORTED"];
+/** The codes of the ENV area. */
+export type EnvDiagnosticCode = (typeof envDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=env.d.ts.map

package/dist/diagnostics/codes/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"mappings":";;;qBAMa;;YAgBD,4BAA4B"}

package/dist/diagnostics/codes/env.js

@@ -0,0 +1,132 @@
+//#region src/diagnostics/codes/env.ts
+/** The codes of the ENV area, in the order they were added. */
+const envDiagnosticCodes = [
+	"MOSTRA_ENV_WARM_MISSING",
+	"MOSTRA_ENV_PORT_TAKEN",
+	"MOSTRA_ENV_BIND_FAILED",
+	"MOSTRA_ENV_SHELL_MISSING",
+	"MOSTRA_ENV_SERVICE_FAILED",
+	"MOSTRA_ENV_BROWSER_MISSING",
+	"MOSTRA_ENV_RUNTIME_MISSING",
+	"MOSTRA_ENV_BUNDLE_INVALID",
+	"MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED",
+	"MOSTRA_ENV_BUNDLE_UNAVAILABLE",
+	"MOSTRA_ENV_NODE_UNSUPPORTED"
+];
+/** The ENV area's catalog entries. */
+const envDiagnostics = {
+	MOSTRA_ENV_WARM_MISSING: {
+		severity: "error",
+		phase: "host",
+		title: "Warm package set missing",
+		hint: "Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.",
+		docs: {
+			explanation: "Builds resolve React, Tailwind and Mostra's own client packages from the warm package set that ships with the runtime. The runtime couldn't find it, which means the runtime installation is incomplete.",
+			fix: "Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the warm set's directory with `MOSTRA_WARM_DIR`."
+		}
+	},
+	MOSTRA_ENV_PORT_TAKEN: {
+		severity: "warning",
+		phase: "host",
+		title: "Leased port taken",
+		hint: "Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.",
+		docs: {
+			explanation: "The shell's port or an artifact's port is leased per home and reused across restarts, so links keep working (D62, D99). At start-up another program held the leased port, so Mostra leased a new one. Links that named the old port stop working; the shell's port changing affects every link of the home.",
+			fix: "Mint new links with `view/url` (the publish receipt of the next publish carries the new default link too). Stop the program that took the port if you want the old links back; `mostra doctor` names it where it can."
+		}
+	},
+	MOSTRA_ENV_BIND_FAILED: {
+		severity: "error",
+		phase: "host",
+		title: "Gateway can't bind",
+		hint: "Start Mostra with an address this machine has, or without `--bind` to use the loopback address.",
+		docs: {
+			explanation: "The gateway couldn't listen on the address it was given: `--bind` named an address no interface has, a wildcard bind came without `--url-host`, or the operating system refused the address. Mostra doesn't start rather than serve on an address nobody asked for.",
+			fix: "Omit `--bind` to serve on `127.0.0.1` only (the default). For a wider bind, pass an address of one of this machine's interfaces, and with `0.0.0.0` or `::` also `--url-host <name>`, the name viewers use to reach it."
+		}
+	},
+	MOSTRA_ENV_SHELL_MISSING: {
+		severity: "error",
+		phase: "host",
+		title: "Shell app missing",
+		hint: "Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.",
+		docs: {
+			explanation: "Viewers open artifacts inside the shell, Mostra's trusted page, which ships with the runtime as built files. The runtime couldn't find them, which means the runtime installation is incomplete. Artifact frames are still served.",
+			fix: "Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the shell's built directory with `MOSTRA_SHELL_DIR`."
+		}
+	},
+	MOSTRA_ENV_SERVICE_FAILED: {
+		severity: "error",
+		phase: "host",
+		title: "Login service could not be installed",
+		hint: "Read the message, fix what it names, and run the install again.",
+		docs: {
+			explanation: "`mostra daemon install` couldn't register the home's daemon as a login service: writing the launchd agent or systemd user unit failed, or `launchctl` or `systemctl --user` refused to load it.",
+			fix: "Check the named file's directory permissions, and on Linux that a systemd user session is running (`systemctl --user status`). On a machine without one, start the daemon from your own login scripts with `mostra daemon start`."
+		}
+	},
+	MOSTRA_ENV_BROWSER_MISSING: {
+		severity: "error",
+		phase: "host",
+		title: "Browser for verify missing",
+		hint: "Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.",
+		docs: {
+			explanation: "Verify renders pages in the Chromium headless shell its Playwright release pins. The runtime bundle fetches that browser when it is set up and checks every file of it (D142). It wasn't there, so verify ran only the stages that need no browser (type check, build and the field-ID scan) and reported this error. Publishing needs `--force` until it is installed.",
+			fix: "Run `bin/mostra-setup` in the runtime bundle's directory (the message names it) with network access; it fetches and checks the pinned browser. Outside a bundle, in a development checkout, run `npx playwright-core install chromium-headless-shell`. Then verify again."
+		}
+	},
+	MOSTRA_ENV_RUNTIME_MISSING: {
+		severity: "error",
+		phase: "host",
+		title: "Runtime not found",
+		hint: "Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.",
+		docs: {
+			explanation: "The CLI starts and attaches to the home's instance through the runtime binary (`mostra-runtime`, D85). It looked, in order, for `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the runtime bundle it runs from, its release's pinned bundle and a development checkout's built runtime (D142), and found nothing it could run: here, `MOSTRA_RUNTIME_BIN` names a file that doesn't exist, or the runtime couldn't be started.",
+			fix: "Unset `MOSTRA_RUNTIME_BIN` or point it at a `mostra-runtime` entry (its `dist/bin.js`), or reinstall Mostra so the CLI and its runtime are complete."
+		}
+	},
+	MOSTRA_ENV_BUNDLE_INVALID: {
+		severity: "error",
+		phase: "platform",
+		title: "Runtime bundle failed verification",
+		hint: "Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.",
+		docs: {
+			explanation: "Mostra checks every runtime bundle before it runs anything from it: the archive against the SHA-256 the installing package pins, then each extracted file against the bundle's own file list, and the verify browser against the bundle's browser pin. One of them differed, so the download was corrupted, changed on the way or replaced, and Mostra refused it. A bundle already installed that fails a later check (`mostra doctor --deep`) is refused the same way.",
+			fix: "Run the install again (`npm create mostra`, or the command that started it), which downloads a fresh copy. When a mirror is configured (`MOSTRA_BUNDLE_MIRROR`), check that it serves the release's files unchanged. Check a file you downloaded yourself against the release's `SHA256SUMS`, or with `gh attestation verify <file> --repo mostra-dev/mostra`."
+		}
+	},
+	MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED: {
+		severity: "error",
+		phase: "platform",
+		title: "Runtime bundle download failed",
+		hint: "Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.",
+		docs: {
+			explanation: "The runtime bundle for this release and platform isn't in the local cache yet, and fetching it failed: the network or a proxy refused it, the server answered with an error, the connection stalled for 60 seconds, or the disk ran out of space while it was written. Nothing partial is kept.",
+			fix: "Check the connection, and set `HTTPS_PROXY` (and `NO_PROXY`) when the network needs a proxy. Behind a firewall that blocks GitHub, host the release's files on a reachable server and set `MOSTRA_BUNDLE_MIRROR` to its base URL (a `file:` URL works for a local directory). Free space in the cache directory (`MOSTRA_CACHE_DIR`) if the message says the disk is full."
+		}
+	},
+	MOSTRA_ENV_BUNDLE_UNAVAILABLE: {
+		severity: "error",
+		phase: "platform",
+		title: "No runtime bundle available",
+		hint: "Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.",
+		docs: {
+			explanation: "Mostra runs on its own runtime bundle, found in the local cache, beside the installed package or at `MOSTRA_BUNDLE`. None was there, and no download could start: Mostra is offline (`MOSTRA_OFFLINE`), this build of the package pins no bundle for this platform, or the platform has none.",
+			fix: "Run the command once with network access and without `MOSTRA_OFFLINE`, so the pinned bundle is fetched and cached; later runs work offline. On a machine without network access, extract the release's archive for the platform and set `MOSTRA_BUNDLE` to its directory. A development checkout uses its own built runtime instead."
+		}
+	},
+	MOSTRA_ENV_NODE_UNSUPPORTED: {
+		severity: "error",
+		phase: "platform",
+		title: "Node.js too old to start Mostra",
+		hint: "Run `mostra` with Node.js 22.19 or later, or run the runtime bundle's own `bin/mostra`, which needs no Node.js.",
+		docs: {
+			explanation: "A `mostra` (or `npm create mostra`) installed from npm starts on the machine's Node.js only long enough to find its runtime bundle, then every Mostra process runs on the bundle's own Node.js (RT-01, D142). That start needs Node.js 22.19 or later, and this one is older, so Mostra stopped before loading anything.",
+			fix: "Upgrade the machine's Node.js to 22.19 or later, or run Mostra without npm: download the runtime bundle for your platform from the GitHub release, check it against `SHA256SUMS`, extract it, run its `bin/mostra-setup` once, then use its `bin/mostra`."
+		}
+	}
+};
+//#endregion
+export { envDiagnosticCodes, envDiagnostics };
+
+//# sourceMappingURL=env.js.map

package/dist/diagnostics/codes/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","names":[],"sources":["../../../src/diagnostics/codes/env.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ENV area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ENV area, in the order they were added. */\nexport const envDiagnosticCodes = [\n  \"MOSTRA_ENV_WARM_MISSING\",\n  \"MOSTRA_ENV_PORT_TAKEN\",\n  \"MOSTRA_ENV_BIND_FAILED\",\n  \"MOSTRA_ENV_SHELL_MISSING\",\n  \"MOSTRA_ENV_SERVICE_FAILED\",\n  \"MOSTRA_ENV_BROWSER_MISSING\",\n  \"MOSTRA_ENV_RUNTIME_MISSING\",\n  \"MOSTRA_ENV_BUNDLE_INVALID\",\n  \"MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED\",\n  \"MOSTRA_ENV_BUNDLE_UNAVAILABLE\",\n  \"MOSTRA_ENV_NODE_UNSUPPORTED\",\n  // gen:codes\n] as const;\n\n/** The codes of the ENV area. */\nexport type EnvDiagnosticCode = (typeof envDiagnosticCodes)[number];\n\n/** The ENV area's catalog entries. */\nexport const envDiagnostics: AreaCatalog<EnvDiagnosticCode> = {\n  MOSTRA_ENV_WARM_MISSING: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Warm package set missing\",\n    hint: \"Reinstall the Mostra runtime, or set `MOSTRA_WARM_DIR` to its warm package set.\",\n    docs: {\n      explanation:\n        \"Builds resolve React, Tailwind and Mostra's own client packages from the warm package set that ships with the runtime. The runtime couldn't find it, which means the runtime installation is incomplete.\",\n      fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the warm set's directory with `MOSTRA_WARM_DIR`.\",\n    },\n  },\n  MOSTRA_ENV_PORT_TAKEN: {\n    severity: \"warning\",\n    phase: \"host\",\n    title: \"Leased port taken\",\n    hint: \"Open the artifact through a new link: `view/url` or `mostra open` mints one on the new port.\",\n    docs: {\n      explanation:\n        \"The shell's port or an artifact's port is leased per home and reused across restarts, so links keep working (D62, D99). At start-up another program held the leased port, so Mostra leased a new one. Links that named the old port stop working; the shell's port changing affects every link of the home.\",\n      fix: \"Mint new links with `view/url` (the publish receipt of the next publish carries the new default link too). Stop the program that took the port if you want the old links back; `mostra doctor` names it where it can.\",\n    },\n  },\n  MOSTRA_ENV_BIND_FAILED: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Gateway can't bind\",\n    hint: \"Start Mostra with an address this machine has, or without `--bind` to use the loopback address.\",\n    docs: {\n      explanation:\n        \"The gateway couldn't listen on the address it was given: `--bind` named an address no interface has, a wildcard bind came without `--url-host`, or the operating system refused the address. Mostra doesn't start rather than serve on an address nobody asked for.\",\n      fix: \"Omit `--bind` to serve on `127.0.0.1` only (the default). For a wider bind, pass an address of one of this machine's interfaces, and with `0.0.0.0` or `::` also `--url-host <name>`, the name viewers use to reach it.\",\n    },\n  },\n  MOSTRA_ENV_SHELL_MISSING: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Shell app missing\",\n    hint: \"Reinstall the Mostra runtime, or set `MOSTRA_SHELL_DIR` to its built shell.\",\n    docs: {\n      explanation:\n        \"Viewers open artifacts inside the shell, Mostra's trusted page, which ships with the runtime as built files. The runtime couldn't find them, which means the runtime installation is incomplete. Artifact frames are still served.\",\n      fix: \"Reinstall Mostra so the runtime bundle is complete. A custom layout can point the runtime at the shell's built directory with `MOSTRA_SHELL_DIR`.\",\n    },\n  },\n  MOSTRA_ENV_SERVICE_FAILED: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Login service could not be installed\",\n    hint: \"Read the message, fix what it names, and run the install again.\",\n    docs: {\n      explanation:\n        \"`mostra daemon install` couldn't register the home's daemon as a login service: writing the launchd agent or systemd user unit failed, or `launchctl` or `systemctl --user` refused to load it.\",\n      fix: \"Check the named file's directory permissions, and on Linux that a systemd user session is running (`systemctl --user status`). On a machine without one, start the daemon from your own login scripts with `mostra daemon start`.\",\n    },\n  },\n  MOSTRA_ENV_BROWSER_MISSING: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Browser for verify missing\",\n    hint: \"Run the runtime bundle's `bin/mostra-setup` (with network access) to fetch the browser verify uses, then verify again.\",\n    docs: {\n      explanation:\n        \"Verify renders pages in the Chromium headless shell its Playwright release pins. The runtime bundle fetches that browser when it is set up and checks every file of it (D142). It wasn't there, so verify ran only the stages that need no browser (type check, build and the field-ID scan) and reported this error. Publishing needs `--force` until it is installed.\",\n      fix: \"Run `bin/mostra-setup` in the runtime bundle's directory (the message names it) with network access; it fetches and checks the pinned browser. Outside a bundle, in a development checkout, run `npx playwright-core install chromium-headless-shell`. Then verify again.\",\n    },\n  },\n  MOSTRA_ENV_RUNTIME_MISSING: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Runtime not found\",\n    hint: \"Reinstall Mostra, or set `MOSTRA_RUNTIME_BIN` to the runtime's `mostra-runtime` entry.\",\n    docs: {\n      explanation:\n        \"The CLI starts and attaches to the home's instance through the runtime binary (`mostra-runtime`, D85). It looked, in order, for `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the runtime bundle it runs from, its release's pinned bundle and a development checkout's built runtime (D142), and found nothing it could run: here, `MOSTRA_RUNTIME_BIN` names a file that doesn't exist, or the runtime couldn't be started.\",\n      fix: \"Unset `MOSTRA_RUNTIME_BIN` or point it at a `mostra-runtime` entry (its `dist/bin.js`), or reinstall Mostra so the CLI and its runtime are complete.\",\n    },\n  },\n  MOSTRA_ENV_BUNDLE_INVALID: {\n    severity: \"error\",\n    phase: \"platform\",\n    title: \"Runtime bundle failed verification\",\n    hint: \"Nothing was installed; install Mostra again, and if it fails the same way, report it with the message.\",\n    docs: {\n      explanation:\n        \"Mostra checks every runtime bundle before it runs anything from it: the archive against the SHA-256 the installing package pins, then each extracted file against the bundle's own file list, and the verify browser against the bundle's browser pin. One of them differed, so the download was corrupted, changed on the way or replaced, and Mostra refused it. A bundle already installed that fails a later check (`mostra doctor --deep`) is refused the same way.\",\n      fix: \"Run the install again (`npm create mostra`, or the command that started it), which downloads a fresh copy. When a mirror is configured (`MOSTRA_BUNDLE_MIRROR`), check that it serves the release's files unchanged. Check a file you downloaded yourself against the release's `SHA256SUMS`, or with `gh attestation verify <file> --repo mostra-dev/mostra`.\",\n    },\n  },\n  MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED: {\n    severity: \"error\",\n    phase: \"platform\",\n    title: \"Runtime bundle download failed\",\n    hint: \"Check the network or proxy (`HTTPS_PROXY`), then run the command again: a retry starts the download over.\",\n    docs: {\n      explanation:\n        \"The runtime bundle for this release and platform isn't in the local cache yet, and fetching it failed: the network or a proxy refused it, the server answered with an error, the connection stalled for 60 seconds, or the disk ran out of space while it was written. Nothing partial is kept.\",\n      fix: \"Check the connection, and set `HTTPS_PROXY` (and `NO_PROXY`) when the network needs a proxy. Behind a firewall that blocks GitHub, host the release's files on a reachable server and set `MOSTRA_BUNDLE_MIRROR` to its base URL (a `file:` URL works for a local directory). Free space in the cache directory (`MOSTRA_CACHE_DIR`) if the message says the disk is full.\",\n    },\n  },\n  MOSTRA_ENV_BUNDLE_UNAVAILABLE: {\n    severity: \"error\",\n    phase: \"platform\",\n    title: \"No runtime bundle available\",\n    hint: \"Run this once with network access, or point `MOSTRA_BUNDLE` at an extracted bundle.\",\n    docs: {\n      explanation:\n        \"Mostra runs on its own runtime bundle, found in the local cache, beside the installed package or at `MOSTRA_BUNDLE`. None was there, and no download could start: Mostra is offline (`MOSTRA_OFFLINE`), this build of the package pins no bundle for this platform, or the platform has none.\",\n      fix: \"Run the command once with network access and without `MOSTRA_OFFLINE`, so the pinned bundle is fetched and cached; later runs work offline. On a machine without network access, extract the release's archive for the platform and set `MOSTRA_BUNDLE` to its directory. A development checkout uses its own built runtime instead.\",\n    },\n  },\n  MOSTRA_ENV_NODE_UNSUPPORTED: {\n    severity: \"error\",\n    phase: \"platform\",\n    title: \"Node.js too old to start Mostra\",\n    hint: \"Run `mostra` with Node.js 22.19 or later, or run the runtime bundle's own `bin/mostra`, which needs no Node.js.\",\n    docs: {\n      explanation:\n        \"A `mostra` (or `npm create mostra`) installed from npm starts on the machine's Node.js only long enough to find its runtime bundle, then every Mostra process runs on the bundle's own Node.js (RT-01, D142). That start needs Node.js 22.19 or later, and this one is older, so Mostra stopped before loading anything.\",\n      fix: \"Upgrade the machine's Node.js to 22.19 or later, or run Mostra without npm: download the runtime bundle for your platform from the GitHub release, check it against `SHA256SUMS`, extract it, run its `bin/mostra-setup` once, then use its `bin/mostra`.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,qBAAqB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,iBAAiD;CAC5D,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,wBAAwB;EACtB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,+BAA+B;EAC7B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

package/dist/diagnostics/codes/field.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/field.d.ts
+/** The codes of the FIELD area, in the order they were added. */
+export declare const fieldDiagnosticCodes: readonly ["MOSTRA_FIELD_TOO_LARGE", "MOSTRA_FIELD_ID_INVALID", "MOSTRA_FIELD_MUTATION_ID_REUSED", "MOSTRA_FIELD_CONFLICT", "MOSTRA_FIELD_DUPLICATE_ID", "MOSTRA_FIELD_ID_UNSTABLE", "MOSTRA_FIELD_SHARED", "MOSTRA_FIELD_UNBOUND"];
+/** The codes of the FIELD area. */
+export type FieldDiagnosticCode = (typeof fieldDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=field.d.ts.map

package/dist/diagnostics/codes/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","names":[],"sources":["../../../src/diagnostics/codes/field.ts"],"mappings":";;;qBAMa;;YAaD,8BAA8B"}

package/dist/diagnostics/codes/field.js

@@ -0,0 +1,99 @@
+//#region src/diagnostics/codes/field.ts
+/** The codes of the FIELD area, in the order they were added. */
+const fieldDiagnosticCodes = [
+	"MOSTRA_FIELD_TOO_LARGE",
+	"MOSTRA_FIELD_ID_INVALID",
+	"MOSTRA_FIELD_MUTATION_ID_REUSED",
+	"MOSTRA_FIELD_CONFLICT",
+	"MOSTRA_FIELD_DUPLICATE_ID",
+	"MOSTRA_FIELD_ID_UNSTABLE",
+	"MOSTRA_FIELD_SHARED",
+	"MOSTRA_FIELD_UNBOUND"
+];
+/** The FIELD area's catalog entries. */
+const fieldDiagnostics = {
+	MOSTRA_FIELD_TOO_LARGE: {
+		severity: "error",
+		phase: "runtime",
+		title: "Field value too large",
+		hint: "Split large data across fields, keeping each value under 1 MiB and the whole document under 16 MiB.",
+		docs: {
+			explanation: "A field value is at most 1 MiB of JSON and a draft or artifact state at most 16 MiB in all (DATA_MODEL §5). This write would pass one of those limits, so Mostra refused it whole: nothing was truncated, and the page keeps the value locally.",
+			fix: "Split the value across several fields under one dotted prefix (`report.part1`, `report.part2`); they nest again in results."
+		}
+	},
+	MOSTRA_FIELD_ID_INVALID: {
+		severity: "error",
+		phase: "runtime",
+		title: "Invalid field ID",
+		hint: "Use a stable field ID of 1 to 256 characters: dot-separated parts, none empty.",
+		docs: {
+			explanation: "Every persisted value has an explicit, stable field ID (D52). An ID is 1 to 256 characters with no control characters; dots separate the parts that nest in results (`reply.m1`), so it can't start or end with a dot or hold two in a row.",
+			fix: "Give the field a fixed ID such as `layout` or `reply.m1` (one per message, from its ID), and keep it the same across renders and versions so drafts carry over."
+		}
+	},
+	MOSTRA_FIELD_MUTATION_ID_REUSED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Mutation ID reused",
+		hint: "Generate a new mutation ID for every new change.",
+		docs: {
+			explanation: "A mutation ID identifies one change, so a retry after a timeout replays its recorded result (IN-01). This ID was already used for a change with other contents or another target. Mostra refuses it rather than answer with the result of a change nobody sent now.",
+			fix: "Create a fresh `mut_` ID for each change and reuse an ID only to retry exactly the same change."
+		}
+	},
+	MOSTRA_FIELD_CONFLICT: {
+		severity: "error",
+		phase: "runtime",
+		title: "Field changed by another writer",
+		hint: "Read the value again, then write it; for a value several writers change often, give each writer a field of its own.",
+		docs: {
+			explanation: "Every write names the revision it was based on, and a field changed after it is a conflict, never overwritten silently (D22). `window.storage` writes end with the last write: on a conflict it writes again over the newer value, a few times. When another writer kept changing the field each time, the write is refused with this code, and the field keeps the other writer's value.",
+			fix: "Read the key again and write the new value. For a counter or a list that many viewers change at once, store each viewer's part under its own key (`votes.<viewer>`) and combine them when reading."
+		}
+	},
+	MOSTRA_FIELD_DUPLICATE_ID: {
+		severity: "error",
+		phase: "lint",
+		title: "Field ID used for two different fields",
+		hint: "Give each of these fields its own ID.",
+		docs: {
+			explanation: "One field ID is used for two different fields: with two hook kinds (`useField` and `useChoice`, say), two scopes (`viewer` and `artifact`), or initial values of two types. The two would overwrite each other's saved value. The same ID used the same way twice is a deliberately shared value and isn't reported here.",
+			fix: "Rename one of them, for example `notes` and `notes.summary`, so each persisted value has its own ID."
+		}
+	},
+	MOSTRA_FIELD_ID_UNSTABLE: {
+		severity: "error",
+		phase: "lint",
+		title: "Field ID changes between renders",
+		hint: "Build the field's ID from stable data, such as a record's ID, never from random numbers or the time.",
+		docs: {
+			explanation: "Verify loaded the page twice with identical inputs and a fixed clock, and a field ID differed between the two loads. A viewer's saved answer would then be lost on every reload. IDs an interaction creates, such as a new list row's, are new fields and aren't reported.",
+			fix: "Derive the ID from something stable, for example a template with the record's ID instead of one with `Math.random()`."
+		}
+	},
+	MOSTRA_FIELD_SHARED: {
+		severity: "hint",
+		phase: "lint",
+		title: "Field ID shared by several controls",
+		hint: "Nothing to fix if these controls are meant to edit one value; give each its own ID if not.",
+		docs: {
+			explanation: "Several mounted components use one field ID in the same way, so they all edit one saved value. That is how a value is shared deliberately; in a list, it can also mean every row edits the same answer.",
+			fix: "If each row should keep its own answer, include the row's identity in the ID, such as a template that adds the task's ID after `done.`."
+		}
+	},
+	MOSTRA_FIELD_UNBOUND: {
+		severity: "hint",
+		phase: "smoke",
+		title: "Input not bound to a field",
+		hint: "Bind the input with `useField` (or a kit input with an `id`) if its value should be saved and submitted.",
+		docs: {
+			explanation: "Verify's smoke test typed into an input and the page saved nothing: the input isn't bound to a field, so what a viewer types there is lost on reload and isn't part of a submission. A search box or a filter may be meant that way.",
+			fix: "Use `const [value, setValue] = useField(\"<id>\", \"\")` for the input's value, or leave it if it isn't meant to persist."
+		}
+	}
+};
+//#endregion
+export { fieldDiagnosticCodes, fieldDiagnostics };
+
+//# sourceMappingURL=field.js.map

package/dist/diagnostics/codes/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","names":[],"sources":["../../../src/diagnostics/codes/field.ts"],"sourcesContent":["/**\n * Diagnostic codes of the FIELD area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the FIELD area, in the order they were added. */\nexport const fieldDiagnosticCodes = [\n  \"MOSTRA_FIELD_TOO_LARGE\",\n  \"MOSTRA_FIELD_ID_INVALID\",\n  \"MOSTRA_FIELD_MUTATION_ID_REUSED\",\n  \"MOSTRA_FIELD_CONFLICT\",\n  \"MOSTRA_FIELD_DUPLICATE_ID\",\n  \"MOSTRA_FIELD_ID_UNSTABLE\",\n  \"MOSTRA_FIELD_SHARED\",\n  \"MOSTRA_FIELD_UNBOUND\",\n  // gen:codes\n] as const;\n\n/** The codes of the FIELD area. */\nexport type FieldDiagnosticCode = (typeof fieldDiagnosticCodes)[number];\n\n/** The FIELD area's catalog entries. */\nexport const fieldDiagnostics: AreaCatalog<FieldDiagnosticCode> = {\n  MOSTRA_FIELD_TOO_LARGE: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Field value too large\",\n    hint: \"Split large data across fields, keeping each value under 1 MiB and the whole document under 16 MiB.\",\n    docs: {\n      explanation:\n        \"A field value is at most 1 MiB of JSON and a draft or artifact state at most 16 MiB in all (DATA_MODEL §5). This write would pass one of those limits, so Mostra refused it whole: nothing was truncated, and the page keeps the value locally.\",\n      fix: \"Split the value across several fields under one dotted prefix (`report.part1`, `report.part2`); they nest again in results.\",\n    },\n  },\n  MOSTRA_FIELD_ID_INVALID: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Invalid field ID\",\n    hint: \"Use a stable field ID of 1 to 256 characters: dot-separated parts, none empty.\",\n    docs: {\n      explanation:\n        \"Every persisted value has an explicit, stable field ID (D52). An ID is 1 to 256 characters with no control characters; dots separate the parts that nest in results (`reply.m1`), so it can't start or end with a dot or hold two in a row.\",\n      fix: \"Give the field a fixed ID such as `layout` or `reply.m1` (one per message, from its ID), and keep it the same across renders and versions so drafts carry over.\",\n    },\n  },\n  MOSTRA_FIELD_MUTATION_ID_REUSED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Mutation ID reused\",\n    hint: \"Generate a new mutation ID for every new change.\",\n    docs: {\n      explanation:\n        \"A mutation ID identifies one change, so a retry after a timeout replays its recorded result (IN-01). This ID was already used for a change with other contents or another target. Mostra refuses it rather than answer with the result of a change nobody sent now.\",\n      fix: \"Create a fresh `mut_` ID for each change and reuse an ID only to retry exactly the same change.\",\n    },\n  },\n  MOSTRA_FIELD_CONFLICT: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Field changed by another writer\",\n    hint: \"Read the value again, then write it; for a value several writers change often, give each writer a field of its own.\",\n    docs: {\n      explanation:\n        \"Every write names the revision it was based on, and a field changed after it is a conflict, never overwritten silently (D22). `window.storage` writes end with the last write: on a conflict it writes again over the newer value, a few times. When another writer kept changing the field each time, the write is refused with this code, and the field keeps the other writer's value.\",\n      fix: \"Read the key again and write the new value. For a counter or a list that many viewers change at once, store each viewer's part under its own key (`votes.<viewer>`) and combine them when reading.\",\n    },\n  },\n  MOSTRA_FIELD_DUPLICATE_ID: {\n    severity: \"error\",\n    phase: \"lint\",\n    title: \"Field ID used for two different fields\",\n    hint: \"Give each of these fields its own ID.\",\n    docs: {\n      explanation:\n        \"One field ID is used for two different fields: with two hook kinds (`useField` and `useChoice`, say), two scopes (`viewer` and `artifact`), or initial values of two types. The two would overwrite each other's saved value. The same ID used the same way twice is a deliberately shared value and isn't reported here.\",\n      fix: \"Rename one of them, for example `notes` and `notes.summary`, so each persisted value has its own ID.\",\n    },\n  },\n  MOSTRA_FIELD_ID_UNSTABLE: {\n    severity: \"error\",\n    phase: \"lint\",\n    title: \"Field ID changes between renders\",\n    hint: \"Build the field's ID from stable data, such as a record's ID, never from random numbers or the time.\",\n    docs: {\n      explanation:\n        \"Verify loaded the page twice with identical inputs and a fixed clock, and a field ID differed between the two loads. A viewer's saved answer would then be lost on every reload. IDs an interaction creates, such as a new list row's, are new fields and aren't reported.\",\n      fix: \"Derive the ID from something stable, for example a template with the record's ID instead of one with `Math.random()`.\",\n    },\n  },\n  MOSTRA_FIELD_SHARED: {\n    severity: \"hint\",\n    phase: \"lint\",\n    title: \"Field ID shared by several controls\",\n    hint: \"Nothing to fix if these controls are meant to edit one value; give each its own ID if not.\",\n    docs: {\n      explanation:\n        \"Several mounted components use one field ID in the same way, so they all edit one saved value. That is how a value is shared deliberately; in a list, it can also mean every row edits the same answer.\",\n      fix: \"If each row should keep its own answer, include the row's identity in the ID, such as a template that adds the task's ID after `done.`.\",\n    },\n  },\n  MOSTRA_FIELD_UNBOUND: {\n    severity: \"hint\",\n    phase: \"smoke\",\n    title: \"Input not bound to a field\",\n    hint: \"Bind the input with `useField` (or a kit input with an `id`) if its value should be saved and submitted.\",\n    docs: {\n      explanation:\n        \"Verify's smoke test typed into an input and the page saved nothing: the input isn't bound to a field, so what a viewer types there is lost on reload and isn't part of a submission. A search box or a filter may be meant that way.\",\n      fix: 'Use `const [value, setValue] = useField(\"<id>\", \"\")` for the input\\'s value, or leave it if it isn\\'t meant to persist.',\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,uBAAuB;CAClC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,mBAAqD;CAChE,wBAAwB;EACtB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,yBAAyB;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,iCAAiC;EAC/B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,qBAAqB;EACnB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,sBAAsB;EACpB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

package/dist/diagnostics/codes/home.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/home.d.ts
+/** The codes of the HOME area, in the order they were added. */
+export declare const homeDiagnosticCodes: readonly ["MOSTRA_HOME_LOCKED", "MOSTRA_HOME_NOT_OWNED", "MOSTRA_HOME_SOCKET_TOO_LONG", "MOSTRA_HOME_TOO_NEW", "MOSTRA_HOME_LEDGER_UNREADABLE", "MOSTRA_HOME_DISK_FULL", "MOSTRA_HOME_GONE", "MOSTRA_HOME_MISMATCH", "MOSTRA_HOME_INTEGRITY", "MOSTRA_HOME_NOT_ALWAYS_ON", "MOSTRA_HOME_GC_INCOMPLETE"];
+/** The codes of the HOME area. */
+export type HomeDiagnosticCode = (typeof homeDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=home.d.ts.map

package/dist/diagnostics/codes/home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home.d.ts","names":[],"sources":["../../../src/diagnostics/codes/home.ts"],"mappings":";;;qBAOa;;YAgBD,6BAA6B"}

package/dist/diagnostics/codes/home.js

@@ -0,0 +1,132 @@
+//#region src/diagnostics/codes/home.ts
+/** The codes of the HOME area, in the order they were added. */
+const homeDiagnosticCodes = [
+	"MOSTRA_HOME_LOCKED",
+	"MOSTRA_HOME_NOT_OWNED",
+	"MOSTRA_HOME_SOCKET_TOO_LONG",
+	"MOSTRA_HOME_TOO_NEW",
+	"MOSTRA_HOME_LEDGER_UNREADABLE",
+	"MOSTRA_HOME_DISK_FULL",
+	"MOSTRA_HOME_GONE",
+	"MOSTRA_HOME_MISMATCH",
+	"MOSTRA_HOME_INTEGRITY",
+	"MOSTRA_HOME_NOT_ALWAYS_ON",
+	"MOSTRA_HOME_GC_INCOMPLETE"
+];
+/** The HOME area's catalog entries. */
+const homeDiagnostics = {
+	MOSTRA_HOME_LOCKED: {
+		severity: "error",
+		phase: "host",
+		title: "Home in use by another instance",
+		hint: "Use the instance that already owns this home, or stop it (`mostra daemon stop`, or end the process named in the message) and start again.",
+		docs: {
+			explanation: "One Mostra instance owns a home at a time. It holds an exclusive lock on the home's ledger, and the operating system releases that lock when the process exits. Mostra reports this code in two cases: `mostra host` was started for a home another instance already owns, or a starter found the owner but couldn't reach its control socket. The message names the owner's process ID.",
+			fix: "To share the running instance, attach to it: start the client with the same home (`MOSTRA_HOME` or `--home`) instead of starting a second instance. To replace it, stop it with `mostra daemon stop`, or end the process named in the message, and start again. A host that needs its own instance gives it its own home."
+		}
+	},
+	MOSTRA_HOME_NOT_OWNED: {
+		severity: "error",
+		phase: "host",
+		title: "Directory not owned by you",
+		hint: "Choose a home you own with `--home` or `MOSTRA_HOME`, or give the directory named in the message back to your user with `chown`.",
+		docs: {
+			explanation: "Mostra keeps secrets, answers and its ledger in the home, and its control socket in a runtime directory, so it uses only directories that belong to the user running it. It reports this code when the home or the runtime directory is owned by another user, or when the path exists but isn't a directory. Mostra changes nothing in that case.",
+			fix: "Point Mostra at a directory you own: `--home <dir>` or `MOSTRA_HOME` for the home, `MOSTRA_RUNTIME_DIR` for the runtime directory. If the directory should be yours, change its owner with `chown`. Mostra tightens a directory you own to mode 0700 by itself."
+		}
+	},
+	MOSTRA_HOME_SOCKET_TOO_LONG: {
+		severity: "error",
+		phase: "host",
+		title: "Control socket path too long",
+		hint: "Set `MOSTRA_RUNTIME_DIR` to a short directory you own, for example `/tmp/mostra-$USER`, and start again.",
+		docs: {
+			explanation: "Clients reach an instance through a Unix socket in a per-user runtime directory. The operating system limits a socket path to 103 bytes on macOS and 107 on Linux, and the path Mostra computed is longer, usually because the home directory's path is long. Mostra stops instead of using a different place that clients couldn't find.",
+			fix: "Set `MOSTRA_RUNTIME_DIR` to a short directory you own, such as `/tmp/mostra-$USER`, in the environment of every Mostra client and host that uses this home. Mostra creates it with mode 0700 and re-creates its socket if a temporary-file cleanup removes it."
+		}
+	},
+	MOSTRA_HOME_TOO_NEW: {
+		severity: "error",
+		phase: "host",
+		title: "Home written by a newer Mostra",
+		hint: "Run a Mostra release at least as new as the one named in the message, or use another home with `--home`.",
+		docs: {
+			explanation: "A newer Mostra migrated this home's ledger to a schema version this runtime doesn't know. Reading it could misinterpret or lose data, so this runtime refuses to open it. The message names the schema version and the release that wrote it.",
+			fix: "Upgrade the runtime (or the host or CLI that bundles it) to at least the release named in the message. Mostra never migrates a ledger backwards; to keep an older release, give it a separate home with `--home` or `MOSTRA_HOME`."
+		}
+	},
+	MOSTRA_HOME_LEDGER_UNREADABLE: {
+		severity: "error",
+		phase: "host",
+		title: "Ledger can't be read",
+		hint: "Restore the ledger from the latest `ledger.sqlite.bak-*` backup in the home's `store/` directory, or move the damaged file aside.",
+		docs: {
+			explanation: "The ledger (`store/ledger.sqlite` in the home) holds drafts, submissions, events and the rest of the home's interaction data. Mostra reports this code when the file can't be opened, isn't a SQLite database, isn't a Mostra ledger, or fails SQLite's integrity check. Mostra never replaces an existing ledger with an empty one.",
+			fix: "Stop every Mostra process for this home. Copy `store/ledger.sqlite` somewhere safe, then restore the newest `store/ledger.sqlite.bak-<from>-<to>` in its place, or move the damaged file aside to start an empty ledger. Versions, sources and blobs in the home are untouched either way."
+		}
+	},
+	MOSTRA_HOME_DISK_FULL: {
+		severity: "error",
+		phase: "host",
+		title: "Disk full",
+		hint: "Free space on the disk that holds the Mostra home, then retry.",
+		docs: {
+			explanation: "A ledger write failed because the disk holding the home is full. The transaction was rolled back, so nothing partial was saved and nothing that was acknowledged earlier is lost. Viewers keep unsaved edits in their browser until a retry succeeds.",
+			fix: "Free space on that disk (`mostra gc` removes unreferenced versions; build caches can be deleted), then retry the operation. Retries with the same request or mutation ID are safe."
+		}
+	},
+	MOSTRA_HOME_GONE: {
+		severity: "error",
+		phase: "host",
+		title: "Home directory removed",
+		hint: "Restore or recreate the home directory, then start Mostra again.",
+		docs: {
+			explanation: "The instance's home directory disappeared or was replaced while the instance was running. Writing anywhere else could split the home's data, so the instance stops accepting requests, stops its child processes and exits.",
+			fix: "Put the home back (or choose a new one with `--home` or `MOSTRA_HOME`) and start Mostra again. Clients reconnect and retry their requests by ID."
+		}
+	},
+	MOSTRA_HOME_MISMATCH: {
+		severity: "error",
+		phase: "host",
+		title: "Instance serves a different home",
+		hint: "Connect to the instance for the home you expect, or start it with `--home` set to that home.",
+		docs: {
+			explanation: "A client sent `home.path` in `mostra/initialize`, and it names a different home from the one the instance locked at start-up. The home is chosen when the instance starts (`--home`, then `MOSTRA_HOME`, then the platform default), so `home.path` is a check: it stops a client from writing to a home it didn't mean.",
+			fix: "Start the instance with `--home` set to the home the client expects, or connect to the socket of the instance that serves it. Leave `home.path` out to accept whichever home the instance serves."
+		}
+	},
+	MOSTRA_HOME_INTEGRITY: {
+		severity: "error",
+		phase: "host",
+		title: "Stored version or file damaged",
+		hint: "Publish the version's source again to rebuild a damaged version in place, and run `mostra doctor` for other damaged objects.",
+		docs: {
+			explanation: "Mostra checks stored versions, source snapshots and blobs against their recorded content digests before using them. This code means a stored object is missing or its content changed after it was written, for example after a disk error or a manual edit inside the home. The message names the object.",
+			fix: "Leave files inside the home unchanged. To repair a version, publish the same source again: Mostra rebuilds the version's directory and puts it back under the same version ID, and the artifact keeps its version number. If the source has changed since, the publish makes a new version and the damaged one stays as it is; its source snapshot in the home holds the original files. `mostra doctor` lists other damaged objects."
+		}
+	},
+	MOSTRA_HOME_NOT_ALWAYS_ON: {
+		severity: "warning",
+		phase: "host",
+		title: "Long-lived artifacts without an always-on daemon",
+		hint: "Run `mostra daemon install` so the home's daemon runs as a login service and these artifacts answer at any hour.",
+		docs: {
+			explanation: "The home has artifacts with submission policy `none`, which are meant to stay open (dashboards, task managers, D63), but no login service runs its daemon. Without one, the daemon exits after 30 idle minutes and their links stop answering until a command starts it again.",
+			fix: "Run `mostra daemon install`. It registers a launchd or systemd user service that keeps the home's daemon running; `mostra daemon uninstall` removes it."
+		}
+	},
+	MOSTRA_HOME_GC_INCOMPLETE: {
+		severity: "warning",
+		phase: "host",
+		title: "gc didn't finish a step",
+		hint: "Run `mostra gc` again: what this run removed is in its result, and the next run picks up what it left.",
+		docs: {
+			explanation: "`mostra gc` removes what nothing references in steps: version files, source snapshots, lock layouts, the package store, verify's caches and, when asked, events. One step failed (the message names it and why), so it left that step's files in place. Everything an earlier step removed is listed in the result, and the versions it collected stay collected. The home is consistent: what gc left is still recorded as there.",
+			fix: "Run `mostra gc` again; a failure that repeats names its cause in the message (for example, a file the user can't remove)."
+		}
+	}
+};
+//#endregion
+export { homeDiagnosticCodes, homeDiagnostics };
+
+//# sourceMappingURL=home.js.map