solid-drift 0.12.0 → 0.13.0

package/README.md

@@ -1130,13 +1130,28 @@ success("Payment sent", { description: "0.5 SOL to alice.sol" })
 
 Push helpers: `toast(title, options?)`, `info(...)`, `success(...)`, `warning(...)`, `error(...)`. Each returns the toast id. Per-toast options: `kind`, `description`, `duration` (ms; `0` means sticky). `dismiss(id)` starts the leave transition for one toast; `clear()` dismisses all. SSR-safe: toasts pushed on the server start `"visible"`. Under reduced motion the enter and leave transitions are instant, but auto-dismiss timing still applies.
 
+### `useLowPowerMode(options?)`
+
+One reactive signal for mobile-first degradation. It combines the OS `prefers-reduced-motion` and `prefers-reduced-data` media queries with low-end device signals (`navigator.deviceMemory`, `navigator.hardwareConcurrency`), so a single check covers user preference, network thrift, and weak hardware. The media queries update live; the device signals are sampled once. There is also a one-shot `isLowPowerMode(options?)` for non-reactive checks.
+
+```tsx
+import { useLowPowerMode } from "solid-drift"
+
+const lowPower = useLowPowerMode()
+// Degrade gracefully: shorter, cheaper motion on weak devices.
+const duration = () => (lowPower() ? 0 : 400)
+const confettiCount = () => (lowPower() ? 20 : 150)
+```
+
+Options: `maxDeviceMemory` (GB, default `4`), `maxHardwareConcurrency` (default `4`): a device at or below either threshold counts as low-end. Where the device signals are unsupported they degrade to "not low-end". SSR-safe: always `false` on the server.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.
 
 ## How it works
 
