@jigs.design/client 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @jigs.design/client
 
-`createPickleClient` is the browser's connection to a Pickle server: the transport and the query cache, on TanStack Query Core. It has no React and no schema library.
+`createPickleClient` is the browser's connection to a Pickle server: the transport and the query cache, on TanStack Query Core. `createViewController` is the framework-free half of the view: it owns the sandbox frame, keeps the tree and routes the program's queries, mutations and actions through the client, so a renderer for any framework builds on it as `PickleView` does. The package has no React and no schema library.
 
 ```ts
 import { createPickleClient } from "@jigs.design/client";
@@ -12,13 +12,19 @@ Create one client per app, in its own module. Every view and session that import
 
 ## Exports
 
-| Export               | What it is                                                       |
-| -------------------- | ---------------------------------------------------------------- |
-| `createPickleClient` | The client, with `observe`, `mutate`, `invalidate` and `session` |
+| Export                                           | What it is                                                                                                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createPickleClient`                             | The client, with `observe`, `mutate`, `invalidate` and `session`                                                                                 |
+| `httpTransport`, `Transport`                     | The default HTTP transport, and the type to implement your own                                                                                   |
+| `TransportError`                                 | What a transport rejects with: `{ code, message }`                                                                                               |
+| `createViewController`, `ViewController`         | One view's page side: `start`, `load`, `subscribe`, `store`, `drawnProps`, `call`, `stop`, and the handlers for issues, actions and confirmation |
+| `missingComponents`                              | The components a program draws that a registry lacks, as issues for `setUnregistered`                                                            |
+| `ViewIssue`, `ViewStatus`                        | What the issue handler receives, and what `getStatus` returns                                                                                    |
+| `ActionCall`, `ActionHandler`, `ConfirmFunction` | What the action and confirmation handlers receive                                                                                                |
 
 The view calls `observe` and `mutate`; app code calls `invalidate`. `mutate(name, input, procedure)` takes the procedure's `kind` and `invalidates` from the program, and every call goes out with its `kind`, which the server checks against the host.
-| `httpTransport`, `Transport` | The default HTTP transport, and the type to implement your own |
-| `TransportError` | What a transport rejects with: `{ code, message }` |
+
+The controller trusts the program it loaded and nothing the worker says: it checks each read and mutation against the program's procedure table, has the tree store check each op against the program's prop schemas, and enforces the budgets on the page again. `drawnProps` turns a node's props into what a component takes, reading each prop's kind from the schema, never from the value.
 
 It re-exports the shared types from `@jigs.design/runtime`.
 
@@ -26,7 +32,10 @@ It re-exports the shared types from `@jigs.design/runtime`.
 
 - `src/client.ts`: the client and its query cache.
 - `src/transport.ts`: the transport contract and the HTTP transport.
+- `src/view/controller.ts`: the frame, its messages, the tree and the calls it makes through the client.
+- `src/view/frame-check.ts`: tells you when a page policy broke the frame's own.
+- `src/view/protocol-reference.test.ts`: renders the frame protocol page of the docs from the types and the limits.
 
 ## Docs
 
-[Transport](../../apps/docs/docs/running/transport.mdx) and [Session](../../apps/docs/docs/running/session.mdx).
+[Transport](../../apps/docs/docs/running/transport.mdx), [Session](../../apps/docs/docs/running/session.mdx), [Renderers](../../apps/docs/docs/renderers/index.mdx) and [Frame protocol](../../apps/docs/docs/renderers/protocol.mdx).

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CallReply, HeadersOption, HttpTransportOptions, Transport, TransportError, httpTransport } from "./transport.js";
 import { ClientOptions, ConfirmFunction, PickleClient, createPickleClient } from "./client.js";
+import { ActionCall, ActionHandler, ViewController, ViewIssue, ViewStatus, createViewController, missingComponents } from "./view/controller.js";
 import { Diagnostic, Invalidation, Message, PickleErrorCode, PickleErrorData, Program, SessionEvent, Span } from "@jigs.design/runtime";
