gemi 0.128.0 → 0.130.0

package/dist/client/index.js

@@ -1,5 +1,6 @@
-import { $ as retryDelayFor, A as useLocation, B as getRealtimeClient, C as useRoute, D as I18nProvider, E as I18nContext, G as QueryConfigContext, H as SOCKET_ID_HEADER, I as RealtimeContext, J as USER_QUERY_CONFIG_KEYS, K as QueryManagerContext, L as channelKey, M as isAbsoluteUrl, O as ServerDataContext, P as Action, Q as parseRetryAfter, R as configureRealtime, S as routeDataUrl, T as useNavigate, U as toVariantKey, V as reconnectRealtime, W as applyParams$1, X as DEFAULT_STALE_TIME, Y as pickDefined, Z as isRetryableQueryError, _ as loadDictionary, a as useRouteTransition, b as setActiveLocale, c as ComponentsContext, d as loadViewModule, et as shouldRetryQuery, f as subscribeViewModules, g as recoverFromChunkLoadError, h as isChunkLoadError, i as RouteTransitionProvider, j as domainUrl, k as ServerDataProvider, l as ComponentsProvider, m as configureChunkLoadRecovery, n as useTheme, nt as Subject, o as ClientRouterContext, p as CHUNK_RELOAD_MARKER, q as QueryManagerProvider, r as m, s as ClientRouterProvider, t as ThemeProvider, tt as QueryError, u as initialViewModulesReady, v as loadDictionaryForRender, w as useSearchParams, x as readRoutePayload, y as registerDictionary, z as currentSocketId } from "../chunks/ThemeProvider-BIrCSrFY.js";
+import { $ as DEFAULT_STALE_TIME, A as ServerDataContext, B as followLive, C as readRoutePayload, D as useNavigate, E as useSearchParams, G as loadedModule, H as realtime, I as Action, J as QueryConfigContext, K as toVariantKey, M as useLocation, N as domainUrl, O as I18nContext, P as isAbsoluteUrl, Q as pickDefined, R as RealtimeContext, S as setActiveLocale, T as useRoute, U as reconnectRealtime, W as loadLazy, X as QueryManagerProvider, Y as QueryManagerContext, Z as USER_QUERY_CONFIG_KEYS, _ as isChunkLoadError, a as useRouteTransition, at as Subject, b as loadDictionaryForRender, c as ClientRouterContext, d as ComponentsProvider, et as isRetryableQueryError, f as initialViewModulesReady, g as configureChunkLoadRecovery, h as CHUNK_RELOAD_MARKER, i as RouteTransitionProvider, it as QueryError, j as ServerDataProvider, k as I18nProvider, l as ClientRouterProvider, m as subscribeViewModules, n as useTheme, nt as retryDelayFor, o as useChannelSubscription, p as loadViewModule, q as applyParams$1, r as m, rt as shouldRetryQuery, s as useCoalesced, t as ThemeProvider, u as ComponentsContext, v as recoverFromChunkLoadError, w as routeDataUrl, x as registerDictionary, y as loadDictionary, z as configureRealtime } from "../chunks/ThemeProvider-gWqXjGh-.js";
 import { n as RouteStateContext, r as RouteStateProvider, t as useParams } from "../chunks/useParams-BN3XXfmG.js";
+import { a as isNetworkError, c as isPermissionError, d as isValidationError, f as mutationErrorField, h as mutationErrorList, i as isHttpError, l as isRateLimitError, m as mutationErrorKind, n as isCsrfError, o as isNotFoundError, p as mutationErrorFromBody, r as isFormError, s as isObject, t as isAuthenticationError, u as isServerError } from "../chunks/MutationError-DuKqBW8o.js";
 import { Fragment, StrictMode, Suspense, createContext, createElement, isValidElement, lazy, memo, use, useCallback, useContext, useDeferredValue, useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createRoot as createRoot$1, hydrateRoot } from "react-dom/client";
@@ -27,180 +28,6 @@ function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 }
 //#endregion
