@humanspeak/svelte-motion 0.4.8 → 0.5.0

package/dist/html/_MotionContainer.svelte

@@ -8,7 +8,7 @@
     import {
         filterReducedMotionKeyframes,
         useReducedMotionConfig
-    } from '../utils/reducedMotionConfig'
+    } from '../utils/reducedMotionConfig.svelte'
     import type {
         MotionProps,
         MotionTransition,
@@ -29,7 +29,7 @@
     import { attachWhileTap } from '../utils/interaction'
     import { attachWhileHover } from '../utils/hover'
     import { attachWhileFocus } from '../utils/focus'
-    import { attachWhileInView } from '../utils/inView'
+    import { attachWhileInView } from '../utils/inView.svelte'
     import {
         measureRect,
         computeFlipTransforms,
@@ -57,7 +57,7 @@
         setCustomContext,
         getCustomContext
     } from '../components/variantContext.context'
-    import { get, writable } from 'svelte/store'
+    import { writable } from 'svelte/store'
     import {
         transformSVGPathProperties,
         computeNormalizedSVGInitialAttrs,
@@ -130,11 +130,11 @@
     let isLoaded = $state<'mounting' | 'initial' | 'ready' | 'animated'>('mounting')
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
-    const reducedMotionStore = useReducedMotionConfig()
-    // Seed synchronously so the first render filters keyframes correctly —
-    // otherwise transforms could flash before the subscribe effect runs.
-    let reducedMotion = $state(get(reducedMotionStore))
-    $effect(() => reducedMotionStore.subscribe((value) => (reducedMotion = value)))
+    const reducedMotionState = useReducedMotionConfig()
+    // `.current` is $state-backed inside reducedMotionState; tracking it via
+    // $derived makes `reducedMotion` re-evaluate whenever the OS preference
+    // or `<MotionConfig reducedMotion>` policy changes.
+    const reducedMotion = $derived(reducedMotionState.current)
 
     // Get presence context to check if we're inside AnimatePresence
     const context = getAnimatePresenceContext()

package/dist/index.d.ts

@@ -10,30 +10,36 @@ export type { DragAxis, DragConstraints, DragControls, DragInfo, DragTransition,
 export { useAnimate } from './utils/animate.svelte';
 export type { AnimationScope } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
+export type { AugmentedMotionValue } from './utils/augmentMotionValue.svelte';
 export { useCycle } from './utils/cycle.svelte';
 export type { Cycle, CycleState } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
-export { useInView } from './utils/inView';
-export type { UseInViewOptions } from './utils/inView';
-export { useMotionTemplate } from './utils/motionTemplate';
-export { useMotionValue } from './utils/motionValue';
-export type { MotionValue } from './utils/motionValue';
+export { useInView } from './utils/inView.svelte';
+export type { InViewState, UseInViewOptions } from './utils/inView.svelte';
+export { useMotionTemplate } from './utils/motionTemplate.svelte';
+export type { MotionTemplateInput } from './utils/motionTemplate.svelte';
+export { useMotionValue } from './utils/motionValue.svelte';
+export type { MotionValue, RawMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
-export { useReducedMotion } from './utils/reducedMotion';
-export { useReducedMotionConfig } from './utils/reducedMotionConfig';
-export { useScroll } from './utils/scroll';
+export { useReducedMotion } from './utils/reducedMotion.svelte';
+export type { ReducedMotionState } from './utils/reducedMotion.svelte';
+export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
+export { useScroll } from './utils/scroll.svelte';
+export type { UseScrollOptions, UseScrollReturn } from './utils/scroll.svelte';
 export { useSpring } from './utils/spring.svelte';
 export type { SpringMotionValue, UseSpringOptions } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
 export type { UsePresenceState } from './utils/usePresence';
-export { useVelocity } from './utils/velocity';
+export { useVelocity } from './utils/velocity.svelte';
+export type { VelocitySource } from './utils/velocity.svelte';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */
 export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
-export { useTime } from './utils/time';
-export { useTransform } from './utils/transform';
+export { useTime } from './utils/time.svelte';
+export { useTransform } from './utils/transform.svelte';
+export type { MultiTransformer, SingleTransformer, TransformOptions, TransformOutputMap, TransformSource } from './utils/transform.svelte';
 export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

package/dist/index.js

@@ -13,23 +13,23 @@ export { useAnimate } from './utils/animate.svelte';
 export { useAnimationFrame } from './utils/animationFrame';
 export { useCycle } from './utils/cycle.svelte';
 export { createDragControls } from './utils/dragControls';
-export { useInView } from './utils/inView';
-export { useMotionTemplate } from './utils/motionTemplate';
-export { useMotionValue } from './utils/motionValue';
+export { useInView } from './utils/inView.svelte';
+export { useMotionTemplate } from './utils/motionTemplate.svelte';
+export { useMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
-export { useReducedMotion } from './utils/reducedMotion';
-export { useReducedMotionConfig } from './utils/reducedMotionConfig';
-export { useScroll } from './utils/scroll';
+export { useReducedMotion } from './utils/reducedMotion.svelte';
+export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
+export { useScroll } from './utils/scroll.svelte';
 export { useSpring } from './utils/spring.svelte';
 export { useIsPresent, usePresence } from './utils/usePresence';
-export { useVelocity } from './utils/velocity';
+export { useVelocity } from './utils/velocity.svelte';
 /**
  * @deprecated Use `styleString` instead for reactive styles with automatic unit handling.
  */
 export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
-export { useTime } from './utils/time';
-export { useTransform } from './utils/transform';
+export { useTime } from './utils/time.svelte';
+export { useTransform } from './utils/transform.svelte';
 export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';

package/dist/utils/attachable.js

@@ -1,3 +1,4 @@
+import { cancelMicrotask, microtask } from 'motion-dom';
 import { resolveElement } from './dom.js';
 /**
  * Builds a subscriber-refcounted DOM-attachment primitive. Both `useScroll`
@@ -27,17 +28,21 @@ import { resolveElement } from './dom.js';
  */
 export const createAttachable = (config) => {
     let cleanup;
-    let pollRaf = 0;
+    let pollScheduled = false;
     let subscriberCount = 0;
     // When stop() runs synchronously inside onAttach, cleanup hasn't been
     // assigned yet. Defer the teardown so the just-returned disposer still
     // gets invoked.
     let attaching = false;
     let stopRequestedDuringAttach = false;
+    const pollTick = () => {
+        pollScheduled = false;
+        tryAttach();
+    };
     const cancelPoll = () => {
-        if (pollRaf) {
-            cancelAnimationFrame(pollRaf);
-            pollRaf = 0;
+        if (pollScheduled) {
+            cancelMicrotask(pollTick);
+            pollScheduled = false;
         }
     };
     const stop = () => {
@@ -65,11 +70,11 @@ export const createAttachable = (config) => {
             els[key] = el;
         }
         if (needsPoll) {
-            if (!pollRaf) {
-                pollRaf = requestAnimationFrame(() => {
-                    pollRaf = 0;
-                    tryAttach();
-                });
+            // Microtask schedule (matches useScroll's pattern) — one frame
+            // faster than rAF for refs that hydrate the same tick.
+            if (!pollScheduled) {
+                pollScheduled = true;
+                microtask.read(pollTick);
             }
             return;
         }

package/dist/utils/augmentMotionValue.svelte.d.ts

@@ -0,0 +1,156 @@
+import { type MotionValue } from 'motion-dom';
+import { type Readable } from 'svelte/store';
+/**
+ * A motion-dom `MotionValue<T>` augmented with the two affordances every
+ * Tier-2 hook in this library exposes for Svelte 5 consumers:
+ *
+ * - `current` — a `$state`-backed reactive getter. Reads inside templates,
+ *   `$derived`, and `$effect` track changes automatically without going
+ *   through `.subscribe()`.
+ * - `subscribe(run)` — Svelte readable store contract. Calls `run(value)`
+ *   once synchronously on subscribe, then on every change. Lets the same
+ *   value drive `$value` template syntax, `svelte/store`'s `get()`, and
+ *   anything else that expects a readable.
+ *
+ * Every Wave 3 hook (`useMotionValue`, `useTransform`, `useScroll`,
+ * `useTime`, `useVelocity`, `useMotionTemplate`) and `useSpring` returns a
+ * value of this shape. The point is to keep one shared surface across all
+ * motion-value-producing hooks instead of repeating the wiring in each.
+ */
+export type AugmentedMotionValue<T> = Omit<MotionValue<T>, 'current'> & {
+    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
+    readonly current: T;
+    /** Svelte readable store compatibility. */
+    subscribe: (run: (value: T) => void) => () => void;
+};
+/**
+ * Detects a Svelte readable store, excluding motion-dom `MotionValue`
+ * instances (which also expose `subscribe`-shaped APIs in some versions).
+ * Used by hook factories that accept either a `MotionValue` or a readable
+ * store as a source.
+ *
+ * @template T The value type the readable emits.
+ * @param value Any value to test.
+ * @returns Whether the value is a Svelte readable (and not a `MotionValue`).
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ * import { motionValue } from 'motion-dom'
+ *
+ * isSvelteReadable(writable(0))  // true
+ * isSvelteReadable(motionValue(0))  // false (a MotionValue, not a readable)
+ * isSvelteReadable({ subscribe: 'nope' })  // false (subscribe isn't callable)
+ * ```
+ */
+export declare const isSvelteReadable: <T = unknown>(value: unknown) => value is Readable<T>;
+/**
+ * Synchronously samples a source: returns `T` directly, calls `.get()` on
+ * a `MotionValue`, or `svelte/store`'s `get()` on a readable. Used by hook
+ * factories to seed an initial value before any subscription is established.
+ *
+ * @template T The value type.
+ * @param source A plain value, a `MotionValue`, or a Svelte readable.
+ * @returns The current value of the source.
+ *
+ * @example
+ * ```ts
+ * sampleSource(42)               // 42
+ * sampleSource(motionValue(7))   // 7
+ * sampleSource(writable(11))     // 11
+ * ```
+ */
+export declare const sampleSource: <T>(source: T | MotionValue<T> | Readable<T>) => T;
+/**
+ * Layer Svelte 5 affordances onto a motion-dom `MotionValue`:
+ *
+ * 1. A `$state`-tracked `.current` accessor. motion-dom writes to its own
+ *    `current` field on every frame via an internal setter; we redirect that
+ *    setter through `$state` so templates and `$derived` / `$effect` re-run
+ *    automatically. Same-value writes are skipped (motion-dom can call the
+ *    setter at rest, and `$state` would itself dedupe, but the explicit
+ *    check avoids the extra accessor work).
+ *
+ * 2. A `.subscribe(run)` shim implementing the Svelte readable store
+ *    contract: synchronous initial emit, then re-emit on every change.
+ *    Forwarded to motion-dom's `.on('change', …)` event bus.
+ *
+ * 3. `.destroy()` is wrapped so a caller-supplied `dispose` runs once before
+ *    motion-dom's own teardown (and only once, guarded against re-entrant
+ *    or duplicate destroy calls).
+ *
+ * The returned reference is the same `MotionValue` passed in, only retyped —
+ * so identity checks (`isMotionValue`, `===`) still work and motion-dom's
+ * own machinery (animation, follow, composition) is untouched.
+ *
+ * **Call once per MotionValue.** This function mutates the value (rewrites
+ * `current`, `subscribe`, `destroy`). Calling it twice would re-define the
+ * accessors and the first call's `dispose` would be discarded.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param value The motion-dom `MotionValue` to augment.
+ * @param dispose Optional cleanup that runs once when `.destroy()` is first called (before motion-dom's internal teardown). Defaults to a no-op.
+ * @returns The same `MotionValue` typed as {@link AugmentedMotionValue}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motionValue } from 'motion-dom'
+ *   import { augmentMotionValue } from './augmentMotionValue.svelte.js'
+ *
+ *   const mv = motionValue(0)
+ *   const aug = augmentMotionValue(mv, () => console.log('disposed'))
+ *
+ *   $effect(() => () => aug.destroy())
+ * </script>
+ *
+ * <div style="transform: translateX({aug.current}px)">{aug.current}</div>
+ * ```
+ */
+export declare const augmentMotionValue: <T>(value: MotionValue<T>, dispose?: VoidFunction) => AugmentedMotionValue<T>;
+/**
+ * Bridges a Svelte `Readable<T>` into a motion-dom `MotionValue<T>` that
+ * mirrors the readable's emissions, so motion-dom primitives (`mapValue`,
+ * `transformValue`, `attachFollow`, `getVelocity`, etc.) that only accept
+ * `MotionValue` can track readable-shaped sources.
+ *
+ * The bridge:
+ * 1. Seeds via `get(source)` so the initial value is correct synchronously.
+ * 2. Subscribes to the readable, skipping the *synchronous initial emit*
+ *    (Svelte readables always fire one on subscribe, but the seed already
+ *    has it — without the skip the bridge would double-write on attach).
+ * 3. Optionally coerces each emit through `coerce` — useful for unit-string
+ *    sources (e.g. `"100px"` → `100`).
+ *
+ * Returns the bridge value and a `dispose` that tears down the subscription
+ * and destroys the bridge MV. Callers register `dispose` with their lifecycle
+ * ($effect cleanup or the augmented `destroy`'s `dispose` slot).
+ *
+ * @template TIn The readable's emit type (often `number | string`).
+ * @template TOut The bridge MotionValue's value type (often `number`).
+ * @param source A Svelte readable store.
+ * @param coerce Optional transform applied to each emit (and the initial seed). Identity by default.
+ * @returns A `MotionValue<TOut>` mirroring the readable + a dispose function.
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ *
+ * // Identity bridge — readable<number> → motionValue<number>
+ * const w = writable(0)
+ * const { value: mv, dispose } = bridgeReadableToMotionValue(w)
+ * w.set(50); mv.get() === 50
+ *
+ * // Coerce bridge — readable<string> → motionValue<number>
+ * const w2 = writable('100px')
+ * const bridge = bridgeReadableToMotionValue<string, number>(w2, parseFloat)
+ * bridge.value.get() === 100
+ *
+ * // Always pair with dispose() in your $effect cleanup.
+ * $effect(() => () => dispose())
+ * ```
+ */
+export declare const bridgeReadableToMotionValue: <TIn, TOut = TIn>(source: Readable<TIn>, coerce?: (v: TIn) => TOut) => {
+    value: MotionValue<TOut>;
+    dispose: VoidFunction;
+};

package/dist/utils/augmentMotionValue.svelte.js

@@ -0,0 +1,193 @@
+import { isMotionValue, motionValue } from 'motion-dom';
+import { get } from 'svelte/store';
+/**
+ * Detects a Svelte readable store, excluding motion-dom `MotionValue`
+ * instances (which also expose `subscribe`-shaped APIs in some versions).
+ * Used by hook factories that accept either a `MotionValue` or a readable
+ * store as a source.
+ *
+ * @template T The value type the readable emits.
+ * @param value Any value to test.
+ * @returns Whether the value is a Svelte readable (and not a `MotionValue`).
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ * import { motionValue } from 'motion-dom'
+ *
+ * isSvelteReadable(writable(0))  // true
+ * isSvelteReadable(motionValue(0))  // false (a MotionValue, not a readable)
+ * isSvelteReadable({ subscribe: 'nope' })  // false (subscribe isn't callable)
+ * ```
+ */
+export const isSvelteReadable = (value) => {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.subscribe === 'function' &&
+        !isMotionValue(value));
+};
+/**
+ * Synchronously samples a source: returns `T` directly, calls `.get()` on
+ * a `MotionValue`, or `svelte/store`'s `get()` on a readable. Used by hook
+ * factories to seed an initial value before any subscription is established.
+ *
+ * @template T The value type.
+ * @param source A plain value, a `MotionValue`, or a Svelte readable.
+ * @returns The current value of the source.
+ *
+ * @example
+ * ```ts
+ * sampleSource(42)               // 42
+ * sampleSource(motionValue(7))   // 7
+ * sampleSource(writable(11))     // 11
+ * ```
+ */
+export const sampleSource = (source) => {
+    if (isMotionValue(source))
+        return source.get();
+    if (isSvelteReadable(source))
+        return get(source);
+    return source;
+};
+/**
+ * Layer Svelte 5 affordances onto a motion-dom `MotionValue`:
+ *
+ * 1. A `$state`-tracked `.current` accessor. motion-dom writes to its own
+ *    `current` field on every frame via an internal setter; we redirect that
+ *    setter through `$state` so templates and `$derived` / `$effect` re-run
+ *    automatically. Same-value writes are skipped (motion-dom can call the
+ *    setter at rest, and `$state` would itself dedupe, but the explicit
+ *    check avoids the extra accessor work).
+ *
+ * 2. A `.subscribe(run)` shim implementing the Svelte readable store
+ *    contract: synchronous initial emit, then re-emit on every change.
+ *    Forwarded to motion-dom's `.on('change', …)` event bus.
+ *
+ * 3. `.destroy()` is wrapped so a caller-supplied `dispose` runs once before
+ *    motion-dom's own teardown (and only once, guarded against re-entrant
+ *    or duplicate destroy calls).
+ *
+ * The returned reference is the same `MotionValue` passed in, only retyped —
+ * so identity checks (`isMotionValue`, `===`) still work and motion-dom's
+ * own machinery (animation, follow, composition) is untouched.
+ *
+ * **Call once per MotionValue.** This function mutates the value (rewrites
+ * `current`, `subscribe`, `destroy`). Calling it twice would re-define the
+ * accessors and the first call's `dispose` would be discarded.
+ *
+ * @template T The value type — typically `number` or `string`.
+ * @param value The motion-dom `MotionValue` to augment.
+ * @param dispose Optional cleanup that runs once when `.destroy()` is first called (before motion-dom's internal teardown). Defaults to a no-op.
+ * @returns The same `MotionValue` typed as {@link AugmentedMotionValue}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { motionValue } from 'motion-dom'
+ *   import { augmentMotionValue } from './augmentMotionValue.svelte.js'
+ *
+ *   const mv = motionValue(0)
+ *   const aug = augmentMotionValue(mv, () => console.log('disposed'))
+ *
+ *   $effect(() => () => aug.destroy())
+ * </script>
+ *
+ * <div style="transform: translateX({aug.current}px)">{aug.current}</div>
+ * ```
+ */
+export const augmentMotionValue = (value, dispose = () => undefined) => {
+    // motion-dom's `.get()` returns `NonNullable<V>`, which would otherwise
+    // narrow `$state` to that and reject nullable-T setter writes. Cast to T
+    // so the state slot matches the public augmented signature; motion-dom's
+    // own contract guarantees it never sets a null/undefined frame value.
+    let current = $state(value.get());
+    Object.defineProperty(value, 'current', {
+        get: () => current,
+        set: (v) => {
+            if (v !== current)
+                current = v;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    const originalDestroy = value.destroy.bind(value);
+    let destroyed = false;
+    value.destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        dispose();
+        originalDestroy();
+    };
+    const subscribe = (run) => {
+        run(value.get());
+        return value.on('change', run);
+    };
+    Object.defineProperty(value, 'subscribe', {
+        value: subscribe,
+        writable: false,
+        enumerable: false,
+        configurable: true
+    });
+    return value;
+};
+/**
+ * Bridges a Svelte `Readable<T>` into a motion-dom `MotionValue<T>` that
+ * mirrors the readable's emissions, so motion-dom primitives (`mapValue`,
+ * `transformValue`, `attachFollow`, `getVelocity`, etc.) that only accept
+ * `MotionValue` can track readable-shaped sources.
+ *
+ * The bridge:
+ * 1. Seeds via `get(source)` so the initial value is correct synchronously.
+ * 2. Subscribes to the readable, skipping the *synchronous initial emit*
+ *    (Svelte readables always fire one on subscribe, but the seed already
+ *    has it — without the skip the bridge would double-write on attach).
+ * 3. Optionally coerces each emit through `coerce` — useful for unit-string
+ *    sources (e.g. `"100px"` → `100`).
+ *
+ * Returns the bridge value and a `dispose` that tears down the subscription
+ * and destroys the bridge MV. Callers register `dispose` with their lifecycle
+ * ($effect cleanup or the augmented `destroy`'s `dispose` slot).
+ *
+ * @template TIn The readable's emit type (often `number | string`).
+ * @template TOut The bridge MotionValue's value type (often `number`).
+ * @param source A Svelte readable store.
+ * @param coerce Optional transform applied to each emit (and the initial seed). Identity by default.
+ * @returns A `MotionValue<TOut>` mirroring the readable + a dispose function.
+ *
+ * @example
+ * ```ts
+ * import { writable } from 'svelte/store'
+ *
+ * // Identity bridge — readable<number> → motionValue<number>
+ * const w = writable(0)
+ * const { value: mv, dispose } = bridgeReadableToMotionValue(w)
+ * w.set(50); mv.get() === 50
+ *
+ * // Coerce bridge — readable<string> → motionValue<number>
+ * const w2 = writable('100px')
+ * const bridge = bridgeReadableToMotionValue<string, number>(w2, parseFloat)
+ * bridge.value.get() === 100
+ *
+ * // Always pair with dispose() in your $effect cleanup.
+ * $effect(() => () => dispose())
+ * ```
+ */
+export const bridgeReadableToMotionValue = (source, coerce = (v) => v) => {
+    const bridge = motionValue(coerce(get(source)));
+    let seenInitial = false;
+    const unsub = source.subscribe((v) => {
+        if (!seenInitial) {
+            seenInitial = true;
+            return;
+        }
+        bridge.set(coerce(v));
+    });
+    return {
+        value: bridge,
+        dispose: () => {
+            unsub();
+            bridge.destroy();
+        }
+    };
+};

package/dist/utils/booleanSnapshot.svelte.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared `{ current, subscribe }` shape returned by the Wave 2 boolean
+ * snapshot hooks — `useReducedMotion`, `useReducedMotionConfig`,
+ * `useInView`. `.current` is `$state`-backed; `.subscribe(run)` is the
+ * Svelte readable store contract preserved for legacy consumers during
+ * the Tier 2 migration.
+ */
+export type BooleanSnapshot = {
+    /** Reactive read in Svelte 5 templates / `$derived` / `$effect`. */
+    readonly current: boolean;
+    /** Svelte readable store contract — emits synchronously on subscribe. */
+    subscribe: (run: (value: boolean) => void) => () => void;
+};
+/**
+ * Build a `{ current, subscribe }` snapshot + an internal `set`
+ * function. Centralises the dedupe + subscriber-fanout that all three
+ * boolean-snapshot hooks need.
+ *
+ * Returns a tuple so consumers can hand the snapshot to callers while
+ * keeping `set` internal (it's not on the returned state object).
+ *
+ * Same-value writes via `set` are no-ops — saves a fanout call and
+ * means callers don't need their own change-detection guard.
+ *
+ * @param initial Starting value for the `current` cell.
+ * @returns A `[state, set]` tuple where `state` is the publicly-shared
+ *   `{ current, subscribe }` and `set` is the internal updater the hook
+ *   uses to push values from its event source.
+ *
+ * @example
+ * ```ts
+ * const [state, set] = createBooleanSnapshot(media.matches)
+ * media.addEventListener('change', (e) => set(e.matches))
+ * return state // { current, subscribe }
+ * ```
+ */
+export declare const createBooleanSnapshot: (initial: boolean) => [BooleanSnapshot, (value: boolean) => void];

package/dist/utils/booleanSnapshot.svelte.js

@@ -0,0 +1,48 @@
+import { SvelteSet } from 'svelte/reactivity';
+/**
+ * Build a `{ current, subscribe }` snapshot + an internal `set`
+ * function. Centralises the dedupe + subscriber-fanout that all three
+ * boolean-snapshot hooks need.
+ *
+ * Returns a tuple so consumers can hand the snapshot to callers while
+ * keeping `set` internal (it's not on the returned state object).
+ *
+ * Same-value writes via `set` are no-ops — saves a fanout call and
+ * means callers don't need their own change-detection guard.
+ *
+ * @param initial Starting value for the `current` cell.
+ * @returns A `[state, set]` tuple where `state` is the publicly-shared
+ *   `{ current, subscribe }` and `set` is the internal updater the hook
+ *   uses to push values from its event source.
+ *
+ * @example
+ * ```ts
+ * const [state, set] = createBooleanSnapshot(media.matches)
+ * media.addEventListener('change', (e) => set(e.matches))
+ * return state // { current, subscribe }
+ * ```
+ */
+export const createBooleanSnapshot = (initial) => {
+    let current = $state(initial);
+    const subscribers = new SvelteSet();
+    const state = {
+        get current() {
+            return current;
+        },
+        subscribe(run) {
+            subscribers.add(run);
+            run(current);
+            return () => {
+                subscribers.delete(run);
+            };
+        }
+    };
+    const set = (value) => {
+        if (value === current)
+            return;
+        current = value;
+        for (const sub of subscribers)
+            sub(value);
+    };
+    return [state, set];
+};

package/dist/utils/dom.d.ts

@@ -41,3 +41,16 @@ export type ElementOrGetter = HTMLElement | (() => HTMLElement | null | undefine
  * ```
  */
 export declare const resolveElement: (ref?: ElementOrGetter) => HTMLElement | undefined;
+/**
+ * Tests whether an `ElementOrGetter` is currently unresolved — defined as a
+ * getter that returns falsy. Direct element refs are never "pending" (they
+ * were already resolved at call time) and absent refs are not "pending"
+ * either (they're just absent).
+ *
+ * Lets microtask-defer / rAF-defer loops wait for refs to hydrate after
+ * `bind:this` settles on mount.
+ *
+ * @param ref Element or getter to check.
+ * @returns `true` only when `ref` is a getter and the getter currently returns falsy.
+ */
+export declare const isRefPending: (ref?: ElementOrGetter) => boolean;

package/dist/utils/dom.js

@@ -39,3 +39,22 @@ export const resolveElement = (ref) => {
     const value = typeof ref === 'function' ? ref() : ref;
     return value ?? undefined;
 };
+/**
+ * Tests whether an `ElementOrGetter` is currently unresolved — defined as a
+ * getter that returns falsy. Direct element refs are never "pending" (they
+ * were already resolved at call time) and absent refs are not "pending"
+ * either (they're just absent).
+ *
+ * Lets microtask-defer / rAF-defer loops wait for refs to hydrate after
+ * `bind:this` settles on mount.
+ *
+ * @param ref Element or getter to check.
+ * @returns `true` only when `ref` is a getter and the getter currently returns falsy.
+ */
+export const isRefPending = (ref) => {
+    if (!ref)
+        return false;
+    if (typeof ref !== 'function')
+        return false;
+    return !ref();
+};