bitboss-ui 3.0.0-beta.64 → 3.0.0-beta.65

package/dist/ai/guides/inertia-helpers.md

@@ -76,6 +76,12 @@ nothing imports them. Your own `@/utils` and `@/types` stay yours. If the app
 auto-imports `composables/**`, exclude one of the two trees until the old
 copies are gone, or both export `useQuery`.
 
+The helpers run and type-check on Inertia 2 and 3 (`@inertiajs/vue3` 2.x or
+3.x). On Inertia 2, `useLazyProp`'s reload cannot keep the page's validation
+errors (Inertia 2 has no `preserveErrors`), and `usePromiseForm` hears a failed
+save through Inertia's global `invalid` / `exception` events, so an async reload
+that fails while a save is out counts as that save failing.
+
 The helpers need these npm packages beyond the app's own
 `@inertiajs/vue3`/`vue` (`add` prints the ones a helper needs). Install them
 explicitly rather than relying on them being hoisted through `bitboss-ui`'s own
@@ -91,10 +97,12 @@ npm i -D @inertiajs/core
 `usePageShellContext`) and `useDeleteCmd`/`useScreenSizes`; `object-code`
 powers the `isEqual` hash-comparison utility below; `query-string` backs
 `useQuery`/`useRouteQuery`/`useQueryObject`; `@inertiajs/core` is a type-only
-import (`PageProps` in `usePaginatedResponseContext`) that `@inertiajs/vue3`
-does not re-export, so a strict pnpm app fails to type-check without it. The
-helpers' shared types and tiny utilities are two files of the folder,
-`types.ts` and `utils.ts`, below.
+import (`PageProps`, `VisitOptions`, in the URL and context helpers) that `@inertiajs/vue3`
+does not re-export, so a strict pnpm app fails to type-check without it. Install
+the version your `@inertiajs/vue3` runs on (`add` prints it pinned, e.g.
+`@inertiajs/core@3.1.1`): a newer core's visit types do not match. The
+helpers' shared types, tiny utilities and words are three files of the
+folder, `types.ts`, `utils.ts` and `messages.ts`, below.
 
 ## Shared types and utilities
 
