@mkbabb/glass-ui 0.3.0 → 2.1.0

package/dist/composables/dom/useBreakpoint.d.ts

@@ -0,0 +1,38 @@
+import { type Ref } from "vue";
+export interface UseBreakpointControls {
+    /** Live `matches` state for the given media query. */
+    readonly matches: Readonly<Ref<boolean>>;
+    /** Tear down the `matchMedia` listener. Auto-called on scope dispose. */
+    stop: () => void;
+}
+/**
+ * `useBreakpoint(query)` — a reactive read of a CSS media query's `matches`
+ * state, kept live across resize / orientation / display-mode changes.
+ *
+ * Wraps `window.matchMedia(query)`, subscribes a single `change` handler,
+ * and mirrors `mql.matches` into a `Ref<boolean>`. Auto-cleans on Vue scope
+ * disposal (mirrors `useResizeObserver` / `useInterval` upstream); outside
+ * a scope callers use the returned `stop()` control.
+ *
+ * SSR-safe: when `window` is undefined the composable returns a
+ * permanently-`false` ref. Consumers should treat the initial frame as
+ * "mobile-first / narrow-default" because the matchMedia subscription only
+ * mounts client-side. This is the same shape consumers wrote by hand at the
+ * speedtest origin sites.
+ *
+ * Why this exists (speedtest origin, glass-ui promotion W6-β): the survey
+ * cockpit (`SurveyWizard.vue`) and the admin data-source toggle
+ * (`AdminDataSourceToggle.vue`) both hand-rolled the same `matchMedia`
+ * subscribe-on-mount + tear-down-on-unmount pattern. Two hand-rolls of one
+ * pattern is the `feedback_generic_components` 2-consumer trigger;
+ * absorbed publisher-side per `feedback_library_gaps`.
+ *
+ * Usage:
+ *   const { matches: isDesktop } = useBreakpoint("(min-width: 720px)");
+ *   const wide = isDesktop.value;  // live across resize.
+ *
+ * @param query A CSS `@media` query string, e.g. `"(min-width: 720px)"`.
+ * @returns Object with `matches: Ref<boolean>` and `stop()` for manual
+ *          disposal outside a Vue scope.
+ */
+export declare function useBreakpoint(query: string): UseBreakpointControls;

package/dist/composables/dom/useClipboard.d.ts

@@ -0,0 +1,45 @@
+import { type Ref } from "vue";
+export interface UseClipboardOptions {
+    /** Milliseconds before `copied` auto-resets to `false` (default 1500). */
+    resetMs?: number;
+}
+export interface UseClipboardReturn {
+    /** Reactive flag—flips `true` on successful copy, auto-resets after `resetMs`. */
+    copied: Ref<boolean>;
+    /** Copy `text` to the clipboard. Returns the success boolean. */
+    copy: (text: string) => Promise<boolean>;
+}
+/**
+ * Bare clipboard copy—stateless `Promise<boolean>` return, no reactive `copied`
+ * flag. P.W5 Lane A.1 (Path B) co-export paralleling the canonical
+ * `useClipboard()` composable. Use this when call sites manage their own
+ * confirmation state (e.g. hand-rolled `ref + setTimeout`) or in non-component
+ * contexts (utility modules, stores).
+ *
+ * The `resetMs` option is currently a no-op for the bare function (no reactive
+ * state to auto-reset); kept on the signature for forward-compatibility with
+ * future paired-callback hooks.
+ *
+ * @example
+ * import { copyToClipboard } from "@mkbabb/glass-ui";
+ *
+ * async function shareLink(url: string) {
+ *   const ok = await copyToClipboard(url);
+ *   if (ok) toast.show("Link copied");
+ * }
+ */
+export declare function copyToClipboard(text: string, _options?: UseClipboardOptions): Promise<boolean>;
+/**
+ * Reactive clipboard copy with auto-reset confirmation flag.
+ *
+ * @example
+ * const { copied, copy } = useClipboard();
+ * <button @click="copy(value)">
+ *   {{ copied ? "Copied" : "Copy" }}
+ * </button>
+ *
+ * @example
+ * // Custom reset window (e.g. for paired toast feedback):
+ * const { copied, copy } = useClipboard({ resetMs: 2000 });
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

package/dist/composables/dom/useResizeObserver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structural Ref shape — accepts the consumer's `Ref<T>` regardless of
+ * which `@vue/reactivity` package the brand symbol comes from. Glass-ui
+ * may sit at a different vue minor than the consumer, and Vue 3.5's
+ * `[RefSymbol]` phantom is nominal-by-package; structural-by-`.value`
+ * is the gestalt-correct contract for a consumer-facing API.
+ */
+type RefLike<T> = {
+    value: T;
+};
+export interface UseResizeObserverOptions {
+    /**
+     * Skip dispatch if every observed dimension delta is below this
+     * threshold (in CSS pixels). Helps dodge sub-pixel resize-drag storms.
+     * Default: 0.5.
+     */
+    threshold?: number;
+    /**
+     * Coalesce dispatch into the next animation frame. The most recent
+     * entry wins; older entries within the same frame are dropped.
+     * Default: true.
+     */
+    rafBatch?: boolean;
+    /** Forwarded to `ResizeObserver.observe`. Default: `"content-box"`. */
+    box?: ResizeObserverBoxOptions;
+}
+export interface UseResizeObserverControls {
+    /** Stop observing and disconnect the underlying observer. */
+    stop: () => void;
+}
+/**
+ * Vue-scope-aware ResizeObserver wrapper.
+ *
+ * Watches one element ref and fires a callback when its bounding box
+ * changes by more than `threshold` CSS pixels in either dimension.
+ * Dispatch coalesces through `requestAnimationFrame` by default so a
+ * caller wiring an expensive re-init (canvas DPR-resync, layout
+ * remeasure) doesn't pay for every drag-resize step.
+ *
+ * Safe to call outside setup/effect scopes. In a scope it auto-cleans
+ * on disposal; outside a scope callers use the returned `stop()`
+ * explicitly. Mirrors the auto-disposal pattern of `useTimer` and
+ * `useInterval` upstream.
+ *
+ * Usage:
+ *   const el = ref<HTMLElement | null>(null);
+ *   useResizeObserver(el, (rect) => recompute(rect));
+ */
+export declare function useResizeObserver<T extends Element>(target: RefLike<T | null>, callback: (rect: DOMRectReadOnly, entry: ResizeObserverEntry) => void, options?: UseResizeObserverOptions): UseResizeObserverControls;
+export {};

