@jigs.design/react 0.1.0 → 0.1.2

package/README.md

@@ -1,19 +1,19 @@
 # @jigs.design/react
 
-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.
+The web renderer. `JigsView` runs a compiled program in a sandboxed frame and draws it with your registry. `useJigsSession` 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";
+import { JigsView, useJigsSession } from "@jigs.design/react";
+import { client } from "./jigs-client";
 
 export function App() {
-	const session = usePickleSession(client);
+	const session = useJigsSession(client);
 	return (
 		<>
 			<button onClick={() => session.send("My open orders")}>Ask</button>
 			{session.program && (
-				<PickleView
+				<JigsView
 					client={client}
 					components={components}
 					documentId={session.documentId}
@@ -25,28 +25,29 @@ export function App() {
 }
 ```
 
-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.
+The program runs in a worker inside a frame served by your Jigs 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 jig 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                                                                      |
+| Export                        | What it is                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `JigsView`                    | Runs one program and draws it. Takes `client`, `components`, `program`, `onAction`, `showIssues`, `allowAutoFocus`       |
+| `useJigsSession`              | 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     |
+| `useLocalValue`, `controlled` | For a controlled control: a local copy of the program's value that runs ahead of the round trip and drops a refused edit |
+| `Registry`, `RegistryFor`     | The type of a map from catalog names to React components                                                                 |
+| `SessionState`, `JigsSession` | The session's state and the hook's return value                                                                          |
+| `ViewIssue`                   | What `onIssue` receives                                                                                                  |
 
-It re-exports the shared types from `@jigs.design/runtime`.
+It re-exports the shared types from `@jigs.design/runtime`. The frame, its messages and the calls through the client are `createViewController` in `@jigs.design/client`, which `JigsView` is built on; a renderer for another framework starts there.
 
 ## 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/JigsView.tsx`: the view component, on the client's view controller.
 - `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.
+- `src/view/local-value.ts`: `useLocalValue` and `controlled`, for controls.
+- `src/view/session.ts`, `src/view/useJigsSession.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).
+[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), [Renderers](../../apps/docs/docs/renderers/index.mdx).

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { ViewIssue } from "./view/controller.js";
+import { controlled, useLocalValue } from "./view/local-value.js";
 import { Registry, RegistryFor } from "./view/registry.js";
-import { PickleView } from "./view/PickleView.js";
+import { JigsView } from "./view/JigsView.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 };
+import { JigsSession, useJigsSession } from "./view/useJigsSession.js";
+import { ConfirmFunction, ViewIssue } from "@jigs.design/client";
+import { Diagnostic, JigsErrorCode, JigsErrorData, Message, Program, SessionEvent, SessionOptions, Span } from "@jigs.design/runtime";
+export { type ConfirmFunction, type Diagnostic, type JigsErrorCode, type JigsErrorData, type JigsSession, JigsView, type Message, type Program, type Registry, type RegistryFor, type SessionEvent, type SessionOptions, type SessionState, type Span, type ViewIssue, controlled, useHandlerSettled, useJigsSession, useLocalValue };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { useHandlerSettled } from "./view/settled.js";
-import { PickleView } from "./view/PickleView.js";
-import { usePickleSession } from "./view/usePickleSession.js";
-export { PickleView, useHandlerSettled, usePickleSession };
+import { controlled, useLocalValue } from "./view/local-value.js";
+import { JigsView } from "./view/JigsView.js";
+import { useJigsSession } from "./view/useJigsSession.js";
+export { JigsView, controlled, useHandlerSettled, useJigsSession, useLocalValue };

package/dist/view/{PickleView.d.ts → JigsView.d.ts}

@@ -1,8 +1,7 @@
-import { ViewIssue } from "./controller.js";
 import { Registry } from "./registry.js";
+import { ConfirmFunction, JigsClient, ViewIssue } from "@jigs.design/client";
 import { Program } from "@jigs.design/runtime";
-import { ConfirmFunction, PickleClient } from "@jigs.design/client";
-//#region src/view/PickleView.d.ts
+//#region src/view/JigsView.d.ts
 /** An action as `onAction` receives it; type it with `ActionEvent<typeof host>`. */
 interface ActionLike {
   input: unknown;
@@ -14,14 +13,14 @@ interface ActionLike {
  * 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: {
+export declare function JigsView<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;
+  client: JigsClient;
   components: Registry;
   /**
    * Which UI `program` is a version of. When it changes, the program starts

package/dist/view/{PickleView.js → JigsView.js}

@@ -1,12 +1,9 @@
-import { createViewController } from "./controller.js";
 import { SettledContext } from "./settled.js";
-import { ROOT_ID } from "@jigs.design/runtime";
 import { useEffect, useState, useSyncExternalStore } from "react";
+import { createViewController, missingComponents } from "@jigs.design/client";
+import { ROOT_ID } from "@jigs.design/runtime";
 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");
+//#region src/view/JigsView.tsx
 function TreeNodeView(props) {
 	const { components, controller } = props;
 	const getNode = () => controller.store.get(props.id);
@@ -24,21 +21,7 @@ function TreeNodeView(props) {
 	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;
-	}
+	const drawn = controller.drawnProps(node, { allowAutoFocus: props.allowAutoFocus });
 	return /* @__PURE__ */ jsx(SettledContext, {
 		value: settled,
 		children: /* @__PURE__ */ jsx(registered, {
@@ -47,16 +30,14 @@ function TreeNodeView(props) {
 		})
 	});
 }
-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`);
-}
+const missingFromRegistry = (program, components) => missingComponents(program, Object.keys(components));
 /**
 * 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) {
+function JigsView(props) {
 	const { program } = props;
 	const [view, setView] = useState(() => ({
 		client: props.client,
@@ -111,15 +92,15 @@ function PickleView(props) {
 			id: ROOT_ID
 		}),
 		showIssues && status.notice !== null && /* @__PURE__ */ jsx("p", {
-			className: "pickle-view-notice",
+			className: "jigs-view-notice",
 			role: "status",
 			children: status.notice
 		}),
 		errors.length + issues.length > 0 && /* @__PURE__ */ jsxs("ul", {
-			className: "pickle-view-errors",
+			className: "jigs-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 };
+export { JigsView };

package/dist/view/local-value.d.ts

@@ -0,0 +1,19 @@
+//#region src/view/local-value.d.ts
+/**
+ * Whether the program controls a control's value: it sets the value prop
+ * (`value`, or `checked`) and handles `onChange`. A control with only
+ * `onChange` is uncontrolled, like a React input without `value`: the
+ * program hears each edit but the control keeps what the user did.
+ */
+export declare const controlled: <T>(value: T | undefined, onChange: ((next: T) => void) | undefined) => boolean;
+/**
+ * A local copy of a value the program owns, so a control can run ahead of the
+ * round trip to the sandbox. Pass `echoes` when the program controls the
+ * value (`controlled`): echoes of the edits sent to it then don't reset the
+ * control, but any other new value does, and so does an edit the program did
+ * not take: once it has answered every call (`useHandlerSettled`) and `value`
+ * is still not the edit, the control goes back to `value`. Without `echoes`,
+ * the control keeps its own state until `value` changes.
+ */
+export declare function useLocalValue<T>(value: T, echoes: boolean): [T, (next: T) => void];
+//#endregion

package/dist/view/local-value.js

@@ -0,0 +1,47 @@
+import { useHandlerSettled } from "./settled.js";
+import { useState } from "react";
+//#region src/view/local-value.ts
+/**
+* Whether the program controls a control's value: it sets the value prop
+* (`value`, or `checked`) and handles `onChange`. A control with only
+* `onChange` is uncontrolled, like a React input without `value`: the
+* program hears each edit but the control keeps what the user did.
+*/
+const controlled = (value, onChange) => value !== void 0 && onChange !== void 0;
+/**
+* A local copy of a value the program owns, so a control can run ahead of the
+* round trip to the sandbox. Pass `echoes` when the program controls the
+* value (`controlled`): echoes of the edits sent to it then don't reset the
+* control, but any other new value does, and so does an edit the program did
+* not take: once it has answered every call (`useHandlerSettled`) and `value`
+* is still not the edit, the control goes back to `value`. Without `echoes`,
+* the control keeps its own state until `value` changes.
+*/
+function useLocalValue(value, echoes) {
+	const settled = useHandlerSettled();
+	const [local, setLocal] = useState(value);
+	const [seen, setSeen] = useState(value);
+	const [seenSettled, setSeenSettled] = useState(settled);
+	const [pending, setPending] = useState([]);
+	if (!Object.is(value, seen)) {
+		setSeen(value);
+		const echo = pending.findIndex((sent) => Object.is(sent, value));
+		if (echo === -1) {
+			setLocal(value);
+			setPending([]);
+		} else setPending(pending.slice(echo + 1));
+	} else if (settled !== seenSettled) {
+		setSeenSettled(settled);
+		if (pending.length > 0) {
+			setLocal(value);
+			setPending([]);
+		}
+	}
+	const edit = (next) => {
+		setLocal(next);
+		if (echoes) setPending([...pending.slice(-20), next]);
+	};
+	return [local, edit];
+}
+//#endregion
+export { controlled, useLocalValue };

package/dist/view/session.d.ts

@@ -1,5 +1,5 @@
-import { Diagnostic, Message, PickleErrorData, Program, SessionOptions } from "@jigs.design/runtime";
-import { PickleClient } from "@jigs.design/client";
+import { JigsClient } from "@jigs.design/client";
+import { Diagnostic, JigsErrorData, Message, Program, SessionOptions } from "@jigs.design/runtime";
 //#region src/view/session.d.ts
 export interface SessionState {
   diagnostics: ReadonlyArray<Diagnostic>;
@@ -7,11 +7,11 @@ export interface SessionState {
    * 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.
+   * `JigsView` as `documentId`, so a new UI starts from fresh state.
    */
   documentId: number;
   /** `{ code, message }` when `status` is "error". */
-  error: PickleErrorData | null;
+  error: JigsErrorData | 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. */

package/dist/view/settled.d.ts

@@ -5,7 +5,7 @@
  * 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`.
+ * Always 0 outside `JigsView`.
  */
 export declare function useHandlerSettled(): number;
 //#endregion

package/dist/view/settled.js

@@ -8,7 +8,7 @@ const SettledContext = createContext(0);
 * 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`.
+* Always 0 outside `JigsView`.
 */
 function useHandlerSettled() {
 	return useContext(SettledContext);

package/dist/view/{usePickleSession.d.ts → useJigsSession.d.ts}

@@ -1,8 +1,8 @@
 import { SessionState } from "./session.js";
+import { JigsClient } from "@jigs.design/client";
 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 {
+//#region src/view/useJigsSession.d.ts
+export interface JigsSession<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
@@ -25,7 +25,7 @@ export interface PickleSession<TOptions extends SessionOptions = SessionOptions>
  * 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?: {
+export declare function useJigsSession<TOptions extends SessionOptions = SessionOptions>(client: JigsClient, options?: {
   initialMessages?: ReadonlyArray<Message>;
-}): PickleSession<TOptions>;
+}): JigsSession<TOptions>;
 //#endregion

package/dist/view/{usePickleSession.js → useJigsSession.js}

@@ -1,6 +1,6 @@
 import { createSessionStore } from "./session.js";
 import { useEffect, useState, useSyncExternalStore } from "react";
-//#region src/view/usePickleSession.ts
+//#region src/view/useJigsSession.ts
 const NO_MESSAGES = [];
 /**
 * Holds a conversation with the server and its latest program. Pass
@@ -10,7 +10,7 @@ const NO_MESSAGES = [];
 * 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) {
+function useJigsSession(client, options) {
 	const [store] = useState(() => createSessionStore(client, options?.initialMessages ?? NO_MESSAGES));
 	const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
 	useEffect(() => {
@@ -26,4 +26,4 @@ function usePickleSession(client, options) {
 	};
 }
 //#endregion
-export { usePickleSession };
+export { useJigsSession };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@jigs.design/react",
-  "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.",
+  "version": "0.1.2",
+  "description": "The web renderer: JigsView runs a compiled program in a sandbox and draws it with your registry; useJigsSession streams programs from the server.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "url": "git+https://github.com/yoamomonstruos/jigs.git",
     "directory": "packages/react"
   },
   "type": "module",
@@ -25,8 +25,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/runtime": "0.1.0",
-    "@jigs.design/client": "0.1.0"
+    "@jigs.design/client": "0.1.2",
+    "@jigs.design/runtime": "0.1.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"

package/dist/view/controller.d.ts

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

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

@@ -1,32 +0,0 @@
-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 };