@jigs.design/client 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @jigs.design/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`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";
+
+export const client = createPickleClient({ endpoint: "/api/pickle" });
+```
+
+Create one client per app, in its own module. Every view and session that imports it shares one query cache, so two views reading the same query make one request, and a mutation's invalidations reach both. The client retries network failures, aborts a query's request when nothing reads it any more, and refreshes the queries a mutation invalidates.
+
+## Exports
+
+| 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.
+
+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`.
+
+## Source
+
+- `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), [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/client.d.ts

@@ -0,0 +1,92 @@
+import { HeadersOption, Transport } from "./transport.js";
+import { Message, MutationResult, QueryResult, SessionEvent, SessionOptions } from "@jigs.design/runtime";
+//#region src/client.d.ts
+interface CacheOptions {
+  /**
+   * How long a query result stays fresh, in milliseconds. A fresh result is
+   * reused by a new view, so two blocks or two turns that read the same
+   * query share one call; a stale one refetches when a view reads it again.
+   * `invalidates` and `invalidate` refetch at any age. Default 60,000: a
+   * minute, so a long session does not show hour-old data.
+   */
+  staleTime?: number;
+}
+/**
+ * What the page asks the user before a mutation whose policy is "confirm"
+ * runs. `message` is the host's text, never the model's; `input` is what
+ * the program sent. Resolve true to run the mutation. `signal` aborts when
+ * the view that called the mutation stops or loads another document: close
+ * the question then, since the mutation has already failed as `DECLINED`.
+ */
+export type ConfirmFunction = (request: {
+  input: unknown;
+  message: string;
+  name: string;
+  signal: AbortSignal;
+}) => Promise<boolean>;
+interface ConfirmOptions {
+  /**
+   * Asks the user to approve a mutation whose policy is "confirm", in the
+   * page's own UI, outside the sandbox. Without it, or when it resolves
+   * false or throws, the mutation fails with `DECLINED`. A `PickleView`'s
+   * `onConfirm` takes its place for that view.
+   */
+  confirm?: ConfirmFunction;
+}
+export type ClientOptions = CacheOptions & ConfirmOptions & ({
+  credentials?: RequestCredentials;
+  endpoint: string;
+  fetch?: typeof fetch;
+  headers?: HeadersOption;
+  transport?: never;
+} | {
+  credentials?: never;
+  endpoint?: never;
+  fetch?: never;
+  headers?: never;
+  transport: Transport;
+});
+export interface PickleClient {
+  /** URL of the sandbox frame document. */
+  readonly frame: string;
+  /** Refetches every query with this name, for every input. */
+  invalidate: (name: string) => Promise<void>;
+  /**
+   * Runs one mutation or action and, when it succeeds, refetches the
+   * queries the server says it refreshed. A reply without that list
+   * refetches every input of each query in `invalidates`. `kind` goes to
+   * the server, which refuses a call whose kind is not the procedure's.
+   * When the server asks for confirmation, `procedure.confirm` (else the
+   * client's `confirm`) asks the user, and the call goes again with the
+   * server's token only if they approve before `procedure.signal` aborts.
+   * The signal only withdraws the question: a call already sent is not
+   * cancelled, since the server may have run it.
+   */
+  mutate: (name: string, input: unknown, procedure: {
+    confirm?: ConfirmFunction | undefined;
+    invalidates: ReadonlyArray<string>;
+    kind: "action" | "mutation";
+    signal?: AbortSignal | undefined;
+  }) => Promise<MutationResult>;
+  /**
+   * Keeps one query subscribed and reports every result. Unsubscribing
+   * aborts its request when nothing else reads it. The call goes out with
+   * `kind: "query"`.
+   */
+  observe: (name: string, input: unknown, listener: (result: QueryResult) => void) => () => void;
+  /** One turn, as session events. */
+  session: (body: {
+    messages: ReadonlyArray<Message>;
+    options?: SessionOptions;
+  }, options: {
+    signal: AbortSignal;
+  }) => AsyncIterable<SessionEvent>;
+}
+/**
+ * The browser's connection to a Pickle server. Create one per app, in its
+ * own module: each client has its own query cache, so two clients share no
+ * requests and no invalidations.
+ */
+export declare function createPickleClient(options: ClientOptions): PickleClient;
+//#endregion
+export {};

package/dist/client.js

@@ -0,0 +1,159 @@
+import { TransportError, errorDataOf, httpTransport } from "./transport.js";
+import { QueryClient, QueryObserver } from "@tanstack/query-core";
+//#region src/client.ts
+/** How long a query result stays fresh by default: a minute. */
+const DEFAULT_STALE_TIME = 6e4;
+const RETRYABLE = /* @__PURE__ */ new Set(["NETWORK", "UNAVAILABLE"]);
+const MAX_RETRIES = 2;
+function toQueryResult(result) {
+	if (result.status === "success") return {
+		data: result.data,
+		error: null,
+		status: "success"
+	};
+	if (result.status === "error") return {
+		data: null,
+		error: errorDataOf(result.error),
+		status: "error"
+	};
+	return {
+		data: null,
+		error: null,
+		status: "pending"
+	};
+}
+/**
+* The browser's connection to a Pickle server. Create one per app, in its
+* own module: each client has its own query cache, so two clients share no
+* requests and no invalidations.
+*/
+function createPickleClient(options) {
+	const transport = options.transport === void 0 ? httpTransport(httpOptions(options)) : options.transport;
+	const queries = new QueryClient({ defaultOptions: {
+		mutations: { retry: false },
+		queries: {
+			gcTime: 3e5,
+			refetchOnReconnect: false,
+			refetchOnWindowFocus: false,
+			retry: (failures, error) => failures < MAX_RETRIES && RETRYABLE.has(errorDataOf(error).code),
+			staleTime: options.staleTime ?? DEFAULT_STALE_TIME
+		}
+	} });
+	return {
+		frame: transport.frame,
+		invalidate: (name) => queries.invalidateQueries({ queryKey: [name] }),
+		mutate: async (name, input, procedure) => {
+			const send = async (confirmation) => {
+				try {
+					return await transport.call(confirmation === void 0 ? {
+						input,
+						kind: procedure.kind,
+						name
+					} : {
+						confirmation,
+						input,
+						kind: procedure.kind,
+						name
+					}, { signal: new AbortController().signal });
+				} catch (error) {
+					return { error: errorDataOf(error) };
+				}
+			};
+			let reply = await send();
+			if ("requiresAction" in reply) {
+				const declined = await askToConfirm(procedure.confirm ?? options.confirm, {
+					input,
+					message: reply.requiresAction.message,
+					name,
+					signal: procedure.signal ?? new AbortController().signal
+				});
+				if (declined !== null) return {
+					error: declined,
+					status: "error"
+				};
+				reply = await send(reply.requiresAction.token);
+			}
+			if ("error" in reply) return {
+				error: reply.error,
+				status: "error"
+			};
+			if ("requiresAction" in reply) return {
+				error: unconfirmed,
+				status: "error"
+			};
+			const targets = reply.invalidate ?? procedure.invalidates.map((target) => ({ name: target }));
+			for (const target of targets) queries.invalidateQueries({ queryKey: target.input === void 0 ? [target.name] : [target.name, target.input] });
+			return {
+				data: reply.data,
+				status: "success"
+			};
+		},
+		observe: (name, input, listener) => {
+			const observer = new QueryObserver(queries, {
+				queryFn: async (context) => {
+					const reply = await transport.call({
+						input,
+						kind: "query",
+						name
+					}, { signal: context.signal });
+					if ("requiresAction" in reply) throw new TransportError(unconfirmed);
+					return reply.data;
+				},
+				queryKey: [name, input]
+			});
+			const unsubscribe = observer.subscribe((result) => {
+				listener(toQueryResult(result));
+			});
+			listener(toQueryResult(observer.getCurrentResult()));
+			return unsubscribe;
+		},
+		session: (body, sessionOptions) => transport.session(body, sessionOptions)
+	};
+}
+const unconfirmed = {
+	code: "FORBIDDEN",
+	message: "The server asked for a confirmation the call cannot give."
+};
+/**
+* Asks the user through `confirm`. Null when they approved before
+* `request.signal` aborted; otherwise the `DECLINED` error the mutation fails
+* with, which says why. An abort settles it even if `confirm` never does.
+*/
+async function askToConfirm(confirm, request) {
+	if (confirm === void 0) return {
+		code: "DECLINED",
+		message: `"${request.name}" needs the user's confirmation, and this page cannot ask for it.`
+	};
+	const withdrawn = {
+		code: "DECLINED",
+		message: `The confirmation for "${request.name}" was withdrawn before the user answered.`
+	};
+	if (request.signal.aborted) return withdrawn;
+	const aborted = Promise.withResolvers();
+	const onAbort = () => aborted.resolve(false);
+	request.signal.addEventListener("abort", onAbort, { once: true });
+	let answer;
+	try {
+		answer = await Promise.race([confirm(request), aborted.promise]) === true ? null : {
+			code: "DECLINED",
+			message: "The user declined."
+		};
+	} catch (error) {
+		answer = {
+			code: "DECLINED",
+			message: `The confirmation for "${request.name}" failed: ${error instanceof Error ? error.message : String(error)}`
+		};
+	} finally {
+		request.signal.removeEventListener("abort", onAbort);
+	}
+	return request.signal.aborted ? withdrawn : answer;
+}
+function httpOptions(options) {
+	const http = { endpoint: options.endpoint };
+	if (options.credentials !== void 0) http.credentials = options.credentials;
+	if (options.fetch !== void 0) http.fetch = options.fetch;
+	if (options.headers !== void 0) http.headers = options.headers;
+	return http;
+}
+//#endregion
+export { createPickleClient };

package/dist/index.d.ts

@@ -0,0 +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 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

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

package/dist/transport.d.ts

@@ -0,0 +1,60 @@
+import { Invalidation, Message, PickleErrorCode, PickleErrorData, ProcedureKind, SessionEvent, SessionOptions } from "@jigs.design/runtime";
+//#region src/transport.d.ts
+/**
+ * A call's reply: the procedure's data and, for a mutation, the queries the
+ * server says it refreshed. Without `invalidate`, the client refreshes every
+ * input of each query in the program's `invalidates` list. A mutation whose
+ * policy is "confirm" first replies with `requiresAction` instead, and has
+ * not run.
+ */
+export type CallReply = {
+  data: unknown;
+  invalidate?: ReadonlyArray<Invalidation>;
+} | {
+  requiresAction: {
+    message: string;
+    token: string;
+  };
+};
+/** How the browser reaches the server. Implement it to host Pickle behind another router. */
+export interface Transport {
+  /**
+   * Resolves with the reply, or rejects with a `TransportError`. `kind` is
+   * the procedure's kind in the program; send it on, since the server
+   * refuses a call without it or with the wrong one.
+   */
+  call: (request: {
+    /** The token from a `requiresAction` reply, once the user approved. */
+    confirmation?: string;
+    input: unknown;
+    kind: ProcedureKind;
+    name: string;
+  }, options: {
+    signal: AbortSignal;
+  }) => Promise<CallReply>;
+  /** URL of the sandbox frame document. */
+  frame: string;
+  /** Reports every failure as one `error` event and then ends; never throws. */
+  session: (body: {
+    messages: ReadonlyArray<Message>;
+    options?: SessionOptions;
+  }, options: {
+    signal: AbortSignal;
+  }) => AsyncIterable<SessionEvent>;
+}
+/** A failure with a code the spec can read. */
+export declare class TransportError extends Error implements PickleErrorData {
+  readonly code: PickleErrorCode;
+  constructor(data: PickleErrorData);
+}
+export type HeadersOption = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export interface HttpTransportOptions {
+  credentials?: RequestCredentials;
+  /** Path or URL where `pickle.handler` is mounted. */
+  endpoint: string;
+  fetch?: typeof fetch;
+  headers?: HeadersOption;
+}
+/** The default transport: `fetch` against `pickle.handler`. */
+export declare function httpTransport(options: HttpTransportOptions): Transport;
+//#endregion

package/dist/transport.js

@@ -0,0 +1,197 @@
+import { parseErrorData, parseInvalidations, parseSessionEvent } from "@jigs.design/runtime";
+//#region src/transport.ts
+/** A failure with a code the spec can read. */
+var TransportError = class extends Error {
+	code;
+	constructor(data) {
+		super(data.message);
+		this.code = data.code;
+		this.name = "TransportError";
+	}
+};
+const VERSION_HEADER = "pickle-version";
+const GATEWAY_STATUSES = /* @__PURE__ */ new Set([
+	502,
+	503,
+	504
+]);
+const unavailable = {
+	code: "UNAVAILABLE",
+	message: "The server is not available right now."
+};
+const network = {
+	code: "NETWORK",
+	message: "Could not reach the server."
+};
+/** The error a reply carries, or `UNAVAILABLE` when the reply is not one of Pickle's. */
+async function replyError(response) {
+	if (GATEWAY_STATUSES.has(response.status) || !response.headers.has(VERSION_HEADER)) return unavailable;
+	try {
+		const body = await response.json();
+		return (typeof body === "object" && body !== null && "error" in body ? parseErrorData(body.error) : null) ?? unavailable;
+	} catch {
+		return unavailable;
+	}
+}
+/** Why the `headers` function failed, as the call's error. */
+function headersError(cause) {
+	return thrownErrorData(cause) ?? {
+		code: "UNAUTHORIZED",
+		message: `The request headers could not be built: ${cause instanceof Error ? cause.message : String(cause)}`
+	};
+}
+/** The default transport: `fetch` against `pickle.handler`. */
+function httpTransport(options) {
+	const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const credentials = options.credentials ?? "same-origin";
+	/**
+	* The request's headers. A `headers` function that throws, such as a
+	* token refresh that failed, is not a network failure: it keeps a thrown
+	* `{ code, message }` and is otherwise `UNAUTHORIZED`, never retried.
+	*/
+	const headers = async () => {
+		let extra;
+		try {
+			extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+		} catch (error) {
+			throw new TransportError(headersError(error));
+		}
+		const merged = new Headers(extra);
+		merged.set("content-type", "application/json");
+		return merged;
+	};
+	const post = (body, init, signal) => fetcher(options.endpoint, {
+		body,
+		credentials,
+		headers: init,
+		method: "POST",
+		signal
+	});
+	return {
+		async call(request, callOptions) {
+			const init = await headers();
+			let response;
+			try {
+				response = await post(JSON.stringify({
+					confirmation: request.confirmation,
+					input: request.input,
+					kind: request.kind,
+					name: request.name,
+					type: "call"
+				}), init, callOptions.signal);
+			} catch (error) {
+				if (callOptions.signal.aborted) throw error;
+				throw new TransportError(network);
+			}
+			if (!response.ok || !response.headers.has(VERSION_HEADER)) throw new TransportError(await replyError(response));
+			let body;
+			try {
+				body = await response.json();
+			} catch {
+				throw new TransportError(unavailable);
+			}
+			if (typeof body !== "object" || body === null) throw new TransportError(unavailable);
+			if ("requiresAction" in body) {
+				const requiresAction = parseRequiresAction(body.requiresAction);
+				if (requiresAction === null) throw new TransportError(unavailable);
+				return { requiresAction };
+			}
+			if (!("data" in body)) throw new TransportError(unavailable);
+			if (!("invalidate" in body)) return { data: body.data };
+			const invalidate = parseInvalidations(body.invalidate);
+			if (invalidate === null) throw new TransportError(unavailable);
+			return {
+				data: body.data,
+				invalidate
+			};
+		},
+		frame: options.endpoint,
+		async *session(body, { signal }) {
+			let init;
+			try {
+				init = await headers();
+			} catch (error) {
+				yield {
+					error: errorDataOf(error),
+					type: "error"
+				};
+				return;
+			}
+			let response;
+			try {
+				response = await post(JSON.stringify({
+					messages: body.messages,
+					options: body.options,
+					type: "session"
+				}), init, signal);
+			} catch {
+				if (!signal.aborted) yield {
+					error: network,
+					type: "error"
+				};
+				return;
+			}
+			if (!response.ok || !response.headers.has(VERSION_HEADER) || response.body === null) {
+				yield {
+					error: await replyError(response),
+					type: "error"
+				};
+				return;
+			}
+			const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+			let buffer = "";
+			let ended = false;
+			try {
+				for (;;) {
+					const chunk = await reader.read();
+					if (chunk.done) {
+						if (!ended && !signal.aborted) yield {
+							error: network,
+							type: "error"
+						};
+						return;
+					}
+					buffer += chunk.value;
+					let end = buffer.indexOf("\n\n");
+					while (end !== -1) {
+						const frame = buffer.slice(0, end);
+						buffer = buffer.slice(end + 2);
+						const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+						const event = data === "" ? null : parseSessionEvent(data);
+						if (event !== null) {
+							ended ||= event.type !== "program";
+							yield event;
+						}
+						end = buffer.indexOf("\n\n");
+					}
+				}
+			} catch {
+				if (!signal.aborted) yield {
+					error: network,
+					type: "error"
+				};
+			} finally {
+				reader.releaseLock();
+			}
+		}
+	};
+}
+function parseRequiresAction(value) {
+	return typeof value === "object" && value !== null && "message" in value && "token" in value && typeof value.message === "string" && typeof value.token === "string" ? {
+		message: value.message,
+		token: value.token
+	} : null;
+}
+/** The `{ code, message }` of anything a transport rejected with. */
+function errorDataOf(cause) {
+	return thrownErrorData(cause) ?? unavailable;
+}
+/** The `{ code, message }` that `cause` carries, or null. */
+function thrownErrorData(cause) {
+	return typeof cause === "object" && cause !== null ? parseErrorData({
+		code: "code" in cause ? cause.code : void 0,
+		message: "message" in cause ? cause.message : void 0
+	}) : null;
+}
+//#endregion
+export { TransportError, errorDataOf, httpTransport };

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,31 @@
 {
   "name": "@jigs.design/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "createPickleClient: the browser's transport and query cache. No React.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tanstack/query-core": "5.104.4",
+    "@jigs.design/runtime": "0.1.1"
+  }
 }