package/dist/composables/dom/useTokenColor.d.ts

@@ -0,0 +1,27 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+export interface UseTokenColorOptions {
+    /** Element to resolve the property against. Defaults to `<html>`. */
+    element?: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** Fallback when the property is unset or `document` is unavailable (SSR). */
+    fallback?: string;
+}
+export interface UseTokenColorControls {
+    /** Reactive resolved value. Trimmed; falls back to `options.fallback` when empty. */
+    value: Readonly<Ref<string>>;
+    /** Force a re-read of the property — useful after manual cascade mutations. */
+    refresh: () => void;
+}
+/**
+ * Read a CSS custom property as a reactive ref.
+ *
+ * The ref re-resolves automatically on dark-mode toggles via `useGlobalDark`
+ * and at mount. SSR returns the fallback.
+ *
+ * @example
+ * const stroke = useTokenColor("--meter-track-stroke", { fallback: "#ccc" });
+ * watch(stroke, (next) => repaintRingTrack(next));
+ *
+ * // With an element-scoped resolve (e.g. a themed container):
+ * const accent = useTokenColor("--accent", { element: panelEl });
+ */
+export declare function useTokenColor(token: MaybeRefOrGetter<string>, options?: UseTokenColorOptions): UseTokenColorControls;

package/dist/composables/dom/useTouchGate.d.ts

@@ -0,0 +1,18 @@
+import { type Ref } from "vue";
+export interface TouchGateReturn {
+    isActive: Ref<boolean>;
+    isTouchDevice: boolean;
+    handleTouchStart: (el: HTMLElement, clientY: number) => boolean;
+    handleScrollCheck: (event: TouchEvent) => void;
+    handleTouchEnd: () => void;
+    resetTimer: () => void;
+    deactivate: () => void;
+    suppressDeactivate: (suppress: boolean) => void;
+}
+/**
+ * Per-control tap-to-activate guard for mobile touch controls.
+ *
+ * Desktop pointers pass through immediately. On touch devices, the first tap
+ * activates the control unless it turns into a vertical scroll gesture.
+ */
+export declare function useTouchGate(deactivateDelayMs?: number): TouchGateReturn;

package/dist/composables/dom/useViewportReady.d.ts

