@mostra/protocol 0.0.0-stage → 0.1.0

package/dist/diagnostics/codes/submit.js

@@ -0,0 +1,99 @@
+//#region src/diagnostics/codes/submit.ts
+/** The codes of the SUBMIT area, in the order they were added. */
+const submitDiagnosticCodes = [
+	"MOSTRA_SUBMIT_ALREADY",
+	"MOSTRA_SUBMIT_REVISION_MOVED",
+	"MOSTRA_SUBMIT_POLICY_NONE",
+	"MOSTRA_SUBMIT_NOT_FOUND",
+	"MOSTRA_SUBMIT_VIEW_INVALID",
+	"MOSTRA_SUBMIT_SIGNAL_INVALID",
+	"MOSTRA_SUBMIT_CHANNEL_DENIED",
+	"MOSTRA_SUBMIT_BLOCKED"
+];
+/** The SUBMIT area's catalog entries. */
+const submitDiagnostics = {
+	MOSTRA_SUBMIT_ALREADY: {
+		severity: "error",
+		phase: "runtime",
+		title: "Already submitted",
+		hint: "This artifact takes one submission, and it was made; read it with `mostra results`.",
+		docs: {
+			explanation: "The artifact's submission policy is `once`, and a submission already closed this draft: for scope `per-artifact` any viewer's submission closes every draft, for `per-viewer` the viewer's own. A submission is immutable and final, so Mostra refuses a second one and further edits to the closed draft. The refusal carries the existing submission. A repeated submit of the same view at the same draft revision is not refused: it returns the original submission.",
+			fix: "Read the existing submission with `mostra results <artifact>`. When another round of answers is wanted, publish a new artifact linked to this one (`links: [{ rel: \"round-of\", artifact }]`), or have the host publish with the `epochs` policy."
+		}
+	},
+	MOSTRA_SUBMIT_REVISION_MOVED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Draft changed before submit",
+		hint: "Reload the draft, check what changed, and submit again with its current revision.",
+		docs: {
+			explanation: "A submit names the draft revision the viewer saw (`expectedRevision`), and the draft has changed since: another tab, device or writer saved an edit. Mostra never makes a submission from content the viewer didn't see (FAILURE_MODEL §4), so it refuses. The message names the draft's current revision.",
+			fix: "Let the page reload the draft so the viewer sees exactly what will be sent, then submit with the new revision. The shell and the client runtime flush pending saves before they submit, which makes this rare."
+		}
+	},
+	MOSTRA_SUBMIT_POLICY_NONE: {
+		severity: "error",
+		phase: "runtime",
+		title: "Artifact takes no submissions",
+		hint: "Exchange data through artifact state, actions and signals; this artifact has no submissions.",
+		docs: {
+			explanation: "The artifact's submission policy is `none` (D63): long-lived artifacts such as dashboards and task managers talk to agents through artifact state, actions, signals and events, and the shell shows no Submit control. Mostra refuses a submit, and a `wait --until submitted`, on such an artifact.",
+			fix: "Wait for a signal (`--until signal:<name>`), a state change (`--until state:<field>`) or an event instead, and read state with `mostra state get`. To collect submissions, publish with policy `once` or `epochs`."
+		}
+	},
+	MOSTRA_SUBMIT_NOT_FOUND: {
+		severity: "error",
+		phase: "runtime",
+		title: "No such submission",
+		hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
+		docs: {
+			explanation: "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home).",
+			fix: "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events."
+		}
+	},
+	MOSTRA_SUBMIT_VIEW_INVALID: {
+		severity: "error",
+		phase: "runtime",
+		title: "Unknown view",
+		hint: "Send the view ID this page was opened with.",
+		docs: {
+			explanation: "Mutations and submits name the view they come from, the one the shell created when it opened this frame. The view named doesn't exist, belongs to another artifact, or belongs to another viewer. Mostra binds every submission to the exact version its view showed, so it refuses a view it can't place.",
+			fix: "Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit."
+		}
+	},
+	MOSTRA_SUBMIT_SIGNAL_INVALID: {
+		severity: "error",
+		phase: "runtime",
+		title: "Invalid signal",
+		hint: "Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.",
+		docs: {
+			explanation: "A signal names something the artifact wants a host's attention for, such as `ping-agent`. Its name is 1 to 64 characters of letters, digits, `.`, `_` and `-`, starting with a letter or digit, and its payload is JSON of at most 64 KiB. This one broke one of those rules. The name `submit` is reserved for submissions.",
+			fix: "Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload."
+		}
+	},
+	MOSTRA_SUBMIT_CHANNEL_DENIED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Submit channel not allowed",
+		hint: "Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.",
+		docs: {
+			explanation: "A submission comes through one of two channels (D40): the shell's trusted Submit (`shell`), which only a person can press, or the artifact's own code (`artifact`, `useSubmit().submit()` and `useChoice().choose()`). The host decides which it accepts (D108): through `HomeConfig.submitChannels` for the home, or its `trustedControls` port for each artifact. This view allows only the other channel, so Mostra refused the submit or the choice. `useSubmit().allowed` is `false` in such a view.",
+			fix: "Ask the viewer to press the shell's Submit (relabel it with `useSubmitControl`), and use `useChoice(id, { candidates })` to have the shell render a trusted Choose. Check `allowed` before showing an in-page submit button."
+		}
+	},
+	MOSTRA_SUBMIT_BLOCKED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Answers missing before submit",
+		hint: "Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.",
+		docs: {
+			explanation: "Before a submit, the shell and the client runtime check every mounted field (D106): a `required` field without a value, a value its `validate` rejects, or a conflict the viewer hasn't resolved blocks the submit. The diagnostic lists the blockers with their field IDs and labels; `useSubmit().blockers` lists them before anyone submits. Nothing was submitted.",
+			fix: "Show `useSubmit().blockers` next to your submit button, or let the shell list them by label. Answer the required fields, fix the invalid values, and keep or take the conflicting values, then submit again."
+		}
+	}
+};
+//#endregion
+export { submitDiagnosticCodes, submitDiagnostics };
+
+//# sourceMappingURL=submit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","names":[],"sources":["../../../src/diagnostics/codes/submit.ts"],"sourcesContent":["/**\n * Diagnostic codes of the SUBMIT area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the SUBMIT area, in the order they were added. */\nexport const submitDiagnosticCodes = [\n  \"MOSTRA_SUBMIT_ALREADY\",\n  \"MOSTRA_SUBMIT_REVISION_MOVED\",\n  \"MOSTRA_SUBMIT_POLICY_NONE\",\n  \"MOSTRA_SUBMIT_NOT_FOUND\",\n  \"MOSTRA_SUBMIT_VIEW_INVALID\",\n  \"MOSTRA_SUBMIT_SIGNAL_INVALID\",\n  \"MOSTRA_SUBMIT_CHANNEL_DENIED\",\n  \"MOSTRA_SUBMIT_BLOCKED\",\n  // gen:codes\n] as const;\n\n/** The codes of the SUBMIT area. */\nexport type SubmitDiagnosticCode = (typeof submitDiagnosticCodes)[number];\n\n/** The SUBMIT area's catalog entries. */\nexport const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {\n  MOSTRA_SUBMIT_ALREADY: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Already submitted\",\n    hint: \"This artifact takes one submission, and it was made; read it with `mostra results`.\",\n    docs: {\n      explanation:\n        \"The artifact's submission policy is `once`, and a submission already closed this draft: for scope `per-artifact` any viewer's submission closes every draft, for `per-viewer` the viewer's own. A submission is immutable and final, so Mostra refuses a second one and further edits to the closed draft. The refusal carries the existing submission. A repeated submit of the same view at the same draft revision is not refused: it returns the original submission.\",\n      fix: 'Read the existing submission with `mostra results <artifact>`. When another round of answers is wanted, publish a new artifact linked to this one (`links: [{ rel: \"round-of\", artifact }]`), or have the host publish with the `epochs` policy.',\n    },\n  },\n  MOSTRA_SUBMIT_REVISION_MOVED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Draft changed before submit\",\n    hint: \"Reload the draft, check what changed, and submit again with its current revision.\",\n    docs: {\n      explanation:\n        \"A submit names the draft revision the viewer saw (`expectedRevision`), and the draft has changed since: another tab, device or writer saved an edit. Mostra never makes a submission from content the viewer didn't see (FAILURE_MODEL §4), so it refuses. The message names the draft's current revision.\",\n      fix: \"Let the page reload the draft so the viewer sees exactly what will be sent, then submit with the new revision. The shell and the client runtime flush pending saves before they submit, which makes this rare.\",\n    },\n  },\n  MOSTRA_SUBMIT_POLICY_NONE: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Artifact takes no submissions\",\n    hint: \"Exchange data through artifact state, actions and signals; this artifact has no submissions.\",\n    docs: {\n      explanation:\n        \"The artifact's submission policy is `none` (D63): long-lived artifacts such as dashboards and task managers talk to agents through artifact state, actions, signals and events, and the shell shows no Submit control. Mostra refuses a submit, and a `wait --until submitted`, on such an artifact.\",\n      fix: \"Wait for a signal (`--until signal:<name>`), a state change (`--until state:<field>`) or an event instead, and read state with `mostra state get`. To collect submissions, publish with policy `once` or `epochs`.\",\n    },\n  },\n  MOSTRA_SUBMIT_NOT_FOUND: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"No such submission\",\n    hint: \"Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.\",\n    docs: {\n      explanation:\n        \"The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home).\",\n      fix: \"Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events.\",\n    },\n  },\n  MOSTRA_SUBMIT_VIEW_INVALID: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Unknown view\",\n    hint: \"Send the view ID this page was opened with.\",\n    docs: {\n      explanation:\n        \"Mutations and submits name the view they come from, the one the shell created when it opened this frame. The view named doesn't exist, belongs to another artifact, or belongs to another viewer. Mostra binds every submission to the exact version its view showed, so it refuses a view it can't place.\",\n      fix: \"Use the `viewId` the shell handed this frame. A page opened outside Mostra's shell has no view and can't submit.\",\n    },\n  },\n  MOSTRA_SUBMIT_SIGNAL_INVALID: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Invalid signal\",\n    hint: \"Name signals with letters, digits, `.`, `_` and `-`, and keep their payload under 64 KiB of JSON.\",\n    docs: {\n      explanation:\n        \"A signal names something the artifact wants a host's attention for, such as `ping-agent`. Its name is 1 to 64 characters of letters, digits, `.`, `_` and `-`, starting with a letter or digit, and its payload is JSON of at most 64 KiB. This one broke one of those rules. The name `submit` is reserved for submissions.\",\n      fix: \"Rename the signal or shrink its payload; put large data into a field or artifact state and send its ID in the payload.\",\n    },\n  },\n  MOSTRA_SUBMIT_CHANNEL_DENIED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Submit channel not allowed\",\n    hint: \"Let the viewer submit with the shell's trusted Submit; this host doesn't take submissions from artifact code.\",\n    docs: {\n      explanation:\n        \"A submission comes through one of two channels (D40): the shell's trusted Submit (`shell`), which only a person can press, or the artifact's own code (`artifact`, `useSubmit().submit()` and `useChoice().choose()`). The host decides which it accepts (D108): through `HomeConfig.submitChannels` for the home, or its `trustedControls` port for each artifact. This view allows only the other channel, so Mostra refused the submit or the choice. `useSubmit().allowed` is `false` in such a view.\",\n      fix: \"Ask the viewer to press the shell's Submit (relabel it with `useSubmitControl`), and use `useChoice(id, { candidates })` to have the shell render a trusted Choose. Check `allowed` before showing an in-page submit button.\",\n    },\n  },\n  MOSTRA_SUBMIT_BLOCKED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Answers missing before submit\",\n    hint: \"Fill in the fields this diagnostic lists, fix their errors or resolve their conflicts, then submit again.\",\n    docs: {\n      explanation:\n        \"Before a submit, the shell and the client runtime check every mounted field (D106): a `required` field without a value, a value its `validate` rejects, or a conflict the viewer hasn't resolved blocks the submit. The diagnostic lists the blockers with their field IDs and labels; `useSubmit().blockers` lists them before anyone submits. Nothing was submitted.\",\n      fix: \"Show `useSubmit().blockers` next to your submit button, or let the shell list them by label. Answer the required fields, fix the invalid values, and keep or take the conflicting values, then submit again.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,uBAAuB;EACrB,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,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,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;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

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

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

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

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

