@mostra/protocol 0.0.0-stage → 0.1.0

package/src/diagnostics/codes/hygiene.ts

@@ -0,0 +1,175 @@
+/**
+ * Diagnostic codes of the HYGIENE area: requests the gateway refuses because they don't come from
+ * the holder of an artifact's capability URL (D06, HY-01). None of them limits what an artifact
+ * or an agent may do; each keeps strangers out.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the HYGIENE area, in the order they were added. */
+export const hygieneDiagnosticCodes = [
+  "MOSTRA_HYGIENE_HOST_REFUSED",
+  "MOSTRA_HYGIENE_ORIGIN_REFUSED",
+  "MOSTRA_HYGIENE_CSRF_MISSING",
+  "MOSTRA_HYGIENE_CONTENT_TYPE",
+  "MOSTRA_HYGIENE_REQUEST_MALFORMED",
+  "MOSTRA_HYGIENE_SESSION_MISSING",
+  "MOSTRA_HYGIENE_TOKEN_INVALID",
+  "MOSTRA_HYGIENE_TOKEN_REVOKED",
+  "MOSTRA_HYGIENE_SCOPE_DENIED",
+  "MOSTRA_HYGIENE_RATE_LIMITED",
+  "MOSTRA_HYGIENE_NOT_SERVED",
+  "MOSTRA_HYGIENE_SESSION_CONFLICT",
+  "MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
+  // gen:codes
+] as const;
+
+/** The codes of the HYGIENE area. */
+export type HygieneDiagnosticCode = (typeof hygieneDiagnosticCodes)[number];
+
+/** The HYGIENE area's catalog entries. */
+export const hygieneDiagnostics: AreaCatalog<HygieneDiagnosticCode> = {
+  MOSTRA_HYGIENE_HOST_REFUSED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Host not served",
+    hint: "Open the artifact through the exact link Mostra gave you.",
+    docs: {
+      explanation:
+        "The request's `Host` header named a host this gateway doesn't serve. Each gateway listener accepts exactly the host and port its capability URLs use, so a page that rebinds its own DNS name to the loopback address can't reach an artifact (DNS rebinding). The gateway answers 421.",
+      fix: "Use the URL from `view/url` or the publish receipt as it is, without replacing `127.0.0.1` by `localhost` or another name. A gateway started with `--bind` and `--url-host` accepts the URL host it was given.",
+    },
+  },
+  MOSTRA_HYGIENE_ORIGIN_REFUSED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Origin refused",
+    hint: "Send the request from the page's own origin.",
+    docs: {
+      explanation:
+        "A request that changes state, opens a stream or upgrades to a WebSocket must carry an `Origin` header equal to the origin it is sent to. The gateway compares the strings exactly and answers 403 otherwise, so another website, or another artifact on a different port, can't drive this one.",
+      fix: "Call the gateway from the page it serves: the shell from the shell, the artifact from its own frame. Tools outside a browser send the listener's own origin.",
+    },
+  },
+  MOSTRA_HYGIENE_CSRF_MISSING: {
+    severity: "error",
+    phase: "hygiene",
+    title: "CSRF token missing or wrong",
+    hint: "Send the session's CSRF token from `GET /_mostra/session` in the `X-Mostra-CSRF` header.",
+    docs: {
+      explanation:
+        "Every request that changes state through a session carries the session's CSRF token in the `X-Mostra-CSRF` header. The token comes only from the session endpoint of the same origin, which no other page can read. A missing or different token is answered with 403.",
+      fix: "Read `csrf` from `GET /_mostra/session` (on the shell, `GET /a/<artifactId>/_mostra/session`) and send it with every POST. Mostra's client runtime and shell do this for you.",
+    },
+  },
+  MOSTRA_HYGIENE_CONTENT_TYPE: {
+    severity: "error",
+    phase: "hygiene",
+    title: "JSON content type required",
+    hint: "Send the body as JSON with `Content-Type: application/json`.",
+    docs: {
+      explanation:
+        "Requests that change state must have a JSON body. A form or plain-text body is something any website can send without asking the browser first, so the gateway refuses it with 415.",
+      fix: "Send `Content-Type: application/json` and a JSON body.",
+    },
+  },
+  MOSTRA_HYGIENE_REQUEST_MALFORMED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Malformed request",
+    hint: "Send one well-formed HTTP request with a path that starts with `/`.",
+    docs: {
+      explanation:
+        "The gateway refused a request it can't interpret safely: a repeated `Host` or `Origin` header, a request target that isn't a path, an encoded `/` or `..` that would leave the served tree, a body that isn't valid JSON, or a header with control characters. It answers 400 rather than guess.",
+      fix: "Send a single request with one `Host` header and a plain path. Browsers always do; this usually means a hand-written client or a probe.",
+    },
+  },
+  MOSTRA_HYGIENE_SESSION_MISSING: {
+    severity: "error",
+    phase: "hygiene",
+    title: "No session",
+    hint: "Open the artifact's capability link again to start a session.",
+    docs: {
+      explanation:
+        "The request carried no valid session for this origin. Sessions start when a capability link is opened: the shell exchanges the link's token for a session cookie, and gives the artifact frame a single-use ticket for its own. A session issued for another origin never counts, because every port of the host shares the browser's cookies. The gateway answers 401.",
+      fix: "Open the full capability link, including the part after `#`. A bookmark of the page without it works while the browser keeps the session cookie (400 days).",
+    },
+  },
+  MOSTRA_HYGIENE_TOKEN_INVALID: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Unknown capability token",
+    hint: "Use the complete capability link Mostra gave you, or mint a new one with `view/url`.",
+    docs: {
+      explanation:
+        "The capability token or frame ticket matched nothing in this home: it was mistyped, cut short, belongs to another home or artifact, or the ticket was already used or expired (tickets last 60 seconds and work once). Over the host protocol, the token ID named in `view/revoke` or `view/rotate` doesn't exist. The gateway answers 401, and failed attempts count towards the rate limit.",
+      fix: "Copy the whole link again. An agent or host mints a fresh one with `view/url`; the shell gets a new frame ticket by reloading.",
+    },
+  },
+  MOSTRA_HYGIENE_TOKEN_REVOKED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Link revoked or expired",
+    hint: "Ask for a new link: `view/url` mints one, or `view/rotate` replaces this one.",
+    docs: {
+      explanation:
+        "The capability link was revoked (`view/revoke`), replaced (`view/rotate`), or reached the end of its `ttl`. Every session started from it ends too. The gateway answers 410. Local links have no expiry unless one was asked for.",
+      fix: "Get a new link from whoever shared this one. An agent mints it with `view/url`, or rotates the old one with `view/rotate`, and shares the new URL.",
+    },
+  },
+  MOSTRA_HYGIENE_SCOPE_DENIED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Not allowed by this link",
+    hint: "Open a link minted with this scope (`view/url` with `scopes`).",
+    docs: {
+      explanation:
+        "The session's link doesn't carry the scope this request needs: `draft` to save answers, `submit` to submit, `review` to comment, and `action:*`, `action:<export>` or `action:<module path>#<export>` to run a server function. A view-and-comment link, for example, can't submit or run an action. The gateway answers 403.",
+      fix: 'Mint a link with the scopes the viewer needs, such as `view/url` with `scopes: ["view", "draft", "submit"]`. Without `scopes`, a link carries every scope.',
+    },
+  },
+  MOSTRA_HYGIENE_RATE_LIMITED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Too many failed attempts",
+    hint: "Wait for the time in `Retry-After`, then open the link again.",
+    docs: {
+      explanation:
+        "More than 30 capability tokens failed for this artifact within a minute, so the gateway refuses every token for it, valid ones included, until the minute has passed. A guess can't succeed while the limit holds, and only this artifact's links wait. The gateway answers 429 with `Retry-After`.",
+      fix: "Wait, then open the link again. Repeated failures usually come from a mistyped link or a script retrying an old one.",
+    },
+  },
+  MOSTRA_HYGIENE_NOT_SERVED: {
+    severity: "error",
+    phase: "hygiene",
+    title: "Nothing served here",
+    hint: "Request a published version's files or a documented `/_mostra/` path.",
+    docs: {
+      explanation:
+        "The gateway serves only published versions' client files and the browser-protocol paths under `/_mostra/`. Everything else in the home, such as sources, server bundles, staging and unpublished builds, has no URL. A path or method nothing answers gets 404 or 405.",
+      fix: "Check the path. Server code runs through the browser protocol, never as a file, and an artifact becomes viewable only once it is published.",
+    },
+  },
+  MOSTRA_HYGIENE_SESSION_CONFLICT: {
+    severity: "warning",
+    phase: "hygiene",
+    title: "Another link is already open for this artifact",
+    hint: "Choose which link to keep; send `replace: true` to use the new one.",
+    docs: {
+      explanation:
+        "This browser already has a live session for the artifact from a different link. Opening a link never silently replaces it, because a page elsewhere could send the viewer to its own, narrower link and take over their tabs (D98). The shell shows both links' access and lets the viewer choose; the answer is 409 with `current` and `offered`.",
+      fix: "In the shell, choose the link to keep. A client exchanging tokens itself sends `replace: true` to replace the session.",
+    },
+  },
+  MOSTRA_HYGIENE_HEADERS_TOO_LARGE: {
+    severity: "error",
+    phase: "hygiene",
+    title: "The request's headers are too large",
+    hint: "Open the link again: this page cleared the cookies that made the request too large.",
+    docs: {
+      explanation:
+        "The request's headers passed the gateway's limit of 1 MiB, more than any browser sends for one host's cookies. Every port of the loopback host shares one cookie jar, so a page on any of them can fill it. The gateway answers 431 with `Clear-Site-Data: \"cookies\"`, which empties the host's cookies, so the next request works. Mostra's sessions go with them and come back when a link is opened again.",
+      fix: "Open the artifact's link again. If it keeps happening, find the page that sets the cookies: it runs on this host.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/index.ts

@@ -0,0 +1,142 @@
+/**
+ * The diagnostic catalog, assembled from one source file per area. `pnpm gen diagnostic` keeps
+ * the lists below in step with the area files; edit the area files, not these lists.
+ */
+import type { Diagnostic } from "../diagnostic.ts";
+import { buildDiagnostic, type DiagnosticDetails, type DiagnosticSpec } from "../spec.ts";
+import { type A11yDiagnosticCode, a11yDiagnostics } from "./a11y.ts";
+import { type ActionDiagnosticCode, actionDiagnostics } from "./action.ts";
+import { type ArtifactDiagnosticCode, artifactDiagnostics } from "./artifact.ts";
+import { type BuildDiagnosticCode, buildDiagnostics } from "./build.ts";
+// gen:area-imports
+import { type CliDiagnosticCode, cliDiagnostics } from "./cli.ts";
+import { type ConsoleDiagnosticCode, consoleDiagnostics } from "./console.ts";
+import { type DepDiagnosticCode, depDiagnostics } from "./dep.ts";
+import { type EnvDiagnosticCode, envDiagnostics } from "./env.ts";
+import { type FieldDiagnosticCode, fieldDiagnostics } from "./field.ts";
+import { type HomeDiagnosticCode, homeDiagnostics } from "./home.ts";
+import { type HostDiagnosticCode, hostDiagnostics } from "./host.ts";
+import { type HygieneDiagnosticCode, hygieneDiagnostics } from "./hygiene.ts";
+import { type LiveDiagnosticCode, liveDiagnostics } from "./live.ts";
+import { type ManifestDiagnosticCode, manifestDiagnostics } from "./manifest.ts";
+import { type NetworkDiagnosticCode, networkDiagnostics } from "./network.ts";
+import { type PlatformDiagnosticCode, platformDiagnostics } from "./platform.ts";
+import { type PublishDiagnosticCode, publishDiagnostics } from "./publish.ts";
+import { type RegressionDiagnosticCode, regressionDiagnostics } from "./regression.ts";
+import { type RuntimeDiagnosticCode, runtimeDiagnostics } from "./runtime.ts";
+import { type SecretDiagnosticCode, secretDiagnostics } from "./secret.ts";
+import { type SmokeDiagnosticCode, smokeDiagnostics } from "./smoke.ts";
+import { type SubmitDiagnosticCode, submitDiagnostics } from "./submit.ts";
+import { type TargetDiagnosticCode, targetDiagnostics } from "./target.ts";
+import { type TypeDiagnosticCode, typeDiagnostics } from "./type.ts";
+import { type VerifyDiagnosticCode, verifyDiagnostics } from "./verify.ts";
+
+export { type A11yDiagnosticCode, a11yDiagnosticCodes } from "./a11y.ts";
+export { type ActionDiagnosticCode, actionDiagnosticCodes } from "./action.ts";
+export { type ArtifactDiagnosticCode, artifactDiagnosticCodes } from "./artifact.ts";
+export { type BuildDiagnosticCode, buildDiagnosticCodes } from "./build.ts";
+// gen:area-exports
+export { type CliDiagnosticCode, cliDiagnosticCodes } from "./cli.ts";
+export { type ConsoleDiagnosticCode, consoleDiagnosticCodes } from "./console.ts";
+export { type DepDiagnosticCode, depDiagnosticCodes } from "./dep.ts";
+export { type EnvDiagnosticCode, envDiagnosticCodes } from "./env.ts";
+export { type FieldDiagnosticCode, fieldDiagnosticCodes } from "./field.ts";
+export { type HomeDiagnosticCode, homeDiagnosticCodes } from "./home.ts";
+export { type HostDiagnosticCode, hostDiagnosticCodes } from "./host.ts";
+export { type HygieneDiagnosticCode, hygieneDiagnosticCodes } from "./hygiene.ts";
+export { type LiveDiagnosticCode, liveDiagnosticCodes } from "./live.ts";
+export { type ManifestDiagnosticCode, manifestDiagnosticCodes } from "./manifest.ts";
+export { type NetworkDiagnosticCode, networkDiagnosticCodes } from "./network.ts";
+export { type PlatformDiagnosticCode, platformDiagnosticCodes } from "./platform.ts";
+export { type PublishDiagnosticCode, publishDiagnosticCodes } from "./publish.ts";
+export { type RegressionDiagnosticCode, regressionDiagnosticCodes } from "./regression.ts";
+export { type RuntimeDiagnosticCode, runtimeDiagnosticCodes } from "./runtime.ts";
+export { type SecretDiagnosticCode, secretDiagnosticCodes } from "./secret.ts";
+export { type SmokeDiagnosticCode, smokeDiagnosticCodes } from "./smoke.ts";
+export { type SubmitDiagnosticCode, submitDiagnosticCodes } from "./submit.ts";
+export { type TargetDiagnosticCode, targetDiagnosticCodes } from "./target.ts";
+export { type TypeDiagnosticCode, typeDiagnosticCodes } from "./type.ts";
+export { type VerifyDiagnosticCode, verifyDiagnosticCodes } from "./verify.ts";
+
+/** Every code in the catalog. Codes are semver surface and are never removed (AX-03). */
+export type KnownDiagnosticCode =
+  // gen:area-codes
+  | CliDiagnosticCode
+  | RegressionDiagnosticCode
+  | SmokeDiagnosticCode
+  | A11yDiagnosticCode
+  | NetworkDiagnosticCode
+  | ConsoleDiagnosticCode
+  | TypeDiagnosticCode
+  | VerifyDiagnosticCode
+  | LiveDiagnosticCode
+  | SecretDiagnosticCode
+  | RuntimeDiagnosticCode
+  | FieldDiagnosticCode
+  | SubmitDiagnosticCode
+  | HygieneDiagnosticCode
+  | DepDiagnosticCode
+  | EnvDiagnosticCode
+  | TargetDiagnosticCode
+  | ArtifactDiagnosticCode
+  | PublishDiagnosticCode
+  | ActionDiagnosticCode
+  | BuildDiagnosticCode
+  | ManifestDiagnosticCode
+  | HomeDiagnosticCode
+  | PlatformDiagnosticCode
+  | HostDiagnosticCode;
+
+/** Every cataloged code with its severity, phase, title, default hint and docs text. */
+export const diagnosticCatalog: Readonly<Record<KnownDiagnosticCode, DiagnosticSpec>> = {
+  // gen:area-spreads
+  ...cliDiagnostics,
+  ...regressionDiagnostics,
+  ...smokeDiagnostics,
+  ...a11yDiagnostics,
+  ...networkDiagnostics,
+  ...consoleDiagnostics,
+  ...typeDiagnostics,
+  ...verifyDiagnostics,
+  ...liveDiagnostics,
+  ...secretDiagnostics,
+  ...runtimeDiagnostics,
+  ...fieldDiagnostics,
+  ...submitDiagnostics,
+  ...hygieneDiagnostics,
+  ...depDiagnostics,
+  ...envDiagnostics,
+  ...targetDiagnostics,
+  ...artifactDiagnostics,
+  ...publishDiagnostics,
+  ...actionDiagnostics,
+  ...buildDiagnostics,
+  ...manifestDiagnostics,
+  ...homeDiagnostics,
+  ...platformDiagnostics,
+  ...hostDiagnostics,
+};
+
+/** Options for {@link createDiagnostic}. */
+export interface CreateDiagnosticOptions {
+  /** The docs site base URL. Defaults to `DEFAULT_DOCS_BASE`. */
+  readonly docsBase?: string;
+}
+
+/**
+ * Creates the diagnostic for one occurrence of a cataloged code. Severity, phase, the default hint
+ * and the docs link come from the catalog.
+ *
+ * ```ts
+ * createDiagnostic("MOSTRA_HOST_REVISION_UNSUPPORTED", {
+ *   message: "The client offered 2026-01-01; this instance supports 2026-10-10.",
+ * });
+ * ```
+ */
+export function createDiagnostic(
+  code: KnownDiagnosticCode,
+  details: DiagnosticDetails,
+  options: CreateDiagnosticOptions = {},
+): Diagnostic {
+  return buildDiagnostic(code, diagnosticCatalog[code], details, options.docsBase);
+}

package/src/diagnostics/codes/live.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the LIVE area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the LIVE area, in the order they were added. */
+export const liveDiagnosticCodes = [
+  "MOSTRA_LIVE_TOO_LARGE",
+  "MOSTRA_LIVE_SOURCE_FAILED",
+  // gen:codes
+] as const;
+
+/** The codes of the LIVE area. */
+export type LiveDiagnosticCode = (typeof liveDiagnosticCodes)[number];
+
+/** The LIVE area's catalog entries. */
+export const liveDiagnostics: AreaCatalog<LiveDiagnosticCode> = {
+  MOSTRA_LIVE_TOO_LARGE: {
+    severity: "error",
+    phase: "runtime",
+    title: "Live value too large",
+    hint: "Push or produce a smaller value: at most 4 MiB serialized.",
+    docs: {
+      explanation:
+        "A live value, pushed or produced, is over 4 MiB once serialized (DATA_MODEL \u00a75). It is refused and the last good value stays.",
+      fix: "Send a smaller window of the data, or split it across several live sources. For high-rate series, push single points in append mode and let the page keep the window.",
+    },
+  },
+  MOSTRA_LIVE_SOURCE_FAILED: {
+    severity: "error",
+    phase: "runtime",
+    title: "Live source failed",
+    hint: "Read the message, fix the live source's loader or stream, and publish again; the last good value stays meanwhile.",
+    docs: {
+      explanation:
+        "A live source's `load` or `stream` threw, or its value was outside the serializable types. Pages keep showing the last good value with `useLive`'s `error` set, and the producer tries again on its schedule (FAILURE_MODEL \u00a76).",
+      fix: "Fix the producer in `live.ts`, or catch transient failures there and return the previous value.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/manifest.ts

@@ -0,0 +1,53 @@
+/**
+ * Diagnostic codes of the MANIFEST area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the MANIFEST area, in the order they were added. */
+export const manifestDiagnosticCodes = [
+  "MOSTRA_MANIFEST_NOT_LITERAL",
+  "MOSTRA_MANIFEST_INVALID",
+  "MOSTRA_MANIFEST_UNKNOWN_KEY",
+  // gen:codes
+] as const;
+
+/** The codes of the MANIFEST area. */
+export type ManifestDiagnosticCode = (typeof manifestDiagnosticCodes)[number];
+
+/** The MANIFEST area's catalog entries. */
+export const manifestDiagnostics: AreaCatalog<ManifestDiagnosticCode> = {
+  MOSTRA_MANIFEST_NOT_LITERAL: {
+    severity: "error",
+    phase: "manifest",
+    title: "Manifest isn't a literal",
+    hint: "Write the manifest as plain values: strings, numbers, booleans, null, arrays and objects, with no variables, calls, spreads or computed keys.",
+    docs: {
+      explanation:
+        "Mostra reads an artifact's manifest without running its code: the `export const artifact = defineArtifact({...})` in a TSX entry, or the frontmatter of an MDX entry. It reports this code when the exported `artifact` isn't a `defineArtifact(...)` call with one object literal, or when a value inside it needs evaluation (an identifier, a function call, a spread, a computed key, a template literal with a placeholder). The location points at the first such value.",
+      fix: 'Replace the value with the literal it stands for, for example `title: "Q3 review"` instead of `title: TITLE`. Keep computed values in the page code, where they can use anything. `as const` and `satisfies` on the object are fine.',
+    },
+  },
+  MOSTRA_MANIFEST_INVALID: {
+    severity: "error",
+    phase: "manifest",
+    title: "Manifest value is invalid",
+    hint: "Fix the manifest field named in the message so it matches the manifest's documented shape.",
+    docs: {
+      explanation:
+        "The manifest was read, but a field has a value the manifest doesn't allow: a missing `title`, a wrong type, an `id` that isn't an artifact ID (`art_` followed by a ULID), a `mode` this runtime doesn't build (`spa` is the only one), or frontmatter that isn't valid YAML. The message names the field and what was expected.",
+      fix: "Correct the field the message names. Leave `id` out to let Mostra bind the artifact to its source path at first publish, or keep the `id` that `mostra new` wrote. Every field except `title` is optional.",
+    },
+  },
+  MOSTRA_MANIFEST_UNKNOWN_KEY: {
+    severity: "warning",
+    phase: "manifest",
+    title: "Unknown manifest key",
+    hint: "Remove the key or correct its spelling; a newer Mostra may support it.",
+    docs: {
+      explanation:
+        "The manifest has a key this runtime doesn't know. Mostra ignores it, so manifests written for a newer release still publish, but a misspelled key (`familly`, `decription`) silently has no effect.",
+      fix: "Check the key against the manifest fields (`id`, `title`, `description`, `family`, `links`, `mode`, `submission`, `kit`, `terminals`, `demos`, `limits`, `verify`) and fix the spelling, or remove it.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/network.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostic codes of the NETWORK area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the NETWORK area, in the order they were added. */
+export const networkDiagnosticCodes = [
+  "MOSTRA_NETWORK_REQUEST_FAILED",
+  "MOSTRA_NETWORK_EXTERNAL_FAILED",
+  // gen:codes
+] as const;
+
+/** The codes of the NETWORK area. */
+export type NetworkDiagnosticCode = (typeof networkDiagnosticCodes)[number];
+
+/** The NETWORK area's catalog entries. */
+export const networkDiagnostics: AreaCatalog<NetworkDiagnosticCode> = {
+  MOSTRA_NETWORK_REQUEST_FAILED: {
+    severity: "error",
+    phase: "network",
+    title: "Request for the page's own resource failed",
+    hint: "Check the path: a file the page loads from the artifact itself failed to load.",
+    docs: {
+      explanation:
+        "A resource the page loaded from the artifact's own origin (the document, a script, a style, an image, a font, or a fetch by artifact code) failed or answered 4xx or 5xx. Requests the browser makes on its own, such as `/favicon.ico`, and Mostra's own protocol aren't counted.",
+      fix: "Put the file in `public/` (served at the root) or import it from the code so the build includes it, and check the path's spelling.",
+    },
+  },
+  MOSTRA_NETWORK_EXTERNAL_FAILED: {
+    severity: "warning",
+    phase: "network",
+    title: "Request to another origin failed",
+    hint: "A request to another origin failed while verify ran; check the URL and whether that service was reachable.",
+    docs: {
+      explanation:
+        "A request the page made to another origin failed or answered 4xx or 5xx. It may be the environment (no network, a service that is down, a request the service refuses from this origin) rather than the code, so it is a warning.",
+      fix: "Check the URL and the service. If the page depends on it, show a fallback when it fails.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/platform.ts

@@ -0,0 +1,30 @@
+/**
+ * Diagnostic codes of the PLATFORM area: the operating systems and architectures Mostra runs on
+ * (D35, RT-07).
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the PLATFORM area, in the order they were added. */
+export const platformDiagnosticCodes = [
+  "MOSTRA_PLATFORM_UNSUPPORTED",
+  // gen:codes
+] as const;
+
+/** The codes of the PLATFORM area. */
+export type PlatformDiagnosticCode = (typeof platformDiagnosticCodes)[number];
+
+/** The PLATFORM area's catalog entries. */
+export const platformDiagnostics: AreaCatalog<PlatformDiagnosticCode> = {
+  MOSTRA_PLATFORM_UNSUPPORTED: {
+    severity: "error",
+    phase: "platform",
+    title: "Unsupported platform",
+    hint: "Run Mostra on macOS or Linux, on an x64 or arm64 machine.",
+    docs: {
+      explanation:
+        "Mostra 1.0 runs on macOS and Linux, on x64 and arm64. On any other operating system or architecture, Windows included, every entry point stops with this code before it creates or changes anything, because the process model, sockets and storage are built and tested only on those platforms. The message names the platform that was detected.",
+      fix: "Run Mostra on a macOS or Linux machine with an x64 or arm64 processor. Windows support is planned for a release after 1.0.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/publish.ts

@@ -0,0 +1,53 @@
+/**
+ * Diagnostic codes of the PUBLISH area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the PUBLISH area, in the order they were added. */
+export const publishDiagnosticCodes = [
+  "MOSTRA_PUBLISH_ID_CONFLICT",
+  "MOSTRA_PUBLISH_SOURCE_CHANGED",
+  "MOSTRA_PUBLISH_VERIFY_FAILED",
+  // gen:codes
+] as const;
+
+/** The codes of the PUBLISH area. */
+export type PublishDiagnosticCode = (typeof publishDiagnosticCodes)[number];
+
+/** The PUBLISH area's catalog entries. */
+export const publishDiagnostics: AreaCatalog<PublishDiagnosticCode> = {
+  MOSTRA_PUBLISH_ID_CONFLICT: {
+    severity: "error",
+    phase: "publish",
+    title: "Artifact ID claimed by two sources",
+    hint: "Give one of the two sources a different `id`, or delete the `id` line from the copy so it becomes a new artifact.",
+    docs: {
+      explanation:
+        "An artifact's `id` names exactly one source. Mostra reports this code when a manifest claims an `id` that is already bound to another source path whose entry still claims it, which usually means a directory was copied. A source that moved, so that the old path no longer claims the `id`, is rebound instead. The message names both paths.",
+      fix: "Decide which source is the artifact. In the other one, remove the `id` from the manifest (it is then bound to its own path at its first publish) or replace it with a new ID from `mostra new`.",
+    },
+  },
+  MOSTRA_PUBLISH_SOURCE_CHANGED: {
+    severity: "error",
+    phase: "publish",
+    title: "Source changed during the publish",
+    hint: "Publish again once the artifact's files have stopped changing.",
+    docs: {
+      explanation:
+        "Publishing reads the entry's manifest twice: once to find the artifact, and again from the snapshot it builds. Mostra reports this code when the two disagree about which artifact the source is, because the manifest `id` or the source's binding changed while the publish ran, for example when an editor saved the entry mid-publish or another publish rebound the path. Nothing was published.",
+      fix: "Wait until the files are saved and nothing else is publishing the same source, then publish again. If the manifest `id` was changed on purpose, the next publish uses the new one.",
+    },
+  },
+  MOSTRA_PUBLISH_VERIFY_FAILED: {
+    severity: "error",
+    phase: "publish",
+    title: "Verify found errors",
+    hint: "Run `mostra verify` to see the errors and fix them, or publish with `--force` to record them in the version.",
+    docs: {
+      explanation:
+        "Publish runs verify (or reuses the verdict it cached for the same source and environment) and refuses when the verdict has errors (D41). The message lists their codes. Nothing was published. With `--force`, publish goes ahead and records the codes in the version, where hosts read them; a source that doesn't build can't be published either way.",
+      fix: "Fix the errors `mostra verify` reports and publish again, or publish with `--force` if the version must ship as it is.",
+    },
+  },
+  // gen:entries
+};

package/src/diagnostics/codes/regression.ts

@@ -0,0 +1,89 @@
+/**
+ * Diagnostic codes of the REGRESSION area.
+ */
+import type { AreaCatalog } from "../spec.ts";
+
+/** The codes of the REGRESSION area, in the order they were added. */
+export const regressionDiagnosticCodes = [
+  "MOSTRA_REGRESSION_ARIA",
+  "MOSTRA_REGRESSION_PIXELS",
+  "MOSTRA_REGRESSION_FIELD_REMOVED",
+  "MOSTRA_REGRESSION_ACTION_REMOVED",
+  "MOSTRA_REGRESSION_LIVE_REMOVED",
+  "MOSTRA_REGRESSION_PAGE_REMOVED",
+  // gen:codes
+] as const;
+
+/** The codes of the REGRESSION area. */
+export type RegressionDiagnosticCode = (typeof regressionDiagnosticCodes)[number];
+
+/** The REGRESSION area's catalog entries. */
+export const regressionDiagnostics: AreaCatalog<RegressionDiagnosticCode> = {
+  MOSTRA_REGRESSION_ARIA: {
+    severity: "warning",
+    phase: "regression",
+    title: "Controls or landmarks gone since the last passing version",
+    hint: "Observed only: the last passing version had these controls or landmarks and this source doesn't; a change that removed them on purpose needs nothing more.",
+    docs: {
+      explanation:
+        "Verify compared this source's accessibility snapshot with the newest version whose verdict passed, rendered in the same run with the same data. The controls or landmarks the message lists (by role and name) were there and aren't now. A redesign may remove them on purpose.",
+      fix: "If they should be gone, nothing needs to change. If not, look at what removed them.",
+    },
+  },
+  MOSTRA_REGRESSION_PIXELS: {
+    severity: "warning",
+    phase: "regression",
+    title: "Page looks different from the last passing version",
+    hint: "Observed only: this share of the viewport's pixels differs from the last passing version; an intended visual change shows here too and needs nothing more.",
+    docs: {
+      explanation:
+        "Verify rendered the newest version whose verdict passed and this source at the same viewport, clock and data, and the share of pixels the message gives differs between them. Any intended visual change shows here too.",
+      fix: "If the change is one you made on purpose, nothing needs to change. To see where it is, read the ARIA snapshots, or look at the diff image the message names if you can view images.",
+    },
+  },
+  MOSTRA_REGRESSION_FIELD_REMOVED: {
+    severity: "warning",
+    phase: "contract",
+    title: "Field gone since the last passing version",
+    hint: "Observed only: answers saved under this field ID won't carry over to this version; a field removed on purpose needs nothing more.",
+    docs: {
+      explanation:
+        "A field ID the last passing version used is gone from this source. Viewers' answers under it become orphans when they switch (D42): kept, shown read-only and delivered, but not editable. The message gives how many saved answers it affects.",
+      fix: "If the field was renamed by mistake, keep its old ID. If it was removed on purpose, nothing needs to change.",
+    },
+  },
+  MOSTRA_REGRESSION_ACTION_REMOVED: {
+    severity: "warning",
+    phase: "contract",
+    title: "Server function gone since the last passing version",
+    hint: "Observed only: the last passing version had this server function and this source doesn't; one removed on purpose needs nothing more.",
+    docs: {
+      explanation:
+        'A `"use server"` export the last passing version had is gone. Pages of the older version still call it while they are open, and keyed runs started by it can\'t be started again.',
+      fix: "If it was renamed by mistake, keep its name. If it was removed on purpose, nothing needs to change.",
+    },
+  },
+  MOSTRA_REGRESSION_LIVE_REMOVED: {
+    severity: "warning",
+    phase: "contract",
+    title: "Live source gone since the last passing version",
+    hint: "Observed only: the last passing version had this live source and this source doesn't; one removed on purpose needs nothing more.",
+    docs: {
+      explanation:
+        "A live source (`live.ts` export) the last passing version had is gone, so its producer stops and hosts that push to it push to a key no page reads.",
+      fix: "If it was renamed by mistake, keep its name. If it was removed on purpose, nothing needs to change.",
+    },
+  },
+  MOSTRA_REGRESSION_PAGE_REMOVED: {
+    severity: "warning",
+    phase: "contract",
+    title: "Page route gone since the last passing version",
+    hint: "Observed only: the last passing version had this page route and this source doesn't; one removed on purpose needs nothing more.",
+    docs: {
+      explanation:
+        "A route of `pages/` the last passing version had is gone, so links and bookmarks to it now open the artifact's fallback page.",
+      fix: "If it was renamed by mistake, keep its path. If it was removed on purpose, nothing needs to change.",
+    },
+  },
+  // gen:entries
+};