-//#region client/realtime/useChannelSubscription.ts
-var CLOSED = {
-	status: "closed",
-	code: null
-};
-var IDLE = {
-	status: "idle",
-	code: null
-};
-/**
-* The one subscription primitive the channel hooks share. Subscribes only in
-* an effect, so a server render, a static page or an island that never
-* mounts opens no socket; on the server it reports `closed`. Handlers may
-* change between renders without resubscribing.
-*/
-function useChannelSubscription(pattern, params, handlers, enabled) {
-	const active = enabled && pattern !== null;
-	const [state, setState] = useState(active ? CLOSED : IDLE);
-	const provided = useContext(RealtimeContext);
-	const handlersRef = useRef(handlers);
-	handlersRef.current = handlers;
-	const paramsRef = useRef(params);
-	paramsRef.current = params;
-	useEffect(() => {
-		if (!active || pattern === null) {
-			setState(IDLE);
-			return;
-		}
-		const socket = provided ?? getRealtimeClient();
-		if (!socket) return;
-		const release = socket.subscribe(pattern, paramsRef.current, {
-			onEvent: (event, data) => handlersRef.current.onEvent?.(event, data),
-			onResync: () => handlersRef.current.onResync?.(),
-			onStatus: (status, code) => setState((previous) => previous.status === status && previous.code === code ? previous : {
-				status,
-				code
-			})
-		});
-		return () => {
-			release();
-			setState(CLOSED);
-		};
-	}, [
-		provided,
-		pattern === null ? null : channelKey(pattern, params),
-		active
-	]);
-	if (typeof window === "undefined") return active ? CLOSED : IDLE;
-	return state;
-}
-/**
-* `fn`, run at most once per `ms`: the first call starts the window, and the
-* calls inside it fold into the one run at its end. Stable across renders;
-* a pending run is dropped on unmount.
-*/
-function useCoalesced(fn, ms = 150) {
-	const fnRef = useRef(fn);
-	fnRef.current = fn;
-	const timer = useRef(null);
-	useEffect(() => () => {
-		if (timer.current) clearTimeout(timer.current);
-		timer.current = null;
-	}, []);
-	const coalesced = useRef(null);
-	coalesced.current ??= () => {
-		if (timer.current) return;
-		timer.current = setTimeout(() => {
-			timer.current = null;
-			fnRef.current();
-		}, ms);
-	};
-	return coalesced.current;
-}
-//#endregion
-//#region client/useChannel.ts
-var warnedWithoutResync = /* @__PURE__ */ new Set();
-/**
-* Subscribes to a broadcast channel while the component is mounted.
-*
-* ```tsx
-* const { status } = useChannel("site.:siteId", { params: { siteId } }, {
-*   on: { changed: (d) => mutate({ path: "/pages/:pageId", params: { pageId } }) },
-*   onResync: () => mutate({ path: "/pages/:pageId", params: { pageId } }),
-* });
-* ```
-*
-* Events are hints, delivered at most once: pair `on` with `onResync`, which
-* runs whenever some may have been missed. `useChannelInvalidate` does both
-* for the common case. On the server, and until the effect runs, `status` is
-* `closed`.
-*/
-function useChannel(pattern, options = {}, config = {}) {
-	const configRef = useRef(config);
-	configRef.current = config;
-	const hasOn = config.on !== void 0 && Object.keys(config.on).length > 0;
-	const hasResync = config.onResync !== void 0;
-	useEffect(() => {
-		if (process.env.NODE_ENV === "production") return;
-		if (!hasOn || hasResync || warnedWithoutResync.has(pattern)) return;
-		warnedWithoutResync.add(pattern);
-		console.warn(`[gemi] useChannel("${pattern}") has \`on\` handlers but no \`onResync\`. Broadcast events are hints delivered at most once: after a reconnect or a gap the events in between are gone, so refetch in \`onResync\` (or use useChannelInvalidate).`);
-	}, [
-		pattern,
-		hasOn,
-		hasResync
-	]);
-	return useChannelSubscription(pattern, options.params ?? {}, {
-		onEvent: (event, data) => {
-			const handler = configRef.current.on?.[event];
-			handler?.(data);
-		},
-		onResync: () => configRef.current.onResync?.()
-	}, config.enabled !== false);
-}
-/**
-* Refetches `paths` on any event on the channel and on every resync. Only
-* the variants being rendered refetch now; the rest are marked stale. Events
-* are coalesced: a burst within 150 ms refetches once.
-*
-* ```tsx
-* useChannelInvalidate("page.:pageId", { pageId }, ["/pages/:pageId", "/pages/:pageId/pictures"]);
-* ```
-*/
-function useChannelInvalidate(pattern, params, paths, config = {}) {
-	const { getResource } = useContext(QueryManagerContext);
-	const routeParams = useParams();
-	const channelParams = params ?? {};
-	const latest = useRef({
-		paths,
-		routeParams,
-		channelParams,
-		getResource
-	});
-	latest.current = {
-		paths,
-		routeParams,
-		channelParams,
-		getResource
-	};
-	const invalidate = () => {
-		const { paths, routeParams, channelParams, getResource } = latest.current;
-		for (const entry of paths) {
-			const target = typeof entry === "string" ? { path: entry } : entry;
-			const resource = getResource(applyParams$1(target.path, {
-				...routeParams,
-				...channelParams,
-				...target.params
-			}));
-			const keys = target.search ? [toVariantKey(target.search)] : resource.variantKeys();
-			for (const key of keys) resource.invalidate(key);
-		}
-	};
-	return useChannelSubscription(pattern, channelParams, {
-		onEvent: useCoalesced(invalidate),
-		onResync: invalidate
-	}, config.enabled !== false);
-}
-function resolveLiveChannel(live) {
-	if (!live) return null;
-	if (typeof live === "string") return {
-		pattern: live,
-		params: {}
-	};
-	if (Array.isArray(live)) return {
-		pattern: live[0],
-		params: live[1] ?? {}
-	};
-	const object = live;
-	return {
-		pattern: object.channel,
-		params: object.params ?? {}
-	};
-}
-//#endregion
 //#region client/useQuery.ts
 /**
 * A DOM event or React's synthetic one. Never a plain object, so a cached
@@ -275,18 +102,15 @@ function useFrameworkQuery(url, ...args) {
 	const lazy = config.lazy;
 	const configRef = useRef(config);
 	configRef.current = config;
-	const liveChannel = resolveLiveChannel(config.live);
+	const realtime = useContext(RealtimeContext);
+	const [liveOpen, setLiveOpen] = useState(false);
 	const liveResourceRef = useRef(resource);
 	liveResourceRef.current = resource;
-	const refreshLive = useCallback(() => {
-		const target = liveResourceRef.current;
-		for (const key of target.variantKeys()) target.invalidate(key);
-	}, []);
-	const refreshLiveOnEvent = useCoalesced(refreshLive);
-	const liveOpen = useChannelSubscription(liveChannel?.pattern ?? null, liveChannel?.params ?? {}, {
-		onEvent: refreshLiveOnEvent,
-		onResync: refreshLive
-	}, liveChannel !== null).status === "open";
+	const liveKey = config.live ? JSON.stringify(config.live) : null;
+	useEffect(() => {
+		if (liveKey === null) return;
+		return followLive(realtime, JSON.parse(liveKey), () => liveResourceRef.current, setLiveOpen);
+	}, [realtime, liveKey]);
 	const refreshIntervalRef = useRef(null);
 	const fetchedRef = useRef(!lazy);
 	const pollRef = useRef({
@@ -712,282 +536,36 @@ function useInfiniteQuery(url, options, config) {
 	};
 }
 //#endregion
-//#region http/refusal.ts
-/**
-* The kind a status stands for, for a refusal that does not name one: an app's
-* own `RequestBreakerError`, or an older server's `{ message }`. Any other 4xx
-* is a `form_error`, a message about this request for `<FormError>` to show.
-*/
-function refusalKindForStatus(status) {
-	if (status === 401) return "authentication";
-	if (status === 403) return "permission";
-	if (status === 404) return "not_found";
-	if (status === 416) return "range_not_satisfiable";
-	if (status === 429) return "rate_limit";
-	if (status >= 500) return "server_error";
-	return "form_error";
-}
-//#endregion
-//#region client/MutationError.ts
-var LEGACY_MESSAGES = {
-	"Authentication error": "authentication",
-	"Not authorized": "authorization",
-	"Insufficient permissions": "permission",
-	"Invalid CSRF token": "csrf",
-	"Internal Server Error": "server_error",
-	Forbidden: "permission",
-	"Not found": "not_found",
-	"Rate limit exceeded": "rate_limit"
-};
-function isObject(error) {
-	return typeof error === "object" && error !== null;
-}
-function legacyKind(message, status) {
-	return LEGACY_MESSAGES[message] ?? (status === 401 ? "authorization" : refusalKindForStatus(status));
-}
+//#region services/broadcast/socketHeader.ts
 /**
-* The `MutationError` a non-2xx response's parsed body stands for.
-*
-* gemi's own error bodies are `{ error }`, and the value under `error` is what
-* is handed over. An app's body without one —
-* `HttpResponse.json({ message: "Taken" }, { status: 409 })` — is handed over
-* whole. A body with no content (`null`) becomes a refusal naming the status.
-*
-* What is handed over carries `status`, and a `kind` when it has a `message`:
-* a bare string, which servers before 0.88 sent for most refusals, becomes
-* `{ kind, message, status }`, and so does a `{ message }` without a kind.
+* The request header a client sends its socket id in, for `toOthers`.
 *
-* @internal
+* A module of its own, re-exported by `./protocol`: every mutation in the
+* browser reads it, and anything else in `./protocol` it pulled along would
+* land in every route's entry chunk instead of the lazily loaded socket's.
 */