@@ -0,0 +1,87 @@
+import { type Ref } from "vue";
+/**
+ * Structural Ref shape — accepts the consumer's `Ref<T>` regardless of which
+ * `@vue/reactivity` package the brand symbol comes from. Glass-ui may sit at
+ * a different vue minor than the consumer, and Vue 3.5's `[RefSymbol]`
+ * phantom is nominal-by-package; structural-by-`.value` is the correct
+ * contract for a consumer-facing API. Same shape `useResizeObserver` uses.
+ */
+type RefLike<T> = {
+    value: T;
+};
+export interface UseViewportReadyOptions {
+    /**
+     * IntersectionObserver `rootMargin`. Default `"200px"` so the gate flips
+     * before the host actually crosses the viewport edge — gives the
+     * consumer a quiet window for lazy-mount (`echarts`, `<canvas>` re-init,
+     * heavy widget hydration) to land off the LCP frame.
+     */
+    rootMargin?: string;
+    /**
+     * `requestIdleCallback` timeout, in ms. Default 10_000.
+     *
+     * Why 10s and not the conventional 1–2s: a cold-loading consumer (slow
+     * throughput, weak device) may not sustainably idle inside a 1–2s
+     * window — the timeout fires inside the LCP measurement window and
+     * defeats the IO gate's "wait for viewport AND idle main thread"
+     * semantic. The IO gate fronts the budget, so the timeout only fires
+     * after intersection has already resolved; ten seconds gives the main
+     * thread room to idle naturally.
+     */
+    idleTimeout?: number;
+    /**
+     * IntersectionObserver `threshold`. Default 0.01 (1 % visible). Mirrors
+     * the speedtest origin-site semantic — "any pixel visible counts".
+     */
+    threshold?: number;
+}
+export interface UseViewportReadyControls {
+    /** Flips `false → true` exactly once when the host is visible + idle. */
+    readonly ready: Ref<boolean>;
+    /** Tear down observer + idle handle. Auto-called on scope dispose. */
+    stop: () => void;
+}
+/**
+ * `useViewportReady(host)` — two-stage `IntersectionObserver` +
+ * `requestIdleCallback` gate that flips a `Ref<boolean>` exactly once when
+ * the host element has entered the viewport AND the main thread has idled.
+ *
+ * The intended use is lazy-mount of a heavy widget (echarts, leaflet,
+ * three.js, codemirror, custom canvas) that would otherwise pull its chunk
+ * into the first-paint critical path. The two-stage gate ensures:
+ *
+ *   1. Visibility-first — `IntersectionObserver` watches `host`. Until the
+ *      host crosses into the viewport (+ `rootMargin`), no fetch fires.
+ *   2. Idle-second — once visible, `requestIdleCallback` schedules the flip
+ *      so the chunk fetch waits for an idle main thread. Safari (no rIC)
+ *      falls back to `setTimeout(fire, 16)` — one frame later — so the
+ *      composition still defers past the IO callback's paint frame.
+ *
+ * The composable is one-shot: once the gate flips to `true` it disconnects
+ * its observer and clears any pending idle handle. Auto-cleans on Vue scope
+ * disposal (mirrors `useResizeObserver` / `useInterval` upstream); outside
+ * a scope callers receive the manual `stop()` control.
+ *
+ * Why this exists (speedtest origin, glass-ui promotion AJ.W6-α): both
+ * `AdminOverviewView` and `ChartsView` shipped a near-identical `chartReady`
+ * flag flipped by `requestIdleCallback` alone. The W3-R1 idiom in those
+ * sites — gate visibility first, then schedule rIC inside the IO callback —
+ * is generic across heavy-widget hydration; the speedtest 2-consumer trigger
+ * fired for a publisher-side absorption per `feedback_generic_components`.
+ *
+ * Usage:
+ *   const host = ref<HTMLElement | null>(null);
+ *   const { ready } = useViewportReady(host);
+ *   // <Chart v-if="ready" /> — fetched lazily once host is visible + idle.
+ *
+ * @param host A `Ref<Element | null>` for the element to gate visibility on.
+ *             The observer watches THIS element, not the lazy-mounted
+ *             widget (which doesn't exist pre-flip).
+ * @param options.rootMargin Default `"200px"`.
+ * @param options.idleTimeout Default `10000` ms.
+ * @param options.threshold   Default `0.01`.
+ * @returns Object with `ready: Ref<boolean>` (flips false → true once) and
+ *          `stop()` for manual disposal outside a Vue scope.
+ */
+export declare function useViewportReady(host: RefLike<Element | null>, options?: UseViewportReadyOptions): UseViewportReadyControls;
+export {};

