@mostra/protocol 0.0.0-placeholder → 0.1.0

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","names":[],"sources":["../src/actions.ts"],"sourcesContent":["/**\n * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the\n * browser protocol, the host protocol and the worker channel share. Server-function arguments and\n * results travel as the serializer's batches (`Batches`).\n *\n * ```ts\n * const run: RunState = await post(\"runs\", { viewId, fnId: \"actions.ts#sendReply\", args, clientKey });\n * if (run.status === \"succeeded\") show(await deserializeAll(run.batches));\n * ```\n */\nimport * as z from \"zod\";\nimport { ViewId } from \"./ids.ts\";\nimport type { Frame, WireError } from \"./serializer.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** A value written by the serializer: its batches, in order (`serializeAll`). */\nexport type Batches = readonly (readonly Frame[])[];\n\n/**\n * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames\n * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.\n */\nexport const Batches: z.ZodType<Batches> = z\n  .array(z.array(z.record(z.string(), z.unknown())).readonly())\n  .readonly()\n  .register(wireRegistry, {\n    id: \"Batches\",\n    description: \"A serialized server-function value: its batches of frames, in order.\",\n  }) as unknown as z.ZodType<Batches>;\n\n/** An error as runs, calls and live sources report it. */\nexport interface ActionError extends WireError {\n  /** The stack of the thrown error, kept in the run log and never sent to a page. */\n  readonly stack?: string;\n}\n\n/** The Zod schema of the `ActionError` type. */\nexport const ActionError: z.ZodType<ActionError> = z\n  .object({\n    message: z.string(),\n    code: z.string().exactOptional(),\n    stack: z.string().exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"ActionError\",\n    description: \"An error from server code: its message and diagnostic code.\",\n  });\n\n/** The largest serialized arguments a call or run takes, in characters of JSON. */\nexport const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;\n\n/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */\nexport const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;\n\n/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */\nexport const RUN_LOG_MAX: number = 1024 * 1024;\n\n/** The line a capped log ends with. */\nexport const RUN_LOG_TRUNCATED = \"[log truncated at 1 MB]\";\n\n/** The longest run key, in characters. */\nexport const RUN_KEY_MAX = 256;\n\n/**\n * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.\n * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's\n * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are\n * final.\n */\nexport type RunStatus = \"queued\" | \"running\" | \"waiting\" | \"succeeded\" | \"failed\" | \"cancelled\";\n\n/** Every run status. */\nexport const RUN_STATUSES: readonly RunStatus[] = [\n  \"queued\",\n  \"running\",\n  \"waiting\",\n  \"succeeded\",\n  \"failed\",\n  \"cancelled\",\n];\n\n/** Whether a run in `status` has ended. */\nexport function isFinalRunStatus(status: RunStatus): boolean {\n  return status === \"succeeded\" || status === \"failed\" || status === \"cancelled\";\n}\n\n/**\n * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance\n * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside\n * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a\n * viewer), `unknown-function`. Later releases add reasons.\n */\nexport type RunReason = string;\n\n/** A run's progress, as the action last reported it. */\nexport interface RunProgress {\n  /** From 0 to 1. */\n  readonly fraction?: number;\n  /** One short line for people. */\n  readonly message?: string;\n}\n\n/** The Zod schema of the `RunProgress` type. */\nexport const RunProgress: z.ZodType<RunProgress> = z\n  .object({\n    fraction: z.number().min(0).max(1).exactOptional(),\n    message: z.string().max(1000).exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"RunProgress\",\n    description: \"A run's progress: fraction and message.\",\n  });\n\n/**\n * One action run as a page reads it (D54): its state, progress, log and the result written so far.\n * A result that is an async iterable grows item by item while the run is `running`.\n */\nexport interface RunState {\n  /** The run's `run_` ID. */\n  readonly runId: string;\n  /** The server function it runs: `<module path>#<export>`. */\n  readonly fnId: string;\n  /** The idempotency key it was started with, if any. */\n  readonly key?: string;\n  /** The run's state. */\n  readonly status: RunStatus;\n  /** Why it ended, for `failed` and `cancelled`. */\n  readonly reason?: RunReason;\n  /** Its latest progress. */\n  readonly progress?: RunProgress;\n  /** The log lines, capped at 1 MB with a marker line. */\n  readonly log: readonly string[];\n  /** The result's batches so far. */\n  readonly batches: Batches;\n  /** For `failed`: what went wrong, without the stack. */\n  readonly error?: WireError;\n  /** When it was recorded. */\n  readonly startedAt: string;\n  /** When it ended. */\n  readonly finishedAt?: string;\n  /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */\n  readonly joined?: boolean;\n  /**\n   * The index of the first line in `log`, when the request said which lines the page holds\n   * (`RunAttachRequest.held`); absent: 0, the whole log.\n   */\n  readonly logFrom?: number;\n  /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */\n  readonly batchFrom?: number;\n}\n\n/** The Zod schema of the `RunState` type. */\nexport const RunState: z.ZodType<RunState> = z\n  .object({\n    runId: z.string(),\n    fnId: z.string(),\n    key: z.string().exactOptional(),\n    status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),\n    reason: z.string().exactOptional(),\n    progress: RunProgress.exactOptional(),\n    log: z.array(z.string()).readonly(),\n    batches: Batches,\n    error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),\n    startedAt: z.string(),\n    finishedAt: z.string().exactOptional(),\n    joined: z.boolean().exactOptional(),\n    logFrom: z.number().int().nonnegative().exactOptional(),\n    batchFrom: z.number().int().nonnegative().exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"RunState\",\n    description: \"An action run: status, progress, log and the result written so far.\",\n  });\n\n/**\n * What changed in a run since a page last heard: a lossy notification on the event stream. Lines\n * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again\n * (`runs/attach`).\n */\nexport interface RunDelta {\n  /** The run's `run_` ID. */\n  readonly runId: string;\n  /** The run's state. */\n  readonly status: RunStatus;\n  /** Why it ended so, for `failed` and `cancelled`. */\n  readonly reason?: RunReason;\n  /** Its latest progress. */\n  readonly progress?: RunProgress;\n  /** The index of the first line in `log`. */\n  readonly logFrom: number;\n  /** Log lines, starting at `logFrom`. */\n  readonly log: readonly string[];\n  /** The index of the first batch in `batches`. */\n  readonly batchFrom: number;\n  /** Result batches, starting at `batchFrom`. */\n  readonly batches: Batches;\n  /** What went wrong. */\n  readonly error?: WireError;\n  /** When it ended. */\n  readonly finishedAt?: string;\n}\n\n/** A live source's value as a page reads it (D56). */\nexport interface LiveState {\n  /** The idempotency key it was started with, if any. */\n  readonly key: string;\n  /** The value's revision, a decimal string that only grows; absent before any value. */\n  readonly revision?: string;\n  /** When the value was produced. */\n  readonly at?: string;\n  /** The latest value, serialized. */\n  readonly value?: Batches;\n  /**\n   * Append mode (`useLive(key, { mode: \"append\" })`): the values kept in the source's ring, oldest\n   * first, at most the window the page asked for.\n   */\n  readonly ring?: readonly {\n    readonly revision: string;\n    readonly at: string;\n    readonly value: Batches;\n  }[];\n  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */\n  readonly error?: WireError;\n}\n\n/** One live update on the event stream: never stored as an event (D63, LL-04). */\nexport interface LiveUpdate {\n  /** The live source's key. */\n  readonly key: string;\n  /** The value's revision. */\n  readonly revision?: string;\n  /** When the value was produced. */\n  readonly at?: string;\n  /** The value, serialized. */\n  readonly value?: Batches;\n  /** What went wrong. */\n  readonly error?: WireError;\n}\n\n/**\n * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an\n * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and\n * never stored as an event.\n */\nexport type EphemeralMessage =\n  | { readonly kind: \"run\"; readonly run: RunDelta }\n  | { readonly kind: \"live\"; readonly live: LiveUpdate };\n\n/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */\nexport interface CallRequest {\n  /** The view the page was opened as (D104). */\n  readonly viewId: string;\n  /** The arguments, serialized as one array value. */\n  readonly args: Batches;\n}\n\n/** The Zod schema of the `CallRequest` type. */\nexport const CallRequest: z.ZodType<CallRequest> = z\n  .object({ viewId: ViewId.schema, args: Batches })\n  .register(wireRegistry, {\n    id: \"CallRequest\",\n    description: \"A plain server-function call: the view and the serialized arguments.\",\n  });\n\n/**\n * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.\n */\nexport type CallLine =\n  | { readonly batch: readonly Frame[] }\n  | { readonly end: { readonly status: \"succeeded\" } }\n  | { readonly end: { readonly status: \"failed\"; readonly error: WireError } };\n\n/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */\nexport interface RunRequest {\n  /** The view the page was opened as (D104). */\n  readonly viewId: string;\n  /** `<module path>#<export>`. */\n  readonly fnId: string;\n  /** The arguments, serialized as one array value. */\n  readonly args: Batches;\n  /** The author's idempotency key: one run per artifact, function and key, ever. */\n  readonly key?: string;\n  /** A fresh ID per invocation, so a retried request joins the run it already started. */\n  readonly clientKey: string;\n}\n\n/** The Zod schema of the `RunRequest` type. */\nexport const RunRequest: z.ZodType<RunRequest> = z\n  .object({\n    viewId: ViewId.schema,\n    fnId: z.string().min(3).max(1024),\n    args: Batches,\n    key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),\n    clientKey: z.string().min(8).max(64),\n  })\n  .register(wireRegistry, {\n    id: \"RunRequest\",\n    description: \"Start or join an action run: the function, its arguments and keys.\",\n  });\n\n/**\n * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute\n * (re-attach after a reload, AC-02). By ID, or by function and key.\n */\nexport interface RunAttachRequest {\n  /** The view the page was opened as (D104). */\n  readonly viewId: string;\n  /** Runs by ID. */\n  readonly runIds?: readonly string[];\n  /** Runs by function and key. */\n  readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];\n  /**\n   * What the page already holds of runs it names by ID: so many log lines and batches. Each such\n   * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest\n   * doesn't read the whole run again (Opus review 14).\n   */\n  readonly held?: readonly {\n    readonly runId: string;\n    readonly log: number;\n    readonly batches: number;\n  }[];\n}\n\n/** The Zod schema of the `RunAttachRequest` type. */\nexport const RunAttachRequest: z.ZodType<RunAttachRequest> = z\n  .object({\n    viewId: ViewId.schema,\n    runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),\n    keyed: z\n      .array(\n        z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),\n      )\n      .max(100)\n      .readonly()\n      .exactOptional(),\n    held: z\n      .array(\n        z.object({\n          runId: z.string().max(64),\n          log: z.number().int().nonnegative(),\n          batches: z.number().int().nonnegative(),\n        }),\n      )\n      .max(100)\n      .readonly()\n      .exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"RunAttachRequest\",\n    description: \"Runs a page reads and follows: by ID, or by function and key.\",\n  });\n\n/** `POST …/runs/{id}/cancel`. */\nexport interface RunCancelRequest {\n  /** The view the page was opened as (D104). */\n  readonly viewId: string;\n}\n\n/** The Zod schema of the `RunCancelRequest` type. */\nexport const RunCancelRequest: z.ZodType<RunCancelRequest> = z\n  .object({ viewId: ViewId.schema })\n  .register(wireRegistry, { id: \"RunCancelRequest\", description: \"Cancel a run, from a view.\" });\n\n/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */\nexport const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;\n\n/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */\nexport const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;\n\n/** The ring size of a pushed source in append mode that no `defineLive` sized. */\nexport const LIVE_RING_DEFAULT = 1024;\n\n/** The largest ring a source may keep. */\nexport const LIVE_RING_MAX = 100_000;\n\n/**\n * `POST …/live`: read live sources and keep their producers running for this view for the next\n * minute (D56, LL-04); a page asks again while it shows them.\n */\nexport interface LiveRequest {\n  /** The view the page was opened as (D104). */\n  readonly viewId: string;\n  /**\n   * The sources, each with its append window; `refresh` asks the source's producer to load again\n   * now (`useLive`'s `refresh()`).\n   */\n  readonly keys: readonly {\n    readonly key: string;\n    readonly window?: number;\n    readonly refresh?: boolean;\n  }[];\n}\n\n/** The Zod schema of the `LiveRequest` type. */\nexport const LiveRequest: z.ZodType<LiveRequest> = z\n  .object({\n    viewId: ViewId.schema,\n    keys: z\n      .array(\n        z.object({\n          key: z.string().regex(LIVE_KEY_PATTERN),\n          window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),\n          refresh: z.boolean().exactOptional(),\n        }),\n      )\n      .max(256)\n      .readonly(),\n  })\n  .register(wireRegistry, {\n    id: \"LiveRequest\",\n    description: \"Live sources a page reads and keeps running: keys and append windows.\",\n  });\n\n/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */\nexport const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;\n\n/** The largest secret value, in UTF-8 bytes. */\nexport const SECRET_VALUE_MAX: number = 64 * 1024;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,MAAa,UAA8B,EACxC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAC5D,SAAS,CAAC,CACV,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,cAAsC,EAChD,OAAO;CACN,SAAS,EAAE,OAAO;CAClB,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc;AAClC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,kBAA0B;;AAGvC,MAAa,oBAA4B;;AAGzC,MAAa,cAAsB;;AAGnC,MAAa,oBAAoB;;AAGjC,MAAa,cAAc;;AAW3B,MAAa,eAAqC;CAChD;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,SAAgB,iBAAiB,QAA4B;CAC3D,OAAO,WAAW,eAAe,WAAW,YAAY,WAAW;AACrE;;AAmBA,MAAa,cAAsC,EAChD,OAAO;CACN,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;CACjD,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,GAAI,CAAC,CAAC,cAAc;AAC9C,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyCH,MAAa,WAAgC,EAC1C,OAAO;CACN,OAAO,EAAE,OAAO;CAChB,MAAM,EAAE,OAAO;CACf,KAAK,EAAE,OAAO,CAAC,CAAC,cAAc;CAC9B,QAAQ,EAAE,KAAK,YAA2C;CAC1D,QAAQ,EAAE,OAAO,CAAC,CAAC,cAAc;CACjC,UAAU,YAAY,cAAc;CACpC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;CAClC,SAAS;CACT,OAAO,EAAE,OAAO;EAAE,SAAS,EAAE,OAAO;EAAG,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAAE,CAAC,CAAC,CAAC,cAAc;CACzF,WAAW,EAAE,OAAO;CACpB,YAAY,EAAE,OAAO,CAAC,CAAC,cAAc;CACrC,QAAQ,EAAE,QAAQ,CAAC,CAAC,cAAc;CAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc;AAC1D,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAqFH,MAAa,cAAsC,EAChD,OAAO;CAAE,QAAQ,OAAO;CAAQ,MAAM;AAAQ,CAAC,CAAC,CAChD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAyBH,MAAa,aAAoC,EAC9C,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;CAChC,MAAM;CACN,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe,CAAC,CAAC,cAAc;CACtD,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE;AACrC,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AA0BH,MAAa,mBAAgD,EAC1D,OAAO;CACN,QAAQ,OAAO;CACf,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;CACtE,OAAO,EACJ,MACC,EAAE,OAAO;EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;EAAG,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,GAAe;CAAE,CAAC,CACzF,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;CACjB,MAAM,EACH,MACC,EAAE,OAAO;EACP,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE;EACxB,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;EAClC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY;CACxC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,cAAc;AACnB,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AASH,MAAa,mBAAgD,EAC1D,OAAO,EAAE,QAAQ,OAAO,OAAO,CAAC,CAAC,CACjC,SAAS,cAAc;CAAE,IAAI;CAAoB,aAAa;AAA6B,CAAC;;AAG/F,MAAa,mBAA2B;;AAGxC,MAAa,iBAAyB;;AAGtC,MAAa,oBAAoB;;AAGjC,MAAa,gBAAgB;;AAqB7B,MAAa,cAAsC,EAChD,OAAO;CACN,QAAQ,OAAO;CACf,MAAM,EACH,MACC,EAAE,OAAO;EACP,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;EACtC,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,cAAc;EACxD,SAAS,EAAE,QAAQ,CAAC,CAAC,cAAc;CACrC,CAAC,CACH,CAAC,CACA,IAAI,GAAG,CAAC,CACR,SAAS;AACd,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,sBAA8B;;AAG3C,MAAa,mBAA2B"}

