@mostra/protocol 0.0.0-stage → 0.1.0

package/src/timers.d.ts

@@ -0,0 +1,8 @@
+// The timer functions the JSON-RPC peer uses for request timeouts, present in browsers, workers and
+// Node.js. Declared here so the package compiles without DOM or Node types.
+declare global {
+  function setTimeout(callback: () => void, ms?: number): unknown;
+  function clearTimeout(handle: unknown): void;
+}
+
+export {};

package/src/verify.ts

@@ -0,0 +1,458 @@
+/**
+ * `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.
+ */
+import * as z from "zod";
+import { Diagnostic } from "./diagnostics/diagnostic.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** When a verdict's screenshots are handed to the caller (AX-05): images cost tokens. */
+export type ScreenshotPolicy = "on-failure" | "always" | "never";
+
+/** The Zod schema of the `ScreenshotPolicy` type. */
+export const ScreenshotPolicy: z.ZodType<ScreenshotPolicy, string> = z
+  .enum(["on-failure", "always", "never"])
+  .register(wireRegistry, {
+    id: "ScreenshotPolicy",
+    description: "When screenshots are returned: on failure (the default), always or never.",
+  });
+
+/** One viewport verify renders at device pixel ratio 1. */
+export interface VerifyViewport {
+  /** Its name in the verdict: `desktop`, `mobile`, `tablet`, or `<width>x<height>`. */
+  readonly name: string;
+  /** Its width in CSS pixels, which at DPR 1 are the screenshot's pixels. */
+  readonly width: number;
+  /** Its height in CSS pixels. */
+  readonly height: number;
+}
+
+/** The viewports verify renders when the manifest names none (ROUND-3 §9): desktop and mobile. */
+export const DEFAULT_VIEWPORTS: readonly VerifyViewport[] = [
+  { name: "desktop", width: 1280, height: 800 },
+  { name: "mobile", width: 390, height: 844 },
+];
+
+const NAMED_VIEWPORTS: Readonly<Record<string, VerifyViewport>> = {
+  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.
+ */
+export function viewportsFor(names: readonly string[] | undefined): {
+  readonly viewports: readonly VerifyViewport[];
+  readonly unknown: readonly string[];
+} {
+  if (names === undefined || names.length === 0)
+    return { viewports: DEFAULT_VIEWPORTS, unknown: [] };
+  const viewports: VerifyViewport[] = [];
+  const unknown: string[] = [];
+  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]) } : undefined);
+    if (
+      !viewport ||
+      viewport.width < 200 ||
+      viewport.height < 200 ||
+      viewport.width > 4000 ||
+      viewport.height > 4000
+    ) {
+      unknown.push(raw);
+      continue;
+    }
+    if (!viewports.some((known) => known.name === viewport.name)) viewports.push(viewport);
+  }
+  return { viewports: viewports.length > 0 ? viewports : DEFAULT_VIEWPORTS, unknown };
+}
+
+/** What one image costs each model family to read (D138 item 9). */
+export interface TokenEstimate {
+  /** Claude's high-resolution tier (Claude 4.7 and later). */
+  readonly claude: number;
+  /** GPT at `detail: "high"` (gpt-5.5, gpt-5.6, gpt-6-astra). */
+  readonly gpt: number;
+  /** Gemini 3 and 4 at the default media resolution. */
+  readonly gemini: number;
+}
+
+/** Claude: tokens of an image already within its tier's limits. */
+const claudeTokens = (width: number, height: number): number =>
+  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: number,
+  height: number,
+  maxEdge: number,
+  maxTokens: number,
+): readonly [number, number] {
+  const fits = (w: number, h: number): boolean =>
+    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: number, height: number): number {
+  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((32 ** 2 * 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.
+ */
+export function estimateImageTokens(width: number, height: number): TokenEstimate {
+  const [cw, ch] = claudeSize(width, height, 2576, 4784);
+  return { claude: claudeTokens(cw, ch), gpt: gptTokens(width, height), gemini: 1120 };
+}
+
+/** One screenshot in a verdict (AX-05). */
+export interface VerdictScreenshot {
+  /** The viewport's name. */
+  readonly viewport: string;
+  /** The PNG, at device pixel ratio 1. */
+  readonly path: string;
+  /** The image's width in pixels. */
+  readonly width: number;
+  /** The image's height in pixels. */
+  readonly height: number;
+  /** What reading the image costs each model family ({@link estimateImageTokens}). */
+  readonly tokensEstimate: TokenEstimate;
+  /** Whether the caller is handed the image: on failure, or when asked (`screenshots`). */
+  readonly returned: boolean;
+}
+
+/** One ARIA snapshot in a verdict: the text-only picture of what a viewport shows. */
+export interface VerdictAria {
+  /** The viewport's name. */
+  readonly viewport: string;
+  /** The snapshot's YAML. */
+  readonly path: string;
+  /** A one-line count of what it holds: headings, controls, landmarks. */
+  readonly summary: string;
+}
+
+/** The verdict of one `verify` run (INTERFACES §13). `status` is `fail` exactly when an error exists. */
+export interface VerifyVerdict {
+  /** `fail` when any diagnostic is an error, else `pass`. */
+  readonly status: "pass" | "fail";
+  /** What was verified. */
+  readonly artifact: {
+    /** The artifact, when it has one already: a manifest `id` or a published path. */
+    readonly id?: string;
+    /** The source path as the request named it. */
+    readonly path: string;
+    /** The snapshot's digest (DATA_MODEL §2); empty when verify couldn't read the source. */
+    readonly sourceDigest: string;
+    /** The environment's digest, `lockDigest` included (DATA_MODEL §2); empty likewise. */
+    readonly envDigest: string;
+    /** The version this source would publish as, when the artifact is known (D89). */
+    readonly versionId?: string;
+  };
+  /** Every finding, errors first, identical ones folded with a `count`. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** One per viewport rendered. */
+  readonly screenshots: readonly VerdictScreenshot[];
+  /** One per viewport rendered. */
+  readonly aria: readonly VerdictAria[];
+  /** What the smoke test did. */
+  readonly smoke: {
+    /** Controls the smoke test used. */
+    readonly interactions: number;
+    /** Server functions that don't check `dryRun()` and were refused instead of run (D55). */
+    readonly skippedActions: readonly string[];
+    /** Field writes the interactions caused. */
+    readonly stateChanges: number;
+  };
+  /** What changed since the last passing version; empty when there is none. */
+  readonly regressions: {
+    /**
+     * The last passing version: the newest whose recorded verdict passed (D138 item 4). When it is
+     * this very source, nothing needed comparing.
+     */
+    readonly against?: string;
+    /** Controls and landmarks the baseline had and this source doesn't, in brief. */
+    readonly aria?: string;
+    /** The share of pixels that differ from the baseline, per viewport. */
+    readonly pixels?: readonly { readonly viewport: string; readonly ratio: number }[];
+    /** Contracts the baseline had that this source drops: fields, actions, live sources, pages. */
+    readonly contracts?: readonly string[];
+  };
+  /** How long each stage took, in milliseconds, and `total`. */
+  readonly timingsMs: Readonly<Record<string, number>>;
+}
+
+const tokenEstimate: z.ZodType<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. */
+export const VerifyVerdict: z.ZodType<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. */
+export const ARTIFACT_PROGRESS = "artifact/progress";
+
+/** `artifact/progress`: one stage of a long request started or ended. */
+export interface ArtifactProgressParams {
+  /** The `progressToken` the request carried. */
+  readonly progressToken: string;
+  /** The stage that started: `prepare`, `compile`, `boot`, `render`, `smoke`, `regression`. */
+  readonly stage: string;
+  /** How much of the request is done, from 0 to 1, when known. */
+  readonly fraction?: number;
+}
+
+/** The Zod schema of the `ArtifactProgressParams` type. */
+export const ArtifactProgressParams: z.ZodType<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.
+ */
+export 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.
+ */
+export const VERIFY_PROBE = "__mostraVerify";
+
+/** One mounted field, as the probe reports it; internal to Mostra. */
+export interface ProbedField {
+  /** The field ID. */
+  readonly id: string;
+  /** Its scope, as first mounted. */
+  readonly scope: "viewer" | "artifact";
+  /** The hook that named it: `useField`, `useChoice`, `useForm` or `storage`. */
+  readonly hook: string;
+  /** `typeof` its initial value, `array` or `null`. */
+  readonly initialType: string;
+  /** How many components have it mounted now. */
+  readonly mounts: number;
+  /** Other hook kinds, scopes or initial types it was mounted with, if any. */
+  readonly conflicts: readonly string[];
+}
+
+/** The verify runner's methods (ARCHITECTURE §1): the supervisor asks, the runner answers; internal to Mostra. */
+export 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",
+} as const;
+
+/** `verify/render`'s params; internal to Mostra. */
+export interface RenderRequest {
+  /** The capability link to open, as a viewer would (D138 item 1). */
+  readonly url: string;
+  /** The viewport to render at, DPR 1. */
+  readonly viewport: VerifyViewport;
+  /** The fixed time `Date` reports, in ms since the epoch: the same for every render of a run. */
+  readonly clockMs: number;
+  /** Where the screenshot and the ARIA snapshot are written, named after `name`. */
+  readonly outDir: string;
+  /** The render's name: its files are `<name>.png` and `<name>.aria.yml`. */
+  readonly name: string;
+  /** What to collect besides readiness and the page's own errors. */
+  readonly collect: {
+    /** A screenshot of the viewport. */
+    readonly screenshot: boolean;
+    /** The ARIA snapshot. */
+    readonly aria: boolean;
+    /** axe-core's violations. */
+    readonly axe: boolean;
+    /** The page's mounted fields, from the field probe. */
+    readonly fields: boolean;
+    /** Run the smoke test after rendering, within this budget. */
+    readonly smoke?: { readonly maxInteractions: number; readonly maxMs: number };
+  };
+  /** When this render must have ended, in ms since the epoch. */
+  readonly deadline: number;
+}
+
+/** `verify/render`'s answer; internal to Mostra. */
+export interface RenderResult {
+  /** Whether the page reported `mostra/ready`. */
+  readonly ready: boolean;
+  /** What the runner found: page errors, console output, failed requests, axe, smoke, blank. */
+  readonly findings: readonly Diagnostic[];
+  /** The screenshot written, when asked for. */
+  readonly screenshot?: { readonly path: string; readonly width: number; readonly height: number };
+  /** The ARIA snapshot written, and its text, when asked for. */
+  readonly aria?: { readonly path: string; readonly text: string };
+  /** The mounted fields the probe reported, when asked for. */
+  readonly fields?: readonly ProbedField[];
+  /** What the smoke test did, when asked for. */
+  readonly smoke?: {
+    /** Controls used. */
+    readonly interactions: number;
+    /** Field writes they caused. */
+    readonly stateChanges: number;
+    /** Server functions the sandbox refused during the smoke test. */
+    readonly skipped: readonly string[];
+    /** Whether it stopped at its budget. */
+    readonly budget: boolean;
+  };
+  /** Whether the render ran past its deadline and stopped where it was. */
+  readonly timedOut: boolean;
+  /** When each step ended, in ms after the render started. */
+  readonly timingsMs: Readonly<Record<string, number>>;
+}
+
+/** `verify/compare`'s params; internal to Mostra. */
+export interface CompareRequest {
+  /** The baseline's screenshot. */
+  readonly a: string;
+  /** The source's screenshot. */
+  readonly b: string;
+  /** Where to write the difference image. */
+  readonly diff: string;
+}
+
+/** `verify/compare`'s answer; internal to Mostra. */
+export interface CompareResult {
+  /** The share of pixels that differ beyond pixelmatch's perceptual threshold. */
+  readonly ratio: number;
+  /** Whether the two images had different sizes (then `ratio` is 1). */
+  readonly sizeChanged: boolean;
+}
+
+/** A one-line count of an ARIA snapshot: headings, controls and landmarks. */
+export function ariaSummary(text: string): string {
+  const counts = new Map<string, number>();
+  for (const match of text.matchAll(/^\s*- ([a-z]+)\b/gm)) {
+    const role = match[1] as string;
+    counts.set(role, (counts.get(role) ?? 0) + 1);
+  }
+  const named: [string, string][] = [
+    ["heading", "headings"],
+    ["button", "buttons"],
+    ["link", "links"],
+    ["textbox", "text fields"],
+    ["checkbox", "checkboxes"],
+    ["combobox", "comboboxes"],
+    ["tab", "tabs"],
+    ["img", "images"],
+    ["table", "tables"],
+  ];
+  const parts = named
+    .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";
+}

package/src/view.ts

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+import * as z from "zod";
+import { ArtifactId, VersionId, ViewId } from "./ids.ts";
+import { SubmissionPolicy } from "./manifest.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** Where a submit came from (D40). */
+export type SubmitChannel = "shell" | "artifact";
+
+/** The Zod schema of the `SubmitChannel` type. */
+export const SubmitChannel: z.ZodType<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.",
+  });
+
+/**
+ * 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 const TrustedControl: z.ZodType<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.",
+  });
+
+/**
+ * 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 const ControlsPolicy: z.ZodType<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`). */
+export const REVIEW_SET_ID_PATTERN: RegExp = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** 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 const VersionRef: z.ZodType<VersionRef> = z
+  .object({ id: VersionId.schema, number: z.int().min(1) })
+  .register(wireRegistry, {
+    id: "VersionRef",
+    description: "A version by ID and number.",
+  });
+
+/**
+ * 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 const ViewContext: z.ZodType<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.",
+  });
+
+/**
+ * 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 const ViewContextWire: z.ZodType<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(),
+}) as z.ZodType<ViewContextWire>;
+
+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`.
+ */
+export function readViewContext(wire: ViewContextWire): ViewContext {
+  const channels = (["shell", "artifact"] as const).filter((channel) =>
+    wire.submitChannels.includes(channel),
+  );
+  const { policy: name, scope } = wire.policy;
+  const policy: SubmissionPolicy =
+    name === "none"
+      ? { policy: "none" }
+      : name === "epochs"
+        ? { policy: "epochs" }
+        : name === "once" && (scope === undefined || scope === "per-artifact")
+          ? { policy: "once", scope: "per-artifact" }
+          : { policy: "once", scope: "per-viewer" };
+  const target = (["live", "static", "mcp-app", "verify"] as const).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",
+  };
+}

package/src/web-crypto.d.ts

@@ -0,0 +1,9 @@
+// The one host API this package uses: Web Crypto's random source, present in browsers and in
+// Node.js 19 and later. Declared here so the package compiles without DOM or Node types.
+declare global {
+  var crypto: {
+    getRandomValues<T extends Uint8Array>(array: T): T;
+  };
+}
+
+export {};