-function mutationErrorFromBody(body, status) {
-	const error = isObject(body) && "error" in body && body.error != null ? body.error : body;
-	if (error == null) return {
-		kind: refusalKindForStatus(status),
-		message: `Request failed with status ${status}`,
-		status
-	};
-	if (typeof error === "string") return {
-		kind: legacyKind(error, status),
-		message: error,
-		status
-	};
-	if (!isObject(error) || error instanceof Error) return error;
-	const withStatus = {
-		...error,
-		status: typeof error.status === "number" ? error.status : status
-	};
-	if (typeof error.kind !== "string" && typeof error.message === "string") return {
-		...withStatus,
-		kind: refusalKindForStatus(withStatus.status)
-	};
-	return withStatus;
-}
-function kindOf(error) {
-	if (typeof error === "string") return LEGACY_MESSAGES[error];
-	if (!isObject(error) || error instanceof Error) return void 0;
-	if (typeof error.kind === "string") return error.kind;
-	if (typeof error.status === "number") return refusalKindForStatus(error.status);
-	return typeof error.message === "string" ? LEGACY_MESSAGES[error.message] : void 0;
-}
-/** Field messages, as `<ValidationErrors>` renders them. */
-function isValidationError(error) {
-	return isObject(error) && error.kind === "validation_error";
-}
-/** A form-level message, as `<FormError>` renders it. */
-function isFormError(error) {
-	return isObject(error) && error.kind === "form_error";
-}
-/** No signed-in user: `AuthenticationError` (401). */
-function isAuthenticationError(error) {
-	return kindOf(error) === "authentication";
-}
-/**
-* A signed-in user who may not do this: `InsufficientPermissionsError` (403),
-* `AuthorizationError` (401) or a policy denial (403), whatever message it was
-* thrown with.
-*/
-function isPermissionError(error) {
-	const kind = kindOf(error);
-	return kind === "permission" || kind === "authorization";
-}
-/** The CSRF cookie is missing or stale (403). A reload fixes it. */
-function isCsrfError(error) {
-	return kindOf(error) === "csrf";
-}
-/** A missing record, file or route (404). */
-function isNotFoundError(error) {
-	return kindOf(error) === "not_found";
-}
-/**
-* `RateLimitMiddleware` or `RateLimiter.enforce` refused the request (429).
-* `retryAfter` (ms) says when to try again, when the server sent it.
-*/
-function isRateLimitError(error) {
-	return kindOf(error) === "rate_limit";
-}
-/**
-* The server failed (a 500, under `gemi dev` too), or answered something that
-* is not JSON.
-*/
-function isServerError(error) {
-	return kindOf(error) === "server_error" || error instanceof SyntaxError;
-}
-/** The request got no answer: offline, DNS, CORS, a dropped connection. */
-function isNetworkError(error) {
-	return error instanceof TypeError;
-}
-/**
-* Which of the guards above `error` passes, for a `switch` over all of them.
-* `"unknown"` is everything else: a 416, an error body of the app's own shape.
-*/
-function mutationErrorKind(error) {
-	if (isValidationError(error)) return "validation";
-	if (isFormError(error)) return "form";
-	if (isAuthenticationError(error)) return "authentication";
-	if (isPermissionError(error)) return "permission";
-	if (isCsrfError(error)) return "csrf";
-	if (isNotFoundError(error)) return "not_found";
-	if (isRateLimitError(error)) return "rate_limit";
-	if (isServerError(error)) return "server";
-	if (isNetworkError(error)) return "network";
-	return "unknown";
-}
-/**
-* An error answered with `status`: a route's typed error from
-* `HttpResponse.error(status, body)` / `httpError`, narrowed to the members
-* of `error`'s type with that status.
-*
-* ```ts
-* onError: (error) => {
-*   if (isHttpError(error, 410)) toast(error.message);
-* }
-* ```
-*
-* At run time it checks the status alone, so gemi's own refusals with the
-* same status (a 404 `not_found`, a 429 `rate_limit`) pass it too; pick a
-* status gemi does not use for its own errors, or check `kind` after it.
-*/
-function isHttpError(error, status) {
-	return isObject(error) && !(error instanceof Error) && error.status === status;
-}
-var FALLBACK_MESSAGE = "Something went wrong. Try again.";
-function unwrapQueryError(error) {
-	if (error instanceof Error && error.name === "QueryError" && "body" in error) {
-		const { body, status } = error;
-		return body == null ? error : mutationErrorFromBody(body, status);
-	}
-	return error;
-}
-/**
-* `error.list(fallback)` for any value: an error kept from a mutation, a
-* `useQuery` `QueryError` (its body is read), or anything else.
-*/
-function mutationErrorList(error, fallback = FALLBACK_MESSAGE) {
-	const value = unwrapQueryError(error);
-	if (isValidationError(value)) {
-		const messages = Object.values(value.messages ?? {}).flat().filter((message) => typeof message === "string" && message !== "");
-		return messages.length > 0 ? messages : [fallback];
-	}
-	if (isObject(value) && !(value instanceof Error) && value.kind !== "server_error" && typeof value.message === "string" && value.message !== "") return [value.message];
-	return [fallback];
-}
-/**
-* `error.field(name)` for any value: a validation error's messages for
-* `name` (a `QueryError`'s body is read), `[]` for anything else.
-*/
-function mutationErrorField(error, name) {
-	const value = unwrapQueryError(error);
-	if (!isValidationError(value)) return [];
-	const messages = value.messages?.[name];
-	return Array.isArray(messages) ? [...messages] : [];
-}
-/**
-* Puts `list` and `field` on an error the hooks hand over, as non-enumerable
-* properties, so `toEqual`, a spread and `JSON.stringify` see the same object
-* as before. A key the error already has is left alone; a primitive or a
-* frozen value is returned as it is.
-*
-* @internal
-*/
-function withMutationErrorHelpers(error) {
-	if (!isObject(error) || !Object.isExtensible(error)) return error;
-	const helpers = {
-		list: (fallback) => mutationErrorList(error, fallback),
-		field: (name) => mutationErrorField(error, name)
-	};
-	for (const key of ["list", "field"]) {
-		if (key in error) continue;
-		Object.defineProperty(error, key, {
-			value: helpers[key],
-			configurable: true,
-			writable: true,
-			enumerable: false
-		});
-	}
-	return error;
-}
+var SOCKET_ID_HEADER = "x-gemi-socket";
 //#endregion
