@jigs.design/client 0.2.0 → 0.3.1

package/README.md

@@ -8,13 +8,13 @@ import { createJigsClient } from "@jigs.design/client";
 export const client = createJigsClient({ endpoint: "/api/jigs" });
 ```
 
-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.
+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. Pages' programs sit in a second cache, keyed by name and props, so a page and a query may share a name. The client retries network failures, aborts a query's request when nothing reads it any more, and refreshes the queries a mutation invalidates. When the server has `events`, it opens the push stream while anything is observed and refetches the queries and pages an event names.
 
 ## Exports
 
 | Export                                           | What it is                                                                                                                                       |
 | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `createJigsClient`                               | The client, with `observe`, `mutate`, `invalidate` and `session`                                                                                 |
+| `createJigsClient`                               | The client, with `observe`, `mutate`, `invalidate`, `session`, and `page`, `observePage` and `invalidatePage` for pages                          |
 | `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 |

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { HeadersOption, Transport } from "./transport.js";
-import { Message, MutationResult, QueryResult, SessionEvent, SessionOptions } from "@jigs.design/protocol";
+import { Diagnostic, JigsErrorData, MutationResult, PageProps, Program, QueryResult, SessionBody, SessionEvent } from "@jigs.design/protocol";
 //#region src/client.d.ts
 interface CacheOptions {
   /**
@@ -46,11 +46,46 @@ export type ClientOptions = CacheOptions & ConfirmOptions & ({
   headers?: never;
   transport: Transport;
 });
+/** A page's program and its diagnostics, as the server compiled them. */
+export interface PageData {
+  /**
+   * A saved page is compiled leniently, so these may hold errors: show a
+   * notice beside the program when one is an error or a warning.
+   */
+  diagnostics: ReadonlyArray<Diagnostic>;
+  program: Program;
+}
+/** A page as `observePage` reports it. */
+export interface PageResult {
+  /** The program's diagnostics; empty until one arrives. */
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /** `{ code, message }` when `status` is "error". */
+  error: JigsErrorData | null;
+  /**
+   * The latest program, or null before the first one. A refetch that fails
+   * keeps the last program here, beside the error.
+   */
+  program: Program | null;
+  status: "error" | "pending" | "success";
+}
 export interface JigsClient {
   /** URL of the sandbox frame document. */
   readonly frame: string;
+  /**
+   * Keeps the push channel from closing until the returned function is
+   * called; it does not open one. A view holds it from `start` to `stop`,
+   * so a program that reads no query for a while, as one still streaming
+   * may, does not close and reopen the stream.
+   */
+  hold: () => () => void;
   /** Refetches every query with this name, for every input. */
   invalidate: (name: string) => Promise<void>;
+  /**
+   * Drops the cached program of page `name`: of every props, or of the
+   * props that contain `props`, as a query's input matches. Pages on
+   * screen refetch; the rest fetch when next observed.
+   */
+  invalidatePage: (name: string, props?: PageProps) => Promise<void>;
   /**
    * Runs one mutation or action and, when it succeeds, refetches the
    * queries the server says it refreshed. A reply without that list
@@ -74,11 +109,25 @@ export interface JigsClient {
    * `kind: "query"`.
    */
   observe: (name: string, input: unknown, listener: (result: QueryResult) => void) => () => void;
+  /**
+   * Keeps one page subscribed and reports every result, as `observe` does
+   * for a query. `initial` is a program the page already has, such as one a
+   * loader rendered: it fills the cache, so it is not fetched again on
+   * mount. Pages are cached by name and props until `invalidatePage` or a
+   * reply from a server of another version.
+   */
+  observePage: (name: string, props: PageProps | undefined, listener: (result: PageResult) => void, options?: {
+    initial?: PageData | undefined;
+  }) => () => void;
+  /**
+   * A page's program by name, from the cache when it holds one, else
+   * through `POST { type: "page" }`. Rejects with the transport's error.
+   */
+  page: (name: string, props?: PageProps, options?: {
+    signal?: AbortSignal;
+  }) => Promise<PageData>;
   /** One turn, as session events. */
-  session: (body: {
-    messages: ReadonlyArray<Message>;
-    options?: SessionOptions;
-  }, options: {
+  session: (body: SessionBody, options: {
     signal: AbortSignal;
   }) => AsyncIterable<SessionEvent>;
 }

package/dist/client.js

@@ -1,10 +1,95 @@
 import { TransportError, errorDataOf, httpTransport } from "./transport.js";
-import { QueryClient, QueryObserver } from "@tanstack/query-core";
+import { QueryClient, QueryObserver, hashKey } 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;
+/**
+* How long the push channel stays open once nothing observes or holds it:
+* a view that remounts, or a block that becomes another, subscribes again
+* well within it.
+*/
+const CHANNEL_LINGER_MS = 1e3;
+/** When a channel the server refused or ended is tried again, with queries still observed. */
+const CHANNEL_REOPEN_MS = 3e5;
+/** The refetch after a gap in the channel waits up to this long, so tabs do not all hit the server at once. */
+const GAP_SPREAD_MS = 2e3;
+/**
+* The push channel: opened by the first query or page observed, kept open
+* while any is observed or a view holds it, and its events applied to the
+* cache. It refetches everything on screen only after a gap
+* it cannot account for: a connection lost without a `close` event, to a
+* server that did not replay what it missed.
+*/
+function createChannel(transport, handlers) {
+	let observers = 0;
+	/** Views mounted: they keep an open channel open, but do not open one. */
+	let holds = 0;
+	let running = null;
+	let linger;
+	let reopen;
+	const consume = async (events, signal) => {
+		let first = true;
+		let closed = false;
+		try {
+			for await (const event of events) if (event.type === "invalidate") handlers.apply(event.invalidate);
+			else if (event.type === "invalidate-pages") handlers.applyPages(event.pages);
+			else if (event.type === "close") closed = true;
+			else if (event.type === "open") {
+				if (!first && !closed && !event.replayed) setTimeout(handlers.refetchActive, Math.random() * GAP_SPREAD_MS);
+				first = false;
+				closed = false;
+			} else if (event.type === "version") handlers.version(event.version);
+		} catch {}
+		if (signal.aborted) return;
+		running = null;
+		clearTimeout(reopen);
+		reopen = setTimeout(() => {
+			if (observers > 0 && running === null) open();
+		}, CHANNEL_REOPEN_MS);
+	};
+	const open = () => {
+		if (transport.events === void 0) return;
+		clearTimeout(reopen);
+		const controller = new AbortController();
+		running = controller;
+		consume(transport.events({ signal: controller.signal }), controller.signal);
+	};
+	/** Closes the channel after the linger, once nothing observes or holds it. */
+	const closeWhenIdle = () => {
+		if (observers > 0 || holds > 0) return;
+		clearTimeout(linger);
+		linger = setTimeout(() => {
+			clearTimeout(reopen);
+			running?.abort();
+			running = null;
+		}, CHANNEL_LINGER_MS);
+	};
+	return {
+		hold: () => {
+			holds += 1;
+			clearTimeout(linger);
+			let held = true;
+			return () => {
+				if (held) {
+					held = false;
+					holds -= 1;
+					closeWhenIdle();
+				}
+			};
+		},
+		release: () => {
+			observers -= 1;
+			closeWhenIdle();
+		},
+		retain: () => {
+			observers += 1;
+			clearTimeout(linger);
+			if (running === null) open();
+		}
+	};
+}
 function toQueryResult(result) {
 	if (result.status === "success") return {
 		data: result.data,
@@ -22,6 +107,18 @@ function toQueryResult(result) {
 		status: "pending"
 	};
 }
+/** A page's key in the program cache: its name, then its props. */
+function pageKey(name, props) {
+	return [name, props ?? {}];
+}
+function toPageResult(result) {
+	return {
+		diagnostics: result.data?.diagnostics ?? [],
+		error: result.status === "error" ? errorDataOf(result.error) : null,
+		program: result.data?.program ?? null,
+		status: result.status
+	};
+}
 /**
 * The browser's connection to a Jigs server. Create one per app, in its
 * own module: each client has its own query cache, so two clients share no
@@ -39,9 +136,61 @@ function createJigsClient(options) {
 			staleTime: options.staleTime ?? DEFAULT_STALE_TIME
 		}
 	} });
+	const applyInvalidations = (targets) => {
+		for (const target of targets) queries.invalidateQueries({ queryKey: target.input === void 0 ? [target.name] : [target.name, target.input] });
+	};
+	const programs = new QueryClient({ defaultOptions: { queries: {
+		gcTime: 3e5,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		retry: (failures, error) => failures < MAX_RETRIES && RETRYABLE.has(errorDataOf(error).code),
+		staleTime: Number.POSITIVE_INFINITY
+	} } });
+	/** The server version the cached programs came from, once one is known. */
+	let programsVersion = null;
+	/**
+	* Notes the server's version. Programs a server of another version
+	* compiled are dropped, except `own`'s, the reply that told us: pages on
+	* screen refetch, and the rest go.
+	*/
+	const noteVersion = (version, own) => {
+		const previous = programsVersion;
+		programsVersion = version;
+		if (previous === null || previous === version) return;
+		const ownHash = own === void 0 ? null : hashKey(own);
+		const others = (query) => query.queryHash !== ownHash;
+		programs.removeQueries({ predicate: (query) => others(query) && query.getObserversCount() === 0 });
+		programs.invalidateQueries({ predicate: others });
+	};
+	const fetchPage = (name, props) => async (context) => {
+		const reply = await transport.page(props === void 0 || Object.keys(props).length === 0 ? { name } : {
+			name,
+			props
+		}, { signal: context.signal });
+		noteVersion(reply.version, pageKey(name, props));
+		return {
+			diagnostics: reply.diagnostics,
+			program: reply.program
+		};
+	};
+	/** Pages by name, or by name and the props they contain, as queries match. */
+	const invalidatePage = (name, props) => programs.invalidateQueries({ queryKey: props === void 0 ? [name] : [name, props] });
+	const channel = createChannel(transport, {
+		apply: applyInvalidations,
+		applyPages: (pages) => {
+			for (const page of pages) invalidatePage(page.name, page.props);
+		},
+		refetchActive: () => {
+			queries.invalidateQueries({ type: "active" });
+			programs.invalidateQueries({ type: "active" });
+		},
+		version: (version) => noteVersion(version)
+	});
 	return {
 		frame: transport.frame,
+		hold: channel.hold,
 		invalidate: (name) => queries.invalidateQueries({ queryKey: [name] }),
+		invalidatePage,
 		mutate: async (name, input, procedure) => {
 			const send = async (confirmation) => {
 				try {
@@ -81,8 +230,7 @@ function createJigsClient(options) {
 				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] });
+			applyInvalidations(reply.invalidate ?? procedure.invalidates.map((target) => ({ name: target })));
 			return {
 				data: reply.data,
 				status: "success"
@@ -104,8 +252,52 @@ function createJigsClient(options) {
 			const unsubscribe = observer.subscribe((result) => {
 				listener(toQueryResult(result));
 			});
+			channel.retain();
 			listener(toQueryResult(observer.getCurrentResult()));
-			return unsubscribe;
+			let subscribed = true;
+			return () => {
+				if (!subscribed) return;
+				subscribed = false;
+				unsubscribe();
+				channel.release();
+			};
+		},
+		observePage: (name, props, listener, observeOptions) => {
+			const initial = observeOptions?.initial;
+			const pageOptions = {
+				queryFn: fetchPage(name, props),
+				queryKey: pageKey(name, props)
+			};
+			if (initial !== void 0) {
+				pageOptions.initialData = initial;
+				pageOptions.initialDataUpdatedAt = Date.now();
+			}
+			const observer = new QueryObserver(programs, pageOptions);
+			const unsubscribe = observer.subscribe((result) => {
+				listener(toPageResult(result));
+			});
+			channel.retain();
+			listener(toPageResult(observer.getCurrentResult()));
+			let subscribed = true;
+			return () => {
+				if (!subscribed) return;
+				subscribed = false;
+				unsubscribe();
+				channel.release();
+			};
+		},
+		page: (name, props, pageOptions) => {
+			const fetched = programs.query({
+				queryFn: fetchPage(name, props),
+				queryKey: pageKey(name, props)
+			});
+			const signal = pageOptions?.signal;
+			if (signal === void 0) return fetched;
+			return Promise.race([fetched, new Promise((_resolve, reject) => {
+				const abort = () => reject(signal.reason);
+				if (signal.aborted) abort();
+				signal.addEventListener("abort", abort, { once: true });
+			})]);
 		},
 		session: (body, sessionOptions) => transport.session(body, sessionOptions)
 	};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { CallReply, HeadersOption, HttpTransportOptions, Transport, TransportError, httpTransport } from "./transport.js";
-import { ClientOptions, ConfirmFunction, JigsClient, createJigsClient } from "./client.js";
+import { ClientOptions, ConfirmFunction, JigsClient, PageData, PageResult, createJigsClient } from "./client.js";
 import { ActionCall, ActionHandler, ViewController, ViewIssue, ViewStatus, createViewController, missingComponents } from "./view/controller.js";
-import { Diagnostic, Invalidation, JigsErrorCode, JigsErrorData, Message, Program, SessionEvent, Severity, Span } from "@jigs.design/protocol";
-export { type ActionCall, type ActionHandler, type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type JigsClient, type JigsErrorCode, type JigsErrorData, type Message, type Program, type SessionEvent, type Severity, type Span, type Transport, TransportError, type ViewController, type ViewIssue, type ViewStatus, createJigsClient, createViewController, httpTransport, missingComponents };
+import { Diagnostic, Invalidation, JigsErrorCode, JigsErrorData, Message, PageProps, PageReply, Program, PushEvent, SessionBody, SessionEvent, Severity, Span } from "@jigs.design/protocol";
+export { type ActionCall, type ActionHandler, type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type JigsClient, type JigsErrorCode, type JigsErrorData, type Message, type PageData, type PageProps, type PageReply, type PageResult, type Program, type PushEvent, type SessionBody, type SessionEvent, type Severity, type Span, type Transport, TransportError, type ViewController, type ViewIssue, type ViewStatus, createJigsClient, createViewController, httpTransport, missingComponents };

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { Invalidation, JigsErrorCode, JigsErrorData, Message, ProcedureKind, SessionEvent, SessionOptions } from "@jigs.design/protocol";
+import { Invalidation, JigsErrorCode, JigsErrorData, PageProps, PageReply, ProcedureKind, PushEvent, SessionBody, SessionEvent } from "@jigs.design/protocol";
 //#region src/transport.d.ts
 /**
  * A call's reply: the procedure's data and, for a mutation, the queries the
@@ -32,14 +32,34 @@ export interface Transport {
   }, options: {
     signal: AbortSignal;
   }) => Promise<CallReply>;
+  /**
+   * Opens the push channel and yields its events until `signal` aborts.
+   * The transport owns the connection: it reconnects with backoff, resends
+   * the last event id, and yields `open` each time a connection is made
+   * (then `version`, when it knows the server's). It ends without an abort
+   * when the server has no channel or refuses it; the client asks again
+   * later. Never throws. Without it, the client has no push.
+   */
+  events?: (options: {
+    signal: AbortSignal;
+  }) => AsyncIterable<PushEvent>;
   /** 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;
+  /**
+   * A page's compiled program by name, with its diagnostics and the
+   * server's version. Rejects with a `TransportError`: `NOT_FOUND` for a
+   * page the server will not serve, `BAD_INPUT` for props it refuses. A
+   * transport that cannot fetch pages rejects with `UNAVAILABLE`.
+   */
+  page: (request: {
+    name: string;
+    props?: PageProps;
   }, options: {
     signal: AbortSignal;
+  }) => Promise<PageReply>;
+  /** Reports every failure as one `error` event and then ends; never throws. */
+  session: (body: SessionBody, options: {
+    signal: AbortSignal;
   }) => AsyncIterable<SessionEvent>;
 }
 /** A failure with a code the spec can read. */

package/dist/transport.js

@@ -1,4 +1,4 @@
-import { parseErrorData, parseInvalidations, parseSessionEvent } from "@jigs.design/protocol";
+import { parseErrorData, parseInvalidations, parsePageReply, parsePushEvent, parseSessionEvent } from "@jigs.design/protocol";
 //#region src/transport.ts
 /** A failure with a code the spec can read. */
 var TransportError = class extends Error {
@@ -15,6 +15,74 @@ const GATEWAY_STATUSES = /* @__PURE__ */ new Set([
 	503,
 	504
 ]);
+/**
+* Push stream answers a reconnect would not change: no channel (204), a
+* refusal (401, 403), or a server that does not know the route (404, 405).
+*/
+const FINAL_STREAM_STATUSES = /* @__PURE__ */ new Set([
+	204,
+	401,
+	403,
+	404,
+	405
+]);
+/** The reconnect delay until the server sends `retry:`, and the most it doubles to. */
+const RETRY_MS = 3e3;
+const MAX_RETRY_MS = 3e4;
+/** A connection that lived this long resets the doubling. */
+const STABLE_MS = 1e4;
+/**
+* The frames of a server-sent event stream, as they complete. Ends when
+* `signal` aborts, even if the body does not.
+*/
+async function* sseFrames(body, signal) {
+	const reader = body.pipeThrough(new TextDecoderStream()).getReader();
+	const stop = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal.addEventListener("abort", stop, { once: true });
+	let buffer = "";
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) return;
+			buffer += chunk.value;
+			let end = buffer.indexOf("\n\n");
+			while (end !== -1) {
+				const lines = buffer.slice(0, end).split("\n");
+				buffer = buffer.slice(end + 2);
+				const field = (name) => lines.filter((line) => line.startsWith(`${name}:`)).map((line) => line.slice(name.length + 1).trimStart());
+				const retry = Number(field("retry").at(-1) ?? "NaN");
+				yield {
+					data: field("data").join("\n"),
+					id: field("id").at(-1) ?? null,
+					retry: Number.isInteger(retry) && retry >= 0 ? retry : null
+				};
+				end = buffer.indexOf("\n\n");
+			}
+		}
+	} finally {
+		signal.removeEventListener("abort", stop);
+		await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+}
+/** Waits `ms`, or less when `signal` aborts. */
+function pause(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) {
+			resolve();
+			return;
+		}
+		const done = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		};
+		const timer = setTimeout(done, ms);
+		signal.addEventListener("abort", done, { once: true });
+	});
+}
 const unavailable = {
 	code: "UNAVAILABLE",
 	message: "The server is not available right now."
@@ -33,6 +101,17 @@ async function replyError(response) {
 		return unavailable;
 	}
 }
