@vizejs/composable 0.345.0 → 0.347.7

package/dist/locale.d.mts

@@ -0,0 +1,65 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/locale.d.ts
+/** Text flow reported by the internationalization runtime. */
+type TextDirection = "ltr" | "rtl";
+/** Locale selection options for {@link useLocale}. */
+interface UseLocaleOptions {
+  /**
+   * Locale detector used when the reactive source has no value.
+   *
+   * @default navigator.language when available; otherwise undefined
+   */
+  readonly detect?: () => Intl.Locale | string | null | undefined;
+  /**
+   * Locale used when neither the source nor detector provides one.
+   *
+   * @default "en"
+   */
+  readonly fallback?: Intl.Locale | string;
+}
+/**
+ * Reactive locale metadata and cached formatter factories.
+ *
+ * Formatter factories propagate `TypeError` and `RangeError` from the
+ * platform `Intl` constructors when the supplied options are invalid.
+ */
+interface LocaleControls {
+  /** Canonical Unicode locale identifier. */
+  readonly locale: ComputedRef<string>;
+  /** Parsed locale details supplied by the internationalization runtime. */
+  readonly details: ComputedRef<Intl.Locale>;
+  /** Native writing direction for the active locale. */
+  readonly direction: ComputedRef<TextDirection>;
+  /** Return a cached number formatter for the active locale and options. */
+  readonly number: (options?: Intl.NumberFormatOptions) => Intl.NumberFormat;
+  /** Return a cached date and time formatter for the active locale and options. */
+  readonly dateTime: (options?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
+  /** Return a cached list formatter for the active locale and options. */
+  readonly list: (options?: Intl.ListFormatOptions) => Intl.ListFormat;
+  /** Return a cached relative-time formatter for the active locale and options. */
+  readonly relativeTime: (options?: Intl.RelativeTimeFormatOptions) => Intl.RelativeTimeFormat;
+}
+/**
+ * Create reactive locale metadata and platform-native formatter factories.
+ *
+ * Equivalent formatter options reuse instances. The bounded cache follows the
+ * active locale automatically and prevents repeated constructor overhead in
+ * reactive render paths.
+ *
+ * Detection is lazy and guarded: the default detector reads
+ * `navigator.language` behind a `typeof` check at call time, so importing and
+ * calling this during server rendering is safe, and runtimes without a
+ * `navigator` resolve to the fallback locale. The composable owns no timers
+ * or listeners, so no scope cleanup is required.
+ *
+ * @param source Reactive locale source. Empty values defer to the detector.
+ * @param options Detection and fallback behavior.
+ * @default options {}
+ * @throws `RangeError` on first read of the reactive values when the winning
+ * candidate is not a structurally valid locale identifier.
+ * @returns Reactive locale metadata and cached formatter factories.
+ */
+declare function useLocale(source?: MaybeRefOrGetter<Intl.Locale | string | null | undefined>, options?: UseLocaleOptions): LocaleControls;
+//#endregion
+export { LocaleControls, TextDirection, UseLocaleOptions, useLocale };

package/dist/locale.mjs

@@ -0,0 +1,72 @@
+import { computed, toValue } from "vue";
+//#region src/locale.ts
+const FORMATTER_CACHE_LIMIT = 32;
+/**
+* Create reactive locale metadata and platform-native formatter factories.
+*
+* Equivalent formatter options reuse instances. The bounded cache follows the
+* active locale automatically and prevents repeated constructor overhead in
+* reactive render paths.
+*
+* Detection is lazy and guarded: the default detector reads
+* `navigator.language` behind a `typeof` check at call time, so importing and
+* calling this during server rendering is safe, and runtimes without a
+* `navigator` resolve to the fallback locale. The composable owns no timers
+* or listeners, so no scope cleanup is required.
+*
+* @param source Reactive locale source. Empty values defer to the detector.
+* @param options Detection and fallback behavior.
+* @default options {}
+* @throws `RangeError` on first read of the reactive values when the winning
+* candidate is not a structurally valid locale identifier.
+* @returns Reactive locale metadata and cached formatter factories.
+*/
+function useLocale(source, options = {}) {
+	const locale = computed(() => {
+		const candidate = (source === void 0 ? void 0 : toValue(source)) ?? (options.detect ?? detectBrowserLocale)() ?? options.fallback ?? "en";
+		return candidate instanceof Intl.Locale ? candidate.toString() : new Intl.Locale(candidate).toString();
+	});
+	const details = computed(() => new Intl.Locale(locale.value));
+	const direction = computed(() => details.value.getTextInfo().direction ?? "ltr");
+	const number = createFormatterCache((activeLocale, formatOptions) => new Intl.NumberFormat(activeLocale, formatOptions));
+	const dateTime = createFormatterCache((activeLocale, formatOptions) => new Intl.DateTimeFormat(activeLocale, formatOptions));
+	const list = createFormatterCache((activeLocale, formatOptions) => new Intl.ListFormat(activeLocale, formatOptions));
+	const relativeTime = createFormatterCache((activeLocale, formatOptions) => new Intl.RelativeTimeFormat(activeLocale, formatOptions));
+	return {
+		locale,
+		details,
+		direction,
+		number: (formatOptions) => number(locale.value, formatOptions),
+		dateTime: (formatOptions) => dateTime(locale.value, formatOptions),
+		list: (formatOptions) => list(locale.value, formatOptions),
+		relativeTime: (formatOptions) => relativeTime(locale.value, formatOptions)
+	};
+}
+function detectBrowserLocale() {
+	return typeof navigator === "undefined" ? void 0 : navigator.language;
+}
+function createFormatterCache(create) {
+	const cache = /* @__PURE__ */ new Map();
+	return (locale, options) => {
+		const key = `${locale}\u0000${serializeOptions(options)}`;
+		const cached = cache.get(key);
+		if (cached !== void 0) {
+			cache.delete(key);
+			cache.set(key, cached);
+			return cached;
+		}
+		const formatter = create(locale, options);
+		if (cache.size >= FORMATTER_CACHE_LIMIT) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== void 0) cache.delete(oldest);
+		}
+		cache.set(key, formatter);
+		return formatter;
+	};
+}
+function serializeOptions(options) {
+	if (options === void 0) return "";
+	return JSON.stringify(Object.entries(options).sort(([left], [right]) => left.localeCompare(right)));
+}
+//#endregion
+export { useLocale };