-//#region client/useSetQueryData.ts
+//#region client/mutationModules.ts
 /**
-* Write into every variant `target` names. `next` is the value to write, or
-* a function of the cached value; a function skips a variant with nothing
-* cached. A value seeds a single variant that is not cached yet; a predicate
-* only ever reaches variants that are.
-*/
-function writeQueryData(getResource, routeParams, target, next) {
-	const { path, params = {}, search = {} } = target;
-	const resource = getResource(applyParams$1(String(path), {
-		...routeParams,
-		...params
-	}));
-	const write = (variantKey) => {
-		if ("value" in next) {
-			resource.set(variantKey, next.value);
-			return;
-		}
-		const state = resource.peek(variantKey);
-		if (!state?.hasData) return;
-		resource.set(variantKey, next.update(state.data));
-	};
-	if (typeof search === "function") {
-		for (const variantKey of resource.variantKeys()) {
-			if (!resource.peek(variantKey)?.hasData) continue;
-			if (search(new URLSearchParams(variantKey))) write(variantKey);
-		}
-		return;
-	}
-	write(toVariantKey(search));
-}
-/**
-* Write a mutation's `updates` with its answer.
-*/
-function applyQueryUpdates(getResource, routeParams, updates, answer) {
-	for (const update of updates ?? []) {
-		const { data } = update;
-		writeQueryData(getResource, routeParams, update, data ? { update: (current) => data(answer, current) } : { value: answer });
-	}
-}
-/**
-* Returns a function that writes into any query's cache by path, with no
-* refetch: for data the server already answered with. `useMutate` is the
-* optimistic counterpart, which refetches to reconcile.
+* `./mutationExtras`, which a page only needs once it mutates: loaded when the
+* first mutation hook, or `useSetQueryData()`, mounts (#915), so no route's
+* entry chunk carries it. By the time a request settles it is normally there;
+* one that settles first waits for it.
 *
-* ```ts
-* const setQueryData = useSetQueryData();
-* setQueryData({ path: "/pages/:pageId/assets", params: { pageId } }, assets);
-* setQueryData({ path: "/todos", search: () => true }, (todos) => todos.slice(1));
-* ```
-*
-* A value replaces the variant's data, and seeds it when nothing is cached
-* yet. A function updates what is cached and skips a variant with nothing
-* cached. A predicate `search` reaches every cached variant it accepts.
+* Keep this module out of `gemi/testing`'s imports. Shared with that entry, it
+* moves into the chunk both entries import, and there an app's bundler can
+* emit `./mutationExtras` even for an app that never mutates, which splits the
+* app's entry chunk ("needs no chunk besides the entry to start" in
+* `packaging.test.ts`).
 */