+/** A JSON reply's body, or the `TransportError` it carries. */
+async function replyBody(response) {
+	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);
+	}
+	return typeof body === "object" ? body : null;
+}
 /** Why the `headers` function failed, as the call's error. */
 function headersError(cause) {
 	return thrownErrorData(cause) ?? {
@@ -49,7 +128,7 @@ function httpTransport(options) {
 	* token refresh that failed, is not a network failure: it keeps a thrown
 	* `{ code, message }` and is otherwise `UNAUTHORIZED`, never retried.
 	*/
-	const headers = async () => {
+	const headers = async (contentType = "application/json") => {
 		let extra;
 		try {
 			extra = typeof options.headers === "function" ? await options.headers() : options.headers;
@@ -57,7 +136,7 @@ function httpTransport(options) {
 			throw new TransportError(headersError(error));
 		}
 		const merged = new Headers(extra);
-		merged.set("content-type", "application/json");
+		if (contentType !== null) merged.set("content-type", contentType);
 		return merged;
 	};
 	const post = (body, init, signal) => fetcher(options.endpoint, {
@@ -67,30 +146,26 @@ function httpTransport(options) {
 		method: "POST",
 		signal
 	});
+	/** Posts `body`; a fetch that fails without an abort is `NETWORK`. */
+	const send = async (body, signal) => {
+		const init = await headers();
+		try {
+			return await post(body, init, signal);
+		} catch (error) {
+			if (signal.aborted) throw error;
+			throw new TransportError(network);
+		}
+	};
 	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);
+			const body = await replyBody(await send(JSON.stringify({
+				confirmation: request.confirmation,
+				input: request.input,
+				kind: request.kind,
+				name: request.name,
+				type: "call"
+			}), callOptions.signal));
+			if (body === null) throw new TransportError(unavailable);
 			if ("requiresAction" in body) {
 				const requiresAction = parseRequiresAction(body.requiresAction);
 				if (requiresAction === null) throw new TransportError(unavailable);
@@ -105,7 +180,79 @@ function httpTransport(options) {
 				invalidate
 			};
 		},
+		async *events({ signal }) {
+			let lastId = null;
+			let retryMs = RETRY_MS;
+			let failures = 0;
+			while (!signal.aborted) {
+				let init;
+				try {
+					init = await headers(null);
+				} catch {
+					return;
+				}
+				init.set("accept", "text/event-stream");
+				const resumed = lastId !== null;
+				if (lastId !== null) init.set("last-event-id", lastId);
+				let response = null;
+				try {
+					response = await fetcher(options.endpoint, {
+						cache: "no-store",
+						credentials,
+						headers: init,
+						method: "GET",
+						signal
+					});
+				} catch {}
+				if (signal.aborted) return;
+				const type = response?.headers.get("content-type") ?? "";
+				if (response !== null && (FINAL_STREAM_STATUSES.has(response.status) || type.toLowerCase().startsWith("text/html"))) {
+					await response.body?.cancel().catch(() => void 0);
+					return;
+				}
+				const version = response?.headers.get(VERSION_HEADER) ?? null;
+				const opened = Date.now();
+				let closed = false;
+				if (response !== null && response.ok && version !== null && response.body !== null && type.toLowerCase().startsWith("text/event-stream")) {
+					yield {
+						replayed: resumed,
+						type: "open"
+					};
+					yield {
+						type: "version",
+						version
+					};
+					try {
+						for await (const frame of sseFrames(response.body, signal)) {
+							if (frame.retry !== null) retryMs = frame.retry;
+							if (frame.id !== null) lastId = frame.id === "" ? null : frame.id;
+							const event = frame.data === "" ? null : parsePushEvent(frame.data);
+							if (event !== null) {
+								closed ||= event.type === "close";
+								yield event;
+							}
+						}
+					} catch {}
+				} else await response?.body?.cancel().catch(() => void 0);
+				if (closed || Date.now() - opened >= STABLE_MS) failures = 0;
+				else failures += 1;
+				await pause(Math.min(retryMs * 2 ** Math.max(0, failures - 1), MAX_RETRY_MS), signal);
+			}
+		},
 		frame: options.endpoint,
+		async page(request, pageOptions) {
+			const response = await send(JSON.stringify(request.props === void 0 ? {
+				name: request.name,
+				type: "page"
+			} : {
+				name: request.name,
+				props: request.props,
+				type: "page"
+			}), pageOptions.signal);
+			const reply = parsePageReply(await replyBody(response));
+			if (reply === null) throw new TransportError(unavailable);
+			return reply;
+		},
 		async *session(body, { signal }) {
 			let init;
 			try {
@@ -120,6 +267,7 @@ function httpTransport(options) {
 			let response;
 			try {
 				response = await post(JSON.stringify({
+					document: body.document,
 					messages: body.messages,
 					options: body.options,
 					type: "session"
@@ -138,40 +286,24 @@ function httpTransport(options) {
 				};
 				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");
+				for await (const frame of sseFrames(response.body, signal)) {
+					const event = frame.data === "" ? null : parseSessionEvent(frame.data);
+					if (event !== null) {
+						ended ||= event.type !== "program";
+						yield event;
 					}
 				}
+				if (!ended && !signal.aborted) yield {
+					error: network,
+					type: "error"
+				};
 			} catch {
 				if (!signal.aborted) yield {
 					error: network,
 					type: "error"
 				};
-			} finally {
-				reader.releaseLock();
 			}
 		}
 	};

package/dist/view/controller.d.ts

@@ -1,5 +1,5 @@
 import { ConfirmFunction, JigsClient } from "../client.js";
-import { Program, PropSchema, RuntimeError, WireArg } from "@jigs.design/protocol";
+import { JsonValue, Program, PropSchema, RuntimeError, WireArg } from "@jigs.design/protocol";
 import { TreeNode, TreeStore } from "@jigs.design/runtime";
 //#region src/view/controller.d.ts
 /** What the view shows beside the tree: a snapshot, replaced on each change. */
@@ -91,6 +91,12 @@ export interface ViewController {
    * `signal` aborted.
    */
   setConfirmHandler: (handler: ConfirmFunction | undefined) => void;
+  /**
+   * Replaces the provided data, by slot name. Every read of a slot whose
+   * value changed, compared as JSON, gets the new value, as a refetched
+   * query's does; a slot left out reads as `UNAVAILABLE`.
+   */
+  setData: (values: Readonly<Record<string, JsonValue>> | undefined) => void;
   /** Replaces what each new issue is given to; `undefined` stops reporting. */
   setIssueHandler: (handler: ((issue: ViewIssue) => void) | undefined) => void;
   /**

package/dist/view/controller.js

@@ -35,6 +35,15 @@ const NO_ACTIONS = {
 	},
 	status: "error"
 };
+/** What a read of slot `name` gets when the page provides no value for it. */
+const notProvided = (name) => ({
+	data: null,
+	error: {
+		code: "UNAVAILABLE",
+		message: `The page provided no "${name}"`
+	},
+	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) {
@@ -73,6 +82,10 @@ function createViewController(client) {
 	const store = createTreeStore();
 	const listeners = /* @__PURE__ */ new Set();
 	const observers = /* @__PURE__ */ new Map();
+	/** Reads of provided slots, answered here, never fetched: key to slot name. */
+	const slotReads = /* @__PURE__ */ new Map();
+	/** The page's provided data, each value with its JSON to compare by. */
+	let provided = /* @__PURE__ */ new Map();
 	const sent = /* @__PURE__ */ new Map();
 	let iframe = null;
 	let ready = false;
@@ -107,6 +120,8 @@ function createViewController(client) {
 	* still showing cannot run a mutation for a program that is gone.
 	*/
 	let confirmationScope = new AbortController();
+	/** Lets the push channel close; set while the view is started. */
+	let unhold = null;
 	const withdrawConfirmations = () => {
 		confirmationScope.abort();
 		confirmationScope = new AbortController();
@@ -241,8 +256,18 @@ function createViewController(client) {
 	const dropObservers = () => {
 		for (const unsubscribe of observers.values()) unsubscribe();
 		observers.clear();
+		slotReads.clear();
 		sent.clear();
 	};
+	/** What a read of slot `name` gets now. */
+	const slotResult = (name) => {
+		const entry = provided.get(name);
+		return entry === void 0 ? notProvided(name) : {
+			data: entry.value,
+			error: null,
+			status: "success"
+		};
+	};
 	/** 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;
@@ -253,7 +278,7 @@ function createViewController(client) {
 	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) {
+			if (!isRecord(read) || typeof read.key !== "string" || typeof read.name !== "string" || procedure(read.name, ["data", "query"]) === void 0) {
 				drop("The sandbox read a query this program does not declare");
 				continue;
 			}
@@ -275,9 +300,20 @@ function createViewController(client) {
 			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);
-		}));
+		for (const key of slotReads.keys()) if (!wanted.has(key)) {
+			slotReads.delete(key);
+			sent.delete(key);
+		}
+		for (const [key, read] of wanted) {
+			if (procedure(read.name, ["data"]) !== void 0) {
+				slotReads.set(key, read.name);
+				sendQuery(key, slotResult(read.name));
+				continue;
+			}
+			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) => {
@@ -478,6 +514,19 @@ function createViewController(client) {
 		setConfirmHandler: (handler) => {
 			confirmHandler = handler;
 		},
+		setData: (values) => {
+			const next = /* @__PURE__ */ new Map();
+			for (const [name, value] of Object.entries(values ?? {})) {
+				const text = JSON.stringify(value);
+				const before = provided.get(name);
+				next.set(name, before?.text === text ? before : {
+					text,
+					value
+				});
+			}
+			provided = next;
+			for (const [key, name] of slotReads) sendQuery(key, slotResult(name));
+		},
 		setIssueHandler: (handler) => {
 			issueHandler = handler;
 		},
@@ -497,6 +546,7 @@ function createViewController(client) {
 				if (iframe === frame && !ready && startup === null) startup = setTimeout(diagnoseFrame, STARTUP_MS);
 			});
 			iframe = frame;
+			unhold = client.hold();
 			window.addEventListener("message", onMessage);
 			document.body.append(frame);
 		},
@@ -520,8 +570,11 @@ function createViewController(client) {
 			latestDocument = void 0;
 			actionHandler = void 0;
 			confirmHandler = void 0;
+			provided = /* @__PURE__ */ new Map();
 			withdrawConfirmations();
 			dropObservers();
+			unhold?.();
+			unhold = null;
 			store.reset();
 			status = idle;
 		},

package/package.json

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