@mostra/protocol 0.0.0-placeholder → 0.1.0

package/dist/capability.js

@@ -0,0 +1,61 @@
+import { wireRegistry } from "./wire-registry.js";
+import * as z from "zod";
+//#region src/capability.ts
+/**
+* Capability links (D06, D97): the scopes a capability token grants and how long it lasts. A
+* token is the authorization: whoever holds its link may do what its scopes allow, and nothing
+* else limits an artifact or its viewers (D05).
+*/
+/** The Zod schema of the `CapabilityScope` type. */
+const CapabilityScope = z.string().regex(/^(view|draft|submit|review|signal|action:(\*|[^\s#*]+(#[^\s#*]+)?))$/).register(wireRegistry, {
+	id: "CapabilityScope",
+	description: "A capability token's scope: view, draft, submit, review, signal, action:*, action:<export> or action:<module path>#<export>."
+});
+/** Every scope at once: what a link minted without `scopes`, and every default link, carries. */
+const ALL_SCOPES = [
+	"view",
+	"draft",
+	"submit",
+	"review",
+	"signal",
+	"action:*"
+];
+/** The Zod schema of the `Duration` type. */
+const Duration = z.string().regex(/^[1-9][0-9]{0,8}[smhd]$/).register(wireRegistry, {
+	id: "Duration",
+	description: "A duration: a positive whole number and s, m, h or d, such as 30m, 24h or 7d."
+});
+const UNIT_MS = {
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+/** The length of a `Duration` in milliseconds. */
+function durationMs(duration) {
+	const unit = duration.slice(-1);
+	return Number(duration.slice(0, -1)) * UNIT_MS[unit];
+}
+/**
+* The scopes a token holds after normalization: `view` added, duplicates removed, sorted, so equal
+* grants compare equal.
+*/
+function normalizeScopes(scopes) {
+	return [.../* @__PURE__ */ new Set(["view", ...scopes])].sort();
+}
+/**
+* Whether `scopes` grant `required`. A plain scope must be held as written. An action scope
+* `action:<module path>#<export>` is granted by `action:*`, by `action:<export>` and by itself.
+*/
+function scopeAllows(scopes, required) {
+	if (scopes.includes(required)) return true;
+	if (!required.startsWith("action:")) return false;
+	if (scopes.includes("action:*")) return true;
+	const functionId = required.slice(7);
+	const hash = functionId.lastIndexOf("#");
+	return hash >= 0 && scopes.includes(`action:${functionId.slice(hash + 1)}`);
+}
+//#endregion
+export { ALL_SCOPES, CapabilityScope, Duration, durationMs, normalizeScopes, scopeAllows };
+
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","names":[],"sources":["../src/capability.ts"],"sourcesContent":["/**\n * Capability links (D06, D97): the scopes a capability token grants and how long it lasts. A\n * token is the authorization: whoever holds its link may do what its scopes allow, and nothing\n * else limits an artifact or its viewers (D05).\n */\nimport * as z from \"zod\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/**\n * What a capability token allows (HY-03, D97):\n * - `view`: open the artifact; every token has it.\n * - `draft`: save answers and other field values.\n * - `submit`: submit.\n * - `review`: comment and choose.\n * - `signal`: raise a signal for the host's attention (D10), which a waiting agent may act on.\n * - `action:*`: run every server function; `action:<export>` runs that export of any\n *   `\"use server\"` module; `action:<module path>#<export>` runs one function ID.\n */\nexport type CapabilityScope =\n  | \"view\"\n  | \"draft\"\n  | \"submit\"\n  | \"review\"\n  | \"signal\"\n  | `action:${string}`;\n\n/** The Zod schema of the `CapabilityScope` type. */\nexport const CapabilityScope: z.ZodType<CapabilityScope> = z\n  .string()\n  .regex(/^(view|draft|submit|review|signal|action:(\\*|[^\\s#*]+(#[^\\s#*]+)?))$/)\n  .register(wireRegistry, {\n    id: \"CapabilityScope\",\n    description:\n      \"A capability token's scope: view, draft, submit, review, signal, action:*, action:<export> or action:<module path>#<export>.\",\n  }) as z.ZodType<CapabilityScope>;\n\n/** Every scope at once: what a link minted without `scopes`, and every default link, carries. */\nexport const ALL_SCOPES: readonly CapabilityScope[] = [\n  \"view\",\n  \"draft\",\n  \"submit\",\n  \"review\",\n  \"signal\",\n  \"action:*\",\n];\n\n/**\n * A duration: a positive whole number and a unit, `s`, `m`, `h` or `d` (`30m`, `24h`, `7d`), as\n * INTERFACES §1 writes durations in flags and manifests.\n */\nexport type Duration = `${number}${\"s\" | \"m\" | \"h\" | \"d\"}`;\n\n/** The Zod schema of the `Duration` type. */\nexport const Duration: z.ZodType<Duration> = z\n  .string()\n  .regex(/^[1-9][0-9]{0,8}[smhd]$/)\n  .register(wireRegistry, {\n    id: \"Duration\",\n    description: \"A duration: a positive whole number and s, m, h or d, such as 30m, 24h or 7d.\",\n  }) as z.ZodType<Duration>;\n\nconst UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;\n\n/** The length of a `Duration` in milliseconds. */\nexport function durationMs(duration: Duration): number {\n  const unit = duration.slice(-1) as keyof typeof UNIT_MS;\n  return Number(duration.slice(0, -1)) * UNIT_MS[unit];\n}\n\n/**\n * The scopes a token holds after normalization: `view` added, duplicates removed, sorted, so equal\n * grants compare equal.\n */\nexport function normalizeScopes(scopes: readonly CapabilityScope[]): CapabilityScope[] {\n  return [...new Set<CapabilityScope>([\"view\", ...scopes])].sort();\n}\n\n/**\n * Whether `scopes` grant `required`. A plain scope must be held as written. An action scope\n * `action:<module path>#<export>` is granted by `action:*`, by `action:<export>` and by itself.\n */\nexport function scopeAllows(\n  scopes: readonly CapabilityScope[],\n  required: CapabilityScope,\n): boolean {\n  if (scopes.includes(required)) return true;\n  if (!required.startsWith(\"action:\")) return false;\n  if (scopes.includes(\"action:*\")) return true;\n  const functionId = required.slice(\"action:\".length);\n  const hash = functionId.lastIndexOf(\"#\");\n  return hash >= 0 && scopes.includes(`action:${functionId.slice(hash + 1)}`);\n}\n"],"mappings":";;;;;;;;;AA2BA,MAAa,kBAA8C,EACxD,OAAO,CAAC,CACR,MAAM,sEAAsE,CAAC,CAC7E,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC;;AAGH,MAAa,aAAyC;CACpD;CACA;CACA;CACA;CACA;CACA;AACF;;AASA,MAAa,WAAgC,EAC1C,OAAO,CAAC,CACR,MAAM,yBAAyB,CAAC,CAChC,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;AAEH,MAAM,UAAU;CAAE,GAAG;CAAO,GAAG;CAAQ,GAAG;CAAW,GAAG;AAAW;;AAGnE,SAAgB,WAAW,UAA4B;CACrD,MAAM,OAAO,SAAS,MAAM,EAAE;CAC9B,OAAO,OAAO,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ;AACjD;;;;;AAMA,SAAgB,gBAAgB,QAAuD;CACrF,OAAO,CAAC,mBAAG,IAAI,IAAqB,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK;AACjE;;;;;AAMA,SAAgB,YACd,QACA,UACS;CACT,IAAI,OAAO,SAAS,QAAQ,GAAG,OAAO;CACtC,IAAI,CAAC,SAAS,WAAW,SAAS,GAAG,OAAO;CAC5C,IAAI,OAAO,SAAS,UAAU,GAAG,OAAO;CACxC,MAAM,aAAa,SAAS,MAAM,CAAgB;CAClD,MAAM,OAAO,WAAW,YAAY,GAAG;CACvC,OAAO,QAAQ,KAAK,OAAO,SAAS,UAAU,WAAW,MAAM,OAAO,CAAC,GAAG;AAC5E"}

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

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/a11y.d.ts
+/** The codes of the A11Y area, in the order they were added. */
+export declare const a11yDiagnosticCodes: readonly ["MOSTRA_A11Y_SERIOUS", "MOSTRA_A11Y_MINOR"];
+/** The codes of the A11Y area. */
+export type A11yDiagnosticCode = (typeof a11yDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=a11y.d.ts.map

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

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

package/dist/diagnostics/codes/a11y.js

@@ -0,0 +1,30 @@
+//#region src/diagnostics/codes/a11y.ts
+/** The codes of the A11Y area, in the order they were added. */
+const a11yDiagnosticCodes = ["MOSTRA_A11Y_SERIOUS", "MOSTRA_A11Y_MINOR"];
+/** The A11Y area's catalog entries. */
+const a11yDiagnostics = {
+	MOSTRA_A11Y_SERIOUS: {
+		severity: "warning",
+		phase: "a11y",
+		title: "Serious accessibility problem",
+		hint: "Read axe's description of the rule in the message; it names the elements it found.",
+		docs: {
+			explanation: "axe-core found a problem it rates critical or serious, such as a button with no accessible name or text with too little contrast. The message names axe's rule and the elements; `count` says how many.",
+			fix: "Follow the rule's advice for each element named, for example add an `aria-label` to an icon button."
+		}
+	},
+	MOSTRA_A11Y_MINOR: {
+		severity: "hint",
+		phase: "a11y",
+		title: "Minor accessibility problem",
+		hint: "Read axe's description of the rule in the message.",
+		docs: {
+			explanation: "axe-core found a problem it rates moderate or minor. The message names axe's rule and the elements.",
+			fix: "Optionally follow the rule's advice."
+		}
+	}
+};
+//#endregion
+export { a11yDiagnosticCodes, a11yDiagnostics };
+
+//# sourceMappingURL=a11y.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.js","names":[],"sources":["../../../src/diagnostics/codes/a11y.ts"],"sourcesContent":["/**\n * Diagnostic codes of the A11Y area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the A11Y area, in the order they were added. */\nexport const a11yDiagnosticCodes = [\n  \"MOSTRA_A11Y_SERIOUS\",\n  \"MOSTRA_A11Y_MINOR\",\n  // gen:codes\n] as const;\n\n/** The codes of the A11Y area. */\nexport type A11yDiagnosticCode = (typeof a11yDiagnosticCodes)[number];\n\n/** The A11Y area's catalog entries. */\nexport const a11yDiagnostics: AreaCatalog<A11yDiagnosticCode> = {\n  MOSTRA_A11Y_SERIOUS: {\n    severity: \"warning\",\n    phase: \"a11y\",\n    title: \"Serious accessibility problem\",\n    hint: \"Read axe's description of the rule in the message; it names the elements it found.\",\n    docs: {\n      explanation:\n        \"axe-core found a problem it rates critical or serious, such as a button with no accessible name or text with too little contrast. The message names axe's rule and the elements; `count` says how many.\",\n      fix: \"Follow the rule's advice for each element named, for example add an `aria-label` to an icon button.\",\n    },\n  },\n  MOSTRA_A11Y_MINOR: {\n    severity: \"hint\",\n    phase: \"a11y\",\n    title: \"Minor accessibility problem\",\n    hint: \"Read axe's description of the rule in the message.\",\n    docs: {\n      explanation:\n        \"axe-core found a problem it rates moderate or minor. The message names axe's rule and the elements.\",\n      fix: \"Optionally follow the rule's advice.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,sBAAsB,CACjC,uBACA,mBAEF;;AAMA,MAAa,kBAAmD;CAC9D,qBAAqB;EACnB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,mBAAmB;EACjB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

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

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/action.d.ts
+/** The codes of the ACTION area, in the order they were added. */
+export declare const actionDiagnosticCodes: readonly ["MOSTRA_ACTION_EXPORT_INVALID", "MOSTRA_ACTION_UNSERIALIZABLE", "MOSTRA_ACTION_THREW", "MOSTRA_ACTION_UNKNOWN_FUNCTION", "MOSTRA_ACTION_INTERRUPTED", "MOSTRA_ACTION_CANCELLED", "MOSTRA_ACTION_TOO_LARGE", "MOSTRA_ACTION_RUN_NOT_FOUND", "MOSTRA_ACTION_EVENT_INVALID"];
+/** The codes of the ACTION area. */
+export type ActionDiagnosticCode = (typeof actionDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","names":[],"sources":["../../../src/diagnostics/codes/action.ts"],"mappings":";;;qBAMa;;YAcD,+BAA+B"}

package/dist/diagnostics/codes/action.js

@@ -0,0 +1,110 @@
+//#region src/diagnostics/codes/action.ts
+/** The codes of the ACTION area, in the order they were added. */
+const actionDiagnosticCodes = [
+	"MOSTRA_ACTION_EXPORT_INVALID",
+	"MOSTRA_ACTION_UNSERIALIZABLE",
+	"MOSTRA_ACTION_THREW",
+	"MOSTRA_ACTION_UNKNOWN_FUNCTION",
+	"MOSTRA_ACTION_INTERRUPTED",
+	"MOSTRA_ACTION_CANCELLED",
+	"MOSTRA_ACTION_TOO_LARGE",
+	"MOSTRA_ACTION_RUN_NOT_FOUND",
+	"MOSTRA_ACTION_EVENT_INVALID"
+];
+/** The ACTION area's catalog entries. */
+const actionDiagnostics = {
+	MOSTRA_ACTION_EXPORT_INVALID: {
+		severity: "error",
+		phase: "compile",
+		title: "Server module exports something other than an async function",
+		hint: "Export only async functions from a \"use server\" module; move other exports to an ordinary module.",
+		docs: {
+			explanation: "A module that starts with `\"use server\"` makes every export a server function the page can call. React's contract allows only async functions there. Mostra reports this code for any other export (a constant, a class, a non-async function, `export *`), naming the export.",
+			fix: "Make the function `async`, or move the value to a separate module without the directive and import it from both sides."
+		}
+	},
+	MOSTRA_ACTION_UNSERIALIZABLE: {
+		severity: "error",
+		phase: "runtime",
+		title: "Server function argument or result outside React's serializable types",
+		hint: "Pass and return only plain objects, arrays, primitives, Map, Set, Date, typed arrays, FormData and promises; convert class instances to plain objects first.",
+		docs: {
+			explanation: "Server function arguments and results cross a process boundary, so Mostra accepts exactly the types React documents for Server Functions (D54): strings, numbers, bigints, booleans, `undefined`, `null`, symbols registered with `Symbol.for`, arrays, `Map`, `Set`, typed arrays, `ArrayBuffer`, `Date`, `FormData`, plain objects, other server functions and promises. A result may also be an async iterable, whose items stream to the page. Mostra reports this code for anything else (a class instance, an `Error`, a `RegExp`, an object with a null prototype, a function that isn't a server function, an unregistered symbol, JSX) and names where in the value it is, such as `Argument 2 at .items[1]`. A promise in an argument that rejects fails the call the same way.",
+			fix: "Convert the value to the supported types before the call or the return: `{ ...instance }` or a mapping for class instances, `error.message` for errors and `regexp.source` for regular expressions."
+		}
+	},
+	MOSTRA_ACTION_THREW: {
+		severity: "error",
+		phase: "runtime",
+		title: "Server function threw",
+		hint: "Read the run's log for the stack, then fix the server function or catch the error and return a result instead.",
+		docs: {
+			explanation: "A server function threw while it ran. The page gets `{ code: \"MOSTRA_ACTION_THREW\", message }` with the thrown error's message (`useAction`'s `error`, or the rejected promise of a plain call); the stack goes to the action run's log, never to the page. When the error carried a diagnostic code of its own (a `MOSTRA_SECRET_MISSING`, say), that code is reported instead.",
+			fix: "Fix the cause in the function, or catch the error inside it and return a value the page can show. Mostra never retries a run by itself (D24); retry in your own code, or call the action again with a new key."
+		}
+	},
+	MOSTRA_ACTION_UNKNOWN_FUNCTION: {
+		severity: "error",
+		phase: "runtime",
+		title: "No such server function in this version",
+		hint: "Publish the artifact again so the page and its server code come from the same version.",
+		docs: {
+			explanation: "The page called a server function ID (`<module path>#<export>`) that the version's server bundle doesn't export. Pages call only functions their own build references, so this means a page and a worker of different versions, or a request written by hand.",
+			fix: "Republish the artifact and reload the page. Call server functions by importing them from their `\"use server\"` module, never by ID."
+		}
+	},
+	MOSTRA_ACTION_INTERRUPTED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Action run interrupted",
+		hint: "Check the run's effects at their provider, then start it again with a new key if it should run again.",
+		docs: {
+			explanation: "The action run's worker crashed, ran out of memory, was stopped by the event-loop watchdog, or the instance stopped while the run was running. The run ends `failed` with the reason `interrupted`, and Mostra never retries it by itself (D24): an action that had already started a side effect, such as sending an email, may or may not have finished it.",
+			fix: "Look at the effect where it happens (the mail provider's sent folder, say) before running the action again. Pass the provider's own idempotency key from the action (for example, the run's key) so a repeated request can't act twice."
+		}
+	},
+	MOSTRA_ACTION_CANCELLED: {
+		severity: "warning",
+		phase: "runtime",
+		title: "Action run cancelled",
+		hint: "Start the action again if it should still run.",
+		docs: {
+			explanation: "The action run was cancelled from a page, and its `abortSignal` fired. The run ends `cancelled` when the action stops; an action that ignores the signal ends with whatever it returns.",
+			fix: "Nothing to fix. Pass `abortSignal` from `@mostra/server` to `fetch` and other cancellable calls so cancelling stops the work."
+		}
+	},
+	MOSTRA_ACTION_TOO_LARGE: {
+		severity: "error",
+		phase: "runtime",
+		title: "Server function arguments or result too large",
+		hint: "Return or pass less data: page through it, or write it to artifact state or a live source instead.",
+		docs: {
+			explanation: "A server function's serialized arguments, or an action run's serialized result, is over 16 MiB. A plain call or run with arguments that large is refused before it starts; a run whose result grows past the limit is stopped and ends `failed`.",
+			fix: "Send identifiers rather than whole documents, return a page of results at a time, or publish large data through a live source or artifact state, which the page reads on its own."
+		}
+	},
+	MOSTRA_ACTION_RUN_NOT_FOUND: {
+		severity: "error",
+		phase: "runtime",
+		title: "No such action run",
+		hint: "Start the action again; the run ID names no run of this artifact.",
+		docs: {
+			explanation: "A page asked for or cancelled an action run that this artifact doesn't have, or one started from another artifact.",
+			fix: "Use the run IDs `useAction` reports. A page that keeps run IDs itself should drop IDs from other artifacts."
+		}
+	},
+	MOSTRA_ACTION_EVENT_INVALID: {
+		severity: "error",
+		phase: "runtime",
+		title: "Host event type or payload invalid",
+		hint: "Name the event `host.<name>` with 1 to 64 letters, digits, `.`, `_` and `-`, and keep its payload JSON of at most 64 KiB.",
+		docs: {
+			explanation: "Server code called `emit(type, payload)` from `@mostra/server` with a type that isn't `host.` followed by a name, or a payload that isn't JSON or is larger than 64 KiB. The event is not appended; `emit` throws.",
+			fix: "Use a type such as `host.reply-sent` and a small JSON payload. Put larger data in artifact state or a live source and send its key in the event."
+		}
+	}
+};
+//#endregion
+export { actionDiagnosticCodes, actionDiagnostics };
+
+//# sourceMappingURL=action.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","names":[],"sources":["../../../src/diagnostics/codes/action.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ACTION area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ACTION area, in the order they were added. */\nexport const actionDiagnosticCodes = [\n  \"MOSTRA_ACTION_EXPORT_INVALID\",\n  \"MOSTRA_ACTION_UNSERIALIZABLE\",\n  \"MOSTRA_ACTION_THREW\",\n  \"MOSTRA_ACTION_UNKNOWN_FUNCTION\",\n  \"MOSTRA_ACTION_INTERRUPTED\",\n  \"MOSTRA_ACTION_CANCELLED\",\n  \"MOSTRA_ACTION_TOO_LARGE\",\n  \"MOSTRA_ACTION_RUN_NOT_FOUND\",\n  \"MOSTRA_ACTION_EVENT_INVALID\",\n  // gen:codes\n] as const;\n\n/** The codes of the ACTION area. */\nexport type ActionDiagnosticCode = (typeof actionDiagnosticCodes)[number];\n\n/** The ACTION area's catalog entries. */\nexport const actionDiagnostics: AreaCatalog<ActionDiagnosticCode> = {\n  MOSTRA_ACTION_EXPORT_INVALID: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Server module exports something other than an async function\",\n    hint: 'Export only async functions from a \"use server\" module; move other exports to an ordinary module.',\n    docs: {\n      explanation:\n        'A module that starts with `\"use server\"` makes every export a server function the page can call. React\\'s contract allows only async functions there. Mostra reports this code for any other export (a constant, a class, a non-async function, `export *`), naming the export.',\n      fix: \"Make the function `async`, or move the value to a separate module without the directive and import it from both sides.\",\n    },\n  },\n  MOSTRA_ACTION_UNSERIALIZABLE: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Server function argument or result outside React's serializable types\",\n    hint: \"Pass and return only plain objects, arrays, primitives, Map, Set, Date, typed arrays, FormData and promises; convert class instances to plain objects first.\",\n    docs: {\n      explanation:\n        \"Server function arguments and results cross a process boundary, so Mostra accepts exactly the types React documents for Server Functions (D54): strings, numbers, bigints, booleans, `undefined`, `null`, symbols registered with `Symbol.for`, arrays, `Map`, `Set`, typed arrays, `ArrayBuffer`, `Date`, `FormData`, plain objects, other server functions and promises. A result may also be an async iterable, whose items stream to the page. Mostra reports this code for anything else (a class instance, an `Error`, a `RegExp`, an object with a null prototype, a function that isn't a server function, an unregistered symbol, JSX) and names where in the value it is, such as `Argument 2 at .items[1]`. A promise in an argument that rejects fails the call the same way.\",\n      fix: \"Convert the value to the supported types before the call or the return: `{ ...instance }` or a mapping for class instances, `error.message` for errors and `regexp.source` for regular expressions.\",\n    },\n  },\n  MOSTRA_ACTION_THREW: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Server function threw\",\n    hint: \"Read the run's log for the stack, then fix the server function or catch the error and return a result instead.\",\n    docs: {\n      explanation:\n        \"A server function threw while it ran. The page gets `{ code: \\\"MOSTRA_ACTION_THREW\\\", message }` with the thrown error's message (`useAction`'s `error`, or the rejected promise of a plain call); the stack goes to the action run's log, never to the page. When the error carried a diagnostic code of its own (a `MOSTRA_SECRET_MISSING`, say), that code is reported instead.\",\n      fix: \"Fix the cause in the function, or catch the error inside it and return a value the page can show. Mostra never retries a run by itself (D24); retry in your own code, or call the action again with a new key.\",\n    },\n  },\n  MOSTRA_ACTION_UNKNOWN_FUNCTION: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"No such server function in this version\",\n    hint: \"Publish the artifact again so the page and its server code come from the same version.\",\n    docs: {\n      explanation:\n        \"The page called a server function ID (`<module path>#<export>`) that the version's server bundle doesn't export. Pages call only functions their own build references, so this means a page and a worker of different versions, or a request written by hand.\",\n      fix: 'Republish the artifact and reload the page. Call server functions by importing them from their `\"use server\"` module, never by ID.',\n    },\n  },\n  MOSTRA_ACTION_INTERRUPTED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Action run interrupted\",\n    hint: \"Check the run's effects at their provider, then start it again with a new key if it should run again.\",\n    docs: {\n      explanation:\n        \"The action run's worker crashed, ran out of memory, was stopped by the event-loop watchdog, or the instance stopped while the run was running. The run ends `failed` with the reason `interrupted`, and Mostra never retries it by itself (D24): an action that had already started a side effect, such as sending an email, may or may not have finished it.\",\n      fix: \"Look at the effect where it happens (the mail provider's sent folder, say) before running the action again. Pass the provider's own idempotency key from the action (for example, the run's key) so a repeated request can't act twice.\",\n    },\n  },\n  MOSTRA_ACTION_CANCELLED: {\n    severity: \"warning\",\n    phase: \"runtime\",\n    title: \"Action run cancelled\",\n    hint: \"Start the action again if it should still run.\",\n    docs: {\n      explanation:\n        \"The action run was cancelled from a page, and its `abortSignal` fired. The run ends `cancelled` when the action stops; an action that ignores the signal ends with whatever it returns.\",\n      fix: \"Nothing to fix. Pass `abortSignal` from `@mostra/server` to `fetch` and other cancellable calls so cancelling stops the work.\",\n    },\n  },\n  MOSTRA_ACTION_TOO_LARGE: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Server function arguments or result too large\",\n    hint: \"Return or pass less data: page through it, or write it to artifact state or a live source instead.\",\n    docs: {\n      explanation:\n        \"A server function's serialized arguments, or an action run's serialized result, is over 16 MiB. A plain call or run with arguments that large is refused before it starts; a run whose result grows past the limit is stopped and ends `failed`.\",\n      fix: \"Send identifiers rather than whole documents, return a page of results at a time, or publish large data through a live source or artifact state, which the page reads on its own.\",\n    },\n  },\n  MOSTRA_ACTION_RUN_NOT_FOUND: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"No such action run\",\n    hint: \"Start the action again; the run ID names no run of this artifact.\",\n    docs: {\n      explanation:\n        \"A page asked for or cancelled an action run that this artifact doesn't have, or one started from another artifact.\",\n      fix: \"Use the run IDs `useAction` reports. A page that keeps run IDs itself should drop IDs from other artifacts.\",\n    },\n  },\n  MOSTRA_ACTION_EVENT_INVALID: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Host event type or payload invalid\",\n    hint: \"Name the event `host.<name>` with 1 to 64 letters, digits, `.`, `_` and `-`, and keep its payload JSON of at most 64 KiB.\",\n    docs: {\n      explanation:\n        \"Server code called `emit(type, payload)` from `@mostra/server` with a type that isn't `host.` followed by a name, or a payload that isn't JSON or is larger than 64 KiB. The event is not appended; `emit` throws.\",\n      fix: \"Use a type such as `host.reply-sent` and a small JSON payload. Put larger data in artifact state or a live source and send its key in the event.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,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,gCAAgC;EAC9B,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,yBAAyB;EACvB,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,6BAA6B;EAC3B,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/artifact.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/artifact.d.ts
+/** The codes of the ARTIFACT area, in the order they were added. */
+export declare const artifactDiagnosticCodes: readonly ["MOSTRA_ARTIFACT_NOT_FOUND", "MOSTRA_ARTIFACT_SOURCE_MISSING", "MOSTRA_ARTIFACT_SOURCE_UNREADABLE", "MOSTRA_ARTIFACT_NO_ENTRY", "MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS", "MOSTRA_ARTIFACT_NO_PAGE", "MOSTRA_ARTIFACT_DIR_NOT_EMPTY", "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN", "MOSTRA_ARTIFACT_VERSION_NOT_FOUND", "MOSTRA_ARTIFACT_VERSION_COLLECTED"];
+/** The codes of the ARTIFACT area. */
+export type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=artifact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"mappings":";;;qBAMa;;YAeD,iCAAiC"}

package/dist/diagnostics/codes/artifact.js

@@ -0,0 +1,121 @@
+//#region src/diagnostics/codes/artifact.ts
+/** The codes of the ARTIFACT area, in the order they were added. */
+const artifactDiagnosticCodes = [
+	"MOSTRA_ARTIFACT_NOT_FOUND",
+	"MOSTRA_ARTIFACT_SOURCE_MISSING",
+	"MOSTRA_ARTIFACT_SOURCE_UNREADABLE",
+	"MOSTRA_ARTIFACT_NO_ENTRY",
+	"MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS",
+	"MOSTRA_ARTIFACT_NO_PAGE",
+	"MOSTRA_ARTIFACT_DIR_NOT_EMPTY",
+	"MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
+	"MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
+	"MOSTRA_ARTIFACT_VERSION_COLLECTED"
+];
+/** The ARTIFACT area's catalog entries. */
+const artifactDiagnostics = {
+	MOSTRA_ARTIFACT_NOT_FOUND: {
+		severity: "error",
+		phase: "host",
+		title: "Artifact not found",
+		hint: "Check the artifact ID or source path, or list the home's artifacts with `mostra list`.",
+		docs: {
+			explanation: "The artifact named by an ID or a source path doesn't exist in this home: the ID was never published here, or the path was never published.",
+			fix: "Use an ID or path from `mostra list`. A source that was never published becomes an artifact at its first `mostra publish`. A host that uses its own home sees only the artifacts published there."
+		}
+	},
+	MOSTRA_ARTIFACT_SOURCE_MISSING: {
+		severity: "error",
+		phase: "publish",
+		title: "Artifact source missing",
+		hint: "Publish from the artifact's source path, or restore the directory the message names.",
+		docs: {
+			explanation: "Publishing needs the artifact's source files. The path given, or the path the artifact was last published from, doesn't exist. Versions already published stay readable, because Mostra keeps a snapshot of their source in the home.",
+			fix: "Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path."
+		}
+	},
+	MOSTRA_ARTIFACT_SOURCE_UNREADABLE: {
+		severity: "error",
+		phase: "publish",
+		title: "Artifact source can't be read",
+		hint: "Fix the file or directory the message names so your user can read it, then publish again.",
+		docs: {
+			explanation: "Mostra couldn't read a file of the artifact's source: permissions, a file that disappeared while it was copied, or two names that are the same after Unicode normalization. Nothing was published.",
+			fix: "Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root."
+		}
+	},
+	MOSTRA_ARTIFACT_NO_ENTRY: {
+		severity: "error",
+		phase: "manifest",
+		title: "No entry file",
+		hint: "Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.",
+		docs: {
+			explanation: "An artifact is a single `.tsx`, `.jsx` or `.mdx` file, or a directory whose entry is `index.tsx`, `index.jsx` or `index.mdx`. The source given is neither.",
+			fix: "Create the entry: its default export is the page, and its manifest is `export const artifact = defineArtifact({ title: \"...\" })` (or frontmatter in MDX). For a single page, publish the file itself."
+		}
+	},
+	MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS: {
+		severity: "error",
+		phase: "manifest",
+		title: "More than one entry file",
+		hint: "Keep one entry file in the directory and rename or remove the others.",
+		docs: {
+			explanation: "A directory artifact has exactly one entry, and this directory has more than one of `index.tsx`, `index.jsx` and `index.mdx`, so Mostra can't tell which one is the page.",
+			fix: "Keep the entry you mean and rename the others, for example into `components/`."
+		}
+	},
+	MOSTRA_ARTIFACT_NO_PAGE: {
+		severity: "error",
+		phase: "manifest",
+		title: "Entry has no page",
+		hint: "Export the page component as the entry's default export, or add a `pages/` folder.",
+		docs: {
+			explanation: "The entry has no default export and the artifact has no `pages/` folder, so there is nothing to render. With `pages/`, each file there is a route and the entry's default export, when present, is the layout around them.",
+			fix: "Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on."
+		}
+	},
+	MOSTRA_ARTIFACT_DIR_NOT_EMPTY: {
+		severity: "error",
+		phase: "host",
+		title: "Directory isn't empty",
+		hint: "Choose a new or empty directory for the artifact.",
+		docs: {
+			explanation: "Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.",
+			fix: "Pass a path that doesn't exist yet or an empty directory. To make existing files an artifact, add the entry yourself and publish."
+		}
+	},
+	MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN: {
+		severity: "error",
+		phase: "host",
+		title: "Unknown template",
+		hint: "Create the artifact without a template, or use a template this Mostra release provides.",
+		docs: {
+			explanation: "The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.",
+			fix: "Leave out the template, or use one of the templates of this release."
+		}
+	},
+	MOSTRA_ARTIFACT_VERSION_NOT_FOUND: {
+		severity: "error",
+		phase: "host",
+		title: "No such version",
+		hint: "Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.",
+		docs: {
+			explanation: "The request named a version number or version ID that this artifact never published in this home. Viewers only ever open published versions (D09), so there is nothing to show.",
+			fix: "List the artifact's versions with `artifact/get` and pick one, or omit the version to open the latest. A link to `/a/<artifactId>/v/<number>` needs a number from that list."
+		}
+	},
+	MOSTRA_ARTIFACT_VERSION_COLLECTED: {
+		severity: "error",
+		phase: "host",
+		title: "Version collected",
+		hint: "Open the artifact's latest version, or publish this version's source again to restore its files.",
+		docs: {
+			explanation: "`mostra gc` removed this version's files because nothing referenced it (D140). Its ID and number stay in the ledger forever, so history and events still name it, but it can't be opened or linked.",
+			fix: "Open a version that still exists (`artifact/get` marks collected ones), or publish the exact source of this version again: publish restores its files under the same ID and number."
+		}
+	}
+};
+//#endregion
+export { artifactDiagnosticCodes, artifactDiagnostics };
+
+//# sourceMappingURL=artifact.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","names":[],"sources":["../../../src/diagnostics/codes/artifact.ts"],"sourcesContent":["/**\n * Diagnostic codes of the ARTIFACT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the ARTIFACT area, in the order they were added. */\nexport const artifactDiagnosticCodes = [\n  \"MOSTRA_ARTIFACT_NOT_FOUND\",\n  \"MOSTRA_ARTIFACT_SOURCE_MISSING\",\n  \"MOSTRA_ARTIFACT_SOURCE_UNREADABLE\",\n  \"MOSTRA_ARTIFACT_NO_ENTRY\",\n  \"MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS\",\n  \"MOSTRA_ARTIFACT_NO_PAGE\",\n  \"MOSTRA_ARTIFACT_DIR_NOT_EMPTY\",\n  \"MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN\",\n  \"MOSTRA_ARTIFACT_VERSION_NOT_FOUND\",\n  \"MOSTRA_ARTIFACT_VERSION_COLLECTED\",\n  // gen:codes\n] as const;\n\n/** The codes of the ARTIFACT area. */\nexport type ArtifactDiagnosticCode = (typeof artifactDiagnosticCodes)[number];\n\n/** The ARTIFACT area's catalog entries. */\nexport const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {\n  MOSTRA_ARTIFACT_NOT_FOUND: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Artifact not found\",\n    hint: \"Check the artifact ID or source path, or list the home's artifacts with `mostra list`.\",\n    docs: {\n      explanation:\n        \"The artifact named by an ID or a source path doesn't exist in this home: the ID was never published here, or the path was never published.\",\n      fix: \"Use an ID or path from `mostra list`. A source that was never published becomes an artifact at its first `mostra publish`. A host that uses its own home sees only the artifacts published there.\",\n    },\n  },\n  MOSTRA_ARTIFACT_SOURCE_MISSING: {\n    severity: \"error\",\n    phase: \"publish\",\n    title: \"Artifact source missing\",\n    hint: \"Publish from the artifact's source path, or restore the directory the message names.\",\n    docs: {\n      explanation:\n        \"Publishing needs the artifact's source files. The path given, or the path the artifact was last published from, doesn't exist. Versions already published stay readable, because Mostra keeps a snapshot of their source in the home.\",\n      fix: \"Pass the path where the source lives now. Its manifest `id`, if it has one, keeps the artifact identity at the new path.\",\n    },\n  },\n  MOSTRA_ARTIFACT_SOURCE_UNREADABLE: {\n    severity: \"error\",\n    phase: \"publish\",\n    title: \"Artifact source can't be read\",\n    hint: \"Fix the file or directory the message names so your user can read it, then publish again.\",\n    docs: {\n      explanation:\n        \"Mostra couldn't read a file of the artifact's source: permissions, a file that disappeared while it was copied, or two names that are the same after Unicode normalization. Nothing was published.\",\n      fix: \"Make the named file readable, rename one of two clashing names, or exclude the file with `.mostraignore` in the artifact's root.\",\n    },\n  },\n  MOSTRA_ARTIFACT_NO_ENTRY: {\n    severity: \"error\",\n    phase: \"manifest\",\n    title: \"No entry file\",\n    hint: \"Add `index.tsx` or `index.mdx` to the directory, or publish a single `.tsx` or `.mdx` file.\",\n    docs: {\n      explanation:\n        \"An artifact is a single `.tsx`, `.jsx` or `.mdx` file, or a directory whose entry is `index.tsx`, `index.jsx` or `index.mdx`. The source given is neither.\",\n      fix: 'Create the entry: its default export is the page, and its manifest is `export const artifact = defineArtifact({ title: \"...\" })` (or frontmatter in MDX). For a single page, publish the file itself.',\n    },\n  },\n  MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS: {\n    severity: \"error\",\n    phase: \"manifest\",\n    title: \"More than one entry file\",\n    hint: \"Keep one entry file in the directory and rename or remove the others.\",\n    docs: {\n      explanation:\n        \"A directory artifact has exactly one entry, and this directory has more than one of `index.tsx`, `index.jsx` and `index.mdx`, so Mostra can't tell which one is the page.\",\n      fix: \"Keep the entry you mean and rename the others, for example into `components/`.\",\n    },\n  },\n  MOSTRA_ARTIFACT_NO_PAGE: {\n    severity: \"error\",\n    phase: \"manifest\",\n    title: \"Entry has no page\",\n    hint: \"Export the page component as the entry's default export, or add a `pages/` folder.\",\n    docs: {\n      explanation:\n        \"The entry has no default export and the artifact has no `pages/` folder, so there is nothing to render. With `pages/`, each file there is a route and the entry's default export, when present, is the layout around them.\",\n      fix: \"Add `export default function Page() { ... }` to the entry, or move pages into `pages/index.tsx`, `pages/settings.tsx` and so on.\",\n    },\n  },\n  MOSTRA_ARTIFACT_DIR_NOT_EMPTY: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Directory isn't empty\",\n    hint: \"Choose a new or empty directory for the artifact.\",\n    docs: {\n      explanation:\n        \"Creating an artifact writes its entry into a directory, and the directory given already has files. Mostra never overwrites them.\",\n      fix: \"Pass a path that doesn't exist yet or an empty directory. To make existing files an artifact, add the entry yourself and publish.\",\n    },\n  },\n  MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Unknown template\",\n    hint: \"Create the artifact without a template, or use a template this Mostra release provides.\",\n    docs: {\n      explanation:\n        \"The template named isn't one this runtime provides. Without a template, Mostra writes a minimal entry with a generated artifact ID.\",\n      fix: \"Leave out the template, or use one of the templates of this release.\",\n    },\n  },\n  MOSTRA_ARTIFACT_VERSION_NOT_FOUND: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"No such version\",\n    hint: \"Name a version the artifact has (`artifact/get` lists them), or leave the version out for the latest.\",\n    docs: {\n      explanation:\n        \"The request named a version number or version ID that this artifact never published in this home. Viewers only ever open published versions (D09), so there is nothing to show.\",\n      fix: \"List the artifact's versions with `artifact/get` and pick one, or omit the version to open the latest. A link to `/a/<artifactId>/v/<number>` needs a number from that list.\",\n    },\n  },\n  MOSTRA_ARTIFACT_VERSION_COLLECTED: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Version collected\",\n    hint: \"Open the artifact's latest version, or publish this version's source again to restore its files.\",\n    docs: {\n      explanation:\n        \"`mostra gc` removed this version's files because nothing referenced it (D140). Its ID and number stay in the ledger forever, so history and events still name it, but it can't be opened or linked.\",\n      fix: \"Open a version that still exists (`artifact/get` marks collected ones), or publish the exact source of this version again: publish restores its files under the same ID and number.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,sBAA2D;CACtE,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,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,0BAA0B;EACxB,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,yBAAyB;EACvB,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,kCAAkC;EAChC,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,mCAAmC;EACjC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

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

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/build.d.ts
+/** The codes of the BUILD area, in the order they were added. */
+export declare const buildDiagnosticCodes: readonly ["MOSTRA_BUILD_FAILED", "MOSTRA_BUILD_UNRESOLVED", "MOSTRA_BUILD_CRASHED", "MOSTRA_BUILD_TIMEOUT"];
+/** The codes of the BUILD area. */
+export type BuildDiagnosticCode = (typeof buildDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=build.d.ts.map

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

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

package/dist/diagnostics/codes/build.js

@@ -0,0 +1,55 @@
+//#region src/diagnostics/codes/build.ts
+/** The codes of the BUILD area, in the order they were added. */
+const buildDiagnosticCodes = [
+	"MOSTRA_BUILD_FAILED",
+	"MOSTRA_BUILD_UNRESOLVED",
+	"MOSTRA_BUILD_CRASHED",
+	"MOSTRA_BUILD_TIMEOUT"
+];
+/** The BUILD area's catalog entries. */
+const buildDiagnostics = {
+	MOSTRA_BUILD_FAILED: {
+		severity: "error",
+		phase: "compile",
+		title: "Build failed",
+		hint: "Fix the error at the reported location, then publish again.",
+		docs: {
+			explanation: "The builder couldn't bundle the artifact: a syntax error, an invalid JSX or MDX construct, a CSS error or another bundler error. The message carries the bundler's own explanation, and the location points at the file, line and column when the bundler reports one. Nothing was published.",
+			fix: "Open the reported file at the reported line and fix the code there. For MDX, check that JSX in the document is closed and that `{` and `<` in prose are escaped. Run `mostra verify` to see the same error with the type checker's findings."
+		}
+	},
+	MOSTRA_BUILD_UNRESOLVED: {
+		severity: "error",
+		phase: "compile",
+		title: "Import can't be resolved",
+		hint: "Correct the import path, or import the package from the warm set or add it with `mostra add`.",
+		docs: {
+			explanation: "An import in the artifact names a file or package the builder can't find. Relative imports resolve inside the artifact's own files, `@/...` resolves from the artifact's root, and package imports resolve from Mostra's warm set and the artifact's installed packages. The message names the import and the file that contains it.",
+			fix: "For a file, check the path and its extension against the artifact's files. For a package, check its name; packages outside the warm set install with `mostra add <package>`."
+		}
+	},
+	MOSTRA_BUILD_CRASHED: {
+		severity: "error",
+		phase: "compile",
+		title: "Builder crashed",
+		hint: "Publish again; if it crashes again, report the builder's last output from the message.",
+		docs: {
+			explanation: "The builder child process exited before it finished, for example after running out of memory or on a signal. The supervisor and everything else in the instance keep working, and nothing was published. The message carries the builder's last lines of error output.",
+			fix: "Run the publish again, which starts a fresh builder. A crash that repeats points at the artifact's size or at a defect in Mostra: very large inline data is better kept in `public/` or loaded through a live source."
+		}
+	},
+	MOSTRA_BUILD_TIMEOUT: {
+		severity: "error",
+		phase: "compile",
+		title: "Build timed out",
+		hint: "Make the build smaller, for example by moving large data into `public/`, then publish again.",
+		docs: {
+			explanation: "The build took longer than its limit (180 seconds) and was stopped. Nothing was published.",
+			fix: "Move large data files that are imported into code into `public/` and fetch them at run time, split very large modules, and remove unused imports of heavy libraries. Then publish again."
+		}
+	}
+};
+//#endregion
+export { buildDiagnosticCodes, buildDiagnostics };
+
+//# sourceMappingURL=build.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","names":[],"sources":["../../../src/diagnostics/codes/build.ts"],"sourcesContent":["/**\n * Diagnostic codes of the BUILD area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the BUILD area, in the order they were added. */\nexport const buildDiagnosticCodes = [\n  \"MOSTRA_BUILD_FAILED\",\n  \"MOSTRA_BUILD_UNRESOLVED\",\n  \"MOSTRA_BUILD_CRASHED\",\n  \"MOSTRA_BUILD_TIMEOUT\",\n  // gen:codes\n] as const;\n\n/** The codes of the BUILD area. */\nexport type BuildDiagnosticCode = (typeof buildDiagnosticCodes)[number];\n\n/** The BUILD area's catalog entries. */\nexport const buildDiagnostics: AreaCatalog<BuildDiagnosticCode> = {\n  MOSTRA_BUILD_FAILED: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Build failed\",\n    hint: \"Fix the error at the reported location, then publish again.\",\n    docs: {\n      explanation:\n        \"The builder couldn't bundle the artifact: a syntax error, an invalid JSX or MDX construct, a CSS error or another bundler error. The message carries the bundler's own explanation, and the location points at the file, line and column when the bundler reports one. Nothing was published.\",\n      fix: \"Open the reported file at the reported line and fix the code there. For MDX, check that JSX in the document is closed and that `{` and `<` in prose are escaped. Run `mostra verify` to see the same error with the type checker's findings.\",\n    },\n  },\n  MOSTRA_BUILD_UNRESOLVED: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Import can't be resolved\",\n    hint: \"Correct the import path, or import the package from the warm set or add it with `mostra add`.\",\n    docs: {\n      explanation:\n        \"An import in the artifact names a file or package the builder can't find. Relative imports resolve inside the artifact's own files, `@/...` resolves from the artifact's root, and package imports resolve from Mostra's warm set and the artifact's installed packages. The message names the import and the file that contains it.\",\n      fix: \"For a file, check the path and its extension against the artifact's files. For a package, check its name; packages outside the warm set install with `mostra add <package>`.\",\n    },\n  },\n  MOSTRA_BUILD_CRASHED: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Builder crashed\",\n    hint: \"Publish again; if it crashes again, report the builder's last output from the message.\",\n    docs: {\n      explanation:\n        \"The builder child process exited before it finished, for example after running out of memory or on a signal. The supervisor and everything else in the instance keep working, and nothing was published. The message carries the builder's last lines of error output.\",\n      fix: \"Run the publish again, which starts a fresh builder. A crash that repeats points at the artifact's size or at a defect in Mostra: very large inline data is better kept in `public/` or loaded through a live source.\",\n    },\n  },\n  MOSTRA_BUILD_TIMEOUT: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Build timed out\",\n    hint: \"Make the build smaller, for example by moving large data into `public/`, then publish again.\",\n    docs: {\n      explanation:\n        \"The build took longer than its limit (180 seconds) and was stopped. Nothing was published.\",\n      fix: \"Move large data files that are imported into code into `public/` and fetch them at run time, split very large modules, and remove unused imports of heavy libraries. Then publish again.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,uBAAuB;CAClC;CACA;CACA;CACA;AAEF;;AAMA,MAAa,mBAAqD;CAChE,qBAAqB;EACnB,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,sBAAsB;EACpB,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/cli.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/cli.d.ts
+/** The codes of the CLI area, in the order they were added. */
+export declare const cliDiagnosticCodes: readonly ["MOSTRA_CLI_USAGE", "MOSTRA_CLI_UNKNOWN_COMMAND", "MOSTRA_CLI_CONFIG_UNWRITABLE"];
+/** The codes of the CLI area. */
+export type CliDiagnosticCode = (typeof cliDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=cli.d.ts.map

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

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

package/dist/diagnostics/codes/cli.js

@@ -0,0 +1,44 @@
+//#region src/diagnostics/codes/cli.ts
+/** The codes of the CLI area, in the order they were added. */
+const cliDiagnosticCodes = [
+	"MOSTRA_CLI_USAGE",
+	"MOSTRA_CLI_UNKNOWN_COMMAND",
+	"MOSTRA_CLI_CONFIG_UNWRITABLE"
+];
+/** The CLI area's catalog entries. */
+const cliDiagnostics = {
+	MOSTRA_CLI_USAGE: {
+		severity: "error",
+		phase: "host",
+		title: "Command used wrongly",
+		hint: "Run `mostra <command> --help` for the command's arguments and flags, then run it again.",
+		docs: {
+			explanation: "The command line didn't fit the command's definition: a missing or extra argument, an unknown flag, a flag without its value, or a value of the wrong form (a duration, a number, JSON). Nothing ran. In `--json` mode the error is the envelope's `error`, and the exit code is 2.",
+			fix: "Read `mostra <command> --help` (or `--help --json` for the machine-readable definition) and correct the arguments."
+		}
+	},
+	MOSTRA_CLI_UNKNOWN_COMMAND: {
+		severity: "error",
+		phase: "host",
+		title: "Unknown command",
+		hint: "Pick one of the commands this message lists; `mostra --help` describes each.",
+		docs: {
+			explanation: "The first word after `mostra` isn't a command this CLI has. The message lists the commands that exist. Commands that later releases add (sharing, export, plugins, terminals) appear only once they exist, never as placeholders.",
+			fix: "Run one of the listed commands. `mostra --help` lists every command with a one-line summary."
+		}
+	},
+	MOSTRA_CLI_CONFIG_UNWRITABLE: {
+		severity: "error",
+		phase: "platform",
+		title: "The CLI's config directory can't be written",
+		hint: "Make the directory the message names yours and writable (or point MOSTRA_CONFIG_DIR at one that is), then run the command again; DO_NOT_TRACK=1 turns telemetry off without writing anything.",
+		docs: {
+			explanation: "`mostra telemetry on` and `off` record the choice in the CLI's config directory (`MOSTRA_CONFIG_DIR`, else `${XDG_CONFIG_HOME:-~/.config}/mostra`). The directory or its `telemetry.json` can't be written (another user owns it, the disk is full, it's read-only), so the choice wasn't recorded and nothing changed. Telemetry never stops another command for this: a store that can't be written means nothing is sent.",
+			fix: "Fix the directory's owner or mode, or set `MOSTRA_CONFIG_DIR` to a directory you own, and run the command again. `DO_NOT_TRACK=1` or `MOSTRA_TELEMETRY=0` in your environment turn telemetry off without a file."
+		}
+	}
+};
+//#endregion
+export { cliDiagnosticCodes, cliDiagnostics };
+
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../../../src/diagnostics/codes/cli.ts"],"sourcesContent":["/**\n * Diagnostic codes of the CLI area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the CLI area, in the order they were added. */\nexport const cliDiagnosticCodes = [\n  \"MOSTRA_CLI_USAGE\",\n  \"MOSTRA_CLI_UNKNOWN_COMMAND\",\n  \"MOSTRA_CLI_CONFIG_UNWRITABLE\",\n  // gen:codes\n] as const;\n\n/** The codes of the CLI area. */\nexport type CliDiagnosticCode = (typeof cliDiagnosticCodes)[number];\n\n/** The CLI area's catalog entries. */\nexport const cliDiagnostics: AreaCatalog<CliDiagnosticCode> = {\n  MOSTRA_CLI_USAGE: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Command used wrongly\",\n    hint: \"Run `mostra <command> --help` for the command's arguments and flags, then run it again.\",\n    docs: {\n      explanation:\n        \"The command line didn't fit the command's definition: a missing or extra argument, an unknown flag, a flag without its value, or a value of the wrong form (a duration, a number, JSON). Nothing ran. In `--json` mode the error is the envelope's `error`, and the exit code is 2.\",\n      fix: \"Read `mostra <command> --help` (or `--help --json` for the machine-readable definition) and correct the arguments.\",\n    },\n  },\n  MOSTRA_CLI_UNKNOWN_COMMAND: {\n    severity: \"error\",\n    phase: \"host\",\n    title: \"Unknown command\",\n    hint: \"Pick one of the commands this message lists; `mostra --help` describes each.\",\n    docs: {\n      explanation:\n        \"The first word after `mostra` isn't a command this CLI has. The message lists the commands that exist. Commands that later releases add (sharing, export, plugins, terminals) appear only once they exist, never as placeholders.\",\n      fix: \"Run one of the listed commands. `mostra --help` lists every command with a one-line summary.\",\n    },\n  },\n  MOSTRA_CLI_CONFIG_UNWRITABLE: {\n    severity: \"error\",\n    phase: \"platform\",\n    title: \"The CLI's config directory can't be written\",\n    hint: \"Make the directory the message names yours and writable (or point MOSTRA_CONFIG_DIR at one that is), then run the command again; DO_NOT_TRACK=1 turns telemetry off without writing anything.\",\n    docs: {\n      explanation:\n        \"`mostra telemetry on` and `off` record the choice in the CLI's config directory (`MOSTRA_CONFIG_DIR`, else `${XDG_CONFIG_HOME:-~/.config}/mostra`). The directory or its `telemetry.json` can't be written (another user owns it, the disk is full, it's read-only), so the choice wasn't recorded and nothing changed. Telemetry never stops another command for this: a store that can't be written means nothing is sent.\",\n      fix: \"Fix the directory's owner or mode, or set `MOSTRA_CONFIG_DIR` to a directory you own, and run the command again. `DO_NOT_TRACK=1` or `MOSTRA_TELEMETRY=0` in your environment turn telemetry off without a file.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,qBAAqB;CAChC;CACA;CACA;AAEF;;AAMA,MAAa,iBAAiD;CAC5D,kBAAkB;EAChB,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,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

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

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/console.d.ts
+/** The codes of the CONSOLE area, in the order they were added. */
+export declare const consoleDiagnosticCodes: readonly ["MOSTRA_CONSOLE_ERROR", "MOSTRA_CONSOLE_WARNING"];
+/** The codes of the CONSOLE area. */
+export type ConsoleDiagnosticCode = (typeof consoleDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=console.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","names":[],"sources":["../../../src/diagnostics/codes/console.ts"],"mappings":";;;qBAMa;;YAOD,gCAAgC"}