@jigs.design/react 0.0.0-stage → 0.1.0

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,52 @@
-# Temporary Holding Version
+# @jigs.design/react
 
-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.
+The web renderer. `PickleView` runs a compiled program in a sandboxed frame and draws it with your registry. `usePickleSession` holds a conversation with the server and streams its latest program.
+
+```tsx
+import { components } from "@jigs.design/catalog/react";
+import { PickleView, usePickleSession } from "@jigs.design/react";
+import { client } from "./pickle-client";
+
+export function App() {
+	const session = usePickleSession(client);
+	return (
+		<>
+			<button onClick={() => session.send("My open orders")}>Ask</button>
+			{session.program && (
+				<PickleView
+					client={client}
+					components={components}
+					documentId={session.documentId}
+					program={session.program}
+				/>
+			)}
+		</>
+	);
+}
+```
+
+The program runs in a worker inside a frame served by your Pickle route. The frame has no network: queries and mutations go through the client, and every prop is checked against the program's schema before it reaches your component. A new `program` replaces the running one and keeps the state it still declares. `onAction` handles the program's actions after the server checked their input. The view drops an `autoFocus` prop unless you pass `allowAutoFocus`, so a pickle streaming into a chat cannot take the focus. It checks what the worker asks for against the program, since the worker is not trusted.
+
+## Exports
+
+| Export                          | What it is                                                                                                           |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `PickleView`                    | Runs one program and draws it. Takes `client`, `components`, `program`, `onAction`, `showIssues`, `allowAutoFocus`   |
+| `usePickleSession`              | The conversation and its latest program. `initialMessages` resumes one                                               |
+| `useHandlerSettled`             | For a registry control: changes once the program has answered its events, so it can drop an edit the program refused |
+| `Registry`, `RegistryFor`       | The type of a map from catalog names to React components                                                             |
+| `SessionState`, `PickleSession` | The session's state and the hook's return value                                                                      |
+
+It re-exports the shared types from `@jigs.design/runtime`.
+
+## Source
+
+- `src/view/PickleView.tsx`: the view component.
+- `src/view/controller.ts`: the frame, its messages, 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/registry.ts`, `src/view/settled.ts`: the registry types and `useHandlerSettled`.
+- `src/view/session.ts`, `src/view/usePickleSession.ts`: the session store and its hook.
+
+## Docs
+
+[React](../../apps/docs/docs/react/index.mdx), [Registry](../../apps/docs/docs/react/registry.mdx), [Sandbox](../../apps/docs/docs/react/sandbox.mdx), [Session](../../apps/docs/docs/running/session.mdx).

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { ViewIssue } from "./view/controller.js";
+import { Registry, RegistryFor } from "./view/registry.js";
+import { PickleView } from "./view/PickleView.js";
+import { useHandlerSettled } from "./view/settled.js";
+import { SessionState } from "./view/session.js";
+import { PickleSession, usePickleSession } from "./view/usePickleSession.js";
+import { Diagnostic, Message, PickleErrorCode, PickleErrorData, Program, SessionEvent, SessionOptions, Span } from "@jigs.design/runtime";
+import { ConfirmFunction } from "@jigs.design/client";
+export { type ConfirmFunction, type Diagnostic, type Message, type PickleErrorCode, type PickleErrorData, type PickleSession, PickleView, type Program, type Registry, type RegistryFor, type SessionEvent, type SessionOptions, type SessionState, type Span, type ViewIssue, useHandlerSettled, usePickleSession };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { useHandlerSettled } from "./view/settled.js";
+import { PickleView } from "./view/PickleView.js";
+import { usePickleSession } from "./view/usePickleSession.js";
+export { PickleView, useHandlerSettled, usePickleSession };

package/dist/view/PickleView.d.ts

@@ -0,0 +1,64 @@
+import { ViewIssue } from "./controller.js";
+import { Registry } from "./registry.js";
+import { Program } from "@jigs.design/runtime";
+import { ConfirmFunction, PickleClient } from "@jigs.design/client";
+//#region src/view/PickleView.d.ts
+/** An action as `onAction` receives it; type it with `ActionEvent<typeof host>`. */
+interface ActionLike {
+  input: unknown;
+  name: string;
+}
+/**
+ * Runs one program in the sandbox and draws it with `components`. A new
+ * `program` replaces the running one; state the new program still declares
+ * keeps its value, unless `documentId` changed with it. A new `client`
+ * starts the program over on that client.
+ */
+export declare function PickleView<TAction extends ActionLike = ActionLike>(props: {
+  /**
+   * Let the program focus a control when it appears, through the
+   * `autoFocus` prop. Default false: in a chat, a UI that streams in would
+   * otherwise take the focus from the composer while the user types.
+   */
+  allowAutoFocus?: boolean;
+  client: PickleClient;
+  components: Registry;
+  /**
+   * Which UI `program` is a version of. When it changes, the program starts
+   * from fresh state instead of keeping the state of the one before. Pass
+   * `session.documentId`, which changes when the model writes a new UI
+   * rather than editing the last one. Leave it out to keep state across
+   * every program, as for edits.
+   */
+  documentId?: number | string;
+  /**
+   * Handles the program's actions, after the server checked their input.
+   * What it returns, awaited and copied with `structuredClone`, is the
+   * handle's `data`; what it throws is its `error`. Without it, every
+   * action fails. It is not called once the view has unmounted.
+   */
+  onAction?: (action: TAction) => unknown;
+  /**
+   * Asks the user to approve a mutation whose policy is "confirm", with the
+   * host's `message`, in the page's own UI: the sandboxed program never
+   * draws or answers it. Resolve true to run the mutation; false, or a
+   * throw, fails it with `DECLINED`. Without it, the client's `confirm` asks.
+   */
+  onConfirm?: ConfirmFunction;
+  /**
+   * Called once for each new issue: a runtime error, something the view
+   * dropped, or a sandbox notice. An issue that persists is reported once;
+   * one that clears and comes back, again. It runs whether or not
+   * `showIssues` is on, so an app can count issues where users don't see
+   * them.
+   */
+  onIssue?: (issue: ViewIssue) => void;
+  program: Program;
+  /**
+   * List runtime errors, dropped props and sandbox notices under the tree.
+   * Default true; turn it off where end users should not see them.
+   */
+  showIssues?: boolean;
+}): import("react").JSX.Element;
+//#endregion
+export {};

package/dist/view/PickleView.js

@@ -0,0 +1,125 @@
+import { createViewController } from "./controller.js";
+import { SettledContext } from "./settled.js";
+import { ROOT_ID } from "@jigs.design/runtime";
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/view/PickleView.tsx
+/** 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");
+function TreeNodeView(props) {
+	const { components, controller } = props;
+	const getNode = () => controller.store.get(props.id);
+	const node = useSyncExternalStore(controller.subscribe, getNode, getNode);
+	const getSettled = () => controller.getSettled(props.id);
+	const settled = useSyncExternalStore(controller.subscribe, getSettled, getSettled);
+	if (node === void 0) return null;
+	if (node.type === "#text") return node.text;
+	const children = node.children.map((child) => /* @__PURE__ */ jsx(TreeNodeView, {
+		allowAutoFocus: props.allowAutoFocus,
+		components,
+		controller,
+		id: child
+	}, child));
+	if (node.type === "#root") return children;
+	const registered = Object.hasOwn(components, node.type) ? components[node.type] : void 0;
+	if (registered === void 0) return null;
+	const drawn = {};
+	for (const [name, value] of Object.entries(node.props)) {
+		if (name === AUTO_FOCUS && !props.allowAutoFocus) continue;
+		const kind = controller.propKind(node.type, name);
+		if (kind === "handler") {
+			if (typeof value === "object" && "fn" in value) {
+				const fn = value.fn;
+				drawn[name] = (...args) => {
+					controller.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 /* @__PURE__ */ jsx(SettledContext, {
+		value: settled,
+		children: /* @__PURE__ */ jsx(registered, {
+			...drawn,
+			children: controller.childrenAllowed(node.type) && children.length > 0 ? children : void 0
+		})
+	});
+}
+function missingFromRegistry(program, components) {
+	return Object.keys(program.components).filter((name) => !Object.hasOwn(components, name)).map((name) => `<${name}> is not in the registry, so it renders nothing`);
+}
+/**
+* Runs one program in the sandbox and draws it with `components`. A new
+* `program` replaces the running one; state the new program still declares
+* keeps its value, unless `documentId` changed with it. A new `client`
+* starts the program over on that client.
+*/
+function PickleView(props) {
+	const { program } = props;
+	const [view, setView] = useState(() => ({
+		client: props.client,
+		controller: createViewController(props.client)
+	}));
+	let { controller } = view;
+	if (view.client !== props.client) {
+		controller = createViewController(props.client);
+		setView({
+			client: props.client,
+			controller
+		});
+	}
+	const status = useSyncExternalStore(controller.subscribe, controller.getStatus, controller.getStatus);
+	useEffect(() => {
+		controller.setIssueHandler(props.onIssue);
+	}, [controller, props.onIssue]);
+	useEffect(() => {
+		controller.start();
+		return () => controller.stop();
+	}, [controller]);
+	useEffect(() => {
+		controller.setUnregistered(missingFromRegistry(program, props.components));
+	}, [
+		controller,
+		program,
+		props.components
+	]);
+	useEffect(() => {
+		const handler = props.onAction;
+		controller.setActionHandler(handler);
+	}, [controller, props.onAction]);
+	useEffect(() => {
+		controller.setConfirmHandler(props.onConfirm);
+	}, [controller, props.onConfirm]);
+	const documentId = props.documentId;
+	useEffect(() => {
+		controller.load(program, documentId);
+	}, [
+		controller,
+		program,
+		documentId
+	]);
+	const showIssues = props.showIssues ?? true;
+	const issues = showIssues ? [...missingFromRegistry(program, props.components), ...status.issues] : [];
+	const errors = showIssues ? status.errors : [];
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx(TreeNodeView, {
+			allowAutoFocus: props.allowAutoFocus === true,
+			components: props.components,
+			controller,
+			id: ROOT_ID
+		}),
+		showIssues && status.notice !== null && /* @__PURE__ */ jsx("p", {
+			className: "pickle-view-notice",
+			role: "status",
+			children: status.notice
+		}),
+		errors.length + issues.length > 0 && /* @__PURE__ */ jsxs("ul", {
+			className: "pickle-view-errors",
+			children: [errors.map((error, index) => /* @__PURE__ */ jsxs("li", { children: [error.line === null ? "" : `Line ${error.line}: `, error.message] }, `error:${index}:${error.message}`)), issues.map((issue) => /* @__PURE__ */ jsx("li", { children: issue }, `issue:${issue}`))]
+		})
+	] });
+}
+//#endregion
+export { PickleView };

package/dist/view/controller.d.ts

@@ -0,0 +1,22 @@
+import { Program } from "@jigs.design/runtime";
+import { ConfirmFunction, PickleClient } from "@jigs.design/client";
+//#region src/view/controller.d.ts
+/**
+ * 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;
+};
+//#endregion

package/dist/view/controller.js

@@ -0,0 +1,524 @@
+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;
+/**
+* The runtime's own limits, checked again here because the worker shares a
+* realm with the program: different requests a render may read, and
+* mutations one handler call may make.
+*/
+const MAX_QUERIES = 20;
+const MAX_MUTATIONS = 5;
+/** Runtime errors the view keeps from one result, and the length of each. */
+const MAX_ERRORS = 20;
+const MAX_ERROR_TEXT = 1e3;
+/**
+* Times a program may hang before the view stops restarting it. One that
+* hangs on its first render is not tried again; one that hangs later, on
+* data or a handler, gets one restart with fresh state.
+*/
+const MAX_HANGS = 2;
+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 >= MAX_ERRORS) 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 < MAX_ERRORS && !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 >= MAX_QUERIES) {
+				drop(`The sandbox read more than ${MAX_QUERIES} 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 > MAX_MUTATIONS) drop(`The sandbox asked for more than ${MAX_MUTATIONS} mutations at once`);
+		const started = generation;
+		for (const mutation of mutations.slice(0, MAX_MUTATIONS)) {
+			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 : MAX_HANGS);
+					if (before === 0) console.warn(`Pickle: ${WATCHDOG_NOTICE}`);
+				}
+				const usable = (candidate) => candidate !== null && (hangs.get(candidate) ?? 0) < MAX_HANGS;
+				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;
+			}
+		}
+	};
+	return {
+		call: (node, fn, args) => {
+			seq++;
+			calls.set(seq, node);
+			openCalls.set(node, (openCalls.get(node) ?? 0) + 1);
+			post({
+				args,
+				fn,
+				seq,
+				type: "call"
+			});
+		},
+		childrenAllowed: (type) => running !== null && Object.hasOwn(running.components, type) && running.components[type]?.children !== "none",
+		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: (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;
+		},
+		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 { createViewController };

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/dist/view/registry.d.ts

@@ -0,0 +1,21 @@
+import { ComponentType, ReactNode } from "react";
+//#region src/view/registry.d.ts
+/**
+ * One React component per catalog name. Props reach a component only after
+ * they passed the schema the program carries, so each component declares the
+ * props it reads; `never` lets any such component into the map.
+ */
+export type Registry = Readonly<Record<string, ComponentType<never>>>;
+/**
+ * A registry checked against a catalog's props: every name present, each
+ * component accepting what the catalog may pass. Use it with
+ * `CatalogProps` from `@jigs.design/host`:
+ *
+ * ```ts
+ * export const components = { … } satisfies RegistryFor<CatalogProps<typeof catalog>>;
+ * ```
+ */
+export type RegistryFor<TProps extends Readonly<Record<string, object>>> = { readonly [K in keyof TProps]: (props: TProps[K] & {
+  children?: ReactNode;
+}) => ReactNode; };
+//#endregion

package/dist/view/session.d.ts

@@ -0,0 +1,21 @@
+import { Diagnostic, Message, PickleErrorData, Program, SessionOptions } from "@jigs.design/runtime";
+import { PickleClient } from "@jigs.design/client";
+//#region src/view/session.d.ts
+export interface SessionState {
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /**
+   * Which UI `program` is a version of. It goes up when the model writes a
+   * new UI rather than editing the last one, or a stored one is restored,
+   * and goes back with the program when a turn is stopped. Pass it to
+   * `PickleView` as `documentId`, so a new UI starts from fresh state.
+   */
+  documentId: number;
+  /** `{ code, message }` when `status` is "error". */
+  error: PickleErrorData | null;
+  /** The conversation, to store or render. Assistant entries hold checked source. */
+  messages: ReadonlyArray<Message>;
+  /** The latest program, or null before the first one arrives. */
+  program: Program | null;
+  status: "error" | "idle" | "streaming";
+}
+//#endregion

package/dist/view/session.js

@@ -0,0 +1,141 @@
+//#region src/view/session.ts
+const endedEarly = {
+	code: "NETWORK",
+	message: "The turn ended before it finished."
+};
+/**
+* The conversation and the latest program for one chat. A turn that ends
+* without `done` leaves no trace: the messages and the program go back to
+* where they were before it started.
+*/
+function createSessionStore(initialClient, initialMessages) {
+	let client = initialClient;
+	const listeners = /* @__PURE__ */ new Set();
+	let committed = {
+		diagnostics: [],
+		documentId: 0,
+		messages: initialMessages,
+		program: null
+	};
+	let state = {
+		...committed,
+		error: null,
+		status: "idle"
+	};
+	let active = null;
+	const set = (next) => {
+		state = next;
+		for (const listener of listeners) listener();
+	};
+	const rollback = (error) => {
+		set({
+			...committed,
+			error,
+			status: error === null ? "idle" : "error"
+		});
+	};
+	const run = async (messages, options, turn) => {
+		const body = options === void 0 ? { messages } : {
+			messages,
+			options
+		};
+		try {
+			for await (const event of client.session(body, { signal: turn.signal })) {
+				if (turn !== active) return;
+				if (event.type === "program") {
+					set({
+						...state,
+						diagnostics: event.diagnostics,
+						documentId: event.fresh ? state.documentId + 1 : state.documentId,
+						program: event.program
+					});
+					continue;
+				}
+				if (event.type === "error") {
+					active = null;
+					rollback(event.error);
+					return;
+				}
+				const last = messages.at(-1);
+				committed = {
+					diagnostics: event.diagnostics,
+					documentId: state.documentId,
+					messages: last?.role === "assistant" ? messages : [...messages, {
+						content: event.source,
+						role: "assistant"
+					}],
+					program: state.program
+				};
+				active = null;
+				set({
+					...committed,
+					error: null,
+					status: "idle"
+				});
+				return;
+			}
+		} catch {}
+		if (turn === active) {
+			active = null;
+			rollback(endedEarly);
+		}
+	};
+	const begin = (messages, options) => {
+		const turn = new AbortController();
+		active = turn;
+		set({
+			...state,
+			error: null,
+			messages,
+			status: "streaming"
+		});
+		run(messages, options, turn);
+	};
+	const stop = () => {
+		if (active === null) return;
+		active.abort();
+		active = null;
+		rollback(null);
+	};
+	const resume = () => {
+		if (active === null && committed.messages.at(-1)?.role === "assistant") begin(committed.messages, void 0);
+	};
+	return {
+		getState: () => state,
+		reset: (messages = []) => {
+			stop();
+			committed = {
+				diagnostics: [],
+				documentId: committed.documentId,
+				messages,
+				program: null
+			};
+			set({
+				...committed,
+				error: null,
+				status: "idle"
+			});
+			resume();
+		},
+		resume,
+		send: (prompt, options) => {
+			stop();
+			begin([...committed.messages, {
+				content: prompt,
+				role: "user"
+			}], options);
+		},
+		setClient: (next) => {
+			client = next;
+		},
+		stop,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+//#endregion
+export { createSessionStore };

package/dist/view/settled.d.ts

@@ -0,0 +1,11 @@
+//#region src/view/settled.d.ts
+/**
+ * Counts the times the program finished answering every handler call of the
+ * component being drawn: it changes once the program has seen the
+ * component's latest events and its answer is on screen. A control that
+ * runs ahead of the program, such as a text field showing what was typed,
+ * can then go back to its value prop if the program kept another value.
+ * Always 0 outside `PickleView`.
+ */
+export declare function useHandlerSettled(): number;
+//#endregion

package/dist/view/settled.js

@@ -0,0 +1,17 @@
+import { createContext, useContext } from "react";
+//#region src/view/settled.ts
+/** How many times the node being drawn had all its handler calls answered. */
+const SettledContext = createContext(0);
+/**
+* Counts the times the program finished answering every handler call of the
+* component being drawn: it changes once the program has seen the
+* component's latest events and its answer is on screen. A control that
+* runs ahead of the program, such as a text field showing what was typed,
+* can then go back to its value prop if the program kept another value.
+* Always 0 outside `PickleView`.
+*/
+function useHandlerSettled() {
+	return useContext(SettledContext);
+}
+//#endregion
+export { SettledContext, useHandlerSettled };

package/dist/view/usePickleSession.d.ts

@@ -0,0 +1,31 @@
+import { SessionState } from "./session.js";
+import { Message, SessionOptions } from "@jigs.design/runtime";
+import { PickleClient } from "@jigs.design/client";
+//#region src/view/usePickleSession.d.ts
+export interface PickleSession<TOptions extends SessionOptions = SessionOptions> extends SessionState {
+  /**
+   * Stops any turn and starts over with `messages` (default none). Like
+   * `initialMessages`, messages that end with an assistant message are
+   * compiled again without calling the model.
+   */
+  reset: (messages?: ReadonlyArray<Message>) => void;
+  /**
+   * Starts a turn. A turn already streaming stops first. `options` go to the
+   * server's `options` schema; type them with the schema's input type.
+   */
+  send: (prompt: string, options?: TOptions) => void;
+  /** Aborts the turn in flight; the conversation goes back to before it. */
+  stop: () => void;
+}
+/**
+ * Holds a conversation with the server and its latest program. Pass
+ * `initialMessages` to resume a stored conversation: when they end with an
+ * assistant message, the server compiles it again without calling the model.
+ * `initialMessages` is read once, when the hook mounts; to load another
+ * conversation later, call `reset(messages)`. A new `client` stops the turn
+ * in flight and compiles the conversation's last answer again through it.
+ */
+export declare function usePickleSession<TOptions extends SessionOptions = SessionOptions>(client: PickleClient, options?: {
+  initialMessages?: ReadonlyArray<Message>;
+}): PickleSession<TOptions>;
+//#endregion

package/dist/view/usePickleSession.js

@@ -0,0 +1,29 @@
+import { createSessionStore } from "./session.js";
+import { useEffect, useState, useSyncExternalStore } from "react";
+//#region src/view/usePickleSession.ts
+const NO_MESSAGES = [];
+/**
+* Holds a conversation with the server and its latest program. Pass
+* `initialMessages` to resume a stored conversation: when they end with an
+* assistant message, the server compiles it again without calling the model.
+* `initialMessages` is read once, when the hook mounts; to load another
+* conversation later, call `reset(messages)`. A new `client` stops the turn
+* in flight and compiles the conversation's last answer again through it.
+*/
+function usePickleSession(client, options) {
+	const [store] = useState(() => createSessionStore(client, options?.initialMessages ?? NO_MESSAGES));
+	const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+	useEffect(() => {
+		store.setClient(client);
+		store.resume();
+		return () => store.stop();
+	}, [store, client]);
+	return {
+		...state,
+		reset: store.reset,
+		send: store.send,
+		stop: store.stop
+	};
+}
+//#endregion
+export { usePickleSession };

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@jigs.design/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The web renderer: PickleView runs a compiled program in a sandbox and draws it with your registry; usePickleSession streams programs from the server.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jigs.design/runtime": "0.1.0",
+    "@jigs.design/client": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
 }