@mostra/protocol 0.0.0-placeholder → 0.1.0

package/dist/bridge.js

@@ -0,0 +1,343 @@
+import { JSON_RPC_ERROR_CODES, RpcError, hostDiagnostic } from "./rpc/error.js";
+import { classifyMessage } from "./rpc/messages.js";
+import { RpcPeer } from "./rpc/peer.js";
+import { REVIEW_SET_ID_PATTERN, ViewContextWire } from "./view.js";
+import * as z from "zod";
+//#region src/bridge.ts
+/**
+* The shell ↔ artifact bridge (INTERFACES §5, ROUND-3 §8, SH-04): JSON-RPC 2.0 over
+* `postMessage`, shaped like MCP Apps so exporting an artifact as an MCP App only swaps the
+* transport. Both ends accept a message only when it comes from the one window they talk to, at
+* its exact origin, and only when it is a message of the bridge's set with valid params; anything
+* else is dropped (or, for a request from the right window, answered with an error). It has no
+* I/O of its own: the caller hands it the window objects.
+*
+* ```ts
+* // In the shell:
+* const bridge = connectBridge({
+*   side: "shell",
+*   receiver: window,
+*   peer: () => frame.contentWindow,
+*   peerOrigin: "http://127.0.0.1:23457",
+*   onRequest: (message, params) => (message === uiInitialize ? initializeResult : undefined),
+* });
+* ```
+*/
+/** The version of MCP Apps whose message shapes the bridge follows (VERIFIED_FACTS, MCP). */
+const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
+const Implementation = z.looseObject({
+	name: z.string(),
+	version: z.string(),
+	title: z.string().exactOptional()
+});
+/** `ui/initialize`: the artifact's first request, answered with the shell's context. */
+const uiInitialize = {
+	method: "ui/initialize",
+	from: "artifact",
+	kind: "request",
+	params: z.looseObject({
+		appInfo: Implementation,
+		appCapabilities: z.record(z.string(), z.unknown()),
+		protocolVersion: z.string().min(1),
+		mostra: z.looseObject({ versionId: z.string().min(1).max(64) }).exactOptional()
+	}),
+	result: z.looseObject({
+		protocolVersion: z.string().min(1),
+		hostInfo: Implementation,
+		hostCapabilities: z.record(z.string(), z.unknown()),
+		hostContext: z.looseObject({
+			theme: z.enum(["light", "dark"]).exactOptional(),
+			displayMode: z.enum([
+				"inline",
+				"fullscreen",
+				"pip"
+			]).exactOptional(),
+			availableDisplayModes: z.array(z.string()).readonly().exactOptional(),
+			locale: z.string().exactOptional(),
+			timeZone: z.string().exactOptional(),
+			platform: z.enum([
+				"web",
+				"desktop",
+				"mobile"
+			]).exactOptional()
+		}),
+		mostra: ViewContextWire.exactOptional()
+	})
+};
+/** `ui/notifications/initialized`: the artifact finished initializing; the shell may now send. */
+const uiInitialized = {
+	method: "ui/notifications/initialized",
+	from: "artifact",
+	kind: "notification",
+	params: z.record(z.string(), z.unknown()),
+	result: z.undefined()
+};
+/** `ui/notifications/size-changed`: the artifact's rendered size (MCP Apps). */
+const uiSizeChanged = {
+	method: "ui/notifications/size-changed",
+	from: "artifact",
+	kind: "notification",
+	params: z.looseObject({
+		width: z.number().min(0).exactOptional(),
+		height: z.number().min(0).exactOptional()
+	}),
+	result: z.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.
+*/
+const OPEN_LINK_SCHEMES = [
+	"http:",
+	"https:",
+	"mailto:",
+	"tel:"
+];
+/**
+* `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.
+*/
+const uiOpenLink = {
+	method: "ui/open-link",
+	from: "artifact",
+	kind: "request",
+	params: z.looseObject({ url: z.string().min(1).max(8192) }),
+	result: z.looseObject({ isError: z.boolean().exactOptional() })
+};
+/** `mostra/ready`: the artifact's page has rendered; `verify` waits for it (ROUND-3 §8). */
+const mostraReady = {
+	method: "mostra/ready",
+	from: "artifact",
+	kind: "notification",
+	params: z.record(z.string(), z.unknown()),
+	result: z.undefined()
+};
+/**
+* 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).
+*/
+const BRIDGE_TEXT_MAX = 1024;
+/** The most fields or blockers one bridge message lists; a page sends those that matter first. */
+const BRIDGE_FIELDS_MAX = 1e4;
+const SubmitBlockerSchema = z.looseObject({
+	fieldId: z.string().min(1).max(256),
+	label: z.string().max(BRIDGE_TEXT_MAX).exactOptional(),
+	reason: z.enum([
+		"required",
+		"invalid",
+		"conflict"
+	])
+});
+/**
+* `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).
+*/
+const mostraFields = {
+	method: "mostra/fields",
+	from: "artifact",
+	kind: "notification",
+	params: z.looseObject({
+		fields: z.array(z.looseObject({
+			id: z.string().min(1).max(256),
+			label: z.string().max(BRIDGE_TEXT_MAX).exactOptional(),
+			required: z.boolean().exactOptional(),
+			scope: z.enum(["viewer", "artifact"]),
+			sensitive: z.boolean().exactOptional(),
+			error: z.string().max(BRIDGE_TEXT_MAX).exactOptional(),
+			conflict: z.boolean().exactOptional()
+		})).max(BRIDGE_FIELDS_MAX).readonly(),
+		save: z.enum([
+			"saved",
+			"saving",
+			"offline",
+			"conflict"
+		]),
+		unsaved: z.boolean()
+	}),
+	result: z.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.
+*/
+const mostraPage = {
+	method: "mostra/page",
+	from: "artifact",
+	kind: "notification",
+	params: z.looseObject({
+		path: z.string().min(1).max(2048),
+		title: z.string().max(1024).exactOptional()
+	}),
+	result: z.undefined()
+};
+/** The longest Submit label the shell renders: one short line. */
+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).
+*/
+const mostraControlsRequest = {
+	method: "mostra/controls.request",
+	from: "artifact",
+	kind: "request",
+	params: z.discriminatedUnion("control", [
+		z.looseObject({
+			control: z.literal("submit"),
+			label: z.string().min(1).max(48).exactOptional(),
+			confirm: z.string().min(1).max(500).exactOptional()
+		}),
+		z.looseObject({
+			control: z.literal("choose"),
+			reviewSetId: z.string().regex(REVIEW_SET_ID_PATTERN),
+			candidates: z.array(z.looseObject({
+				id: z.string().min(1).max(256),
+				label: z.string().max(48).exactOptional()
+			})).min(1).max(64).readonly(),
+			current: z.string().min(1).max(256).exactOptional()
+		}),
+		z.looseObject({
+			control: z.literal("release"),
+			submit: z.literal(true).exactOptional(),
+			reviewSetId: z.string().regex(REVIEW_SET_ID_PATTERN).exactOptional()
+		})
+	]),
+	result: z.looseObject({ shown: z.boolean() })
+};
+/**
+* `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.
+*/
+const mostraFlush = {
+	method: "mostra/flush",
+	from: "shell",
+	kind: "request",
+	params: z.looseObject({ reason: z.enum(["submit", "switch"]) }),
+	result: z.looseObject({
+		revision: z.string().regex(/^(0|[1-9][0-9]{0,15})$/),
+		unsaved: z.boolean(),
+		blockers: z.array(SubmitBlockerSchema).max(BRIDGE_FIELDS_MAX).readonly()
+	})
+};
+/**
+* `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.
+*/
+const mostraVersionAvailable = {
+	method: "mostra/version.available",
+	from: "shell",
+	kind: "notification",
+	params: z.looseObject({
+		versionId: z.string().min(1),
+		version: z.int().min(1),
+		orphans: z.int().min(0)
+	}),
+	result: z.undefined()
+};
+/** `mostra/field.focus`: the viewer picked a blocker in the shell; the page focuses that field. */
+const mostraFieldFocus = {
+	method: "mostra/field.focus",
+	from: "shell",
+	kind: "notification",
+	params: z.looseObject({ id: z.string().min(1).max(256) }),
+	result: z.undefined()
+};
+/**
+* Every message of the bridge in this release. WP-20 adds review messages; a message never
+* changes meaning once released (D32).
+*/
+const BRIDGE_MESSAGES = [
+	uiInitialize,
+	uiInitialized,
+	uiSizeChanged,
+	uiOpenLink,
+	mostraReady,
+	mostraFields,
+	mostraPage,
+	mostraControlsRequest,
+	mostraFlush,
+	mostraVersionAvailable,
+	mostraFieldFocus
+];
+const asMethod = (message) => ({
+	method: message.method,
+	direction: "client-to-instance",
+	mutating: false,
+	params: message.params,
+	result: message.result
+});
+/**
+* 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.
+*/
+function connectBridge(options) {
+	const known = new Map(BRIDGE_MESSAGES.map((message) => [message.method, message]));
+	const send = (message) => {
+		const peer = options.peer();
+		if (!peer) throw new Error("The bridge's peer window is gone.");
+		peer.postMessage(message, options.peerOrigin);
+	};
+	const rpc = new RpcPeer({
+		send,
+		onRequest: (method, params) => {
+			const message = known.get(method);
+			if (!message || message.from === options.side || message.kind !== "request") throw new RpcError(hostDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", { message: `The bridge has no request ${method} for this side.` }), JSON_RPC_ERROR_CODES.methodNotFound);
+			if (!options.onRequest) throw new RpcError(hostDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", { message: `This side doesn't answer ${method}.` }), JSON_RPC_ERROR_CODES.methodNotFound);
+			const parsed = message.params.safeParse(params ?? {});
+			if (!parsed.success) throw new RpcError(hostDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message: `Invalid params for ${method}.` }), JSON_RPC_ERROR_CODES.invalidParams);
+			return options.onRequest(message, parsed.data);
+		},
+		onNotification: (method, params) => {
+			const message = known.get(method);
+			if (message?.kind !== "notification" || message.from === options.side) return;
+			const parsed = message.params.safeParse(params ?? {});
+			if (parsed.success) options.onNotification?.(message, parsed.data);
+		}
+	});
+	/** Why an incoming message must be dropped, or `undefined` when the RPC peer may take it. */
+	const screen = (event) => {
+		const peer = options.peer();
+		if (!peer || event.source !== peer) return "wrong-source";
+		if (event.origin !== options.peerOrigin) return "wrong-origin";
+		const classified = classifyMessage(event.data);
+		if (classified.kind === "invalid") return "not-json-rpc";
+		if (classified.kind !== "request" && classified.kind !== "notification") return void 0;
+		const message = known.get(classified.message.method);
+		if (!message) return "unknown-method";
+		if (message.from === options.side) return "wrong-direction";
+		if (!message.params.safeParse(classified.message.params ?? {}).success) return "invalid-params";
+	};
+	const listener = (event) => {
+		const rejection = screen(event);
+		if (rejection !== void 0) {
+			options.onRejected?.(rejection, event);
+			if (!(rejection !== "wrong-source" && rejection !== "wrong-origin" && rejection !== "not-json-rpc" && classifyMessage(event.data).kind === "request")) return;
+		}
+		rpc.receive(event.data);
+	};
+	options.receiver.addEventListener("message", listener);
+	const sendable = (message) => {
+		if (message.from !== options.side) throw new Error(`The ${options.side} doesn't send ${message.method}.`);
+	};
+	return {
+		call(message, params, callOptions) {
+			sendable(message);
+			return rpc.call(asMethod(message), params, callOptions ?? {});
+		},
+		notify(message, params) {
+			sendable(message);
+			const parsed = message.params.parse(params);
+			rpc.notify(message.method, parsed);
+		},
+		close() {
+			options.receiver.removeEventListener("message", listener);
+			rpc.close();
+		}
+	};
+}
+//#endregion
+export { BRIDGE_FIELDS_MAX, BRIDGE_MESSAGES, BRIDGE_TEXT_MAX, CONTROL_LABEL_MAX, MCP_APPS_PROTOCOL_VERSION, OPEN_LINK_SCHEMES, connectBridge, mostraControlsRequest, mostraFieldFocus, mostraFields, mostraFlush, mostraPage, mostraReady, mostraVersionAvailable, uiInitialize, uiInitialized, uiOpenLink, uiSizeChanged };
+
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

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

package/dist/browser.d.ts

@@ -0,0 +1,195 @@
+import { EphemeralMessage } from "./actions.js";
+import { DeliveryTarget, REVIEW_SET_ID_PATTERN, VersionRef, ViewContext, ViewContextWire, readViewContext } from "./view.js";
+import { DocumentRevision, EventRecord, FieldOp, FieldState, SubmissionSummary, Viewer } from "./interaction.js";
+import * as z from "zod";
+//#region src/browser.d.ts
+/** Every browser-protocol revision this release serves, oldest first. */
+export declare const BROWSER_PROTOCOL_REVISIONS: readonly ["2026-10-15"];
+/** The newest browser-protocol revision: what a client runtime built now speaks. */
+export declare const BROWSER_PROTOCOL_REVISION = "2026-10-15";
+/** The longest JSON a signal's payload may be, in UTF-8 bytes (D106). */
+export declare const SIGNAL_PAYLOAD_MAX_BYTES: number;
+/** `POST …/fields`: one mutation of the viewer's draft or the artifact's state. */
+export interface FieldsRequest {
+  /** A fresh `mut_` ID per change; a retry repeats it and gets the recorded result. */
+  readonly mutationId: string;
+  /** Which document: the viewer's draft or the artifact's shared state. */
+  readonly scope: "viewer" | "artifact";
+  /** The document revision the page last saw; fields changed after it come back as conflicts. */
+  readonly baseRevision: DocumentRevision;
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** The field changes, applied together under one revision. */
+  readonly ops: readonly FieldOp[];
+}
+/** The Zod schema of the `FieldsRequest` type. */
+export declare const FieldsRequest: z.ZodType<FieldsRequest>;
+/** `POST …/submit`: submit the viewer's draft from the artifact's own code (D40). */
+export interface SubmitRequest {
+  /** The view the page was opened as (D104); its version is what the submission names. */
+  readonly viewId: string;
+  /** The draft revision the viewer saw; another one is `MOSTRA_SUBMIT_REVISION_MOVED`. */
+  readonly expectedRevision: DocumentRevision;
+  /** Always `artifact` on this route; the shell's trusted Submit is the `shell` channel (D40). */
+  readonly channel: "artifact";
+}
+/** The Zod schema of the `SubmitRequest` type. */
+export declare const SubmitRequest: z.ZodType<SubmitRequest>;
+/** `POST …/signal`: raise a named signal for the host's attention (IN-09). */
+export interface SignalRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** Letters, digits, `.`, `_` and `-`; `submit` is reserved. */
+  readonly name: string;
+  /** Any JSON, at most 64 KiB. */
+  readonly payload?: unknown;
+}
+/** The Zod schema of the `SignalRequest` type. */
+export declare const SignalRequest: z.ZodType<SignalRequest>;
+/** A document as the page loads it: its revision and fields. */
+export interface DocumentSnapshot {
+  /** The document's revision. */
+  readonly revision: DocumentRevision;
+  /** The draft's epoch (D103); 1 for artifact state. */
+  readonly epoch: number;
+  /** Every field by ID. */
+  readonly fields: Readonly<Record<string, FieldState>>;
+}
+/** The Zod schema of the `DocumentSnapshot` type. */
+export declare const DocumentSnapshot: z.ZodType<DocumentSnapshot>;
+/**
+ * The first message of a browser event stream, and a poll's `snapshot`: where the page stands,
+ * so it renders the canonical draft and state before applying events after `cursor`.
+ */
+export interface StreamSnapshot {
+  /** Events after this cursor follow. */
+  readonly cursor: string;
+  /** Who the page acts as. */
+  readonly viewer: Viewer;
+  /** The viewer's draft. */
+  readonly draft: DocumentSnapshot;
+  /** The artifact's shared state. */
+  readonly state: DocumentSnapshot;
+  /** The submission that closed this draft, or this viewer's latest under `epochs`. */
+  readonly submission?: SubmissionSummary;
+  /**
+   * The artifact's latest version when the snapshot was read (WP-07): a reader that missed its
+   * `version.published` event (published between a frame ticket and the stream, or compacted)
+   * still learns of it.
+   */
+  readonly latest?: VersionRef;
+}
+/** The Zod schema of the `StreamSnapshot` type. */
+export declare const StreamSnapshot: z.ZodType<StreamSnapshot>;
+/** `GET …/events/poll`: the long-poll answer on the same cursor as the stream (D47). */
+export interface PollResult {
+  /** Where the next poll continues. */
+  readonly cursor: string;
+  /** The events for this page after the cursor asked for, in order. */
+  readonly events: readonly EventRecord[];
+  /** Present when the poll asked for none or its cursor was compacted away. */
+  readonly snapshot?: StreamSnapshot;
+  /**
+   * Run and live updates for this view since its last poll (WP-08): lossy and never stored as
+   * events, the long-poll's counterpart of the stream's `run` and `live` messages.
+   */
+  readonly ephemeral?: readonly EphemeralMessage[];
+}
+/** The Zod schema of the `PollResult` type. */
+export declare const PollResult: z.ZodType<PollResult>;
+/**
+ * `POST /a/{artifactId}/_mostra/ticket`'s answer on the shell origin: a single-use frame ticket,
+ * the view it opens and what the shell needs to render the view's trusted controls (D104, D108).
+ */
+export interface FrameTicket extends ViewContext {
+  /** The frame's entry URL, carrying the single-use ticket. */
+  readonly src: string;
+  /** The artifact's origin: the only origin the bridge accepts messages from. */
+  readonly artifactOrigin: string;
+  /** Whether this viewer follows the artifact's new versions (D63). */
+  readonly follow: boolean;
+  /** Whether the link opens this version only (D97 item 9): then the shell offers no newer one. */
+  readonly pinned: boolean;
+  /**
+   * The version's server code keeps crashing and is parked (WP-08, FAILURE_MODEL §2): the shell
+   * says so, since the page's actions and live data won't work until a new publish.
+   */
+  readonly serverParked?: true;
+  /**
+   * The frame shows `mostra dev`'s development preview of unpublished source (D140 item 12): the
+   * shell says so, and it is never a published version.
+   */
+  readonly devPreview?: true;
+}
+/** The Zod schema of the `FrameTicket` type. */
+export declare const FrameTicket: z.ZodType<FrameTicket>;
+/**
+ * `POST /a/{artifactId}/_mostra/v/{rev}/submit`: the shell's trusted Submit (the `shell` channel,
+ * D40). Only the shell's page can send it: the route takes the shell's session, its exact origin
+ * and its CSRF token, none of which an artifact's page has.
+ */
+export interface ShellSubmitRequest {
+  /** The view the shell's frame shows (D104); its version is what the submission names. */
+  readonly viewId: string;
+  /** The draft revision the viewer saw, after the frame flushed its saves. */
+  readonly expectedRevision: DocumentRevision;
+}
+/** The Zod schema of the `ShellSubmitRequest` type. */
+export declare const ShellSubmitRequest: z.ZodType<ShellSubmitRequest>;
+/**
+ * `POST /a/{artifactId}/_mostra/v/{rev}/review/choose`: the shell's trusted Choose (D65, D113).
+ * It writes the viewer's draft field `review.<reviewSetId>.choice` like any mutation, so a stale
+ * base revision comes back as a conflict.
+ */
+export interface ChooseRequest {
+  /** The view the shell's frame shows. */
+  readonly viewId: string;
+  /** A fresh `mut_` ID; a retry repeats it. */
+  readonly mutationId: string;
+  /** The draft revision the shell last saw. */
+  readonly baseRevision: DocumentRevision;
+  /** The review set. */
+  readonly reviewSetId: string;
+  /** The chosen candidate's ID. */
+  readonly candidateId: string;
+  /** The candidate's label, kept with the choice for results. */
+  readonly label?: string;
+}
+/** The Zod schema of the `ChooseRequest` type. */
+export declare const ChooseRequest: z.ZodType<ChooseRequest>;
+/** `POST /a/{artifactId}/_mostra/v/{rev}/follow`: the viewer's "Always follow this artifact" (D63). */
+export interface FollowRequest {
+  /** `true` to load new versions automatically, `false` to stop. */
+  readonly follow: boolean;
+}
+/** The Zod schema of the `FollowRequest` type. */
+export declare const FollowRequest: z.ZodType<FollowRequest>;
+/** A draft field a version doesn't cover (D42, D109): kept, shown read-only and delivered. */
+export interface OrphanedField {
+  /** The field's ID. */
+  readonly id: string;
+  /** Its label, when it has one. */
+  readonly label?: string;
+  /** Its value. */
+  readonly value: unknown;
+  /** The version whose view last wrote it. */
+  readonly fromVersion: number;
+}
+/** The Zod schema of the `OrphanedField` type. */
+export declare const OrphanedField: z.ZodType<OrphanedField>;
+/**
+ * `GET /a/{artifactId}/_mostra/v/{rev}/carry?version=<number>`: which of the viewer's answers a
+ * version doesn't carry over (D42, D109). The banner counts them before a switch; the "Not
+ * carried over" panel lists them for the version shown.
+ */
+export interface CarryOver {
+  /** The version asked about. */
+  readonly version: VersionRef;
+  /** The viewer's draft fields the version doesn't cover. */
+  readonly orphans: readonly OrphanedField[];
+}
+/** The Zod schema of the `CarryOver` type. */
+export declare const CarryOver: z.ZodType<CarryOver>;
+//#endregion
+export { type DeliveryTarget, REVIEW_SET_ID_PATTERN, VersionRef, ViewContext, ViewContextWire, readViewContext };
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","names":[],"sources":["../src/browser.ts"],"mappings":";;;;;;qBA0Ca;;qBAGA;;qBAGA;;iBAGI;;WAEN;;WAEA;;WAEA,cAAc;;WAEd;;WAEA,cAAc;;;qBAIZ,eAAe,EAAE,QAAQ;;iBAcrB;;WAEN;;WAEA,kBAAkB;;WAElB;;;qBAIE,eAAe,EAAE,QAAQ;;iBAYrB;;WAEN;;WAEA;;WAEA;;;qBAIE,eAAe,EAAE,QAAQ;;iBAYrB;;WAEN,UAAU;;WAEV;;WAEA,QAAQ,SAAS,eAAe;;;qBAI9B,kBAAkB,EAAE,QAAQ;;;;;iBAexB;;WAEN;;WAEA,QAAQ;;WAER,OAAO;;WAEP,OAAO;;WAEP,aAAa;;;;;;WAMb,SAAS;;;qBAIP,gBAAgB,EAAE,QAAQ;;iBAetB;;WAEN;;WAEA,iBAAiB;;WAEjB,WAAW;;;;;WAKX,qBAAqB;;;qBAInB,YAAY,EAAE,QAAQ;;;;;iBAgBlB,oBAAoB;;WAE1B;;WAEA;;WAEA;;WAEA;;;;;WAKA;;;;;WAKA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;;iBA6BnB;;WAEN;;WAEA,kBAAkB;;;qBAIhB,oBAAoB,EAAE,QAAQ;;;;;;iBAY1B;;WAEN;;WAEA;;WAEA,cAAc;;WAEd;;WAEA;;WAEA;;;qBAIE,eAAe,EAAE,QAAQ;;iBAgBrB;;WAEN;;;qBAIE,eAAe,EAAE,QAAQ;;iBAQrB;;WAEN;;WAEA;;WAEA;;WAEA;;;qBAIE,eAAe,EAAE,QAAQ;;;;;;iBAiBrB;;WAEN,SAAS;;WAET,kBAAkB;;;qBAIhB,WAAW,EAAE,QAAQ"}