package/dist/diagnostics/codes/target.js

@@ -0,0 +1,18 @@
+//#region src/diagnostics/codes/target.ts
+/** The codes of the TARGET area, in the order they were added. */
+const targetDiagnosticCodes = ["MOSTRA_TARGET_UNAVAILABLE"];
+/** The TARGET area's catalog entries. */
+const targetDiagnostics = { MOSTRA_TARGET_UNAVAILABLE: {
+	severity: "error",
+	phase: "runtime",
+	title: "Not available in this delivery target",
+	hint: "Open the published version through Mostra to use this feature.",
+	docs: {
+		explanation: "The page called something that needs Mostra's server, such as a server function, and this delivery target doesn't provide it: a static export, a file opened from disk, or a runtime without server support. The page keeps working without it.",
+		fix: "Open the artifact through its Mostra link, where server functions, submissions and live data are available. In a static export, handle the error so the page explains what isn't available."
+	}
+} };
+//#endregion
+export { targetDiagnosticCodes, targetDiagnostics };
+
+//# sourceMappingURL=target.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","names":[],"sources":["../../../src/diagnostics/codes/target.ts"],"sourcesContent":["/**\n * Diagnostic codes of the TARGET area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the TARGET area, in the order they were added. */\nexport const targetDiagnosticCodes = [\n  \"MOSTRA_TARGET_UNAVAILABLE\",\n  // gen:codes\n] as const;\n\n/** The codes of the TARGET area. */\nexport type TargetDiagnosticCode = (typeof targetDiagnosticCodes)[number];\n\n/** The TARGET area's catalog entries. */\nexport const targetDiagnostics: AreaCatalog<TargetDiagnosticCode> = {\n  MOSTRA_TARGET_UNAVAILABLE: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Not available in this delivery target\",\n    hint: \"Open the published version through Mostra to use this feature.\",\n    docs: {\n      explanation:\n        \"The page called something that needs Mostra's server, such as a server function, and this delivery target doesn't provide it: a static export, a file opened from disk, or a runtime without server support. The page keeps working without it.\",\n      fix: \"Open the artifact through its Mostra link, where server functions, submissions and live data are available. In a static export, handle the error so the page explains what isn't available.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB,CACnC,2BAEF;;AAMA,MAAa,oBAAuD,EAClE,2BAA2B;CACzB,UAAU;CACV,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;EACJ,aACE;EACF,KAAK;CACP;AACF,EAEF"}

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

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

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

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