package/dist/artifact.d.ts

@@ -0,0 +1,113 @@
+import { ArtifactLink, ArtifactManifest, SubmissionPolicy } from "./manifest.js";
+import * as z from "zod";
+//#region src/artifact.d.ts
+/**
+ * Where to build an artifact from: a source path (a `.tsx`, `.jsx` or `.mdx` file, or a directory
+ * with an `index` entry), or an artifact ID, meaning the path it was last published from.
+ */
+export type SourceRef = {
+  readonly path: string;
+} | {
+  readonly artifactId: string;
+};
+/** Names an artifact: by its ID, or by a source path bound to it. */
+export type ArtifactRef = {
+  readonly artifactId: string;
+} | {
+  readonly path: string;
+};
+/** The Zod schema of the `SourceRef` type. */
+export declare const SourceRef: z.ZodType<SourceRef>;
+/** The Zod schema of the `ArtifactRef` type. */
+export declare const ArtifactRef: z.ZodType<ArtifactRef>;
+/** One published version. */
+export interface VersionSummary {
+  /** The content-addressed version ID (D89). */
+  readonly id: string;
+  /** The per-artifact version number, for people: 1, 2, 3 … */
+  readonly number: number;
+  /** When it was published (RFC 3339, UTC). */
+  readonly publishedAt: string;
+  /** SHA-256 of the source tree's canonical listing, lowercase hex (DATA_MODEL §2). */
+  readonly sourceDigest: string;
+  /** SHA-256 of the build environment's canonical JSON, lowercase hex (DATA_MODEL §2). */
+  readonly envDigest: string;
+  /** SHA-256 of the build output's canonical listing: recorded, never identity (VR-01). */
+  readonly outputDigest: string;
+  /** Diagnostic codes a forced publish recorded (D41); absent when none. */
+  readonly forcedDiagnostics?: readonly string[];
+  /**
+   * When `mostra gc` removed the version's files (D140): its ID and number stay, but it can't be
+   * opened until its exact source is published again. Absent for a version whose files exist.
+   */
+  readonly collected?: string;
+}
+/** One artifact, as `artifact/list` returns it. Metadata comes from the latest version's manifest. */
+export interface ArtifactSummary {
+  /** The artifact ID. */
+  readonly id: string;
+  /** The title people see. */
+  readonly title: string;
+  /** What the artifact is for. */
+  readonly description?: string;
+  /** What kind of artifact it is. */
+  readonly family?: string;
+  /** Related artifacts. */
+  readonly links: readonly ArtifactLink[];
+  /** The render mode of the latest version. */
+  readonly mode: "spa";
+  /** The submission policy requested at publish or in the manifest; the host decides (D39). */
+  readonly policy?: SubmissionPolicy;
+  /** The source path the artifact was last published from. */
+  readonly source?: string;
+  /** When the artifact was first published (RFC 3339, UTC). */
+  readonly createdAt: string;
+  /** The version viewers are offered. */
+  readonly latestVersion?: VersionSummary;
+}
+/** One artifact in full, as `artifact/get` returns it. */
+export interface ArtifactDetail extends ArtifactSummary {
+  /** The latest version's manifest. */
+  readonly manifest: ArtifactManifest;
+  /** Every version, newest number first. */
+  readonly versions: readonly VersionSummary[];
+}
+/**
+ * The receipt of `artifact/publish` (INTERFACES §6, H-07). Everything it names is durable before the
+ * response is sent.
+ */
+export interface PublishReceipt {
+  /** The artifact the version belongs to. */
+  readonly artifactId: string;
+  /** The content-addressed version ID (D89). */
+  readonly versionId: string;
+  /** The version number. */
+  readonly version: number;
+  /**
+   * The capability URL: the artifact's default link (D97), the same for every publish until it is
+   * rotated or revoked. Instances with the gateway (WP-05 on) always set it; optional on
+   * the wire so instances without it can publish (D90).
+   */
+  readonly url?: string;
+  /**
+   * The ID of the token behind `url`, the artifact's default link (D97), for `view/rotate` and
+   * `view/revoke`. Present whenever `url` is.
+   */
+  readonly tokenId?: string;
+  /** The event cursor of the version's `version.published` event; `wait` and events read after it. */
+  readonly cursor: string;
+  /** `true` when this artifact already had this exact source and environment as a version. */
+  readonly reused: boolean;
+  /** The error codes a forced publish recorded (D41). */
+  readonly forcedDiagnostics?: readonly string[];
+}
+/** The Zod schema of the `VersionSummary` type. */
+export declare const VersionSummary: z.ZodType<VersionSummary>;
+/** The Zod schema of the `ArtifactSummary` type. */
+export declare const ArtifactSummary: z.ZodType<ArtifactSummary>;
+/** The Zod schema of the `ArtifactDetail` type. */
+export declare const ArtifactDetail: z.ZodType<ArtifactDetail>;
+/** The Zod schema of the `PublishReceipt` type. */
+export declare const PublishReceipt: z.ZodType<PublishReceipt>;
+//#endregion
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","names":[],"sources":["../src/artifact.ts"],"mappings":";;;;;;;YAgBY;WAAuB;;WAA4B;;;YAGnD;WAAyB;;WAAkC;;;qBAG1D,WAAW,EAAE,QAAQ;;qBASrB,aAAa,EAAE,QAAQ;;iBAQnB;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;WAKA;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,gBAAgB;;WAEhB;;WAEA,SAAS;;WAET;;WAEA;;WAEA,gBAAgB;;;iBAIV,uBAAuB;;WAE7B,UAAU;;WAEV,mBAAmB;;;;;;iBAOb;;WAEN;;WAEA;;WAEA;;;;;;WAMA;;;;;WAKA;;WAEA;;WAEA;;WAEA;;;qBAIE,gBAAgB,EAAE,QAAQ;;qBA2B1B,iBAAiB,EAAE,QAAQ;;qBAQ3B,gBAAgB,EAAE,QAAQ;;qBAY1B,gBAAgB,EAAE,QAAQ"}

