@vizejs/composable 0.302.0 → 0.303.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ubugeeei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -50,18 +50,47 @@ interface UseAsyncResourceOptions<Data> {
 }
 /** Reactive state and controls for an asynchronous loader. */
 interface AsyncResource<Data, Arguments extends readonly unknown[], Failure> {
+  /** Data of the newest successful execution, retained according to `keepData`. */
   readonly data: Readonly<ShallowRef<Data | undefined>>;
+  /** Failure of the newest settled execution, cleared when a new one starts. */
   readonly error: Readonly<ShallowRef<Failure | undefined>>;
+  /** Current lifecycle status, driven only by the newest execution. */
   readonly status: Readonly<Ref<AsyncResourceStatus>>;
+  /** Whether an execution is currently pending. */
   readonly pending: ComputedRef<boolean>;
+  /**
+   * Run the loader. The returned promise never rejects: loader failures,
+   * cancellation, and supersession are reported as the discriminated result,
+   * and stale executions leave the reactive state untouched.
+   */
   readonly execute: (...arguments_: Arguments) => Promise<AsyncResourceExecution<Data, Failure>>;
+  /**
+   * Abort the active execution and mark the resource cancelled.
+   *
+   * @param reason Abort reason forwarded to the loader's signal.
+   * @default reason DOMException("AbortError")
+   * @returns Whether an active execution was cancelled.
+   */
   readonly cancel: (reason?: unknown) => boolean;
+  /** Cancel any active execution and restore the initial idle state. */
   readonly reset: () => void;
 }
 /**
  * Create a scoped, abortable asynchronous resource with latest-result-wins
  * state. Every execution returns a discriminated result, so cancellation,
  * supersession, loader failure, and successful `undefined` data stay distinct.
+ *
+ * When created inside an active reactive scope (and `scope` is enabled), the
+ * active execution is aborted when that scope stops; outside a scope,
+ * cancellation ownership stays with the caller. The execute promise never
+ * rejects — synchronous and asynchronous loader failures both settle into
+ * the `"error"` result. Safe during server rendering: no browser globals are
+ * read and abort reasons use the runtime-native `DOMException`.
+ *
+ * @param loader Asynchronous loader receiving the abort context first.
+ * @param options Data retention, supersession, and scope behavior.
+ * @default options {}
+ * @returns Reactive state and controls for the loader.
  */
 declare function useAsyncResource<Data, Arguments extends readonly unknown[], Failure = unknown>(loader: (context: AsyncResourceContext, ...arguments_: Arguments) => Promise<Data>, options?: UseAsyncResourceOptions<Data>): AsyncResource<Data, Arguments, Failure>;
 //#endregion