package/dist/media-query.d.mts

@@ -0,0 +1,56 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/media-query.d.ts
+/** Capability required to evaluate media queries. */
+interface MediaQueryHost {
+  /** Create an observable result for a media query. */
+  readonly matchMedia: (query: string) => MediaQueryList;
+}
+/** Options for {@link useMediaQuery}. */
+interface UseMediaQueryOptions {
+  /**
+   * Value exposed when no media-query capability is available.
+   *
+   * @default false
+   */
+  readonly ssrValue?: boolean;
+  /**
+   * Reactive media-query capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<MediaQueryHost | null | undefined>;
+}
+/**
+ * Evaluate a reactive media query without requiring browser globals.
+ *
+ * During server rendering (or whenever no capability host resolves) the ref
+ * holds the configured server value and no subscription is created. The
+ * change subscription follows the reactive query and host: each
+ * re-evaluation removes the previous listener, and the final listener is
+ * removed when the owning reactive scope stops. Call inside an active scope
+ * so the subscription is released. A host whose matcher throws propagates
+ * the error to the active effect run; the browser default never throws.
+ *
+ * @param query Reactive media-query source.
+ * @param options Runtime capability and server-rendered fallback.
+ * @default options {}
+ * @returns Readonly ref that is `true` while the query matches.
+ */
+declare function useMediaQuery(query: MaybeRefOrGetter<string>, options?: UseMediaQueryOptions): Readonly<Ref<boolean>>;
+/** User motion preference exposed by {@link useReducedMotion}. */
+type MotionPreference = "reduce" | "no-preference";
+/**
+ * Return the reactive user motion preference.
+ *
+ * Shares {@link useMediaQuery} semantics: during server rendering the
+ * preference is `"no-preference"` unless `ssrValue` is `true`, and the
+ * underlying subscription is removed when the owning reactive scope stops.
+ *
+ * @param options Runtime capability and server-rendered fallback.
+ * @default options {}
+ * @returns Computed preference for `(prefers-reduced-motion: reduce)`.
+ */
+declare function useReducedMotion(options?: UseMediaQueryOptions): ComputedRef<MotionPreference>;
+//#endregion
+export { MediaQueryHost, MotionPreference, UseMediaQueryOptions, useMediaQuery, useReducedMotion };

package/dist/media-query.mjs

@@ -0,0 +1,56 @@
+import { computed, readonly, ref, toValue, watchEffect } from "vue";
+//#region src/media-query.ts
+/**
+* Evaluate a reactive media query without requiring browser globals.
+*
+* During server rendering (or whenever no capability host resolves) the ref
+* holds the configured server value and no subscription is created. The
+* change subscription follows the reactive query and host: each
+* re-evaluation removes the previous listener, and the final listener is
+* removed when the owning reactive scope stops. Call inside an active scope
+* so the subscription is released. A host whose matcher throws propagates
+* the error to the active effect run; the browser default never throws.
+*
+* @param query Reactive media-query source.
+* @param options Runtime capability and server-rendered fallback.
+* @default options {}
+* @returns Readonly ref that is `true` while the query matches.
+*/
+function useMediaQuery(query, options = {}) {
+	const matches = ref(options.ssrValue ?? false);
+	watchEffect((onCleanup) => {
+		const host = options.host === void 0 ? browserMediaQueryHost() : toValue(options.host);
+		if (!host) {
+			matches.value = options.ssrValue ?? false;
+			return;
+		}
+		const media = host.matchMedia(toValue(query));
+		const update = () => {
+			matches.value = media.matches;
+		};
+		update();
+		media.addEventListener("change", update);
+		onCleanup(() => media.removeEventListener("change", update));
+	});
+	return readonly(matches);
+}
+/**
+* Return the reactive user motion preference.
+*
+* Shares {@link useMediaQuery} semantics: during server rendering the
+* preference is `"no-preference"` unless `ssrValue` is `true`, and the
+* underlying subscription is removed when the owning reactive scope stops.
+*
+* @param options Runtime capability and server-rendered fallback.
+* @default options {}
+* @returns Computed preference for `(prefers-reduced-motion: reduce)`.
+*/
+function useReducedMotion(options = {}) {
+	const reduced = useMediaQuery("(prefers-reduced-motion: reduce)", options);
+	return computed(() => reduced.value ? "reduce" : "no-preference");
+}
+function browserMediaQueryHost() {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window : void 0;
+}
+//#endregion
+export { useMediaQuery, useReducedMotion };

package/dist/retry-async.d.mts

@@ -0,0 +1,91 @@
+import { TimeoutScheduler } from "./timeout-scheduler.mjs";
+import { RetryDelayOptions } from "./retry-delay.mjs";
+
+//#region src/retry-async.d.ts
+/** Context supplied to every invocation of a retried operation. */
+interface RetryAttemptContext {
+  /** One-based operation attempt, including the initial call. */
+  readonly attempt: number;
+  /** Shared cancellation signal for the complete retry execution. */
+  readonly signal: AbortSignal;
+}
+/** Context supplied after an operation fails and before retry policy runs. */
+interface RetryFailureContext extends RetryAttemptContext {
+  /** Exact value thrown or rejected by the failed operation. */
+  readonly error: unknown;
+  /** One-based retry that would follow this failure. */
+  readonly retryAttempt: number;
+}
+/** Context supplied when an approved retry is about to wait. */
+interface RetryScheduledContext extends RetryFailureContext {
+  /** One-based operation attempt that will run after the wait. */
+  readonly nextAttempt: number;
+  /** Calculated backoff delay in integer milliseconds. */
+  readonly delayMs: number;
+}
+/** Options for {@link retryAsync}. */
+interface RetryAsyncOptions extends RetryDelayOptions {
+  /**
+   * Maximum retries after the initial operation attempt.
+   *
+   * @default 3
+   */
+  readonly maximumRetries?: number;
+  /**
+   * Cancels the active operation, policy hook, notification hook, or backoff
+   * wait. The returned promise rejects with the signal's exact reason.
+   *
+   * @default a private non-aborting signal
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Deterministic or host-specific scheduler used for backoff waits.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Decide whether an operation failure is retryable. Returning `false`
+   * rejects with the original operation error without calculating a delay.
+   * The decision may be asynchronous and remains abortable.
+   *
+   * @default every failure is retryable while retries remain
+   */
+  readonly shouldRetry?: (context: RetryFailureContext) => boolean | PromiseLike<boolean>;
+  /**
+   * Observe an approved retry before its backoff wait begins. The hook may be
+   * asynchronous and remains abortable; a hook failure is propagated exactly
+   * and the next operation attempt is not started.
+   *
+   * @default undefined
+   */
+  readonly onRetry?: (context: RetryScheduledContext) => void | PromiseLike<void>;
+}
+/**
+ * Execute an operation with bounded, abortable retries and deterministic delay policy.
+ *
+ * Synchronous throws and asynchronous rejections follow the same path. A
+ * successful value is returned unchanged. Exhaustion rejects with the final
+ * operation error, a negative retry decision rejects with the error that was
+ * evaluated, and cancellation rejects with the signal's exact reason. These
+ * values are deliberately not wrapped.
+ *
+ * Cancellation races every asynchronous stage, so callers are not forced to
+ * wait for an operation or hook that ignores its signal. Late settlements are
+ * still observed internally and cannot become unhandled rejections. Backoff
+ * options and entropy are evaluated lazily only after a failure is approved
+ * for retry.
+ *
+ * @typeParam Value Value produced by the operation.
+ * @param operation Work to invoke with a one-based attempt and shared signal.
+ * @param options Retry count, cancellation, policy, hooks, and delay options.
+ * @default options {}
+ * @throws {RangeError} A tagged error when `maximumRetries` or inherited delay
+ * options are outside their documented ranges.
+ * @throws {TypeError} A tagged error when `options` is not an object, a
+ * callback is not callable, or a retry decision does not resolve to a boolean.
+ * @returns The first successful operation value.
+ */
+declare function retryAsync<Value>(operation: (context: RetryAttemptContext) => Value | PromiseLike<Value>, options?: RetryAsyncOptions): Promise<Value>;
+//#endregion
+export { RetryAsyncOptions, RetryAttemptContext, RetryFailureContext, RetryScheduledContext, retryAsync };

package/dist/retry-async.mjs

@@ -0,0 +1,136 @@
+import { timeoutAbortSignal } from "./abort-signal.mjs";
+import { calculateRetryDelay } from "./retry-delay.mjs";
+//#region src/retry-async.ts
+/**
+* Execute an operation with bounded, abortable retries and deterministic delay policy.
+*
+* Synchronous throws and asynchronous rejections follow the same path. A
+* successful value is returned unchanged. Exhaustion rejects with the final
+* operation error, a negative retry decision rejects with the error that was
+* evaluated, and cancellation rejects with the signal's exact reason. These
+* values are deliberately not wrapped.
+*
+* Cancellation races every asynchronous stage, so callers are not forced to
+* wait for an operation or hook that ignores its signal. Late settlements are
+* still observed internally and cannot become unhandled rejections. Backoff
+* options and entropy are evaluated lazily only after a failure is approved
+* for retry.
+*
+* @typeParam Value Value produced by the operation.
+* @param operation Work to invoke with a one-based attempt and shared signal.
+* @param options Retry count, cancellation, policy, hooks, and delay options.
+* @default options {}
+* @throws {RangeError} A tagged error when `maximumRetries` or inherited delay
+* options are outside their documented ranges.
+* @throws {TypeError} A tagged error when `options` is not an object, a
+* callback is not callable, or a retry decision does not resolve to a boolean.
+* @returns The first successful operation value.
+*/
+async function retryAsync(operation, options = {}) {
+	if (typeof operation !== "function") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_OPERATION] operation must be a function; received ${typeof operation}`);
+	if (options === null || typeof options !== "object") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] options must be an object; received ${options === null ? "null" : typeof options}`);
+	const maximumRetries = options.maximumRetries === void 0 ? 3 : options.maximumRetries;
+	if (!Number.isSafeInteger(maximumRetries) || maximumRetries < 0 || maximumRetries >= Number.MAX_SAFE_INTEGER) throw new RangeError(`[VIZE_COMPOSE_RETRY_INVALID_MAXIMUM_RETRIES] maximumRetries must be an integer from 0 through ${String(Number.MAX_SAFE_INTEGER - 1)}; received ${String(maximumRetries)}`);
+	const shouldRetryPolicy = options.shouldRetry;
+	const retryObserver = options.onRetry;
+	if (shouldRetryPolicy !== void 0 && typeof shouldRetryPolicy !== "function") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_CALLBACK] shouldRetry must be a function; received ${typeof shouldRetryPolicy}`);
+	if (retryObserver !== void 0 && typeof retryObserver !== "function") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_CALLBACK] onRetry must be a function; received ${typeof retryObserver}`);
+	const signal = options.signal === void 0 ? new AbortController().signal : options.signal;
+	let attempt = 1;
+	while (true) {
+		throwIfAborted(signal);
+		const outcome = await capture(raceWithAbort(Promise.resolve().then(() => operation({
+			attempt,
+			signal
+		})), signal));
+		if (outcome.status === "success") return outcome.value;
+		if (signal.aborted) throw signal.reason;
+		if (attempt > maximumRetries) throw outcome.error;
+		const failure = {
+			attempt,
+			error: outcome.error,
+			retryAttempt: attempt,
+			signal
+		};
+		if (shouldRetryPolicy !== void 0) {
+			const shouldRetry = await raceWithAbort(Promise.resolve().then(() => shouldRetryPolicy(failure)), signal);
+			if (typeof shouldRetry !== "boolean") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_DECISION] shouldRetry must resolve to a boolean; received ${typeof shouldRetry}`);
+			if (!shouldRetry) throw outcome.error;
+		}
+		throwIfAborted(signal);
+		const delayMs = calculateRetryDelay(attempt, options);
+		const scheduled = {
+			...failure,
+			delayMs,
+			nextAttempt: attempt + 1
+		};
+		if (retryObserver !== void 0) await raceWithAbort(Promise.resolve().then(() => retryObserver(scheduled)), signal);
+		await waitForRetry(delayMs, signal, options.scheduler);
+		attempt += 1;
+	}
+}
+async function capture(promise) {
+	try {
+		return {
+			status: "success",
+			value: await promise
+		};
+	} catch (error) {
+		return {
+			status: "error",
+			error
+		};
+	}
+}
+function raceWithAbort(promise, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		let listening = false;
+		let settled = false;
+		const cleanup = () => {
+			if (!listening) return;
+			listening = false;
+			try {
+				signal.removeEventListener("abort", onAbort);
+			} catch {}
+		};
+		const settle = (callback) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			callback();
+		};
+		const onAbort = () => settle(() => reject(signal.reason));
+		promise.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
+		try {
+			listening = true;
+			signal.addEventListener("abort", onAbort, { once: true });
+			if (settled) cleanup();
+			else if (signal.aborted) onAbort();
+		} catch (error) {
+			settle(() => reject(error));
+		}
+	});
+}
+async function waitForRetry(delayMs, signal, scheduler) {
+	const elapsed = {};
+	const delaySignal = timeoutAbortSignal(delayMs, scheduler === void 0 ? {
+		reason: elapsed,
+		signal
+	} : {
+		reason: elapsed,
+		scheduler,
+		signal
+	});
+	try {
+		await raceWithAbort(new Promise(() => void 0), delaySignal);
+	} catch (reason) {
+		if (reason === elapsed) return;
+		throw reason;
+	}
+}
+function throwIfAborted(signal) {
+	if (signal.aborted) throw signal.reason;
+}
+//#endregion
+export { retryAsync };

package/dist/retry-delay.d.mts

@@ -0,0 +1,73 @@
+//#region src/retry-delay.d.ts
+/** Options for {@link calculateRetryDelay}. */
+interface RetryDelayOptions {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 100
+   */
+  readonly initialDelayMs?: number;
+  /**
+   * Exponential multiplier applied for each subsequent retry.
+   *
+   * Values may be fractional but must be finite and at least one. The
+   * calculated delay is rounded up so a retry never starts earlier than the
+   * requested backoff.
+   *
+   * @default 2
+   */
+  readonly multiplier?: number;
+  /**
+   * Inclusive ceiling for the calculated delay, in milliseconds.
+   *
+   * The ceiling may be lower than {@link RetryDelayOptions.initialDelayMs};
+   * in that case it also caps the first retry.
+   *
+   * @default 30000
+   */
+  readonly maximumDelayMs?: number;
+  /**
+   * Fraction of the capped delay eligible for downward jitter.
+   *
+   * `0` is deterministic exponential backoff, `0.5` samples from the upper
+   * half of the range, and `1` applies full jitter from zero through the
+   * capped delay. Jitter never exceeds the unjittered delay.
+   *
+   * @default 0
+   */
+  readonly jitterRatio?: number;
+  /**
+   * Entropy source returning a number in the half-open interval `[0, 1)`.
+   * It is called exactly once when the selected jitter range contains more
+   * than one integer millisecond, and is otherwise not read.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+}
+/**
+ * Calculate a bounded exponential-backoff delay for a one-based retry.
+ *
+ * The first retry is `retryAttempt = 1`. The result is always an integer from
+ * zero through `2_147_483_647`, making it safe to pass to common host timer
+ * APIs without implementation-specific clamping. The calculation is pure
+ * unless jitter requires the supplied entropy source, and it performs no work
+ * when the module is imported.
+ *
+ * Jitter samples uniformly from the inclusive integer range
+ * `ceil(cappedDelay * (1 - jitterRatio))...cappedDelay`. Capping occurs before
+ * jitter, so neither floating-point overflow nor entropy can exceed the
+ * configured maximum.
+ *
+ * @param retryAttempt One-based retry number after a failed initial attempt.
+ * @param options Backoff, cap, jitter, and entropy configuration.
+ * @default options {}
+ * @throws {RangeError} A tagged error when the retry number, delay options, or
+ * entropy value is outside its documented range.
+ * @throws {TypeError} A tagged error when `options` is not an object or
+ * `random` is not callable.
+ * @returns An integer delay in milliseconds.
+ */
+declare function calculateRetryDelay(retryAttempt: number, options?: RetryDelayOptions): number;
+//#endregion
+export { RetryDelayOptions, calculateRetryDelay };

package/dist/retry-delay.mjs

@@ -0,0 +1,50 @@
+//#region src/retry-delay.ts
+/**
+* Calculate a bounded exponential-backoff delay for a one-based retry.
+*
+* The first retry is `retryAttempt = 1`. The result is always an integer from
+* zero through `2_147_483_647`, making it safe to pass to common host timer
+* APIs without implementation-specific clamping. The calculation is pure
+* unless jitter requires the supplied entropy source, and it performs no work
+* when the module is imported.
+*
+* Jitter samples uniformly from the inclusive integer range
+* `ceil(cappedDelay * (1 - jitterRatio))...cappedDelay`. Capping occurs before
+* jitter, so neither floating-point overflow nor entropy can exceed the
+* configured maximum.
+*
+* @param retryAttempt One-based retry number after a failed initial attempt.
+* @param options Backoff, cap, jitter, and entropy configuration.
+* @default options {}
+* @throws {RangeError} A tagged error when the retry number, delay options, or
+* entropy value is outside its documented range.
+* @throws {TypeError} A tagged error when `options` is not an object or
+* `random` is not callable.
+* @returns An integer delay in milliseconds.
+*/
+function calculateRetryDelay(retryAttempt, options = {}) {
+	if (!Number.isSafeInteger(retryAttempt) || retryAttempt < 1) throw new RangeError(`[VIZE_COMPOSE_RETRY_INVALID_ATTEMPT] retryAttempt must be a positive safe integer; received ${String(retryAttempt)}`);
+	if (options === null || typeof options !== "object") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] options must be an object; received ${options === null ? "null" : typeof options}`);
+	const initialDelayMs = options.initialDelayMs === void 0 ? 100 : options.initialDelayMs;
+	const multiplier = options.multiplier === void 0 ? 2 : options.multiplier;
+	const maximumDelayMs = options.maximumDelayMs === void 0 ? 3e4 : options.maximumDelayMs;
+	const jitterRatio = options.jitterRatio === void 0 ? 0 : options.jitterRatio;
+	if (!isPortableDelay(initialDelayMs) || !isPortableDelay(maximumDelayMs) || !Number.isFinite(multiplier) || multiplier < 1 || !Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) throw new RangeError(`[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] initialDelayMs and maximumDelayMs must be integers from 0 through ${String(maximumPortableTimeoutMs)}, multiplier must be finite and at least 1, and jitterRatio must be from 0 through 1; received initialDelayMs=${String(initialDelayMs)}, maximumDelayMs=${String(maximumDelayMs)}, multiplier=${String(multiplier)}, jitterRatio=${String(jitterRatio)}`);
+	if (initialDelayMs === 0 || maximumDelayMs === 0) return 0;
+	const scaledDelay = initialDelayMs * multiplier ** (retryAttempt - 1);
+	const cappedDelay = Math.min(maximumDelayMs, Math.ceil(scaledDelay));
+	const minimumDelay = Math.ceil(cappedDelay * (1 - jitterRatio));
+	const integerRange = cappedDelay - minimumDelay;
+	if (integerRange === 0) return cappedDelay;
+	const random = options.random === void 0 ? Math.random : options.random;
+	if (typeof random !== "function") throw new TypeError(`[VIZE_COMPOSE_RETRY_INVALID_RANDOM] random must be a function; received ${typeof random}`);
+	const sample = random();
+	if (!Number.isFinite(sample) || sample < 0 || sample >= 1) throw new RangeError(`[VIZE_COMPOSE_RETRY_INVALID_RANDOM] random must return a finite number from 0 up to but excluding 1; received ${String(sample)}`);
+	return minimumDelay + Math.floor(sample * (integerRange + 1));
+}
+function isPortableDelay(value) {
+	return Number.isSafeInteger(value) && value >= 0 && value <= maximumPortableTimeoutMs;
+}
+const maximumPortableTimeoutMs = 2147483647;
+//#endregion
+export { calculateRetryDelay };