package/dist/diagnostics/codes/type.js

@@ -0,0 +1,30 @@
+//#region src/diagnostics/codes/type.ts
+/** The codes of the TYPE area, in the order they were added. */
+const typeDiagnosticCodes = ["MOSTRA_TYPE_ERROR", "MOSTRA_TYPE_UNTYPED_PACKAGE"];
+/** The TYPE area's catalog entries. */
+const typeDiagnostics = {
+	MOSTRA_TYPE_ERROR: {
+		severity: "error",
+		phase: "compile",
+		title: "Type error",
+		hint: "Fix the type error at the reported location; the message carries TypeScript's code and text.",
+		docs: {
+			explanation: "TypeScript's checker (`tsc --noEmit`, TypeScript 7) found an error in the artifact's code. Verify checks with the artifact's own `tsconfig.json` when it has one, else in strict mode without the unused-variable rules, and resolves imports exactly as the build does. MDX isn't checked.",
+			fix: "Open the file at the reported line and fix the code, for example a missing property, a wrong argument type or a misspelled import."
+		}
+	},
+	MOSTRA_TYPE_UNTYPED_PACKAGE: {
+		severity: "warning",
+		phase: "compile",
+		title: "Package without type declarations",
+		hint: "Nothing breaks: the package works without types; declare a module for it if you want them checked.",
+		docs: {
+			explanation: "The artifact imports a package that ships no type declarations (TypeScript's TS7016). The package still builds and runs, so this is a warning: its values are typed `any`.",
+			fix: "Optionally add a declaration file such as `declare module \"<package>\";`, or a typed wrapper, to the artifact."
+		}
+	}
+};
+//#endregion
+export { typeDiagnosticCodes, typeDiagnostics };
+
+//# sourceMappingURL=type.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","names":[],"sources":["../../../src/diagnostics/codes/type.ts"],"sourcesContent":["/**\n * Diagnostic codes of the TYPE area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the TYPE area, in the order they were added. */\nexport const typeDiagnosticCodes = [\n  \"MOSTRA_TYPE_ERROR\",\n  \"MOSTRA_TYPE_UNTYPED_PACKAGE\",\n  // gen:codes\n] as const;\n\n/** The codes of the TYPE area. */\nexport type TypeDiagnosticCode = (typeof typeDiagnosticCodes)[number];\n\n/** The TYPE area's catalog entries. */\nexport const typeDiagnostics: AreaCatalog<TypeDiagnosticCode> = {\n  MOSTRA_TYPE_ERROR: {\n    severity: \"error\",\n    phase: \"compile\",\n    title: \"Type error\",\n    hint: \"Fix the type error at the reported location; the message carries TypeScript's code and text.\",\n    docs: {\n      explanation:\n        \"TypeScript's checker (`tsc --noEmit`, TypeScript 7) found an error in the artifact's code. Verify checks with the artifact's own `tsconfig.json` when it has one, else in strict mode without the unused-variable rules, and resolves imports exactly as the build does. MDX isn't checked.\",\n      fix: \"Open the file at the reported line and fix the code, for example a missing property, a wrong argument type or a misspelled import.\",\n    },\n  },\n  MOSTRA_TYPE_UNTYPED_PACKAGE: {\n    severity: \"warning\",\n    phase: \"compile\",\n    title: \"Package without type declarations\",\n    hint: \"Nothing breaks: the package works without types; declare a module for it if you want them checked.\",\n    docs: {\n      explanation:\n        \"The artifact imports a package that ships no type declarations (TypeScript's TS7016). The package still builds and runs, so this is a warning: its values are typed `any`.\",\n      fix: 'Optionally add a declaration file such as `declare module \"<package>\";`, or a typed wrapper, to the artifact.',\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,sBAAsB,CACjC,qBACA,6BAEF;;AAMA,MAAa,kBAAmD;CAC9D,mBAAmB;EACjB,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/verify.d.ts

@@ -0,0 +1,8 @@
+import "../spec.js";
+//#region src/diagnostics/codes/verify.d.ts
+/** The codes of the VERIFY area, in the order they were added. */
+export declare const verifyDiagnosticCodes: readonly ["MOSTRA_VERIFY_ACTION_SKIPPED", "MOSTRA_VERIFY_SKIP_CONSEQUENCE", "MOSTRA_VERIFY_TIMEOUT", "MOSTRA_VERIFY_CRASHED", "MOSTRA_VERIFY_NO_BASELINE", "MOSTRA_VERIFY_BASELINE_MISSING", "MOSTRA_VERIFY_LIVE_FAILED", "MOSTRA_VERIFY_SECRET_MISSING"];
+/** The codes of the VERIFY area. */
+export type VerifyDiagnosticCode = (typeof verifyDiagnosticCodes)[number];
+//#endregion
+//# sourceMappingURL=verify.d.ts.map

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

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

package/dist/diagnostics/codes/verify.js