package/dist/composables/glass/index.d.ts

@@ -0,0 +1 @@
+export { useGlassRenderer, createGlassFilter, destroyGlassFilter, type GlassTier, type GlassFilterState, } from "./useGlassRenderer";

package/dist/composables/glass/useGlassRenderer.d.ts

@@ -0,0 +1,37 @@
+export type GlassTier = "svg-filter" | "css" | "fallback";
+export interface GlassFilterState {
+    filterId: string;
+    svgEl: SVGSVGElement;
+    dispCanvas: HTMLCanvasElement;
+    specCanvas: HTMLCanvasElement;
+    observer: ResizeObserver | null;
+}
+/**
+ * Create an SVG filter for glass refraction + frost.
+ *
+ * Architecture (Chromium SVG displacement approach):
+ * 1. Hidden canvas generates Snell's law displacement map
+ * 2. Inline SVG <filter> references the canvas via <feImage>
+ * 3. <feDisplacementMap> warps the backdrop using R/G channels
+ * 4. CSS `backdrop-filter: url(#filterId) blur(Xpx) saturate(Y)` applies it
+ *
+ * This naturally composites with whatever is behind the element —
+ * no texture capture, no WebGL context, no scroll sync needed.
+ */
+export declare function createGlassFilter(el: HTMLElement, opts?: {
+    blur?: number;
+    refraction?: number;
+    chromaticAberration?: number;
+}): GlassFilterState;
+/**
+ * Remove a glass filter and clean up DOM elements.
+ */
+export declare function destroyGlassFilter(state: GlassFilterState): void;
+/**
+ * Composable for tiered glass rendering.
+ */
+export declare function useGlassRenderer(options?: {
+    preferredTier?: GlassTier;
+}): {
+    tier: import("vue").Ref<GlassTier, GlassTier>;
+};