package/dist/scope.d.mts

@@ -0,0 +1,18 @@
+//#region src/scope.d.ts
+/**
+ * Register cleanup in the active reactive scope when one exists.
+ *
+ * This is the shared lifecycle primitive of the package: composables hand
+ * their teardown here so owned resources are released when the surrounding
+ * scope stops.
+ *
+ * Never throws and is safe during server rendering; no browser globals are
+ * read. When no scope is active the cleanup is not registered and disposal
+ * ownership stays with the caller.
+ *
+ * @param cleanup Cleanup invoked exactly once when the scope is disposed.
+ * @returns Whether the cleanup was registered.
+ */
+declare function tryOnScopeDispose(cleanup: () => void): boolean;
+//#endregion
+export { tryOnScopeDispose };

package/dist/scope.mjs

@@ -0,0 +1,23 @@
+import { getCurrentScope, onScopeDispose } from "vue";
+//#region src/scope.ts
+/**
+* Register cleanup in the active reactive scope when one exists.
+*
+* This is the shared lifecycle primitive of the package: composables hand
+* their teardown here so owned resources are released when the surrounding
+* scope stops.
+*
+* Never throws and is safe during server rendering; no browser globals are
+* read. When no scope is active the cleanup is not registered and disposal
+* ownership stays with the caller.
+*
+* @param cleanup Cleanup invoked exactly once when the scope is disposed.
+* @returns Whether the cleanup was registered.
+*/
+function tryOnScopeDispose(cleanup) {
+	if (!getCurrentScope()) return false;
+	onScopeDispose(cleanup);
+	return true;
+}
+//#endregion
+export { tryOnScopeDispose };

package/dist/timeout-scheduler.d.mts

@@ -0,0 +1,18 @@
+//#region src/timeout-scheduler.d.ts
+/**
+ * Single-shot timer host used by the debounced and throttled state
+ * utilities.
+ *
+ * Implement this interface to integrate a deterministic test clock, a native
+ * runtime timer, or an application-owned scheduler. Handles are opaque: the
+ * utilities only hand them back to {@link TimeoutScheduler.clearTimeout}.
+ * This module declares types only and contributes no runtime code.
+ */
+interface TimeoutScheduler {
+  /** Starts a single-shot callback and returns its opaque cancellation handle. */
+  readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+  /** Cancels a handle previously returned by {@link TimeoutScheduler.setTimeout}. */
+  readonly clearTimeout: (handle: unknown) => void;
+}
+//#endregion
+export { TimeoutScheduler };

package/dist/timeout-scheduler.mjs

@@ -0,0 +1 @@
+export {};