@@ -0,0 +1,99 @@
+//#region src/diagnostics/codes/verify.ts
+/** The codes of the VERIFY area, in the order they were added. */
+const verifyDiagnosticCodes = [
+	"MOSTRA_VERIFY_ACTION_SKIPPED",
+	"MOSTRA_VERIFY_SKIP_CONSEQUENCE",
+	"MOSTRA_VERIFY_TIMEOUT",
+	"MOSTRA_VERIFY_CRASHED",
+	"MOSTRA_VERIFY_NO_BASELINE",
+	"MOSTRA_VERIFY_BASELINE_MISSING",
+	"MOSTRA_VERIFY_LIVE_FAILED",
+	"MOSTRA_VERIFY_SECRET_MISSING"
+];
+/** The VERIFY area's catalog entries. */
+const verifyDiagnostics = {
+	MOSTRA_VERIFY_ACTION_SKIPPED: {
+		severity: "hint",
+		phase: "smoke",
+		title: "Action skipped in verify",
+		hint: "To have verify run this action, check `dryRun()` from `@mostra/server` in it and return early without its side effects when it is true.",
+		docs: {
+			explanation: "Verify's smoke test never runs a server function that doesn't check `dryRun()` (D55). When the page called one, verify refused the call instead: the page's `run()` or server reference rejected with a `MostraError` carrying this code, as it would for any failed action. The verdict lists every such function in `smoke.skippedActions`. Nothing was sent, written or charged.",
+			fix: "Nothing is wrong. To have verify exercise the action, add `if (dryRun()) return <a representative result>;` before its side effects; verify then runs it with `dryRun()` true."
+		}
+	},
+	MOSTRA_VERIFY_SKIP_CONSEQUENCE: {
+		severity: "hint",
+		phase: "smoke",
+		title: "Page reaction to a skipped action",
+		hint: "Nothing to fix: this followed from verify skipping an action, which a viewer's page never meets.",
+		docs: {
+			explanation: "After verify refused a server function that doesn't check `dryRun()`, the page reported an error: an unhandled rejection, an error a boundary caught, or a console error while it settled. It follows from verify's synthetic refusal, not from a defect a viewer would meet, so it is reported as a hint naming the skipped action.",
+			fix: "Nothing is required. To let verify see the action's real result, opt it into the smoke test with `dryRun()`."
+		}
+	},
+	MOSTRA_VERIFY_TIMEOUT: {
+		severity: "error",
+		phase: "runtime",
+		title: "Verify ran out of time",
+		hint: "Make the page render without waiting on slow work at load, then verify again.",
+		docs: {
+			explanation: "Verify allows 120 s for everything after the build: booting the sandbox, rendering each viewport, the smoke test and the regression stage. This run went past it, so its verdict is partial: the message names the stage it reached. A partial run can't vouch for the page, so this is an error, and the verdict isn't cached.",
+			fix: "Look for work the page does at load that takes long (large data, long animations, requests that never answer) and defer it, then verify again. On a heavily loaded machine, verifying again may be enough."
+		}
+	},
+	MOSTRA_VERIFY_CRASHED: {
+		severity: "error",
+		phase: "runtime",
+		title: "Verify runner crashed",
+		hint: "Verify again; if it keeps crashing, report the message with `mostra doctor`'s output.",
+		docs: {
+			explanation: "The verify runner, the child process that drives the browser, stopped before it finished (FAILURE_MODEL §2). The message carries its last lines of output. Nothing was published, and the next verify starts a fresh runner.",
+			fix: "Verify again. A crash that repeats for the same artifact can come from a page that exhausts the browser's memory; one that repeats for every artifact means the runtime's browser is damaged."
+		}
+	},
+	MOSTRA_VERIFY_NO_BASELINE: {
+		severity: "hint",
+		phase: "regression",
+		title: "No earlier passing version",
+		hint: "Nothing to fix: the next version will be compared with this one once it is published.",
+		docs: {
+			explanation: "Verify compares a source with the newest published version of its artifact whose verdict passed. This artifact has none yet (it is new, or every earlier version was published with `--force`), so no regression stage ran.",
+			fix: "Nothing is required."
+		}
+	},
+	MOSTRA_VERIFY_BASELINE_MISSING: {
+		severity: "hint",
+		phase: "regression",
+		title: "Baseline version's build is missing",
+		hint: "Nothing to fix here; publish again to give later versions a baseline.",
+		docs: {
+			explanation: "The newest version that passed verify is recorded in the ledger, but its stored build isn't in the home any more, so verify couldn't render it and ran no regression stage.",
+			fix: "Nothing is required. A version published from this source becomes the next baseline."
+		}
+	},
+	MOSTRA_VERIFY_LIVE_FAILED: {
+		severity: "warning",
+		phase: "runtime",
+		title: "Live source failed during verify",
+		hint: "Check the live source's message: it failed while verify rendered the page, which may be the environment rather than the code.",
+		docs: {
+			explanation: "A live source's producer (`live.ts`) threw or couldn't reach its data while verify rendered the page. Verify runs producers for real, since they only read, so a failure can come from the environment (no network, a service that is down) as well as from the code. The page shows `useLive`'s `error` meanwhile.",
+			fix: "Read the message. If the producer itself is wrong, fix it; if the data source was unreachable, verify again when it is back."
+		}
+	},
+	MOSTRA_VERIFY_SECRET_MISSING: {
+		severity: "warning",
+		phase: "runtime",
+		title: "Secret missing during verify",
+		hint: "Set the secret with `mostra secret set <NAME>` if the artifact needs it; verify reports it as the environment, not the code.",
+		docs: {
+			explanation: "Server code asked for a secret (`secret()`) that neither the host, the artifact's secrets nor the home's hold, while verify ran it. Secrets are part of the environment, so verify reports this as a warning rather than an error.",
+			fix: "Run `mostra secret set <NAME>` (for the artifact or the home) with the value the code needs, then verify again."
+		}
+	}
+};
+//#endregion
+export { verifyDiagnosticCodes, verifyDiagnostics };
+
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","names":[],"sources":["../../../src/diagnostics/codes/verify.ts"],"sourcesContent":["/**\n * Diagnostic codes of the VERIFY area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the VERIFY area, in the order they were added. */\nexport const verifyDiagnosticCodes = [\n  \"MOSTRA_VERIFY_ACTION_SKIPPED\",\n  \"MOSTRA_VERIFY_SKIP_CONSEQUENCE\",\n  \"MOSTRA_VERIFY_TIMEOUT\",\n  \"MOSTRA_VERIFY_CRASHED\",\n  \"MOSTRA_VERIFY_NO_BASELINE\",\n  \"MOSTRA_VERIFY_BASELINE_MISSING\",\n  \"MOSTRA_VERIFY_LIVE_FAILED\",\n  \"MOSTRA_VERIFY_SECRET_MISSING\",\n  // gen:codes\n] as const;\n\n/** The codes of the VERIFY area. */\nexport type VerifyDiagnosticCode = (typeof verifyDiagnosticCodes)[number];\n\n/** The VERIFY area's catalog entries. */\nexport const verifyDiagnostics: AreaCatalog<VerifyDiagnosticCode> = {\n  MOSTRA_VERIFY_ACTION_SKIPPED: {\n    severity: \"hint\",\n    phase: \"smoke\",\n    title: \"Action skipped in verify\",\n    hint: \"To have verify run this action, check `dryRun()` from `@mostra/server` in it and return early without its side effects when it is true.\",\n    docs: {\n      explanation:\n        \"Verify's smoke test never runs a server function that doesn't check `dryRun()` (D55). When the page called one, verify refused the call instead: the page's `run()` or server reference rejected with a `MostraError` carrying this code, as it would for any failed action. The verdict lists every such function in `smoke.skippedActions`. Nothing was sent, written or charged.\",\n      fix: \"Nothing is wrong. To have verify exercise the action, add `if (dryRun()) return <a representative result>;` before its side effects; verify then runs it with `dryRun()` true.\",\n    },\n  },\n  MOSTRA_VERIFY_SKIP_CONSEQUENCE: {\n    severity: \"hint\",\n    phase: \"smoke\",\n    title: \"Page reaction to a skipped action\",\n    hint: \"Nothing to fix: this followed from verify skipping an action, which a viewer's page never meets.\",\n    docs: {\n      explanation:\n        \"After verify refused a server function that doesn't check `dryRun()`, the page reported an error: an unhandled rejection, an error a boundary caught, or a console error while it settled. It follows from verify's synthetic refusal, not from a defect a viewer would meet, so it is reported as a hint naming the skipped action.\",\n      fix: \"Nothing is required. To let verify see the action's real result, opt it into the smoke test with `dryRun()`.\",\n    },\n  },\n  MOSTRA_VERIFY_TIMEOUT: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Verify ran out of time\",\n    hint: \"Make the page render without waiting on slow work at load, then verify again.\",\n    docs: {\n      explanation:\n        \"Verify allows 120 s for everything after the build: booting the sandbox, rendering each viewport, the smoke test and the regression stage. This run went past it, so its verdict is partial: the message names the stage it reached. A partial run can't vouch for the page, so this is an error, and the verdict isn't cached.\",\n      fix: \"Look for work the page does at load that takes long (large data, long animations, requests that never answer) and defer it, then verify again. On a heavily loaded machine, verifying again may be enough.\",\n    },\n  },\n  MOSTRA_VERIFY_CRASHED: {\n    severity: \"error\",\n    phase: \"runtime\",\n    title: \"Verify runner crashed\",\n    hint: \"Verify again; if it keeps crashing, report the message with `mostra doctor`'s output.\",\n    docs: {\n      explanation:\n        \"The verify runner, the child process that drives the browser, stopped before it finished (FAILURE_MODEL §2). The message carries its last lines of output. Nothing was published, and the next verify starts a fresh runner.\",\n      fix: \"Verify again. A crash that repeats for the same artifact can come from a page that exhausts the browser's memory; one that repeats for every artifact means the runtime's browser is damaged.\",\n    },\n  },\n  MOSTRA_VERIFY_NO_BASELINE: {\n    severity: \"hint\",\n    phase: \"regression\",\n    title: \"No earlier passing version\",\n    hint: \"Nothing to fix: the next version will be compared with this one once it is published.\",\n    docs: {\n      explanation:\n        \"Verify compares a source with the newest published version of its artifact whose verdict passed. This artifact has none yet (it is new, or every earlier version was published with `--force`), so no regression stage ran.\",\n      fix: \"Nothing is required.\",\n    },\n  },\n  MOSTRA_VERIFY_BASELINE_MISSING: {\n    severity: \"hint\",\n    phase: \"regression\",\n    title: \"Baseline version's build is missing\",\n    hint: \"Nothing to fix here; publish again to give later versions a baseline.\",\n    docs: {\n      explanation:\n        \"The newest version that passed verify is recorded in the ledger, but its stored build isn't in the home any more, so verify couldn't render it and ran no regression stage.\",\n      fix: \"Nothing is required. A version published from this source becomes the next baseline.\",\n    },\n  },\n  MOSTRA_VERIFY_LIVE_FAILED: {\n    severity: \"warning\",\n    phase: \"runtime\",\n    title: \"Live source failed during verify\",\n    hint: \"Check the live source's message: it failed while verify rendered the page, which may be the environment rather than the code.\",\n    docs: {\n      explanation:\n        \"A live source's producer (`live.ts`) threw or couldn't reach its data while verify rendered the page. Verify runs producers for real, since they only read, so a failure can come from the environment (no network, a service that is down) as well as from the code. The page shows `useLive`'s `error` meanwhile.\",\n      fix: \"Read the message. If the producer itself is wrong, fix it; if the data source was unreachable, verify again when it is back.\",\n    },\n  },\n  MOSTRA_VERIFY_SECRET_MISSING: {\n    severity: \"warning\",\n    phase: \"runtime\",\n    title: \"Secret missing during verify\",\n    hint: \"Set the secret with `mostra secret set <NAME>` if the artifact needs it; verify reports it as the environment, not the code.\",\n    docs: {\n      explanation:\n        \"Server code asked for a secret (`secret()`) that neither the host, the artifact's secrets nor the home's hold, while verify ran it. Secrets are part of the environment, so verify reports this as a warning rather than an error.\",\n      fix: \"Run `mostra secret set <NAME>` (for the artifact or the home) with the value the code needs, then verify again.\",\n    },\n  },\n  // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;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,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,uBAAuB;EACrB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,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,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}

package/dist/diagnostics/diagnostic.d.ts

@@ -0,0 +1,79 @@
+import * as z from "zod";
+//#region src/diagnostics/diagnostic.d.ts
+/**
+ * Diagnostic areas. A code is `MOSTRA_<AREA>_<NAME>`. INTERFACES §13 holds the authoritative list,
+ * which only grows.
+ */
+export type DiagnosticArea = "MANIFEST" | "BUILD" | "TYPE" | "LINT" | "DEP" | "KIT" | "FIELD" | "ACTION" | "LIVE" | "RUNTIME" | "CONSOLE" | "NETWORK" | "A11Y" | "VISUAL" | "SMOKE" | "REGRESSION" | "TERM" | "PUBLISH" | "SUBMIT" | "HOST" | "HOME" | "HYGIENE" | "SECRET" | "SHARE" | "VERIFY" | "TARGET" | "ENV" | "PLATFORM" | "ARTIFACT" | "CLI";
+/** Every diagnostic area, in INTERFACES §13 order. */
+export declare const DIAGNOSTIC_AREAS: readonly DiagnosticArea[];
+/**
+ * A diagnostic code. Codes are semver surface: once released, a code keeps its meaning and is
+ * never removed (AX-03).
+ */
+export type DiagnosticCode = `MOSTRA_${DiagnosticArea}_${string}`;
+/**
+ * How bad it is. `error` is only for definite failures; observations that might be fine are
+ * warnings (D72).
+ */
+export type DiagnosticSeverity = "error" | "warning" | "hint";
+/** The stage of work that produced the diagnostic. */
+export type DiagnosticPhase = "manifest" | "compile" | "lint" | "runtime" | "console" | "network" | "a11y" | "visual" | "smoke" | "regression" | "contract" | "publish" | "host" | "hygiene" | "platform";
+/**
+ * A machine-applicable fix. `range` is `[startLine, startColumn, endLine, endColumn]`, 1-based,
+ * with the end exclusive.
+ */
+export interface DiagnosticFix {
+  /** Replace, insert or delete text in `file`, or run `command`. */
+  readonly kind: "replace" | "insert" | "delete" | "command";
+  /** The file to edit, relative to the artifact or project root. */
+  readonly file?: string;
+  /** The span to edit. */
+  readonly range?: readonly [number, number, number, number];
+  /** The replacement or inserted text. */
+  readonly text?: string;
+  /** The command to run, for `kind: "command"`. */
+  readonly command?: string;
+}
+/** Where the problem is: a source position (1-based) or a place in a rendered viewport. */
+export type DiagnosticLocation = {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+} | {
+  readonly viewport: string;
+  readonly selector?: string;
+};
+/** One diagnostic (INTERFACES §13). */
+export interface Diagnostic {
+  /** The stable code, `MOSTRA_<AREA>_<NAME>`. */
+  readonly code: DiagnosticCode;
+  /** How bad it is. */
+  readonly severity: DiagnosticSeverity;
+  /** What is wrong, for this occurrence. */
+  readonly message: string;
+  /** What to do: one imperative sentence. */
+  readonly hint?: string;
+  /** A machine-applicable fix, when one exists. */
+  readonly fix?: DiagnosticFix;
+  /** Where the problem is, when it has a place. */
+  readonly location?: DiagnosticLocation;
+  /** The stage of work that produced it. */
+  readonly phase: DiagnosticPhase;
+  /** The code's documentation page: `${docsBase}/errors/${code}` (D37). */
+  readonly docs: string;
+  /** How many identical occurrences this one stands for, when deduplicated. */
+  readonly count?: number;
+}
+/** The Zod schema of the `DiagnosticSeverity` type. */
+export declare const DiagnosticSeverity: z.ZodType<DiagnosticSeverity, string>;
+/** The Zod schema of the `DiagnosticPhase` type. */
+export declare const DiagnosticPhase: z.ZodType<DiagnosticPhase, string>;
+/** The Zod schema of the `DiagnosticFix` type. */
+export declare const DiagnosticFix: z.ZodType<DiagnosticFix>;
+/** The Zod schema of the `DiagnosticLocation` type. */
+export declare const DiagnosticLocation: z.ZodType<DiagnosticLocation>;
+/** The Zod schema of the `Diagnostic` type. */
+export declare const Diagnostic: z.ZodType<Diagnostic>;
+//#endregion
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/diagnostics/diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.d.ts","names":[],"sources":["../../src/diagnostics/diagnostic.ts"],"mappings":";;;;;;YAWY;;qBAiCC,2BAA2B;;;;;YAqC5B,2BAA2B;;;;;YAM3B;;YAGA;;;;;iBAqBK;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;YAIC;WACG;WAAuB;WAAuB;;WAC9C;WAA2B;;;iBAGzB;;WAEN,MAAM;;WAEN,UAAU;;WAEV;;WAEA;;WAEA,MAAM;;WAEN,WAAW;;WAEX,OAAO;;WAEP;;WAEA;;;qBAkBE,oBAAoB,EAAE,QAAQ;;qBAQ9B,iBAAiB,EAAE,QAAQ;;qBAwB3B,eAAe,EAAE,QAAQ;;qBAezB,oBAAoB,EAAE,QAAQ;;qBAW9B,YAAY,EAAE,QAAQ"}

package/dist/diagnostics/diagnostic.js

@@ -0,0 +1,131 @@
+import { wireRegistry } from "../wire-registry.js";
+import * as z from "zod";
+//#region src/diagnostics/diagnostic.ts
+/**
+* The one diagnostic object every Mostra interface uses for errors, warnings and hints
+* (INTERFACES §1 and §13, AX-03).
+*/
+/** Every diagnostic area, in INTERFACES §13 order. */
+const DIAGNOSTIC_AREAS = [
+	"MANIFEST",
+	"BUILD",
+	"TYPE",
+	"LINT",
+	"DEP",
+	"KIT",
+	"FIELD",
+	"ACTION",
+	"LIVE",
+	"RUNTIME",
+	"CONSOLE",
+	"NETWORK",
+	"A11Y",
+	"VISUAL",
+	"SMOKE",
+	"REGRESSION",
+	"TERM",
+	"PUBLISH",
+	"SUBMIT",
+	"HOST",
+	"HOME",
+	"HYGIENE",
+	"SECRET",
+	"SHARE",
+	"VERIFY",
+	"TARGET",
+	"ENV",
+	"PLATFORM",
+	"ARTIFACT",
+	"CLI"
+];
+const positiveInt = z.int().min(1);
+/**
+* Codes on the wire accept any area, so a client keeps working when a newer Mostra reports a code
+* from an area it doesn't know yet. Producers are typed against {@link DiagnosticArea}.
+*/
+const codeSchema = z.string().regex(/^MOSTRA_[A-Z0-9]+_[A-Z0-9_]+$/).register(wireRegistry, {
+	id: "DiagnosticCode",
+	description: "Stable diagnostic code: MOSTRA_<AREA>_<NAME>."
+});
+/** The Zod schema of the `DiagnosticSeverity` type. */
+const DiagnosticSeverity = z.enum([
+	"error",
+	"warning",
+	"hint"
+]).register(wireRegistry, {
+	id: "DiagnosticSeverity",
+	description: "How bad it is: error only for definite failures."
+});
+/** The Zod schema of the `DiagnosticPhase` type. */
+const DiagnosticPhase = z.enum([
+	"manifest",
+	"compile",
+	"lint",
+	"runtime",
+	"console",
+	"network",
+	"a11y",
+	"visual",
+	"smoke",
+	"regression",
+	"contract",
+	"publish",
+	"host",
+	"hygiene",
+	"platform"
+]).register(wireRegistry, {
+	id: "DiagnosticPhase",
+	description: "The stage of work that produced the diagnostic."
+});
+/** The Zod schema of the `DiagnosticFix` type. */
+const DiagnosticFix = z.object({
+	kind: z.enum([
+		"replace",
+		"insert",
+		"delete",
+		"command"
+	]),
+	file: z.string().exactOptional(),
+	range: z.tuple([
+		positiveInt,
+		positiveInt,
+		positiveInt,
+		positiveInt
+	]).readonly().exactOptional(),
+	text: z.string().exactOptional(),
+	command: z.string().exactOptional()
+}).register(wireRegistry, {
+	id: "DiagnosticFix",
+	description: "A machine-applicable fix; range is [startLine, startColumn, endLine, endColumn], 1-based, end exclusive."
+});
+/** The Zod schema of the `DiagnosticLocation` type. */
+const DiagnosticLocation = z.union([z.object({
+	file: z.string(),
+	line: positiveInt,
+	column: positiveInt
+}), z.object({
+	viewport: z.string(),
+	selector: z.string().exactOptional()
+})]).register(wireRegistry, {
+	id: "DiagnosticLocation",
+	description: "A 1-based source position, or a place in a rendered viewport."
+});
+/** The Zod schema of the `Diagnostic` type. */
+const Diagnostic = z.object({
+	code: codeSchema,
+	severity: DiagnosticSeverity,
+	message: z.string(),
+	hint: z.string().exactOptional(),
+	fix: DiagnosticFix.exactOptional(),
+	location: DiagnosticLocation.exactOptional(),
+	phase: DiagnosticPhase,
+	docs: z.url(),
+	count: positiveInt.exactOptional()
+}).register(wireRegistry, {
+	id: "Diagnostic",
+	description: "One diagnostic: a stable code, severity, message, hint, fix and docs link."
+});
+//#endregion
+export { DIAGNOSTIC_AREAS, Diagnostic, DiagnosticFix, DiagnosticLocation, DiagnosticPhase, DiagnosticSeverity };
+
+//# sourceMappingURL=diagnostic.js.map

package/dist/diagnostics/diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.js","names":[],"sources":["../../src/diagnostics/diagnostic.ts"],"sourcesContent":["/**\n * The one diagnostic object every Mostra interface uses for errors, warnings and hints\n * (INTERFACES §1 and §13, AX-03).\n */\nimport * as z from \"zod\";\nimport { wireRegistry } from \"../wire-registry.ts\";\n\n/**\n * Diagnostic areas. A code is `MOSTRA_<AREA>_<NAME>`. INTERFACES §13 holds the authoritative list,\n * which only grows.\n */\nexport type DiagnosticArea =\n  | \"MANIFEST\"\n  | \"BUILD\"\n  | \"TYPE\"\n  | \"LINT\"\n  | \"DEP\"\n  | \"KIT\"\n  | \"FIELD\"\n  | \"ACTION\"\n  | \"LIVE\"\n  | \"RUNTIME\"\n  | \"CONSOLE\"\n  | \"NETWORK\"\n  | \"A11Y\"\n  | \"VISUAL\"\n  | \"SMOKE\"\n  | \"REGRESSION\"\n  | \"TERM\"\n  | \"PUBLISH\"\n  | \"SUBMIT\"\n  | \"HOST\"\n  | \"HOME\"\n  | \"HYGIENE\"\n  | \"SECRET\"\n  | \"SHARE\"\n  | \"VERIFY\"\n  | \"TARGET\"\n  | \"ENV\"\n  | \"PLATFORM\"\n  | \"ARTIFACT\"\n  | \"CLI\";\n\n/** Every diagnostic area, in INTERFACES §13 order. */\nexport const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [\n  \"MANIFEST\",\n  \"BUILD\",\n  \"TYPE\",\n  \"LINT\",\n  \"DEP\",\n  \"KIT\",\n  \"FIELD\",\n  \"ACTION\",\n  \"LIVE\",\n  \"RUNTIME\",\n  \"CONSOLE\",\n  \"NETWORK\",\n  \"A11Y\",\n  \"VISUAL\",\n  \"SMOKE\",\n  \"REGRESSION\",\n  \"TERM\",\n  \"PUBLISH\",\n  \"SUBMIT\",\n  \"HOST\",\n  \"HOME\",\n  \"HYGIENE\",\n  \"SECRET\",\n  \"SHARE\",\n  \"VERIFY\",\n  \"TARGET\",\n  \"ENV\",\n  \"PLATFORM\",\n  \"ARTIFACT\",\n  \"CLI\",\n];\n\n/**\n * A diagnostic code. Codes are semver surface: once released, a code keeps its meaning and is\n * never removed (AX-03).\n */\nexport type DiagnosticCode = `MOSTRA_${DiagnosticArea}_${string}`;\n\n/**\n * How bad it is. `error` is only for definite failures; observations that might be fine are\n * warnings (D72).\n */\nexport type DiagnosticSeverity = \"error\" | \"warning\" | \"hint\";\n\n/** The stage of work that produced the diagnostic. */\nexport type DiagnosticPhase =\n  | \"manifest\"\n  | \"compile\"\n  | \"lint\"\n  | \"runtime\"\n  | \"console\"\n  | \"network\"\n  | \"a11y\"\n  | \"visual\"\n  | \"smoke\"\n  | \"regression\"\n  | \"contract\"\n  | \"publish\"\n  | \"host\"\n  | \"hygiene\"\n  | \"platform\";\n\n/**\n * A machine-applicable fix. `range` is `[startLine, startColumn, endLine, endColumn]`, 1-based,\n * with the end exclusive.\n */\nexport interface DiagnosticFix {\n  /** Replace, insert or delete text in `file`, or run `command`. */\n  readonly kind: \"replace\" | \"insert\" | \"delete\" | \"command\";\n  /** The file to edit, relative to the artifact or project root. */\n  readonly file?: string;\n  /** The span to edit. */\n  readonly range?: readonly [number, number, number, number];\n  /** The replacement or inserted text. */\n  readonly text?: string;\n  /** The command to run, for `kind: \"command\"`. */\n  readonly command?: string;\n}\n\n/** Where the problem is: a source position (1-based) or a place in a rendered viewport. */\nexport type DiagnosticLocation =\n  | { readonly file: string; readonly line: number; readonly column: number }\n  | { readonly viewport: string; readonly selector?: string };\n\n/** One diagnostic (INTERFACES §13). */\nexport interface Diagnostic {\n  /** The stable code, `MOSTRA_<AREA>_<NAME>`. */\n  readonly code: DiagnosticCode;\n  /** How bad it is. */\n  readonly severity: DiagnosticSeverity;\n  /** What is wrong, for this occurrence. */\n  readonly message: string;\n  /** What to do: one imperative sentence. */\n  readonly hint?: string;\n  /** A machine-applicable fix, when one exists. */\n  readonly fix?: DiagnosticFix;\n  /** Where the problem is, when it has a place. */\n  readonly location?: DiagnosticLocation;\n  /** The stage of work that produced it. */\n  readonly phase: DiagnosticPhase;\n  /** The code's documentation page: `${docsBase}/errors/${code}` (D37). */\n  readonly docs: string;\n  /** How many identical occurrences this one stands for, when deduplicated. */\n  readonly count?: number;\n}\n\nconst positiveInt = z.int().min(1);\n\n/**\n * Codes on the wire accept any area, so a client keeps working when a newer Mostra reports a code\n * from an area it doesn't know yet. Producers are typed against {@link DiagnosticArea}.\n */\nconst codeSchema = z\n  .string()\n  .regex(/^MOSTRA_[A-Z0-9]+_[A-Z0-9_]+$/)\n  .register(wireRegistry, {\n    id: \"DiagnosticCode\",\n    description: \"Stable diagnostic code: MOSTRA_<AREA>_<NAME>.\",\n  }) as unknown as z.ZodType<DiagnosticCode, string>;\n\n/** The Zod schema of the `DiagnosticSeverity` type. */\nexport const DiagnosticSeverity: z.ZodType<DiagnosticSeverity, string> = z\n  .enum([\"error\", \"warning\", \"hint\"])\n  .register(wireRegistry, {\n    id: \"DiagnosticSeverity\",\n    description: \"How bad it is: error only for definite failures.\",\n  });\n\n/** The Zod schema of the `DiagnosticPhase` type. */\nexport const DiagnosticPhase: z.ZodType<DiagnosticPhase, string> = z\n  .enum([\n    \"manifest\",\n    \"compile\",\n    \"lint\",\n    \"runtime\",\n    \"console\",\n    \"network\",\n    \"a11y\",\n    \"visual\",\n    \"smoke\",\n    \"regression\",\n    \"contract\",\n    \"publish\",\n    \"host\",\n    \"hygiene\",\n    \"platform\",\n  ])\n  .register(wireRegistry, {\n    id: \"DiagnosticPhase\",\n    description: \"The stage of work that produced the diagnostic.\",\n  });\n\n/** The Zod schema of the `DiagnosticFix` type. */\nexport const DiagnosticFix: z.ZodType<DiagnosticFix> = z\n  .object({\n    kind: z.enum([\"replace\", \"insert\", \"delete\", \"command\"]),\n    file: z.string().exactOptional(),\n    range: z.tuple([positiveInt, positiveInt, positiveInt, positiveInt]).readonly().exactOptional(),\n    text: z.string().exactOptional(),\n    command: z.string().exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"DiagnosticFix\",\n    description:\n      \"A machine-applicable fix; range is [startLine, startColumn, endLine, endColumn], 1-based, end exclusive.\",\n  });\n\n/** The Zod schema of the `DiagnosticLocation` type. */\nexport const DiagnosticLocation: z.ZodType<DiagnosticLocation> = z\n  .union([\n    z.object({ file: z.string(), line: positiveInt, column: positiveInt }),\n    z.object({ viewport: z.string(), selector: z.string().exactOptional() }),\n  ])\n  .register(wireRegistry, {\n    id: \"DiagnosticLocation\",\n    description: \"A 1-based source position, or a place in a rendered viewport.\",\n  });\n\n/** The Zod schema of the `Diagnostic` type. */\nexport const Diagnostic: z.ZodType<Diagnostic> = z\n  .object({\n    code: codeSchema,\n    severity: DiagnosticSeverity,\n    message: z.string(),\n    hint: z.string().exactOptional(),\n    fix: DiagnosticFix.exactOptional(),\n    location: DiagnosticLocation.exactOptional(),\n    phase: DiagnosticPhase,\n    docs: z.url(),\n    count: positiveInt.exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"Diagnostic\",\n    description: \"One diagnostic: a stable code, severity, message, hint, fix and docs link.\",\n  });\n"],"mappings":";;;;;;;;AA4CA,MAAa,mBAA8C;CACzD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AA4EA,MAAM,cAAc,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;;;;;AAMjC,MAAM,aAAa,EAChB,OAAO,CAAC,CACR,MAAM,+BAA+B,CAAC,CACtC,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,qBAA4D,EACtE,KAAK;CAAC;CAAS;CAAW;AAAM,CAAC,CAAC,CAClC,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,kBAAsD,EAChE,KAAK;CACJ;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,gBAA0C,EACpD,OAAO;CACN,MAAM,EAAE,KAAK;EAAC;EAAW;EAAU;EAAU;CAAS,CAAC;CACvD,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,OAAO,EAAE,MAAM;EAAC;EAAa;EAAa;EAAa;CAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;CAC9F,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,SAAS,EAAE,OAAO,CAAC,CAAC,cAAc;AACpC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC;;AAGH,MAAa,qBAAoD,EAC9D,MAAM,CACL,EAAE,OAAO;CAAE,MAAM,EAAE,OAAO;CAAG,MAAM;CAAa,QAAQ;AAAY,CAAC,GACrE,EAAE,OAAO;CAAE,UAAU,EAAE,OAAO;CAAG,UAAU,EAAE,OAAO,CAAC,CAAC,cAAc;AAAE,CAAC,CACzE,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,aAAoC,EAC9C,OAAO;CACN,MAAM;CACN,UAAU;CACV,SAAS,EAAE,OAAO;CAClB,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,KAAK,cAAc,cAAc;CACjC,UAAU,mBAAmB,cAAc;CAC3C,OAAO;CACP,MAAM,EAAE,IAAI;CACZ,OAAO,YAAY,cAAc;AACnC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC"}