package/dist/composables/glass/webgl/frostShader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * WebGL frost/refraction fragment shader for glass-ui.
+ *
+ * Features:
+ * - Frosted glass blur (Gaussian kernel with spatial variation)
+ * - Snell's law refraction displacement
+ * - Fresnel-based specular highlights
+ * - Chromatic aberration at glass edges
+ */
+/** Vertex shader — full-screen quad */
+export declare const VERTEX_SHADER = "#version 300 es\nprecision highp float;\n\nin vec2 a_position;\nin vec2 a_texCoord;\n\nout vec2 v_texCoord;\n\nvoid main() {\n    gl_Position = vec4(a_position, 0.0, 1.0);\n    v_texCoord = a_texCoord;\n}\n";
+/** Fragment shader — frosted glass with refraction and chromatic aberration */
+export declare const FRAGMENT_SHADER = "#version 300 es\nprecision highp float;\n\nuniform sampler2D u_background;    // Captured page content behind glass\nuniform vec2 u_resolution;         // Canvas resolution (px)\nuniform vec4 u_glassBounds;        // Glass panel rect (x, y, w, h) in UV space\nuniform float u_blurRadius;        // Base blur radius (0-40)\nuniform float u_refractionStrength; // Refraction displacement (0-1)\nuniform float u_chromaticAberration; // Edge chromatic aberration (0-1)\nuniform vec2 u_lightPos;           // Light source position (UV, 0-1)\nuniform float u_time;              // Animation time (seconds)\n\nin vec2 v_texCoord;\nout vec4 fragColor;\n\n// Gaussian weight for blur kernel\nfloat gaussian(float x, float sigma) {\n    return exp(-(x * x) / (2.0 * sigma * sigma));\n}\n\n// Distance from point to nearest edge of glass panel (in UV space)\nfloat edgeDistance(vec2 uv) {\n    vec2 glassMin = u_glassBounds.xy;\n    vec2 glassMax = u_glassBounds.xy + u_glassBounds.zw;\n    vec2 d = min(uv - glassMin, glassMax - uv);\n    return min(d.x, d.y);\n}\n\n// Fresnel approximation (Schlick)\nfloat fresnel(vec3 viewDir, vec3 normal, float ior) {\n    float r0 = pow((1.0 - ior) / (1.0 + ior), 2.0);\n    return r0 + (1.0 - r0) * pow(1.0 - max(dot(viewDir, normal), 0.0), 5.0);\n}\n\nvoid main() {\n    vec2 uv = v_texCoord;\n    vec2 pixelSize = 1.0 / u_resolution;\n\n    // Check if fragment is inside the glass panel\n    vec2 glassMin = u_glassBounds.xy;\n    vec2 glassMax = u_glassBounds.xy + u_glassBounds.zw;\n\n    if (uv.x < glassMin.x || uv.x > glassMax.x ||\n        uv.y < glassMin.y || uv.y > glassMax.y) {\n        fragColor = texture(u_background, uv);\n        return;\n    }\n\n    // Progressive blur \u2014 stronger at center, weaker at edges\n    float edgeDist = edgeDistance(uv);\n    float maxEdgeDist = min(u_glassBounds.z, u_glassBounds.w) * 0.5;\n    float blurFactor = smoothstep(0.0, maxEdgeDist * 0.3, edgeDist);\n    float effectiveBlur = u_blurRadius * (0.4 + 0.6 * blurFactor);\n\n    // Refraction displacement (Snell's law approximation)\n    vec2 center = u_glassBounds.xy + u_glassBounds.zw * 0.5;\n    vec2 fromCenter = uv - center;\n    vec2 refractionOffset = fromCenter * u_refractionStrength * 0.02;\n\n    // Gaussian blur with refraction offset\n    vec3 blurColor = vec3(0.0);\n    float totalWeight = 0.0;\n\n    int samples = int(min(effectiveBlur * 2.0, 20.0));\n    float sigma = max(effectiveBlur * 0.5, 0.1);\n\n    for (int x = -10; x <= 10; x++) {\n        for (int y = -10; y <= 10; y++) {\n            if (abs(x) > samples || abs(y) > samples) continue;\n\n            vec2 offset = vec2(float(x), float(y)) * pixelSize * effectiveBlur * 0.1;\n            float weight = gaussian(float(x), sigma) * gaussian(float(y), sigma);\n\n            vec2 sampleUV = uv + offset + refractionOffset;\n            blurColor += texture(u_background, sampleUV).rgb * weight;\n            totalWeight += weight;\n        }\n    }\n    blurColor /= totalWeight;\n\n    // Chromatic aberration at edges\n    if (u_chromaticAberration > 0.0) {\n        float edgeStrength = 1.0 - smoothstep(0.0, maxEdgeDist * 0.15, edgeDist);\n        vec2 aberrationDir = normalize(fromCenter) * edgeStrength * u_chromaticAberration * 0.003;\n\n        float r = texture(u_background, uv + refractionOffset + aberrationDir).r;\n        float b = texture(u_background, uv + refractionOffset - aberrationDir).b;\n        blurColor.r = mix(blurColor.r, r, edgeStrength * 0.5);\n        blurColor.b = mix(blurColor.b, b, edgeStrength * 0.5);\n    }\n\n    // Specular highlight (Fresnel)\n    vec3 viewDir = vec3(0.0, 0.0, 1.0);\n    vec2 normalXY = fromCenter / (u_glassBounds.zw * 0.5);\n    vec3 normal = normalize(vec3(normalXY * 0.3, 1.0));\n    float spec = fresnel(viewDir, normal, 1.5);\n\n    // Light-source-aware specular\n    vec2 lightDir = normalize(u_lightPos - uv);\n    float lightDot = max(dot(normalXY, lightDir), 0.0);\n    spec *= 0.3 + 0.7 * lightDot;\n\n    // Combine: frosted blur + specular + slight tint\n    vec3 tint = vec3(1.0, 1.0, 1.0); // neutral tint\n    vec3 result = blurColor * tint + vec3(spec * 0.15);\n\n    // Glass opacity with frosted appearance\n    float alpha = 0.85 + spec * 0.1;\n    fragColor = vec4(result, alpha);\n}\n";
+/** Shader program setup — compiles and links vertex + fragment shaders */
+export declare function createFrostProgram(gl: WebGL2RenderingContext | WebGLRenderingContext): WebGLProgram | null;
+/** Uniform locations cache for the frost program */
+export interface FrostUniforms {
+    u_background: WebGLUniformLocation | null;
+    u_resolution: WebGLUniformLocation | null;
+    u_glassBounds: WebGLUniformLocation | null;
+    u_blurRadius: WebGLUniformLocation | null;
+    u_refractionStrength: WebGLUniformLocation | null;
+    u_chromaticAberration: WebGLUniformLocation | null;
+    u_lightPos: WebGLUniformLocation | null;
+    u_time: WebGLUniformLocation | null;
+}
+export declare function getFrostUniforms(gl: WebGL2RenderingContext | WebGLRenderingContext, program: WebGLProgram): FrostUniforms;