package/dist/artifact.js

@@ -0,0 +1,79 @@
+import { wireRegistry } from "./wire-registry.js";
+import { ArtifactId, Cursor, TokenId, VersionId } from "./ids.js";
+import { ArtifactLink, ArtifactManifest, SubmissionPolicy } from "./manifest.js";
+import * as z from "zod";
+//#region src/artifact.ts
+/**
+* Artifacts and versions as clients see them (INTERFACES §6): how a client names an artifact or its
+* source, and the summaries `artifact/list`, `artifact/get` and `artifact/publish` return.
+*/
+/** An absolute file system path: the client resolves relative paths against its own directory. */
+const AbsolutePath = z.string().regex(/^\//);
+/** The Zod schema of the `SourceRef` type. */
+const SourceRef = z.union([z.object({ path: AbsolutePath }), z.object({ artifactId: ArtifactId.schema })]).register(wireRegistry, {
+	id: "SourceRef",
+	description: "Where to build an artifact from: an absolute source path, or an artifact ID (its last published source path)."
+});
+/** The Zod schema of the `ArtifactRef` type. */
+const ArtifactRef = z.union([z.object({ artifactId: ArtifactId.schema }), z.object({ path: AbsolutePath })]).register(wireRegistry, {
+	id: "ArtifactRef",
+	description: "Names an artifact by its ID or by an absolute source path bound to it."
+});
+/** The Zod schema of the `VersionSummary` type. */
+const VersionSummary = z.object({
+	id: VersionId.schema,
+	number: z.int().min(1),
+	publishedAt: z.iso.datetime(),
+	sourceDigest: z.string().regex(/^[0-9a-f]{64}$/),
+	envDigest: z.string().regex(/^[0-9a-f]{64}$/),
+	outputDigest: z.string().regex(/^[0-9a-f]{64}$/),
+	forcedDiagnostics: z.array(z.string()).readonly().exactOptional(),
+	collected: z.iso.datetime().exactOptional()
+}).register(wireRegistry, {
+	id: "VersionSummary",
+	description: "One published version."
+});
+const summaryShape = {
+	id: ArtifactId.schema,
+	title: z.string(),
+	description: z.string().exactOptional(),
+	family: z.string().exactOptional(),
+	links: z.array(ArtifactLink).readonly(),
+	mode: z.literal("spa"),
+	policy: SubmissionPolicy.exactOptional(),
+	source: z.string().exactOptional(),
+	createdAt: z.iso.datetime(),
+	latestVersion: VersionSummary.exactOptional()
+};
+/** The Zod schema of the `ArtifactSummary` type. */
+const ArtifactSummary = z.object(summaryShape).register(wireRegistry, {
+	id: "ArtifactSummary",
+	description: "One artifact: metadata from its latest version, its source and latest version."
+});
+/** The Zod schema of the `ArtifactDetail` type. */
+const ArtifactDetail = z.object({
+	...summaryShape,
+	manifest: ArtifactManifest,
+	versions: z.array(VersionSummary).readonly()
+}).register(wireRegistry, {
+	id: "ArtifactDetail",
+	description: "One artifact in full: its summary, the latest manifest and every version."
+});
+/** The Zod schema of the `PublishReceipt` type. */
+const PublishReceipt = z.object({
+	artifactId: ArtifactId.schema,
+	versionId: VersionId.schema,
+	version: z.int().min(1),
+	url: z.string().exactOptional(),
+	tokenId: TokenId.schema.exactOptional(),
+	cursor: Cursor.schema,
+	reused: z.boolean(),
+	forcedDiagnostics: z.array(z.string()).readonly().exactOptional()
+}).register(wireRegistry, {
+	id: "PublishReceipt",
+	description: "The receipt of artifact/publish: artifact, version, number, capability URL when served, event cursor, reuse."
+});
+//#endregion
+export { ArtifactDetail, ArtifactRef, ArtifactSummary, PublishReceipt, SourceRef, VersionSummary };
+
+//# sourceMappingURL=artifact.js.map

package/dist/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","names":[],"sources":["../src/artifact.ts"],"sourcesContent":["/**\n * Artifacts and versions as clients see them (INTERFACES §6): how a client names an artifact or its\n * source, and the summaries `artifact/list`, `artifact/get` and `artifact/publish` return.\n */\nimport * as z from \"zod\";\nimport { ArtifactId, Cursor, TokenId, VersionId } from \"./ids.ts\";\nimport { ArtifactLink, ArtifactManifest, SubmissionPolicy } from \"./manifest.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** An absolute file system path: the client resolves relative paths against its own directory. */\nconst AbsolutePath = z.string().regex(/^\\//);\n\n/**\n * Where to build an artifact from: a source path (a `.tsx`, `.jsx` or `.mdx` file, or a directory\n * with an `index` entry), or an artifact ID, meaning the path it was last published from.\n */\nexport type SourceRef = { readonly path: string } | { readonly artifactId: string };\n\n/** Names an artifact: by its ID, or by a source path bound to it. */\nexport type ArtifactRef = { readonly artifactId: string } | { readonly path: string };\n\n/** The Zod schema of the `SourceRef` type. */\nexport const SourceRef: z.ZodType<SourceRef> = z\n  .union([z.object({ path: AbsolutePath }), z.object({ artifactId: ArtifactId.schema })])\n  .register(wireRegistry, {\n    id: \"SourceRef\",\n    description:\n      \"Where to build an artifact from: an absolute source path, or an artifact ID (its last published source path).\",\n  });\n\n/** The Zod schema of the `ArtifactRef` type. */\nexport const ArtifactRef: z.ZodType<ArtifactRef> = z\n  .union([z.object({ artifactId: ArtifactId.schema }), z.object({ path: AbsolutePath })])\n  .register(wireRegistry, {\n    id: \"ArtifactRef\",\n    description: \"Names an artifact by its ID or by an absolute source path bound to it.\",\n  });\n\n/** One published version. */\nexport interface VersionSummary {\n  /** The content-addressed version ID (D89). */\n  readonly id: string;\n  /** The per-artifact version number, for people: 1, 2, 3 … */\n  readonly number: number;\n  /** When it was published (RFC 3339, UTC). */\n  readonly publishedAt: string;\n  /** SHA-256 of the source tree's canonical listing, lowercase hex (DATA_MODEL §2). */\n  readonly sourceDigest: string;\n  /** SHA-256 of the build environment's canonical JSON, lowercase hex (DATA_MODEL §2). */\n  readonly envDigest: string;\n  /** SHA-256 of the build output's canonical listing: recorded, never identity (VR-01). */\n  readonly outputDigest: string;\n  /** Diagnostic codes a forced publish recorded (D41); absent when none. */\n  readonly forcedDiagnostics?: readonly string[];\n  /**\n   * When `mostra gc` removed the version's files (D140): its ID and number stay, but it can't be\n   * opened until its exact source is published again. Absent for a version whose files exist.\n   */\n  readonly collected?: string;\n}\n\n/** One artifact, as `artifact/list` returns it. Metadata comes from the latest version's manifest. */\nexport interface ArtifactSummary {\n  /** The artifact ID. */\n  readonly id: string;\n  /** The title people see. */\n  readonly title: string;\n  /** What the artifact is for. */\n  readonly description?: string;\n  /** What kind of artifact it is. */\n  readonly family?: string;\n  /** Related artifacts. */\n  readonly links: readonly ArtifactLink[];\n  /** The render mode of the latest version. */\n  readonly mode: \"spa\";\n  /** The submission policy requested at publish or in the manifest; the host decides (D39). */\n  readonly policy?: SubmissionPolicy;\n  /** The source path the artifact was last published from. */\n  readonly source?: string;\n  /** When the artifact was first published (RFC 3339, UTC). */\n  readonly createdAt: string;\n  /** The version viewers are offered. */\n  readonly latestVersion?: VersionSummary;\n}\n\n/** One artifact in full, as `artifact/get` returns it. */\nexport interface ArtifactDetail extends ArtifactSummary {\n  /** The latest version's manifest. */\n  readonly manifest: ArtifactManifest;\n  /** Every version, newest number first. */\n  readonly versions: readonly VersionSummary[];\n}\n\n/**\n * The receipt of `artifact/publish` (INTERFACES §6, H-07). Everything it names is durable before the\n * response is sent.\n */\nexport interface PublishReceipt {\n  /** The artifact the version belongs to. */\n  readonly artifactId: string;\n  /** The content-addressed version ID (D89). */\n  readonly versionId: string;\n  /** The version number. */\n  readonly version: number;\n  /**\n   * The capability URL: the artifact's default link (D97), the same for every publish until it is\n   * rotated or revoked. Instances with the gateway (WP-05 on) always set it; optional on\n   * the wire so instances without it can publish (D90).\n   */\n  readonly url?: string;\n  /**\n   * The ID of the token behind `url`, the artifact's default link (D97), for `view/rotate` and\n   * `view/revoke`. Present whenever `url` is.\n   */\n  readonly tokenId?: string;\n  /** The event cursor of the version's `version.published` event; `wait` and events read after it. */\n  readonly cursor: string;\n  /** `true` when this artifact already had this exact source and environment as a version. */\n  readonly reused: boolean;\n  /** The error codes a forced publish recorded (D41). */\n  readonly forcedDiagnostics?: readonly string[];\n}\n\n/** The Zod schema of the `VersionSummary` type. */\nexport const VersionSummary: z.ZodType<VersionSummary> = z\n  .object({\n    id: VersionId.schema,\n    number: z.int().min(1),\n    publishedAt: z.iso.datetime(),\n    sourceDigest: z.string().regex(/^[0-9a-f]{64}$/),\n    envDigest: z.string().regex(/^[0-9a-f]{64}$/),\n    outputDigest: z.string().regex(/^[0-9a-f]{64}$/),\n    forcedDiagnostics: z.array(z.string()).readonly().exactOptional(),\n    collected: z.iso.datetime().exactOptional(),\n  })\n  .register(wireRegistry, { id: \"VersionSummary\", description: \"One published version.\" });\n\nconst summaryShape = {\n  id: ArtifactId.schema,\n  title: z.string(),\n  description: z.string().exactOptional(),\n  family: z.string().exactOptional(),\n  links: z.array(ArtifactLink).readonly(),\n  mode: z.literal(\"spa\"),\n  policy: SubmissionPolicy.exactOptional(),\n  source: z.string().exactOptional(),\n  createdAt: z.iso.datetime(),\n  latestVersion: VersionSummary.exactOptional(),\n};\n\n/** The Zod schema of the `ArtifactSummary` type. */\nexport const ArtifactSummary: z.ZodType<ArtifactSummary> = z\n  .object(summaryShape)\n  .register(wireRegistry, {\n    id: \"ArtifactSummary\",\n    description: \"One artifact: metadata from its latest version, its source and latest version.\",\n  });\n\n/** The Zod schema of the `ArtifactDetail` type. */\nexport const ArtifactDetail: z.ZodType<ArtifactDetail> = z\n  .object({\n    ...summaryShape,\n    manifest: ArtifactManifest,\n    versions: z.array(VersionSummary).readonly(),\n  })\n  .register(wireRegistry, {\n    id: \"ArtifactDetail\",\n    description: \"One artifact in full: its summary, the latest manifest and every version.\",\n  });\n\n/** The Zod schema of the `PublishReceipt` type. */\nexport const PublishReceipt: z.ZodType<PublishReceipt> = z\n  .object({\n    artifactId: ArtifactId.schema,\n    versionId: VersionId.schema,\n    version: z.int().min(1),\n    url: z.string().exactOptional(),\n    tokenId: TokenId.schema.exactOptional(),\n    cursor: Cursor.schema,\n    reused: z.boolean(),\n    forcedDiagnostics: z.array(z.string()).readonly().exactOptional(),\n  })\n  .register(wireRegistry, {\n    id: \"PublishReceipt\",\n    description:\n      \"The receipt of artifact/publish: artifact, version, number, capability URL when served, event cursor, reuse.\",\n  });\n"],"mappings":";;;;;;;;;;AAUA,MAAM,eAAe,EAAE,OAAO,CAAC,CAAC,MAAM,KAAK;;AAY3C,MAAa,YAAkC,EAC5C,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,WAAW,OAAO,CAAC,CAAC,CAAC,CAAC,CACtF,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC;;AAGH,MAAa,cAAsC,EAChD,MAAM,CAAC,EAAE,OAAO,EAAE,YAAY,WAAW,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC,CACtF,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAwFH,MAAa,iBAA4C,EACtD,OAAO;CACN,IAAI,UAAU;CACd,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;CACrB,aAAa,EAAE,IAAI,SAAS;CAC5B,cAAc,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;CAC/C,WAAW,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;CAC5C,cAAc,EAAE,OAAO,CAAC,CAAC,MAAM,gBAAgB;CAC/C,mBAAmB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;CAChE,WAAW,EAAE,IAAI,SAAS,CAAC,CAAC,cAAc;AAC5C,CAAC,CAAC,CACD,SAAS,cAAc;CAAE,IAAI;CAAkB,aAAa;AAAyB,CAAC;AAEzF,MAAM,eAAe;CACnB,IAAI,WAAW;CACf,OAAO,EAAE,OAAO;CAChB,aAAa,EAAE,OAAO,CAAC,CAAC,cAAc;CACtC,QAAQ,EAAE,OAAO,CAAC,CAAC,cAAc;CACjC,OAAO,EAAE,MAAM,YAAY,CAAC,CAAC,SAAS;CACtC,MAAM,EAAE,QAAQ,KAAK;CACrB,QAAQ,iBAAiB,cAAc;CACvC,QAAQ,EAAE,OAAO,CAAC,CAAC,cAAc;CACjC,WAAW,EAAE,IAAI,SAAS;CAC1B,eAAe,eAAe,cAAc;AAC9C;;AAGA,MAAa,kBAA8C,EACxD,OAAO,YAAY,CAAC,CACpB,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,iBAA4C,EACtD,OAAO;CACN,GAAG;CACH,UAAU;CACV,UAAU,EAAE,MAAM,cAAc,CAAC,CAAC,SAAS;AAC7C,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;AAGH,MAAa,iBAA4C,EACtD,OAAO;CACN,YAAY,WAAW;CACvB,WAAW,UAAU;CACrB,SAAS,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;CACtB,KAAK,EAAE,OAAO,CAAC,CAAC,cAAc;CAC9B,SAAS,QAAQ,OAAO,cAAc;CACtC,QAAQ,OAAO;CACf,QAAQ,EAAE,QAAQ;CAClB,mBAAmB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc;AAClE,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aACE;AACJ,CAAC"}