package/dist/diagnostics/spec.d.ts

@@ -0,0 +1,49 @@
+import { DiagnosticArea, DiagnosticFix, DiagnosticLocation, DiagnosticPhase, DiagnosticSeverity } from "./diagnostic.js";
+//#region src/diagnostics/spec.d.ts
+/** Everything Mostra knows about one code, besides the code itself. */
+export interface DiagnosticSpec {
+  /** The severity of every occurrence. */
+  readonly severity: DiagnosticSeverity;
+  /** The stage of work that reports it. */
+  readonly phase: DiagnosticPhase;
+  /** One line naming the condition. It is the docs page's title. */
+  readonly title: string;
+  /** The default hint: one imperative sentence. An occurrence may give a more specific one. */
+  readonly hint: string;
+  /** The docs page body. */
+  readonly docs: {
+    /** What the code means and when Mostra reports it. */
+    readonly explanation: string;
+    /** The minimal fix. */
+    readonly fix: string;
+  };
+  /**
+   * Set when Mostra no longer reports the code, saying what replaced it. Codes are never
+   * removed (AX-03).
+   */
+  readonly deprecated?: string;
+}
+/** The catalog of one area: exactly the codes `C`, each with its spec. */
+export type AreaCatalog<C extends `MOSTRA_${DiagnosticArea}_${string}`> = { readonly [K in C]: DiagnosticSpec; };
+/**
+ * Where diagnostics link by default: the GitHub Pages docs site (D37). Hosts and the runtime pass
+ * their own base when the docs move.
+ */
+export declare const DEFAULT_DOCS_BASE: string;
+/** The docs page for `code` under `docsBase`: `${docsBase}/errors/${code}`. */
+export declare function docsUrl(code: string, docsBase?: string): string;
+/** The parts of a diagnostic that belong to one occurrence rather than to its code. */
+export interface DiagnosticDetails {
+  /** What is wrong, for this occurrence. Never include secrets or capability tokens. */
+  readonly message: string;
+  /** Replaces the catalog's default hint when the occurrence allows a more specific one. */
+  readonly hint?: string;
+  /** A machine-applicable fix. */
+  readonly fix?: DiagnosticFix;
+  /** Where the problem is. */
+  readonly location?: DiagnosticLocation;
+  /** How many identical occurrences this one stands for. */
+  readonly count?: number;
+}
+//#endregion
+//# sourceMappingURL=spec.d.ts.map