package/dist/composables/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./dark";
+export * from "./keyboard";
+export * from "./reactive";
+export * from "./dom";
+export * from "./motion";
+export * from "./glass";
+export * from "./sortable";
+export * from "./sidebar";
+export * from "../components/custom/infinite-scroll/composables";

package/dist/composables/keyboard/index.d.ts

@@ -0,0 +1 @@
+export * from "./useKeyboardShortcuts";

package/dist/composables/keyboard/useKeyboardShortcuts.d.ts

@@ -0,0 +1,33 @@
+import { type ComputedRef } from "vue";
+export type ShortcutEventType = "keydown" | "keyup";
+export interface ShortcutOptions {
+    /** Fire even when focus is in input/textarea/contenteditable. Default: false */
+    allowInInput?: boolean;
+    /** Call preventDefault on the event. Default: false */
+    preventDefault?: boolean;
+    /** Human-readable label for the shortcuts modal */
+    label?: string;
+    /** Group name for display (e.g. "Playback", "Navigation") */
+    group?: string;
+    /** Keyboard event phase to match. Default: keydown */
+    event?: ShortcutEventType;
+}
+export interface RegisteredShortcut {
+    combo: ShortcutCombo;
+    raw: string;
+    handler: (e: KeyboardEvent) => void;
+    options: ShortcutOptions;
+}
+export interface ShortcutCombo {
+    key: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    alt: boolean;
+    mod: boolean;
+}
+export declare const isMac: boolean;
+export declare function formatComboParts(raw: string): string[];
+export declare function formatCombo(raw: string): string;
+export declare function registerShortcut(combo: string, handler: (e: KeyboardEvent) => void, options?: ShortcutOptions): () => void;
+export declare function useRegisteredShortcuts(): ComputedRef<RegisteredShortcut[]>;

package/dist/composables/motion/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared damping factors for live numeric motion.
+ *
+ * These values preserve the app-level tuning that used to live in
+ * speedtest's local animation utility while making glass-ui the owner of the
+ * generic motion contract.
+ */
+export declare const DAMPING: {
+    readonly canvasNeedle: 0.08;
+    readonly domHero: 0.12;
+    readonly domPill: 0.14;
+    readonly domProgress: 0.18;
+};
+/** Shared absolute snap thresholds for live numeric motion. */
+export declare const SNAP_THRESHOLD: {
+    readonly canvas: 0.002;
+    readonly dom: 0.05;
+    readonly domProgress: 0.5;
+};

package/dist/composables/motion/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./constants";
+export * from "./useSpring";
+export * from "./useSpringMount";
+export * from "./useSpringPress";
+export * from "./useNumericTransition";
+export * from "./useSpringOrchestrator";
+export * from "./useStaggerReveal";
+export * from "./useScrollProgress";
+export * from "./useAnimatedNumber";
+export * from "./useAnimatedNumberMap";
+export * from "./installDarkModeSync";
+export * from "./useRAFLoop";
+export * from "./useIntersectionPause";
+export * from "./useStagger";

package/dist/composables/motion/installDarkModeSync.d.ts

@@ -0,0 +1 @@
+export declare function installDarkModeSync(onSync: () => void): void;

package/dist/composables/motion/useAnimatedNumber.d.ts

@@ -0,0 +1,40 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+export type AnimatedNumberMode = "absolute" | "progress";
+export interface UseAnimatedNumberOptions {
+    /** Numeric contract. Progress mode accepts and clamps 0..100. Default absolute. */
+    mode?: AnimatedNumberMode;
+    /** SmoothProgress damping. Lower = smoother, higher = snappier. */
+    damping?: number;
+    /** Absolute-delta threshold below which current snaps to target. */
+    snapThreshold?: number;
+    /** Minimum target change accepted as noise filter. Default 0. */
+    targetEpsilon?: number;
+    /** Starting current value. Default 0. */
+    initial?: number;
+    /** Absolute-mode clamp to [0, 1]. Progress mode always clamps to [0, 100]. */
+    clamp?: boolean;
+    /** Respect prefers-reduced-motion with synchronous target snaps. Default true. */
+    respectReducedMotion?: boolean;
+    /** Per-frame side-effect hook. Receives the smoothed current value. */
+    onValue?: (value: number) => void;
+}
+export interface AnimatedNumber {
+    /** Reactive smoothed value. Bind in templates. */
+    current: Readonly<Ref<number>>;
+    /** True while the rAF loop is running and not settled. */
+    isAnimating: Readonly<Ref<boolean>>;
+    /** Force current to the target immediately and stop the loop. */
+    snap: () => void;
+    /** Reset current and target to `value` (default 0), then stop the loop. */
+    reset: (value?: number) => void;
+    /** Stop the smoother and target watcher. */
+    dispose: () => void;
+}
+/**
+ * Track a live numeric target with exponentially damped hysteresis.
+ *
+ * Wraps keyframes.js `SmoothProgress.play(onFrame)`. The engine owns rAF; this
+ * composable wires Vue reactivity, reduced-motion handling, and lifecycle
+ * cleanup.
+ */
+export declare function useAnimatedNumber(target: MaybeRefOrGetter<number | null | undefined>, options?: UseAnimatedNumberOptions): AnimatedNumber;

