@jigs.design/client 0.1.2 → 0.3.0

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 |
@@ -26,7 +26,7 @@ The view calls `observe` and `mutate`; app code calls `invalidate`. `mutate(name
 
 The controller trusts the program it loaded and nothing the worker says: it checks each read and mutation against the program's procedure table, has the tree store check each op against the program's prop schemas, and enforces the budgets on the page again. `drawnProps` turns a node's props into what a component takes, reading each prop's kind from the schema, never from the value.
 
-It re-exports the shared types from `@jigs.design/runtime`.
+It re-exports the shared types from `@jigs.design/protocol`.
 
 ## Source
 

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { HeadersOption, Transport } from "./transport.js";
-import { Message, MutationResult, QueryResult, SessionEvent, SessionOptions } from "@jigs.design/runtime";
+import { Diagnostic, JigsErrorData, MutationResult, PageProps, Program, QueryResult, SessionBody, SessionEvent } from "@jigs.design/protocol";
 //#region src/client.d.ts
 interface CacheOptions {
   /**
@@ -46,11 +46,39 @@ 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;
   /** 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 +102,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,76 @@
 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 after the last query unsubscribes:
+* a program swap re-creates its observers after a round trip to the
+* sandbox, not within a tick.
+*/
+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: open while any query or page is observed, 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;
+	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);
+	};
+	return {
+		release: () => {
+			observers -= 1;
+			if (observers > 0) return;
+			clearTimeout(linger);
+			linger = setTimeout(() => {
+				clearTimeout(reopen);
+				running?.abort();
+				running = null;
+			}, CHANNEL_LINGER_MS);
+		},
+		retain: () => {
+			observers += 1;
+			clearTimeout(linger);
+			if (running === null) open();
+		}
+	};
+}
 function toQueryResult(result) {
 	if (result.status === "success") return {
 		data: result.data,
@@ -22,6 +88,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 +117,60 @@ 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,
 		invalidate: (name) => queries.invalidateQueries({ queryKey: [name] }),
+		invalidatePage,
 		mutate: async (name, input, procedure) => {
 			const send = async (confirmation) => {
 				try {
@@ -81,8 +210,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 +232,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, Span } from "@jigs.design/runtime";
-export { type ActionCall, type ActionHandler, type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type JigsClient, type JigsErrorCode, type JigsErrorData, type Message, type Program, type SessionEvent, 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/runtime";
+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/runtime";
+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,6 @@
 import { ConfirmFunction, JigsClient } from "../client.js";
-import { Program, PropSchema, RuntimeError, TreeNode, TreeStore, WireArg } from "@jigs.design/runtime";
+import { 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. */
 export interface ViewStatus {

package/dist/view/controller.js

@@ -1,5 +1,6 @@
 import { frameProblem, unprotectedProblem } from "./frame-check.js";
-import { createTreeStore, parseErrorData, parseProgram } from "@jigs.design/runtime";
+import { parseErrorData, parseProgram } from "@jigs.design/protocol";
+import { createTreeStore } 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.";

package/package.json

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