-function useSetQueryData() {
-	const { getResource } = useContext(QueryManagerContext);
-	const routeParams = useParams();
-	return useCallback(function setQueryData(target, next) {
-		writeQueryData(getResource, routeParams, target, typeof next === "function" ? { update: next } : { value: next });
-	}, [getResource, routeParams]);
+var mutationExtras = {
+	current: null,
+	load: () => import("../chunks/mutationExtras-CtY-X9m7.js")
+};
+/** Starts loading `./mutationExtras`: the hooks' mount effect. */
+function preloadMutationExtras() {
+	loadLazy(mutationExtras).catch(() => {});
 }
 //#endregion
 //#region client/useMutation.ts
@@ -1022,6 +600,7 @@ function useMutation(method, url, ...args) {
 		...config
 	};
 	const parallel = options.concurrency === "parallel";
+	useEffect(preloadMutationExtras, []);
 	async function trigger(input, call = {}) {
 		const controller = new AbortController();
 		abortController.current = controller;
@@ -1064,24 +643,26 @@ function useMutation(method, url, ...args) {
 		if (input instanceof FormData) body = input;
 		else if (typeof input === "undefined") body = formData.current;
 		else if (input) body = JSON.stringify(input);
+		const socketId = realtime.client?.socketId;
 		try {
 			const response = await fetch(`/api${finalUrl}`, {
 				method,
 				headers: {
 					...contentType,
-					...socketIdHeader()
+					...socketId ? { [SOCKET_ID_HEADER]: socketId } : {}
 				},
 				...body ? { body } : {},
 				signal: controller.signal
 			});
 			const data = await response.json();
+			const error = response.ok ? null : await withErrorHelpers(mutationErrorFromBody(data, response.status));
+			const extras = response.ok && options.updates ? await loadOrNull() : null;
 			if (isSuperseded()) {
 				settle((prev) => prev, true);
 				return;
 			}
 			resetFormData();
 			if (!response.ok) {
-				const error = withMutationErrorHelpers(mutationErrorFromBody(data, response.status));
 				settle((prev) => ({
 					data: prev.data,
 					error
@@ -1091,7 +672,7 @@ function useMutation(method, url, ...args) {
 				return;
 			}
 			clearPrefetchCache?.();
-			applyQueryUpdates(getResource, _params, options.updates, data);
+			extras?.applyQueryUpdates(getResource, _params, options.updates, data);
 			options.onSuccess(data);
 			call.onSuccess?.(data);
 			settle(() => ({
@@ -1099,7 +680,8 @@ function useMutation(method, url, ...args) {
 				error: null
 			}));
 			return data;
-		} catch (error) {
+		} catch (thrown) {
+			const error = await withErrorHelpers(thrown);
 			if (isSuperseded()) {
 				settle((prev) => prev, true);
 				return;
@@ -1109,12 +691,11 @@ function useMutation(method, url, ...args) {
 				settle((prev) => prev);
 				return;
 			}
-			const failure = withMutationErrorHelpers(error);
-			options.onError(failure);
-			call.onError?.(failure);
+			options.onError(error);
+			call.onError?.(error);
 			settle((prev) => ({
 				data: parallel ? prev.data : null,
-				error: failure
+				error
 			}));
 		}
 	}
@@ -1162,6 +743,7 @@ function useUpload(url, ...args) {
 	const { getResource } = useContext(QueryManagerContext);
 	const abortRef = useRef(null);
 	const [inputs = {}, options = defaultOptions] = args ?? [];
+	useEffect(preloadMutationExtras, []);
 	const cancel = () => {
 		const abort = abortRef.current;
 		if (!abort) return;
@@ -1231,20 +813,22 @@ function useUpload(url, ...args) {
 				try {
 					error = mutationErrorFromBody(JSON.parse(outcome.body), outcome.status);
 				} catch {}
+				const failure = await withErrorHelpers(error);
 				setState("error");
-				options?.onError?.(withMutationErrorHelpers(error));
+				options?.onError?.(failure);
 				return;
 			}
 			const json = JSON.parse(outcome.body);
 			clearPrefetchCache?.();
-			applyQueryUpdates(getResource, _params, options?.updates, json);
+			if (options.updates) (await loadOrNull())?.applyQueryUpdates(getResource, _params, options.updates, json);
 			options?.onSuccess?.(json);
 			setState("done");
 			return json;
 		} catch (error) {
 			release();
+			const failure = await withErrorHelpers(error);
 			setState("error");
-			options?.onError?.(withMutationErrorHelpers(error));
+			options?.onError?.(failure);
 			return;
 		}
 	};
@@ -1255,13 +839,17 @@ function useUpload(url, ...args) {
 		cancel
 	};
 }
-/**
-* `X-Gemi-Socket` with this tab's broadcast socket id, while one is open, so
-* a controller's `Broadcast.toOthers(req)` skips the tab that made the change.
-*/
-function socketIdHeader() {
-	const id = currentSocketId();
-	return id ? { [SOCKET_ID_HEADER]: id } : {};
+function loadOrNull() {
+	return loadLazy(mutationExtras).catch(() => null);
+}
+async function withErrorHelpers(error) {
+	const extras = await loadOrNull();
+	if (extras) return extras.withMutationErrorHelpers(error);
+	if (isObject(error) && Object.isExtensible(error) && !("list" in error)) Object.defineProperties(error, {
+		list: { value: (fallback = "Something went wrong. Try again.") => [fallback] },
+		field: { value: () => [] }
+	});
+	return error;
 }
 //#endregion
 //#region client/useMutate.ts
@@ -1309,6 +897,10 @@ function useMutate() {
 }
 //#endregion
 //#region client/fetchFile.ts
+var request = {
+	current: null,
+	load: () => import("../chunks/fetchFileRequest-BSrgYnAy.js")
+};
 /**
 * Downloads a file route's body as a `Blob`.
 *
@@ -1323,75 +915,57 @@ function useMutate() {
 * `retryAfter`), the error `useQuery` throws, so `mutationErrorList(error)`
 * reads its message. A network failure rejects with the browser's `TypeError`,
 * an abort with its `AbortError`.
+*
+* The request code loads on the first call (#915), so a route that never
+* downloads a file carries none of it; a failed load rejects as a network
+* failure does.
 */
 async function fetchBlob(path, ...args) {
-	const response = await request(path, args[0]);
-	return {
-		blob: await response.blob(),
-		filename: filenameOf(response),
-		response
-	};
+	return (await loadLazy(request)).fetchFile(path, args[0], "blob");
 }
 /** `fetchBlob`, with the body read as text. */
 async function fetchText(path, ...args) {
-	const response = await request(path, args[0]);
-	return {
-		text: await response.text(),
-		filename: filenameOf(response),
-		response
-	};
-}
-async function request(path, options = {}) {
-	const { params = {}, search, signal, init } = options;
-	const url = applyParams$1(path, params);
-	const query = searchString(search);
-	const response = await fetch(`/api${url}${query ? `?${query}` : ""}`, {
-		...init,
-		method: "GET",
-		signal
-	});
-	if (!response.ok) {
-		const body = await response.json().catch(() => null);
-		throw new QueryError(url, query, response.status, body, parseRetryAfter(response.headers.get("retry-after")));
-	}
-	return response;
-}
-function searchString(search) {
-	if (!search) return "";
-	if (search instanceof URLSearchParams) return search.toString();
-	const params = new URLSearchParams();
-	for (const [key, value] of Object.entries(search)) if (value !== null && value !== void 0) params.append(key, String(value));
-	return params.toString();
+	return (await loadLazy(request)).fetchFile(path, args[0], "text");
 }
+//#endregion
+//#region client/useSetQueryData.ts
 /**
-* The file name in a `Content-Disposition` header: the RFC 5987
-* `filename*=UTF-8''...` form when present and decodable, else `filename`.
+* Returns a function that writes into any query's cache by path, with no
+* refetch: for data the server already answered with. `useMutate` is the
+* optimistic counterpart, which refetches to reconcile.
+*
+* ```ts
+* const setQueryData = useSetQueryData();
+* setQueryData({ path: "/pages/:pageId/assets", params: { pageId } }, assets);
+* setQueryData({ path: "/todos", search: () => true }, (todos) => todos.slice(1));
+* ```
+*
+* A value replaces the variant's data, and seeds it when nothing is cached
+* yet. A function updates what is cached and skips a variant with nothing
+* cached. A predicate `search` reaches every cached variant it accepts.
 *
-* @internal Exported for tests.
+* The code behind the writes is loaded when the hook mounts. A call made
+* before it has arrived (during the first render, say) is written once it
+* has, in order.
 */
-function filenameOf(response) {
-	const header = response.headers.get("content-disposition");
-	if (!header) return null;
-	const extended = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(header);
-	if (extended) try {
-		return decodeURIComponent(extended[2].trim());
-	} catch {}
-	const plain = /filename\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^;]+))/i.exec(header);
-	if (!plain) return null;
-	return (plain[1] !== void 0 ? plain[1].replace(/\\(.)/g, "$1") : plain[2].trim()) || null;
+function useSetQueryData() {
+	const { getResource } = useContext(QueryManagerContext);
+	const routeParams = useParams();
+	useEffect(preloadMutationExtras, []);
+	return useCallback(function setQueryData(target, next) {
+		const write = typeof next === "function" ? { update: next } : { value: next };
+		const writes = mutationExtras.current;
+		if (writes) {
+			writes.writeQueryData(getResource, routeParams, target, write);
+			return;
+		}
+		loadLazy(mutationExtras).then((loaded) => loaded.writeQueryData(getResource, routeParams, target, write)).catch(() => {});
+	}, [getResource, routeParams]);
 }
 //#endregion
 //#region client/useSubscription.ts
-var MIN_RETRY_MS = 1e3;
-var MAX_RETRY_MS = 3e4;
-/** The server answered in a way retrying will not change (401, 403, 404). */
-var FatalStatus = class extends Error {
-	status;
-	constructor(status) {
-		super(`The subscription was refused with ${status}.`);
-		this.status = status;
-	}
-};
+/** `./subscriptionStream`, loaded on first use. Replaceable in tests. */
+var streamModule = { load: () => import("../chunks/subscriptionStream-CULcRbx0.js") };
 /**
 * Follows a route that answers with `ChangeFeed.stream`, as long as the
 * component is mounted: each change reaches `onChange`, in order, exactly
@@ -1442,105 +1016,27 @@ function useSubscription(url, options = {}, config = {}) {
 			return;
 		}
 		let stopped = false;
-		let request = null;
-		let resume = null;
-		let retryMs = MIN_RETRY_MS;
-		const hidden = () => pauseWhenHidden && typeof document !== "undefined" && document.visibilityState === "hidden";
-		const onVisibilityChange = () => {
-			if (hidden()) request?.abort();
-			else resume?.();
-		};
-		if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibilityChange);
-		const wait = (ms) => new Promise((resolve) => {
-			const timer = setTimeout(done, ms);
-			function done() {
-				clearTimeout(timer);
-				resume = null;
-				resolve();
-			}
-			resume = done;
+		let stop = null;
+		streamModule.load().then((module) => {
+			const { follow } = loadedModule(module);
+			if (stopped) return;
+			stop = follow({
+				endpoint,
+				pauseWhenHidden,
+				cursor,
+				callbacks,
+				setState
+			});
+		}).catch((error) => {
+			if (!stopped) setState((s) => ({
+				...s,
+				status: "closed",
+				error
+			}));
 		});
-		(async () => {
-			while (!stopped) {
-				if (hidden()) {
-					setState((s) => ({
-						...s,
-						status: "paused"
-					}));
-					await new Promise((resolve) => resume = resolve);
-					resume = null;
-					continue;
-				}
-				setState((s) => ({
-					...s,
-					status: "connecting"
-				}));
-				const controller = request = new AbortController();
-				let delay = retryMs;
-				try {
-					const headers = { Accept: "text/event-stream" };
-					if (cursor.current) headers["Last-Event-ID"] = cursor.current;
-					const response = await fetch(endpoint, {
-						headers,
-						signal: controller.signal
-					});
-					if (!response.ok || !response.body) {
-						const status = response.status;
-						if (status >= 400 && status < 500 && status !== 408 && status !== 429) throw new FatalStatus(status);
-						const retryAfter = Number(response.headers.get("Retry-After"));
-						if (Number.isFinite(retryAfter) && retryAfter > 0) delay = retryAfter * 1e3;
-						throw new Error(`The subscription answered ${status}.`);
-					}
-					for await (const { id, message } of readEvents(response.body)) {
-						if (stopped) return;
-						if (id !== void 0) cursor.current = id;
-						if (message.type === "ready") {
-							retryMs = MIN_RETRY_MS;
-							delay = MIN_RETRY_MS;
-							setState({
-								status: "open",
-								cursor: cursor.current,
-								error: null
-							});
-						} else {
-							setState((s) => ({
-								...s,
-								cursor: cursor.current
-							}));
-							if (message.type === "change") callbacks.current.onChange?.(message);
-							else if (message.type === "reset") callbacks.current.onReset?.(message);
-						}
-					}
-				} catch (error) {
-					if (stopped) return;
-					if (error instanceof FatalStatus) {
-						setState((s) => ({
-							...s,
-							status: "closed",
-							error
-						}));
-						return;
-					}
-					if (controller.signal.aborted) continue;
-					setState((s) => ({
-						...s,
-						error
-					}));
-				}
-				if (stopped || controller.signal.aborted) continue;
-				setState((s) => ({
-					...s,
-					status: "connecting"
-				}));
-				await wait(delay);
-				retryMs = Math.min(retryMs * 2, MAX_RETRY_MS);
-			}
-		})();
 		return () => {
 			stopped = true;
-			request?.abort();
-			resume?.();
-			if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibilityChange);
+			stop?.();
 		};
 	}, [
 		endpoint,
@@ -1550,48 +1046,89 @@ function useSubscription(url, options = {}, config = {}) {
 	]);
 	return state;
 }
+//#endregion
+//#region client/useChannel.ts
+var warnedWithoutResync = /* @__PURE__ */ new Set();
 /**
-* The events of an SSE body: `id` and the JSON `data`. Comments (keepalives)
-* and events without data are skipped; an event whose data is not JSON is
-* dropped rather than ending the stream.
+* Subscribes to a broadcast channel while the component is mounted.
+*
+* ```tsx
+* const { status } = useChannel("site.:siteId", { params: { siteId } }, {
+*   on: { changed: (d) => mutate({ path: "/pages/:pageId", params: { pageId } }) },
+*   onResync: () => mutate({ path: "/pages/:pageId", params: { pageId } }),
+* });
+* ```
+*
+* Events are hints, delivered at most once: pair `on` with `onResync`, which
+* runs whenever some may have been missed. `useChannelInvalidate` does both
+* for the common case. On the server, and until the effect runs, `status` is
+* `closed`.
 */
-async function* readEvents(body) {
-	const reader = body.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) return;
-			buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n?/g, "\n");
-			let boundary = buffer.indexOf("\n\n");
-			while (boundary !== -1) {
-				const block = buffer.slice(0, boundary);
-				buffer = buffer.slice(boundary + 2);
-				boundary = buffer.indexOf("\n\n");
-				let id;
-				const data = [];
-				for (const line of block.split("\n")) {
-					if (line === "" || line.startsWith(":")) continue;
-					const colon = line.indexOf(":");
-					const field = colon === -1 ? line : line.slice(0, colon);
-					let text = colon === -1 ? "" : line.slice(colon + 1);
-					if (text.startsWith(" ")) text = text.slice(1);
-					if (field === "id") id = text;
-					else if (field === "data") data.push(text);
-				}
-				if (data.length === 0) continue;
-				try {
-					yield {
-						id,
-						message: JSON.parse(data.join("\n"))
-					};
-				} catch {}
-			}
+function useChannel(pattern, options = {}, config = {}) {
+	const configRef = useRef(config);
+	configRef.current = config;
+	const hasOn = config.on !== void 0 && Object.keys(config.on).length > 0;
+	const hasResync = config.onResync !== void 0;
+	useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		if (!hasOn || hasResync || warnedWithoutResync.has(pattern)) return;
+		warnedWithoutResync.add(pattern);
+		console.warn(`[gemi] useChannel("${pattern}") has \`on\` handlers but no \`onResync\`. Broadcast events are hints delivered at most once: after a reconnect or a gap the events in between are gone, so refetch in \`onResync\` (or use useChannelInvalidate).`);
+	}, [
+		pattern,
+		hasOn,
+		hasResync
+	]);
+	return useChannelSubscription(pattern, options.params ?? {}, {
+		onEvent: (event, data) => {
+			const handler = configRef.current.on?.[event];
+			handler?.(data);
+		},
+		onResync: () => configRef.current.onResync?.()
+	}, config.enabled !== false);
+}
+/**
+* Refetches `paths` on any event on the channel and on every resync. Only
+* the variants being rendered refetch now; the rest are marked stale. Events
+* are coalesced: a burst within 150 ms refetches once.
+*
+* ```tsx
+* useChannelInvalidate("page.:pageId", { pageId }, ["/pages/:pageId", "/pages/:pageId/pictures"]);
+* ```
+*/
+function useChannelInvalidate(pattern, params, paths, config = {}) {
+	const { getResource } = useContext(QueryManagerContext);
+	const routeParams = useParams();
+	const channelParams = params ?? {};
+	const latest = useRef({
+		paths,
+		routeParams,
+		channelParams,
+		getResource
+	});
+	latest.current = {
+		paths,
+		routeParams,
+		channelParams,
+		getResource
+	};
+	const invalidate = () => {
+		const { paths, routeParams, channelParams, getResource } = latest.current;
+		for (const entry of paths) {
+			const target = typeof entry === "string" ? { path: entry } : entry;
+			const resource = getResource(applyParams$1(target.path, {
+				...routeParams,
+				...channelParams,
+				...target.params
+			}));
+			const keys = target.search ? [toVariantKey(target.search)] : resource.variantKeys();
+			for (const key of keys) resource.invalidate(key);
 		}
-	} finally {
-		await reader.cancel().catch(() => {});
-	}
+	};
+	return useChannelSubscription(pattern, channelParams, {
+		onEvent: useCoalesced(invalidate),
+		onResync: invalidate
+	}, config.enabled !== false);
 }
 //#endregion
 //#region client/Mutation.tsx