@@ -87,7 +116,8 @@ interface UseEventListenerOptions {
    */
   readonly passive?: boolean;
   /**
-   * Stop listening when this signal is aborted.
+   * Stop listening when this signal is aborted. An already-aborted signal
+   * prevents listening from ever starting.
    *
    * @default undefined
    */
@@ -112,7 +142,9 @@ interface EventListenerControls {
   /**
    * Begin listening.
    *
-   * @returns Whether a new reactive listener was started.
+   * @returns Whether a new reactive watcher was started. `false` while the
+   * watcher is already active (including a null-target watcher with no
+   * listener attached) and after the abort signal has fired.
    */
   readonly start: () => boolean;
   /** Stop listening. Repeated calls are safe. */
@@ -120,13 +152,23 @@ interface EventListenerControls {
 }
 /**
  * Attach an event listener to a reactive target and clean it up with the
- * current reactive scope. Missing targets are valid during server rendering.
+ * current reactive scope. Missing targets are valid during server rendering:
+ * a `null`/`undefined` target keeps the listener detached until a concrete
+ * target appears, so no browser globals are required.
+ *
+ * The listener is re-attached whenever the reactive target changes and is
+ * removed when the owning reactive scope stops, when
+ * {@link EventListenerControls.stop} is called, or when the abort signal
+ * fires. Outside an active scope, teardown ownership stays with the caller,
+ * who must call `stop` explicitly. Errors thrown by a custom target's
+ * add/remove methods propagate to the active watcher run.
  *
  * @param target Reactive event target.
  * @param event Event name.
  * @param listener Typed event listener.
  * @param options Listener lifecycle and scheduling options.
  * @default options {}
+ * @returns Controls to observe and change the listening state.
  */
 declare function useEventListener<Key extends keyof WindowEventMap>(target: MaybeRefOrGetter<Window | null | undefined>, event: Key, listener: (event: WindowEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
 declare function useEventListener<Key extends keyof DocumentEventMap>(target: MaybeRefOrGetter<Document | null | undefined>, event: Key, listener: (event: DocumentEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
@@ -151,7 +193,12 @@ interface UseLocaleOptions {
    */
   readonly fallback?: Intl.Locale | string;
 }
-/** Reactive locale metadata and cached formatter factories. */
+/**
+ * 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>;
@@ -174,6 +221,19 @@ interface LocaleControls {
  * 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
@@ -201,9 +261,18 @@ interface UseMediaQueryOptions {
 /**
  * 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}. */
@@ -211,8 +280,13 @@ 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
@@ -220,9 +294,492 @@ declare function useReducedMotion(options?: UseMediaQueryOptions): ComputedRef<M
 /**
  * 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 { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, EventListenerControls, LocaleControls, MediaQueryHost, MotionPreference, TextDirection, UseAsyncResourceOptions, UseEventListenerOptions, UseLocaleOptions, UseMediaQueryOptions, tryOnScopeDispose, useAsyncResource, useEventListener, useLocale, useMediaQuery, useReducedMotion };
+//#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
+//#region src/use-counter.d.ts
+/** Options for {@link useCounter}. */
+interface UseCounterOptions {
+  /**
+   * Inclusive lower bound applied to every value the counter takes.
+   *
+   * @default Number.NEGATIVE_INFINITY
+   */
+  readonly min?: number;
+  /**
+   * Inclusive upper bound applied to every value the counter takes.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly max?: number;
+}
+/** Reactive controls returned by {@link useCounter}. */
+interface CounterControls {
+  /** Current count. Changes only through the controls, never by assignment. */
+  readonly count: Readonly<ShallowRef<number>>;
+  /** Whether the count currently sits on the configured lower bound. */
+  readonly atMin: ComputedRef<boolean>;
+  /** Whether the count currently sits on the configured upper bound. */
+  readonly atMax: ComputedRef<boolean>;
+  /**
+   * Add `delta` (default `1`) to the count and clamp into the bounds.
+   *
+   * @param delta Amount added; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly increment: (delta?: number) => number;
+  /**
+   * Subtract `delta` (default `1`) from the count and clamp into the bounds.
+   *
+   * @param delta Amount subtracted; may be negative or infinite.
+   * @returns The count after clamping.
+   */
+  readonly decrement: (delta?: number) => number;
+  /**
+   * Assign a value directly, clamped into the bounds.
+   *
+   * @returns The count after clamping.
+   */
+  readonly set: (value: number) => number;
+  /**
+   * Restore the reset baseline, or establish a new one.
+   *
+   * Without an argument the count returns to the creation-time initial value
+   * (after its original clamping). With an argument, the clamped value
+   * becomes both the new count and the baseline used by later `reset()`
+   * calls.
+   *
+   * @param value Replacement baseline.
+   * @returns The count after clamping.
+   */
+  readonly reset: (value?: number) => number;
+}
+/**
+ * Create a clamped counter whose every transition stays inside `[min, max]`.
+ *
+ * All operations clamp instead of failing, including the initial value, so
+ * the count is inside the bounds at every observable moment. Only `NaN` is
+ * rejected — silently corrupting the count is never an option. Purely
+ * synchronous state: safe during server rendering (no browser globals, no
+ * timers) and nothing to dispose, so it works inside and outside reactive
+ * scopes alike. Bounds are fixed at creation and not reactive.
+ *
+ * @example
+ * ```ts
+ * const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
+ * increment(); // 10
+ * increment(); // 10 (clamped)
+ * atMax.value; // true
+ * ```
+ *
+ * @param initial Count before any operation, clamped into the bounds.
+ * @default initial 0
+ * @param options Inclusive bounds for every value the counter takes.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
+ * bound is `NaN` or `min` exceeds `max`.
+ * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
+ * initial value, operand, or arithmetic result is `NaN` (for example
+ * incrementing `-Infinity` by `Infinity`); the count is left unchanged.
+ * @returns Reactive count, bound flags, and mutation controls.
+ */
+declare function useCounter(initial?: number, options?: UseCounterOptions): CounterControls;
+//#endregion
+//#region src/use-debounced.d.ts
+/** Options for {@link useDebounced}. */
+interface UseDebouncedOptions {
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the debounced view
+   * mirrors the source synchronously instead of starting timers. Enable it
+   * for native, desktop, worker, and test runtimes whose scheduler is
+   * lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the single-shot timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive debounced view and controls returned by {@link useDebounced}. */
+interface DebouncedControls<Value> {
+  /** Readonly view of the source that settles `waitMs` after the last change. */
+  readonly debounced: Readonly<ShallowRef<Value>>;
+  /** Whether a trailing update is currently scheduled. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+  /**
+   * Discard the scheduled trailing update and keep the last settled value.
+   * Later source changes debounce again as usual.
+   *
+   * @returns Whether a scheduled update was discarded.
+   */
+  readonly cancel: () => boolean;
+  /**
+   * Apply the current source value immediately instead of waiting out the
+   * delay.
+   *
+   * @returns Whether a scheduled update was applied.
+   */
+  readonly flush: () => boolean;
+}
+/**
+ * Create a readonly debounced view of a reactive source.
+ *
+ * The view starts at the current source value. Each source change (observed
+ * with `flush: "sync"`, so every synchronous write counts) restarts a
+ * single-shot timer of `waitMs` milliseconds; when it fires, the view takes
+ * the source value current at that moment. `waitMs` is reactive and is read
+ * when a timer is scheduled; changing it does not restart an already-pending
+ * timer. A wait of `0` still defers to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
+ * the view mirrors the source synchronously, so server-rendered output shows
+ * current values and nothing leaks. `pending` stays `false` and the controls
+ * report `false` in that mode.
+ *
+ * Cleanup rule: the watcher and any pending timer are released when the
+ * owning reactive scope stops; call inside an active scope. Outside one, the
+ * watcher lives as long as the source and `cancel()` only clears the pending
+ * timer.
+ *
+ * @example
+ * ```ts
+ * const query = shallowRef("");
+ * const { debounced, flush } = useDebounced(query, 300);
+ * query.value = "vize"; // debounced.value still "" for 300ms
+ * flush(); // debounced.value === "vize" immediately
+ * ```
+ *
+ * @param source Reactive source to debounce.
+ * @param waitMs Reactive delay in milliseconds; must be finite and at least
+ * zero. Fractions are truncated.
+ * @param options Runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again for every scheduled delay.
+ * @returns Readonly debounced view, pending flag, and cancel/flush controls.
+ */
+declare function useDebounced<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseDebouncedOptions): DebouncedControls<Value>;
+//#endregion
+//#region src/use-history.d.ts
+/** Options for {@link useHistory}. */
+interface UseHistoryOptions<Value> {
+  /**
+   * Maximum number of undo entries retained; recording a change beyond it
+   * drops the oldest entry. The redo stack is bounded by construction, since
+   * redo entries only ever come from undone changes. Must be an integer
+   * greater than zero and is fixed at creation.
+   *
+   * @default 100
+   */
+  readonly capacity?: number;
+  /**
+   * Clone applied to every value captured into history and to every value
+   * restored out of it, isolating snapshots from later in-place mutation.
+   *
+   * @default identity — values are stored and restored by reference
+   */
+  readonly clone?: (value: Value) => Value;
+}
+/** Reactive undo/redo controls returned by {@link useHistory}. */
+interface HistoryControls {
+  /** Whether {@link HistoryControls.undo} currently has an entry to restore. */
+  readonly canUndo: ComputedRef<boolean>;
+  /** Whether {@link HistoryControls.redo} currently has an entry to restore. */
+  readonly canRedo: ComputedRef<boolean>;
+  /** Number of retained undo entries. */
+  readonly undoCount: ComputedRef<number>;
+  /** Number of retained redo entries. */
+  readonly redoCount: ComputedRef<number>;
+  /**
+   * Restore the newest undo entry and move the current value onto the redo
+   * stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly undo: () => boolean;
+  /**
+   * Restore the newest redo entry and move the current value back onto the
+   * undo stack. The restoring write is not recorded.
+   *
+   * @returns Whether an entry was restored.
+   */
+  readonly redo: () => boolean;
+  /**
+   * Group every source write inside `run` into at most one undo entry.
+   *
+   * The entry restores the value from just before the batch. It is committed
+   * only when the final value differs (`Object.is`) from the starting value,
+   * and it is committed even when `run` throws, so a partially applied batch
+   * stays undoable as one step. Nested calls collapse into the outermost
+   * batch. The callback's return value is passed through.
+   */
+  readonly batch: <Result>(run: () => Result) => Result;
+  /** Drop every undo and redo entry while keeping the current value. */
+  readonly clear: () => void;
+}
+/**
+ * Record bounded undo/redo history over the writes of a ref.
+ *
+ * Recording is shallow and identity-based, matching Vue's own change
+ * detection: assignments to `source.value` are recorded (observed with
+ * `flush: "sync"`, so every synchronous write counts), writes that are
+ * `Object.is`-equal to the current value are not changes, and in-place
+ * mutations of object values are invisible — pair mutable values with
+ * {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
+ * values through `clone` as well, so snapshots never share identity with the
+ * live value unless the default identity clone is kept. When a
+ * user-provided `clone` throws, the failed operation leaves history
+ * unchanged and the error propagates.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. Cleanup rule: when the owning reactive scope stops, recording stops
+ * and every retained snapshot is released, so `undo`/`redo` return `false`
+ * afterwards; call inside an active scope, or the watcher lives as long as
+ * the source.
+ *
+ * @example
+ * ```ts
+ * const text = shallowRef("");
+ * const { undo, redo, batch } = useHistory(text);
+ * text.value = "a";
+ * batch(() => {
+ *   text.value = "ab";
+ *   text.value = "abc";
+ * });
+ * undo(); // text.value === "a" (the batch is one step)
+ * redo(); // text.value === "abc"
+ * ```
+ *
+ * @param source Ref whose writes are recorded.
+ * @param options Retention bound and snapshot cloning.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
+ * the capacity is not an integer greater than zero.
+ * @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
+ * `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
+ * stack movement would corrupt the pending group.
+ * @returns Reactive undo/redo state and controls.
+ */
+declare function useHistory<Value>(source: Ref<Value>, options?: UseHistoryOptions<Value>): HistoryControls;
+//#endregion
+//#region src/use-previous.d.ts
+/**
+ * Track the value a reactive source held before its latest change.
+ *
+ * The semantics are precise and arity-based:
+ *
+ * - Without an `initial` argument the ref holds `undefined` until the source
+ *   changes for the first time.
+ * - With an `initial` argument (including an explicit `undefined` when
+ *   `Value` allows it) the ref holds that value until the first change, and
+ *   the return type never widens with `undefined`.
+ * - Every synchronous write is observed (`flush: "sync"`), so a sequence of
+ *   writes in one tick shifts the previous value step by step instead of
+ *   collapsing into one batch.
+ * - Writes whose value is `Object.is`-equal to the current value do not
+ *   count as changes, matching Vue's own change detection.
+ * - Tracking is shallow: reassignments are observed, in-place mutations of
+ *   object values are not.
+ *
+ * Safe during server rendering: no browser globals are read and no timers
+ * start. The underlying watcher is bound to the current reactive scope and
+ * stops with it; call inside an active scope, or the watcher lives as long
+ * as the source. A plain non-reactive source never changes, so the ref stays
+ * at its initial value.
+ *
+ * @example
+ * ```ts
+ * const route = shallowRef("/home");
+ * const previousRoute = usePrevious(route, "/");
+ * route.value = "/settings";
+ * previousRoute.value; // "/home"
+ * ```
+ *
+ * @param source Reactive source to observe.
+ * @param initial Value reported before the first change.
+ * @returns Readonly shallow ref holding the previous source value.
+ */
+declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>): Readonly<ShallowRef<Value | undefined>>;
+declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>, initial: Value): Readonly<ShallowRef<Value>>;
+//#endregion
+//#region src/use-throttled.d.ts
+/** Options for {@link useThrottled}. */
+interface UseThrottledOptions {
+  /**
+   * Apply the first change of a cooldown window immediately.
+   *
+   * @default true
+   */
+  readonly leading?: boolean;
+  /**
+   * Apply the newest change collected during a cooldown window when the
+   * window ends. When disabled, changes inside a window are dropped.
+   *
+   * @default true
+   */
+  readonly trailing?: boolean;
+  /**
+   * Applies the timing policy when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering, where the throttled view
+   * mirrors the source synchronously instead of starting timers. Enable it
+   * for native, desktop, worker, and test runtimes whose scheduler is
+   * lifecycle-bound.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the single-shot cooldown timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive throttled view and controls returned by {@link useThrottled}. */
+interface ThrottledControls<Value> {
+  /** Readonly view of the source updated at most once per cooldown window. */
+  readonly throttled: Readonly<ShallowRef<Value>>;
+  /** Whether a trailing update is waiting for the current window to end. */
+  readonly pending: Readonly<ShallowRef<boolean>>;
+  /**
+   * Discard the waiting trailing update and close the cooldown window, so
+   * the next change starts fresh on a leading edge.
+   *
+   * @returns Whether a waiting trailing update was discarded.
+   */
+  readonly cancel: () => boolean;
+  /**
+   * Apply the waiting trailing update immediately and close the cooldown
+   * window. Without a waiting update the window is left untouched.
+   *
+   * @returns Whether a waiting trailing update was applied.
+   */
+  readonly flush: () => boolean;
+}
+/**
+ * Create a readonly throttled view of a reactive source.
+ *
+ * Changes are observed with `flush: "sync"`, so every synchronous write
+ * counts. Outside a cooldown window, a change applies immediately when
+ * {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
+ * trailing update) and opens a window of `waitMs` milliseconds. Changes
+ * inside a window are collected as the trailing candidate; when the window
+ * ends with a candidate waiting, the source value current at that moment is
+ * applied and the next window opens back to back, keeping applications
+ * spaced by `waitMs`. A window that ends without a candidate closes silently.
+ * `waitMs` is reactive and is read each time a window opens; changing it
+ * never disturbs an already-open window. A wait of `0` still defers trailing
+ * updates to the next scheduler tick.
+ *
+ * Server rendering is explicit: without a browser `window` (and with
+ * {@link UseThrottledOptions.runOnServer} disabled) no timer ever starts and
+ * the view mirrors the source synchronously, so server-rendered output shows
+ * current values and nothing leaks. `pending` stays `false` and the controls
+ * report `false` in that mode.
+ *
+ * Cleanup rule: the watcher and any open window timer are released when the
+ * owning reactive scope stops; call inside an active scope. Outside one, the
+ * watcher lives as long as the source and `cancel()` only clears the window.
+ *
+ * @example
+ * ```ts
+ * const scrollY = shallowRef(0);
+ * const { throttled } = useThrottled(scrollY, 100);
+ * scrollY.value = 40; // applied immediately (leading edge)
+ * scrollY.value = 80; // applied when the 100ms window ends
+ * ```
+ *
+ * @param source Reactive source to throttle.
+ * @param waitMs Reactive cooldown in milliseconds; must be finite and at
+ * least zero. Fractions are truncated.
+ * @param options Edge policy and runtime scheduling overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
+ * resolved wait is not finite or is negative, both synchronously at creation
+ * (even in mirror mode) and again each time a window opens.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
+ * `leading` and `trailing` are disabled, because updates could then never
+ * propagate.
+ * @returns Readonly throttled view, pending flag, and cancel/flush controls.
+ */
+declare function useThrottled<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseThrottledOptions): ThrottledControls<Value>;
+//#endregion
+//#region src/use-toggle.d.ts
+/** Reactive controls returned by {@link useToggle}. */
+interface ToggleControls {
+  /**
+   * Owned boolean state.
+   *
+   * Deliberately writable: unlike the derived views elsewhere in this
+   * package, the toggle owns its state, so assigning the ref directly (for
+   * example through `v-model`) is equivalent to calling
+   * {@link ToggleControls.toggle} with a forced value.
+   */
+  readonly state: Ref<boolean>;
+  /**
+   * Invert the state, or force it to `force` when the argument is given.
+   * Passing an explicit `undefined` behaves like passing no argument.
+   *
+   * @param force Value assigned instead of inverting.
+   * @returns The state after the change.
+   */
+  readonly toggle: (force?: boolean) => boolean;
+}
+/**
+ * Create owned boolean state with an inverting control.
+ *
+ * Purely synchronous state: safe during server rendering (no browser
+ * globals, no timers) and nothing to dispose, so it works inside and
+ * outside reactive scopes alike.
+ *
+ * @example
+ * ```ts
+ * const { state: open, toggle } = useToggle();
+ * toggle(); // true
+ * toggle(false); // false
+ * open.value; // false
+ * ```
+ *
+ * @param initial State before the first toggle.
+ * @default initial false
+ * @returns The writable state and its toggle control.
+ */
+declare function useToggle(initial?: boolean): ToggleControls;
+//#endregion
+export { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, CounterControls, DebouncedControls, EventListenerControls, HistoryControls, LocaleControls, MediaQueryHost, MotionPreference, TextDirection, ThrottledControls, TimeoutScheduler, ToggleControls, UseAsyncResourceOptions, UseCounterOptions, UseDebouncedOptions, UseEventListenerOptions, UseHistoryOptions, UseLocaleOptions, UseMediaQueryOptions, UseThrottledOptions, tryOnScopeDispose, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };

package/dist/index.mjs

@@ -3,6 +3,14 @@ import { computed, getCurrentScope, onScopeDispose, readonly, ref, shallowRef, t
 /**
 * 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.
 */
@@ -17,6 +25,18 @@ function tryOnScopeDispose(cleanup) {
 * Create a scoped, abortable asynchronous resource with latest-result-wins
 * state. Every execution returns a discriminated result, so cancellation,
 * supersession, loader failure, and successful `undefined` data stay distinct.
+*
+* When created inside an active reactive scope (and `scope` is enabled), the
+* active execution is aborted when that scope stops; outside a scope,
+* cancellation ownership stays with the caller. The execute promise never
+* rejects — synchronous and asynchronous loader failures both settle into
+* the `"error"` result. Safe during server rendering: no browser globals are
+* read and abort reasons use the runtime-native `DOMException`.
+*
+* @param loader Asynchronous loader receiving the abort context first.
+* @param options Data retention, supersession, and scope behavior.
+* @default options {}
+* @returns Reactive state and controls for the loader.
 */
 function useAsyncResource(loader, options = {}) {
 	const data = shallowRef(options.initialData);
@@ -152,6 +172,19 @@ const FORMATTER_CACHE_LIMIT = 32;
 * 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(() => {
@@ -205,9 +238,18 @@ function serializeOptions(options) {
 /**
 * 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);
@@ -230,8 +272,13 @@ function useMediaQuery(query, options = {}) {
 /**
 * 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);
@@ -241,4 +288,460 @@ function browserMediaQueryHost() {
 	return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window : void 0;
 }
 //#endregion
-export { tryOnScopeDispose, useAsyncResource, useEventListener, useLocale, useMediaQuery, useReducedMotion };
+//#region src/use-counter.ts
+/**
+* Create a clamped counter whose every transition stays inside `[min, max]`.
+*
+* All operations clamp instead of failing, including the initial value, so
+* the count is inside the bounds at every observable moment. Only `NaN` is
+* rejected — silently corrupting the count is never an option. Purely
+* synchronous state: safe during server rendering (no browser globals, no
+* timers) and nothing to dispose, so it works inside and outside reactive
+* scopes alike. Bounds are fixed at creation and not reactive.
+*
+* @example
+* ```ts
+* const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
+* increment(); // 10
+* increment(); // 10 (clamped)
+* atMax.value; // true
+* ```
+*
+* @param initial Count before any operation, clamped into the bounds.
+* @default initial 0
+* @param options Inclusive bounds for every value the counter takes.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
+* bound is `NaN` or `min` exceeds `max`.
+* @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
+* initial value, operand, or arithmetic result is `NaN` (for example
+* incrementing `-Infinity` by `Infinity`); the count is left unchanged.
+* @returns Reactive count, bound flags, and mutation controls.
+*/
+function useCounter(initial = 0, options = {}) {
+	const min = requireBound(options.min ?? Number.NEGATIVE_INFINITY, "min");
+	const max = requireBound(options.max ?? Number.POSITIVE_INFINITY, "max");
+	if (min > max) throw new RangeError(`[VIZE_COMPOSE_COUNTER_INVALID_RANGE] min must not exceed max; received min ${String(min)} and max ${String(max)}`);
+	const clamp = (value) => Math.min(max, Math.max(min, value));
+	const count = shallowRef(clamp(requireValue(initial)));
+	let baseline = count.value;
+	const setClamped = (next) => {
+		count.value = clamp(requireValue(next));
+		return count.value;
+	};
+	const reset = (value) => {
+		const applied = setClamped(value ?? baseline);
+		if (value !== void 0) baseline = applied;
+		return applied;
+	};
+	return {
+		count,
+		atMin: computed(() => count.value === min),
+		atMax: computed(() => count.value === max),
+		increment: (delta = 1) => setClamped(count.value + requireValue(delta)),
+		decrement: (delta = 1) => setClamped(count.value - requireValue(delta)),
+		set: setClamped,
+		reset
+	};
+}
+function requireBound(value, label) {
+	if (Number.isNaN(value)) throw new RangeError(`[VIZE_COMPOSE_COUNTER_INVALID_RANGE] ${label} must not be NaN`);
+	return value;
+}
+function requireValue(value) {
+	if (Number.isNaN(value)) throw new RangeError("[VIZE_COMPOSE_COUNTER_INVALID_VALUE] the value is NaN; counter state was left unchanged");
+	return value;
+}
+//#endregion
+//#region src/use-debounced.ts
+const defaultScheduler$1 = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Create a readonly debounced view of a reactive source.
+*
+* The view starts at the current source value. Each source change (observed
+* with `flush: "sync"`, so every synchronous write counts) restarts a
+* single-shot timer of `waitMs` milliseconds; when it fires, the view takes
+* the source value current at that moment. `waitMs` is reactive and is read
+* when a timer is scheduled; changing it does not restart an already-pending
+* timer. A wait of `0` still defers to the next scheduler tick.
+*
+* Server rendering is explicit: without a browser `window` (and with
+* {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
+* the view mirrors the source synchronously, so server-rendered output shows
+* current values and nothing leaks. `pending` stays `false` and the controls
+* report `false` in that mode.
+*
+* Cleanup rule: the watcher and any pending timer are released when the
+* owning reactive scope stops; call inside an active scope. Outside one, the
+* watcher lives as long as the source and `cancel()` only clears the pending
+* timer.
+*
+* @example
+* ```ts
+* const query = shallowRef("");
+* const { debounced, flush } = useDebounced(query, 300);
+* query.value = "vize"; // debounced.value still "" for 300ms
+* flush(); // debounced.value === "vize" immediately
+* ```
+*
+* @param source Reactive source to debounce.
+* @param waitMs Reactive delay in milliseconds; must be finite and at least
+* zero. Fractions are truncated.
+* @param options Runtime scheduling overrides.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
+* resolved wait is not finite or is negative, both synchronously at creation
+* (even in mirror mode) and again for every scheduled delay.
+* @returns Readonly debounced view, pending flag, and cancel/flush controls.
+*/
+function useDebounced(source, waitMs, options = {}) {
+	const scheduler = options.scheduler ?? defaultScheduler$1;
+	const debounced = shallowRef(toValue(source));
+	const pending = shallowRef(false);
+	let handle;
+	resolveWaitMs$1(toValue(waitMs));
+	const apply = () => {
+		handle = void 0;
+		pending.value = false;
+		debounced.value = toValue(source);
+	};
+	const cancel = () => {
+		if (!pending.value) return false;
+		scheduler.clearTimeout(handle);
+		handle = void 0;
+		pending.value = false;
+		return true;
+	};
+	const flush = () => {
+		if (!pending.value) return false;
+		scheduler.clearTimeout(handle);
+		apply();
+		return true;
+	};
+	watch(() => toValue(source), (next) => {
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+			debounced.value = next;
+			return;
+		}
+		const delayMs = resolveWaitMs$1(toValue(waitMs));
+		if (pending.value) scheduler.clearTimeout(handle);
+		pending.value = true;
+		handle = scheduler.setTimeout(apply, delayMs);
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		cancel();
+	});
+	return {
+		debounced,
+		pending,
+		cancel,
+		flush
+	};
+}
+function resolveWaitMs$1(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+//#endregion
+//#region src/use-history.ts
+/**
+* Record bounded undo/redo history over the writes of a ref.
+*
+* Recording is shallow and identity-based, matching Vue's own change
+* detection: assignments to `source.value` are recorded (observed with
+* `flush: "sync"`, so every synchronous write counts), writes that are
+* `Object.is`-equal to the current value are not changes, and in-place
+* mutations of object values are invisible — pair mutable values with
+* {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
+* values through `clone` as well, so snapshots never share identity with the
+* live value unless the default identity clone is kept. When a
+* user-provided `clone` throws, the failed operation leaves history
+* unchanged and the error propagates.
+*
+* Safe during server rendering: no browser globals are read and no timers
+* start. Cleanup rule: when the owning reactive scope stops, recording stops
+* and every retained snapshot is released, so `undo`/`redo` return `false`
+* afterwards; call inside an active scope, or the watcher lives as long as
+* the source.
+*
+* @example
+* ```ts
+* const text = shallowRef("");
+* const { undo, redo, batch } = useHistory(text);
+* text.value = "a";
+* batch(() => {
+*   text.value = "ab";
+*   text.value = "abc";
+* });
+* undo(); // text.value === "a" (the batch is one step)
+* redo(); // text.value === "abc"
+* ```
+*
+* @param source Ref whose writes are recorded.
+* @param options Retention bound and snapshot cloning.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
+* the capacity is not an integer greater than zero.
+* @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
+* `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
+* stack movement would corrupt the pending group.
+* @returns Reactive undo/redo state and controls.
+*/
+function useHistory(source, options = {}) {
+	const capacity = options.capacity ?? 100;
+	if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError(`[VIZE_COMPOSE_HISTORY_INVALID_CAPACITY] capacity must be an integer greater than zero; received ${String(capacity)}`);
+	const clone = options.clone ?? ((value) => value);
+	const undoStack = shallowRef([]);
+	const redoStack = shallowRef([]);
+	let restoring = false;
+	let batchDepth = 0;
+	let activeBatch;
+	const pushUndo = (entry) => {
+		const next = [...undoStack.value, entry];
+		undoStack.value = next.length > capacity ? next.slice(next.length - capacity) : next;
+		redoStack.value = [];
+	};
+	const writeSilently = (value) => {
+		restoring = true;
+		try {
+			source.value = value;
+		} finally {
+			restoring = false;
+		}
+	};
+	const requireOutsideBatch = (operation) => {
+		if (batchDepth > 0) throw new Error(`[VIZE_COMPOSE_HISTORY_IN_BATCH] ${operation}() is not available inside batch()`);
+	};
+	const undo = () => {
+		requireOutsideBatch("undo");
+		const entry = undoStack.value.at(-1);
+		if (entry === void 0) return false;
+		const restored = clone(entry.value);
+		const recorded = { value: clone(source.value) };
+		undoStack.value = undoStack.value.slice(0, -1);
+		redoStack.value = [...redoStack.value, recorded];
+		writeSilently(restored);
+		return true;
+	};
+	const redo = () => {
+		requireOutsideBatch("redo");
+		const entry = redoStack.value.at(-1);
+		if (entry === void 0) return false;
+		const restored = clone(entry.value);
+		const recorded = { value: clone(source.value) };
+		redoStack.value = redoStack.value.slice(0, -1);
+		undoStack.value = [...undoStack.value, recorded];
+		writeSilently(restored);
+		return true;
+	};
+	const batch = (run) => {
+		if (batchDepth === 0) activeBatch = {
+			raw: source.value,
+			entry: { value: clone(source.value) }
+		};
+		batchDepth += 1;
+		try {
+			return run();
+		} finally {
+			batchDepth -= 1;
+			if (batchDepth === 0 && activeBatch !== void 0) {
+				const finished = activeBatch;
+				activeBatch = void 0;
+				if (!Object.is(finished.raw, source.value)) pushUndo(finished.entry);
+			}
+		}
+	};
+	const clear = () => {
+		requireOutsideBatch("clear");
+		undoStack.value = [];
+		redoStack.value = [];
+	};
+	const handle = watch(source, (_next, replaced) => {
+		if (restoring || batchDepth > 0) return;
+		pushUndo({ value: clone(replaced) });
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		handle.stop();
+		undoStack.value = [];
+		redoStack.value = [];
+	});
+	return {
+		canUndo: computed(() => undoStack.value.length > 0),
+		canRedo: computed(() => redoStack.value.length > 0),
+		undoCount: computed(() => undoStack.value.length),
+		redoCount: computed(() => redoStack.value.length),
+		undo,
+		redo,
+		batch,
+		clear
+	};
+}
+//#endregion
+//#region src/use-previous.ts
+function usePrevious(source, ...initial) {
+	const previous = shallowRef(initial.length === 1 ? initial[0] : void 0);
+	watch(() => toValue(source), (_next, replaced) => {
+		previous.value = replaced;
+	}, { flush: "sync" });
+	return previous;
+}
+//#endregion
+//#region src/use-throttled.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Create a readonly throttled view of a reactive source.
+*
+* Changes are observed with `flush: "sync"`, so every synchronous write
+* counts. Outside a cooldown window, a change applies immediately when
+* {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
+* trailing update) and opens a window of `waitMs` milliseconds. Changes
+* inside a window are collected as the trailing candidate; when the window
+* ends with a candidate waiting, the source value current at that moment is
+* applied and the next window opens back to back, keeping applications
+* spaced by `waitMs`. A window that ends without a candidate closes silently.
+* `waitMs` is reactive and is read each time a window opens; changing it
+* never disturbs an already-open window. A wait of `0` still defers trailing
+* updates to the next scheduler tick.
+*
+* Server rendering is explicit: without a browser `window` (and with
+* {@link UseThrottledOptions.runOnServer} disabled) no timer ever starts and
+* the view mirrors the source synchronously, so server-rendered output shows
+* current values and nothing leaks. `pending` stays `false` and the controls
+* report `false` in that mode.
+*
+* Cleanup rule: the watcher and any open window timer are released when the
+* owning reactive scope stops; call inside an active scope. Outside one, the
+* watcher lives as long as the source and `cancel()` only clears the window.
+*
+* @example
+* ```ts
+* const scrollY = shallowRef(0);
+* const { throttled } = useThrottled(scrollY, 100);
+* scrollY.value = 40; // applied immediately (leading edge)
+* scrollY.value = 80; // applied when the 100ms window ends
+* ```
+*
+* @param source Reactive source to throttle.
+* @param waitMs Reactive cooldown in milliseconds; must be finite and at
+* least zero. Fractions are truncated.
+* @param options Edge policy and runtime scheduling overrides.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
+* resolved wait is not finite or is negative, both synchronously at creation
+* (even in mirror mode) and again each time a window opens.
+* @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
+* `leading` and `trailing` are disabled, because updates could then never
+* propagate.
+* @returns Readonly throttled view, pending flag, and cancel/flush controls.
+*/
+function useThrottled(source, waitMs, options = {}) {
+	const leading = options.leading ?? true;
+	const trailing = options.trailing ?? true;
+	if (!leading && !trailing) throw new TypeError("[VIZE_COMPOSE_THROTTLE_INVALID_EDGES] at least one of leading or trailing must be enabled");
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const throttled = shallowRef(toValue(source));
+	const pending = shallowRef(false);
+	let windowHandle;
+	let windowOpen = false;
+	resolveWaitMs(toValue(waitMs));
+	const openWindow = () => {
+		windowOpen = true;
+		windowHandle = scheduler.setTimeout(() => {
+			windowHandle = void 0;
+			if (!pending.value) {
+				windowOpen = false;
+				return;
+			}
+			pending.value = false;
+			throttled.value = toValue(source);
+			openWindow();
+		}, resolveWaitMs(toValue(waitMs)));
+	};
+	const closeWindow = () => {
+		if (windowOpen) scheduler.clearTimeout(windowHandle);
+		windowHandle = void 0;
+		windowOpen = false;
+		pending.value = false;
+	};
+	const cancel = () => {
+		const hadTrailing = pending.value;
+		closeWindow();
+		return hadTrailing;
+	};
+	const flush = () => {
+		if (!pending.value) return false;
+		closeWindow();
+		throttled.value = toValue(source);
+		return true;
+	};
+	watch(() => toValue(source), (next) => {
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) {
+			throttled.value = next;
+			return;
+		}
+		if (windowOpen) {
+			if (trailing) pending.value = true;
+			return;
+		}
+		if (leading) throttled.value = next;
+		else pending.value = true;
+		openWindow();
+	}, { flush: "sync" });
+	tryOnScopeDispose(() => {
+		cancel();
+	});
+	return {
+		throttled,
+		pending,
+		cancel,
+		flush
+	};
+}
+function resolveWaitMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_THROTTLE_INVALID_WAIT] waitMs must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+//#endregion
+//#region src/use-toggle.ts
+/**
+* Create owned boolean state with an inverting control.
+*
+* Purely synchronous state: safe during server rendering (no browser
+* globals, no timers) and nothing to dispose, so it works inside and
+* outside reactive scopes alike.
+*
+* @example
+* ```ts
+* const { state: open, toggle } = useToggle();
+* toggle(); // true
+* toggle(false); // false
+* open.value; // false
+* ```
+*
+* @param initial State before the first toggle.
+* @default initial false
+* @returns The writable state and its toggle control.
+*/
+function useToggle(initial = false) {
+	const state = shallowRef(initial);
+	const toggle = (force) => {
+		state.value = force ?? !state.value;
+		return state.value;
+	};
+	return {
+		state,
+		toggle
+	};
+}
+//#endregion
+export { tryOnScopeDispose, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };

package/dist/temporal.d.mts

@@ -75,15 +75,31 @@ interface UseTemporalZonedDateTimeOptions extends UseTemporalNowOptions {
  * effect scope.
  *
  * The timer is replaced when reactive options change and is always cancelled
- * when the owning scope stops. During server rendering, no timer starts unless
+ * when the owning scope stops. Call inside an active effect scope; without
+ * one, there is no automatic timer cleanup. During
+ * server rendering, no timer starts unless
  * {@link UseTemporalNowOptions.runOnServer} is explicitly enabled.
+ *
+ * @param options Clock scheduling, pause, and runtime overrides.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TEMPORAL_INVALID_INTERVAL` when
+ * the resolved interval is not finite or not greater than zero, both
+ * synchronously at creation and on invalid reactive updates.
+ * @returns Reactive clock controls.
  */
 declare function useTemporalNow(options?: UseTemporalNowOptions): TemporalClock;
 /**
  * Creates a reactive zoned date-time derived from a scoped Temporal clock.
  *
  * Changes to {@link UseTemporalZonedDateTimeOptions.timeZone} are reflected
- * without replacing the underlying timer.
+ * without replacing the underlying timer. Scheduling, server rendering, and
+ * scope-cleanup rules are shared with {@link useTemporalNow}.
+ *
+ * @param options Clock scheduling plus the reactive time zone.
+ * @default options {}
+ * @throws `RangeError` for invalid intervals (see {@link useTemporalNow}),
+ * and on read when the reactive time zone cannot be resolved by Temporal.
+ * @returns Computed zoned date-time in the reactive time zone.
  */
 declare function useTemporalZonedDateTime(options?: UseTemporalZonedDateTimeOptions): ComputedRef<Temporal.ZonedDateTime>;
 //#endregion

package/dist/temporal.mjs

@@ -20,8 +20,17 @@ function shouldSchedule(options) {
 * effect scope.
 *
 * The timer is replaced when reactive options change and is always cancelled
-* when the owning scope stops. During server rendering, no timer starts unless
+* when the owning scope stops. Call inside an active effect scope; without
+* one, there is no automatic timer cleanup. During
+* server rendering, no timer starts unless
 * {@link UseTemporalNowOptions.runOnServer} is explicitly enabled.
+*
+* @param options Clock scheduling, pause, and runtime overrides.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_TEMPORAL_INVALID_INTERVAL` when
+* the resolved interval is not finite or not greater than zero, both
+* synchronously at creation and on invalid reactive updates.
+* @returns Reactive clock controls.
 */
 function useTemporalNow(options = {}) {
 	const readNow = options.now ?? Temporal.Now.instant;
@@ -48,7 +57,14 @@ function useTemporalNow(options = {}) {
 * Creates a reactive zoned date-time derived from a scoped Temporal clock.
 *
 * Changes to {@link UseTemporalZonedDateTimeOptions.timeZone} are reflected
-* without replacing the underlying timer.
+* without replacing the underlying timer. Scheduling, server rendering, and
+* scope-cleanup rules are shared with {@link useTemporalNow}.
+*
+* @param options Clock scheduling plus the reactive time zone.
+* @default options {}
+* @throws `RangeError` for invalid intervals (see {@link useTemporalNow}),
+* and on read when the reactive time zone cannot be resolved by Temporal.
+* @returns Computed zoned date-time in the reactive time zone.
 */
 function useTemporalZonedDateTime(options = {}) {
 	const clock = useTemporalNow(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizejs/composable",
-  "version": "0.302.0",
+  "version": "0.303.0",
   "description": "Lifecycle-safe composable foundations for Vize applications",
   "keywords": [
     "composables",
@@ -41,29 +41,29 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vp pack",
-    "dev": "vp pack --watch",
-    "pretest": "vp pack && pnpm check:size",
-    "test": "vp exec node --test 'src/**/*.test.ts'",
-    "check": "vp check src scripts vite.config.ts",
-    "check:fix": "vp check --fix src scripts vite.config.ts",
-    "check:size": "node scripts/check-size.mjs",
-    "fmt": "vp fmt --write src scripts vite.config.ts"
-  },
   "dependencies": {
     "temporal-polyfill-lite": "0.4.2"
   },
   "devDependencies": {
-    "@types/node": "catalog:typescript",
-    "typescript": "catalog:typescript",
-    "vite-plus": "catalog:vite-stack",
-    "vue": "catalog:vue-stable"
+    "@types/node": "25.9.2",
+    "typescript": "6.0.3",
+    "vite-plus": "0.1.21",
+    "vue": "3.5.35"
   },
   "peerDependencies": {
     "vue": "^3.5.0"
   },
   "engines": {
     "node": ">=24"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "pretest": "vp pack && pnpm check:size",
+    "test": "vp exec node --test 'src/**/*.test.ts'",
+    "check": "vp check src scripts vite.config.ts",
+    "check:fix": "vp check --fix src scripts vite.config.ts",
+    "check:size": "node scripts/check-size.mjs",
+    "fmt": "vp fmt --write src scripts vite.config.ts"
   }
-}
+}