@@ -158,10 +166,76 @@ export const isPlainObject = (
 	typeof value === 'object' &&
 	value !== null &&
 	Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Deep copy of server data (arrays and plain objects; anything else, e.g. a
+ * Date an app put there, is shared). Reads through Vue proxies, which
+ * `structuredClone` refuses.
+ */
+export const cloneDeep = <T>(value: T): T =>
+	(Array.isArray(value)
+		? value.map(cloneDeep)
+		: isPlainObject(value)
+			? Object.fromEntries(
+					Object.entries(value).map(([key, item]) => [key, cloneDeep(item)])
+				)
+			: value) as T;
+```
+
+`messages.ts` holds the words a helper shows (today the leave guard's dialog),
+by the library's `locale` (`useBbConfig().locale`): `it-IT`, else `it`, else
+`en`. It is the one helper file meant to be edited: add your locales next to
+`en`. `helpers update` keeps your copy; when a release adds words here, it
+holds back this file and the helpers that read it until you merge them
+(`npx bitboss-ui helpers diff messages`).
+
+```ts
+// inertia-helpers/messages.ts
+// The words the helpers show, by the library's `locale`. Yours to edit: add
+// your app's locales next to `en` (keyed as you set `locale`: `it`, or `it-IT`
+// to tell regions apart). `helpers update` keeps your copy; if a release
+// adds words here, `npx bitboss-ui helpers diff messages` shows what to merge.
+import { useBbConfig } from 'bitboss-ui';
+import { computed } from 'vue';
+
+export type HelperMessages = {
+	leave: { title: string; text: string; yes: string; no: string };
+};
+
+export const messages: Record<string, HelperMessages> = {
+	en: {
+		leave: {
+			title: 'Unsaved changes',
+			text: 'You have unsaved changes. Leave without saving?',
+			yes: 'Discard changes',
+			no: 'Keep editing',
+		},
+	},
+};
+
+/** The messages for the current locale: `it-IT`, else `it`, else `en`. */
+export const useHelperMessages = () => {
+	const { locale } = useBbConfig();
+	return computed(
+		() =>
+			messages[locale.value] ??
+			messages[locale.value.split('-')[0]!.toLowerCase()] ??
+			messages.en!
+	);
+};
 ```
 
 ---
 
+**Unit-testing code that uses the helpers.** A test that mocks
+`@inertiajs/vue3` has to follow Inertia's own contract, or the helpers read the
+mock as a refused or broken visit: `router.visit` / `reload` call `onStart`
+synchronously (a visit with no `onStart` counts as refused before it started);
+`onFinish` receives the visit with `cancelled` / `interrupted` / `completed`;
+`router.on` returns its unbind function. `usePaginatedResponseContext` clamps a
+page past the end in `onMounted`, so call it from a mounted component, not a
+bare `effectScope`.
+
 ## Page props
 
 ### useProp / useOptionalProp
@@ -254,9 +328,17 @@ when the data lands. `loading`/`loaded`/`error` expose the fetch state;
 ```ts
 // inertia-helpers/useLazyProp.ts
 import { isEqual, isNil, isNotNil } from './utils';
+import type { PageProps } from '@inertiajs/core';
 import { router, usePage } from '@inertiajs/vue3';
 import type { Ref } from 'vue';
-import { customRef, onBeforeUnmount, readonly, ref, watch } from 'vue';
+import {
+	customRef,
+	nextTick,
+	onBeforeUnmount,
+	readonly,
+	ref,
+	watch,
+} from 'vue';
 
 export type UseLazyPropOptions = {
 	/** Keep the last non-nil value across visits that reset the prop. Default true. */
@@ -288,7 +370,9 @@ export function useLazyProp<T>(
 	initialValue?: T,
 	options: UseLazyPropOptions = {}
 ): UseLazyProp<T | undefined> {
-	const page = usePage<{ [key: string]: T | undefined }>();
+	// `PageProps &` keeps usePage's constraint satisfied in an app that
+	// augments Inertia's `PageProps` (TS2344 otherwise).
+	const page = usePage<PageProps & { [key: string]: T | undefined }>();
 	const { cache = true } = options;
 	const loading = ref(false);
 	const loaded = ref(page.props[propName] !== undefined);
@@ -296,50 +380,107 @@ export function useLazyProp<T>(
 	let inFlightPromise: Promise<void> | null = null;
 	let isUnmounted = false;
 	let cached = page.props[propName];
+	// Settles a reload a navigation cancelled, once that navigation is over.
+	let resumeCancelled: (() => void) | null = null;
 
 	onBeforeUnmount(() => {
 		isUnmounted = true;
+		resumeCancelled?.();
 	});
 
 	const loadProp = (onSuccess: () => void): Promise<void> => {
 		if (inFlightPromise) return inFlightPromise;
 
 		error.value = null;
-
-		inFlightPromise = new Promise<void>((resolve) => {
-			router.reload({
-				only: [propName],
-				replace: true,
-				...(options.headers ? { headers: options.headers } : {}),
-				onStart: () => {
-					loading.value = true;
-				},
-				onSuccess: () => {
-					if (!isUnmounted) {
-						loaded.value = true;
-						cached = page.props[propName];
-						onSuccess();
-					}
-				},
-				onError: (errors) => {
-					if (!isUnmounted) {
-						error.value =
-							errors instanceof Error
-								? errors
-								: new Error(`Failed to load lazy prop "${propName}"`);
-					}
-				},
-				onFinish: () => {
-					if (!isUnmounted) {
-						loading.value = false;
-					}
-					inFlightPromise = null;
-					resolve();
-				},
-			});
+		let started = false;
+		let succeeded = false;
+		let settle!: () => void;
+		const promise = new Promise<void>((resolve) => {
+			settle = () => {
+				if (!isUnmounted) loading.value = false;
+				if (inFlightPromise === promise) inFlightPromise = null;
+				resolve();
+			};
+		});
+		inFlightPromise = promise;
+
+		router.reload({
+			only: [propName],
+			replace: true,
+			// Like Inertia's own deferred-props loader: keep the page's
+			// validation errors (Inertia 3; Inertia 2 has no such option).
+			...({ preserveErrors: true } as object),
+			...(options.headers ? { headers: options.headers } : {}),
+			onStart: () => {
+				started = true;
+				loading.value = true;
+			},
+			onSuccess: () => {
+				succeeded = true;
+				if (!isUnmounted) {
+					loaded.value = true;
+					cached = page.props[propName];
+					onSuccess();
+				}
+			},
+			onError: (errors) => {
+				if (!isUnmounted) {
+					error.value =
+						errors instanceof Error
+							? errors
+							: new Error(`Failed to load lazy prop "${propName}"`);
+				}
+			},
+			onFinish: (visit) => {
+				// A visit to another page cancels this reload: no failure. Stay
+				// loading (a reader must not re-fire it at the outgoing URL) until
+				// that navigation is over, then retry if this page is still
+				// mounted (a same-component visit) or settle if it unmounted.
+				if (visit.cancelled) {
+					const cancelledOn = page.url;
+					const unbindFinish = router.on('finish', (event) => {
+						const next = event.detail.visit;
+						if (next.cancelled || next.interrupted) return;
+						// An async visit is over too (a mutation answered on another
+						// URL redirects back with no other visit), unless it is one
+						// of this page's own reloads (a poll, another lazy prop).
+						if (
+							next.async &&
+							next.url.href === new URL(cancelledOn, next.url).href
+						)
+							return;
+						resumeCancelled?.();
+					});
+					// Back / Forward swaps the page with no finish event.
+					const unbindNavigate = router.on('navigate', () =>
+						resumeCancelled?.()
+					);
+					resumeCancelled = () => {
+						resumeCancelled = null;
+						unbindFinish();
+						unbindNavigate();
+						void nextTick(() => {
+							inFlightPromise = null;
+							if (isUnmounted || loaded.value) settle();
+							else void loadProp(onSuccess).then(settle);
+						});
+					};
+					return;
+				}
+				// A network error or a non-Inertia response (Inertia's error
+				// dialog) reaches only onFinish: report it. The self-loading read
+				// does not retry a failed load; `execute()` does.
+				if (!succeeded && !error.value && !isUnmounted) {
+					error.value = new Error(`Failed to load lazy prop "${propName}"`);
+				}
+				settle();
+			},
 		});
+		// Refused before it started (a `before` listener cancelled it, or no
+		// `window` during SSR): no callback will ever come.
+		if (!started) settle();
 
-		return inFlightPromise;
+		return promise;
 	};
 
 	/** Self-loading ref: reading it while the prop is absent starts the fetch. */
@@ -348,8 +489,7 @@ export function useLazyProp<T>(
 			track();
 			const isMissing = page.props[propName] === undefined;
 
-			if (isMissing && !loaded.value && !loading.value) {
-				loading.value = true;
+			if (isMissing && !loaded.value && !loading.value && !error.value) {
 				void loadProp(trigger);
 			}
 
@@ -408,6 +548,10 @@ Gotchas:
   load `stats.revenue`, only `stats`.
 - Filter navigations reset lazy props server-side; with `cache: true`
   (default) the last value keeps rendering while the fresh one loads.
+- A failed load (offline, a non-Inertia 500) sets `error` and is **not**
+  retried by the next read — that would be a request storm. `execute()`
+  retries. A load a navigation cancels is no failure: it stays `loading`
+  until that navigation is over, then retries if the page is still mounted.
 
 ### useLazyPropGetter
 
@@ -458,7 +602,9 @@ export function useLazyPropGetter<T, U = T>(
 		if (!loaded.value) {
 			await execute();
 		}
-		if (isNil(value.value)) {
+		// `loaded` first: reading `value` while unloaded would start a
+		// second, background reload.
+		if (!loaded.value || isNil(value.value)) {
 			throw new Error(`Could not load lazy prop "${propName}"`);
 		}
 		if (isNil(formatter)) return value.value as unknown as U;
@@ -496,29 +642,163 @@ navigation.
 
 ### useQuery
 
-Parses the current page URL's query string into an object. Snapshot, not
-reactive — used by the writers below.
+Parses the current page URL's query string into an object, the way the
+server reads it: decoded once, comma arrays split (an encoded `%2C` too, as
+PHP decodes it before Spatie splits — so with the comma format a comma inside
+a free-text value reads back as a separator, exactly as the server sees it).
+Snapshot, not reactive — used by the writers below.
+
+The file is also the one URL writer every helper shares (`withQuery`,
+`visitUrl`): while a write's visit is in flight, every reader sees the URL it
+is heading to and every writer builds on it. So a sort and a direction set in
+one click both land, a filter change followed by `page = 1` keeps the filter,
+undoing a write before the server answers is not swallowed, and a ref reads
+back what was just written. Any visit that lands supersedes it. A write
+changes only its own keys: the other parameters keep their order and
+encoding, and a `#fragment` stays a fragment.
 
 ```ts
 // inertia-helpers/useQuery.ts
 // requires: npm i query-string
-import { usePage } from '@inertiajs/vue3';
+import type { VisitOptions } from '@inertiajs/core';
+import { router, usePage } from '@inertiajs/vue3';
 import qs, { type StringifyOptions } from 'query-string';
+import { shallowRef } from 'vue';
+
+/**
+ * How arrays sit in the query string, for every helper that reads or writes
+ * it: `tags=a,b`, what Spatie QueryBuilder parses. Change it here, once —
+ * a reader and a writer that disagree turn an array into a string.
+ */
+export const QUERY_ARRAY_FORMAT = 'comma';
+
+/** A URL's parts. The first `?` starts the query; a `#` ends it. */
+export const splitUrl = (url: string) => {
+	const hashAt = url.indexOf('#');
+	const hash = hashAt < 0 ? '' : url.slice(hashAt);
+	const rest = hashAt < 0 ? url : url.slice(0, hashAt);
+	const queryAt = rest.indexOf('?');
+	return queryAt < 0
+		? { path: rest, query: '', hash }
+		: { path: rest.slice(0, queryAt), query: rest.slice(queryAt + 1), hash };
+};
+
+/**
+ * The URL the last write is heading to, while its visit is in flight. Every
+ * reader and writer builds on it, so two writes before the server answers
+ * both land, and a write reads back at once. It counts only while `page.url`
+ * is still the one it was built on: any visit that lands supersedes it.
+ */
+const pending = shallowRef<{ from: string; url: string } | null>(null);
+
+/** `page.url`, or where the write in flight is taking it. */
+export const currentUrl = (): string => {
+	const { url } = usePage();
+	return pending.value?.from === url ? pending.value.url : url;
+};
+
+const decodeKey = (raw: string): string => {
+	try {
+		return decodeURIComponent(raw.replace(/\+/g, ' '));
+	} catch {
+		return raw;
+	}
+};
+
+/**
+ * `url` with `changes` written in. A nullish, empty-string or empty-array
+ * value removes its key. Every other parameter is kept as it was written, in
+ * its place: a write never re-encodes or re-orders what it does not own.
+ */
+export const withQuery = (
+	url: string,
+	changes: Record<string, unknown>
+): string => {
+	const { path, query, hash } = splitUrl(url);
+	const encoded = (key: string): string[] => {
+		const value = changes[key];
+		if (value == null || value === '') return [];
+		if (Array.isArray(value) && value.length === 0) return [];
+		return [
+			qs.stringify({ [key]: value }, { arrayFormat: QUERY_ARRAY_FORMAT }),
+		];
+	};
+	const written = new Set<string>();
+	const parts = query
+		.split('&')
+		.filter(Boolean)
+		.flatMap((part) => {
+			const key = decodeKey(part.split('=')[0] ?? '');
+			if (!(key in changes)) return [part];
+			if (written.has(key)) return [];
+			written.add(key);
+			return encoded(key);
+		});
+	Object.keys(changes)
+		.filter((key) => !written.has(key))
+		.forEach((key) => parts.push(...encoded(key)));
+	return `${path}${parts.length ? `?${parts.join('&')}` : ''}${hash}`;
+};
+
+/**
+ * Takes the page to `url`: an Inertia visit, or with `server: false` a URL
+ * write with no request. Readers see `url` from now until the visit finishes.
+ */
+export const visitUrl = (
+	url: string,
+	options: Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>,
+	server = true
+): void => {
+	const from = usePage().url;
+	const write = { from, url };
+	pending.value = write;
+	const settle = () => {
+		if (pending.value === write) pending.value = null;
+	};
+	if (server) {
+		let started = false;
+		router.visit(url, {
+			...options,
+			onStart: (visit) => {
+				started = true;
+				options.onStart?.(visit);
+			},
+			onFinish: (visit) => {
+				settle();
+				options.onFinish?.(visit);
+			},
+		});
+		// A visit a `before` listener refused never starts, and never finishes.
+		if (!started) settle();
+		return;
+	}
+	const { preserveState, preserveScroll, replace } = options;
+	const client = { url, preserveState, preserveScroll, onFinish: settle };
+	if (replace) router.replace(client);
+	else router.push(client);
+};
+
+/** The query of `url` as an object, the way the server reads it. */
+export const parseQuery = (
+	url: string,
+	arrayFormat: StringifyOptions['arrayFormat'] = QUERY_ARRAY_FORMAT
+): Record<string, unknown> => {
+	const { query } = splitUrl(url);
+	if (!query) return {};
+	// `qs.parse` decodes once. An encoded comma separates too: Laravel's pager
+	// links write `a%2Cb`, which PHP decodes to `a,b` before Spatie splits it.
+	return qs.parse(
+		arrayFormat === 'comma' ? query.replace(/%2C/gi, ',') : query,
+		{ arrayFormat }
+	);
+};
 
 export const useQuery = ({
-	arrayFormat = 'comma',
+	arrayFormat = QUERY_ARRAY_FORMAT,
 }: { arrayFormat?: StringifyOptions['arrayFormat'] } = {}): Record<
 	string,
 	unknown
-> => {
-	const { url } = usePage();
-	const [, queryString] = url.split('?');
-	if (!queryString) return {};
-	return qs.parse(decodeURIComponent(queryString), {
-		arrayFormat,
-		decode: true,
-	});
-};
+> => parseQuery(currentUrl(), arrayFormat);
 ```
 
 **Don't swap `query-string` for a hand-rolled `URLSearchParams` reader.** It
@@ -535,14 +815,19 @@ assume the parsed-array shape. Install the dependency.
 ### useRouteQuery
 
 A single query parameter as a **writable ref**. Reading tracks the current
-URL; writing merges the parameter and performs a (replace) visit, so the
-server re-renders with the new value. Writing the current value is a no-op —
-safe to sync from server responses without visit loops.
+URL (a repeated key reads its last value, as PHP does); writing merges the
+parameter and performs a (replace) visit, so the server re-renders with the
+new value. Writing the current value is a no-op — safe to sync from server
+responses without visit loops. Writing `null` / `undefined` or the default
+removes the key. Options, as on `useQueryObject`: `visitOptions` (Inertia's
+`VisitOptions`, merged over `preserveState` / `preserveScroll` /
+`replace: true`) and `server: false` for a URL write with no request.
 
 ```ts
 // inertia-helpers/useRouteQuery.ts
 // requires: npm i query-string
-import { router, usePage } from '@inertiajs/vue3';
+import { currentUrl, splitUrl, visitUrl, withQuery } from './useQuery';
+import type { VisitOptions } from '@inertiajs/core';
 import qs from 'query-string';
 import {
 	computed,
@@ -554,8 +839,15 @@ import {
 type Options<T> = {
 	/** Parse the raw string (e.g. `Number`). Defaults to identity. */
 	transform?: (value: string) => T;
-	preserveScroll?: boolean;
-	preserveState?: boolean;
+	/** `false` writes the URL with no request. Default `true`. */
+	server?: boolean;
+	/**
+	 * Merged over `{ preserveState, preserveScroll, replace: true }`. With
+	 * `server: false` only those three apply.
+	 */
+	visitOptions?: MaybeRefOrGetter<
+		Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>
+	>;
 };
 
 export function useRouteQuery<T = string>(
@@ -566,37 +858,34 @@ export function useRouteQuery<T = string>(
 ): WritableComputedRef<T> {
 	const {
 		transform = (value) => value as unknown as T,
-		preserveScroll = true,
-		preserveState = true,
+		server = true,
+		visitOptions,
 	} = options;
-	const page = usePage();
 
 	const readRaw = (): string => {
-		const [, queryString = ''] = page.url.split('?');
-		const raw = qs.parse(queryString)[key];
-		const single = Array.isArray(raw) ? raw[0] : raw;
+		const raw = qs.parse(splitUrl(currentUrl()).query)[key];
+		// A repeated key reads its last value, as PHP does.
+		const single = Array.isArray(raw) ? raw.at(-1) : raw;
 		return single != null ? String(single) : toValue(defaultValue);
 	};
 
 	return computed<T>({
 		get: () => transform(readRaw()),
 		set: (next) => {
-			const nextRaw = String(next);
+			// `null` / `undefined` mean "no value": the key leaves the URL.
+			const nextRaw = next == null ? toValue(defaultValue) : String(next);
 			if (nextRaw === readRaw()) return;
-
-			const [path = '', queryString = ''] = page.url.split('?');
-			const query = qs.parse(queryString);
-			if (nextRaw === toValue(defaultValue)) {
-				delete query[key]; // keep URLs clean at the default
-			} else {
-				query[key] = nextRaw;
-			}
-			const stringified = qs.stringify(query);
-			router.visit(stringified ? `${path}?${stringified}` : path, {
-				preserveScroll,
-				preserveState,
-				replace: true,
-			});
+			const value = nextRaw === toValue(defaultValue) ? null : nextRaw; // keep URLs clean at the default
+			visitUrl(
+				withQuery(currentUrl(), { [key]: value }),
+				{
+					preserveScroll: true,
+					preserveState: true,
+					replace: true,
+					...toValue(visitOptions),
+				},
+				server
+			);
 		},
 	});
 }
@@ -605,103 +894,120 @@ export function useRouteQuery<T = string>(
 ### useQueryObject
 
 The **filter engine**: watch a filters object and mirror its non-empty
-values into the query string with an Inertia visit per change. Keys it has
-seen are cleaned up when they empty out; the `page` parameter resets on
-every filter change so results are never hidden on an out-of-range page.
+values into the query string with one Inertia visit per change. Keys it has
+seen are cleaned up when they empty out; keys it does not own (a tab, a sort)
+are kept. Every change also removes `resetKeys` (default `['page']`), so
+results are never hidden on an out-of-range page.
+
+| Option         | Default    | What it does                                                                                                                                      |
+| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `visitOptions` | —          | Inertia's own `VisitOptions` (`only`, `headers`, `reset`, callbacks…), merged over `preserveState` / `preserveScroll` / `replace: true`           |
+| `debounce`     | `{}`       | Per-key wait in ms for typed keys: `{ search: 300 }`                                                                                              |
+| `resetKeys`    | `['page']` | Keys removed on every change. Passing it **replaces** the default: `['page', 'lots_page']`, or `[]` to keep the page                              |
+| `paused`       | `false`    | While `true`, track changes but send nothing; resuming sends the current state once (see below)                                                   |
+| `server`       | `true`     | `false` writes the URL with no request (`router.replace` / `push`); `visitOptions` then takes only `preserveState` / `preserveScroll` / `replace` |
+
+Arrays are written in the one `QUERY_ARRAY_FORMAT` of `useQuery.ts` (`comma`:
+`tags=a,b`, what Spatie QueryBuilder parses), the same one `useQuery` reads.
+To send server-shaped keys (`filter[status]`) or reshape values, pass a getter
+that builds them: `useQueryObject(() => ({ 'filter[status]': f.status }))`.
 
 ```ts
 // inertia-helpers/useQueryObject.ts
 // requires: npm i query-string
-import { useQuery } from './useQuery';
-import { isEmpty, isNil } from './utils';
-import { router, usePage } from '@inertiajs/vue3';
-import qs, { type StringifyOptions } from 'query-string';
+import {
+	QUERY_ARRAY_FORMAT,
+	currentUrl,
+	parseQuery,
+	visitUrl,
+	withQuery,
+} from './useQuery';
+import type { VisitOptions } from '@inertiajs/core';
+import qs from 'query-string';
 import { onScopeDispose, toValue, watch, type MaybeRefOrGetter } from 'vue';
 
+/** A server visit's options; the URL, method and data are the helper's. */
+type ServerVisitOptions = Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>;
+/** A URL-only write (`server: false`) has no request to configure. */
+type ClientVisitOptions = Pick<
+	VisitOptions,
+	'preserveState' | 'preserveScroll' | 'replace'
+>;
+
 type Options<T> = {
-	transform?: (value: Partial<T>) => Partial<T>;
-	/** Reset the `page` parameter on change. Default true. */
-	resetPage?: boolean;
-	/** Additional query keys removed whenever the object changes. */
+	/**
+	 * Query keys removed on every change. Default `['page']`, so a filter
+	 * change never strands the list on a page past its new end. Passing it
+	 * REPLACES the default: name `page` too when it should still reset.
+	 */
 	resetKeys?: string[];
-	/** Inertia partial reload prop names (supports reactive getter). */
-	only?: MaybeRefOrGetter<string[]>;
 	/**
-	 * When it resolves to `false` the watcher keeps tracking keys but skips
-	 * the navigation — use it when another owner performs the visit during a
-	 * programmatic transition, to avoid competing self-cancelling requests.
+	 * While it resolves to `true`, changes are tracked but no visit is sent.
+	 * When it goes back to `false`, the object's current state is sent once,
+	 * if the URL does not already hold it. See the guide for when to use it.
 	 */
-	shouldNavigate?: MaybeRefOrGetter<boolean>;
+	paused?: MaybeRefOrGetter<boolean>;
 	/**
 	 * Keys whose changes wait this many ms before the visit, e.g. a search
 	 * box: `{ search: 300 }`. A change to any other key visits at once and
 	 * carries the waiting value with it, so nothing typed is lost.
 	 */
 	debounce?: Partial<Record<keyof T & string, number>>;
-	arrayFormat?: StringifyOptions['arrayFormat'];
-	preserveState?: boolean;
-	preserveScroll?: boolean;
-	replace?: boolean;
-};
+} & (
+	| {
+			/** Default `true`: every change is an Inertia visit. */
+			server?: true;
+			/** Merged over `{ preserveState, preserveScroll, replace: true }`. */
+			visitOptions?: MaybeRefOrGetter<ServerVisitOptions>;
+	  }
+	| {
+			/** `false` writes the URL with no request (`router.replace` / `push`). */
+			server: false;
+			visitOptions?: MaybeRefOrGetter<ClientVisitOptions>;
+	  }
+);
 
 export function useQueryObject<T extends Record<string, unknown>>(
 	object: MaybeRefOrGetter<T>,
 	options: Options<T> = {}
 ): void {
 	const {
-		transform,
-		resetPage = true,
-		resetKeys = [],
-		preserveState = true,
-		preserveScroll = true,
-		replace = true,
-		only: onlyOption = [],
-		shouldNavigate = true,
+		resetKeys = ['page'],
+		paused = false,
 		debounce = {},
-		arrayFormat = 'comma',
+		server = true,
+		visitOptions,
 	} = options;
 
-	const filterValidValues = (obj: T): Partial<T> => {
-		const filtered: Partial<T> = {};
-		Object.entries(obj).forEach(([key, val]) => {
-			if (!isNil(val) && val !== '') {
-				(filtered as Record<string, unknown>)[key] = val;
-			}
-		});
-		return filtered;
-	};
-
 	/** Every key this composable has ever managed, for stable URL cleanup. */
 	const seenKeys = new Set<string>(Object.keys(toValue(object) ?? {}));
 
-	const navigate = (newObject: T) => {
-		const validValues = filterValidValues(newObject);
-		const transformedValues = transform ? transform(validValues) : validValues;
-
-		// Start from the existing query to preserve keys owned elsewhere.
-		const existingQuery = useQuery({ arrayFormat });
-		seenKeys.forEach((key) => delete existingQuery[key]);
-		if (resetPage) delete existingQuery.page;
-		resetKeys.forEach((key) => delete existingQuery[key]);
-
-		Object.entries(transformedValues).forEach(([key, val]) => {
-			if (!isEmpty(val)) existingQuery[key] = val;
-		});
-
-		const stringified = qs.stringify(existingQuery, { arrayFormat });
-		const newUrl = stringified
-			? [window.location.pathname, stringified].join('?')
-			: window.location.pathname;
+	/** A query in one canonical form, so encoding and key order never count. */
+	const canonical = (url: string) =>
+		qs.stringify(parseQuery(url), { arrayFormat: QUERY_ARRAY_FORMAT });
 
-		if (newUrl === usePage().url) return;
-		if (!toValue(shouldNavigate)) return;
-
-		router.visit(newUrl, {
-			preserveState,
-			preserveScroll,
-			only: toValue(onlyOption),
-			replace,
-		});
+	const navigate = (newObject: T) => {
+		if (toValue(paused)) return;
+
+		// Only the reset keys and the keys this object owns change; every
+		// other parameter (a tab, a sort) stays as it is.
+		const changes: Record<string, unknown> = {};
+		resetKeys.forEach((key) => (changes[key] = null));
+		seenKeys.forEach((key) => (changes[key] = newObject[key]));
+		const from = currentUrl();
+		const url = withQuery(from, changes);
+		if (canonical(url) === canonical(from)) return;
+
+		visitUrl(
+			url,
+			{
+				preserveState: true,
+				preserveScroll: true,
+				replace: true,
+				...toValue(visitOptions),
+			},
+			server
+		);
 	};
 
 	/** Each key's value as last seen, to tell which keys a change touched. */
@@ -714,8 +1020,8 @@ export function useQueryObject<T extends Record<string, unknown>>(
 	onScopeDispose(() => clearTimeout(pending));
 
 	watch(
-		() => toValue(object),
-		(newObject) => {
+		[() => toValue(object), () => toValue(paused)],
+		([newObject, isPaused], [, wasPaused]) => {
 			if (!newObject) return;
 
 			Object.keys(newObject).forEach((key) => {
@@ -734,12 +1040,15 @@ export function useQueryObject<T extends Record<string, unknown>>(
 			);
 			lastSeen = now;
 			clearTimeout(pending);
+			if (isPaused) return;
+			// Resuming sends what changed while paused, without waiting.
+			const resumed = wasPaused && !isPaused;
 			const waits = changed.map(
 				(key) => (debounce as Record<string, number | undefined>)[key] ?? 0
 			);
 			// Only debounced keys changed: wait for the typing to settle, then
 			// visit with whatever the object holds by then.
-			if (changed.length && waits.every((ms) => ms > 0)) {
+			if (!resumed && changed.length && waits.every((ms) => ms > 0)) {
 				pending = setTimeout(
 					() => navigate(toValue(object)),
 					Math.max(...waits)
@@ -753,7 +1062,8 @@ export function useQueryObject<T extends Record<string, unknown>>(
 		 * into one watcher run, so a `clearFilters()` that blanks three keys
 		 * fires ONE visit instead of three (measured: 3 writes → 3 runs under
 		 * `sync`, 1 under the default). The two it saves used to self-cancel,
-		 * but they were still sent.
+		 * but they were still sent. Watching `paused` in the same source means
+		 * resuming and the change that comes with it are one run, one visit.
 		 *
 		 * This does NOT make typing cheap on its own — one visit per settled
 		 * keystroke is still one visit per keystroke. `debounce` is for that.
@@ -766,7 +1076,10 @@ export function useQueryObject<T extends Record<string, unknown>>(
 ```ts
 // A listing page's whole filter wiring:
 const filters = reactive({ search: '', status: null as string | null });
-useQueryObject(filters, { only: ['invoices'], debounce: { search: 300 } });
+useQueryObject(filters, {
+	visitOptions: { only: ['invoices'] },
+	debounce: { search: 300 },
+});
 // Bind BbTextInput / BbSelectPopover to `filters.*` — every change becomes a
 // partial reload and the server re-renders the `invoices` prop.
 ```
@@ -775,9 +1088,9 @@ useQueryObject(filters, { only: ['invoices'], debounce: { search: 300 } });
 > their own URL writers (the `page` / `perPage` refs of
 > `usePaginatedResponseContext`, or `useRouteQuery`). Put the page ref in the
 > object too and a pager click visits twice: once through the ref, once
-> through this watcher. And `resetPage` stops working: `navigate()` deletes
-> `page` from the query, then writes the object's value back, so a filter
-> change keeps the old page, possibly past the last one.
+> through this watcher. And the page reset stops working: `navigate()`
+> deletes `page` from the query, then writes the object's value back, so a
+> filter change keeps the old page, possibly past the last one.
 
 > **Typing: debounce the key, not the page.** Without `debounce`, "an
 > Inertia visit per change" is literal: a text field bound straight to
@@ -787,16 +1100,63 @@ useQueryObject(filters, { only: ['invoices'], debounce: { search: 300 } });
 >
 > ```ts
 > const filters = reactive({ search: '', status: null as string | null });
-> useQueryObject(filters, { only: ['invoices'], debounce: { search: 300 } });
+> useQueryObject(filters, {
+> 	visitOptions: { only: ['invoices'] },
+> 	debounce: { search: 300 },
+> });
 > ```
 >
 > Typing in the search waits 300 ms of quiet; picking a status visits at once
 > and takes the typed text with it. Keys not named in `debounce` never wait.
->
-> **Programmatic multi-key writes** (reset, apply-a-saved-view): gate them
-> with `shouldNavigate` and perform the one visit yourself once the object is
-> settled. That is what the option is for: the watcher keeps tracking keys
-> for URL cleanup while the navigation is yours.
+
+> **Programmatic multi-key writes need nothing.** A reset or an
+> apply-a-saved-view that writes several keys in one tick is already one
+> visit: the watcher runs once per tick. Do not reach for `paused` for this.
+
+#### `paused`: when another visit owns the page for a while
+
+Use it when something else sends a visit that also changes keys this object
+mirrors, and that visit takes time: a view switch whose own `router.get`
+rewrites the filters, a wizard step that navigates and seeds the next step's
+filters. Without it, the object's watcher fires on the next tick with the
+seeded values and sends a second visit; Inertia cancels the first (the one
+that mattered) in favour of it.
+
+```ts
+const switching = ref(false);
+useQueryObject(filters, {
+	visitOptions: { only: ['conversations'] },
+	paused: switching,
+});
+
+const switchView = (view: string) => {
+	switching.value = true;
+	Object.assign(filters, filtersFor(view)); // tracked, not sent
+	router.get(
+		`/inbox/${view}`,
+		{},
+		{
+			onFinish: () => (switching.value = false), // also runs on cancel
+		}
+	);
+};
+```
+
+What happens, exactly:
+
+- **While `paused` is `true`**, every change is tracked (key cleanup, the
+  debounce bookkeeping) and nothing is sent. A debounced change already
+  waiting when the pause starts is dropped, not sent late.
+- **When it goes back to `false`**, the object's _current_ state is sent once,
+  without waiting for a debounce. If the URL already holds that state — the
+  other visit landed exactly these filters, the usual case — nothing is sent.
+  Resuming and a change in the same tick are one visit.
+- It is a **span over time**, not a tick guard: set and cleared in the same
+  tick, it pauses nothing (the watcher runs after the tick, when it is already
+  `false`). Clear it in the competing visit's `onFinish`, which Inertia also
+  calls when that visit is cancelled or fails, so the object never stays
+  paused.
+- It accepts a ref or a getter: `paused: () => form.processing`.
 
 ---
 
@@ -807,31 +1167,50 @@ counterpart of the component-state context
 [`useBbTableContext`](../composables/useBbTableContext.md). Rule of thumb:
 `useBbTableContext` mirrors what the _table widget_ is doing (selection,
 sort, highlight); these contexts own what the _server sent_ (items, meta)
-and survive being read from any component on the page. First caller creates
-the context, later callers join it — no provider component required.
+and survive being read from any component on the page. The first caller
+creates the context and every later caller **below it** joins it — no
+provider component, but siblings (a table and a bulk bar) share one only
+when a common parent (the page) calls it first; each would otherwise create
+its own.
 
 ### usePaginatedResponseContext
 
 Wraps a Laravel paginated prop (`PaginatedResponse<T>`) into a shared
-context: `items` (editable until the prop changes), `totalItems`,
-`totalPages`, and `page` / `perPage` refs that read what the server answered
-and visit when written (`page` at 1 and `per_page` at the server's default
-leave the URL).
+context: `items` (a deep copy of the rows: `v-model` a row's field for inline
+editing without touching the page prop; editable until the prop changes),
+`totalItems`, `totalPages`, and `page` / `perPage` refs that read what the
+server answered and visit when written (`page` at 1 and `per_page` at the
+server's default leave the URL; a new `perPage` starts again from page 1). A
+missing or deferred prop reads as an empty page.
+
+**When `items` resets.** A server visit that asks for this prop (a pager
+click, a filter, `router.reload({ only: ['users'] })`) always brings fresh
+rows, even identical ones: reloading after a failed delete undoes the
+optimistic edit. Anything else that swaps the prop — `router.appendToProp`
+on another prop rebuilds every prop, a reload of another prop, Back /
+Forward — keeps your edits unless the rows really changed. Anything past
+that (rolling back a failed edit, merging a concurrent change) is the app's.
 
 ```ts
 // inertia-helpers/usePaginatedResponseContext.ts
-import { useRouteQuery } from './useRouteQuery';
+// requires: npm i query-string
+import { currentUrl, visitUrl, withQuery } from './useQuery';
 import type { PaginatedResponse } from './types';
-import { isNotNil } from './utils';
-import type { PageProps } from '@inertiajs/core';
-import { usePage } from '@inertiajs/vue3';
+import { cloneDeep, isEqual, isNotNil } from './utils';
+import type { PageProps, VisitOptions } from '@inertiajs/core';
+import { router, usePage } from '@inertiajs/vue3';
 import { injectLocal, provideLocal } from '@vueuse/core';
 import {
 	computed,
+	onMounted,
+	onScopeDispose,
 	ref,
+	shallowRef,
+	toValue,
 	watch,
 	watchEffect,
 	type ComputedRef,
+	type MaybeRefOrGetter,
 	type Ref,
 } from 'vue';
 
@@ -840,10 +1219,21 @@ export type PaginatedResponseContext<T> = {
 	perPage: Ref<number>;
 	page: Ref<number>;
 	totalPages: ComputedRef<number>;
-	/** Current page items. Writable for optimistic edits; resets on navigation. */
+	/** Current page items, a deep copy: edit it freely; resets on a new answer. */
 	items: Ref<T[]>;
 };
 
+export type PaginatedResponseOptions = {
+	/** The query key the server reads the page from (Laravel's `pageName`). Default `'page'`. */
+	pageQueryKey?: string;
+	/** The query key the server reads the page size from. Default `'per_page'`. */
+	perPageQueryKey?: string;
+	/** Merged over `{ preserveState, preserveScroll }` and the history default (a page pushes, a size replaces). */
+	visitOptions?: MaybeRefOrGetter<
+		Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>
+	>;
+};
+
 const toContextKey = (key: string): string => `${key}:paginatedResponse`;
 
 /**
@@ -851,30 +1241,40 @@ const toContextKey = (key: string): string => `${key}:paginatedResponse`;
  * fields under `meta` (a resource collection, a hand-built shape) or at the
  * top level (`->paginate()`, `->simplePaginate()`). `simplePaginate()` knows
  * no total: the count is the rows so far, and the last page is the next one
- * while a next page exists.
+ * while a next page exists, or the one before an empty page past the end.
  */
 export const readPagination = (paginated: PaginatedResponse<unknown>) => {
 	const fields = paginated.meta ?? paginated;
 	const current = fields.current_page ?? 1;
 	const perPage = fields.per_page ?? 10;
+	const rows = paginated.data?.length ?? 0;
 	const links = paginated.links as { next?: string | null } | undefined;
 	const hasNext = !!(
 		fields.next_page_url ?? (Array.isArray(links) ? null : links?.next)
 	);
+	const pastEnd = !rows && !hasNext && current > 1;
 	return {
 		current,
 		perPage,
-		lastPage: fields.last_page ?? (hasNext ? current + 1 : current),
+		lastPage:
+			fields.last_page ??
+			(hasNext ? current + 1 : pastEnd ? current - 1 : current),
 		total:
 			fields.total ??
-			(current - 1) * perPage +
-				(paginated.data?.length ?? 0) +
-				(hasNext ? 1 : 0),
+			(pastEnd ? 0 : (current - 1) * perPage + rows + (hasNext ? 1 : 0)),
 	};
 };
 
+const isCount = (value: number): boolean =>
+	Number.isInteger(value) && value > 0;
+
 export const usePaginatedResponseContext = <T = object>(
-	dataKey: string
+	dataKey: string,
+	{
+		pageQueryKey = 'page',
+		perPageQueryKey = 'per_page',
+		visitOptions,
+	}: PaginatedResponseOptions = {}
 ): PaginatedResponseContext<T> => {
 	const existing = injectLocal<PaginatedResponseContext<T> | null>(
 		toContextKey(dataKey),
@@ -893,18 +1293,46 @@ export const usePaginatedResponseContext = <T = object>(
 	const inertiaPage = usePage<
 		PageProps & Record<string, PaginatedResponse<T>>
 	>();
+	// A deferred, optional or not-yet-reloaded prop reads as an empty page.
 	const paginated = computed(
-		() => inertiaPage.props[dataKey] as PaginatedResponse<T>
+		(): PaginatedResponse<T> => inertiaPage.props[dataKey] ?? { data: [] }
 	);
 
 	const pagination = computed(() => readPagination(paginated.value));
-	const items = ref<T[]>(paginated.value.data ?? []) as Ref<T[]>;
+	// A deep copy: inline edits (`v-model` on a row's field) stay off the page
+	// prop, so the "rows really changed" check below compares two things.
+	const items = ref<T[]>(cloneDeep(paginated.value.data ?? [])) as Ref<T[]>;
 	const totalItems = computed(() => pagination.value.total);
 	const totalPages = computed(() => pagination.value.lastPage);
 
-	// A new prop is a new answer (a visit, Back / Forward); a partial reload of
-	// another prop keeps this one, and the edits made to `items`.
-	watch(paginated, (fresh) => (items.value = fresh.data ?? []));
+	// Server visits in flight that ask for this prop (a pager click, a filter,
+	// `router.reload({ only: [dataKey] })`).
+	const asking = new Set<unknown>();
+	const asks = ({ only, except }: { only: string[]; except: string[] }) =>
+		only.length ? only.includes(dataKey) : !except.includes(dataKey);
+	const unbindStart = router.on('start', ({ detail: { visit } }) => {
+		if (asks(visit)) asking.add(visit);
+	});
+	const unbindFinish = router.on('finish', ({ detail: { visit } }) => {
+		asking.delete(visit);
+	});
+	onScopeDispose(() => {
+		unbindStart();
+		unbindFinish();
+	});
+
+	// A visit that asked for this prop is a new answer: fresh rows, the edits
+	// made to `items` go. Anything else that swaps the prop (`appendToProp` on
+	// another prop rebuilds them all, Back / Forward) keeps the edits unless the
+	// rows really changed. `sync`: the answer lands before its visit finishes.
+	watch(
+		paginated,
+		(fresh, old) => {
+			if (!asking.size && isEqual(fresh.data, old.data)) return;
+			items.value = cloneDeep(fresh.data ?? []);
+		},
+		{ flush: 'sync' }
+	);
 
 	// The server's default page size is what it answers a URL without
 	// `per_page`. Until such an answer arrives it is unknown (`''` matches no
@@ -913,24 +1341,74 @@ export const usePaginatedResponseContext = <T = object>(
 	const defaultPerPage = ref('');
 	watchEffect(() => {
 		const [, queryString = ''] = inertiaPage.url.split('?');
-		if (!new URLSearchParams(queryString).has('per_page'))
+		if (!new URLSearchParams(queryString).has(perPageQueryKey))
 			defaultPerPage.value = `${pagination.value.perPage}`;
 	});
-	const pageQuery = useRouteQuery('page', '1');
-	const perPageQuery = useRouteQuery('per_page', defaultPerPage);
+
+	// Where the last pager write is going, while its visit is in flight: a
+	// second click before the answer builds on it ("next" twice is page 3).
+	const target = shallowRef<{ url: string; page: number; perPage: number }>();
+	const inFlight = () => {
+		const write = target.value;
+		return write?.url === currentUrl() && write.url !== inertiaPage.url
+			? write
+			: undefined;
+	};
+	const go = (to: number, size?: number, extra?: { replace: true }) => {
+		const url = withQuery(currentUrl(), {
+			[pageQueryKey]: to === 1 ? null : to,
+			...(isNotNil(size) && {
+				[perPageQueryKey]: `${size}` === defaultPerPage.value ? null : size,
+			}),
+		});
+		target.value = { url, page: to, perPage: size ?? perPage.value };
+		visitUrl(url, {
+			preserveScroll: true,
+			preserveState: true,
+			// A page is a history entry (Back goes to the previous page); a new
+			// size is a setting and replaces.
+			replace: isNotNil(size),
+			...toValue(visitOptions),
+			...extra,
+		});
+	};
 
 	// Both read the server's answer, not the URL: a clamped `?page=99`, a
 	// capped `?per_page=500` or a redirect to the bare URL shows what the
-	// server sent. Writing one visits, and only when the URL changes.
+	// server sent. Writing one visits when it changes what they show; a size
+	// starts again from page 1. Junk (0, NaN, 2.5, past a known last page) is
+	// ignored.
 	const page = computed({
-		get: () => pagination.value.current,
-		set: (next: number) => (pageQuery.value = `${next}`),
+		get: () => inFlight()?.page ?? pagination.value.current,
+		set: (next: number) => {
+			const last = (paginated.value.meta ?? paginated.value).last_page;
+			if (!isCount(next) || (isNotNil(last) && next > last)) return;
+			if (next !== page.value) go(next);
+		},
 	});
 	const perPage = computed({
-		get: () => pagination.value.perPage,
-		set: (next: number) => (perPageQuery.value = `${next}`),
+		get: () => inFlight()?.perPage ?? pagination.value.perPage,
+		set: (next: number) => {
+			if (isCount(next) && next !== perPage.value) go(1, next);
+		},
 	});
 
+	// Laravel's `paginate()` does not clamp: `?page=3` after page 3's last row
+	// went answers an empty page 3 of 2. Go to the last page, once per answer.
+	let clampedFrom = '';
+	onMounted(() =>
+		watch(
+			pagination,
+			({ current, lastPage }) => {
+				if (current <= lastPage || lastPage < 1) return;
+				if (clampedFrom === inertiaPage.url) return;
+				clampedFrom = inertiaPage.url;
+				go(lastPage, undefined, { replace: true });
+			},
+			{ immediate: true }
+		)
+	);
+
 	const context: PaginatedResponseContext<T> = {
 		totalItems,
 		perPage,
@@ -963,6 +1441,38 @@ return Inertia::render('Admin/Users/Index', [
 one while a next page exists) and `totalPages` ends at the next page, so a
 pager shows "next" until the last page.
 
+**`->cursorPaginate()` is not supported.** It has no page numbers (only
+`next_cursor` / `prev_cursor` links), so `page` would read 1 on every page
+and "next" would visit a `?page=2` Laravel ignores. Use `->paginate()` or
+`->simplePaginate()` with this context.
+
+**A page is a history entry.** Writing `page` pushes, so Back goes to the
+previous page; a new `perPage` (a setting) and filter writes replace. Pass
+`visitOptions: { replace: true }` to keep the pager out of history.
+
+**A page past the last goes to the last.** Laravel does not clamp: delete
+the last row of page 3 and `?page=3` answers an empty page 3 of 2. The
+context visits the last page once (`replace`); an empty `simplePaginate()`
+page past the first goes back one.
+
+**Writes before the answer build on each other.** While a pager visit is in
+flight, `page` / `perPage` read where it is going, so "next" clicked twice
+lands two pages on, and a click right after a filter or size change keeps
+it. A write equal to what they show, a page that is not a positive integer,
+or a page past a known last page makes no visit.
+
+Options (the second argument, also taken by `useTableContext`):
+
+- `pageQueryKey` / `perPageQueryKey` — the query keys the server reads
+  (defaults `'page'` / `'per_page'`). A paginator with its own page name,
+  `->paginate(15, ['*'], 'lots_page')`, takes
+  `usePaginatedResponseContext('lots', { pageQueryKey: 'lots_page' })` — and
+  two tables on one page need one each.
+- `visitOptions` — merged over `{ preserveState, preserveScroll, replace:
+true }` on every pager visit, a ref or getter read each time. Without it a
+  page change reloads every prop; `{ only: ['users'] }` reloads the table
+  alone.
+
 ### useTableSelectionContext
 
 Shared selection state by key, in server terms: `selected` and `unselected`
@@ -971,6 +1481,12 @@ item lists plus the `all` flag ("select-all across pages" semantics — when
 combines `all` + `unselected` instead). Bind these to `BbTable`'s
 `v-model`, `v-model:unselected-items` and `v-model:select-all`.
 
+The selection is never reset for you: it survives page changes (that is
+the cross-page feature) and filter changes alike, since the URL also holds
+state that has nothing to do with the table. When a bulk action must not
+reach rows the new filter hides, call `resetSelection()` where the filters
+change, e.g. `watch(filters, resetSelection, { deep: true })`.
+
 ```ts
 // inertia-helpers/useTableSelectionContext.ts
 import { isNotNil } from './utils';
@@ -1034,6 +1550,7 @@ builds on.
 import {
 	usePaginatedResponseContext,
 	type PaginatedResponseContext,
+	type PaginatedResponseOptions,
 } from './usePaginatedResponseContext';
 import {
 	useTableSelectionContext,
@@ -1048,7 +1565,9 @@ export type TableContext<T, U> = TableSelectionContext<U> &
 const toTableKey = (key: string): string => `${key}:table`;
 
 export const useTableContext = <T = object, U = T>(
-	dataKey: string
+	dataKey: string,
+	/** For the paginated half: query keys and pager visit options. */
+	options?: PaginatedResponseOptions
 ): TableContext<T, U> => {
 	const existing = injectLocal<TableContext<T, U> | null>(
 		toTableKey(dataKey),
@@ -1058,7 +1577,7 @@ export const useTableContext = <T = object, U = T>(
 
 	const context: TableContext<T, U> = {
 		...useTableSelectionContext<U>(dataKey),
-		...usePaginatedResponseContext<T>(dataKey),
+		...usePaginatedResponseContext<T>(dataKey, options),
 	};
 
 	provideLocal(toTableKey(dataKey), context);
@@ -1070,7 +1589,10 @@ Gotchas:
 
 - The key is a rendezvous string (use the page-prop name, e.g.
   `'invoices'`). Like the library's table context, a typo doesn't error —
-  it silently creates a second, orphan context.
+  it silently creates a second, orphan context. So does a sibling: call it
+  in the page (or a parent of every reader) first.
+- The selection outlives a filter change (it is cross-page by design). Call
+  `resetSelection()` where the filter changes when the old picks must go.
 - Each composite context provides under a namespaced key
   (`invoices:table`, `invoices:selection`, `invoices:paginatedResponse`),
   so the pieces can also be joined individually.
@@ -1104,9 +1626,14 @@ submit, chain a toast, or hand the promise to a `BbButton` `@click` /
 Inertia form — `form.errors`, `form.isDirty`, `form.reset()` all work.
 
 The promise resolves `true` when the server answered and `false` when the visit
-was cancelled (a `before` listener such as `useConfirmOnRouteLeave`, `cancel()`)
-or interrupted by a newer one: nothing was saved, so skip the success toast and
-the re-baseline (`if (!(await put(url))) return;`) and the form stays dirty.
+was cancelled (its own `onBefore` returning false, a `before` listener such as
+`useConfirmOnRouteLeave`, `cancel()`) or interrupted by a newer one: nothing was
+saved, so skip the success toast and the re-baseline
+(`if (!(await put(url))) return;`) and the form stays dirty. A save the server
+answers with a redirect to a `#fragment` (Inertia's 409 follow-up visit) or with
+`Inertia::location()` resolves `true`; an Inertia-rendered error page (a 403 /
+500 with your custom error component) rejects. Your own `onSuccess` / `onError`
+/ `onFinish` options still run.
 
 **Declare the draft shape as a `type` alias, not an `interface`.** The generic
 is constrained to `Record<string, FormValue>` (what Inertia can serialize), and
@@ -1119,6 +1646,7 @@ TypeScript quirk, not a statement about your data.
 // inertia-helpers/usePromiseForm.ts
 import { useLoading } from './useLoading';
 import {
+	router,
 	useForm,
 	type InertiaForm,
 	type InertiaFormProps,
@@ -1136,6 +1664,17 @@ type FormValue =
 
 type Options = Parameters<InertiaFormProps<object>['get']>[1];
 
+// Inertia 3's per-visit failure callbacks. Inertia 2 has none (it ignores
+// them), only the global `invalid` / `exception` events, heard below.
+type FailureCallbacks = {
+	onHttpException?: (response: { status: number }) => boolean | void;
+	onNetworkError?: (error: unknown) => boolean | void;
+};
+const onRouterEvent = (
+	name: string,
+	listener: (event: CustomEvent) => void
+): (() => void) => router.on(name as 'start', listener as never);
+
 export const usePromiseForm = <T extends Record<string, FormValue>>(
 	initialData: T
 ) => {
@@ -1150,34 +1689,129 @@ export const usePromiseForm = <T extends Record<string, FormValue>>(
 		): Promise<boolean> =>
 			// true: the server answered and the save went through. false: the
 			// visit was cancelled or interrupted, nothing to report. Rejects with
-			// the error bag, or for a response that is not Inertia's.
-			new Promise<boolean>((resolve, reject) => {
-				const { onFinish: userOnFinish, ...visitOptions } = options;
+			// the error bag, or for an error page / a response that is not Inertia's.
+			new Promise<boolean>((resolvePromise, rejectPromise) => {
+				const {
+					onBefore,
+					onSuccess,
+					onError,
+					onHttpException,
+					onNetworkError,
+					onFinish,
+					...visitOptions
+				} = options as NonNullable<Options> & FailureCallbacks;
+				// Visits sent with these callbacks, and how many finished: a save
+				// answered with a 409 redirect (a redirect with a #fragment) is
+				// re-sent by Inertia itself with the same callbacks, and that
+				// follow-up interrupts the first visit. The last one settles.
+				let sent = 0;
+				let finished = 0;
+				let awaitingBefore = false;
+				let failedStatus: number | null = null;
+				// Inertia 2: a non-Inertia response or a network error is a global
+				// event only, fired before the visit finishes. Heard while this
+				// promise is open (an async reload failing meanwhile counts too).
+				const unbindFailures = [
+					onRouterEvent('invalid', ({ detail }) => {
+						failedStatus = (detail as { response: { status: number } }).response
+							.status;
+					}),
+					onRouterEvent('exception', () => void (failedStatus = 0)),
+				];
+				const settle = () => {
+					unbind();
+					unbindFailures.forEach((unbindFailure) => unbindFailure());
+				};
+				const resolve = (value: boolean) => {
+					settle();
+					resolvePromise(value);
+				};
+				const reject = (error: unknown) => {
+					settle();
+					rejectPromise(error);
+				};
+				// A visit stopped before it starts (its own onBefore returning
+				// false, below, or a `before` listener that refuses it) fires no
+				// callback at all: no save, resolve false. Registered last, this
+				// listener sees what the ones before it decided.
+				const unbind = router.on('before', (event) => {
+					if (!awaitingBefore) return;
+					awaitingBefore = false;
+					if (!event.defaultPrevented) return;
+					// Held by useConfirmOnRouteLeave's dialog: "Discard changes"
+					// re-sends it with these callbacks, "Keep editing" finishes it
+					// as cancelled. Either one settles this promise.
+					if (
+						(event.detail.visit as { awaitingConfirm?: boolean })
+							.awaitingConfirm
+					)
+						return;
+					if (--sent === finished) resolve(false);
+				});
 
 				form[method](url, {
 					...visitOptions,
-					onSuccess: () => resolve(true),
-					onError: (errors: unknown) => reject(errors),
+					onBefore: (visit) => {
+						const answer = onBefore?.(visit);
+						if (answer === false) {
+							if (sent === finished) resolve(false);
+						} else {
+							sent++;
+							awaitingBefore = true;
+						}
+						return answer;
+					},
+					onSuccess: (page) => {
+						onSuccess?.(page);
+						// An error page Inertia renders (a 403 / 500 with `x-inertia`)
+						// lands like a success: it is not a save.
+						if (failedStatus === null) resolve(true);
+						else reject(new Error(`Inertia visit answered ${failedStatus}.`));
+					},
+					onError: (errors) => {
+						onError?.(errors);
+						reject(errors);
+					},
+					...({
+						onHttpException: (response) => {
+							failedStatus = response.status;
+							return onHttpException?.(response);
+						},
+						onNetworkError: (error) => {
+							failedStatus = 0;
+							return onNetworkError?.(error);
+						},
+					} satisfies FailureCallbacks),
 					onFinish: (
 						...args: Parameters<NonNullable<NonNullable<Options>['onFinish']>>
 					) => {
-						userOnFinish?.(...args);
-						// A cancelled visit (`cancel()`, a `before` listener such as
-						// useConfirmOnRouteLeave's "Keep editing") or one a newer visit
+						onFinish?.(...args);
+						finished++;
+						// A cancelled visit (`cancel()`) or one a newer visit
 						// interrupted is no failure, and no save either: it reaches
-						// only onFinish. Resolve false.
+						// only onFinish. Resolve false, unless it is Inertia's own
+						// 409 follow-up that interrupted it: that one settles.
 						const [visit] = args as unknown as [
 							{ cancelled?: boolean; interrupted?: boolean } | undefined,
 						];
 						if (visit?.cancelled || visit?.interrupted) {
-							resolve(false);
+							if (sent <= finished) resolve(false);
 							return;
 						}
 						// A non-Inertia response (e.g. a 423 entity lock or a 419
-						// CSRF mismatch) fires neither onSuccess nor onError, only
-						// onFinish. Settle here so isSubmitting is released instead
-						// of hanging the form forever. No-op once already settled.
-						reject(new Error('Inertia visit did not return a valid response.'));
+						// CSRF mismatch) or a network error fires neither onSuccess
+						// nor onError, only onFinish. Settle here so isSubmitting is
+						// released instead of hanging the form forever. No-op once
+						// already settled.
+						if (failedStatus !== null) {
+							reject(
+								new Error('Inertia visit did not return a valid response.')
+							);
+							return;
+						}
+						// `Inertia::location()` (an external redirect after the save)
+						// fires only onFinish too, while the browser leaves.
+						resolve(true);
 					},
 				});
 			})
@@ -1207,6 +1841,26 @@ export const usePromiseForm = <T extends Record<string, FormValue>>(
 > have nothing else to do on rejection. Every call site in this guide and its
 > recipes follows one of those two shapes — copy them, not a bare `post(...)`.
 
+**A summary line over the form is the page's, not the helper's.** The
+rejection tells the two failures apart: the error bag (an object, already in
+`form.errors`) or an `Error` (the server answered with something that is not
+Inertia's). Word them in the `catch`:
+
+```ts
+const failure = ref('');
+const save = async () => {
+	failure.value = '';
+	try {
+		await put(`/invoices/${invoice.id}`);
+	} catch (error) {
+		failure.value =
+			error instanceof Error
+				? 'The save did not go through. Try again.'
+				: 'Check the highlighted fields.';
+	}
+};
+```
+
 **Seeding a draft: `NullableKeys<T>`, not a hand-rolled `| null` on every
 field.** Don't declare a bespoke `Draft` type that bolts `| null` onto each
 string prop by hand — that's what produces empty-string drafts (`''`
@@ -1251,57 +1905,86 @@ const { form } = usePromiseForm<NullableKeys<InvoiceRequest>>({
 
 Deep dirty-checking against a snapshot baseline — for edit screens whose
 state is not a single Inertia form (multiple forms, ad-hoc refs). For a
-single `usePromiseForm`, prefer the built-in `form.isDirty`.
+single `usePromiseForm`, prefer the built-in `form.isDirty`. The baseline is
+a structural hash of each value, so Dates, Sets, Maps, `undefined` and NaN
+compare as they are, and a `File` by its name, size, type and date, so picking
+another file over a picked one counts.
 
 ```ts
 // inertia-helpers/useHasChanged.ts
-import { isEqual } from './utils';
+import { isPlainObject } from './utils';
+import { hash } from 'object-code';
 import { computed, ref, toValue, type WatchSource } from 'vue';
 
 export function useHasChanged<T extends WatchSource<unknown>[]>(
 	dependencies: T
 ) {
 	/*
-	 * Baselines are JSON round-trips, NOT `structuredClone`. This composable's
-	 * documented inputs are refs and reactive objects, and `structuredClone`
-	 * throws `DataCloneError` on every one of them — a Vue proxy is not a
-	 * structured-cloneable type. It took the page down at setup.
-	 *
-	 * The comparison needs no copy at all: `isEqual` is hash-based and reads
-	 * straight through a proxy, so the live value can be hashed as-is. Only the
-	 * BASELINE needs detaching from live state, which is what the round-trip is
-	 * for.
+	 * The baseline is a structural HASH, not a copy. A copy has to survive the
+	 * values a form holds: a JSON round-trip turns a Date into a string, a File,
+	 * Set or Map into `{}`, drops `undefined` (and throws on a bare one), so
+	 * an untouched form read as changed; `structuredClone` throws on Vue proxies.
+	 * `object-code` hashes straight through a proxy and keeps Dates (by time),
+	 * Sets / Maps (by entries), `undefined` and NaN apart, and a number is all
+	 * the baseline needs to hold. It hashes every File alike (no own keys), so
+	 * a File is read by name, size, type and date first: picking another file
+	 * over a picked one counts as a change.
 	 */
 	const snapshot = (dep: WatchSource<unknown>) =>
-		JSON.parse(JSON.stringify(toValue(dep)));
+		hash(withFileFingerprints(toValue(dep)));
 
-	const baselineValues = ref<unknown[]>(dependencies.map(snapshot));
+	const baselines = ref<number[]>(dependencies.map(snapshot));
 
 	/** Re-baseline (call after a successful save). */
 	const takeSnapshot = (): void => {
-		baselineValues.value = dependencies.map(snapshot);
+		baselines.value = dependencies.map(snapshot);
 	};
 
 	const hasChanged = computed(() =>
-		dependencies.some(
-			(dep, index) => !isEqual(toValue(dep), baselineValues.value[index])
-		)
+		dependencies.some((dep, index) => snapshot(dep) !== baselines.value[index])
 	);
 
 	return { hasChanged, takeSnapshot };
 }
+
+const withFileFingerprints = (value: unknown): unknown =>
+	value instanceof Blob
+		? [
+				value.size,
+				value.type,
+				(value as Partial<File>).name,
+				(value as Partial<File>).lastModified,
+			]
+		: Array.isArray(value)
+			? value.map(withFileFingerprints)
+			: isPlainObject(value)
+				? Object.fromEntries(
+						Object.entries(value).map(([key, item]) => [
+							key,
+							withFileFingerprints(item),
+						])
+					)
+				: value;
 ```
 
 ### useConfirmOnRouteLeave
 
 A dirty-state navigation guard: intercepts Inertia visits and asks through
 [`useConfirm`](../composables/useConfirm.md) before leaving. Requires
-`<BbHost />` mounted in the app root. Server redirects after a
-whitelisted action carry the `X-Whitelisted-Action` header so a saving
-visit's redirect is never blocked by its own guard.
+`<BbHost />` mounted in the app root. `whitelist` names the form's own
+submit targets: a submit (POST / PUT / PATCH / DELETE) to one of them goes
+out without asking, while a plain link to the same path (a Cancel button
+back to `/invoices`) still asks. Server redirects after a whitelisted
+action carry the `X-Whitelisted-Action` header so a saving visit's redirect
+is never blocked by its own guard. Leaving the app (closing the tab,
+reloading, a typed URL, a plain `<a>`) gets the browser's own "Leave site?"
+prompt while the guard is armed; a whitelisted save that the server answers
+with `Inertia::location()` leaves without one. `stack` picks the `BbDialog`
+stack the dialog joins; `variant` defaults to `'destructive'`.
 
 ```ts
 // inertia-helpers/useConfirmOnRouteLeave.ts
+import { useHelperMessages } from './messages';
 import { router } from '@inertiajs/vue3';
 import { useConfirm, type BbConfirmMessage } from 'bitboss-ui';
 import { onScopeDispose, toValue, type MaybeRefOrGetter } from 'vue';
@@ -1315,7 +1998,11 @@ type Visit = {
 };
 
 type Options = {
-	/** URLs that bypass the dialog (e.g. the form's own submit target). */
+	/**
+	 * Submit targets that bypass the dialog (the form's own save). Only a
+	 * submit (POST / PUT / PATCH / DELETE) passes: a link to the same path
+	 * (Cancel → the list) still asks.
+	 */
 	whitelist?: MaybeRefOrGetter<string[]>;
 	/** Disable the guard (bind to `!hasChanged` / `!form.isDirty`). */
 	disabled?: MaybeRefOrGetter<boolean>;
@@ -1327,12 +2014,14 @@ type Options = {
 	text?: string;
 	/**
 	 * The dialog's buttons and look, BbConfirm's own options: a label string
-	 * or a full button config. Defaults: `'Discard changes'` / `'Keep editing'`,
-	 * `variant: 'destructive'`. Pass translated labels in a non-English app.
+	 * or a full button config. Default words: `leave` in `messages.ts`, in the
+	 * library's `locale`; `variant: 'destructive'`.
 	 */
 	yes?: BbConfirmMessage['yes'];
 	no?: BbConfirmMessage['no'];
 	variant?: BbConfirmMessage['variant'];
+	/** The `BbDialog` stack the dialog joins (BbConfirm's `stack`). */
+	stack?: BbConfirmMessage['stack'];
 };
 
 const normalizeUrl = (value: string | URL) => {
@@ -1359,24 +2048,26 @@ export const useConfirmOnRouteLeave = ({
 	disabled = false,
 	onBefore = () => true,
 	onLeave = () => true,
-	title = 'Unsaved changes',
-	text = 'You have unsaved changes. Leave without saving?',
-	yes = 'Discard changes',
-	no = 'Keep editing',
+	title,
+	text,
+	yes,
+	no,
 	variant = 'destructive',
+	stack,
 }: Options = {}) => {
 	// Captured in setup so the built-in dialog is owned by the guarded page:
 	// if the page unmounts anyway, the dialog dismisses itself quietly.
 	const { confirm } = useConfirm();
+	const messages = useHelperMessages();
 	let bypassNextVisit = false;
 
 	const unbind = router.on('before', (event) => {
 		const visit = event.detail.visit as Visit;
 
 		// A hover / mount prefetch (`<Link prefetch>`, `<BbButton href prefetch>`)
-		// fires `before` too, but leaves nothing: no dialog, and it must not use up
-		// the bypass the re-sent visit below is waiting for.
-		if (visit.prefetch) return;
+		// fires `before` too, but leaves nothing: no dialog. A visit another
+		// guard on the page already stopped is that guard's to ask about.
+		if (visit.prefetch || event.defaultPrevented) return;
 
 		if (bypassNextVisit) {
 			bypassNextVisit = false;
@@ -1388,41 +2079,146 @@ export const useConfirmOnRouteLeave = ({
 
 		const nextPath = normalizeUrl(visit.url.href);
 		if (nextPath === normalizeUrl(window.location.href)) return;
-		if (toValue(whitelist).map(normalizeUrl).includes(nextPath)) return;
+		if (
+			visit.method !== 'get' &&
+			toValue(whitelist).map(normalizeUrl).includes(nextPath)
+		) {
+			// Marked: a save answered with a 409 redirect (a redirect with a
+			// #fragment) is re-sent by Inertia with these same headers, and that
+			// follow-up must not ask either.
+			visit.headers = { ...visit.headers, [WHITELIST_HEADER]: '1' };
+			return;
+		}
 
 		// `return`, not `return false`: an Inertia `before` listener that returns
 		// false CANCELS the visit, which is the opposite of what `onBefore`
 		// promises (false = let this visit through, no dialog).
 		if (onBefore(visit) === false) return;
 		event.preventDefault();
+		// Held, not refused: the dialog decides. `usePromiseForm` reads this
+		// flag and waits instead of answering `false` at once.
+		visit.awaitingConfirm = true;
 
 		void (async () => {
-			const confirmed = await confirm({ variant, title, text, yes, no });
-			if (!confirmed) return;
+			const words = messages.value.leave;
+			const confirmed = await confirm({
+				title: title ?? words.title,
+				text: text ?? words.text,
+				yes: yes ?? words.yes,
+				no: no ?? words.no,
+				variant,
+				...(stack && { stack }),
+			});
+			if (!confirmed) {
+				// "Keep editing" ends the held visit the way Inertia ends a
+				// cancelled one, so its own callbacks (a form's processing state,
+				// a pending promise) settle.
+				const callbacks = visit as {
+					onCancel?: () => void;
+					onFinish?: (visit: Visit) => void;
+				};
+				callbacks.onCancel?.();
+				callbacks.onFinish?.({ ...visit, cancelled: true });
+				return;
+			}
 
 			await onLeave(visit);
+			// Re-sent as a plain visit: never as a prefetch or a background one,
+			// and without the visit's own onBefore (its `confirm('Sure?')` was
+			// already answered).
+			const {
+				prefetch: _prefetch,
+				async: _async,
+				onBefore: _onBefore,
+				awaitingConfirm: _awaitingConfirm,
+				...rest
+			} = visit;
+			// `before` fires inside router.visit(): the bypass covers exactly
+			// that visit, and is never left armed for the next one (a re-send
+			// its own callbacks stop before `before`).
 			bypassNextVisit = true;
-			// Re-sent as a plain visit: never as a prefetch or a background one.
-			const { prefetch: _prefetch, async: _async, ...rest } = visit;
 			router.visit(visit.url, {
 				...(rest as Parameters<typeof router.visit>[1]),
 				headers: { ...visit.headers, [WHITELIST_HEADER]: '1' },
 			});
+			bypassNextVisit = false;
 		})();
 	});
 
+	// Leaving the app (closing the tab, reloading, a typed URL, a plain `<a>`)
+	// never reaches `before`: the browser's own prompt covers it. Not for a
+	// visit this guard let through: a save answered with `Inertia::location()`
+	// is a real unload with the form still dirty. Inertia sets
+	// `window.location` inside that visit, and WebKit asks only after the visit
+	// finished, so a let-through visit that completed with no answer (no page,
+	// no error bag, no error response: Inertia left) keeps it quiet until the
+	// next visit starts.
+	const released = new Set<unknown>();
+	let answered = false;
+	let leaving = false;
+	const marked = (visit: { headers?: Record<string, string> }) =>
+		getHeaderValue(visit.headers, WHITELIST_HEADER) === '1';
+	const unbindStart = router.on('start', ({ detail: { visit } }) => {
+		leaving = false;
+		answered = false;
+		if (marked(visit)) released.add(visit);
+	});
+	// Every way a visit gets an answer; the last two pairs are Inertia 3's
+	// names and Inertia 2's (each fires only on its own version).
+	const onRouterEvent = (name: string, listener: () => void) =>
+		router.on(name as 'start', listener);
+	const unbindAnswers = [
+		'success',
+		'error',
+		'httpException',
+		'invalid',
+		'networkError',
+		'exception',
+	].map((name) => onRouterEvent(name, () => void (answered = true)));
+	const unbindFinish = router.on('finish', ({ detail: { visit } }) => {
+		released.delete(visit);
+		if (marked(visit) && visit.completed && !answered) leaving = true;
+	});
+	const onBeforeUnload = (event: BeforeUnloadEvent) => {
+		if (toValue(disabled) || released.size || leaving) return;
+		event.preventDefault();
+		event.returnValue = '';
+	};
+	const inBrowser = typeof window !== 'undefined';
+	if (inBrowser) window.addEventListener('beforeunload', onBeforeUnload);
+
 	// `router.on` is a global bus that outlives this component: unbind it.
 	// `onScopeDispose` over `onUnmounted`: it fires on unmount too (`setup()`
 	// runs inside a component's own effect scope), but also works if this
 	// composable is ever called from outside one.
-	onScopeDispose(unbind);
+	onScopeDispose(() => {
+		unbind();
+		unbindStart();
+		unbindAnswers.forEach((unbindAnswer) => unbindAnswer());
+		unbindFinish();
+		if (inBrowser) window.removeEventListener('beforeunload', onBeforeUnload);
+	});
 };
 ```
 
 A prefetch never asks: `<Link prefetch>` and `<BbButton href prefetch>` fire
 Inertia's `before` event on hover too, and the guard lets them through (they
 leave nothing). The visit "Discard changes" re-sends is a plain one, never a
-prefetch or an `async` visit.
+prefetch or an `async` visit, and it does not ask the visit's own `onBefore`
+(an `onBefore: () => confirm('Sure?')`) a second time. "Keep editing" ends
+the held visit as Inertia ends a cancelled one (`onCancel`, then `onFinish`
+with `cancelled: true`), so a `usePromiseForm` save held by the dialog
+answers the user's choice: the re-sent save's result, or `false`. Two guards
+on one page ask once. **Back / Forward are not guarded, by design:** Inertia restores
+those pages from history without a `before` event, and catching them would
+mean fighting Inertia's own history and scroll restore.
+
+**The dialog speaks the library's `locale`.** Its default words come from
+`messages.ts` (see [Shared types and utilities](#shared-types-and-utilities)),
+which ships English only. Add your app's locale there once, keyed as you set
+the library's `locale`, and every guard follows `setConfig({ locale })`; a
+locale with no entry falls back to English. `title` / `text` / `yes` / `no`
+passed to one guard still win over it.
 
 > **`router.on(...)` subscribes to a global, module-level event bus — it
 > outlives the component that registered it unless you unbind it.** Inertia
@@ -1610,13 +2406,22 @@ export function useAsyncFn<T>(
 "Given an id, keep its resource loaded": re-fetches whenever the id
 changes, resets to `null` when the id clears, exposes `loading` and
 `refresh()`. The natural engine for a detail sidebar or peek panel — feed
-it the highlighted row's id.
+it the highlighted row's id. `fn` gets an `AbortSignal` as its second argument
+(`(id, signal) => fetch(url, { signal })`): it aborts when the load goes stale
+(a newer id, a clear, the page unmounting).
 
 ```ts
 // inertia-helpers/useResourceContext.ts
 import { useLoading } from './useLoading';
 import { noop } from './utils';
-import { ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue';
+import {
+	onScopeDispose,
+	ref,
+	toValue,
+	watch,
+	type MaybeRefOrGetter,
+	type Ref,
+} from 'vue';
 
 type UseResourceContextOptions<T, ID> = {
 	immediate?: boolean;
@@ -1629,7 +2434,8 @@ type UseResourceContextOptions<T, ID> = {
 
 export function useResourceContext<T, ID = string>(
 	id: MaybeRefOrGetter<ID | null | undefined>,
-	fn: (id: ID) => Promise<T>,
+	/** `signal` aborts when the load goes stale: pass it to `fetch` / axios. */
+	fn: (id: ID, signal: AbortSignal) => Promise<T>,
 	options: UseResourceContextOptions<T, ID> = {}
 ) {
 	const data = ref<T | null>(null) as Ref<T | null>;
@@ -1643,31 +2449,69 @@ export function useResourceContext<T, ID = string>(
 		onFinish = noop,
 	} = options;
 
-	const { loading, fn: fetch } = useLoading((resourceId: ID) => fn(resourceId));
+	const { loading, fn: fetch } = useLoading(
+		(resourceId: ID, signal: AbortSignal) => fn(resourceId, signal)
+	);
+
+	// Each load takes a ticket; a newer load, an id change or the scope's end
+	// makes older tickets stale, and a stale response is dropped (no data, no
+	// callbacks): a slow answer for the row the user left never lands. Going
+	// stale also aborts its request.
+	let ticket = 0;
+	let controller: AbortController | null = null;
+	const stale = () => {
+		ticket++;
+		controller?.abort();
+	};
+	let loadedId: ID | null = null;
+	const clear = () => {
+		stale();
+		data.value = null;
+		loadedId = null;
+	};
+	onScopeDispose(stale);
 
 	const load = async (resourceId: ID) => {
+		stale();
+		const own = ticket;
+		controller = new AbortController();
+		const outcome = await fetch(resourceId, controller.signal).then(
+			(result) => ({ ok: true as const, result }),
+			(error: unknown) => ({ ok: false as const, error })
+		);
+		if (own !== ticket) return;
 		try {
-			const result = await fetch(resourceId);
-			data.value = result;
-			await onSuccess(result, resourceId);
-		} catch (error) {
-			data.value = null;
-			await onError(error, resourceId);
+			if (outcome.ok) {
+				data.value = outcome.result;
+				loadedId = resourceId;
+				// Outside the fetch's catch: a throwing onSuccess is the
+				// caller's bug, not a failed fetch.
+				await onSuccess(outcome.result, resourceId);
+			} else {
+				clear();
+				await onError(outcome.error, resourceId);
+			}
 		} finally {
 			await onFinish(resourceId);
 		}
 	};
 
+	// Per-item sources: a re-run that yields the same id and flag (a partial
+	// reload handing a new row object with the same id) does not refetch.
 	watch(
-		() => ({ resourceId: toValue(id), isDisabled: toValue(disabled) }),
-		async ({ resourceId, isDisabled }) => {
+		[() => toValue(id), () => toValue(disabled)],
+		async ([resourceId, isDisabled]) => {
 			if (!resourceId) {
-				data.value = null;
+				clear();
 				await options.onReset?.();
 				return;
 			}
-			// Keep already-loaded data while disabled.
-			if (isDisabled) return;
+			// Keep already-loaded data while disabled, but only for the id it
+			// was loaded for: never show row a's resource under row b.
+			if (isDisabled) {
+				if (resourceId !== loadedId) clear();
+				return;
+			}
 			await load(resourceId as ID);
 		},
 		{ immediate }
@@ -1697,6 +2541,10 @@ Gotchas:
   never rejects on a non-2xx response — a 403/404 body still parses as JSON
   (or throws inside `.json()`, which is _also_ swallowed by `useResourceContext`
   the same way). Throw when `!res.ok` so `onError` actually fires.
+- **Only the current id's answer lands.** A slower response for a row the
+  user already left, or one landing after the id cleared or the scope ended,
+  is dropped: no `data`, no callbacks. While `disabled`, `data` is kept only
+  for the id it was loaded for; an id change clears it (re-enabling loads).
 
 ## UI utilities
 
@@ -1741,28 +2589,32 @@ export function useDeleteCmd(
 
 ### useScreenSizes
 
-Shared reactive breakpoints aligned with Tailwind `md`/`lg` — one window
-listener for the whole app via `createSharedComposable`.
+Shared reactive breakpoints — one window listener for the whole app via
+`createSharedComposable`. `isMobile` is the library's own signal (below the
+plugin's `mobileMaxWidth`, 768 by default), so a page and its components
+agree; tablet ends at Tailwind `lg`.
 
 ```ts
 // inertia-helpers/useScreenSizes.ts
 import { createSharedComposable, useWindowSize } from '@vueuse/core';
+import { useMobile } from 'bitboss-ui';
 import { computed } from 'vue';
 
-/** Tailwind md breakpoint (px). Mobile when width < 768. */
-export const SCREEN_BREAKPOINT_MD = 768;
-/** Tailwind lg breakpoint (px). Tablet when 768 <= width < 1024. */
+/** Tailwind lg breakpoint (px). Tablet from the library's mobile cut up to here. */
 export const SCREEN_BREAKPOINT_LG = 1024;
 
 const useScreenSizesImpl = () => {
 	const { width } = useWindowSize();
+	// The library's own signal (below the plugin's `mobileMaxWidth`), so a page
+	// and the components on it never disagree about "mobile".
+	const { isMobile } = useMobile();
 
-	const isMobile = computed(() => width.value < SCREEN_BREAKPOINT_MD);
 	const isTablet = computed(
-		() =>
-			width.value >= SCREEN_BREAKPOINT_MD && width.value < SCREEN_BREAKPOINT_LG
+		() => !isMobile.value && width.value < SCREEN_BREAKPOINT_LG
+	);
+	const isDesktop = computed(
+		() => !isMobile.value && width.value >= SCREEN_BREAKPOINT_LG
 	);
-	const isDesktop = computed(() => width.value >= SCREEN_BREAKPOINT_LG);
 
 	return { width, isMobile, isTablet, isDesktop };
 };