@aihu/use

function toValue<T>(v: MaybeGetter<T>): T

function tryOnMounted(fn: () => void): void

Run `fn` on the client; no-op under SSR.

function tryOnScopeDispose(fn: () => void): boolean

Register `fn` to run when the current effect scope stops — IF one is active.

function unrefElement(target: MaybeElementGetter): Element | null | undefined

function useActiveElement(): UseActiveElementReturn

Track the truly-focused element across shadow boundaries, updating on `focusin`/`focusout` (both bubble to `document`, so a single pair of document-level listeners covers every focus change anywhere in the page).

function useAsync<T, Args extends unknown[] = []>( fn: (...args: Args) => Promise<T>, options: UseAsyncOptions<T> = {}, ): UseAsyncReturn<T, Args>

Wrap `fn` in reactive `data`/`error`/`isLoading`/`isFinished` getters plus a manual `execute()`.

function useAsyncAbortable<T, Args extends unknown[] = []>( fn: (signal: AbortSignal, ...args: Args) => Promise<T>, options: UseAsyncAbortableOptions<T> = {}, ): UseAsyncAbortableReturn<T, Args>

`useAsync`, but `fn` receives an `AbortSignal` it should pass to `fetch`/etc.

function useBreakpoints<K extends string = keyof typeof breakpointsDefault>( breakpoints: Breakpoints<K> = breakpointsDefault as unknown as Breakpoints<K>, ): UseBreakpointsReturn<K>

function useBrowserLanguage( _options: UseBrowserLanguageOptions = {}, ): UseBrowserLanguageReturn