package/dist/bridge.d.ts

@@ -0,0 +1,295 @@
+import { ViewContextWire } from "./view.js";
+import * as z from "zod";
+//#region src/bridge.d.ts
+/** Which end of the bridge: the trusted shell, or the artifact's frame. */
+export type BridgeSide = "shell" | "artifact";
+/** One message of the bridge's set. */
+export interface BridgeMessage<P, R> {
+  /** The JSON-RPC method name; MCP Apps' name where the concept exists. */
+  readonly method: string;
+  /** The side that sends it. */
+  readonly from: BridgeSide;
+  /** A request is answered; a notification isn't. */
+  readonly kind: "request" | "notification";
+  /** The schema of its params. */
+  readonly params: z.ZodType<P>;
+  /** The schema of a request's result (`z.undefined()` for notifications). */
+  readonly result: z.ZodType<R>;
+}
+/** A bridge message of any params and result type. */
+export type AnyBridgeMessage = BridgeMessage<unknown, unknown>;
+/** The version of MCP Apps whose message shapes the bridge follows (VERIFIED_FACTS, MCP). */
+export declare const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
+/** An application's name and version (MCP's `Implementation`). */
+export interface BridgeImplementation {
+  /** A stable machine name, such as `mostra-shell`. */
+  readonly name: string;
+  /** Its release. */
+  readonly version: string;
+  /** A name for people. */
+  readonly title?: string;
+}
+/** The params of `ui/initialize`: the artifact introduces itself (MCP Apps). */
+export interface UiInitializeParams {
+  /** The artifact's client runtime. */
+  readonly appInfo: BridgeImplementation;
+  /** What the artifact offers (MCP Apps' `McpUiAppCapabilities`). */
+  readonly appCapabilities: Readonly<Record<string, unknown>>;
+  /** The MCP Apps revision the artifact speaks, {@link MCP_APPS_PROTOCOL_VERSION}. */
+  readonly protocolVersion: string;
+  /**
+   * What the page is (WP-07): the version whose build the frame loaded. An artifact origin serves
+   * the version its frame session last entered (D98 item 5), so a frame reloaded after another
+   * tab switched versions may hold another version than its view; the shell re-enters its own.
+   */
+  readonly mostra?: {
+    readonly versionId: string;
+  };
+}
+/** What the shell tells the artifact about where it is shown (MCP Apps' `HostContext`). */
+export interface BridgeHostContext {
+  /** The viewer's color scheme. */
+  readonly theme?: "light" | "dark";
+  /** How the artifact is shown: the shell shows it `fullscreen`. */
+  readonly displayMode?: "inline" | "fullscreen" | "pip";
+  /** The display modes the shell offers. */
+  readonly availableDisplayModes?: readonly string[];
+  /** The viewer's language (BCP 47). */
+  readonly locale?: string;
+  /** The viewer's time zone (IANA). */
+  readonly timeZone?: string;
+  /** The kind of device. */
+  readonly platform?: "web" | "desktop" | "mobile";
+  /** Further MCP Apps context, passed through. */
+  readonly [key: string]: unknown;
+}
+/** The result of `ui/initialize`: the shell introduces itself (MCP Apps). */
+export interface UiInitializeResult {
+  /** The MCP Apps revision both ends speak. */
+  readonly protocolVersion: string;
+  /** The shell. */
+  readonly hostInfo: BridgeImplementation;
+  /** What the shell offers (MCP Apps' `McpUiHostCapabilities`). */
+  readonly hostCapabilities: Readonly<Record<string, unknown>>;
+  /** Where and how the artifact is shown. */
+  readonly hostContext: BridgeHostContext;
+  /** Mostra's shell: the view this frame load is, and what the host allows in it (WP-07). */
+  readonly mostra?: ViewContextWire;
+}
+/** `ui/initialize`: the artifact's first request, answered with the shell's context. */
+export declare const uiInitialize: BridgeMessage<UiInitializeParams, UiInitializeResult>;
+/** `ui/notifications/initialized`: the artifact finished initializing; the shell may now send. */
+export declare const uiInitialized: BridgeMessage<Readonly<Record<string, unknown>>, undefined>;
+/** `ui/notifications/size-changed`: the artifact's rendered size (MCP Apps). */
+export declare const uiSizeChanged: BridgeMessage<{
+  readonly width?: number;
+  readonly height?: number;
+}, undefined>;
+/**
+ * The URL schemes `ui/open-link` opens: the web, mail and phone numbers. Anything else, such as
+ * `javascript:` or `data:`, would run or show content in the shell's own context.
+ */
+export declare const OPEN_LINK_SCHEMES: readonly string[];
+/**
+ * `ui/open-link`: the artifact asks the shell to open a URL in a new tab (MCP Apps). The frame
+ * can't navigate the viewer's tab itself (D98 item 7), so this is how an artifact sends the
+ * viewer anywhere. `isError` is `true` when the shell couldn't open it.
+ */
+export declare const uiOpenLink: BridgeMessage<{
+  readonly url: string;
+}, {
+  readonly isError?: boolean;
+  readonly [key: string]: unknown;
+}>;
+/** `mostra/ready`: the artifact's page has rendered; `verify` waits for it (ROUND-3 §8). */
+export declare const mostraReady: BridgeMessage<Readonly<Record<string, unknown>>, undefined>;
+/** The page's save state, as the shell's rail shows it (D47). */
+export type SaveState = "saved" | "saving" | "offline" | "conflict";
+/** Why a field blocks a submit (INTERFACES §2.3). */
+export interface SubmitBlocker {
+  /** The field's ID. */
+  readonly fieldId: string;
+  /** Its label, when it has one. */
+  readonly label?: string;
+  /** `required` without a value, `invalid` by its `validate`, or a `conflict` not yet resolved. */
+  readonly reason: "required" | "invalid" | "conflict";
+}
+/**
+ * The longest label, validation message or other text a field carries over the bridge; a page
+ * shortens longer ones before it sends them (Claude review finding 11).
+ */
+export declare const BRIDGE_TEXT_MAX = 1024;
+/** The most fields or blockers one bridge message lists; a page sends those that matter first. */
+export declare const BRIDGE_FIELDS_MAX = 1e4;
+/**
+ * A field the page has mounted, with what the shell needs to list blockers by label (D52, D106).
+ * The page reports it; the shell checks `required` against the draft it reads itself.
+ */
+export interface FieldRegistration {
+  /** The field's ID. */
+  readonly id: string;
+  /** The label people see. */
+  readonly label?: string;
+  /** Whether a submit needs a value. */
+  readonly required?: boolean;
+  /** The viewer's draft or the artifact's shared state. */
+  readonly scope: "viewer" | "artifact";
+  /** Whether its value is kept out of events and logs. */
+  readonly sensitive?: boolean;
+  /** Its `validate` message for the current value, if any. */
+  readonly error?: string;
+  /** Whether it has a conflict the viewer hasn't resolved. */
+  readonly conflict?: boolean;
+}
+/** The params of `mostra/fields`. */
+export interface FieldsParams {
+  /** Every mounted field, once per ID. */
+  readonly fields: readonly FieldRegistration[];
+  /** The page's save state. */
+  readonly save: SaveState;
+  /** Whether edits are waiting to be saved (typed, offline, or in the journal). */
+  readonly unsaved: boolean;
+}
+/**
+ * `mostra/fields`: the page's mounted fields and save state, sent whenever they change, so the
+ * shell lists blockers by label and its rail shows "Saving" and "Saved" (INTERFACES §5).
+ */
+export declare const mostraFields: BridgeMessage<FieldsParams, undefined>;
+/**
+ * `mostra/page`: the page the viewer is on, inside a `pages/` artifact (D57), so comments record
+ * it (WP-20). `path` is the route's path with its search and hash, whatever the history mode.
+ */
+export declare const mostraPage: BridgeMessage<{
+  readonly path: string;
+  readonly title?: string;
+}, undefined>;
+/** A trusted control the artifact asks the shell for (INTERFACES §5): the artifact asks, the shell decides. */
+export type ControlRequest = {
+  /** Relabel the shell's trusted Submit, with an optional confirmation text. */
+  readonly control: "submit";
+  readonly label?: string;
+  readonly confirm?: string;
+} | {
+  /** Render a trusted Choose for a review set's candidates (D113). */
+  readonly control: "choose";
+  readonly reviewSetId: string;
+  readonly candidates: readonly {
+    readonly id: string;
+    readonly label?: string;
+  }[];
+  /** The candidate the page shows now, which Choose names. */
+  readonly current?: string;
+} | {
+  /** Withdraw an earlier request: the Submit label, or a review set's Choose. */
+  readonly control: "release";
+  readonly submit?: true;
+  readonly reviewSetId?: string;
+};
+/** The longest Submit label the shell renders: one short line. */
+export declare const CONTROL_LABEL_MAX = 48;
+/**
+ * `mostra/controls.request`: the artifact asks the shell for a trusted control (D06, SH-02). The
+ * shell renders it in its own origin, where the artifact can neither click nor reach it, and
+ * answers whether it is shown: a control the host's policy leaves out is not (D108).
+ */
+export declare const mostraControlsRequest: BridgeMessage<ControlRequest, {
+  readonly shown: boolean;
+}>;
+/** What the page answers `mostra/flush`. */
+export interface FlushResult {
+  /** The viewer's draft revision once every save landed. */
+  readonly revision: string;
+  /** Whether edits still wait (offline, or a save failed). */
+  readonly unsaved: boolean;
+  /** What blocks a submit now: invalid values and open conflicts, and required fields the page sees empty. */
+  readonly blockers: readonly SubmitBlocker[];
+}
+/**
+ * `mostra/flush`: the shell asks the page to save everything now, before its trusted Submit or a
+ * switch to a newer version (IN-02, D110). For a submit, the page first writes the defaults the
+ * viewer saw. The shell checks the answer against the draft it reads itself.
+ */
+export declare const mostraFlush: BridgeMessage<{
+  readonly reason: "submit" | "switch";
+}, FlushResult>;
+/** The params of `mostra/version.available`. */
+export interface VersionAvailableParams {
+  /** The newer version's ID. */
+  readonly versionId: string;
+  /** Its number. */
+  readonly version: number;
+  /** How many of the viewer's answers it doesn't carry over (D42). */
+  readonly orphans: number;
+}
+/**
+ * `mostra/version.available`: a newer version was published while the page is open (VR-04). The
+ * shell always shows its own trusted banner; the page may show a notice too.
+ */
+export declare const mostraVersionAvailable: BridgeMessage<VersionAvailableParams, undefined>;
+/** `mostra/field.focus`: the viewer picked a blocker in the shell; the page focuses that field. */
+export declare const mostraFieldFocus: BridgeMessage<{
+  readonly id: string;
+}, undefined>;
+/**
+ * Every message of the bridge in this release. WP-20 adds review messages; a message never
+ * changes meaning once released (D32).
+ */
+export declare const BRIDGE_MESSAGES: readonly AnyBridgeMessage[];
+/** The window events arrive on (`window` itself). */
+export interface BridgeReceiver {
+  /** Starts delivering `message` events to `listener`. */
+  addEventListener(type: "message", listener: (event: BridgeEvent) => void): void;
+  /** Stops delivering them. */
+  removeEventListener(type: "message", listener: (event: BridgeEvent) => void): void;
+}
+/** The parts of a `MessageEvent` the bridge reads. */
+export interface BridgeEvent {
+  /** The message. */
+  readonly data: unknown;
+  /** The sender's origin, as the browser reports it. */
+  readonly origin: string;
+  /** The sending window. */
+  readonly source: unknown;
+}
+/** The window messages go to: the frame's `contentWindow`, or the shell (`window.parent`). */
+export interface BridgePeer {
+  /** Posts `message` to the window, delivered only if its origin is `targetOrigin`. */
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+/** Why the bridge dropped a message, for logs and tests. */
+export type BridgeRejection = "wrong-source" | "wrong-origin" | "not-json-rpc" | "unknown-method" | "wrong-direction" | "invalid-params";
+/** Options for {@link connectBridge}. */
+export interface BridgeOptions {
+  /** This end. It accepts only messages the other side sends. */
+  readonly side: BridgeSide;
+  /** Where messages arrive. */
+  readonly receiver: BridgeReceiver;
+  /** The window this end talks to, looked up on every message (a frame's window changes on reload). */
+  readonly peer: () => BridgePeer | null | undefined;
+  /** The peer's exact origin. Messages from any other origin are dropped. */
+  readonly peerOrigin: string;
+  /** Answers a request from the peer; throw an {@link RpcError} to answer with an error. */
+  readonly onRequest?: (message: AnyBridgeMessage, params: unknown) => unknown;
+  /** Receives a notification from the peer. */
+  readonly onNotification?: (message: AnyBridgeMessage, params: unknown) => void;
+  /** Hears about every dropped message. */
+  readonly onRejected?: (reason: BridgeRejection, event: BridgeEvent) => void;
+}
+/** One end of a connected bridge. */
+export interface Bridge {
+  /** Sends a request this side may send and resolves with its validated result. */
+  call<P, R>(message: BridgeMessage<P, R>, params: P, options?: {
+    timeoutMs?: number;
+  }): Promise<R>;
+  /** Sends a notification this side may send. */
+  notify<P>(message: BridgeMessage<P, undefined>, params: P): void;
+  /** Stops listening; waiting calls reject. */
+  close(): void;
+}
+/**
+ * Connects one end of the bridge. Every incoming message must come from `peer()` at exactly
+ * `peerOrigin`, be a JSON-RPC message, name a message the other side sends, and carry valid params.
+ */
+export declare function connectBridge(options: BridgeOptions): Bridge;
+//#endregion
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","names":[],"sources":["../src/bridge.ts"],"mappings":";;;;YA2BY;;iBAGK,cAAc,GAAG;;WAEvB;;WAEA,MAAM;;WAEN;;WAEA,QAAQ,EAAE,QAAQ;;WAElB,QAAQ,EAAE,QAAQ;;;YAIjB,mBAAmB;;qBAGlB;;iBAGI;;WAEN;;WAEA;;WAEA;;;iBAUM;;WAEN,SAAS;;WAET,iBAAiB,SAAS;;WAE1B;;;;;;WAMA;aAAoB;;;;iBAId;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;iBAMM;;WAEN;;WAEA,UAAU;;WAEV,kBAAkB,SAAS;;WAE3B,aAAa;;WAEb,SAAS;;;qBAIP,cAAc,cAAc,oBAAoB;;qBA2BhD,eAAe,cAAc,SAAS;;qBAStC,eAAe;WACf;WAAyB;;;;;;qBAiBzB;;;;;;qBAOA,YAAY;WACZ;;WACA;;;;qBAUA,aAAa,cAAc,SAAS;;YAWrC;;iBAGK;;WAEN;;WAEA;;WAEA;;;;;;qBAOE;;qBAGA;;;;;iBAYI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;iBAIM;;WAEN,iBAAiB;;WAEjB,MAAM;;WAEN;;;;;;qBAOE,cAAc,cAAc;;;;;qBA6B5B,YAAY;WACZ;WAAuB;;;YAcxB;;WAGG;WACA;WACA;;;WAIA;WACA;WACA;aAAgC;aAAqB;;;WAErD;;;WAIA;WACA;WACA;;;qBAIF;;;;;;qBAOA,uBAAuB,cAAc;WAA2B;;;iBAmC5D;;WAEN;;WAEA;;WAEA,mBAAmB;;;;;;;qBAQjB,aAAa;WAAyB;GAA+B;;iBAajE;;WAEN;;WAEA;;WAEA;;;;;;qBAOE,wBAAwB,cAAc;;qBAatC,kBAAkB;WAAyB;;;;;;qBAY3C,0BAA0B;;iBAetB;;EAEf,iBAAiB,iBAAiB,WAAW,OAAO;;EAEpD,oBAAoB,iBAAiB,WAAW,OAAO;;;iBAIxC;;WAEN;;WAEA;;WAEA;;;iBAIM;;EAEf,YAAY,kBAAkB;;;YAIpB;;iBASK;;WAEN,MAAM;;WAEN,UAAU;;WAEV,YAAY;;WAEZ;;WAEA,aAAa,SAAS,kBAAkB;;WAExC,kBAAkB,SAAS,kBAAkB;;WAE7C,cAAc,QAAQ,iBAAiB,OAAO;;;iBAIxC;;EAEf,KAAK,GAAG,GAAG,SAAS,cAAc,GAAG,IAAI,QAAQ,GAAG;IAAY;MAAuB,QAAQ;;EAE/F,OAAO,GAAG,SAAS,cAAc,eAAe,QAAQ;;EAExD;;;;;;wBAec,cAAc,SAAS,gBAAgB"}