package/dist/composables/motion/useAnimatedNumberMap.d.ts

@@ -0,0 +1,29 @@
+import { type ComputedRef } from "vue";
+import { type UseAnimatedNumberOptions } from "./useAnimatedNumber";
+export interface UseAnimatedNumberMapOptions extends UseAnimatedNumberOptions {
+}
+/**
+ * Fan out N independent `useAnimatedNumber` instances into a `Record<K, ...>`.
+ *
+ * Each key gets one rAF-smoothed `ComputedRef<number | null>`. The smoothing
+ * options apply identically across the set; consumers that need per-key
+ * options should call `useAnimatedNumber` per key directly.
+ *
+ * The `null` propagation is preserved: when `source(key)` resolves to `null`,
+ * the corresponding ref returns `null` rather than freezing on the last
+ * smoothed sample. This matches the per-metric `raw → smoothed` contract.
+ *
+ * @example
+ * const keys = ["ping", "jitter", "download", "upload"] as const;
+ * const smoothed = useAnimatedNumberMap({
+ *     keys,
+ *     source: (k) => computed(() => store.resultFor(k).value ?? null),
+ *     damping: DAMPING.domPill,
+ *     snapThreshold: SNAP_THRESHOLD.dom,
+ * });
+ * // smoothed.ping.value, smoothed.jitter.value, ...
+ */
+export declare function useAnimatedNumberMap<K extends string>(options: {
+    keys: readonly K[];
+    source: (key: K) => ComputedRef<number | null>;
+} & UseAnimatedNumberMapOptions): Record<K, ComputedRef<number | null>>;

package/dist/composables/motion/useIntersectionPause.d.ts

@@ -0,0 +1,33 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+export interface PausableRuntime {
+    pause: () => void;
+    resume: () => void;
+}
+export interface UseIntersectionPauseOptions {
+    /** IntersectionObserver root. Default null (viewport). */
+    root?: Element | Document | null;
+    /** IntersectionObserver rootMargin. Default 0px. */
+    rootMargin?: string;
+    /** IntersectionObserver threshold. Default 0. */
+    threshold?: number | number[];
+    /** Pause while document.hidden is true. Default true. */
+    pauseWhenHidden?: boolean;
+}
+export interface IntersectionPauseControls {
+    /** Latest IntersectionObserver visible state. Defaults true until observed. */
+    readonly isIntersecting: Readonly<Ref<boolean>>;
+    /** Current document visibility state, SSR-safe default true. */
+    readonly isDocumentVisible: Readonly<Ref<boolean>>;
+    /** True when the runtime should be paused. */
+    readonly isPaused: Readonly<Ref<boolean>>;
+    /** Re-apply current intersection and visibility state to the runtime. */
+    refresh: () => void;
+    /** Disconnect observers and document listeners. */
+    dispose: () => void;
+}
+/**
+ * Pause a runtime while its target is outside the viewport or the document is
+ * hidden. Safe to call in SSR/tests; unavailable observers leave runtime state
+ * controlled by document visibility only.
+ */
+export declare function useIntersectionPause(target: MaybeRefOrGetter<Element | null | undefined>, runtime: PausableRuntime, options?: UseIntersectionPauseOptions): IntersectionPauseControls;

package/dist/composables/motion/useNumericTransition.d.ts