-One shared `requestAnimationFrame` loop drives every animation in the app, so hundreds of springs cost a single rAF tick per frame. Springs integrate with semi-implicit Euler, tweens sample an easing curve. Everything is SSR-safe (animations simply don't run on the server).
+One shared `requestAnimationFrame` loop drives every animation in the app, so hundreds of springs cost a single rAF tick per frame. Springs integrate with semi-implicit Euler, tweens sample an easing curve. When the tab becomes hidden the engine pauses the loop and freezes its clock, so nothing burns battery in the background; on return the clock continues where it left off and in-flight animations resume seamlessly. Everything is SSR-safe (animations simply don't run on the server).
 
 ## License
 

package/dist/engine.d.ts

@@ -4,6 +4,11 @@
  * A single requestAnimationFrame loop drives every active animation in the
  * app, so hundreds of springs and tweens cost exactly one rAF tick per frame.
  * Tasks return `false` when finished and are removed automatically.
+ *
+ * Battery saving: when the tab becomes hidden the loop stops and the clock
+ * freezes, so no animation burns CPU in the background. When the tab is
+ * visible again the loop resumes and the clock continues where it left off,
+ * so in-flight animations continue seamlessly instead of jumping forward.
  */
 export type AnimationTask = (now: number) => boolean;
 /**
@@ -11,5 +16,8 @@ export type AnimationTask = (now: number) => boolean;
  * Safe to call during SSR (no-op without requestAnimationFrame).
  */
 export declare function schedule(task: AnimationTask): () => void;
-/** Monotonic clock in milliseconds. */
+/**
+ * Monotonic clock in milliseconds. Freezes while the tab is hidden and
+ * resumes where it left off, so animations never observe the hidden gap.
+ */
 export declare function now(): number;

package/dist/engine.js

@@ -4,14 +4,31 @@
  * A single requestAnimationFrame loop drives every active animation in the
  * app, so hundreds of springs and tweens cost exactly one rAF tick per frame.
  * Tasks return `false` when finished and are removed automatically.
+ *
+ * Battery saving: when the tab becomes hidden the loop stops and the clock
+ * freezes, so no animation burns CPU in the background. When the tab is
+ * visible again the loop resumes and the clock continues where it left off,
+ * so in-flight animations continue seamlessly instead of jumping forward.
  */
 const tasks = new Set();
 let rafId = 0;
-function tick(now) {
+// Milliseconds of hidden time subtracted from the raw clock, so now()
+// freezes while the tab is hidden and resumes seamlessly on return.
+let pausedMs = 0;
+// Raw timestamp of the moment the tab was hidden, or null while visible.
+let hiddenAt = null;
+let visibilityHooked = false;
+function rawNow() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function tick() {
+    // Tasks always see the pause-adjusted clock, never the raw rAF stamp,
+    // so a hidden-then-visible gap never shows up as a time jump.
+    const t = now();
     for (const task of tasks) {
         let alive = false;
         try {
-            alive = task(now);
+            alive = task(t);
         }
         catch {
             alive = false;
@@ -21,6 +38,39 @@ function tick(now) {
     }
     rafId = tasks.size > 0 ? requestAnimationFrame(tick) : 0;
 }
+function onVisibilityChange() {
+    if (typeof document === "undefined")
+        return;
+    if (document.hidden) {
+        if (hiddenAt === null) {
+            hiddenAt = rawNow();
+            if (rafId) {
+                if (typeof cancelAnimationFrame !== "undefined") {
+                    cancelAnimationFrame(rafId);
+                }
+                rafId = 0;
+            }
+        }
+    }
+    else if (hiddenAt !== null) {
+        pausedMs += rawNow() - hiddenAt;
+        hiddenAt = null;
+        if (tasks.size > 0 &&
+            !rafId &&
+            typeof requestAnimationFrame !== "undefined") {
+            rafId = requestAnimationFrame(tick);
+        }
+    }
+}
+function hookVisibility() {
+    if (visibilityHooked)
+        return;
+    visibilityHooked = true;
+    if (typeof document !== "undefined" &&
+        typeof document.addEventListener === "function") {
+        document.addEventListener("visibilitychange", onVisibilityChange);
+    }
+}
 /**
  * Register a task on the shared clock. Returns a cancel function.
  * Safe to call during SSR (no-op without requestAnimationFrame).
@@ -28,14 +78,19 @@ function tick(now) {
 export function schedule(task) {
     if (typeof requestAnimationFrame === "undefined")
         return () => { };
+    hookVisibility();
     tasks.add(task);
-    if (!rafId)
+    const hidden = typeof document !== "undefined" && document.hidden === true;
+    if (!rafId && !hidden)
         rafId = requestAnimationFrame(tick);
     return () => {
         tasks.delete(task);
     };
 }
-/** Monotonic clock in milliseconds. */
+/**
+ * Monotonic clock in milliseconds. Freezes while the tab is hidden and
+ * resumes where it left off, so animations never observe the hidden gap.
+ */
 export function now() {
-    return typeof performance !== "undefined" ? performance.now() : Date.now();
+    return (hiddenAt ?? rawNow()) - pausedMs;
 }

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { drift, type DriftProps } from "./directive.js";
 export { createScrollProgress, type ScrollTarget } from "./scroll.js";
 export { createInView, type InViewOptions } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
+export { isLowPowerMode, useLowPowerMode, type LowPowerOptions, } from "./power.js";
 export { createStagger } from "./stagger.js";
 export { createHorizontalScroll, type HorizontalScrollOptions, type HorizontalScrollResult, } from "./horizontal.js";
 export { createScrub, type ScrubKeyframe, type ScrubOptions } from "./scrub.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { drift } from "./directive.js";
 export { createScrollProgress } from "./scroll.js";
 export { createInView } from "./inview.js";
 export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion.js";
+export { isLowPowerMode, useLowPowerMode, } from "./power.js";
 export { createStagger } from "./stagger.js";
 export { createHorizontalScroll, } from "./horizontal.js";
 export { createScrub } from "./scrub.js";

package/dist/power.d.ts

@@ -0,0 +1,44 @@
+import { type Accessor } from "solid-js";
+export interface LowPowerOptions {
+    /** deviceMemory in GB at or below which the device counts as low-end. Default 4. */
+    maxDeviceMemory?: number;
+    /** hardwareConcurrency at or below which the device counts as low-end. Default 4. */
+    maxHardwareConcurrency?: number;
+}
+/**
+ * Non-reactive check: should the app conserve power and motion right now?
+ *
+ * True when any of these hold: the OS prefers reduced motion, the user
+ * asked to reduce data usage, or the device looks low-end (small
+ * deviceMemory or few CPU cores, both Chrome-only signals that degrade
+ * to "not low-end" where unsupported).
+ *
+ * SSR-safe: always `false` on the server. Pair with the reduced-motion
+ * behavior of the primitives: when this is true, prefer shorter or
+ * zero durations and skip decorative motion.
+ *
+ * ```ts
+ * if (isLowPowerMode()) {
+ *   // skip the ambient background animation
+ * }
+ * ```
+ */
+export declare function isLowPowerMode(options?: LowPowerOptions): boolean;
+/**
+ * Reactive low-power signal for mobile-first degradation.
+ *
+ * Combines `prefers-reduced-motion`, `prefers-reduced-data`, and low-end
+ * device signals into one accessor. The media queries update live if the
+ * OS preference changes while the app is running; the device signals are
+ * sampled once. SSR-safe: `false` on the server.
+ *
+ * ```tsx
+ * import { isLowPowerMode, useLowPowerMode } from "solid-drift"
+ *
+ * const lowPower = useLowPowerMode()
+ * // Degrade gracefully: shorter, cheaper motion on weak devices.
+ * const duration = () => (lowPower() ? 0 : 400)
+ * const confettiCount = () => (lowPower() ? 20 : 150)
+ * ```
+ */
+export declare function useLowPowerMode(options?: LowPowerOptions): Accessor<boolean>;

package/dist/power.js

@@ -0,0 +1,83 @@
+import { createSignal, onCleanup } from "solid-js";
+const MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+const DATA_QUERY = "(prefers-reduced-data: reduce)";
+function mediaMatches(query) {
+    return (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia(query).matches);
+}
+function isLowEndDevice(options) {
+    if (typeof navigator === "undefined")
+        return false;
+    const { maxDeviceMemory = 4, maxHardwareConcurrency = 4 } = options;
+    const memory = typeof navigator.deviceMemory ===
+        "number"
+        ? navigator.deviceMemory
+        : Infinity;
+    const cores = typeof navigator.hardwareConcurrency === "number"
+        ? navigator.hardwareConcurrency
+        : Infinity;
+    return memory <= maxDeviceMemory || cores <= maxHardwareConcurrency;
+}
+function checkLowPower(options) {
+    return (mediaMatches(MOTION_QUERY) ||
+        mediaMatches(DATA_QUERY) ||
+        isLowEndDevice(options));
+}
+/**
+ * Non-reactive check: should the app conserve power and motion right now?
+ *
+ * True when any of these hold: the OS prefers reduced motion, the user
+ * asked to reduce data usage, or the device looks low-end (small
+ * deviceMemory or few CPU cores, both Chrome-only signals that degrade
+ * to "not low-end" where unsupported).
+ *
+ * SSR-safe: always `false` on the server. Pair with the reduced-motion
+ * behavior of the primitives: when this is true, prefer shorter or
+ * zero durations and skip decorative motion.
+ *
+ * ```ts
+ * if (isLowPowerMode()) {
+ *   // skip the ambient background animation
+ * }
+ * ```
+ */
+export function isLowPowerMode(options = {}) {
+    return checkLowPower(options);
+}
+/**
+ * Reactive low-power signal for mobile-first degradation.
+ *
+ * Combines `prefers-reduced-motion`, `prefers-reduced-data`, and low-end
+ * device signals into one accessor. The media queries update live if the
+ * OS preference changes while the app is running; the device signals are
+ * sampled once. SSR-safe: `false` on the server.
+ *
+ * ```tsx
+ * import { isLowPowerMode, useLowPowerMode } from "solid-drift"
+ *
+ * const lowPower = useLowPowerMode()
+ * // Degrade gracefully: shorter, cheaper motion on weak devices.
+ * const duration = () => (lowPower() ? 0 : 400)
+ * const confettiCount = () => (lowPower() ? 20 : 150)
+ * ```
+ */
+export function useLowPowerMode(options = {}) {
+    const lowEnd = isLowEndDevice(options);
+    const [lowPower, setLowPower] = createSignal(checkLowPower(options));
+    if (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function") {
+        const motionMq = window.matchMedia(MOTION_QUERY);
+        const dataMq = window.matchMedia(DATA_QUERY);
+        const onChange = () => {
+            setLowPower(lowEnd || motionMq.matches || dataMq.matches);
+        };
+        motionMq.addEventListener("change", onChange);
+        dataMq.addEventListener("change", onChange);
+        onCleanup(() => {
+            motionMq.removeEventListener("change", onChange);
+            dataMq.removeEventListener("change", onChange);
+        });
+    }
+    return lowPower;
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.12.0"
+  "version": "0.13.0"
 }