@mostra/protocol 0.0.0-placeholder → 0.1.0

package/dist/verify.js

@@ -0,0 +1,243 @@
+import { wireRegistry } from "./wire-registry.js";
+import { Diagnostic } from "./diagnostics/diagnostic.js";
+import * as z from "zod";
+//#region src/verify.ts
+/**
+* `verify` (D29, D41, D55, D72, D138; INTERFACES §13): the verdict it returns, the viewports it
+* renders, and the image-token estimates every screenshot carries. Pure and free of I/O, so the
+* runtime, the verify runner, the CLI and the MCP server share one definition.
+*/
+/** The Zod schema of the `ScreenshotPolicy` type. */
+const ScreenshotPolicy = z.enum([
+	"on-failure",
+	"always",
+	"never"
+]).register(wireRegistry, {
+	id: "ScreenshotPolicy",
+	description: "When screenshots are returned: on failure (the default), always or never."
+});
+/** The viewports verify renders when the manifest names none (ROUND-3 §9): desktop and mobile. */
+const DEFAULT_VIEWPORTS = [{
+	name: "desktop",
+	width: 1280,
+	height: 800
+}, {
+	name: "mobile",
+	width: 390,
+	height: 844
+}];
+const NAMED_VIEWPORTS = {
+	desktop: {
+		name: "desktop",
+		width: 1280,
+		height: 800
+	},
+	mobile: {
+		name: "mobile",
+		width: 390,
+		height: 844
+	},
+	tablet: {
+		name: "tablet",
+		width: 768,
+		height: 1024
+	}
+};
+/**
+* The viewports a manifest's `verify.viewports` names (`desktop`, `mobile`, `tablet`, or
+* `<width>x<height>` from 200 to 4000 px), in its order and without repeats; the defaults when it
+* names none. Returns the names it couldn't read beside them.
+*/
+function viewportsFor(names) {
+	if (names === void 0 || names.length === 0) return {
+		viewports: DEFAULT_VIEWPORTS,
+		unknown: []
+	};
+	const viewports = [];
+	const unknown = [];
+	for (const raw of names) {
+		const name = raw.trim().toLowerCase();
+		const sized = /^(\d{3,4})x(\d{3,4})$/.exec(name);
+		const viewport = NAMED_VIEWPORTS[name] ?? (sized ? {
+			name,
+			width: Number(sized[1]),
+			height: Number(sized[2])
+		} : void 0);
+		if (!viewport || viewport.width < 200 || viewport.height < 200 || viewport.width > 4e3 || viewport.height > 4e3) {
+			unknown.push(raw);
+			continue;
+		}
+		if (!viewports.some((known) => known.name === viewport.name)) viewports.push(viewport);
+	}
+	return {
+		viewports: viewports.length > 0 ? viewports : DEFAULT_VIEWPORTS,
+		unknown
+	};
+}
+/** Claude: tokens of an image already within its tier's limits. */
+const claudeTokens = (width, height) => Math.ceil(width / 28) * Math.ceil(height / 28);
+/**
+* The size Claude resizes an image to (its documented reference implementation): the largest
+* aspect-preserving size whose 28-px-rounded sides fit `maxEdge` and whose tokens fit `maxTokens`.
+*/
+function claudeSize(width, height, maxEdge, maxTokens) {
+	const fits = (w, h) => Math.ceil(w / 28) * 28 <= maxEdge && Math.ceil(h / 28) * 28 <= maxEdge && claudeTokens(w, h) <= maxTokens;
+	if (fits(width, height)) return [width, height];
+	if (height > width) {
+		const [h, w] = claudeSize(height, width, maxEdge, maxTokens);
+		return [w, h];
+	}
+	const aspect = width / height;
+	let lo = 1;
+	let hi = width;
+	while (lo + 1 < hi) {
+		const mid = Math.floor((lo + hi) / 2);
+		if (fits(mid, Math.max(Math.round(mid / aspect), 1))) lo = mid;
+		else hi = mid;
+	}
+	return [lo, Math.max(Math.round(lo / aspect), 1)];
+}
+/** GPT at `detail: "high"`: fit 2048 × 2048, then a 2,500-patch budget, then the 1.2 multiplier. */
+function gptTokens(width, height) {
+	let w = width;
+	let h = height;
+	const edge = Math.min(1, 2048 / Math.max(w, h));
+	if (edge < 1) {
+		w = Math.max(1, Math.round(w * edge));
+		h = Math.max(1, Math.round(h * edge));
+	}
+	let patches = Math.ceil(w / 32) * Math.ceil(h / 32);
+	const budget = 2500;
+	if (patches > budget) {
+		const shrink = Math.sqrt(1024 * budget / (w * h));
+		const adjusted = shrink * Math.min(Math.floor(w * shrink / 32) / (w * shrink / 32), Math.floor(h * shrink / 32) / (h * shrink / 32));
+		patches = Math.ceil(Math.floor(w * adjusted) / 32) * Math.ceil(Math.floor(h * adjusted) / 32);
+	}
+	return Math.ceil(patches * 1.2);
+}
+/**
+* What an image of `width` × `height` pixels costs Claude, GPT and Gemini to read, by each
+* provider's published rule as verified on 2026-10-17 (VERIFIED_FACTS, WP-09). Estimates: harnesses
+* use them to budget, and each provider may round differently by a token.
+*/
+function estimateImageTokens(width, height) {
+	const [cw, ch] = claudeSize(width, height, 2576, 4784);
+	return {
+		claude: claudeTokens(cw, ch),
+		gpt: gptTokens(width, height),
+		gemini: 1120
+	};
+}
+const tokenEstimate = z.object({
+	claude: z.int().min(0),
+	gpt: z.int().min(0),
+	gemini: z.int().min(0)
+});
+/** The Zod schema of the `VerifyVerdict` type. */
+const VerifyVerdict = z.object({
+	status: z.enum(["pass", "fail"]),
+	artifact: z.object({
+		id: z.string().exactOptional(),
+		path: z.string(),
+		sourceDigest: z.string(),
+		envDigest: z.string(),
+		versionId: z.string().exactOptional()
+	}),
+	diagnostics: z.array(Diagnostic).readonly(),
+	screenshots: z.array(z.object({
+		viewport: z.string(),
+		path: z.string(),
+		width: z.int().min(1),
+		height: z.int().min(1),
+		tokensEstimate: tokenEstimate,
+		returned: z.boolean()
+	})).readonly(),
+	aria: z.array(z.object({
+		viewport: z.string(),
+		path: z.string(),
+		summary: z.string()
+	})).readonly(),
+	smoke: z.object({
+		interactions: z.int().min(0),
+		skippedActions: z.array(z.string()).readonly(),
+		stateChanges: z.int().min(0)
+	}),
+	regressions: z.object({
+		against: z.string().exactOptional(),
+		aria: z.string().exactOptional(),
+		pixels: z.array(z.object({
+			viewport: z.string(),
+			ratio: z.number().min(0).max(1)
+		})).readonly().exactOptional(),
+		contracts: z.array(z.string()).readonly().exactOptional()
+	}),
+	timingsMs: z.record(z.string(), z.number().min(0))
+}).register(wireRegistry, {
+	id: "VerifyVerdict",
+	description: "The verdict of artifact/verify: pass or fail, diagnostics, screenshots with token estimates, ARIA snapshots, the smoke test, regressions and timings."
+});
+/** The notification `artifact/verify` sends while it runs, when the client accepts it. */
+const ARTIFACT_PROGRESS = "artifact/progress";
+/** The Zod schema of the `ArtifactProgressParams` type. */
+const ArtifactProgressParams = z.object({
+	progressToken: z.string().min(1),
+	stage: z.string().min(1),
+	fraction: z.number().min(0).max(1).exactOptional()
+}).register(wireRegistry, {
+	id: "ArtifactProgressParams",
+	description: "One stage of a long request (artifact/verify) started."
+});
+/**
+* The global the verify runner's recorder installs in every frame of a render: a page in the
+* `verify` target reports errors its React error boundaries caught through it, with their
+* `cause` chains, so the runner judges each by its cause (D138 items 2 and 3, Opus review finding
+* 3). Viewers' pages never have it.
+*/
+const VERIFY_REPORT = "__mostraVerifyReport";
+/**
+* What a verify run's page tells the runner about its fields (D138 item 3), on
+* `globalThis[VERIFY_PROBE]` in the `verify` target only: every field it mounted, how, and with
+* which initial value's type; internal to Mostra.
+*/
+const VERIFY_PROBE = "__mostraVerify";
+/** The verify runner's methods (ARCHITECTURE §1): the supervisor asks, the runner answers; internal to Mostra. */
+const VERIFY_RUNNER_METHODS = {
+	/** Opens one capability link in a fresh browser context and reports what the page did. */
+	render: "verify/render",
+	/** Compares two screenshots and writes their difference. */
+	compare: "verify/compare"
+};
+/** A one-line count of an ARIA snapshot: headings, controls and landmarks. */
+function ariaSummary(text) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const match of text.matchAll(/^\s*- ([a-z]+)\b/gm)) {
+		const role = match[1];
+		counts.set(role, (counts.get(role) ?? 0) + 1);
+	}
+	const parts = [
+		["heading", "headings"],
+		["button", "buttons"],
+		["link", "links"],
+		["textbox", "text fields"],
+		["checkbox", "checkboxes"],
+		["combobox", "comboboxes"],
+		["tab", "tabs"],
+		["img", "images"],
+		["table", "tables"]
+	].filter(([role]) => counts.has(role)).map(([role, plural]) => `${counts.get(role)} ${counts.get(role) === 1 ? role : plural}`);
+	const landmarks = [
+		"main",
+		"navigation",
+		"banner",
+		"contentinfo",
+		"form",
+		"region",
+		"dialog"
+	].filter((role) => counts.has(role));
+	if (landmarks.length > 0) parts.push(`landmarks: ${landmarks.join(", ")}`);
+	return parts.length > 0 ? parts.join(", ") : "no headings, controls or landmarks";
+}
+//#endregion
+export { ARTIFACT_PROGRESS, ArtifactProgressParams, DEFAULT_VIEWPORTS, ScreenshotPolicy, VERIFY_PROBE, VERIFY_REPORT, VERIFY_RUNNER_METHODS, VerifyVerdict, ariaSummary, estimateImageTokens, viewportsFor };
+
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","names":[],"sources":["../src/verify.ts"],"sourcesContent":["/**\n * `verify` (D29, D41, D55, D72, D138; INTERFACES §13): the verdict it returns, the viewports it\n * renders, and the image-token estimates every screenshot carries. Pure and free of I/O, so the\n * runtime, the verify runner, the CLI and the MCP server share one definition.\n */\nimport * as z from \"zod\";\nimport { Diagnostic } from \"./diagnostics/diagnostic.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** When a verdict's screenshots are handed to the caller (AX-05): images cost tokens. */\nexport type ScreenshotPolicy = \"on-failure\" | \"always\" | \"never\";\n\n/** The Zod schema of the `ScreenshotPolicy` type. */\nexport const ScreenshotPolicy: z.ZodType<ScreenshotPolicy, string> = z\n  .enum([\"on-failure\", \"always\", \"never\"])\n  .register(wireRegistry, {\n    id: \"ScreenshotPolicy\",\n    description: \"When screenshots are returned: on failure (the default), always or never.\",\n  });\n\n/** One viewport verify renders at device pixel ratio 1. */\nexport interface VerifyViewport {\n  /** Its name in the verdict: `desktop`, `mobile`, `tablet`, or `<width>x<height>`. */\n  readonly name: string;\n  /** Its width in CSS pixels, which at DPR 1 are the screenshot's pixels. */\n  readonly width: number;\n  /** Its height in CSS pixels. */\n  readonly height: number;\n}\n\n/** The viewports verify renders when the manifest names none (ROUND-3 §9): desktop and mobile. */\nexport const DEFAULT_VIEWPORTS: readonly VerifyViewport[] = [\n  { name: \"desktop\", width: 1280, height: 800 },\n  { name: \"mobile\", width: 390, height: 844 },\n];\n\nconst NAMED_VIEWPORTS: Readonly<Record<string, VerifyViewport>> = {\n  desktop: { name: \"desktop\", width: 1280, height: 800 },\n  mobile: { name: \"mobile\", width: 390, height: 844 },\n  tablet: { name: \"tablet\", width: 768, height: 1024 },\n};\n\n/**\n * The viewports a manifest's `verify.viewports` names (`desktop`, `mobile`, `tablet`, or\n * `<width>x<height>` from 200 to 4000 px), in its order and without repeats; the defaults when it\n * names none. Returns the names it couldn't read beside them.\n */\nexport function viewportsFor(names: readonly string[] | undefined): {\n  readonly viewports: readonly VerifyViewport[];\n  readonly unknown: readonly string[];\n} {\n  if (names === undefined || names.length === 0)\n    return { viewports: DEFAULT_VIEWPORTS, unknown: [] };\n  const viewports: VerifyViewport[] = [];\n  const unknown: string[] = [];\n  for (const raw of names) {\n    const name = raw.trim().toLowerCase();\n    const sized = /^(\\d{3,4})x(\\d{3,4})$/.exec(name);\n    const viewport =\n      NAMED_VIEWPORTS[name] ??\n      (sized ? { name, width: Number(sized[1]), height: Number(sized[2]) } : undefined);\n    if (\n      !viewport ||\n      viewport.width < 200 ||\n      viewport.height < 200 ||\n      viewport.width > 4000 ||\n      viewport.height > 4000\n    ) {\n      unknown.push(raw);\n      continue;\n    }\n    if (!viewports.some((known) => known.name === viewport.name)) viewports.push(viewport);\n  }\n  return { viewports: viewports.length > 0 ? viewports : DEFAULT_VIEWPORTS, unknown };\n}\n\n/** What one image costs each model family to read (D138 item 9). */\nexport interface TokenEstimate {\n  /** Claude's high-resolution tier (Claude 4.7 and later). */\n  readonly claude: number;\n  /** GPT at `detail: \"high\"` (gpt-5.5, gpt-5.6, gpt-6-astra). */\n  readonly gpt: number;\n  /** Gemini 3 and 4 at the default media resolution. */\n  readonly gemini: number;\n}\n\n/** Claude: tokens of an image already within its tier's limits. */\nconst claudeTokens = (width: number, height: number): number =>\n  Math.ceil(width / 28) * Math.ceil(height / 28);\n\n/**\n * The size Claude resizes an image to (its documented reference implementation): the largest\n * aspect-preserving size whose 28-px-rounded sides fit `maxEdge` and whose tokens fit `maxTokens`.\n */\nfunction claudeSize(\n  width: number,\n  height: number,\n  maxEdge: number,\n  maxTokens: number,\n): readonly [number, number] {\n  const fits = (w: number, h: number): boolean =>\n    Math.ceil(w / 28) * 28 <= maxEdge &&\n    Math.ceil(h / 28) * 28 <= maxEdge &&\n    claudeTokens(w, h) <= maxTokens;\n  if (fits(width, height)) return [width, height];\n  if (height > width) {\n    const [h, w] = claudeSize(height, width, maxEdge, maxTokens);\n    return [w, h];\n  }\n  const aspect = width / height;\n  let lo = 1;\n  let hi = width;\n  while (lo + 1 < hi) {\n    const mid = Math.floor((lo + hi) / 2);\n    if (fits(mid, Math.max(Math.round(mid / aspect), 1))) lo = mid;\n    else hi = mid;\n  }\n  return [lo, Math.max(Math.round(lo / aspect), 1)];\n}\n\n/** GPT at `detail: \"high\"`: fit 2048 × 2048, then a 2,500-patch budget, then the 1.2 multiplier. */\nfunction gptTokens(width: number, height: number): number {\n  let w = width;\n  let h = height;\n  const edge = Math.min(1, 2048 / Math.max(w, h));\n  if (edge < 1) {\n    w = Math.max(1, Math.round(w * edge));\n    h = Math.max(1, Math.round(h * edge));\n  }\n  let patches = Math.ceil(w / 32) * Math.ceil(h / 32);\n  const budget = 2500;\n  if (patches > budget) {\n    const shrink = Math.sqrt((32 ** 2 * budget) / (w * h));\n    const adjusted =\n      shrink *\n      Math.min(\n        Math.floor((w * shrink) / 32) / ((w * shrink) / 32),\n        Math.floor((h * shrink) / 32) / ((h * shrink) / 32),\n      );\n    patches = Math.ceil(Math.floor(w * adjusted) / 32) * Math.ceil(Math.floor(h * adjusted) / 32);\n  }\n  return Math.ceil(patches * 1.2);\n}\n\n/**\n * What an image of `width` × `height` pixels costs Claude, GPT and Gemini to read, by each\n * provider's published rule as verified on 2026-10-17 (VERIFIED_FACTS, WP-09). Estimates: harnesses\n * use them to budget, and each provider may round differently by a token.\n */\nexport function estimateImageTokens(width: number, height: number): TokenEstimate {\n  const [cw, ch] = claudeSize(width, height, 2576, 4784);\n  return { claude: claudeTokens(cw, ch), gpt: gptTokens(width, height), gemini: 1120 };\n}\n\n/** One screenshot in a verdict (AX-05). */\nexport interface VerdictScreenshot {\n  /** The viewport's name. */\n  readonly viewport: string;\n  /** The PNG, at device pixel ratio 1. */\n  readonly path: string;\n  /** The image's width in pixels. */\n  readonly width: number;\n  /** The image's height in pixels. */\n  readonly height: number;\n  /** What reading the image costs each model family ({@link estimateImageTokens}). */\n  readonly tokensEstimate: TokenEstimate;\n  /** Whether the caller is handed the image: on failure, or when asked (`screenshots`). */\n  readonly returned: boolean;\n}\n\n/** One ARIA snapshot in a verdict: the text-only picture of what a viewport shows. */\nexport interface VerdictAria {\n  /** The viewport's name. */\n  readonly viewport: string;\n  /** The snapshot's YAML. */\n  readonly path: string;\n  /** A one-line count of what it holds: headings, controls, landmarks. */\n  readonly summary: string;\n}\n\n/** The verdict of one `verify` run (INTERFACES §13). `status` is `fail` exactly when an error exists. */\nexport interface VerifyVerdict {\n  /** `fail` when any diagnostic is an error, else `pass`. */\n  readonly status: \"pass\" | \"fail\";\n  /** What was verified. */\n  readonly artifact: {\n    /** The artifact, when it has one already: a manifest `id` or a published path. */\n    readonly id?: string;\n    /** The source path as the request named it. */\n    readonly path: string;\n    /** The snapshot's digest (DATA_MODEL §2); empty when verify couldn't read the source. */\n    readonly sourceDigest: string;\n    /** The environment's digest, `lockDigest` included (DATA_MODEL §2); empty likewise. */\n    readonly envDigest: string;\n    /** The version this source would publish as, when the artifact is known (D89). */\n    readonly versionId?: string;\n  };\n  /** Every finding, errors first, identical ones folded with a `count`. */\n  readonly diagnostics: readonly Diagnostic[];\n  /** One per viewport rendered. */\n  readonly screenshots: readonly VerdictScreenshot[];\n  /** One per viewport rendered. */\n  readonly aria: readonly VerdictAria[];\n  /** What the smoke test did. */\n  readonly smoke: {\n    /** Controls the smoke test used. */\n    readonly interactions: number;\n    /** Server functions that don't check `dryRun()` and were refused instead of run (D55). */\n    readonly skippedActions: readonly string[];\n    /** Field writes the interactions caused. */\n    readonly stateChanges: number;\n  };\n  /** What changed since the last passing version; empty when there is none. */\n  readonly regressions: {\n    /**\n     * The last passing version: the newest whose recorded verdict passed (D138 item 4). When it is\n     * this very source, nothing needed comparing.\n     */\n    readonly against?: string;\n    /** Controls and landmarks the baseline had and this source doesn't, in brief. */\n    readonly aria?: string;\n    /** The share of pixels that differ from the baseline, per viewport. */\n    readonly pixels?: readonly { readonly viewport: string; readonly ratio: number }[];\n    /** Contracts the baseline had that this source drops: fields, actions, live sources, pages. */\n    readonly contracts?: readonly string[];\n  };\n  /** How long each stage took, in milliseconds, and `total`. */\n  readonly timingsMs: Readonly<Record<string, number>>;\n}\n\nconst tokenEstimate: z.ZodType<TokenEstimate> = z.object({\n  claude: z.int().min(0),\n  gpt: z.int().min(0),\n  gemini: z.int().min(0),\n});\n\n/** The Zod schema of the `VerifyVerdict` type. */\nexport const VerifyVerdict: z.ZodType<VerifyVerdict> = z\n  .object({\n    status: z.enum([\"pass\", \"fail\"]),\n    artifact: z.object({\n      id: z.string().exactOptional(),\n      path: z.string(),\n      sourceDigest: z.string(),\n      envDigest: z.string(),\n      versionId: z.string().exactOptional(),\n    }),\n    diagnostics: z.array(Diagnostic).readonly(),\n    screenshots: z\n      .array(\n        z.object({\n          viewport: z.string(),\n          path: z.string(),\n          width: z.int().min(1),\n          height: z.int().min(1),\n          tokensEstimate: tokenEstimate,\n          returned: z.boolean(),\n        }),\n      )\n      .readonly(),\n    aria: z\n      .array(z.object({ viewport: z.string(), path: z.string(), summary: z.string() }))\n      .readonly(),\n    smoke: z.object({\n      interactions: z.int().min(0),\n      skippedActions: z.array(z.string()).readonly(),\n      stateChanges: z.int().min(0),\n    }),\n    regressions: z.object({\n      against: z.string().exactOptional(),\n      aria: z.string().exactOptional(),\n      pixels: z\n        .array(z.object({ viewport: z.string(), ratio: z.number().min(0).max(1) }))\n        .readonly()\n        .exactOptional(),\n      contracts: z.array(z.string()).readonly().exactOptional(),\n    }),\n    timingsMs: z.record(z.string(), z.number().min(0)),\n  })\n  .register(wireRegistry, {\n    id: \"VerifyVerdict\",\n    description:\n      \"The verdict of artifact/verify: pass or fail, diagnostics, screenshots with token estimates, ARIA snapshots, the smoke test, regressions and timings.\",\n  });\n\n/** The notification `artifact/verify` sends while it runs, when the client accepts it. */\nexport const ARTIFACT_PROGRESS = \"artifact/progress\";\n\n/** `artifact/progress`: one stage of a long request started or ended. */\nexport interface ArtifactProgressParams {\n  /** The `progressToken` the request carried. */\n  readonly progressToken: string;\n  /** The stage that started: `prepare`, `compile`, `boot`, `render`, `smoke`, `regression`. */\n  readonly stage: string;\n  /** How much of the request is done, from 0 to 1, when known. */\n  readonly fraction?: number;\n}\n\n/** The Zod schema of the `ArtifactProgressParams` type. */\nexport const ArtifactProgressParams: z.ZodType<ArtifactProgressParams> = z\n  .object({\n    progressToken: z.string().min(1),\n    stage: z.string().min(1),\n    fraction: z.number().min(0).max(1).exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"ArtifactProgressParams\",\n    description: \"One stage of a long request (artifact/verify) started.\",\n  });\n\n/**\n * The global the verify runner's recorder installs in every frame of a render: a page in the\n * `verify` target reports errors its React error boundaries caught through it, with their\n * `cause` chains, so the runner judges each by its cause (D138 items 2 and 3, Opus review finding\n * 3). Viewers' pages never have it.\n */\nexport const VERIFY_REPORT = \"__mostraVerifyReport\";\n\n/**\n * What a verify run's page tells the runner about its fields (D138 item 3), on\n * `globalThis[VERIFY_PROBE]` in the `verify` target only: every field it mounted, how, and with\n * which initial value's type; internal to Mostra.\n */\nexport const VERIFY_PROBE = \"__mostraVerify\";\n\n/** One mounted field, as the probe reports it; internal to Mostra. */\nexport interface ProbedField {\n  /** The field ID. */\n  readonly id: string;\n  /** Its scope, as first mounted. */\n  readonly scope: \"viewer\" | \"artifact\";\n  /** The hook that named it: `useField`, `useChoice`, `useForm` or `storage`. */\n  readonly hook: string;\n  /** `typeof` its initial value, `array` or `null`. */\n  readonly initialType: string;\n  /** How many components have it mounted now. */\n  readonly mounts: number;\n  /** Other hook kinds, scopes or initial types it was mounted with, if any. */\n  readonly conflicts: readonly string[];\n}\n\n/** The verify runner's methods (ARCHITECTURE §1): the supervisor asks, the runner answers; internal to Mostra. */\nexport const VERIFY_RUNNER_METHODS = {\n  /** Opens one capability link in a fresh browser context and reports what the page did. */\n  render: \"verify/render\",\n  /** Compares two screenshots and writes their difference. */\n  compare: \"verify/compare\",\n} as const;\n\n/** `verify/render`'s params; internal to Mostra. */\nexport interface RenderRequest {\n  /** The capability link to open, as a viewer would (D138 item 1). */\n  readonly url: string;\n  /** The viewport to render at, DPR 1. */\n  readonly viewport: VerifyViewport;\n  /** The fixed time `Date` reports, in ms since the epoch: the same for every render of a run. */\n  readonly clockMs: number;\n  /** Where the screenshot and the ARIA snapshot are written, named after `name`. */\n  readonly outDir: string;\n  /** The render's name: its files are `<name>.png` and `<name>.aria.yml`. */\n  readonly name: string;\n  /** What to collect besides readiness and the page's own errors. */\n  readonly collect: {\n    /** A screenshot of the viewport. */\n    readonly screenshot: boolean;\n    /** The ARIA snapshot. */\n    readonly aria: boolean;\n    /** axe-core's violations. */\n    readonly axe: boolean;\n    /** The page's mounted fields, from the field probe. */\n    readonly fields: boolean;\n    /** Run the smoke test after rendering, within this budget. */\n    readonly smoke?: { readonly maxInteractions: number; readonly maxMs: number };\n  };\n  /** When this render must have ended, in ms since the epoch. */\n  readonly deadline: number;\n}\n\n/** `verify/render`'s answer; internal to Mostra. */\nexport interface RenderResult {\n  /** Whether the page reported `mostra/ready`. */\n  readonly ready: boolean;\n  /** What the runner found: page errors, console output, failed requests, axe, smoke, blank. */\n  readonly findings: readonly Diagnostic[];\n  /** The screenshot written, when asked for. */\n  readonly screenshot?: { readonly path: string; readonly width: number; readonly height: number };\n  /** The ARIA snapshot written, and its text, when asked for. */\n  readonly aria?: { readonly path: string; readonly text: string };\n  /** The mounted fields the probe reported, when asked for. */\n  readonly fields?: readonly ProbedField[];\n  /** What the smoke test did, when asked for. */\n  readonly smoke?: {\n    /** Controls used. */\n    readonly interactions: number;\n    /** Field writes they caused. */\n    readonly stateChanges: number;\n    /** Server functions the sandbox refused during the smoke test. */\n    readonly skipped: readonly string[];\n    /** Whether it stopped at its budget. */\n    readonly budget: boolean;\n  };\n  /** Whether the render ran past its deadline and stopped where it was. */\n  readonly timedOut: boolean;\n  /** When each step ended, in ms after the render started. */\n  readonly timingsMs: Readonly<Record<string, number>>;\n}\n\n/** `verify/compare`'s params; internal to Mostra. */\nexport interface CompareRequest {\n  /** The baseline's screenshot. */\n  readonly a: string;\n  /** The source's screenshot. */\n  readonly b: string;\n  /** Where to write the difference image. */\n  readonly diff: string;\n}\n\n/** `verify/compare`'s answer; internal to Mostra. */\nexport interface CompareResult {\n  /** The share of pixels that differ beyond pixelmatch's perceptual threshold. */\n  readonly ratio: number;\n  /** Whether the two images had different sizes (then `ratio` is 1). */\n  readonly sizeChanged: boolean;\n}\n\n/** A one-line count of an ARIA snapshot: headings, controls and landmarks. */\nexport function ariaSummary(text: string): string {\n  const counts = new Map<string, number>();\n  for (const match of text.matchAll(/^\\s*- ([a-z]+)\\b/gm)) {\n    const role = match[1] as string;\n    counts.set(role, (counts.get(role) ?? 0) + 1);\n  }\n  const named: [string, string][] = [\n    [\"heading\", \"headings\"],\n    [\"button\", \"buttons\"],\n    [\"link\", \"links\"],\n    [\"textbox\", \"text fields\"],\n    [\"checkbox\", \"checkboxes\"],\n    [\"combobox\", \"comboboxes\"],\n    [\"tab\", \"tabs\"],\n    [\"img\", \"images\"],\n    [\"table\", \"tables\"],\n  ];\n  const parts = named\n    .filter(([role]) => counts.has(role))\n    .map(([role, plural]) => `${counts.get(role)} ${counts.get(role) === 1 ? role : plural}`);\n  const landmarks = [\n    \"main\",\n    \"navigation\",\n    \"banner\",\n    \"contentinfo\",\n    \"form\",\n    \"region\",\n    \"dialog\",\n  ].filter((role) => counts.has(role));\n  if (landmarks.length > 0) parts.push(`landmarks: ${landmarks.join(\", \")}`);\n  return parts.length > 0 ? parts.join(\", \") : \"no headings, controls or landmarks\";\n}\n"],"mappings":"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"}