-export { type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type Message, type PickleClient, type PickleErrorCode, type PickleErrorData, type Program, type SessionEvent, type Span, type Transport, TransportError, createPickleClient, httpTransport };
+export { type ActionCall, type ActionHandler, type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type Message, type PickleClient, type PickleErrorCode, type PickleErrorData, type Program, type SessionEvent, type Span, type Transport, TransportError, type ViewController, type ViewIssue, type ViewStatus, createPickleClient, createViewController, httpTransport, missingComponents };

package/dist/index.js

@@ -1,3 +1,4 @@
 import { TransportError, httpTransport } from "./transport.js";
 import { createPickleClient } from "./client.js";
-export { TransportError, createPickleClient, httpTransport };
+import { createViewController, missingComponents } from "./view/controller.js";
+export { TransportError, createPickleClient, createViewController, httpTransport, missingComponents };

package/dist/view/controller.d.ts

@@ -0,0 +1,132 @@
+import { ConfirmFunction, PickleClient } from "../client.js";
+import { Program, PropSchema, RuntimeError, TreeNode, TreeStore, WireArg } from "@jigs.design/runtime";
+//#region src/view/controller.d.ts
+/** What the view shows beside the tree: a snapshot, replaced on each change. */
+export interface ViewStatus {
+  /** Runtime errors the program threw in its last result. */
+  errors: ReadonlyArray<RuntimeError>;
+  /** Props and components the view dropped while checking ops. */
+  issues: ReadonlyArray<string>;
+  /** Set when the sandbox rejected or stopped a program, or cannot run. */
+  notice: string | null;
+}
+/**
+ * A problem the view found, as `onIssue` receives it: a runtime error the
+ * program threw, something the view dropped (a prop or component that failed
+ * its schema, a request the program does not declare, a component missing
+ * from the registry), or a notice that the sandbox rejected or stopped a
+ * program or cannot run.
+ */
+export type ViewIssue = {
+  kind: "dropped";
+  message: string;
+} | {
+  kind: "error";
+  line: number | null;
+  message: string;
+} | {
+  kind: "notice";
+  message: string;
+};
+/** An action the program called, after the server checked its input. */
+export interface ActionCall {
+  input: unknown;
+  name: string;
+}
+/**
+ * Handles the program's actions. What it returns (awaited and copied with
+ * `structuredClone`) is the handle's `data`; what it throws is the handle's
+ * `error`.
+ */
+export type ActionHandler = (action: ActionCall) => unknown;
+/**
+ * The page side of one view, for any renderer: it owns the sandbox frame and
+ * the tree, and routes the program's queries, mutations and actions. Call
+ * `start`, then `load` a program; `subscribe` fires when the tree or the
+ * status changes, and `store.get` reads a node from `ROOT_ID` down. Draw
+ * each node's props through `drawnProps`, which gives handlers as functions
+ * that call back into the worker. `stop` tears everything down.
+ */
+export interface ViewController {
+  /**
+   * Runs handler `fn` of node `node` in the worker with `args`. The
+   * functions `drawnProps` returns call this; use it directly to replay an
+   * event from elsewhere.
+   */
+  call: (node: number, fn: string, args: ReadonlyArray<WireArg>) => void;
+  /** Whether the current program lets `type` take children. */
+  childrenAllowed: (type: string) => boolean;
+  /**
+   * The props to draw `node` with: a primitive prop as it is, a list as its
+   * rows, and a handler as a function that sends its primitive arguments to
+   * the worker. Which is which comes from the program's schema, never from
+   * the value. A prop named `autoFocus` is left out unless `allowAutoFocus`,
+   * so a program cannot take the focus on a page that has not allowed it.
+   */
+  drawnProps: (node: TreeNode, options: {
+    allowAutoFocus: boolean;
+  }) => Record<string, unknown>;
+  /**
+   * How many times the worker finished answering every handler call of
+   * `node`. It changes once the program has seen the node's latest events.
+   */
+  getSettled: (node: number) => number;
+  getStatus: () => ViewStatus;
+  /**
+   * Runs `program`. When `document` differs from the last one's, the
+   * program starts from fresh state and confirmations still waiting on the
+   * user are withdrawn; otherwise state it still declares keeps its value,
+   * and an equal program, by value, does nothing.
+   */
+  load: (program: Program, document?: number | string) => void;
+  /** The kind of prop `name` of `type` in the current program's schema. */
+  propKind: (type: string, name: string) => PropSchema["kind"] | undefined;
+  /** Replaces the action handler; `undefined` makes every action fail. */
+  setActionHandler: (handler: ActionHandler | undefined) => void;
+  /**
+   * Replaces what asks the user to confirm a mutation; `undefined` falls
+   * back to the client's `confirm`. A question still open when the view
+   * stops, loads another document or restarts a hung worker has its
+   * `signal` aborted.
+   */
+  setConfirmHandler: (handler: ConfirmFunction | undefined) => void;
+  /** Replaces what each new issue is given to; `undefined` stops reporting. */
+  setIssueHandler: (handler: ((issue: ViewIssue) => void) | undefined) => void;
+  /**
+   * Components the program uses that the registry lacks, as issues to
+   * report; `missingComponents` lists them.
+   */
+  setUnregistered: (issues: ReadonlyArray<string>) => void;
+  /**
+   * Appends the hidden sandbox frame to the document and listens for its
+   * messages. Call it once the renderer is on the page; a second call does
+   * nothing until `stop`.
+   */
+  start: () => void;
+  /**
+   * Removes the frame, forgets the programs, withdraws open confirmations
+   * and empties the tree. Results that arrive afterwards are dropped. The
+   * controller can `start` again.
+   */
+  stop: () => void;
+  /** The tree the program drew, checked against its schemas. Read it from `ROOT_ID`. */
+  store: TreeStore;
+  /** Fires after the tree or the status changed. Returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void;
+}
+/**
+ * The components `program` draws that `registered` lacks, as the issues the
+ * view reports for them. Give the result to `setUnregistered`.
+ */
+export declare function missingComponents(program: Program, registered: ReadonlyArray<string>): Array<string>;
+/**
+ * Page side of the sandbox. Owns the frame, sends programs and handler calls
+ * to the worker, applies the ops it returns to `store`, keeps exactly the
+ * queries the program reads subscribed through the client, and runs the
+ * mutations its handlers call. Messages from anything but its own frame are
+ * ignored, and the names a result asks for must be the right kind of
+ * procedure in the program, since the worker shares its realm with the
+ * program and is not trusted either.
+ */
+export declare function createViewController(client: PickleClient): ViewController;
+//#endregion

package/dist/view/controller.js

@@ -0,0 +1,539 @@
+import { frameProblem, unprotectedProblem } from "./frame-check.js";
+import { createTreeStore, parseErrorData, parseProgram } from "@jigs.design/runtime";
+//#region src/view/controller.ts
+const WATCHDOG_NOTICE = "Program stopped: it did not answer within a second. The sandbox was restarted.";
+const GAVE_UP_NOTICE = "Program stopped: it did not answer within a second, again after a restart. It will not run until a new program is loaded.";
+const idle = {
+	errors: [],
+	issues: [],
+	notice: null
+};
+const FORMAT_NOTICE = "This program was compiled for another version of the runtime; compile it again.";
+/**
+* How long after the frame loads it may take to say it is ready. Its policy
+* check takes a moment, or up to a second when the policy is gone, and then
+* the frame says `unprotected` itself; silence past this means its script
+* never ran.
+*/
+const STARTUP_MS = 3e3;
+const MAX_ERROR_TEXT = 1e3;
+/** The prop a registry component reads to focus itself when it mounts. */
+const AUTO_FOCUS = "autoFocus";
+const toWireArgs = (args) => args.filter((arg) => typeof arg === "string" || typeof arg === "number" || typeof arg === "boolean");
+/**
+* The components `program` draws that `registered` lacks, as the issues the
+* view reports for them. Give the result to `setUnregistered`.
+*/
+function missingComponents(program, registered) {
+	return Object.keys(program.components).filter((name) => !registered.includes(name)).map((name) => `<${name}> is not in the registry, so it renders nothing`);
+}
+const NO_ACTIONS = {
+	error: {
+		code: "UNAVAILABLE",
+		message: "This page handles no actions"
+	},
+	status: "error"
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The runtime errors of a result, as text React can draw. The frame is not trusted. */
+function parseErrors(list) {
+	const errors = [];
+	for (const entry of list) {
+		if (errors.length >= 20) break;
+		if (isRecord(entry) && typeof entry.message === "string") {
+			const line = entry.line;
+			errors.push({
+				line: typeof line === "number" && Number.isSafeInteger(line) ? line : null,
+				message: entry.message.slice(0, MAX_ERROR_TEXT)
+			});
+		}
+	}
+	return errors;
+}
+/** A message from the frame with the fields its kind needs. The frame is not trusted. */
+function isFrameMessage(value) {
+	if (typeof value !== "object" || value === null || !("type" in value)) return false;
+	if (value.type === "ready" || value.type === "unprotected") return true;
+	if (!("seq" in value) || typeof value.seq !== "number") return false;
+	if (value.type === "result") return "ops" in value && Array.isArray(value.ops) && "errors" in value && Array.isArray(value.errors) && "queries" in value && Array.isArray(value.queries) && "mutations" in value && Array.isArray(value.mutations);
+	if (value.type === "failed") return "message" in value && typeof value.message === "string";
+	return value.type === "quarantined";
+}
+/**
+* Page side of the sandbox. Owns the frame, sends programs and handler calls
+* to the worker, applies the ops it returns to `store`, keeps exactly the
+* queries the program reads subscribed through the client, and runs the
+* mutations its handlers call. Messages from anything but its own frame are
+* ignored, and the names a result asks for must be the right kind of
+* procedure in the program, since the worker shares its realm with the
+* program and is not trusted either.
+*/
+function createViewController(client) {
+	const store = createTreeStore();
+	const listeners = /* @__PURE__ */ new Set();
+	const observers = /* @__PURE__ */ new Map();
+	const sent = /* @__PURE__ */ new Map();
+	let iframe = null;
+	let ready = false;
+	let queue = [];
+	let seq = 0;
+	/** The program the worker accepted and is running. */
+	let running = null;
+	/** The program the view was last given; the worker may not have accepted it yet. */
+	let latest = null;
+	let latestKey = null;
+	/** The document of the last program sent to the worker, as `load` was told. */
+	let latestDocument;
+	let lastGood = null;
+	const updates = /* @__PURE__ */ new Map();
+	/** Times each program hung, against `MAX_HANGS`. */
+	let hangs = /* @__PURE__ */ new WeakMap();
+	/** Handler calls the worker has not answered yet: seq to node. */
+	const calls = /* @__PURE__ */ new Map();
+	/** Unanswered calls per node, and how often each node's calls all settled. */
+	const openCalls = /* @__PURE__ */ new Map();
+	const settled = /* @__PURE__ */ new Map();
+	/** What the view itself dropped from results since the last program change. */
+	let dropped = [];
+	let status = idle;
+	/** Bumped on stop and on quarantine, so late results are dropped. */
+	let generation = 0;
+	let startup = null;
+	let actionHandler;
+	let confirmHandler;
+	/**
+	* Aborts the confirmations the program on screen asked for, so a question
+	* still showing cannot run a mutation for a program that is gone.
+	*/
+	let confirmationScope = new AbortController();
+	const withdrawConfirmations = () => {
+		confirmationScope.abort();
+		confirmationScope = new AbortController();
+	};
+	let issueHandler;
+	/** Issues already reported that are still present, by key. */
+	let announced = /* @__PURE__ */ new Set();
+	let unregistered = [];
+	let reported = false;
+	let warnedClone = false;
+	/**
+	* Reports each issue that was not present before. One that persists is
+	* reported once; one that goes away and comes back, again.
+	*/
+	const announce = () => {
+		const present = /* @__PURE__ */ new Set();
+		const fresh = [];
+		const note = (key, issue) => {
+			present.add(key);
+			if (!announced.has(key)) fresh.push(issue);
+		};
+		for (const error of status.errors) note(`error:${error.line ?? ""}:${error.message}`, {
+			kind: "error",
+			line: error.line,
+			message: error.message
+		});
+		for (const message of [...unregistered, ...status.issues]) note(`dropped:${message}`, {
+			kind: "dropped",
+			message
+		});
+		if (status.notice !== null) note(`notice:${status.notice}`, {
+			kind: "notice",
+			message: status.notice
+		});
+		announced = present;
+		const handler = issueHandler;
+		for (const issue of fresh) handler?.(issue);
+	};
+	const setStatus = (next) => {
+		status = next;
+		for (const listener of listeners) listener();
+		announce();
+	};
+	const drop = (issue) => {
+		if (dropped.length < 20 && !dropped.includes(issue)) dropped = [...dropped, issue];
+	};
+	const clearStartup = () => {
+		if (startup !== null) {
+			clearTimeout(startup);
+			startup = null;
+		}
+	};
+	/** A frame that cannot run is a setup mistake: say so once, in the view and the console. */
+	const reportFrame = (problem) => {
+		clearStartup();
+		if (reported) return;
+		reported = true;
+		console.error(`Pickle: ${problem}`);
+		setStatus({
+			...status,
+			notice: problem
+		});
+	};
+	/** Fetches the frame again to tell a replaced policy from other reasons it stayed silent. */
+	const diagnoseFrame = () => {
+		startup = null;
+		const started = generation;
+		fetch(client.frame, { cache: "no-store" }).then((response) => frameProblem(client.frame, response, window.location.origin), () => frameProblem(client.frame, null, window.location.origin)).then((problem) => {
+			if (started === generation && !ready) reportFrame(problem);
+		});
+	};
+	/** `value` as the worker may receive it, or null when it cannot be copied (a function, say). */
+	const cloneable = (value) => {
+		try {
+			return structuredClone(value ?? null);
+		} catch {
+			if (!warnedClone) {
+				warnedClone = true;
+				console.warn("Pickle: an onAction handler returned a value structuredClone cannot copy (a function, a DOM node, a class with private fields), so the program's handle got null as its data.");
+			}
+			return null;
+		}
+	};
+	/** Gives a checked action to the page's handler and settles the handle with its outcome. */
+	const runAction = async (action) => {
+		const handler = actionHandler;
+		if (handler === void 0) return NO_ACTIONS;
+		try {
+			return {
+				data: cloneable(await handler(action)),
+				status: "success"
+			};
+		} catch (error) {
+			return {
+				error: parseErrorData(error) ?? {
+					code: "INTERNAL",
+					message: error instanceof Error ? error.message : String(error)
+				},
+				status: "error"
+			};
+		}
+	};
+	const post = (message) => {
+		if (ready && iframe?.contentWindow) iframe.contentWindow.postMessage(message, "*");
+		else queue.push(message);
+	};
+	const sendUpdate = (next, fresh) => {
+		seq++;
+		updates.set(seq, next);
+		post({
+			code: next.code,
+			fresh,
+			procedures: next.procedures,
+			prose: next.prose,
+			seq,
+			type: "update"
+		});
+	};
+	const sendQuery = (key, result) => {
+		const text = JSON.stringify(result);
+		if (sent.get(key) === text) return;
+		sent.set(key, text);
+		if (result.status === "pending") return;
+		seq++;
+		post({
+			key,
+			result,
+			seq,
+			type: "query"
+		});
+	};
+	const dropObservers = () => {
+		for (const unsubscribe of observers.values()) unsubscribe();
+		observers.clear();
+		sent.clear();
+	};
+	/** The running program's entry for `name`, if it is one of `kinds`. */
+	const procedure = (name, kinds) => {
+		if (running === null || !Object.hasOwn(running.procedures, name)) return;
+		const entry = running.procedures[name];
+		return entry !== void 0 && kinds.includes(entry.kind) ? entry : void 0;
+	};
+	/** The queries a result reads that the program declares, up to `MAX_QUERIES`. */
+	const checkedReads = (reads) => {
+		const wanted = /* @__PURE__ */ new Map();
+		for (const read of reads) {
+			if (!isRecord(read) || typeof read.key !== "string" || typeof read.name !== "string" || procedure(read.name, ["query"]) === void 0) {
+				drop("The sandbox read a query this program does not declare");
+				continue;
+			}
+			if (!wanted.has(read.key) && wanted.size >= 20) {
+				drop(`The sandbox read more than 20 queries`);
+				continue;
+			}
+			wanted.set(read.key, {
+				input: read.input,
+				key: read.key,
+				name: read.name
+			});
+		}
+		return wanted;
+	};
+	const syncQueries = (wanted) => {
+		for (const [key, unsubscribe] of observers) if (!wanted.has(key)) {
+			unsubscribe();
+			observers.delete(key);
+			sent.delete(key);
+		}
+		for (const [key, read] of wanted) if (!observers.has(key)) observers.set(key, client.observe(read.name, read.input, (result) => {
+			sendQuery(key, result);
+		}));
+	};
+	/** Marks the call `answered` done; returns whether it was a handler call. */
+	const answer = (answered) => {
+		const node = calls.get(answered);
+		if (node === void 0) return false;
+		calls.delete(answered);
+		const left = (openCalls.get(node) ?? 1) - 1;
+		if (left > 0) openCalls.set(node, left);
+		else {
+			openCalls.delete(node);
+			settled.set(node, (settled.get(node) ?? 0) + 1);
+		}
+		return true;
+	};
+	const forgetCalls = () => {
+		calls.clear();
+		openCalls.clear();
+		settled.clear();
+	};
+	const runMutations = (mutations, fromHandler) => {
+		if (mutations.length > 0 && !fromHandler) {
+			drop("The sandbox asked for a mutation outside an event handler");
+			return;
+		}
+		if (mutations.length > 5) drop(`The sandbox asked for more than 5 mutations at once`);
+		const started = generation;
+		for (const mutation of mutations.slice(0, 5)) {
+			const call = isRecord(mutation) && typeof mutation.id === "number" && typeof mutation.name === "string" ? {
+				id: mutation.id,
+				input: mutation.input,
+				name: mutation.name
+			} : null;
+			const entry = call === null ? void 0 : procedure(call.name, ["action", "mutation"]);
+			if (call === null || entry === void 0) {
+				drop("The sandbox called a mutation this program does not declare");
+				continue;
+			}
+			const kind = entry.kind === "action" ? "action" : "mutation";
+			client.mutate(call.name, call.input, {
+				confirm: confirmHandler,
+				invalidates: entry.invalidates,
+				kind,
+				signal: confirmationScope.signal
+			}).then((result) => kind === "action" && result.status === "success" && started === generation ? runAction({
+				input: result.data,
+				name: call.name
+			}) : result).then((result) => {
+				if (started === generation) {
+					seq++;
+					post({
+						id: call.id,
+						result,
+						seq,
+						type: "mutation"
+					});
+				}
+			});
+		}
+	};
+	const onMessage = (event) => {
+		if (iframe === null || event.source !== iframe.contentWindow) return;
+		const message = event.data;
+		if (!isFrameMessage(message)) return;
+		switch (message.type) {
+			case "unprotected":
+				reportFrame(unprotectedProblem(client.frame));
+				return;
+			case "ready": {
+				clearStartup();
+				ready = true;
+				const queued = queue;
+				queue = [];
+				for (const item of queued) post(item);
+				return;
+			}
+			case "result": {
+				const update = updates.get(message.seq);
+				updates.delete(message.seq);
+				if (update !== void 0) {
+					running = update;
+					lastGood = update;
+					dropped = [];
+					store.setSchemas(update);
+				}
+				store.apply(message.ops);
+				const fromHandler = answer(message.seq);
+				const wanted = checkedReads(message.queries);
+				runMutations(message.mutations, fromHandler);
+				const newest = update !== void 0 && update === latest && !hangs.has(update);
+				setStatus({
+					errors: parseErrors(message.errors),
+					issues: [...store.getIssues(), ...dropped],
+					notice: newest ? null : status.notice
+				});
+				syncQueries(wanted);
+				return;
+			}
+			case "failed": {
+				const failed = updates.get(message.seq);
+				updates.delete(message.seq);
+				answer(message.seq);
+				if (failed !== void 0 && failed === latest) latest = running;
+				setStatus({
+					...status,
+					notice: `Program failed (${message.message}); showing the last working version.`
+				});
+				return;
+			}
+			case "quarantined": {
+				const failed = updates.get(message.seq);
+				const culprit = failed ?? running ?? latest;
+				updates.clear();
+				generation++;
+				withdrawConfirmations();
+				dropObservers();
+				forgetCalls();
+				store.reset();
+				running = null;
+				if (culprit !== null) {
+					const before = hangs.get(culprit) ?? 0;
+					hangs.set(culprit, failed === void 0 ? before + 1 : 2);
+					if (before === 0) console.warn(`Pickle: ${WATCHDOG_NOTICE}`);
+				}
+				const usable = (candidate) => candidate !== null && (hangs.get(candidate) ?? 0) < 2;
+				let recovery = null;
+				if (usable(latest)) recovery = latest;
+				else if (usable(lastGood)) recovery = lastGood;
+				setStatus({
+					errors: [],
+					issues: [],
+					notice: recovery === null ? GAVE_UP_NOTICE : WATCHDOG_NOTICE
+				});
+				if (recovery !== null) sendUpdate(recovery, false);
+				return;
+			}
+		}
+	};
+	const call = (node, fn, args) => {
+		seq++;
+		calls.set(seq, node);
+		openCalls.set(node, (openCalls.get(node) ?? 0) + 1);
+		post({
+			args,
+			fn,
+			seq,
+			type: "call"
+		});
+	};
+	const propKind = (type, name) => {
+		const component = running !== null && Object.hasOwn(running.components, type) ? running.components[type] : void 0;
+		return component !== void 0 && Object.hasOwn(component.props, name) ? component.props[name]?.kind : void 0;
+	};
+	return {
+		call,
+		childrenAllowed: (type) => running !== null && Object.hasOwn(running.components, type) && running.components[type]?.children !== "none",
+		drawnProps: (node, options) => {
+			const drawn = {};
+			for (const [name, value] of Object.entries(node.props)) {
+				if (name === AUTO_FOCUS && !options.allowAutoFocus) continue;
+				const kind = propKind(node.type, name);
+				if (kind === "handler") {
+					if (typeof value === "object" && "fn" in value) {
+						const fn = value.fn;
+						drawn[name] = (...args) => {
+							call(node.id, fn, toWireArgs(args));
+						};
+					}
+				} else if (kind === "list") {
+					if (typeof value === "object" && "rows" in value) drawn[name] = value.rows;
+				} else if (kind !== void 0 && typeof value !== "object") drawn[name] = value;
+			}
+			return drawn;
+		},
+		getSettled: (node) => settled.get(node) ?? 0,
+		getStatus: () => status,
+		load: (next, document) => {
+			const fresh = document !== latestDocument;
+			const key = JSON.stringify(next);
+			if (key === latestKey && !fresh) return;
+			latestKey = key;
+			const checked = parseProgram(next);
+			if (checked === null) {
+				setStatus({
+					...status,
+					notice: FORMAT_NOTICE
+				});
+				return;
+			}
+			latest = checked;
+			latestDocument = document;
+			if (fresh) withdrawConfirmations();
+			sendUpdate(checked, fresh);
+		},
+		propKind,
+		setActionHandler: (handler) => {
+			actionHandler = handler;
+		},
+		setConfirmHandler: (handler) => {
+			confirmHandler = handler;
+		},
+		setIssueHandler: (handler) => {
+			issueHandler = handler;
+		},
+		setUnregistered: (issues) => {
+			unregistered = issues;
+			announce();
+		},
+		start: () => {
+			if (iframe !== null) return;
+			const frame = document.createElement("iframe");
+			frame.setAttribute("sandbox", "allow-scripts");
+			frame.setAttribute("aria-hidden", "true");
+			frame.setAttribute("tabindex", "-1");
+			frame.style.display = "none";
+			frame.src = client.frame;
+			frame.addEventListener("load", () => {
+				if (iframe === frame && !ready && startup === null) startup = setTimeout(diagnoseFrame, STARTUP_MS);
+			});
+			iframe = frame;
+			window.addEventListener("message", onMessage);
+			document.body.append(frame);
+		},
+		stop: () => {
+			generation++;
+			window.removeEventListener("message", onMessage);
+			iframe?.remove();
+			iframe = null;
+			ready = false;
+			clearStartup();
+			reported = false;
+			queue = [];
+			updates.clear();
+			hangs = /* @__PURE__ */ new WeakMap();
+			forgetCalls();
+			dropped = [];
+			lastGood = null;
+			running = null;
+			latest = null;
+			latestKey = null;
+			latestDocument = void 0;
+			actionHandler = void 0;
+			confirmHandler = void 0;
+			withdrawConfirmations();
+			dropObservers();
+			store.reset();
+			status = idle;
+		},
+		store,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			const unsubscribe = store.subscribe(listener);
+			return () => {
+				listeners.delete(listener);
+				unsubscribe();
+			};
+		}
+	};
+}
+//#endregion
+export { MAX_ERROR_TEXT, STARTUP_MS, createViewController, missingComponents };

package/dist/view/frame-check.js

@@ -0,0 +1,32 @@
+import { frameSecurityPolicy } from "@jigs.design/runtime";
+//#region src/view/frame-check.ts
+const ADVICE = "Exclude that route from your page policy: `contentSecurityPolicy(host, { endpoint }).appliesTo(request.url)` is false for it.";
+/**
+* The issue for a frame that started and found its own policy missing: its
+* scripts ran, so whatever replaced the policy does not block them, but the
+* frame's network lock is gone and it refuses to run programs.
+*/
+function unprotectedProblem(frame) {
+	return `The sandbox frame's Content-Security-Policy is not in force on ${frame}, so the sandbox will not run. A page policy replaced it, or something stripped it. ${ADVICE}`;
+}
+/**
+* The issue for a frame that never said it was ready. `response` is the
+* frame as the view fetched it again, or `null` when that fetch failed, as
+* it does for an endpoint on another origin that does not list the page's
+* origin, `pageOrigin`, in `allowedOrigins`. A response can carry several
+* policies, which `Headers` joins with commas; the frame's own starts with
+* `frameSecurityPolicy`.
+*/
+function frameProblem(frame, response, pageOrigin) {
+	if (response === null) {
+		if ((URL.canParse(frame, pageOrigin) ? new URL(frame, pageOrigin).origin : pageOrigin) !== pageOrigin) return `The sandbox frame at ${frame} did not start, and its response could not be read to say why. It is on another origin: check that the server's \`allowedOrigins\` lists ${pageOrigin}, which its frame-ancestors and CORS headers both need, and that nothing replaces the Content-Security-Policy it sends.`;
+		return `The sandbox frame at ${frame} did not start, and its response could not be read to say why. Check that nothing replaces the Content-Security-Policy it sends.`;
+	}
+	if (response.status !== 200) return `The sandbox frame at ${frame} answered ${response.status}, so the view cannot start. Check that the route hands GET requests to \`pickle.handler\`.`;
+	const policies = (response.headers.get("content-security-policy") ?? "").split(",").map((policy) => policy.trim()).filter((policy) => policy !== "");
+	if (!policies.some((policy) => policy.startsWith(frameSecurityPolicy))) return `The page's Content-Security-Policy replaced the sandbox frame's on ${frame}, so the sandbox will not run. ${ADVICE}`;
+	if (policies.length > 1) return `A second Content-Security-Policy is added to the sandbox frame's response on ${frame}, and it stops the frame from starting. ${ADVICE}`;
+	return `The sandbox frame at ${frame} did not start. Its policy is intact; check the browser console for the frame's own errors.`;
+}
+//#endregion
+export { frameProblem, unprotectedProblem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "createPickleClient: the browser's transport and query cache. No React.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,6 @@
   },
   "dependencies": {
     "@tanstack/query-core": "5.104.4",
-    "@jigs.design/runtime": "0.1.0"
+    "@jigs.design/runtime": "0.1.1"
   }
 }