@snail-js/api 0.1.28 → 1.0.0

package/dist/chunks/use-download-FAjtdJ58.js

@@ -0,0 +1,1816 @@
+import { a as SnailHttpError, n as createPlugin, o as SnailResponseError } from "./plugin-D3RDffDG.js";
+import { t as SnailCancelledError } from "./request-qeRhihEF.js";
+import { n as deferred, r as noop } from "./object-Ct0w-h4i.js";
+import { i as Emitter, r as triggerDownload } from "./download-lBC7oOTT.js";
+import { isCancel } from "axios";
+//#region src/adapter/plain.ts
+/**
+* Framework-free state adapter.
+*
+* A plain mutable box. Values update correctly, they just do not *trigger*
+* anything — which is exactly right for a test, an SSR pass or a script, and is
+* the safe default when no UI framework is present.
+*
+* A framework adapter registered with `setStateAdapter` replaces it.
+*/
+var plainStateAdapter = {
+	name: "plain",
+	create(initial) {
+		return { value: initial };
+	},
+	read(ref) {
+		return ref.value;
+	},
+	write(ref, value) {
+		ref.value = value;
+	}
+};
+//#endregion
+//#region src/adapter/registry.ts
+/**
+* The active state adapter.
+*
+* Strategies never touch `ref()` or `useState()` directly — they ask this
+* registry. That is what lets one `useRequest` implementation serve Vue, React
+* and framework-free code without the core importing any of them.
+*/
+var active = plainStateAdapter;
+/** Replace the active adapter. Called once by a framework entry point. */
+function setStateAdapter(adapter) {
+	if (!adapter || typeof adapter.create !== "function") throw new TypeError("[snail] setStateAdapter() expects an object with a create() method");
+	active = adapter;
+}
+/** The active adapter. */
+function getStateAdapter() {
+	return active;
+}
+//#endregion
+//#region src/strategies/shared/adapter.ts
+/**
+* Resolve the state adapter one strategy instance should use.
+*
+* The adapter is resolved **once per hook** rather than per read. A hook that
+* asked the registry on every write could observe two different adapters if an
+* application called `setStateAdapter()` between two requests, and would then mix
+* Vue refs with plain boxes in one set of handles.
+*/
+function resolveStateAdapter(options = {}) {
+	return options.adapter ?? getStateAdapter();
+}
+/**
+* Read a handle for the current render.
+*
+* `useBind` exists for frameworks that only re-render on an explicit
+* subscription (React's `useSyncExternalStore`); Vue tracks the `.value` access
+* itself, so its adapter omits the method and the read is the whole story. The
+* `??` fallback — rather than a truthiness check — keeps a legitimate `false`,
+* `0` or `""` from being replaced by a second read.
+*/
+function bindRef(adapter, ref) {
+	return adapter.useBind?.(ref) ?? adapter.read(ref);
+}
+//#endregion
+//#region src/strategies/shared/error.ts
+/**
+* `true` when an error means "this request was deliberately stopped".
+*
+* Cancellation is **expected control flow**, not a failure: `method.abort()` and
+* a strategy discarding a stale response both produce it. Every strategy must ask
+* this question before writing `error` state or firing `onError`, otherwise a
+* user aborting a request would see a spurious error toast.
+*
+* The duck-typed `code` check is what catches an `AbortError` produced by a
+* caller-supplied `AbortSignal`, which axios does not always wrap in its own
+* cancel class.
+*/
+function isCancellation(error) {
+	if (error instanceof SnailCancelledError) return true;
+	if (isCancel(error)) return true;
+	const code = error?.code;
+	return code === "ERR_CANCELED" || code === "ABORT_ERR";
+}
+/**
+* Best-effort business/HTTP code of a failure, for the `code` state handle.
+*
+* Reading it from the error rather than from a response keeps `code` meaningful
+* on the failure path too — a `401` should be visible to the UI even though no
+* envelope ever passed validation.
+*/
+function readErrorCode(error) {
+	if (error instanceof SnailResponseError) return error.businessCode;
+	if (error instanceof SnailHttpError) return error.status;
+	const candidate = error;
+	const value = candidate?.response?.status ?? candidate?.status;
+	return typeof value === "number" || typeof value === "string" ? value : void 0;
+}
+/**
+* Best-effort human readable message of a failure, for the `message` handle.
+*
+* The backend envelope is preferred over the `Error.message` because an axios
+* transport message ("Request failed with status code 401") is useless to show a
+* user while `{ message: "token expired" }` is not.
+*/
+function readErrorMessage(error) {
+	if (error instanceof SnailResponseError) {
+		const payload = error.payload;
+		if (payload && typeof payload.message === "string") return payload.message;
+	}
+	const message = error?.message;
+	return typeof message === "string" ? message : void 0;
+}
+//#endregion
+//#region src/strategies/shared/state.ts
+/** `true` when `key` was explicitly provided, even with an `undefined` value. */
+function hasKey(source, key) {
+	return Object.prototype.hasOwnProperty.call(source, key);
+}
+/**
+* Build the state handles, the listeners and the writers for one hook.
+*
+* All five refs are created here, even for a hook that will not use them: a
+* `useFetcher({ withState: false })` still has to answer `abort()` and
+* `onFinish()`, and creating state lazily would hand the UI handles that appear
+* only after the first request.
+*/
+function createStrategyState(options = {}) {
+	const adapter = resolveStateAdapter(options);
+	const loading = adapter.create(false);
+	const data = adapter.create(options.initialData);
+	const error = adapter.create(void 0);
+	const code = adapter.create(void 0);
+	const message = adapter.create(void 0);
+	const events = new Emitter();
+	return {
+		adapter,
+		state: {
+			loading,
+			data,
+			error,
+			code,
+			message,
+			abort() {
+				options.onAbort?.();
+			},
+			update(patch) {
+				if (hasKey(patch, "data")) adapter.write(data, patch.data);
+				if (hasKey(patch, "loading")) adapter.write(loading, patch.loading);
+				if (hasKey(patch, "error")) adapter.write(error, patch.error);
+				if (hasKey(patch, "code")) adapter.write(code, patch.code);
+				if (hasKey(patch, "message")) adapter.write(message, patch.message);
+			},
+			bind() {
+				return {
+					loading: bindRef(adapter, loading),
+					data: bindRef(adapter, data),
+					error: bindRef(adapter, error),
+					code: bindRef(adapter, code),
+					message: bindRef(adapter, message)
+				};
+			},
+			onSuccess(callback) {
+				return events.on("success", callback);
+			},
+			onError(callback) {
+				return events.on("error", callback);
+			},
+			onFinish(callback) {
+				return events.on("finish", callback);
+			}
+		},
+		setLoading(value) {
+			adapter.write(loading, value);
+		},
+		setData(value) {
+			adapter.write(data, value);
+		},
+		setError(value) {
+			adapter.write(error, value);
+		},
+		setCode(value) {
+			adapter.write(code, value);
+		},
+		setMessage(value) {
+			adapter.write(message, value);
+		},
+		resetForSend() {
+			adapter.write(error, void 0);
+			adapter.write(code, void 0);
+			adapter.write(message, void 0);
+		},
+		applySuccess(result) {
+			adapter.write(data, result.data);
+			adapter.write(code, result.code);
+			adapter.write(message, result.message);
+			adapter.write(error, void 0);
+			return result.data;
+		},
+		applyFailure(failure) {
+			adapter.write(error, failure);
+			adapter.write(code, readErrorCode(failure));
+			adapter.write(message, readErrorMessage(failure));
+		},
+		emitSuccess(value) {
+			events.emit("success", value);
+		},
+		emitError(failure) {
+			events.emit("error", failure);
+		},
+		emitFinish() {
+			events.emit("finish", void 0);
+		},
+		dispose() {
+			events.clear();
+			adapter.dispose?.(loading);
+			adapter.dispose?.(data);
+			adapter.dispose?.(error);
+			adapter.dispose?.(code);
+			adapter.dispose?.(message);
+		}
+	};
+}
+//#endregion
+//#region src/strategies/shared/method.ts
+/** Create a {@link MethodHolder} around a proxied api method. */
+function createMethodHolder(method) {
+	let instance;
+	return {
+		get instance() {
+			return instance;
+		},
+		get pending() {
+			return instance?.pending ?? false;
+		},
+		resolve(args) {
+			instance ??= method(...args);
+			return instance;
+		},
+		abort() {
+			instance?.abort();
+		}
+	};
+}
+/**
+* Attach a per-request upload progress callback.
+*
+* The core resolves `onUploadProgress` from `@UploadProgress(...)` metadata when
+* the `SnailMethod` is built, which is once per method — not once per file. To
+* vary it per request this writes onto the **live** axios config instead.
+*
+* The timing is load-bearing: `send()` calls `begin()` synchronously before its
+* first `await`, so the config read here is the one axios will send. Calling this
+* before `send()` would be silently overwritten by `begin()`, and calling it
+* after an `await` would be too late.
+*
+* @returns `false` when there was no live config to attach to.
+*/
+function attachUploadProgress(snail, listener) {
+	const config = snail.context?.request;
+	if (!config) return false;
+	const previous = config.onUploadProgress;
+	config.onUploadProgress = (event) => {
+		if (typeof previous === "function") previous(event);
+		listener(event);
+	};
+	return true;
+}
+//#endregion
+//#region src/strategies/use-request.ts
+/**
+* Drive one api method from component state.
+*
+* ```ts
+* const user = useRequest(userApi.getUser);
+* await user.send("1");              // → payload
+* user.data.value;                   // → the same payload
+* ```
+*
+* The hook owns exactly one `SnailMethod`, built from the arguments of the first
+* send and reused afterwards. That is what keeps the reactive handles stable
+* across re-sends — see `shared/method.ts` for why a second instance would break
+* the UI — while `send("2")` still overrides the arguments per call.
+*
+* One instance also means one request at a time: `SnailMethod` resets its context
+* at the start of every `send()`, so a second `send()` issued while the first is
+* still in flight would leave the first reading a context that belongs to the
+* second. Call `abort()` first, or use `useWatcher`/`useAutoRequest`, which
+* collapse bursts for exactly this reason.
+*/
+function useRequest(method, options = {}) {
+	const holder = createMethodHolder(method);
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		initialData: options.initialData,
+		onAbort: () => holder.abort()
+	});
+	const { state } = controller;
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	async function send(...args) {
+		const snail = holder.resolve(args);
+		controller.resetForSend();
+		if (options.resetOnSend) controller.setData(options.initialData);
+		controller.setLoading(true);
+		try {
+			const result = await snail.send(...args);
+			const payload = controller.applySuccess(result);
+			controller.emitSuccess(payload);
+			return payload;
+		} catch (error) {
+			if (isCancellation(error)) throw error;
+			controller.applyFailure(error);
+			controller.emitError(error);
+			throw error;
+		} finally {
+			controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	const result = {
+		...state,
+		send
+	};
+	if (options.immediate) send(...[]).catch(noop);
+	return result;
+}
+//#endregion
+//#region src/strategies/shared/timing.ts
+/**
+* Sleep for `ms`, rejecting with a {@link SnailCancelledError} the moment the
+* signal aborts.
+*
+* A plain `setTimeout` promise is the wrong primitive for a backoff: `abort()`
+* during a 30 second retry delay would leave the loop asleep and the caller's
+* promise pending long after it cancelled. The listener is `{ once: true }` and
+* removed on either outcome so a long-lived signal cannot accumulate handlers.
+*/
+function cancellableDelay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new SnailCancelledError("wait cancelled before it started"));
+			return;
+		}
+		let timer;
+		const onAbort = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			reject(new SnailCancelledError("wait cancelled"));
+		};
+		timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, Math.max(0, ms));
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Detach a Node timer from the event loop, when it has an `unref`.
+*
+* A polling strategy that is never stopped would otherwise keep a Node process
+* (or a test worker) alive forever. In a browser `setTimeout` returns a number,
+* which has no `unref` — hence the optional call rather than a feature test.
+*/
+function unrefTimer(timer) {
+	timer?.unref?.();
+}
+/**
+* Collapse a burst of `schedule()` calls into at most one request.
+*
+* Two modes, one rule — **the most recent task wins**, because a request must be
+* sent with the latest arguments, never with the ones captured when the burst
+* started:
+*
+* - `debounce` waits for `debounce` ms of quiet. Every new call pushes the run
+*   back, so ten keystrokes produce one request, not ten.
+* - `throttle` runs on the leading edge and then books exactly one trailing run
+*   per window. Without the trailing run the last change in a burst would be
+*   silently dropped — a search box that ignores the final character.
+*
+* `debounce` is preferred when both are configured (see `useWatcher`): the two
+* express contradictory intents, and picking one deterministically beats a
+* half-debounced, half-throttled hybrid nobody can reason about.
+*/
+function createRequestScheduler(options = {}) {
+	const debounce = options.debounce && options.debounce > 0 ? options.debounce : 0;
+	const throttle = options.throttle && options.throttle > 0 ? options.throttle : 0;
+	let timer;
+	let latest;
+	let lastRunAt = 0;
+	let ran = false;
+	const clear = () => {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+	};
+	const runNow = () => {
+		const task = latest;
+		latest = void 0;
+		clear();
+		lastRunAt = Date.now();
+		ran = true;
+		task?.();
+	};
+	return {
+		get pending() {
+			return latest !== void 0;
+		},
+		schedule(task) {
+			latest = task;
+			if (debounce > 0) {
+				clear();
+				timer = setTimeout(runNow, debounce);
+				return;
+			}
+			if (throttle > 0) {
+				if (timer !== void 0) return;
+				const elapsed = Date.now() - lastRunAt;
+				if (!ran || elapsed >= throttle) {
+					runNow();
+					return;
+				}
+				timer = setTimeout(runNow, throttle - elapsed);
+				return;
+			}
+			runNow();
+		},
+		cancel() {
+			clear();
+			latest = void 0;
+		}
+	};
+}
+//#endregion
+//#region src/strategies/shared/watcher.ts
+/**
+* Read one entry of a `watching()` result.
+*
+* `docs/guide/plugin-lifecycle.md`'s adapter contract exposes no way to ask "is this a state
+* handle?" portably: the Vue adapter has `isState`, React's has none, and the
+* plain adapter's boxes are bare `{ value }` objects. So three cases are handled,
+* in order of confidence:
+*
+* 1. `adapter.isState(value)` says yes — unwrap it (Vue).
+* 2. the value is a plain object whose *only* own key is `value` — the exact shape
+*    the plain and React adapters allocate — unwrap it.
+* 3. anything else is the value itself.
+*
+* Case 2 is a heuristic, and it is the reason `watching: () => [{ value: 1 }]`
+* should be written as `() => [{ value: 1 }.value]` if the object is genuine
+* data rather than a handle. Without it, `() => [pageRef]` — the natural thing to
+* write — would compare the ref object itself and never detect a change.
+*/
+function unwrapWatchedValue(adapter, value) {
+	if (adapter.isState?.(value)) return adapter.read(value);
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const keys = Object.keys(value);
+		if (keys.length === 1 && keys[0] === "value") return value.value;
+	}
+	return value;
+}
+/**
+* Evaluate a `watching()` function into the plain values that get compared.
+*
+* A watcher is user code, so a non-array return is normalised to a one-element
+* list rather than iterated blindly — spreading a string would compare its
+* characters, and spreading `undefined` would throw inside the hook.
+*/
+function readWatchedValues(adapter, watching) {
+	const produced = watching();
+	return (Array.isArray(produced) ? produced : [produced]).map((value) => unwrapWatchedValue(adapter, value));
+}
+/**
+* Compare two watched snapshots with `Object.is`.
+*
+* `Object.is` rather than `===` so `NaN` does not look like a change on every
+* render — a watcher over a numeric field that happens to be `NaN` would
+* otherwise re-send forever.
+*/
+function shallowEqual(a, b) {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let index = 0; index < a.length; index += 1) if (!Object.is(a[index], b[index])) return false;
+	return true;
+}
+//#endregion
+//#region src/strategies/use-watcher.ts
+/**
+* Re-send a request when watched values move.
+*
+* ```ts
+* const keyword = createState("");
+* const search = useWatcher(searchApi.find, {
+*   watching: () => [keyword.value],
+*   debounce: 200
+* });
+*
+* keyword.value = "a"; await search.send();   // sends
+* await search.send();                        // same values → no request
+* keyword.value = "ab"; await search.send();  // sends again
+* ```
+*
+* ## Why `send()` is the evaluation trigger
+*
+* `SnailStateAdapter` exposes `create`/`read`/`write` and an optional
+* `subscribe`; it has no `watch` or `effect`, and the core deliberately keeps
+* framework reactivity out of the strategy layer. So there is nothing to fire at
+* the *moment* a value changes. The hook therefore evaluates `watching()` when
+* `send()` is called and treats an unchanged snapshot as a no-op, which keeps the
+* behaviour deterministic and framework-free: a Vue/React integration can call
+* `send()` from its own reactive effect, and a script calls it directly.
+*
+* `debounce`/`throttle` then collapse the *bursts* of `send()` calls a reactive
+* effect produces. Every collapsed caller's promise settles with the single
+* request's outcome, so no `await` is ever left hanging.
+*/
+function useWatcher(method, options) {
+	const holder = createMethodHolder(method);
+	const scheduler = createRequestScheduler({
+		debounce: options.debounce,
+		throttle: options.throttle
+	});
+	let settleWaiters = [];
+	const rejectWaiters = (error) => {
+		const waiters = settleWaiters;
+		settleWaiters = [];
+		for (const waiter of waiters) waiter.reject(error);
+	};
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		initialData: options.initialData,
+		onAbort: () => {
+			scheduler.cancel();
+			rejectWaiters(new SnailCancelledError("watched request cancelled before it was sent"));
+			holder.abort();
+		}
+	});
+	const { state } = controller;
+	const watching = controller.adapter.create(true);
+	let snapshot;
+	let queuedArgs;
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	async function perform() {
+		const waiters = settleWaiters;
+		settleWaiters = [];
+		if (waiters.length === 0) return;
+		const args = queuedArgs ?? [];
+		const snail = holder.resolve(args);
+		controller.resetForSend();
+		if (options.resetOnSend) controller.setData(options.initialData);
+		controller.setLoading(true);
+		try {
+			const result = await snail.send(...args);
+			const payload = controller.applySuccess(result);
+			controller.emitSuccess(payload);
+			for (const waiter of waiters) waiter.resolve(payload);
+		} catch (error) {
+			if (!isCancellation(error)) {
+				controller.applyFailure(error);
+				controller.emitError(error);
+			}
+			for (const waiter of waiters) waiter.reject(error);
+		} finally {
+			controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	function send(...args) {
+		let values;
+		try {
+			values = readWatchedValues(controller.adapter, options.watching);
+		} catch (error) {
+			controller.setError(error);
+			controller.emitError(error);
+			return Promise.reject(error);
+		}
+		const changed = snapshot === void 0 || !shallowEqual(values, snapshot);
+		snapshot = values;
+		queuedArgs = args;
+		if (controller.adapter.read(watching) && !changed) return Promise.resolve(controller.adapter.read(state.data));
+		const promise = new Promise((resolve, reject) => {
+			settleWaiters.push({
+				resolve,
+				reject
+			});
+		});
+		scheduler.schedule(() => {
+			perform();
+		});
+		return promise;
+	}
+	const result = {
+		...state,
+		watching,
+		send
+	};
+	if (options.immediate) send(...[]).catch(noop);
+	return result;
+}
+//#endregion
+//#region src/strategies/use-fetcher.ts
+function useFetcher(method, options = {}) {
+	const track = options.withState === true;
+	const holder = createMethodHolder(method);
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		onAbort: () => holder.abort()
+	});
+	const { state } = controller;
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	async function fetch(...args) {
+		const snail = holder.resolve(args);
+		if (track) {
+			controller.resetForSend();
+			controller.setLoading(true);
+		}
+		try {
+			const result = await snail.send(...args);
+			const payload = result.data;
+			if (track) controller.applySuccess(result);
+			controller.emitSuccess(payload);
+			return payload;
+		} catch (error) {
+			if (!isCancellation(error)) {
+				if (track) controller.applyFailure(error);
+				controller.emitError(error);
+			}
+			throw error;
+		} finally {
+			if (track) controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	const core = {
+		fetch,
+		abort: () => state.abort(),
+		onSuccess: (callback) => state.onSuccess(callback),
+		onError: (callback) => state.onError(callback),
+		onFinish: (callback) => state.onFinish(callback)
+	};
+	if (options.immediate) fetch(...[]).catch(noop);
+	if (!track) return core;
+	return {
+		...core,
+		...state
+	};
+}
+//#endregion
+//#region src/strategies/use-pagination.ts
+/** Default row extractor — array payloads, then the two common wrapper keys. */
+function defaultList(payload) {
+	if (Array.isArray(payload)) return payload;
+	const candidate = payload;
+	if (Array.isArray(candidate?.list)) return candidate.list;
+	if (Array.isArray(candidate?.items)) return candidate.items;
+	return [];
+}
+/** Default total extractor — `total`, then `count`, then the current page size. */
+function defaultTotal(payload) {
+	if (Array.isArray(payload)) return payload.length;
+	const candidate = payload;
+	if (typeof candidate?.total === "number") return candidate.total;
+	if (typeof candidate?.count === "number") return candidate.count;
+	return defaultList(payload).length;
+}
+/**
+* Page through one api method.
+*
+* ```ts
+* const users = usePagination(userApi.list, {
+*   total: (payload) => payload.total,
+*   list: (payload) => payload.rows
+* });
+* await users.reload();
+* await users.next();
+* ```
+*
+* `next()`/`prev()` are **no-ops at the bounds and fire no request**: a user
+* holding down the "next" button at the last page must not hammer the server, and
+* the promise still resolves (with `undefined`) so an `await` never hangs.
+*/
+function usePagination(method, options = {}) {
+	const initialPage = Number.isFinite(options.initialPage) ? Math.max(1, Math.floor(options.initialPage)) : 1;
+	const initialPageSize = Number.isFinite(options.initialPageSize) ? Math.max(1, Math.floor(options.initialPageSize)) : 10;
+	const append = options.append === true;
+	const extractList = options.list ?? defaultList;
+	const extractTotal = options.total ?? defaultTotal;
+	/** The preloaded page, ready to be served without a request. */
+	let buffered;
+	let preloading = false;
+	const holder = createMethodHolder(method);
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		onAbort: () => holder.abort()
+	});
+	const { state } = controller;
+	const adapter = controller.adapter;
+	const page = adapter.create(initialPage);
+	const pageSize = adapter.create(initialPageSize);
+	const total = adapter.create(0);
+	const list = adapter.create([]);
+	const isLastPage = adapter.create(false);
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	/** Last page reachable, or `Infinity` while the total is still unknown. */
+	function lastPage() {
+		const size = Math.max(1, adapter.read(pageSize));
+		const known = adapter.read(total);
+		if (known > 0) return Math.max(1, Math.ceil(known / size));
+		return adapter.read(isLastPage) ? adapter.read(page) : Number.POSITIVE_INFINITY;
+	}
+	/** Write the paging derived from one payload. */
+	function applyPage(payload, target, size, accumulate) {
+		const rows = extractList(payload);
+		const known = extractTotal(payload);
+		adapter.write(page, target);
+		adapter.write(total, known);
+		adapter.write(list, accumulate ? [...adapter.read(list), ...rows] : rows);
+		adapter.write(isLastPage, known > 0 ? target * size >= known : rows.length < size);
+	}
+	async function request(target, size, accumulate) {
+		const snail = holder.resolve([{
+			page: target,
+			pageSize: size
+		}]);
+		controller.resetForSend();
+		controller.setLoading(true);
+		try {
+			const result = await snail.send({
+				page: target,
+				pageSize: size
+			});
+			const payload = controller.applySuccess(result);
+			applyPage(payload, target, size, accumulate);
+			controller.emitSuccess(payload);
+			if (options.preloadNext) startPreload(target + 1);
+			return payload;
+		} catch (error) {
+			if (!isCancellation(error)) {
+				controller.applyFailure(error);
+				controller.emitError(error);
+			}
+			throw error;
+		} finally {
+			controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	/**
+	* Warm the buffer with `target`, using a throwaway `SnailMethod`.
+	*
+	* A second instance is what keeps the preload invisible: it has its own context,
+	* so its `loading`/`data` never reach the caller's handles. A failed preload is
+	* swallowed on purpose — `next()` simply falls back to a real request.
+	*/
+	async function startPreload(target) {
+		if (preloading) return;
+		if (target > lastPage()) return;
+		preloading = true;
+		try {
+			const size = Math.max(1, adapter.read(pageSize));
+			buffered = {
+				page: target,
+				payload: (await method({
+					page: target,
+					pageSize: size
+				}).send({
+					page: target,
+					pageSize: size
+				})).data
+			};
+		} catch {
+			buffered = void 0;
+		} finally {
+			preloading = false;
+		}
+	}
+	function clamp(target) {
+		const bound = lastPage();
+		return Math.min(Math.max(1, Number.isFinite(target) ? Math.floor(target) : 1), bound);
+	}
+	async function next() {
+		const current = adapter.read(page);
+		if (current >= lastPage()) return void 0;
+		const target = current + 1;
+		const size = Math.max(1, adapter.read(pageSize));
+		if (buffered && buffered.page === target) {
+			const ready = buffered;
+			buffered = void 0;
+			applyPage(ready.payload, target, size, append);
+			if (options.preloadNext) startPreload(target + 1);
+			return ready.payload;
+		}
+		return request(target, size, append);
+	}
+	async function prev() {
+		const current = adapter.read(page);
+		if (current <= 1) return void 0;
+		return request(current - 1, Math.max(1, adapter.read(pageSize)), append);
+	}
+	async function goTo(target) {
+		const resolved = clamp(target);
+		if (resolved === adapter.read(page)) return void 0;
+		return request(resolved, Math.max(1, adapter.read(pageSize)), false);
+	}
+	async function reload() {
+		const size = Math.max(1, adapter.read(pageSize));
+		adapter.write(list, []);
+		adapter.write(isLastPage, false);
+		buffered = void 0;
+		return request(initialPage, size, append);
+	}
+	async function changePageSize(size) {
+		if (!Number.isFinite(size) || size < 1) return void 0;
+		const resolved = Math.max(1, Math.floor(size));
+		adapter.write(pageSize, resolved);
+		adapter.write(list, []);
+		adapter.write(isLastPage, false);
+		buffered = void 0;
+		return request(initialPage, resolved, false);
+	}
+	return {
+		...state,
+		page,
+		pageSize,
+		total,
+		list,
+		isLastPage,
+		next,
+		prev,
+		goTo,
+		reload,
+		changePageSize
+	};
+}
+//#endregion
+//#region src/strategies/shared/dom.ts
+/** The global `window`, or `undefined` outside a DOM environment. */
+function getWindowTarget() {
+	if (typeof window === "undefined") return void 0;
+	return window;
+}
+/** The global `document`, or `undefined` outside a DOM environment. */
+function getDocumentTarget() {
+	if (typeof document === "undefined") return void 0;
+	return document;
+}
+/**
+* `true` when the page is on screen.
+*
+* Node reports `true` so a `visibilitychange`-driven strategy still works in a
+* script; there is no hidden page to miss.
+*/
+function isDocumentVisible() {
+	if (typeof document === "undefined") return true;
+	return document.visibilityState !== "hidden";
+}
+/**
+* Create a listener bookkeeping scope.
+*
+* `stop()` and `dispose()` are called from event handlers, from `finally` blocks
+* and sometimes twice; without one central registry it is far too easy to remove a
+* listener with a *different* function reference than the one added, which leaks
+* silently and keeps the component from being collected.
+*/
+function createListenerScope() {
+	const registered = [];
+	return {
+		get size() {
+			return registered.length;
+		},
+		add(target, type, listener) {
+			if (!target) return false;
+			target.addEventListener(type, listener);
+			registered.push({
+				target,
+				type,
+				listener
+			});
+			return true;
+		},
+		removeAll() {
+			while (registered.length > 0) {
+				const entry = registered.pop();
+				entry.target.removeEventListener(entry.type, entry.listener);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/strategies/use-auto-request.ts
+/**
+* Keep a request fresh by itself: polling plus the three "the user is back"
+* signals a dashboard actually needs.
+*
+* ```ts
+* const stats = useAutoRequest(statsApi.get, {
+*   pollingInterval: 5000,
+*   refreshOnVisible: true
+* });
+* stats.start();
+* stats.dispose();     // on unmount
+* ```
+*
+* ## Lifecycle
+*
+* `stop()` is the single release point: it halts the polling timer **and** removes
+* every listener, so an unmounted view cannot be kept alive by a focus handler.
+* `start()` re-arms both. The refresh listeners are attached at creation rather
+* than in `start()` — a hook whose only job is "refresh when the user comes back"
+* should not need an extra call — while polling itself only runs between `start()`
+* and `stop()`.
+*
+* ## Node safety
+*
+* `window`/`document` are looked up lazily and may be absent, so creating the hook
+* during SSR is harmless. Every listener goes through one listener scope, which is
+* what makes `stop()` remove exactly what was added; a listener removed with a
+* fresh closure reference would leak silently. The polling timer is `unref`'d on
+* Node so it never holds the process (or a test worker) open.
+*/
+function useAutoRequest(method, options = {}) {
+	const request = useRequest(method, {
+		...options,
+		immediate: false
+	});
+	const running = resolveStateAdapter(options).create(false);
+	const scope = createListenerScope();
+	const interval = Number.isFinite(options.pollingInterval) ? Math.max(0, options.pollingInterval) : 0;
+	let timer;
+	let disposed = false;
+	function clearTimer() {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+	}
+	function refresh() {
+		return request.send(...[]);
+	}
+	/** Run one refresh without letting a rejection escape into a timer/listener. */
+	async function refreshQuietly() {
+		try {
+			await refresh();
+		} catch {}
+	}
+	function schedule() {
+		if (disposed || !running.value || interval <= 0) return;
+		timer = setTimeout(() => {
+			timer = void 0;
+			loop();
+		}, interval);
+		unrefTimer(timer);
+	}
+	async function loop() {
+		await refreshQuietly();
+		schedule();
+	}
+	function attach() {
+		scope.removeAll();
+		if (options.enableFocusRefresh) scope.add(getWindowTarget(), "focus", () => {
+			refreshQuietly();
+		});
+		if (options.enableReconnectRefresh) scope.add(getWindowTarget(), "online", () => {
+			refreshQuietly();
+		});
+		if (options.refreshOnVisible) scope.add(getDocumentTarget(), "visibilitychange", () => {
+			if (isDocumentVisible()) refreshQuietly();
+		});
+	}
+	function start() {
+		if (disposed || running.value) return;
+		running.value = true;
+		attach();
+		loop();
+	}
+	function stop() {
+		running.value = false;
+		clearTimer();
+		scope.removeAll();
+	}
+	function dispose() {
+		stop();
+		disposed = true;
+	}
+	attach();
+	if (options.immediate) start();
+	return {
+		...request,
+		running,
+		start,
+		stop,
+		refresh,
+		dispose
+	};
+}
+//#endregion
+//#region src/strategies/shared/retry.ts
+/** Defaults are deliberately conservative: three tries, exponential, jittered. */
+var DEFAULT_RETRY_POLICY = {
+	retries: 3,
+	delayMs: 1e3,
+	maxDelayMs: 3e4,
+	factor: 2,
+	jitter: true
+};
+/**
+* Fill in the retry defaults.
+*
+* `retries` is floored and clamped to `>= 0`: a negative value would make the
+* attempt loop run zero times and resolve without ever sending, which is a
+* silent no-op rather than a validation error the caller can see.
+*/
+function resolveRetryPolicy(options = {}) {
+	return {
+		retries: Number.isFinite(options.retries) ? Math.max(0, Math.floor(options.retries)) : DEFAULT_RETRY_POLICY.retries,
+		delayMs: Number.isFinite(options.delayMs) ? Math.max(0, options.delayMs) : DEFAULT_RETRY_POLICY.delayMs,
+		maxDelayMs: Number.isFinite(options.maxDelayMs) ? Math.max(0, options.maxDelayMs) : DEFAULT_RETRY_POLICY.maxDelayMs,
+		factor: Number.isFinite(options.factor) ? Math.max(1, options.factor) : DEFAULT_RETRY_POLICY.factor,
+		jitter: options.jitter ?? DEFAULT_RETRY_POLICY.jitter
+	};
+}
+/**
+* Delay before attempt `attempt` (1-based), with exponential growth and an
+* optional jitter.
+*
+* Jitter is *half* the computed delay plus a random share, not a fresh random
+* pick: full jitter can produce a near-zero delay that turns a retry storm into a
+* hammering loop, while half jitter still spreads a fleet of clients out.
+*/
+function computeBackoffDelay(attempt, policy) {
+	const exponent = Math.max(0, attempt - 1);
+	const base = Math.min(policy.delayMs * policy.factor ** exponent, policy.maxDelayMs);
+	if (!policy.jitter) return base;
+	return base / 2 + Math.random() * (base / 2);
+}
+/**
+* The default {@link RetryPredicate}: retry everything except a cancellation.
+*
+* Retrying a cancellation is the one case that is always wrong — the caller asked
+* for the request to stop, so a retry ignores an explicit instruction and keeps
+* the socket busy.
+*/
+var defaultRetryPredicate = (error) => !isCancellation(error);
+//#endregion
+//#region src/strategies/use-retriable-request.ts
+/**
+* A request that heals itself.
+*
+* ```ts
+* const save = useRetriableRequest(api.save, { retries: 3, delayMs: 200 });
+* await save.send(payload);      // may hit the network up to 4 times
+* save.attempts.value;           // how many tries it actually took
+* ```
+*
+* ## Cancellation is the hard part
+*
+* The hook keeps its own `AbortController` for the backoff *between* attempts,
+* because at that moment there is no in-flight request to cancel. `abort()` trips
+* both, so a `abort()` during a 30 second delay rejects immediately instead of
+* leaving the caller's promise pending until the timer fires. A cancellation is
+* never counted as a failed attempt and never written to `error`.
+*
+* `attempts` is exposed because it is genuinely useful for telemetry ("this call
+* needed three tries") and because it makes the retry loop testable without
+* counting requests.
+*/
+function useRetriableRequest(method, options = {}) {
+	const policy = resolveRetryPolicy(options);
+	const retryAllowed = options.retryOn ?? defaultRetryPredicate;
+	const holder = createMethodHolder(method);
+	let backoff;
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		initialData: options.initialData,
+		onAbort: () => {
+			backoff?.abort();
+			holder.abort();
+		}
+	});
+	const { state } = controller;
+	const attempts = controller.adapter.create(0);
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	async function send(...args) {
+		const snail = holder.resolve(args);
+		const signal = new AbortController();
+		backoff = signal;
+		controller.resetForSend();
+		if (options.resetOnSend) controller.setData(options.initialData);
+		controller.setLoading(true);
+		controller.adapter.write(attempts, 0);
+		try {
+			for (let attempt = 0; attempt <= policy.retries; attempt += 1) {
+				controller.adapter.write(attempts, attempt + 1);
+				try {
+					const result = await snail.send(...args);
+					const payload = controller.applySuccess(result);
+					controller.emitSuccess(payload);
+					return payload;
+				} catch (error) {
+					if (isCancellation(error)) throw error;
+					if (!(attempt < policy.retries && retryAllowed(error, attempt + 1))) throw error;
+					controller.applyFailure(error);
+					await cancellableDelay(computeBackoffDelay(attempt + 1, policy), signal.signal);
+				}
+			}
+			throw new SnailCancelledError("retry loop ended without a result");
+		} catch (error) {
+			if (!isCancellation(error)) {
+				controller.applyFailure(error);
+				controller.emitError(error);
+			}
+			throw error;
+		} finally {
+			if (backoff === signal) backoff = void 0;
+			controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	return {
+		...state,
+		send,
+		attempts
+	};
+}
+//#endregion
+//#region src/strategies/shared/queue.ts
+/**
+* Create a queue that runs at most `concurrency` tasks at a time.
+*
+* A task that rejects is swallowed rather than failing the queue: one broken
+* upload must not stall the remaining ones, and the caller observes the failure
+* through per-file state anyway. `concurrency` is clamped to at least 1, because a
+* queue with zero slots would never drain and `drain()` would never resolve.
+*/
+function createTaskQueue(concurrency = 1) {
+	const limit = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 1;
+	const waiting = [];
+	let active = 0;
+	let idleWaiters = [];
+	const settleIdle = () => {
+		if (active > 0 || waiting.length > 0) return;
+		const waiters = idleWaiters;
+		idleWaiters = [];
+		for (const waiter of waiters) waiter();
+	};
+	const pump = () => {
+		while (active < limit && waiting.length > 0) {
+			const task = waiting.shift();
+			active += 1;
+			Promise.resolve().then(task).catch(noop).then(() => {
+				active -= 1;
+				pump();
+				settleIdle();
+			});
+		}
+		settleIdle();
+	};
+	return {
+		get active() {
+			return active;
+		},
+		get pending() {
+			return waiting.length;
+		},
+		add(task) {
+			waiting.push(task);
+			queueMicrotask(pump);
+		},
+		drain() {
+			if (active === 0 && waiting.length === 0) return Promise.resolve();
+			return new Promise((resolve) => {
+				idleWaiters.push(resolve);
+			});
+		},
+		clear() {
+			waiting.length = 0;
+			settleIdle();
+		}
+	};
+}
+//#endregion
+//#region src/strategies/use-uploader.ts
+/** Normalise the several shapes a file input hands out. */
+function normalizeFiles(input) {
+	if (!input) return [];
+	if (Array.isArray(input)) return input;
+	if (typeof input.length === "number") return Array.from(input);
+	return [input];
+}
+/** Keep a fraction inside `0`–`1`; a transport can report `loaded > total`. */
+function clamp01(value) {
+	if (!Number.isFinite(value)) return 0;
+	return Math.min(1, Math.max(0, value));
+}
+/**
+* Upload files with a bounded number of parallel requests.
+*
+* ```ts
+* const uploader = useUploader(api.upload, { concurrency: 2 });
+* await uploader.upload(input.files);
+* uploader.files.value;      // per-file status, progress, error, response
+* uploader.retry(id);        // re-queue one failure
+* ```
+*
+* ## Progress
+*
+* Per-file progress comes from the transport via axios' `onUploadProgress`, which
+* the hook attaches to the **live** request config of each file (see
+* `shared/method.ts` for why that has to happen right after `send()` starts). The
+* aggregate is the mean of the per-file values, and a finished file counts as `1`
+* regardless of what the transport reported — a mocked or `fetch`-based adapter
+* reports nothing at all, and without that rule the bar would stop at `0`.
+*
+* ## `data` and `code`
+*
+* The state handles are shared by the whole batch, so `data` holds the payload of
+* the most recently finished file. Use `files[i].response` for anything
+* per-file. `error` mirrors the file list: it holds the first failed file's error
+* while any file is in the `error` state, and clears itself once the last failure
+* has been retried successfully.
+*/
+function useUploader(method, options = {}) {
+	const fieldName = options.fieldName ?? "file";
+	const queue = createTaskQueue(options.concurrency ?? 3);
+	const inFlight = /* @__PURE__ */ new Set();
+	let states = [];
+	let sequence = 0;
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		onAbort: () => {
+			for (const snail of [...inFlight]) snail.abort();
+			inFlight.clear();
+			queue.clear();
+			for (const entry of states) {
+				if (entry.status === "success") continue;
+				patch(entry.id, {
+					status: "pending",
+					progress: 0,
+					error: void 0
+				});
+			}
+		}
+	});
+	const { state } = controller;
+	const adapter = controller.adapter;
+	const files = adapter.create([]);
+	const progress = adapter.create(0);
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	function writeStates() {
+		adapter.write(files, states.slice());
+	}
+	function recalc() {
+		const aggregate = states.length === 0 ? 0 : states.reduce((sum, entry) => sum + entry.progress, 0) / states.length;
+		adapter.write(progress, aggregate);
+		const failure = states.find((entry) => entry.status === "error");
+		controller.setError(failure ? failure.error : void 0);
+		options.onProgress?.({
+			progress: aggregate,
+			files: states.slice()
+		});
+	}
+	function patch(id, changes) {
+		states = states.map((entry) => entry.id === id ? {
+			...entry,
+			...changes
+		} : entry);
+		writeStates();
+		recalc();
+	}
+	async function runFile(id) {
+		const entry = states.find((candidate) => candidate.id === id);
+		if (!entry || entry.status === "success" || entry.status === "uploading") return;
+		patch(id, {
+			status: "uploading",
+			error: void 0
+		});
+		const form = new FormData();
+		form.append(fieldName, entry.file, entry.file.name);
+		const snail = method(form);
+		inFlight.add(snail);
+		try {
+			const sending = snail.send(form);
+			attachUploadProgress(snail, (event) => {
+				if (!event.total || event.total <= 0) return;
+				patch(id, { progress: clamp01(event.loaded / event.total) });
+			});
+			const result = await sending;
+			patch(id, {
+				status: "success",
+				progress: 1,
+				response: result.data,
+				error: void 0
+			});
+			controller.setData(result.data);
+			controller.setCode(result.code);
+			controller.setMessage(result.message);
+			controller.emitSuccess(result.data);
+		} catch (error) {
+			if (isCancellation(error)) {
+				patch(id, {
+					status: "pending",
+					progress: 0,
+					error: void 0
+				});
+				return;
+			}
+			patch(id, {
+				status: "error",
+				error
+			});
+			controller.applyFailure(error);
+			controller.emitError(error);
+		} finally {
+			inFlight.delete(snail);
+			recalc();
+		}
+	}
+	async function upload(input) {
+		const incoming = normalizeFiles(input);
+		const accepted = options.multiple === false ? incoming.slice(0, 1) : incoming;
+		if (accepted.length === 0) return;
+		const queued = accepted.map((file) => {
+			sequence += 1;
+			return {
+				id: `upload-${sequence}`,
+				file,
+				status: "pending",
+				progress: 0,
+				error: void 0,
+				response: void 0
+			};
+		});
+		controller.resetForSend();
+		states = [...states, ...queued];
+		writeStates();
+		recalc();
+		for (const entry of queued) queue.add(() => runFile(entry.id));
+		await queue.drain();
+	}
+	function retry(id) {
+		const entry = states.find((candidate) => candidate.id === id);
+		if (!entry || entry.status === "success" || entry.status === "uploading") return;
+		patch(id, {
+			status: "pending",
+			progress: 0,
+			error: void 0
+		});
+		queue.add(() => runFile(id));
+	}
+	return {
+		...state,
+		upload,
+		files,
+		progress,
+		retry
+	};
+}
+//#endregion
+//#region src/strategies/use-token-auth.ts
+/** `ctx.state` key holding the token one request was actually sent with. */
+var USED_TOKEN = "token-auth:used";
+/**
+* Read the HTTP status a failure carried, without assuming an axios error class.
+*
+* Only a transport-level 401 is recoverable here. A backend that answers HTTP 200
+* with `{ code: 401 }` produces its `SnailResponseError` in `SnailMethod.finalize`,
+* *after* the `beforeRequest` chain has already returned — and no hook can recover
+* a post-chain failure (`onError` is observe-only by design). Such a response is
+* left to the caller.
+*/
+function statusOf(error) {
+	const candidate = error;
+	const status = candidate?.response?.status ?? candidate?.status;
+	return typeof status === "number" ? status : void 0;
+}
+/**
+* Bearer-token authentication with single-flight refresh, as a plugin.
+*
+* ```ts
+* const auth = useTokenAuth({
+*   token: () => localStorage.getItem("token"),
+*   refresh: async () => (await api.refresh().send()).token,
+*   onUnauthorized: () => router.push("/login")
+* });
+*
+* Service.use(auth.plugin);
+* auth.setToken("...");
+* ```
+*
+* ## Why a plugin and not a hook
+*
+* A token is global: every request of the service has to carry it, and a 401 on
+* any one of them has to invalidate the token for all of them. A per-method hook
+* could not see the other requests, so refresh coordination would be impossible.
+*
+* ## Exactly one refresh per wave of 401s
+*
+* Three parallel requests, one expired token, three 401s. Refreshing per request
+* would fire three refreshes and, with a rotating refresh token, two of them would
+* fail and log the user out. Two mechanisms prevent that:
+*
+* 1. a request that 401s while a refresh is already in flight **joins** it instead
+*    of starting a second one;
+* 2. a request whose 401 was produced by a token that has since been replaced
+*    replays directly, without refreshing again.
+*
+* The token each request was sent with is remembered in `ctx.state` (which the core
+* clears per send), and that is what makes rule 2 decidable without keeping
+* timers around.
+*
+* ## Replaying
+*
+* `onError` cannot recover a failure — the core rethrows after every `onError`
+* hook — so the recovery lives in `beforeRequest`, around `await next()`. The
+* replay re-runs the `requestInterceptor` reduce, the transport and the
+* `afterResponse` chain, so headers a plugin signs are recomputed for the retried
+* call. `beforeRequest` hooks are deliberately *not* re-entered: the refresh
+* decision has already been made, and re-entering could loop.
+*
+* ## What this cannot recover
+*
+* Only a **transport** 401 (HTTP 401). A backend that reports `{ code: 401 }` with
+* HTTP 200 fails in `finalize`, after the chain, where no hook can intervene; that
+* response reaches the caller as a `SnailResponseError`.
+*/
+function useTokenAuth(options) {
+	const header = options.header ?? "authorization";
+	const scheme = options.scheme ?? "Bearer";
+	let cached;
+	let refreshing;
+	let disposed = false;
+	/** Resolves when the plugin is uninstalled; lets queued requests bail out. */
+	const disposal = deferred();
+	async function readToken() {
+		if (cached !== void 0) return cached;
+		const value = await options.token();
+		if (typeof value === "string" && value.length > 0) cached = value;
+		return cached;
+	}
+	function inject(ctx, token) {
+		ctx.request.headers.set(header, scheme ? `${scheme} ${token}` : token);
+	}
+	/** Start the one refresh this wave gets, or return the one already running. */
+	function startRefresh() {
+		if (refreshing) return refreshing;
+		const tracked = Promise.resolve().then(() => options.refresh()).then((token) => {
+			if (typeof token === "string" && token.length > 0) cached = token;
+			return cached ?? token;
+		}).finally(() => {
+			if (refreshing === tracked) refreshing = void 0;
+		});
+		refreshing = tracked;
+		tracked.catch(noop);
+		return tracked;
+	}
+	/**
+	* Await a refresh, giving up early when the plugin is uninstalled.
+	*
+	* @returns `true` when a fresh token is available, `false` when the refresh
+	* failed or the plugin went away — in both cases the caller rethrows the
+	* **original** 401, because the refresh error is an implementation detail the
+	* application cannot act on.
+	*/
+	async function settleRefresh(pending) {
+		try {
+			await Promise.race([pending, disposal.promise]);
+		} catch {
+			return false;
+		}
+		return !disposed;
+	}
+	/**
+	* Re-send the request that 401'd, with the refreshed token.
+	*
+	* The replay reproduces `SnailMethod.dispatch` using public plugin-manager
+	* surface. It intentionally skips the `beforeRequest` chain — see the hook
+	* documentation.
+	*/
+	async function replay(ctx) {
+		const manager = ctx.server.pluginManager;
+		const config = manager.reduce("requestInterceptor", ctx.request, ctx);
+		ctx.request = config;
+		const response = await ctx.server.axios.request(config);
+		ctx.setResponse(response);
+		await manager.runChain("afterResponse", ctx);
+	}
+	return {
+		plugin: createPlugin({
+			name: "token-auth",
+			priority: 20,
+			setup(_pluginOptions, api) {
+				api.onDispose(() => {
+					disposed = true;
+					disposal.resolve();
+				});
+				return { async beforeRequest(ctx, next) {
+					if (disposed) {
+						await next();
+						return;
+					}
+					if (refreshing) await settleRefresh(refreshing);
+					const token = await readToken();
+					if (token) inject(ctx, token);
+					ctx.state.set(USED_TOKEN, token);
+					try {
+						await next();
+					} catch (error) {
+						if (disposed || statusOf(error) !== 401) throw error;
+						const used = ctx.state.get(USED_TOKEN);
+						if (!(cached !== void 0 && used !== void 0 && cached !== used)) {
+							if (!await settleRefresh(refreshing ?? startRefresh())) {
+								options.onUnauthorized?.(error);
+								throw error;
+							}
+						}
+						const refreshed = await readToken();
+						if (refreshed) inject(ctx, refreshed);
+						try {
+							await replay(ctx);
+						} catch (replayError) {
+							if (statusOf(replayError) === 401) options.onUnauthorized?.(replayError);
+							throw replayError;
+						}
+					}
+				} };
+			}
+		})(options),
+		setToken(token) {
+			cached = typeof token === "string" && token.length > 0 ? token : void 0;
+		},
+		getToken() {
+			return cached;
+		},
+		clearToken() {
+			cached = void 0;
+		}
+	};
+}
+//#endregion
+//#region src/strategies/use-sse.ts
+/** Find the message tap an endpoint or its connection offers, if any. */
+function attachTap(endpoint, connection, listener) {
+	if (typeof endpoint.subscribe === "function") return endpoint.subscribe(listener) ?? noop;
+	const onMessage = connection.onMessage;
+	if (typeof onMessage === "function") return onMessage.call(connection, listener) ?? noop;
+	return noop;
+}
+/**
+* Consume a Server-Sent Events endpoint as reactive state.
+*
+* ```ts
+* const events = Service.createSse(Events);
+* const feed = useSSE(events, { maxMessages: 50 });
+* feed.open();
+* feed.messages.value;   // SnailSseMessage[]
+* feed.close();
+* ```
+*
+* ## The message tap
+*
+* `Service.createSse()` returns an object whose only member is `open()`, and the
+* messages it parses are dispatched to the decorated class's methods
+* (`@SseEvent()`), not to the caller. `useSSE` therefore accepts an endpoint that
+* additionally implements `subscribe(listener)`, or a connection that implements
+* `onMessage(listener)`. Both extend the core contract without changing it; an
+* endpoint that implements neither still reports `connected`/`error` faithfully,
+* it just never fills `messages`.
+*
+* ## Never an unhandled rejection
+*
+* A rejected `opened` promise is exactly how a failed SSE connect is reported, and
+* nothing else in the application will ever await it. Both `opened` and `closed`
+* are handled here, so a dead server cannot take the process down with an
+* unhandled rejection.
+*/
+function useSSE(endpoint, options = {}) {
+	const adapter = resolveStateAdapter(options);
+	const maxMessages = Number.isFinite(options.maxMessages) ? Math.max(1, Math.floor(options.maxMessages)) : 100;
+	const messages = adapter.create([]);
+	const lastMessage = adapter.create(void 0);
+	const connected = adapter.create(false);
+	const error = adapter.create(void 0);
+	let connection;
+	let detach;
+	let listening = false;
+	function handle(message) {
+		try {
+			if (options.filter && !options.filter(message)) return;
+			const buffered = [...adapter.read(messages), message];
+			if (buffered.length > maxMessages) buffered.splice(0, buffered.length - maxMessages);
+			adapter.write(messages, buffered);
+			adapter.write(lastMessage, message);
+			options.onMessage?.(message);
+		} catch (cause) {
+			adapter.write(error, cause);
+		}
+		adapter.write(connected, connection?.connected ?? adapter.read(connected));
+	}
+	function open() {
+		if (listening) return;
+		detach?.();
+		detach = void 0;
+		const next = endpoint.open();
+		connection = next;
+		listening = true;
+		detach = attachTap(endpoint, next, handle);
+		adapter.write(connected, next.connected);
+		adapter.write(error, void 0);
+		next.opened.then(() => {
+			if (connection !== next) return;
+			adapter.write(connected, true);
+			adapter.write(error, void 0);
+		}, (cause) => {
+			if (connection !== next) return;
+			adapter.write(connected, false);
+			adapter.write(error, cause);
+		});
+		next.closed.then(() => {
+			if (connection !== next) return;
+			listening = false;
+			adapter.write(connected, false);
+		}, () => {
+			if (connection !== next) return;
+			listening = false;
+			adapter.write(connected, false);
+		});
+	}
+	function close() {
+		const current = connection;
+		connection = void 0;
+		listening = false;
+		adapter.write(connected, false);
+		detach?.();
+		detach = void 0;
+		current?.close();
+	}
+	function clear() {
+		adapter.write(messages, []);
+		adapter.write(lastMessage, void 0);
+	}
+	if (options.immediate) open();
+	return {
+		messages,
+		lastMessage,
+		connected,
+		error,
+		open,
+		close,
+		clear,
+		bind() {
+			return {
+				messages: bindRef(adapter, messages),
+				lastMessage: bindRef(adapter, lastMessage),
+				connected: bindRef(adapter, connected),
+				error: bindRef(adapter, error)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/strategies/use-download.ts
+/**
+* Drive a server-prepared download.
+*
+* ```ts
+* @Api("/report")
+* class ReportApi {
+*   /** Prepares the export server-side and answers with a temp url. *\/
+*   @Post("/export")
+*   create(@Data() query: ReportQuery): Promise<{ url: string; filename: string }> {
+*     return null!;
+*   }
+* }
+*
+* const { download, loading, error } = useDownload(reportApi.create);
+* await download({ from: "2026-01-01" });
+* ```
+*
+* ## Why it does not fetch the file
+*
+* `useDownload` awaits the request that *mints* a download URL, and only that. It
+* never fetches the file itself. Buffering a response into a `Blob` costs the whole
+* file in JavaScript memory — twice, once for the body and once for the object URL
+* — with no progress and no resume. Letting the browser fetch the URL instead gives
+* you the native download manager, streaming to disk, resume support and a download
+* that survives navigation.
+*
+* ## Why this is a strategy and not a plugin
+*
+* A plugin is for a cross-cutting concern that applies to requests an application
+* did not write specially: caching, interceptors, validation. A download is the
+* opposite — one explicit user action, with its own visible state and its own
+* failure modes, invoked from a click handler. That is the definition of a request
+* strategy. The reusable half that is *not* about reactivity — clicking a temporary
+* anchor — lives in `triggerDownload()`, which is exported from the package root so
+* a non-hook caller can use it directly.
+*/
+function useDownload(method, options = {}) {
+	const holder = createMethodHolder(method);
+	const controller = createStrategyState({
+		adapter: options.adapter,
+		onAbort: () => holder.abort()
+	});
+	const { state, adapter } = controller;
+	const info = adapter.create(void 0);
+	const downloadListeners = /* @__PURE__ */ new Set();
+	if (options.onSuccess) state.onSuccess(options.onSuccess);
+	if (options.onError) state.onError(options.onError);
+	if (options.onFinish) state.onFinish(options.onFinish);
+	const triggerOptions = {
+		openInNewTab: options.openInNewTab,
+		container: options.container,
+		referrerPolicy: options.referrerPolicy
+	};
+	/** Fire the browser download, surfacing a throwing callback as a state error. */
+	function dispatch(descriptor) {
+		const result = triggerDownload(descriptor.url, {
+			...triggerOptions,
+			filename: options.filename ?? descriptor.filename
+		});
+		adapter.write(info, descriptor);
+		for (const listener of [...downloadListeners]) try {
+			listener(descriptor);
+		} catch {}
+		return result;
+	}
+	async function download(...args) {
+		controller.resetForSend();
+		controller.setLoading(true);
+		try {
+			const result = await holder.resolve(args).send(...args);
+			const descriptor = resolveDescriptor(result.data, options);
+			let triggered;
+			if (options.autoTrigger === false) {
+				adapter.write(info, descriptor);
+				triggered = {
+					url: descriptor.url,
+					filename: descriptor.filename
+				};
+			} else triggered = dispatch(descriptor);
+			controller.applySuccess(result);
+			controller.emitSuccess(result.data);
+			return triggered;
+		} catch (error) {
+			if (!isCancellation(error)) {
+				controller.applyFailure(error);
+				controller.emitError(error);
+			}
+			throw error;
+		} finally {
+			controller.setLoading(false);
+			controller.emitFinish();
+		}
+	}
+	return {
+		...state,
+		download,
+		info,
+		onDownload(callback) {
+			downloadListeners.add(callback);
+			return () => {
+				downloadListeners.delete(callback);
+			};
+		}
+	};
+}
+/**
+* Turn a payload into a descriptor.
+*
+* Accepting several spellings is not sloppiness — it removes a naming argument from
+* every integration. A backend that answers `{ fileUrl }` should not force a `pick`
+* implementation for the sake of one word.
+*/
+function resolveDescriptor(payload, options) {
+	if (options.pick) {
+		const descriptor = options.pick(payload);
+		if (!descriptor || typeof descriptor.url !== "string" || descriptor.url.length === 0) throw new TypeError("[snail] useDownload: `pick` must return a descriptor with a non-empty `url`");
+		return descriptor;
+	}
+	if (typeof payload === "string" && payload.length > 0) return { url: payload };
+	const candidate = payload;
+	if (candidate && typeof candidate === "object") {
+		const url = candidate.url ?? candidate.downloadUrl ?? candidate.fileUrl;
+		if (typeof url === "string" && url.length > 0) {
+			const filename = candidate.filename ?? candidate.name;
+			return filename ? {
+				url,
+				filename
+			} : { url };
+		}
+	}
+	throw new TypeError("[snail] useDownload: the response carried no download url. Expected a string, or an object with `url` / `downloadUrl` / `fileUrl`. Pass `pick` if your server names it differently.");
+}
+//#endregion
+export { useRetriableRequest as a, useFetcher as c, createStrategyState as d, setStateAdapter as f, useUploader as i, useWatcher as l, useSSE as n, useAutoRequest as o, plainStateAdapter as p, useTokenAuth as r, usePagination as s, useDownload as t, useRequest as u };
+
+//# sourceMappingURL=use-download-FAjtdJ58.js.map