package/dist/view.d.ts

@@ -0,0 +1,103 @@
+import { SubmissionPolicy } from "./manifest.js";
+import * as z from "zod";
+//#region src/view.d.ts
+/** Where a submit came from (D40). */
+export type SubmitChannel = "shell" | "artifact";
+/** The Zod schema of the `SubmitChannel` type. */
+export declare const SubmitChannel: z.ZodType<SubmitChannel>;
+/**
+ * A trusted control the shell renders outside the artifact's frame (D06, PRODUCT vocabulary):
+ * Submit, Choose (review sets) and Approve. Open for later controls on the wire.
+ */
+export type TrustedControl = "submit" | "choose" | "approve" | (string & {});
+/** The Zod schema of the `TrustedControl` type. */
+export declare const TrustedControl: z.ZodType<TrustedControl>;
+/**
+ * Which submit channels a view accepts and which trusted controls its shell renders (D40, D108):
+ * the `trustedControls` port's answer, or the home's `HomeConfig.submitChannels`.
+ */
+export interface ControlsPolicy {
+  /** The channels submissions may come through; at least one. */
+  readonly submitChannels: readonly SubmitChannel[];
+  /** The trusted controls the shell may render; absent: every control the artifact asks for. */
+  readonly controls?: readonly TrustedControl[];
+}
+/** The Zod schema of the `ControlsPolicy` type. */
+export declare const ControlsPolicy: z.ZodType<ControlsPolicy>;
+/** A review set's ID: letters, digits, `_` and `-` (its choice is the field `review.<id>.choice`). */
+export declare const REVIEW_SET_ID_PATTERN: RegExp;
+/** Where a client runtime runs (D111): Mostra's gateway, a static export, an MCP App, or `verify`. */
+export type DeliveryTarget = "live" | "static" | "mcp-app" | "verify";
+/** A version by ID and number. */
+export interface VersionRef {
+  /** The version's ID. */
+  readonly id: string;
+  /** Its number, for people. */
+  readonly number: number;
+}
+/** The Zod schema of the `VersionRef` type. */
+export declare const VersionRef: z.ZodType<VersionRef>;
+/**
+ * What one view is (D104, D108): the shell learns it from its frame ticket and hands it to the
+ * frame in `ui/initialize`'s result, so the client runtime names the view in every request and
+ * knows what the host allows.
+ */
+export interface ViewContext {
+  /** The artifact. */
+  readonly artifactId: string;
+  /** The view this frame load is; every mutation and submit names it (D104). */
+  readonly viewId: string;
+  /** The version the view shows. */
+  readonly version: VersionRef;
+  /** The artifact's latest version when the view opened. */
+  readonly latest: VersionRef;
+  /** The submission policy in force (D102). */
+  readonly policy: SubmissionPolicy;
+  /** The submit channels this view accepts (D108). */
+  readonly submitChannels: readonly SubmitChannel[];
+  /** The trusted controls the shell renders for this view (D108). */
+  readonly controls: readonly TrustedControl[];
+  /** Always `live` in a frame Mostra's shell hosts. */
+  readonly target: DeliveryTarget;
+}
+/** The Zod schema of the `ViewContext` type. */
+export declare const ViewContext: z.ZodType<ViewContext>;
+/**
+ * A view as a page reads it from `ui/initialize` (Claude review finding 5): every published
+ * version embeds the page's reader, so it takes values a later Mostra may add (a channel, a
+ * policy, a target) without refusing the whole view; {@link readViewContext} reads them safely.
+ */
+export interface ViewContextWire {
+  /** The artifact. */
+  readonly artifactId: string;
+  /** The view this frame load is (D104). */
+  readonly viewId: string;
+  /** The version the view shows. */
+  readonly version: VersionRef;
+  /** The artifact's latest version when the view opened. */
+  readonly latest: VersionRef;
+  /** The submission policy in force (D102); a later policy or scope is read as `once` per viewer. */
+  readonly policy: {
+    /** `once`, `epochs`, `none`, or one a later release adds. */
+    readonly policy: string;
+    /** `per-artifact` or `per-viewer` under `once`, or one a later release adds. */
+    readonly scope?: string;
+  };
+  /** The submit channels the view accepts (D108); channels this release doesn't know are not allowed. */
+  readonly submitChannels: readonly string[];
+  /** The trusted controls the shell renders for the view (D108). */
+  readonly controls: readonly string[];
+  /** Where the page runs (D111); a target this release doesn't know is read as `live`. */
+  readonly target: string;
+}
+/** The Zod schema of the `ViewContextWire` type: open where later revisions may add values. */
+export declare const ViewContextWire: z.ZodType<ViewContextWire>;
+/**
+ * The view a page acts on, with every value this release doesn't know read the safe way: an
+ * unknown channel isn't allowed (the shell's stays), an unknown policy or `once` scope is read as
+ * `once` per viewer (the page may submit and the server decides; it closes on its own submission
+ * only), and an unknown target as `live`.
+ */
+export declare function readViewContext(wire: ViewContextWire): ViewContext;
+//#endregion
+//# sourceMappingURL=view.d.ts.map