Track `navigator.language` (e.g.

function useCanvasSurface( host: MaybeElementGetter, options: UseCanvasSurfaceOptions = {}, ): UseCanvasSurfaceReturn

Manage a decorative canvas filling `host`.

function useCharacterField( host: MaybeElementGetter, options: UseCharacterFieldOptions = {}, ): UseCharacterFieldReturn

Animate a grid of glyphs across a canvas filling `host`.

function useClamp( value: MaybeGetter<number>, min: MaybeGetter<number>, max: MaybeGetter<number>, ): UseClampReturn

function useClickOutside( target: MaybeElementGetter, handler: (event: PointerEvent) => void, options: UseClickOutsideOptions = {}, ): () => void

Call `handler` when a pointer gesture (`pointerdown` + matching `pointerup`) both land outside `target` and outside every `ignore` entry.

function useClipboard(options: UseClipboardOptions = {}): UseClipboardReturn

Copy text to the clipboard, with a `copied()` flag for feedback UI.

function useColorScheme(options: UseColorSchemeOptions = {}): UseColorSchemeReturn

Track a `'light' | 'dark' | 'auto'` color-scheme choice and its resolved `'light' | 'dark'` value.

function useCountdown( duration: number, options: UseCountdownOptions = {}, ): UseCountdownReturn

Count down from `duration` ms, with `pause()`/`resume()` support and an optional `onComplete` fired once `remaining` reaches `0`.

function useCounter(options: UseCounterOptions = {}): UseCounterReturn

A numeric counter with increment/decrement/set/reset, clamped to an optional `[min, max]` range.

function useCountTo(options: UseCountToOptions = {}): UseCountToReturn

Tween a number toward `to` on every `start()` call.

function useDateFormat( date: MaybeGetter<UseDateFormatSource>, options: UseDateFormatOptions = {}, ): UseDateFormatReturn

Format `date` (a `Date`/epoch-`number`/date-`string`, or a getter for one) with `Intl.DateTimeFormat`.

function useDebounced<T>(source: () => T, delay: number = 200): UseDebouncedReturn<T>

Track `source()`, but only propagate a new value after it has been stable for `delay` ms (trailing edge).

function useDeviceMotion(): UseDeviceMotionReturn

Track `devicemotion` events.

function useDeviceOrientation(): UseDeviceOrientationReturn

Track `deviceorientation` events.

function useDevicePixelRatio(): UseDevicePixelRatioReturn

Track `window.devicePixelRatio`, re-arming a `matchMedia` resolution query on every change (see module doc).

function useDocumentVisibility(): UseDocumentVisibilityReturn

Track `document.visibilityState` (`'visible' | 'hidden'`), updating on the `visibilitychange` event.

function useElementSize(options: UseElementSizeOptions = {}): UseElementSizeReturn

Track an element's content (or border) box size.

function useElementVisibility( options: UseElementVisibilityOptions = {}, ): UseElementVisibilityReturn

Track whether an element currently intersects its root (the viewport by default).

function useEventListener( target: MaybeElementGetter | Window | Document, event: string, handler: (event: Event) => void, options?: boolean | AddEventListenerOptions, ): () => void

function useEventListenerMap( target: MaybeElementGetter | Window | Document, map: Record<string, ((event: Event) => void) | undefined>, options?: boolean | AddEventListenerOptions, ): () => void

function useFocusWithin(options: UseFocusWithinOptions = {}): UseFocusWithinReturn

Track whether focus is currently inside `target` (itself or a descendant).

function useHover(options: UseHoverOptions = {}): UseHoverReturn

Track whether the pointer is currently over `target` (itself or any composed descendant, across shadow boundaries).

function useIdle(options: UseIdleOptions = {}): UseIdleReturn

Track whether the user has gone `timeout` ms without an activity event.

function useIntersectionObserver( target: MaybeElementGetter, callback: (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void, options: UseIntersectionObserverOptions = {}, ): UseIntersectionObserverReturn

Observe `target`'s intersection with its root (the viewport by default) via `IntersectionObserver`, calling `callback` with every batch of entries (mirrors the native `IntersectionObserverCallback` signature, plus the observer instance).

function useInterval( interval: number = 1000, options: UseIntervalOptions = {}, ): UseIntervalReturn

A counter that increments by `1` every `interval` ms (default `1000`).

function useIntervalFn( callback: () => void, interval: number = 1000, options: UseIntervalFnOptions = {}, ): UseIntervalFnReturn

Repeatedly call `callback` every `interval` ms.

function useJwt<T = Record<string, unknown>>(token: string): UseJwtReturn<T>

Decode `token`'s payload.

function useKeyedAsync<T, K>( key: () => K | null | undefined, fn: (key: K, signal: AbortSignal) => Promise<T>, options: UseKeyedAsyncOptions<T> = {}, ): UseKeyedAsyncReturn<T>

Fetch `fn(key, signal)` whenever the reactive `key()` getter's value changes (`useWatch`'s `Object.is` value-change gate — shallow, by reference; a key that mutates in place is not detected as a change).

function useLocalStorage<T>( key: string, defaultValue: T, options: UseLocalStorageOptions<T> = {}, ): UseLocalStorageReturn<T>

A reactive value stored under `key` in `localStorage`, JSON serialized/deserialized by default (override via `serializer`/ `deserializer` for a different format).

function useMap<K, V>(seed?: Iterable<readonly [K, V]>): UseMapReturn<K, V>

A reactive `Map<K, V>`, optionally seeded from `seed` (anything `new Map()` itself accepts).

function useMeasure(options: UseMeasureOptions = {}): UseMeasureReturn

Track an element's full bounding rect.

function useMediaQuery( query: string, options: UseMediaQueryOptions = {}, ): UseMediaQueryReturn

Track whether `query` (a CSS media-query string, e.g.

function useMouse(options: UseMouseOptions = {}): UseMouseReturn

Track the mouse position.

function useMouseInElement(options: UseMouseInElementOptions = {}): UseMouseInElementReturn

Track the mouse position relative to `target`.

function useMutationObserver( target: MaybeElementGetter, callback: (records: MutationRecord[], observer: MutationObserver) => void, options: MutationObserverInit, ): UseMutationObserverReturn

Observe `target` for mutations matching `options` (the native `MutationObserverInit` — the caller MUST set at least one of `childList`, `attributes`, or `characterData` to `true`, same requirement as the native `observe()` call), calling `callback` with every batch of records (mirrors the native `MutationCallback` signature, plus the observer instance).

function useNetworkState(options: UseNetworkStateOptions = {}): UseNetworkStateReturn

Track online/offline status and (where supported) connection-quality hints.

function useNow(options: UseNowOptions = {}): UseNowReturn

Track the current time as a reactive `Date`.

function useOperatingSystem( _options: UseOperatingSystemOptions = {}, ): UseOperatingSystemReturn

Best-effort detection of the OS the page is running on.

function useOrientation(): UseOrientationReturn

Track the screen's rotation angle and orientation type.

function usePageLeave(): UsePageLeaveReturn

Track whether the pointer has left the document (`mouseleave`) versus re-entered it (`mouseenter`).

function useParticleField( host: MaybeElementGetter, options: UseParticleFieldOptions = {}, ): UseParticleFieldReturn

Drift `count` particles across a canvas filling `host`.

function usePerformanceObserver( callback: PerformanceObserverCallback, options: PerformanceObserverInit, ): UsePerformanceObserverReturn

Observe performance entries matching `options` (the native `PerformanceObserverInit` — set `entryTypes` or `type`), calling `callback` with every batch (mirrors the native `PerformanceObserverCallback` signature).

function usePreferredContrast( _options: UsePreferredContrastOptions = {}, ): UsePreferredContrastReturn

Track the `prefers-contrast` media feature (`'more' | 'less' | 'custom' | 'no-preference'`).

function usePreferredDark(): UsePreferredDarkReturn

Track the user's OS/browser dark-mode preference (`prefers-color-scheme: dark`).

function usePreferredLanguages( _options: UsePreferredLanguagesOptions = {}, ): UsePreferredLanguagesReturn

Track `navigator.languages` (the user's ordered language preferences), updating on the `languagechange` event.

function usePreferredReducedMotion( _options: UsePreferredReducedMotionOptions = {}, ): UsePreferredReducedMotionReturn

Track the `(prefers-reduced-motion: reduce)` media query.

function usePreferredReducedTransparency( _options: UsePreferredReducedTransparencyOptions = {}, ): UsePreferredReducedTransparencyReturn

Track the `(prefers-reduced-transparency: reduce)` media query.

function usePrevious<T>(source: () => T): UsePreviousReturn<T>

Track the value `source` held BEFORE its most recent change.

function useRafFn( callback: (args: UseRafFnCallbackArgs) => void, options: UseRafFnOptions = {}, ): UseRafFnReturn

Run `callback` on every animation frame until paused.

function useReducedMotion(): UseReducedMotionReturn

Track the `(prefers-reduced-motion: reduce)` media query as a boolean.

function useResizeObserver( target: MaybeElementGetter, callback: (entries: ResizeObserverEntry[], observer: ResizeObserver) => void, options: UseResizeObserverOptions = {}, ): UseResizeObserverReturn

Observe `target`'s box size via `ResizeObserver`, calling `callback` with every batch of entries (mirrors the native `ResizeObserverCallback` signature, plus the observer instance for advanced use — e.g.

function useRouteParams(): UseRouteParamsReturn

Read the current route's matched params (e.g.

function useScroll(options: UseScrollOptions = {}): UseScrollReturn

Track the scroll position of `window` or an element.

function useSequence<T>( items: readonly T[], options: UseSequenceOptions = {}, ): UseSequenceReturn<T>

Cycle through `items`, holding on each for `interval` ms.

function useSet<T>(seed?: Iterable<T>): UseSetReturn<T>

A reactive `Set<T>`, optionally seeded from `seed` (anything `new Set()` itself accepts).

function useStopwatch(options: UseStopwatchOptions = {}): UseStopwatchReturn

Track elapsed wall-clock time from `start()`, with `pause()`/`resume()` and lap recording.

function useSupported(predicate: () => boolean): UseSupportedReturn

Feature-detect once on the client via `predicate` (e.g.

function useSwarm(options: UseSwarmOptions = {}): UseSwarmReturn

Open a live connection to the swarm command-center bus's `/stream` endpoint and expose its state reactively.

function useTextDirection(options: UseTextDirectionOptions = {}): UseTextDirectionReturn

Track an element's `dir` attribute (default the document root), updating on any `dir` mutation via `MutationObserver`.

function useThrottle<T>(source: () => T, delay: number = 200): UseThrottleReturn<T>

Track `source()`, updating at most once per `delay` ms: the first change in a window propagates immediately (leading edge), and any change that arrives before the window elapses is flushed once at the window's end (trailing edge) — no update is ever dropped.

function useTimeAgo( date: MaybeGetter<UseTimeAgoSource>, options: UseTimeAgoOptions = {}, ): UseTimeAgoReturn

Track a reactive relative-time string for `date`.

function useTimeout( delay: number = 1000, options: UseTimeoutOptions = {}, ): UseTimeoutReturn

Flip a reactive `ready` boolean to `true`, `delay` ms (default `1000`) after `start()` runs.

function useTimeoutFn( callback: () => void, delay: number = 1000, options: UseTimeoutFnOptions = {}, ): UseTimeoutFnReturn

Call `callback` once, `delay` ms after `start()` runs.

function useTimer(options: UseTimerOptions = {}): UseTimerReturn

Track elapsed wall-clock time from `start()`, with `pause()`/`resume()` support.

function useTimestamp(options: UseTimestampOptions = {}): UseTimestampReturn

Track the current epoch-ms timestamp (`Date.now()`).

function useToggle(initial = false): UseToggleReturn

A toggleable boolean.

function useTokenStream( source: string[], options: UseTokenStreamOptions = {}, ): UseTokenStreamReturn

Reveal `source` one token at a time.

function useTypewriter( source: string, options: UseTypewriterOptions = {}, ): UseTypewriterReturn

Type `source` out one character at a time.

function useWatch<T>( source: () => T, callback: UseWatchCallback<T>, options: UseWatchOptions = {}, ): Dispose

Track `source()` and invoke `callback(value, oldValue, onCleanup)` on every change (lazy by default — see module doc).

function useWindowSize(options: UseWindowSizeOptions = {}): UseWindowSizeReturn

Track the browser window's inner size.

const breakpointsDefault: Breakpoints<'sm' | 'md' | 'lg' | 'xl' | '2xl'>

The default breakpoint preset — Tailwind's scale (`sm`/`md`/`lg`/`xl`/ `2xl`), a widely-recognized set of five.

const defaultDocument: Document | undefined

The global `document`, or `undefined` under SSR.

const defaultNavigator: Navigator | undefined

The global `navigator`, or `undefined` when unavailable (SSR; some embedded runtimes lack it even with a DOM, hence the extra guard).

const defaultWindow: Window | undefined

The global `window`, or `undefined` under SSR.

const isClient

`true` when a real DOM is available (browser / jsdom); `false` under SSR (Node, Workers).

const onClickOutside

Alias — VueUse names this composable `onClickOutside`; both names are exported so callers can use either the house `useX` convention or the upstream-familiar spelling.

interface AgentEntry {
  role: string
  flags: string[]
  [k: string]: unknown
}

OPEN: only `role` and `flags` are required (the UI reads `a.flags.length` unconditionally); every other field is dashboard-defined and may vary.

interface ContractEntry {
  id: string
  issue: string | null
  owner: string | null
  status: string
  recon: string
}

interface DecideEntry {
  from: string
  contract: string | null
  ago: string
  question: string
}

interface ErrorEntry {
  from: string
  ago: string
  msg: string
}

interface FieldCell {
  column: number
  row: number
  x: number
  y: number
  /** The glyph currently drawn — mutated in place by `'drift'`. */
  char: string
  /** Index into the resolved character set, the drift base. */
  index: number
  /** Phase offset in radians, so the field does not animate in unison. */
  phase: number
  /** Per-cell speed multiplier, `[0.5, 1.5)`. */
  rate: number
  /** Alpha last drawn with. */
  opacity: number
}

One grid cell's mutable state.

interface OrphanEntry {
  contract: string
}

interface Particle {
  x: number
  y: number
  /** Horizontal velocity, px/sec. */
  vx: number
  /** Vertical velocity, px/sec. */
  vy: number
  /** Draw radius in CSS pixels. */
  radius: number
  /** Base alpha before any twinkle modulation. */
  opacity: number
  /** Fill style, drawn from `colors`. */
  color: string
  /** Twinkle phase offset in radians, so the field does not pulse in unison. */
  phase: number
}

One particle's mutable state, in CSS pixels / pixels-per-second.

interface ReviewEntry {
  contract: string
  owner: string | null
  status: string
  /** dashboard.py surface: the string `"PR #641"` or null — not a number. */
  pr: string | null
}

interface SwarmParseError {
  /** One human line for the console banner. */
  message: string
  /** Every field path that failed, e.g. `decide[0].question` — this is what
   * makes the drift diagnosable rather than a blank panel. */
  fields: string[]
}

The loud, field-naming result of a failed `/state` validation.

interface SwarmState {
  /** Formatted clock string from the server (`"20:31:10"`), not an epoch. */
  t: string
  supervisor_up: boolean
  decide: DecideEntry[]
  orphan: OrphanEntry[]
  reviews: ReviewEntry[]
  errors: ErrorEntry[]
  backlog?: SwarmBacklog
  agents: AgentEntry[]
  contracts: ContractEntry[]
  activity: ActivityEntry[]
}

interface SwarmYourMove {
  decide: DecideEntry[]
  orphan: OrphanEntry[]
  reviews: ReviewEntry[]
  errors: ErrorEntry[]
}

interface UseActiveElementReturn {
  /** Reactive getter — read as `{activeElement()}` in templates (parens
   * required). `null` under SSR; on the client, `document.body` (not
   * `null`) when nothing is explicitly focused — see module doc. */
  readonly activeElement: () => Element | null
}

interface UseAsyncAbortableOptions<T> {
  /** Invoke `fn` once immediately on call. Default `true`. Only meaningful
   * when `fn` is callable with zero (non-signal) arguments. */
  immediate?: boolean
  /** `data()`'s value before the first resolve. Default `undefined`. */
  initialData?: T
  /** Called with the resolved value after a successful (non-aborted)
   * `execute()`. */
  onSuccess?: (data: T) => void
  /** Called with the caught error after a rejected `execute()` — NOT
   * called when the rejection is the abort itself (see module doc). */
  onError?: (error: unknown) => void
  /** Clear `error()` and `isFinished()` at the START of each `execute()`
   * call. Default `true`. */
  resetOnExecute?: boolean
}

interface UseAsyncAbortableReturn<T, Args extends unknown[]> {
  /** Reactive getter — read as `{data()}` in templates (parens required). */
  readonly data: () => T | undefined
  /** Reactive getter — the last caught error, or `undefined`. An abort
   * never populates this (see module doc). */
  readonly error: () => unknown
  /** Reactive getter — `true` while a call is in flight. */
  readonly isLoading: () => boolean
  /** Reactive getter — `true` once at least one call has settled
   * (resolved, rejected, or was superseded/aborted). */
  readonly isFinished: () => boolean
  /**
   * (Re)invoke `fn`, passing it an `AbortSignal` as its first argument
   * (then `...args`). Aborts the PREVIOUS in-flight call (if any) first —
   * only one call is ever in flight at a time. An aborted call's
   * resolve/reject is silently dropped: it updates neither `data` nor
   * `error`.
   */
  execute: (...args: Args) => Promise<T | undefined>
  /** Abort the current in-flight call, if any. Idempotent. Does not by
   * itself start a new call. */
  abort: () => void
}

interface UseAsyncOptions<T> {
  /** Invoke `fn` once immediately on call. Default `true`. Only meaningful
   * when `fn` is callable with zero arguments — a `fn` that requires
   * arguments should pass `immediate: false` and call `execute(...)`
   * itself. */
  immediate?: boolean
  /** `data()`'s value before the first resolve. Default `undefined`. */
  initialData?: T
  /** Called with the resolved value after a successful `execute()`. */
  onSuccess?: (data: T) => void
  /** Called with the caught error after a rejected `execute()`. */
  onError?: (error: unknown) => void
  /** Clear `error()` and `isFinished()` at the START of each `execute()`
   * call (before `fn` resolves). Default `true` — set `false` to keep the
   * previous error/data visible while a re-fetch is in flight. */
  resetOnExecute?: boolean
}

interface UseAsyncReturn<T, Args extends unknown[]> {
  /** Reactive getter — read as `{data()}` in templates (parens required).
   * The last resolved value, or `initialData` before the first resolve. */
  readonly data: () => T | undefined
  /** Reactive getter — the last caught error, or `undefined`. Cleared at
   * the start of the next `execute()` when `resetOnExecute` (default). */
  readonly error: () => unknown
  /** Reactive getter — `true` while an `execute()` call is in flight. */
  readonly isLoading: () => boolean
  /** Reactive getter — `true` once at least one `execute()` call has
   * settled (resolved OR rejected). */
  readonly isFinished: () => boolean
  /** (Re)invoke `fn`. A call in flight is NOT cancelled by a new call (see
   * `useAsyncAbortable` for that) — but only the LATEST call's result is
   * ever written to `data`/`error`/`isLoading`/`isFinished` (a stale
   * resolve from a superseded call is silently dropped). */
  execute: (...args: Args) => Promise<T | undefined>
}

interface UseBrowserLanguageReturn {
  /** Reactive getter — read as `{language()}` in templates (parens
   * required). `undefined` under SSR (no `navigator` to read). */
  readonly language: () => string | undefined
}

interface UseCanvasSurfaceFrame {
  /** The 2D context, already transformed by `pixelRatio`. The previous
   * frame is NOT cleared — clearing is the effect's call, since a trail
   * effect wants the old pixels. */
  readonly ctx: CanvasRenderingContext2D
  /** Host width in CSS pixels. */
  readonly width: number
  /** Host height in CSS pixels. */
  readonly height: number
  /** Milliseconds since the previous frame (`0` on a `redraw()` paint and on
   * the loop's first frame). */
  readonly delta: number
  /** The frame's `DOMHighResTimeStamp`. */
  readonly timestamp: number
  /** The clamped device pixel ratio the backing store was sized with. */
  readonly pixelRatio: number
  /** `true` when this is a one-off static paint under reduced motion (see
   * the module doc's convention) — render the at-rest composition. */
  readonly reducedMotion: boolean
}

One frame's worth of drawing state, handed to `onFrame`.

interface UseCanvasSurfaceOptions {
  /** Draw callback, invoked once per animation frame while running and once
   * per `redraw()`. Omitted means the surface is sized and managed but never
   * painted. */
  onFrame?: (frame: UseCanvasSurfaceFrame) => void
  /** Called after the backing store is resized, before the repaint that
   * follows it, with the new CSS size — the hook for rebuilding
   * size-dependent state such as a particle seed or a glyph grid. */
  onResize?: (width: number, height: number) => void
  /** Start the loop as soon as a host element and context exist. Default
   * `true`. */
  immediate?: boolean
  /** Ceiling on the device pixel ratio used for the backing store. Default
   * `2`: a 3x phone display costs 2.25x the fill rate of a 2x one for detail
   * nobody can see in a decorative effect. */
  maxPixelRatio?: number
  /** Pause the loop while the host is scrolled out of view. Default `true`;
   * `false` only for a surface that must stay in sync with something
   * off-screen. */
  pauseWhenHidden?: boolean
  /** Let pointer events reach the canvas. Default `false` — decorative
   * surfaces must not eat clicks meant for the content they sit behind. */
  interactive?: boolean
  /** `alpha: false` lets the compositor skip blending when the effect paints
   * an opaque background. Default `true` (transparent). */
  alpha?: boolean
}

interface UseCanvasSurfaceReturn {
  /** Reactive getter — the owned `<canvas>`, or `null` before the host
   * resolves (and always under SSR). */
  readonly canvas: () => HTMLCanvasElement | null
  /** Reactive getter — the 2D context, or `null` if the host has not
   * resolved or the browser refused a context. */
  readonly ctx: () => CanvasRenderingContext2D | null
  /** Reactive getter — host width in CSS pixels. */
  readonly width: () => number
  /** Reactive getter — host height in CSS pixels. */
  readonly height: () => number
  /** Reactive getter — the clamped device pixel ratio in force. */
  readonly pixelRatio: () => number
  /** Reactive getter — whether the host currently intersects the viewport. */
  readonly isVisible: () => boolean
  /** Reactive getter — whether frames are actually being produced. `false`
   * under reduced motion, while hidden, and before the host resolves, even
   * after `start()`. */
  readonly isRunning: () => boolean
  /** Reactive getter — the user's reduced-motion preference, re-exported so
   * an effect can opt out of painting entirely (see the module doc). */
  readonly prefersReduced: () => boolean
  /** Ask for frames. Under reduced motion this paints one static frame
   * instead of looping. No-op after the owning effect scope is disposed. */
  start: () => void
  /** Stop asking for frames. Idempotent, and sticky: a later visibility or
   * reduced-motion change will not resume — call `start()` again. */
  stop: () => void
  /** Paint exactly one frame right now, running or not. This is how an
   * effect renders its static reduced-motion composition on demand. */
  redraw: () => void
}

interface UseCharacterFieldOptions {
  /** The glyphs to draw from, densest-last by convention. Default
   * `' .:-=+*#%@'`. A string is split per code unit; pass an array for
   * multi-code-unit glyphs. */
  characters?: string | readonly string[]
  /** Grid pitch in CSS pixels — the cell width AND height. Default `14`. */
  cellSize?: number
  /** Fraction of cells that carry a glyph at all, `[0, 1]`. Default `1`.
   * Below 1 the field is sparse, which reads as texture rather than a
   * filled block. */
  density?: number
  /** Animation mode. Default `'drift'`. */
  mode?: CharacterFieldMode
  /** Fill color for the glyphs. Default `'#ffffff'`. */
  color?: string
  /** Font family. Default `'monospace'` — a proportional font in a fixed
   * grid looks broken, so this should stay monospaced. */
  fontFamily?: string
  /** Font size in CSS px. Default `cellSize`, which fills the cell. */
  fontSize?: number
  /** Animation rate multiplier: glyph changes/sec in `'drift'`, cycles/sec
   * in `'pulse'`. Ignored by `'reveal'`. Default `4`. */
  speed?: number
  /** Base alpha before per-mode modulation. Default `0.85`. */
  opacity?: number
  /** `'reveal'` wipe duration in ms. Default `1500`. */
  revealDuration?: number
  /** Randomness source, `[0, 1)`. Default `Math.random`. Injectable so tests
   * can seed a reproducible field. */
  random?: () => number
  /** Start animating immediately. Default `true`. */
  immediate?: boolean
  /** Forwarded to {@link useCanvasSurface}. */
  maxPixelRatio?: number
  /** Forwarded to {@link useCanvasSurface}. */
  pauseWhenHidden?: boolean
}

interface UseCharacterFieldReturn {
  /** The live cell array, mutated in place — NOT reactive (see the module
   * doc). Empty until the host has a non-zero size. */
  readonly cells: () => readonly FieldCell[]
  /** Reactive getter — grid columns. */
  readonly columns: () => number
  /** Reactive getter — grid rows. */
  readonly rows: () => number
  /** Reactive getter — the owned canvas, or `null` before the host
   * resolves. */
  readonly canvas: () => HTMLCanvasElement | null
  /** Reactive getter — whether frames are actually being produced. */
  readonly isRunning: () => boolean
  /** Reactive getter — the user's reduced-motion preference. */
  readonly prefersReduced: () => boolean
  /** Rebuild the grid with fresh random glyphs/phases and repaint. In
   * `'reveal'` mode this also restarts the wipe. No-op while the host has
   * no size. */
  reseed: () => void
  /** Start animating (one static frame under reduced motion). */
  start: () => void
  /** Stop animating. Sticky — see {@link useCanvasSurface}. */
  stop: () => void
}

interface UseClampReturn {
  /** Reactive clamped getter — read as `{value()}` in templates (parens
   * required). Recomputes whenever `value`, `min`, or `max` changes. */
  readonly value: () => number
}

interface UseClickOutsideOptions {
  /** Additional elements treated as "inside" — a trigger button, a
   * teleported panel, etc. Getter entries are re-resolved on every pointer
   * event (not cached), so a `$ref` that is `null` at dispatch time is
   * simply skipped that once. */
  ignore?: Iterable<MaybeElementGetter>
  /** `addEventListener` `capture` flag for both the `pointerdown` and
   * `pointerup` document listeners. Default `true` — capture-phase so an
   * inner `stopPropagation()` (e.g. a menu item's own click handler) cannot
   * hide the outside click from this composable. */
  capture?: boolean
}

interface UseClipboardOptions {
  /** How long `copied()` stays `true` after a successful `copy()`, in ms.
   * Default `1500`. */
  copiedDuring?: number
}

interface UseClipboardReturn {
  /** Write `text` to the clipboard. Resolves once the write settles;
   * swallows a rejected `navigator.clipboard.writeText` (e.g. denied
   * permission) rather than throwing — check `isSupported()` beforehand for
   * a UI-level guard. No-op under SSR/unsupported browsers, and after the
   * owning effect scope is disposed. */
  copy: (text: string) => Promise<void>
  /** Reactive getter — `true` for `copiedDuring` ms after a successful
   * `copy()`, then resets to `false`. Read as `{copied()}` in templates
   * (parens required). */
  readonly copied: () => boolean
  /** Reactive getter — whether the async Clipboard API is available. Read
   * as `{isSupported()}` in templates (parens required). `false` under
   * SSR. */
  readonly isSupported: () => boolean
}

interface UseColorSchemeOptions {
  /** The scheme to start in. Default `'auto'`. */
  initialValue?: ColorScheme
}

interface UseColorSchemeReturn {
  /** Reactive getter for the RAW setting (`'light' | 'dark' | 'auto'`) —
   * read as `{scheme()}` in templates (parens required). */
  readonly scheme: () => ColorScheme
  /** Reactive getter for the RESOLVED scheme (`'light' | 'dark'`) — `'auto'`
   * is resolved against `usePreferredDark`. Read as `{resolved()}` in
   * templates (parens required). `'light'` under SSR. */
  readonly resolved: () => 'light' | 'dark'
  /** Update the raw setting. No-op under SSR. */
  setScheme: (value: ColorScheme) => void
}

interface UseCountdownOptions {
  /** How often (ms) the reactive `remaining` getter is refreshed while
   * running. Default `1000`. */
  interval?: number
  /** Called once, synchronously, when `remaining` reaches `0`. Not called
   * again until a subsequent `start()` completes. */
  onComplete?: () => void
}

interface UseCountdownReturn {
  /** Reactive getter — read as `{remaining()}` in templates (parens
   * required). Milliseconds remaining, clamped to `>= 0`. */
  readonly remaining: () => number
  /** Reactive getter — read as `{isRunning()}` in templates (parens
   * required). */
  readonly isRunning: () => boolean
  /** Reactive getter — read as `{isComplete()}` in templates (parens
   * required). `true` once `remaining` has reached `0`. */
  readonly isComplete: () => boolean
  /** Reset `remaining` to `duration` and (re)start counting down. No-op
   * after the owning effect scope is disposed. */
  start: () => void
  /** Stop counting down, freezing `remaining` at its current value.
   * Idempotent. */
  pause: () => void
  /** Continue counting down from the current `remaining` value. No-op if
   * already running, already complete, or after the owning effect scope is
   * disposed. */
  resume: () => void
  /** Stop counting down and reset `remaining` back to `duration`. */
  reset: () => void
}

interface UseCounterOptions {
  /** Starting value. Default `0`. Clamped to `[min, max]` at call time. */
  initial?: number
  /** Inclusive lower bound. Default `-Infinity` (no lower bound). */
  min?: number
  /** Inclusive upper bound. Default `Infinity` (no upper bound). */
  max?: number
}

interface UseCounterReturn {
  /** Reactive getter — read as `{count()}` in templates (parens required). */
  readonly count: () => number
  /** Increment by `delta` (default `1`), clamped to `max`. */
  readonly inc: (delta?: number) => void
  /** Decrement by `delta` (default `1`), clamped to `min`. */
  readonly dec: (delta?: number) => void
  /** Set to an explicit value, clamped to `[min, max]`. */
  readonly set: (value: number) => void
  /** Reset back to the (clamped) initial value. */
  readonly reset: () => void
}

interface UseCountToOptions {
  /** Starting value before any `start()` call. Default `0`. Every
   * subsequent `start()` tweens from whatever `value()` currently holds,
   * not back to this. */
  from?: number
  /** Tween duration in milliseconds. Default `1200`. */
  duration?: number
  /** Decimal places to round `value()` to. Default `0` (whole numbers). */
  decimals?: number
  /** Easing curve, `[0, 1] -> [0, 1]`. Default ease-out cubic. */
  easing?: (t: number) => number
}

interface UseCountToReturn {
  /** Reactive getter — the current (eased, rounded) value. */
  readonly value: () => number
  /** Reactive getter — true while a tween is in flight. */
  readonly isCounting: () => boolean
  /** Tween from the current `value()` to `to` over `duration`. Replaces any
   * tween in progress. No-op after the owning effect scope is disposed. */
  start: (to: number) => void
  /** Freeze the tween where it stands. Idempotent. */
  stop: () => void
  /** Jump straight to the in-flight (or most recently requested) target and
   * stop. */
  skip: () => void
}

interface UseDateFormatOptions {
  /** Passed through to `Intl.DateTimeFormat`. Default the runtime's
   * locale. */
  locales?: string | string[]
  /** Passed through to `Intl.DateTimeFormat`. Default (no options):
   * `Intl`'s numeric-date/time default. */
  dateTimeFormatOptions?: Intl.DateTimeFormatOptions
}

interface UseDebouncedReturn<T> {
  /** Reactive getter — read as `{value()}` in templates (parens required). */
  readonly value: () => T
}

interface UseDeviceMotionReturn {
  /** Reactive getter — whether the `DeviceMotionEvent` API exists. Read as
   * `{isSupported()}` in templates (parens required). `false` under SSR.
   * Does NOT reflect the iOS permission grant (see module doc) — only
   * feature presence. */
  readonly isSupported: () => boolean
  /** Reactive getter — device acceleration excluding gravity, or `null`
   * before the first reading (also `null` on devices without an
   * accelerometer that filters gravity). Read as `{acceleration()}`
   * (parens required). */
  readonly acceleration: () => DeviceMotionEventAcceleration | null
  /** Reactive getter — device acceleration including gravity, or `null`
   * before the first reading. Read as `{accelerationIncludingGravity()}`
   * (parens required). */
  readonly accelerationIncludingGravity: () => DeviceMotionEventAcceleration | null
  /** Reactive getter — device rotation rate, or `null` before the first
   * reading. Read as `{rotationRate()}` (parens required). */
  readonly rotationRate: () => DeviceMotionEventRotationRate | null
  /** Reactive getter — interval, in ms, at which data is obtained from the
   * underlying hardware. `0` before the first reading and under SSR. Read
   * as `{interval()}` (parens required). */
  readonly interval: () => number
}

interface UseDeviceOrientationReturn {
  /** Reactive getter — whether the `DeviceOrientationEvent` API exists.
   * Read as `{isSupported()}` in templates (parens required). `false`
   * under SSR. Does NOT reflect the iOS permission grant (see module doc)
   * — only feature presence. */
  readonly isSupported: () => boolean
  /** Reactive getter — rotation around the z-axis, degrees `[0, 360)`, or
   * `null` before the first reading. Read as `{alpha()}` (parens
   * required). */
  readonly alpha: () => number | null
  /** Reactive getter — rotation around the x-axis, degrees `[-180, 180]`,
   * or `null` before the first reading. Read as `{beta()}` (parens
   * required). */
  readonly beta: () => number | null
  /** Reactive getter — rotation around the y-axis, degrees `[-90, 90]`, or
   * `null` before the first reading. Read as `{gamma()}` (parens
   * required). */
  readonly gamma: () => number | null
  /** Reactive getter — whether the device provides absolute orientation
   * data. Read as `{absolute()}` (parens required). `false` before the
   * first reading and under SSR. */
  readonly absolute: () => boolean
}

interface UseDevicePixelRatioReturn {
  /** Reactive getter — read as `{pixelRatio()}` in templates (parens
   * required). `1` under SSR. */
  readonly pixelRatio: () => number
}

interface UseDocumentVisibilityReturn {
  /** Reactive getter — read as `{visibility()}` in templates (parens
   * required). `'visible'` under SSR (no `document` to observe). */
  readonly visibility: () => DocumentVisibilityState
}

interface UseElementSizeOptions {
  /** Element to observe. Omitted/`null` observes nothing — the getters stay
   * at `initialSize` and never update. A getter target rebinds reactively
   * (the observer moves to the new element when the getter's tracked signal
   * changes), mirroring {@link useElementSize}'s sibling sensors. */
  target?: MaybeElementGetter
  /** Size before the first observation (and the permanent value under
   * SSR). Default `{ width: 0, height: 0 }`. Snapshotted at call time —
   * later mutation of the passed object has no effect. */
  initialSize?: { width: number; height: number }
  /** Which box `ResizeObserver` reports. Default `'content-box'`. */
  box?: ResizeObserverBoxOptions
}

interface UseElementSizeReturn {
  /** Reactive width getter — read as `{width()}` in templates (parens
   * required). */
  readonly width: () => number
  /** Reactive height getter — read as `{height()}` in templates (parens
   * required). */
  readonly height: () => number
}

interface UseElementVisibilityOptions {
  /** Element to observe. Omitted/`null` observes nothing — the getter stays
   * at its initial value forever. A getter target rebinds reactively. */
  target?: MaybeElementGetter
  /** Value before the first observation (and the permanent value under
   * SSR). Default `false`. */
  initialValue?: boolean
  /** `IntersectionObserver` root (`null`/omitted = viewport). */
  root?: MaybeElementGetter
  /** `IntersectionObserver` `rootMargin`. */
  rootMargin?: string
  /** `IntersectionObserver` `threshold`. */
  threshold?: number | number[]
}

interface UseElementVisibilityReturn {
  /** Reactive visibility getter — read as `{isVisible()}` in templates
   * (parens required). */
  readonly isVisible: () => boolean
}

interface UseFocusWithinOptions {
  /** Element to watch. Omitted/`null` watches nothing — the getter stays
   * `false` forever. A getter target rebinds reactively (see
   * `useEventListener`'s module doc for the general pattern). */
  target?: MaybeElementGetter
}

interface UseFocusWithinReturn {
  /** Reactive getter — read as `{focused()}` in templates (parens
   * required). `true` while focus is on the target itself or any
   * (light-DOM-reachable) descendant — see module doc for the shadow-DOM
   * containment caveat. */
  readonly focused: () => boolean
}

interface UseHoverOptions {
  /** Element to watch. Omitted/`null` watches nothing — the getter stays
   * `false` forever. A getter target rebinds reactively (see
   * `useEventListener`'s module doc for the general pattern). */
  target?: MaybeElementGetter
  /** Milliseconds to wait before flipping to `true` after the pointer
   * enters. Default `0` (synchronous). A pending enter is cancelled if the
   * pointer leaves first. */
  delayEnter?: number
  /** Milliseconds to wait before flipping to `false` after the pointer
   * leaves. Default `0` (synchronous). A pending leave is cancelled if the
   * pointer re-enters first. */
  delayLeave?: number
}

interface UseHoverReturn {
  /** Reactive getter — read as `{isHovering()}` in templates (parens
   * required). */
  readonly isHovering: () => boolean
}

interface UseIdleOptions {
  /** Milliseconds of inactivity before `idle()` flips to `true`. Default
   * `60_000` (one minute). */
  timeout?: number
  /** `idle()`'s value before the first timeout elapses (and the permanent
   * value under SSR). Default `false`. */
  initialState?: boolean
  /** Which `window` events reset the idle timer. Default
   * `['mousemove', 'keydown', 'touchstart', 'scroll']`. */
  events?: Array<keyof WindowEventMap>
  /** The `window` to listen on. Default the global `window`. */
  window?: Window
  /** The `document` to watch `visibilitychange` on (becoming visible again
   * counts as activity). Default the global `document`; pass `null` to
   * disable this check. */
  document?: Document | null
}

interface UseIdleReturn {
  /** Reactive getter — read as `{idle()}` in templates (parens required). */
  readonly idle: () => boolean
  /** Reactive getter — `Date.now()` (ms epoch) at the last detected
   * activity. `0` before the first activity (and under SSR — see module
   * doc; deliberately static rather than a live server-side timestamp). */
  readonly lastActive: () => number
  /** Manually mark activity now, as if an activity event had just fired —
   * clears `idle()` and restarts the timeout. No-op under SSR. */
  reset: () => void
}

interface UseIntersectionObserverOptions {
  /** `IntersectionObserver` root (`null`/omitted = viewport). Resolved once
   * per `resume()`, not tracked reactively — a mid-observation root change
   * is rare enough that a manual `pause()`/`resume()` covers it. */
  root?: MaybeElementGetter
  /** `IntersectionObserver` `rootMargin`. */
  rootMargin?: string
  /** `IntersectionObserver` `threshold`. */
  threshold?: number | number[]
  /** Start observing immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseIntersectionObserverReturn {
  /** Reactive getter — whether the observer is currently attached. Read as
   * `{isActive()}` in templates (parens required). `false` under SSR. */
  readonly isActive: () => boolean
  /** Disconnect the observer without tearing down the composable — a
   * subsequent `resume()` re-attaches it. No-op if already paused. */
  pause: () => void
  /** (Re)attach the observer. No-op if already active, or after the owning
   * effect scope is disposed / `stop()` has been called. */
  resume: () => void
  /** Permanently stop: disconnects and disposes the target-rebinding
   * effect. Idempotent. Unlike `pause()`, a stopped observer cannot be
   * `resume()`d. */
  stop: () => void
}

interface UseIntervalFnOptions {
  /** Start the interval immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseIntervalFnReturn {
  /** Reactive getter — read as `{isActive()}` in templates (parens required). */
  readonly isActive: () => boolean
  /** Stop the interval. Idempotent. */
  pause: () => void
  /** (Re)start the interval. No-op if already running, or after the owning
   * effect scope is disposed. */
  resume: () => void
}

interface UseIntervalOptions {
  /** Start ticking immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseIntervalReturn {
  /** Reactive getter — read as `{counter()}` in templates (parens
   * required). */
  readonly counter: () => number
  /** Reset the counter back to `0`. Does not pause/resume ticking. */
  reset: () => void
  /** Stop ticking. Idempotent. */
  pause: () => void
  /** (Re)start ticking. No-op if already running, or after the owning
   * effect scope is disposed. */
  resume: () => void
}

interface UseJwtReturn<T> {
  /** Reactive decoded-payload getter — read as `{payload()}` in templates
   * (parens required). `undefined` until the first decode settles, or on
   * failure (see `error`). */
  readonly payload: () => T | undefined
  /** Reactive decode-error getter — a clear, descriptive `Error` when the
   * token is malformed OR the optional `jwt-decode` peer could not be
   * loaded; `undefined` once `payload` is set. `useJwt` never throws
   * synchronously — it degrades to this error state instead. */
  readonly error: () => Error | undefined
}

interface UseKeyedAsyncOptions<T> {
  /** `data()`'s value before the first resolve, and whenever the key
   * resets to `null`/`undefined`. Default `undefined`. */
  initialData?: T
  /** Called with the resolved value after a successful fetch for the
   * CURRENT key (a superseded key's resolve never calls this). */
  onSuccess?: (data: T) => void
  /** Called with the caught error after a rejected fetch for the CURRENT
   * key. NOT called when the rejection is the abort itself (see module
   * doc on `useAsyncAbortable` for the same rule). */
  onError?: (error: unknown) => void
}

interface UseKeyedAsyncReturn<T> {
  /** Reactive getter — read as `{data()}` in templates (parens required).
   * The latest resolved value for the CURRENT key, or `initialData`. */
  readonly data: () => T | undefined
  /** Reactive getter — the last caught error for the CURRENT key, or
   * `undefined`. Cleared the instant the key changes. */
  readonly error: () => unknown
  /** Reactive getter — `true` while a fetch for the CURRENT key is in
   * flight. */
  readonly isLoading: () => boolean
  /** Reactive getter — `true` once the CURRENT key's fetch has settled
   * (resolved or rejected); `false` again the instant the key changes. */
  readonly isFinished: () => boolean
  /** Re-run `fn` for the CURRENT key WITHOUT clearing `data` first — a
   * refresh, not a navigation to a different identity. No-op when the
   * current key is `null`/`undefined`. */
  reload: () => void
}

interface UseLocalStorageOptions<T> {
  /** Serialize a value for storage. Default `JSON.stringify`. */
  serializer?: (value: T) => string
  /** Deserialize a stored string back to a value. Default `JSON.parse`. */
  deserializer?: (raw: string) => T
  /** The `window` to read `localStorage`/listen for `storage` on. Default
   * the global `window`. */
  window?: Window
}

interface UseLocalStorageReturn<T> {
  /** Reactive getter — read as `{value()}` in templates (parens required).
   * The provided default under SSR. */
  readonly value: () => T
  /** Write a new value: updates the signal, persists to `localStorage`,
   * and (SSR: a plain in-memory write — no `localStorage` access). */
  setValue: (next: T) => void
}

interface UseMapReturn<K, V> {
  /** Reactive getter — read as `{size()}` in templates (parens required). */
  readonly size: () => number
  /** Reactive read — tracks the underlying signal, so an effect calling
   * `get(key)` re-runs on any `set`/`delete`/`clear` that could affect it. */
  get: (key: K) => V | undefined
  /** Reactive read, same tracking as `get`. */
  has: (key: K) => boolean
  /** Reactive getter — a fresh `[key, value]` array snapshot, read as
   * `{entries()}` (parens required). */
  readonly entries: () => Array<[K, V]>
  /** Reactive getter — a fresh key array snapshot. */
  readonly keys: () => K[]
  /** Reactive getter — a fresh value array snapshot. */
  readonly values: () => V[]
  /** Set `key` to `value` — replaces the underlying `Map` (see module
   * doc). No-op under SSR. */
  set: (key: K, value: V) => void
  /** Delete `key`; returns whether it was present. Replaces the underlying
   * `Map` only when it actually removes an entry. No-op (returns `false`)
   * under SSR. */
  delete: (key: K) => boolean
  /** Remove every entry. No-op under SSR. */
  clear: () => void
}

interface UseMeasureOptions {
  /** Element to observe. Omitted/`null` observes nothing — the getters
   * stay at `initialRect` and never update. A getter target rebinds
   * reactively (see `useResizeObserver`). */
  target?: MaybeElementGetter
  /** Rect before the first observation (and the permanent value under
   * SSR). Default all-`0`. Snapshotted at call time — later mutation of
   * the passed object has no effect. */
  initialRect?: Partial<UseMeasureRect>
  /** Which box `ResizeObserver` reports for `width`/`height`. Default
   * `'content-box'`. Does not affect `x`/`y`/`top`/`right`/`bottom`/`left`
   * — those always come from `getBoundingClientRect()` (see module doc). */
  box?: ResizeObserverBoxOptions
}

interface UseMeasureRect {
  x: number
  y: number
  width: number
  height: number
  top: number
  right: number
  bottom: number
  left: number
}

interface UseMeasureReturn {
  /** Reactive getter — read as `{x()}` in templates (parens required).
   * Viewport-relative, from `getBoundingClientRect()`. */
  readonly x: () => number
  /** Reactive getter — viewport-relative `y`. */
  readonly y: () => number
  /** Reactive getter — box width (honors `box`). */
  readonly width: () => number
  /** Reactive getter — box height (honors `box`). */
  readonly height: () => number
  /** Reactive getter — viewport-relative `top`. */
  readonly top: () => number
  /** Reactive getter — viewport-relative `right`. */
  readonly right: () => number
  /** Reactive getter — viewport-relative `bottom`. */
  readonly bottom: () => number
  /** Reactive getter — viewport-relative `left`. */
  readonly left: () => number
}

interface UseMediaQueryOptions {
  /** The `window` to query against. Default the global `window`. */
  window?: Window
}

interface UseMediaQueryReturn {
  /** Reactive match getter — read as `{matches()}` in templates (parens
   * required). `false` under SSR (no viewport to evaluate the query). */
  readonly matches: () => boolean
}

interface UseMouseInElementOptions {
  /** Element to measure against. Omitted/`null` (or a getter currently
   * resolving to one) means nothing is ever "inside" — `isOutside()` stays
   * `true` and the element-relative getters stay `0`. A getter target
   * rebinds reactively (see `useEventListener`'s module doc). */
  target?: MaybeElementGetter
}

interface UseMouseInElementReturn {
  /** Reactive getter — raw viewport `clientX`. */
  readonly x: () => number
  /** Reactive getter — raw viewport `clientY`. */
  readonly y: () => number
  /** Reactive getter — `x()` relative to the target's left edge. */
  readonly elementX: () => number
  /** Reactive getter — `y()` relative to the target's top edge. */
  readonly elementY: () => number
  /** Reactive getter — the target's left edge, document-relative
   * (`rect.left + scrollX`). */
  readonly elementPositionX: () => number
  /** Reactive getter — the target's top edge, document-relative
   * (`rect.top + scrollY`). */
  readonly elementPositionY: () => number
  /** Reactive getter — the target's current `getBoundingClientRect().width`. */
  readonly elementWidth: () => number
  /** Reactive getter — the target's current `getBoundingClientRect().height`. */
  readonly elementHeight: () => number
  /** Reactive getter — `true` when the pointer is NOT currently over the
   * target's composed subtree (see module doc for how this is computed). */
  readonly isOutside: () => boolean
}

interface UseMouseOptions {
  /** Position before the first `mousemove` (and the permanent value under
   * SSR). Default `{ x: 0, y: 0 }`. Snapshotted at call time — later
   * mutation of the passed object has no effect (keeps SSR and client
   * deterministic). */
  initialValue?: { x: number; y: number }
  /** Listen target. OMITTED (`undefined`) defaults to `window`; an explicit
   * `null` means "nothing" and registers no listener (the ratified
   * null-vs-undefined rule for all sensors). Getter targets rebind
   * reactively (see {@link useEventListener}). */
  target?: MaybeElementGetter | Window | Document
  /** Coordinate system: `clientX/Y` (default), `pageX/Y`, or `screenX/Y`. */
  type?: UseMouseCoordType
}

interface UseMouseReturn {
  /** Reactive x getter — read as `{x()}` in templates (parens required). */
  readonly x: () => number
  /** Reactive y getter — read as `{y()}` in templates (parens required). */
  readonly y: () => number
}

interface UseMutationObserverReturn {
  /** Disconnect the observer (and dispose the target-rebinding effect).
   * Idempotent. */
  stop: () => void
  /** Forward to the live observer's `takeRecords()` — drains its pending
   * mutation record queue without waiting for the next microtask. Returns
   * `[]` if no observer is currently attached (no target yet, or after
   * `stop()`). */
  takeRecords: () => MutationRecord[]
}

interface UseNetworkStateOptions {
  /** The `window` to listen for `online`/`offline` on. Default the global
   * `window`. */
  window?: Window
  /** The `navigator` to read `onLine`/`connection` from. Default the
   * global `navigator`. */
  navigator?: Navigator
}

interface UseNetworkStateReturn {
  /** Reactive getter — read as `{isOnline()}` in templates (parens
   * required). Mirrors `navigator.onLine`. `true` under SSR (see module
   * doc). */
  readonly isOnline: () => boolean
  /** Reactive getter — Network Information API's connection type estimate
   * (`'4g'`, `'3g'`, …), or `undefined` when unsupported. */
  readonly effectiveType: () => string | undefined
  /** Reactive getter — estimated downlink bandwidth in Mbps, or
   * `undefined` when unsupported. */
  readonly downlink: () => number | undefined
  /** Reactive getter — estimated round-trip time in ms, or `undefined`
   * when unsupported. */
  readonly rtt: () => number | undefined
  /** Reactive getter — the user's data-saver preference, or `undefined`
   * when unsupported. */
  readonly saveData: () => boolean | undefined
  /** `true` when the Network Information API (`navigator.connection` or a
   * vendor-prefixed equivalent) is present in this environment. Static —
   * computed once at call time, support does not change mid-session. */
  readonly isSupported: () => boolean
}

interface UseNowOptions {
  /** Update cadence: a millisecond interval (default `1000`), or
   * `'requestAnimationFrame'` to update on every frame. */
  interval?: 'requestAnimationFrame' | number
}

interface UseNowReturn {
  /** Reactive getter — read as `{now()}` in templates (parens required). */
  readonly now: () => Date
}

interface UseOperatingSystemReturn {
  /** Best-effort getter — read as `{os()}` in templates (parens required).
   * `'unknown'` under SSR. See the module doc's heuristic caveat before
   * using this for anything but presentation. */
  readonly os: () => OperatingSystem
}

interface UseOrientationReturn {
  /** Reactive getter for the rotation angle in degrees. Read as
   * `{angle()}` in templates (parens required). `0` under SSR. */
  readonly angle: () => number
  /** Reactive getter for the orientation type. Read as `{type()}` in
   * templates (parens required). `'portrait-primary'` under SSR. */
  readonly type: () => OrientationType
}

interface UseParticleFieldOptions {
  /** How many particles. Default `48`. Snapshotted — this is not reactive;
   * a component that needs a live count should re-create the composable. */
  count?: number
  /** Fill colors, sampled per particle. Default `['#ffffff']`. A future
   * `.aihu` component prop will arrive as a comma-separated string; parsing
   * that is the COMPONENT's job (Slice 9), not this composable's — the TS
   * API takes a real array. */
  colors?: readonly string[]
  /** Smallest particle radius, CSS px. Default `1`. */
  minRadius?: number
  /** Largest particle radius, CSS px. Default `2.5`. */
  maxRadius?: number
  /** Peak drift speed, px/sec, seeded per particle in `[-speed, speed]` on
   * each axis. Default `18`. */
  speed?: number
  /** Constant downward acceleration, px/sec^2. Default `0` (weightless
   * drift). Negative floats particles upward. */
  gravity?: number
  /** Acceleration toward the pointer, px/sec^2 at 100px distance, falling
   * off with the inverse square of distance. Default `0` (off — and when
   * off, no pointer listener is registered at all). Negative repels. */
  pointerAttraction?: number
  /** Modulate each particle's alpha sinusoidally. Default `true`. */
  twinkle?: boolean
  /** Twinkle cycles per second. Default `0.4`. */
  twinkleSpeed?: number
  /** Lowest seeded base opacity. Default `0.25`. */
  minOpacity?: number
  /** Highest seeded base opacity. Default `0.9`. */
  maxOpacity?: number
  /** Randomness source, `[0, 1)`. Default `Math.random`. Injectable so tests
   * (and any future deterministic render) can seed a reproducible field. */
  random?: () => number
  /** Start animating immediately. Default `true`. */
  immediate?: boolean
  /** Forwarded to {@link useCanvasSurface}. */
  maxPixelRatio?: number
  /** Forwarded to {@link useCanvasSurface}. */
  pauseWhenHidden?: boolean
}

interface UseParticleFieldReturn {
  /** The live particle array, mutated in place — NOT reactive (see the
   * module doc). Empty until the host has a non-zero size. */
  readonly particles: () => readonly Particle[]
  /** Reactive getter — the owned canvas, or `null` before the host
   * resolves. */
  readonly canvas: () => HTMLCanvasElement | null
  /** Reactive getter — whether frames are actually being produced. */
  readonly isRunning: () => boolean
  /** Reactive getter — the user's reduced-motion preference. */
  readonly prefersReduced: () => boolean
  /** Re-seed every particle at fresh random positions and velocities, then
   * repaint. Idempotent; no-op while the host has no size. */
  reseed: () => void
  /** Start animating (one static frame under reduced motion). */
  start: () => void
  /** Stop animating. Sticky — see {@link useCanvasSurface}. */
  stop: () => void
}

interface UsePerformanceObserverReturn {
  /** Disconnect the observer. Idempotent; also a no-op when
   * `PerformanceObserver` was never supported/constructed. */
  stop: () => void
}

interface UsePreferredContrastReturn {
  /** Reactive getter — read as `{preference()}` in templates (parens
   * required). `'no-preference'` under SSR (no viewport to evaluate the
   * query against). */
  readonly preference: () => ContrastPreference
}

interface UsePreferredDarkReturn {
  /** Reactive getter — read as `{prefersDark()}` in templates (parens
   * required). `false` under SSR. */
  readonly prefersDark: () => boolean
}

interface UsePreferredLanguagesReturn {
  /** Reactive getter — read as `{languages()}` in templates (parens
   * required). `[]` under SSR (no `navigator` to read). */
  readonly languages: () => readonly string[]
}

interface UsePreferredReducedMotionReturn {
  /** Reactive getter — read as `{preference()}` in templates (parens
   * required). `'no-preference'` under SSR (no viewport to evaluate the
   * query against). */
  readonly preference: () => ReducedMotionPreference
}

interface UsePreferredReducedTransparencyReturn {
  /** Reactive getter — read as `{preference()}` in templates (parens
   * required). `'no-preference'` under SSR (no viewport to evaluate the
   * query against). */
  readonly preference: () => ReducedTransparencyPreference
}

interface UseRafFnCallbackArgs {
  /** Milliseconds elapsed since the previous frame (`0` on the first). */
  delta: number
  /** The frame's `DOMHighResTimeStamp`, as passed to `requestAnimationFrame`. */
  timestamp: number
}

interface UseRafFnOptions {
  /** Start the rAF loop immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseRafFnReturn {
  /** Reactive getter — read as `{isActive()}` in templates (parens required). */
  readonly isActive: () => boolean
  /** Cancel the pending frame and stop the loop. Idempotent. */
  pause: () => void
  /** (Re)start the loop. No-op if already running, or after the owning
   * effect scope is disposed. */
  resume: () => void
}

interface UseReducedMotionReturn {
  /** Reactive getter — read as `{prefersReduced()}` in templates (parens
   * required). `false` under SSR (no viewport to evaluate the query). */
  readonly prefersReduced: () => boolean
}

interface UseResizeObserverOptions {
  /** Which box(es) `ResizeObserver` reports. Default `'content-box'`. */
  box?: ResizeObserverBoxOptions
}

interface UseResizeObserverReturn {
  /** Disconnect the observer (and dispose the target-rebinding effect).
   * Idempotent. */
  stop: () => void
}

interface UseRouteParamsReturn {
  /** Reactive params getter — read as `{params()}` in templates (parens
   * required). `{}` with no active route (or outside a `<router>` context). */
  readonly params: () => Record<string, string>
}

interface UseScrollOptions {
  /** Scroll container. OMITTED (`undefined`) defaults to `window`; an
   * explicit `null` means "nothing" and registers no listener (the
   * ratified null-vs-undefined rule for all sensors). Getter targets
   * rebind reactively (see {@link useEventListener}). */
  target?: MaybeElementGetter | Window
  /** Position before the first `scroll` event (and the permanent value
   * under SSR). Default `{ x: 0, y: 0 }`. Snapshotted at call time — later
   * mutation of the passed object has no effect. */
  initialValue?: { x: number; y: number }
}

interface UseScrollReturn {
  /** Reactive x getter — read as `{x()}` in templates (parens required). */
  readonly x: () => number
  /** Reactive y getter — read as `{y()}` in templates (parens required). */
  readonly y: () => number
}

interface UseSequenceOptions {
  /** Milliseconds to hold on each item before advancing. Default `2000`. */
  interval?: number
  /** Wrap from the last item back to the first. Default `true`; `false`
   * stops (and stays put) after reaching the last item. */
  loop?: boolean
  /** Start the auto-advance interval immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseSequenceReturn<T> {
  /** Reactive getter — the item at the current index. */
  readonly current: () => T
  /** Reactive getter — the current index into `items`. */
  readonly index: () => number
  /** Reactive getter — true while the auto-advance interval is armed (false
   * whenever `prefersReduced()` is true, even if `start()` was called). */
  readonly isRunning: () => boolean
  /** (Re)start auto-advancing. Under reduced motion, arms once the
   * preference clears (see the reduced-motion note above); no-op after the
   * owning effect scope is disposed. */
  start: () => void
  /** Stop auto-advancing. Idempotent. A later reduced-motion preference
   * change will not resume it — call `start()` again to re-arm. */
  stop: () => void
  /** Advance one item (wrapping per `loop`). Works regardless of
   * `isRunning()` — an explicit call, not autoplay. */
  next: () => void
  /** Go back one item (wrapping per `loop`). */
  prev: () => void
}

interface UseSetReturn<T> {
  /** Reactive getter — read as `{size()}` in templates (parens required). */
  readonly size: () => number
  /** Reactive read — tracks the underlying signal, so an effect calling
   * `has(value)` re-runs on any `add`/`delete`/`clear` that could affect
   * it. */
  has: (value: T) => boolean
  /** Reactive getter — a fresh value array snapshot, read as `{values()}`
   * (parens required). */
  readonly values: () => T[]
  /** Add `value`. Replaces the underlying `Set` (see module doc) only when
   * `value` wasn't already present. No-op under SSR. */
  add: (value: T) => void
  /** Delete `value`; returns whether it was present. No-op (returns
   * `false`) under SSR. */
  delete: (value: T) => boolean
  /** Remove every value. No-op under SSR. */
  clear: () => void
}

interface UseStopwatchOptions {
  /** How often (ms) the reactive `elapsed` getter is refreshed while
   * running. Default `1000`. */
  interval?: number
}

interface UseStopwatchReturn {
  /** Reactive getter — read as `{elapsed()}` in templates (parens
   * required). Milliseconds elapsed since `start()`, minus paused time. */
  readonly elapsed: () => number
  /** Reactive getter — read as `{laps()}` in templates (parens required).
   * Cumulative `elapsed` snapshot at each `lap()` call, oldest first. A
   * fresh array reference on every change (safe to read directly in a
   * template `$each`). */
  readonly laps: () => number[]
  /** Reactive getter — read as `{isRunning()}` in templates (parens
   * required). */
  readonly isRunning: () => boolean
  /** Reset `elapsed` to `0`, clear `laps`, and (re)start running. No-op
   * after the owning effect scope is disposed. */
  start: () => void
  /** Stop running, freezing `elapsed` at its current value. Idempotent. */
  pause: () => void
  /** Continue running from the current `elapsed` value. No-op if already
   * running, or after the owning effect scope is disposed. */
  resume: () => void
  /** Record the current `elapsed` value onto the end of `laps`. No-op
   * while not running (there is nothing meaningful to snapshot before the
   * first `start()`, or after a `pause()`/`reset()`). */
  lap: () => void
  /** Stop running and reset both `elapsed` and `laps`. */
  reset: () => void
}

interface UseSwarmOptions {
  /** Base URL of the bus (no trailing slash). Default
   * `http://127.0.0.1:8791`; `/stream` is appended to open the SSE
   * connection. */
  url?: string
  /** The `window` used to gate client-ness. Default the global `window`.
   * Passing `undefined` explicitly forces the SSR-style no-op path, same as
   * `useLocalStorage`. */
  window?: Window
}

interface UseSwarmReturn {
  /** Reactive getter — read as `{state()}` in templates (parens required).
   * The latest full {@link SwarmState} frame; a static empty default under
   * SSR / before the first frame arrives. */
  readonly state: () => SwarmState
  /** Reactive getter — `state().agents`. */
  readonly agents: () => AgentEntry[]
  /** Reactive getter — `state().contracts`. */
  readonly contracts: () => ContractEntry[]
  /** Reactive getter — the `decide`/`orphan`/`reviews`/`errors` slice of
   * `state()`, grouped for a "what needs a move" view. */
  readonly yourMove: () => SwarmYourMove
  /** Reactive getter — whether the `/stream` connection is currently open.
   * Always `false` under SSR. */
  readonly connected: () => boolean
  /** Reactive getter — the LOUD drift signal. `null` when the latest `/state`
   * frame validated; a {@link SwarmParseError} naming the failed field(s) when
   * it did not. The UI MUST render this: `/state` is produced by out-of-tree
   * `dashboard.py`, so a renamed Python field is caught only here, and a
   * silent empty panel (rendering as though there is nothing to decide) is
   * indistinguishable from real drift. A validation failure NEVER blanks data —
   * `state()` keeps the last good frame and `error()` explains the drift. */
  readonly error: () => SwarmParseError | null
  /** Tear down the underlying `EventSource`. Idempotent; a no-op under
   * SSR. */
  close: () => void
}

interface UseTextDirectionOptions {
  /** Element to read `dir` from. Default `document.documentElement` (the
   * `<html>` root). A getter target rebinds reactively — the observer moves
   * to the new element when the getter's tracked signal changes (mirrors
   * `useElementSize`'s sibling sensors); a getter that reads no signal runs
   * once and never rebinds (same documented caveat as `useEventListener`). */
  target?: MaybeElementGetter
}

interface UseTextDirectionReturn {
  /** Reactive getter — read as `{direction()}` in templates (parens
   * required). `'ltr'` under SSR (no DOM to read). */
  readonly direction: () => TextDirection
}

interface UseThrottleReturn<T> {
  /** Reactive getter — read as `{value()}` in templates (parens required). */
  readonly value: () => T
}

interface UseTimeAgoOptions {
  /** Passed through to `Intl.RelativeTimeFormat`. Default the runtime's
   * locale. */
  locales?: string | string[]
  /** Start the auto-update loop immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTimeAgoReturn {
  /** Reactive getter — read as `{timeAgo()}` in templates (parens
   * required). */
  readonly timeAgo: () => string
  /** Stop auto-updating, freezing the string at its current value.
   * Idempotent. */
  pause: () => void
  /** Resume auto-updating (recomputes immediately, then resumes the
   * adaptive cadence). No-op if already running, or after the owning
   * effect scope is disposed. */
  resume: () => void
}

interface UseTimeoutFnOptions {
  /** Call `start()` immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTimeoutFnReturn {
  /** Reactive getter — read as `{isPending()}` in templates (parens required). */
  readonly isPending: () => boolean
  /** (Re)start the timeout, replacing any pending one. No-op after the
   * owning effect scope is disposed. */
  start: () => void
  /** Cancel a pending timeout. Idempotent; no-op if none pending. */
  stop: () => void
}

interface UseTimeoutOptions {
  /** Call `start()` immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTimeoutReturn {
  /** Reactive getter — read as `{ready()}` in templates (parens required).
   * `false` until `delay` ms after the most recent `start()`. */
  readonly ready: () => boolean
  /** (Re)start the timeout, replacing any pending one and resetting
   * `ready` to `false`. No-op after the owning effect scope is disposed. */
  start: () => void
  /** Cancel a pending timeout without flipping `ready`. Idempotent. */
  stop: () => void
}

interface UseTimerOptions {
  /** How often (ms) the reactive `elapsed` getter is refreshed while
   * running. Default `1000`. Lower values give smoother display at the
   * cost of more ticks. */
  interval?: number
}

interface UseTimerReturn {
  /** Reactive getter — read as `{elapsed()}` in templates (parens
   * required). Milliseconds elapsed since `start()`, minus paused time. */
  readonly elapsed: () => number
  /** Reactive getter — read as `{isRunning()}` in templates (parens
   * required). */
  readonly isRunning: () => boolean
  /** Reset `elapsed` to `0` and (re)start running. No-op after the owning
   * effect scope is disposed. */
  start: () => void
  /** Stop running, freezing `elapsed` at its current value. Idempotent. */
  pause: () => void
  /** Continue running from the current `elapsed` value. No-op if already
   * running, or after the owning effect scope is disposed. */
  resume: () => void
  /** Stop running and reset `elapsed` back to `0`. */
  reset: () => void
}

interface UseTimestampOptions {
  /** Update cadence: a millisecond interval (default `1000`), or
   * `'requestAnimationFrame'` to update on every frame. */
  interval?: 'requestAnimationFrame' | number
  /** Start updating immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTimestampReturn {
  /** Reactive getter — read as `{timestamp()}` in templates (parens
   * required). */
  readonly timestamp: () => number
  /** Stop updating. Idempotent. */
  pause: () => void
  /** (Re)start updating. No-op if already running, or after the owning
   * effect scope is disposed. */
  resume: () => void
}

interface UseTokenStreamOptions {
  /** Milliseconds between revealing each token. Default `60`. */
  interval?: number
  /** Milliseconds to hold the fully-revealed stream before resetting and
   * restreaming, when `loop` is on. Default `1500`. */
  holdDelay?: number
  /** Reset to empty and restream forever once fully revealed. Default `false`. */
  loop?: boolean
  /** Start streaming `source` immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTokenStreamReturn {
  /** Reactive getter — the tokens revealed so far, in order. */
  readonly tokens: () => string[]
  /** Reactive getter — true while a reveal/hold step is scheduled. */
  readonly isStreaming: () => boolean
  /** Reactive getter — true once a non-looping run has revealed every
   * token, or immediately after `skip()`. Never true mid-loop. */
  readonly isDone: () => boolean
  /** (Re)start streaming `source` from empty, replacing any run in progress.
   * No-op after the owning effect scope is disposed. */
  start: (source: string[]) => void
  /** Cancel the pending step, freezing `tokens()` where it stands. Idempotent. */
  stop: () => void
  /** Reveal every remaining token immediately and stop. */
  skip: () => void
}

interface UseTypewriterOptions {
  /** Milliseconds per character typed. Default `40`. */
  speed?: number
  /** Milliseconds per character erased, when `loop` is on. Default `20`. */
  eraseSpeed?: number
  /** Milliseconds to hold the fully-typed text before erasing, when `loop`
   * is on. Default `1200`. */
  holdDelay?: number
  /** Erase and retype forever once the text is fully typed. Default `false`. */
  loop?: boolean
  /** Start typing `source` immediately on call. Default `true`. */
  immediate?: boolean
}

interface UseTypewriterReturn {
  /** Reactive getter — the substring typed (or not yet erased) so far. */
  readonly text: () => string
  /** Reactive getter — true while a type/hold/erase step is scheduled. */
  readonly isTyping: () => boolean
  /** Reactive getter — true once a non-looping run has fully typed `source`,
   * or immediately after `skip()`. Never true mid-loop. */
  readonly isDone: () => boolean
  /** (Re)start typing `source` from an empty string, replacing any run in
   * progress. No-op after the owning effect scope is disposed. */
  start: (source: string) => void
  /** Cancel the pending step, freezing `text()` where it stands. Idempotent. */
  stop: () => void
  /** Jump straight to the fully-typed string and stop. */
  skip: () => void
}

interface UseWatchOptions {
  /** Invoke `callback` once synchronously at creation, with `oldValue` as
   * `undefined`. Default `false` — lazy: the callback only runs on a
   * subsequent CHANGE, never on creation. */
  immediate?: boolean
  /** Stop after the callback's first invocation (the immediate call if
   * `immediate: true`, otherwise the first real change). Default `false`. */
  once?: boolean
}

interface UseWindowSizeOptions {
  /** Width before the first `resize` event (and the permanent value under
   * SSR). Default `0`. */
  initialWidth?: number
  /** Height before the first `resize` event (and the permanent value under
   * SSR). Default `0`. */
  initialHeight?: number
}

interface UseWindowSizeReturn {
  /** Reactive width getter — read as `{width()}` in templates (parens
   * required). */
  readonly width: () => number
  /** Reactive height getter — read as `{height()}` in templates (parens
   * required). */
  readonly height: () => number
}

type Breakpoints<K extends string = string> = Record<K, number>

type CharacterFieldMode = 'drift' | 'pulse' | 'reveal'

How the field animates.

type ColorScheme = 'light' | 'dark' | 'auto'

A color-scheme setting: an explicit choice, or `'auto'` to follow the OS preference.

type ContrastPreference = 'more' | 'less' | 'custom' | 'no-preference'

The `prefers-contrast` media-feature's value vocabulary.

type Dispose

type MaybeElementGetter = Element | null | undefined | (() => Element | null | undefined)

A composable element target: a static element, nothing, or a getter for one (e.g.

type MaybeGetter<T> = T | (() => T)

A plain value or a zero-arg getter for one.

type OperatingSystem = 'windows' | 'macos' | 'linux' | 'android' | 'ios' | 'unknown'

Best-effort OS classification.

type ReducedMotionPreference = 'reduce' | 'no-preference'

The `prefers-reduced-motion` media-feature's value vocabulary — matches the CSS feature directly rather than collapsing to a bare boolean, so a caller can distinguish "the browser has an opinion and it's 'reduce'" from a hypothetical future third value without a breaking rename.

type ReducedTransparencyPreference = 'reduce' | 'no-preference'

The `prefers-reduced-transparency` media-feature's value vocabulary.

type SwarmRecord = Record<string, unknown>

type TextDirection = 'ltr' | 'rtl' | 'auto'

The `dir` attribute's three legal values.

type UseBreakpointsReturn<K extends string> = Record<K, () => boolean> & {
  /** `true` when the viewport is at least as wide as breakpoint `name`
   * (identical to calling `result[name]()` — spelled out for readability
   * at call sites that already have the name as a variable). */
  greaterOrEqual: (name: K) => boolean
  /** `true` when the viewport is narrower than breakpoint `name`. */
  smaller: (name: K) => boolean
  /** `true` when the viewport is in `[breakpoints[from], breakpoints[to])`
   * — at least `from`, but narrower than `to`. */
  between: (from: K, to: K) => boolean
  /** Every breakpoint name currently satisfied (ascending by px value),
   * e.g. `['sm', 'md']` on a viewport >= `md` but < `lg`. Recomputed on
   * each call from the underlying getters — not cached. */
  current: () => K[]
}

type UseBrowserLanguageOptions = Record<string, never>

type UseDateFormatReturn = () => string

Reactive getter — read as `{formatted()}` in templates (parens required).

type UseDateFormatSource = Date | number | string

A `Date`, an epoch-ms `number`, or any string `Date` accepts.

type UseMouseCoordType = 'client' | 'page' | 'screen'

Which coordinate pair to report.

type UseOperatingSystemOptions = Record<string, never>

type UsePageLeaveReturn = () => boolean

Reactive getter — read as `{isLeft()}` in templates (parens required).

type UsePreferredContrastOptions = Record<string, never>

type UsePreferredLanguagesOptions = Record<string, never>

type UsePreferredReducedMotionOptions = Record<string, never>

type UsePreferredReducedTransparencyOptions = Record<string, never>

type UsePreviousReturn<T> = () => T | undefined

Reactive getter — read as `{previous()}` in templates (parens required).

type UseSupportedReturn = () => boolean

Reactive getter — read as `{supported()}` in templates (parens required).

type UseTimeAgoSource = Date | number | string

A `Date`, an epoch-ms `number`, or any string `Date` accepts.

type UseToggleFn = (value?: boolean) => void

Flip the current value, or set it explicitly.

type UseToggleReturn = readonly [() => boolean, UseToggleFn]

`[state, toggle]` — read as `on()` and `toggle()`/`toggle(v)`.

type UseWatchCallback<T> = (
  value: T,
  oldValue: T | undefined,
  onCleanup: (fn: () => void) => void,
) => void