@@ -0,0 +1,32 @@
+import type { TimingFunction, TimingFunctionNames } from "@mkbabb/keyframes.js";
+export type SpringSnapshot<K extends string> = Record<K, number>;
+export interface UseNumericTransitionOptions<K extends string> {
+    /** Named numeric endpoints to interpolate between. */
+    from: SpringSnapshot<K>;
+    to: SpringSnapshot<K>;
+    /** Playback duration in ms. */
+    duration: number;
+    /** keyframes.js timing function — string name or explicit function. */
+    timingFunction?: TimingFunction | TimingFunctionNames;
+    /** Per-frame consumer. Receives the same zero-allocation record each tick. */
+    onFrame?: (values: SpringSnapshot<K>) => void;
+}
+/**
+ * Drive a numeric transition between two snapshots — e.g. CSS variable
+ * values, element transforms, or color channel tuples. Wraps keyframes.js's
+ * `NumericAnimation`, which handles easing, binary-search segment lookup,
+ * and zero-allocation playback.
+ *
+ * The caller owns how values map to the DOM: provide `onFrame` and write
+ * the record into `element.style.setProperty`, a `ref`, or wherever. This
+ * composable never touches the DOM directly — it's the orchestrator, not
+ * the renderer.
+ *
+ * For physics-based motion (mass / stiffness / damping), use `useSpring`.
+ */
+export declare function useNumericTransition<K extends string>(options: UseNumericTransitionOptions<K>): {
+    start: () => Promise<void>;
+    stop: () => void;
+    progress: import("vue").Ref<number, number>;
+    playing: import("vue").Ref<boolean, boolean>;
+};

package/dist/composables/motion/useRAFLoop.d.ts

@@ -0,0 +1,43 @@
+import { type Ref } from "vue";
+export interface RAFLoopTiming {
+    /** Current frame timestamp from requestAnimationFrame. */
+    now: number;
+    /** Milliseconds since the previous delivered frame. First frame is 0. */
+    delta: number;
+    /** Accumulated running time, excluding paused time. */
+    elapsed: number;
+    /** Delivered frame count since the last start(), zero-based. */
+    frame: number;
+}
+export type RAFLoopCallback = (timing: RAFLoopTiming) => void;
+export interface UseRAFLoopOptions {
+    /** Start the loop immediately. Default true. */
+    immediate?: boolean;
+    /** Stop scheduling frames while document.hidden is true. Default true. */
+    pauseWhenHidden?: boolean;
+    /** Honor prefers-reduced-motion by pausing the loop. Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface RAFLoopControls {
+    /** True while a frame is scheduled or being delivered. */
+    readonly isActive: Readonly<Ref<boolean>>;
+    /** True when the loop was requested but is paused by controls or environment. */
+    readonly isPaused: Readonly<Ref<boolean>>;
+    /** Current prefers-reduced-motion state when monitored. */
+    readonly isReducedMotion: Readonly<Ref<boolean>>;
+    /** Request frame delivery, resetting elapsed/frame counters. */
+    start: () => void;
+    /** Stop frame delivery and clear elapsed/frame counters. */
+    stop: () => void;
+    /** Temporarily pause frame delivery without clearing counters. */
+    pause: () => void;
+    /** Resume a paused loop if start() has been requested. */
+    resume: () => void;
+    /** Stop the loop and detach document/media listeners. */
+    dispose: () => void;
+}
+/**
+ * Scope-aware requestAnimationFrame loop with manual controls plus document
+ * visibility and reduced-motion gates.
+ */
+export declare function useRAFLoop(callback: RAFLoopCallback, options?: UseRAFLoopOptions): RAFLoopControls;

package/dist/composables/motion/useScrollProgress.d.ts

@@ -0,0 +1,23 @@
+import type { MaybeRef, Ref } from "vue";
+interface ScrollProgressConfig {
+    /** Element whose vertical position maps to 0..1. */
+    target: MaybeRef<HTMLElement | null>;
+    /** Pixel offset added to the mapped start. Negative values start earlier. */
+    offset?: number;
+    /**
+     * When true, progress reaches 1 at the target's bottom rather than its
+     * top. Default false — progress is 0 when target top is at viewport
+     * bottom, 1 when target top reaches viewport top.
+     */
+    trackExit?: boolean;
+}
+/**
+ * Map a target element's scroll position in the viewport to a reactive
+ * `Ref<number>` in [0, 1]. Drives things like scroll-linked typography
+ * axes, parallax depth, or progress indicators.
+ *
+ * Uses a rAF-coalesced scroll listener plus ResizeObserver so the mapping
+ * stays accurate when layout shifts.
+ */
+export declare function useScrollProgress(options: ScrollProgressConfig): Ref<number>;
+export {};