package/dist/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","names":[],"sources":["../src/view.ts"],"mappings":";;;;YAYY;;qBAGC,eAAe,EAAE,QAAQ;;;;;YAW1B;;qBAGC,gBAAgB,EAAE,QAAQ;;;;;iBAYtB;;WAEN,yBAAyB;;WAEzB,oBAAoB;;;qBAIlB,gBAAgB,EAAE,QAAQ;;qBAY1B,uBAAuB;;YAGxB;;iBAGK;;WAEN;;WAEA;;;qBAIE,YAAY,EAAE,QAAQ;;;;;;iBAYlB;;WAEN;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER,QAAQ;;WAER,yBAAyB;;WAEzB,mBAAmB;;WAEnB,QAAQ;;;qBAIN,aAAa,EAAE,QAAQ;;;;;;iBAsBnB;;WAEN;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER;;aAEE;;aAEA;;;WAGF;;WAEA;;WAEA;;;qBAIE,iBAAiB,EAAE,QAAQ;;;;;;;wBAmBxB,gBAAgB,MAAM,kBAAkB"}

package/dist/view.js

@@ -0,0 +1,110 @@
+import { wireRegistry } from "./wire-registry.js";
+import { ArtifactId, VersionId, ViewId } from "./ids.js";
+import { SubmissionPolicy } from "./manifest.js";
+import * as z from "zod";
+//#region src/view.ts
+/**
+* What one view is (D104, D108): its artifact, version, policy, submit channels and trusted
+* controls. The browser protocol's frame ticket, the bridge's `ui/initialize` result and the
+* interaction core's channel policy share these shapes, so they live in a module of their own:
+* the bridge, which every version embeds, imports them without the interaction schemas.
+*/
+/** The Zod schema of the `SubmitChannel` type. */
+const SubmitChannel = z.enum(["shell", "artifact"]).register(wireRegistry, {
+	id: "SubmitChannel",
+	description: "Where a submit comes from: the shell's trusted Submit, or the artifact's code."
+});
+/** The Zod schema of the `TrustedControl` type. */
+const TrustedControl = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/).register(wireRegistry, {
+	id: "TrustedControl",
+	description: "A trusted control the shell renders: submit, choose, approve; open for more."
+});
+/** The Zod schema of the `ControlsPolicy` type. */
+const ControlsPolicy = z.object({
+	submitChannels: z.array(SubmitChannel).min(1).max(2).readonly(),
+	controls: z.array(TrustedControl).max(32).readonly().exactOptional()
+}).register(wireRegistry, {
+	id: "ControlsPolicy",
+	description: "Which submit channels a view accepts and which trusted controls its shell renders (D108)."
+});
+/** A review set's ID: letters, digits, `_` and `-` (its choice is the field `review.<id>.choice`). */
+const REVIEW_SET_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** The Zod schema of the `VersionRef` type. */
+const VersionRef = z.object({
+	id: VersionId.schema,
+	number: z.int().min(1)
+}).register(wireRegistry, {
+	id: "VersionRef",
+	description: "A version by ID and number."
+});
+/** The Zod schema of the `ViewContext` type. */
+const ViewContext = z.object({
+	artifactId: ArtifactId.schema,
+	viewId: ViewId.schema,
+	version: VersionRef,
+	latest: VersionRef,
+	policy: SubmissionPolicy,
+	submitChannels: z.array(SubmitChannel).min(1).max(2).readonly(),
+	controls: z.array(TrustedControl).max(32).readonly(),
+	target: z.enum([
+		"live",
+		"static",
+		"mcp-app",
+		"verify"
+	])
+}).register(wireRegistry, {
+	id: "ViewContext",
+	description: "What one view is: its artifact, view ID, version, latest version, policy, channels and controls."
+});
+/** The Zod schema of the `ViewContextWire` type: open where later revisions may add values. */
+const ViewContextWire = z.looseObject({
+	artifactId: ArtifactId.schema,
+	viewId: ViewId.schema,
+	version: VersionRef,
+	latest: VersionRef,
+	policy: z.looseObject({
+		policy: z.string(),
+		scope: z.string().exactOptional()
+	}),
+	submitChannels: z.array(z.string()).max(16).readonly(),
+	controls: z.array(z.string()).max(32).readonly(),
+	target: z.string()
+});
+const CONTROL_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/**
+* The view a page acts on, with every value this release doesn't know read the safe way: an
+* unknown channel isn't allowed (the shell's stays), an unknown policy or `once` scope is read as
+* `once` per viewer (the page may submit and the server decides; it closes on its own submission
+* only), and an unknown target as `live`.
+*/
+function readViewContext(wire) {
+	const channels = ["shell", "artifact"].filter((channel) => wire.submitChannels.includes(channel));
+	const { policy: name, scope } = wire.policy;
+	const policy = name === "none" ? { policy: "none" } : name === "epochs" ? { policy: "epochs" } : name === "once" && (scope === void 0 || scope === "per-artifact") ? {
+		policy: "once",
+		scope: "per-artifact"
+	} : {
+		policy: "once",
+		scope: "per-viewer"
+	};
+	const target = [
+		"live",
+		"static",
+		"mcp-app",
+		"verify"
+	].find((known) => known === wire.target);
+	return {
+		artifactId: wire.artifactId,
+		viewId: wire.viewId,
+		version: wire.version,
+		latest: wire.latest,
+		policy,
+		submitChannels: channels.length > 0 ? channels : ["shell"],
+		controls: wire.controls.filter((control) => CONTROL_NAME.test(control)),
+		target: target ?? "live"
+	};
+}
+//#endregion
+export { ControlsPolicy, REVIEW_SET_ID_PATTERN, SubmitChannel, TrustedControl, VersionRef, ViewContext, ViewContextWire, readViewContext };
+
+//# sourceMappingURL=view.js.map

package/dist/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","names":[],"sources":["../src/view.ts"],"sourcesContent":["/**\n * What one view is (D104, D108): its artifact, version, policy, submit channels and trusted\n * controls. The browser protocol's frame ticket, the bridge's `ui/initialize` result and the\n * interaction core's channel policy share these shapes, so they live in a module of their own:\n * the bridge, which every version embeds, imports them without the interaction schemas.\n */\nimport * as z from \"zod\";\nimport { ArtifactId, VersionId, ViewId } from \"./ids.ts\";\nimport { SubmissionPolicy } from \"./manifest.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** Where a submit came from (D40). */\nexport type SubmitChannel = \"shell\" | \"artifact\";\n\n/** The Zod schema of the `SubmitChannel` type. */\nexport const SubmitChannel: z.ZodType<SubmitChannel> = z\n  .enum([\"shell\", \"artifact\"])\n  .register(wireRegistry, {\n    id: \"SubmitChannel\",\n    description: \"Where a submit comes from: the shell's trusted Submit, or the artifact's code.\",\n  });\n\n/**\n * A trusted control the shell renders outside the artifact's frame (D06, PRODUCT vocabulary):\n * Submit, Choose (review sets) and Approve. Open for later controls on the wire.\n */\nexport type TrustedControl = \"submit\" | \"choose\" | \"approve\" | (string & {});\n\n/** The Zod schema of the `TrustedControl` type. */\nexport const TrustedControl: z.ZodType<TrustedControl> = z\n  .string()\n  .regex(/^[a-z][a-z0-9-]{0,31}$/)\n  .register(wireRegistry, {\n    id: \"TrustedControl\",\n    description: \"A trusted control the shell renders: submit, choose, approve; open for more.\",\n  });\n\n/**\n * Which submit channels a view accepts and which trusted controls its shell renders (D40, D108):\n * the `trustedControls` port's answer, or the home's `HomeConfig.submitChannels`.\n */\nexport interface ControlsPolicy {\n  /** The channels submissions may come through; at least one. */\n  readonly submitChannels: readonly SubmitChannel[];\n  /** The trusted controls the shell may render; absent: every control the artifact asks for. */\n  readonly controls?: readonly TrustedControl[];\n}\n\n/** The Zod schema of the `ControlsPolicy` type. */\nexport const ControlsPolicy: z.ZodType<ControlsPolicy> = z\n  .object({\n    submitChannels: z.array(SubmitChannel).min(1).max(2).readonly(),\n    controls: z.array(TrustedControl).max(32).readonly().exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"ControlsPolicy\",\n    description:\n      \"Which submit channels a view accepts and which trusted controls its shell renders (D108).\",\n  });\n\n/** A review set's ID: letters, digits, `_` and `-` (its choice is the field `review.<id>.choice`). */\nexport const REVIEW_SET_ID_PATTERN: RegExp = /^[A-Za-z0-9_-]{1,64}$/;\n\n/** Where a client runtime runs (D111): Mostra's gateway, a static export, an MCP App, or `verify`. */\nexport type DeliveryTarget = \"live\" | \"static\" | \"mcp-app\" | \"verify\";\n\n/** A version by ID and number. */\nexport interface VersionRef {\n  /** The version's ID. */\n  readonly id: string;\n  /** Its number, for people. */\n  readonly number: number;\n}\n\n/** The Zod schema of the `VersionRef` type. */\nexport const VersionRef: z.ZodType<VersionRef> = z\n  .object({ id: VersionId.schema, number: z.int().min(1) })\n  .register(wireRegistry, {\n    id: \"VersionRef\",\n    description: \"A version by ID and number.\",\n  });\n\n/**\n * What one view is (D104, D108): the shell learns it from its frame ticket and hands it to the\n * frame in `ui/initialize`'s result, so the client runtime names the view in every request and\n * knows what the host allows.\n */\nexport interface ViewContext {\n  /** The artifact. */\n  readonly artifactId: string;\n  /** The view this frame load is; every mutation and submit names it (D104). */\n  readonly viewId: string;\n  /** The version the view shows. */\n  readonly version: VersionRef;\n  /** The artifact's latest version when the view opened. */\n  readonly latest: VersionRef;\n  /** The submission policy in force (D102). */\n  readonly policy: SubmissionPolicy;\n  /** The submit channels this view accepts (D108). */\n  readonly submitChannels: readonly SubmitChannel[];\n  /** The trusted controls the shell renders for this view (D108). */\n  readonly controls: readonly TrustedControl[];\n  /** Always `live` in a frame Mostra's shell hosts. */\n  readonly target: DeliveryTarget;\n}\n\n/** The Zod schema of the `ViewContext` type. */\nexport const ViewContext: z.ZodType<ViewContext> = z\n  .object({\n    artifactId: ArtifactId.schema,\n    viewId: ViewId.schema,\n    version: VersionRef,\n    latest: VersionRef,\n    policy: SubmissionPolicy,\n    submitChannels: z.array(SubmitChannel).min(1).max(2).readonly(),\n    controls: z.array(TrustedControl).max(32).readonly(),\n    target: z.enum([\"live\", \"static\", \"mcp-app\", \"verify\"]),\n  })\n  .register(wireRegistry, {\n    id: \"ViewContext\",\n    description:\n      \"What one view is: its artifact, view ID, version, latest version, policy, channels and controls.\",\n  });\n\n/**\n * A view as a page reads it from `ui/initialize` (Claude review finding 5): every published\n * version embeds the page's reader, so it takes values a later Mostra may add (a channel, a\n * policy, a target) without refusing the whole view; {@link readViewContext} reads them safely.\n */\nexport interface ViewContextWire {\n  /** The artifact. */\n  readonly artifactId: string;\n  /** The view this frame load is (D104). */\n  readonly viewId: string;\n  /** The version the view shows. */\n  readonly version: VersionRef;\n  /** The artifact's latest version when the view opened. */\n  readonly latest: VersionRef;\n  /** The submission policy in force (D102); a later policy or scope is read as `once` per viewer. */\n  readonly policy: {\n    /** `once`, `epochs`, `none`, or one a later release adds. */\n    readonly policy: string;\n    /** `per-artifact` or `per-viewer` under `once`, or one a later release adds. */\n    readonly scope?: string;\n  };\n  /** The submit channels the view accepts (D108); channels this release doesn't know are not allowed. */\n  readonly submitChannels: readonly string[];\n  /** The trusted controls the shell renders for the view (D108). */\n  readonly controls: readonly string[];\n  /** Where the page runs (D111); a target this release doesn't know is read as `live`. */\n  readonly target: string;\n}\n\n/** The Zod schema of the `ViewContextWire` type: open where later revisions may add values. */\nexport const ViewContextWire: z.ZodType<ViewContextWire> = z.looseObject({\n  artifactId: ArtifactId.schema,\n  viewId: ViewId.schema,\n  version: VersionRef,\n  latest: VersionRef,\n  policy: z.looseObject({ policy: z.string(), scope: z.string().exactOptional() }),\n  submitChannels: z.array(z.string()).max(16).readonly(),\n  controls: z.array(z.string()).max(32).readonly(),\n  target: z.string(),\n}) as z.ZodType<ViewContextWire>;\n\nconst CONTROL_NAME = /^[a-z][a-z0-9-]{0,31}$/;\n\n/**\n * The view a page acts on, with every value this release doesn't know read the safe way: an\n * unknown channel isn't allowed (the shell's stays), an unknown policy or `once` scope is read as\n * `once` per viewer (the page may submit and the server decides; it closes on its own submission\n * only), and an unknown target as `live`.\n */\nexport function readViewContext(wire: ViewContextWire): ViewContext {\n  const channels = ([\"shell\", \"artifact\"] as const).filter((channel) =>\n    wire.submitChannels.includes(channel),\n  );\n  const { policy: name, scope } = wire.policy;\n  const policy: SubmissionPolicy =\n    name === \"none\"\n      ? { policy: \"none\" }\n      : name === \"epochs\"\n        ? { policy: \"epochs\" }\n        : name === \"once\" && (scope === undefined || scope === \"per-artifact\")\n          ? { policy: \"once\", scope: \"per-artifact\" }\n          : { policy: \"once\", scope: \"per-viewer\" };\n  const target = ([\"live\", \"static\", \"mcp-app\", \"verify\"] as const).find(\n    (known) => known === wire.target,\n  );\n  return {\n    artifactId: wire.artifactId,\n    viewId: wire.viewId,\n    version: wire.version,\n    latest: wire.latest,\n    policy,\n    submitChannels: channels.length > 0 ? channels : [\"shell\"],\n    controls: wire.controls.filter((control) => CONTROL_NAME.test(control)),\n    target: target ?? \"live\",\n  };\n}\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,gBAA0C,EACpD,KAAK,CAAC,SAAS,UAAU,CAAC,CAAC,CAC3B,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,iBAA4C,EACtD,OAAO,CAAC,CACR,MAAM,wBAAwB,CAAC,CAC/B,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAcH,MAAa,iBAA4C,EACtD,OAAO;CACN,gBAAgB,EAAE,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CAC9D,UAAU,EAAE,MAAM,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;AACrE,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC;;AAGH,MAAa,wBAAgC;;AAc7C,MAAa,aAAoC,EAC9C,OAAO;CAAE,IAAI,UAAU;CAAQ,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;AAAE,CAAC,CAAC,CACxD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AA2BH,MAAa,cAAsC,EAChD,OAAO;CACN,YAAY,WAAW;CACvB,QAAQ,OAAO;CACf,SAAS;CACT,QAAQ;CACR,QAAQ;CACR,gBAAgB,EAAE,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CAC9D,UAAU,EAAE,MAAM,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS;CACnD,QAAQ,EAAE,KAAK;EAAC;EAAQ;EAAU;EAAW;CAAQ,CAAC;AACxD,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC;;AAgCH,MAAa,kBAA8C,EAAE,YAAY;CACvE,YAAY,WAAW;CACvB,QAAQ,OAAO;CACf,SAAS;CACT,QAAQ;CACR,QAAQ,EAAE,YAAY;EAAE,QAAQ,EAAE,OAAO;EAAG,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc;CAAE,CAAC;CAC/E,gBAAgB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS;CACrD,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS;CAC/C,QAAQ,EAAE,OAAO;AACnB,CAAC;AAED,MAAM,eAAe;;;;;;;AAQrB,SAAgB,gBAAgB,MAAoC;CAClE,MAAM,WAAY,CAAC,SAAS,UAAU,CAAC,CAAW,QAAQ,YACxD,KAAK,eAAe,SAAS,OAAO,CACtC;CACA,MAAM,EAAE,QAAQ,MAAM,UAAU,KAAK;CACrC,MAAM,SACJ,SAAS,SACL,EAAE,QAAQ,OAAO,IACjB,SAAS,WACP,EAAE,QAAQ,SAAS,IACnB,SAAS,WAAW,UAAU,KAAA,KAAa,UAAU,kBACnD;EAAE,QAAQ;EAAQ,OAAO;CAAe,IACxC;EAAE,QAAQ;EAAQ,OAAO;CAAa;CAChD,MAAM,SAAU;EAAC;EAAQ;EAAU;EAAW;CAAQ,CAAC,CAAW,MAC/D,UAAU,UAAU,KAAK,MAC5B;CACA,OAAO;EACL,YAAY,KAAK;EACjB,QAAQ,KAAK;EACb,SAAS,KAAK;EACd,QAAQ,KAAK;EACb;EACA,gBAAgB,SAAS,SAAS,IAAI,WAAW,CAAC,OAAO;EACzD,UAAU,KAAK,SAAS,QAAQ,YAAY,aAAa,KAAK,OAAO,CAAC;EACtE,QAAQ,UAAU;CACpB;AACF"}

package/dist/wire-registry.js

@@ -0,0 +1,11 @@
+import * as z from "zod";
+//#region src/wire-registry.ts
+/**
+* The registry of named wire schemas. It is private to this package (not Zod's global registry), so
+* two copies of the package in one process never collide.
+*/
+const wireRegistry = z.registry();
+//#endregion
+export { wireRegistry };
+
+//# sourceMappingURL=wire-registry.js.map

package/dist/wire-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-registry.js","names":[],"sources":["../src/wire-registry.ts"],"sourcesContent":["import * as z from \"zod\";\n\n/** Metadata for a wire schema that has a stable name in the published JSON Schema. */\nexport interface WireSchemaMeta {\n  /** The definition name in the published JSON Schema (`$defs`). Stable once released. */\n  readonly id: string;\n  readonly description?: string;\n}\n\n/**\n * The registry of named wire schemas. It is private to this package (not Zod's global registry), so\n * two copies of the package in one process never collide.\n */\nexport const wireRegistry: z.core.$ZodRegistry<WireSchemaMeta> = z.registry<WireSchemaMeta>();\n"],"mappings":";;;;;;AAaA,MAAa,eAAoD,EAAE,SAAyB"}