@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/backgrounds/runtime/color.js

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// Canvas and WebGL cannot read CSS variables, so colours like
+// `var(--color-sx-accent)` or `color-mix(...)` are resolved to numbers once
+// (and again when the theme changes). `parseRgb` is pure (tested); the
+// resolver needs a browser.
+// ---------------------------------------------------------------------------
+/** Parses `rgb(…)` / `rgba(…)` in both comma and space syntax. Null for anything else. */
+export function parseRgb(css) {
+    const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)$/i.exec(css.trim());
+    if (!m)
+        return null;
+    const alpha = m[4] === undefined ? 1 : Number(m[4]) / (m[5] ? 100 : 1);
+    return [Number(m[1]), Number(m[2]), Number(m[3]), Math.min(1, Math.max(0, alpha))];
+}
+/** A canvas fill string, with the colour's own alpha multiplied by `alpha`. */
+export function rgba(c, alpha = 1) {
+    return `rgba(${c[0]}, ${c[1]}, ${c[2]}, ${Math.round(c[3] * alpha * 1000) / 1000})`;
+}
+/**
+ * Resolves any CSS colour, var() included, in the context of `host` (so the
+ * host's theme applies). The browser computes it on a hidden probe; anything
+ * it does not report as rgb() (oklch, color(srgb …)) goes through a 1×1 canvas,
+ * which returns sRGB bytes for every colour syntax the browser knows.
+ */
+export function createColorResolver(host) {
+    const probe = document.createElement("span");
+    probe.style.display = "none";
+    host.appendChild(probe);
+    let ctx = null;
+    return {
+        resolve(css) {
+            probe.style.color = "";
+            probe.style.color = css;
+            const computed = getComputedStyle(probe).color;
+            const direct = parseRgb(computed);
+            if (direct)
+                return direct;
+            ctx ?? (ctx = document.createElement("canvas").getContext("2d", { willReadFrequently: true }));
+            if (!ctx)
+                return [0, 0, 0, 1];
+            ctx.canvas.width = 1;
+            ctx.canvas.height = 1;
+            ctx.clearRect(0, 0, 1, 1);
+            ctx.fillStyle = computed;
+            ctx.fillRect(0, 0, 1, 1);
+            const d = ctx.getImageData(0, 0, 1, 1).data;
+            return [d[0] ?? 0, d[1] ?? 0, d[2] ?? 0, (d[3] ?? 255) / 255];
+        },
+        dispose() {
+            probe.remove();
+        },
+    };
+}
+/**
+ * Calls `listener` when the theme may have changed: the colour scheme, or the
+ * `class` / `data-theme` / `style` of <html> (how sites switch themes).
+ * Returns the stop function.
+ */
+export function watchTheme(listener) {
+    const scheme = matchMedia("(prefers-color-scheme: dark)");
+    scheme.addEventListener("change", listener);
+    const observer = new MutationObserver(listener);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] });
+    return () => {
+        scheme.removeEventListener("change", listener);
+        observer.disconnect();
+    };
+}

package/dist/backgrounds/runtime/context.d.ts

@@ -0,0 +1,43 @@
+import { type RefObject } from "react";
+import type { BackgroundConfig } from "../config.js";
+import type { CanvasPointer, DeviceTier } from "../types.js";
+import type { ScrollState } from "./scroll.js";
+/**
+ * What every layer under a `Background.Root` shares. Everything that changes
+ * per frame or per scroll is a ref or a subscription, never React state, so a
+ * layer re-renders only when the tier or the config changes.
+ */
+export interface BackgroundRuntime {
+    readonly config: BackgroundConfig;
+    /** The resolved device tier (`quality`, or the detected one under `auto`). */
+    readonly tier: DeviceTier;
+    readonly root: RefObject<HTMLDivElement | null>;
+    /** On screen (or `pauseOffscreen` off) and the tab is visible. Read it; don't render from it. */
+    readonly visible: {
+        readonly current: boolean;
+    };
+    /** Called whenever `visible` flips. Returns an unsubscribe function. */
+    onVisibility(listener: (visible: boolean) => void): () => void;
+    /**
+     * Start writing the pointer position on the root (`--sx-pointer-x/y` in px,
+     * `--sx-pointer-nx/ny` 0–1, `data-sx-pointer="in" | "out"`). Reference
+     * counted; returns the release function.
+     */
+    trackPointer(): () => void;
+    /** The pointer as numbers (root px), kept current while anything tracks it. Read it; don't hold copies. */
+    readonly pointer: CanvasPointer;
+    /** Taps / clicks that land inside the root (root px), while anything tracks the pointer. Returns an unsubscribe function. */
+    onTap(listener: (x: number, y: number) => void): () => void;
+    /**
+     * Start writing the root's scroll progress (`--sx-scroll`, `--sx-scroll-exit`,
+     * both 0–1; see `ScrollState`). Reference counted; returns the release function.
+     */
+    trackScroll(): () => void;
+    /** The scroll progress as numbers, kept current while anything tracks it. Read it; don't hold copies. */
+    readonly scroll: Readonly<ScrollState>;
+    /** Called after `scroll` changes. Returns an unsubscribe function. */
+    onScroll(listener: () => void): () => void;
+}
+export declare const BackgroundRuntimeContext: import("react").Context<BackgroundRuntime | null>;
+/** The runtime of the nearest `Background.Root`. For custom effects and hosts. */
+export declare function useBackgroundRuntime(part?: string): BackgroundRuntime;

package/dist/backgrounds/runtime/context.js

@@ -0,0 +1,11 @@
+"use client";
+import { createContext, useContext } from "react";
+export const BackgroundRuntimeContext = createContext(null);
+/** The runtime of the nearest `Background.Root`. For custom effects and hosts. */
+export function useBackgroundRuntime(part = "useBackgroundRuntime") {
+    const runtime = useContext(BackgroundRuntimeContext);
+    if (!runtime) {
+        throw new Error(`[@sharedex/ui] ${part} must be rendered inside <Background.Root>.`);
+    }
+    return runtime;
+}

package/dist/backgrounds/runtime/hooks.d.ts

@@ -0,0 +1,57 @@
+import { type RefObject } from "react";
+import type { BackgroundConfig } from "../config.js";
+import type { DeviceTier } from "../types.js";
+import { type ScrollState } from "./scroll.js";
+/**
+ * The device tier. Under `auto` the first render (and the server render) says
+ * `low`, so heavier effects start on their fallback and upgrade after mount:
+ * no blank frame, no hydration mismatch.
+ */
+export declare function useDeviceTier(quality: BackgroundConfig["quality"]): DeviceTier;
+export interface Visibility {
+    readonly visible: {
+        current: boolean;
+    };
+    readonly subscribe: (listener: (visible: boolean) => void) => () => void;
+}
+/**
+ * Off screen or in a hidden tab -> `data-sx-paused` on the root (CSS
+ * animations stop) and listeners are told (JS layers stop their loops).
+ */
+export declare function useVisibility(root: RefObject<HTMLDivElement | null>, pauseOffscreen: boolean): Visibility;
+/** The live pointer, in root coordinates (px). Mutated in place, never replaced. */
+export interface PointerState {
+    x: number;
+    y: number;
+    inside: boolean;
+}
+/**
+ * Pointer position as CSS variables on the root (for CSS effects) and as
+ * numbers in `pointer` (for canvas / WebGL), at most once per frame, on
+ * motion's frame loop. One window listener however many layers ask for it.
+ */
+export declare function usePointerTracking(root: RefObject<HTMLDivElement | null>, visible: {
+    readonly current: boolean;
+}): {
+    readonly track: () => () => void;
+    readonly pointer: PointerState;
+    /** Taps / clicks inside the root (root px), while anything tracks the pointer. */
+    readonly onTap: (listener: (x: number, y: number) => void) => () => void;
+};
+export interface ScrollTracking {
+    readonly track: () => () => void;
+    /** Mutated in place, never replaced. */
+    readonly scroll: ScrollState;
+    /** Called after `scroll` changes. Returns an unsubscribe function. */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/**
+ * The root's scroll progress as `--sx-scroll` / `--sx-scroll-exit` on the root
+ * (for CSS effects) and as numbers in `scroll` (for JS layers), at most once per
+ * frame. Listens in the capture phase, so a page that scrolls an inner
+ * container works too. Skips work while the root is off screen, measures again
+ * when it comes back. Under reduced motion `still` it holds `RESTING_SCROLL`.
+ */
+export declare function useScrollTracking(root: RefObject<HTMLDivElement | null>, visible: {
+    readonly current: boolean;
+}, onVisibility: (listener: (visible: boolean) => void) => () => void, reducedMotion: BackgroundConfig["reducedMotion"]): ScrollTracking;

package/dist/backgrounds/runtime/hooks.js

@@ -0,0 +1,240 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { cancelFrame, frame } from "motion/react";
+import { classifyTier, readTierSignals } from "./tier.js";
+import { RESTING_SCROLL, scrollProgress } from "./scroll.js";
+// ---------------------------------------------------------------------------
+// The runtime's jobs that touch the browser: device tier, visibility,
+// pointer, scroll. Each writes the DOM directly; none causes a React render per event.
+// ---------------------------------------------------------------------------
+/** Detected once per page: reading it creates a throwaway WebGL context. */
+let detectedTier;
+/**
+ * The device tier. Under `auto` the first render (and the server render) says
+ * `low`, so heavier effects start on their fallback and upgrade after mount:
+ * no blank frame, no hydration mismatch.
+ */
+export function useDeviceTier(quality) {
+    const [tier, setTier] = useState(quality === "auto" ? (detectedTier ?? "low") : quality);
+    useEffect(() => {
+        if (quality !== "auto") {
+            setTier(quality);
+            return;
+        }
+        detectedTier ?? (detectedTier = classifyTier(readTierSignals()));
+        setTier(detectedTier);
+    }, [quality]);
+    return tier;
+}
+/**
+ * Off screen or in a hidden tab -> `data-sx-paused` on the root (CSS
+ * animations stop) and listeners are told (JS layers stop their loops).
+ */
+export function useVisibility(root, pauseOffscreen) {
+    const visible = useRef(true);
+    const listeners = useRef(new Set());
+    useEffect(() => {
+        const el = root.current;
+        if (!el)
+            return;
+        let onScreen = true;
+        const apply = () => {
+            const next = (!pauseOffscreen || onScreen) && !document.hidden;
+            if (next === visible.current)
+                return;
+            visible.current = next;
+            el.toggleAttribute("data-sx-paused", !next);
+            for (const listener of listeners.current)
+                listener(next);
+        };
+        const io = new IntersectionObserver((entries) => {
+            const entry = entries[entries.length - 1];
+            if (entry)
+                onScreen = entry.isIntersecting;
+            apply();
+        });
+        io.observe(el);
+        document.addEventListener("visibilitychange", apply);
+        apply();
+        return () => {
+            io.disconnect();
+            document.removeEventListener("visibilitychange", apply);
+        };
+    }, [root, pauseOffscreen]);
+    const subscribe = useCallback((listener) => {
+        listeners.current.add(listener);
+        return () => {
+            listeners.current.delete(listener);
+        };
+    }, []);
+    return { visible, subscribe };
+}
+/**
+ * Pointer position as CSS variables on the root (for CSS effects) and as
+ * numbers in `pointer` (for canvas / WebGL), at most once per frame, on
+ * motion's frame loop. One window listener however many layers ask for it.
+ */
+export function usePointerTracking(root, visible) {
+    const pointer = useRef({ x: 0, y: 0, inside: false }).current;
+    const tapListeners = useRef(new Set());
+    const users = useRef(0);
+    const detach = useRef(null);
+    useEffect(() => () => detach.current?.(), []);
+    const track = useCallback(() => {
+        if (users.current++ === 0) {
+            let x = 0;
+            let y = 0;
+            let scheduled = false;
+            const write = () => {
+                scheduled = false;
+                const el = root.current;
+                if (!el || !visible.current)
+                    return;
+                const rect = el.getBoundingClientRect();
+                const px = x - rect.left;
+                const py = y - rect.top;
+                const inside = px >= 0 && py >= 0 && px <= rect.width && py <= rect.height;
+                pointer.x = px;
+                pointer.y = py;
+                pointer.inside = inside;
+                el.style.setProperty("--sx-pointer-x", `${Math.round(px)}px`);
+                el.style.setProperty("--sx-pointer-y", `${Math.round(py)}px`);
+                el.style.setProperty("--sx-pointer-nx", rect.width ? (px / rect.width).toFixed(3) : "0.5");
+                el.style.setProperty("--sx-pointer-ny", rect.height ? (py / rect.height).toFixed(3) : "0.5");
+                el.setAttribute("data-sx-pointer", inside ? "in" : "out");
+            };
+            const move = (e) => {
+                x = e.clientX;
+                y = e.clientY;
+                if (!scheduled) {
+                    scheduled = true;
+                    frame.render(write);
+                }
+            };
+            const leave = () => {
+                pointer.inside = false;
+                root.current?.setAttribute("data-sx-pointer", "out");
+            };
+            // the root never takes pointer events (content sits above it), so taps
+            // are read on the window and kept when they land inside the root's box
+            const down = (e) => {
+                const el = root.current;
+                if (!el || !visible.current || tapListeners.current.size === 0)
+                    return;
+                const rect = el.getBoundingClientRect();
+                const px = e.clientX - rect.left;
+                const py = e.clientY - rect.top;
+                if (px < 0 || py < 0 || px > rect.width || py > rect.height)
+                    return;
+                for (const listener of tapListeners.current)
+                    listener(px, py);
+            };
+            window.addEventListener("pointermove", move, { passive: true });
+            window.addEventListener("pointerdown", down, { passive: true });
+            document.documentElement.addEventListener("pointerleave", leave);
+            detach.current = () => {
+                window.removeEventListener("pointermove", move);
+                window.removeEventListener("pointerdown", down);
+                document.documentElement.removeEventListener("pointerleave", leave);
+                cancelFrame(write);
+            };
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (--users.current === 0) {
+                detach.current?.();
+                detach.current = null;
+            }
+        };
+    }, [root, visible, pointer]);
+    const onTap = useCallback((listener) => {
+        tapListeners.current.add(listener);
+        return () => {
+            tapListeners.current.delete(listener);
+        };
+    }, []);
+    return { track, pointer, onTap };
+}
+/**
+ * The root's scroll progress as `--sx-scroll` / `--sx-scroll-exit` on the root
+ * (for CSS effects) and as numbers in `scroll` (for JS layers), at most once per
+ * frame. Listens in the capture phase, so a page that scrolls an inner
+ * container works too. Skips work while the root is off screen, measures again
+ * when it comes back. Under reduced motion `still` it holds `RESTING_SCROLL`.
+ */
+export function useScrollTracking(root, visible, onVisibility, reducedMotion) {
+    const scroll = useRef({ ...RESTING_SCROLL }).current;
+    const listeners = useRef(new Set());
+    const users = useRef(0);
+    const detach = useRef(null);
+    // read at measure time, so a config change needs no re-subscription
+    const policy = useRef(reducedMotion);
+    policy.current = reducedMotion;
+    useEffect(() => () => detach.current?.(), []);
+    const track = useCallback(() => {
+        if (users.current++ === 0) {
+            const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+            let scheduled = false;
+            const write = () => {
+                scheduled = false;
+                const el = root.current;
+                if (!el || !visible.current)
+                    return;
+                let next = RESTING_SCROLL;
+                if (!(reduce.matches && policy.current === "still")) {
+                    const rect = el.getBoundingClientRect();
+                    next = scrollProgress(rect.top, rect.height, window.innerHeight);
+                }
+                if (next.progress === scroll.progress && next.exit === scroll.exit && el.style.getPropertyValue("--sx-scroll"))
+                    return;
+                scroll.progress = next.progress;
+                scroll.exit = next.exit;
+                el.style.setProperty("--sx-scroll", next.progress.toFixed(4));
+                el.style.setProperty("--sx-scroll-exit", next.exit.toFixed(4));
+                for (const listener of listeners.current)
+                    listener();
+            };
+            const schedule = () => {
+                if (!scheduled) {
+                    scheduled = true;
+                    frame.render(write);
+                }
+            };
+            document.addEventListener("scroll", schedule, { passive: true, capture: true });
+            window.addEventListener("resize", schedule, { passive: true });
+            reduce.addEventListener("change", schedule);
+            const offVisibility = onVisibility((isVisible) => {
+                if (isVisible)
+                    schedule();
+            });
+            schedule();
+            detach.current = () => {
+                document.removeEventListener("scroll", schedule, { capture: true });
+                window.removeEventListener("resize", schedule);
+                reduce.removeEventListener("change", schedule);
+                offVisibility();
+                cancelFrame(write);
+            };
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (--users.current === 0) {
+                detach.current?.();
+                detach.current = null;
+            }
+        };
+    }, [root, visible, onVisibility, scroll]);
+    const subscribe = useCallback((listener) => {
+        listeners.current.add(listener);
+        return () => {
+            listeners.current.delete(listener);
+        };
+    }, []);
+    return { track, scroll, subscribe };
+}

package/dist/backgrounds/runtime/nativeScroll.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A native `view()` timeline follows the nearest scroll container above the
+ * root. `overflow: hidden` (very common on sections, e.g. Tailwind
+ * `overflow-hidden`) makes one that never scrolls, so the timeline would sit
+ * still. Native works when there is no such ancestor, or the nearest one
+ * really scrolls vertically. (`overflow: clip` is not a scroll container.)
+ */
+export declare function nativeScrollTimelineWorks(root: HTMLElement): boolean;

package/dist/backgrounds/runtime/nativeScroll.js

@@ -0,0 +1,20 @@
+// Whether a native scroll timeline can drive an element here. A plain module: backgrounds, transitions and text share it.
+const SCROLLER = new Set(["auto", "scroll", "overlay", "hidden"]);
+/**
+ * A native `view()` timeline follows the nearest scroll container above the
+ * root. `overflow: hidden` (very common on sections, e.g. Tailwind
+ * `overflow-hidden`) makes one that never scrolls, so the timeline would sit
+ * still. Native works when there is no such ancestor, or the nearest one
+ * really scrolls vertically. (`overflow: clip` is not a scroll container.)
+ */
+export function nativeScrollTimelineWorks(root) {
+    if (typeof CSS === "undefined" || !CSS.supports("animation-timeline: view()"))
+        return false;
+    for (let el = root.parentElement; el && el !== document.body && el !== document.documentElement; el = el.parentElement) {
+        const { overflowX, overflowY } = getComputedStyle(el);
+        if (SCROLLER.has(overflowX) || SCROLLER.has(overflowY)) {
+            return (overflowY === "auto" || overflowY === "scroll" || overflowY === "overlay") && el.scrollHeight > el.clientHeight;
+        }
+    }
+    return true;
+}

package/dist/backgrounds/runtime/noise.d.ts

@@ -0,0 +1,4 @@
+export type Noise3 = (x: number, y: number, z: number) => number;
+export declare function noise3(seed: number): Noise3;
+/** Two octaves: broad shapes plus finer detail, still in [-1, 1]. */
+export declare function fbm(noise: Noise3, x: number, y: number, z: number): number;

package/dist/backgrounds/runtime/noise.js

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// Seeded 3D value noise: smooth random hills in space (x, y) and time (z).
+// Pure and tiny; good enough for flow fields, ASCII shading and melting lines,
+// where nobody inspects the noise itself. Output is in [-1, 1].
+// ---------------------------------------------------------------------------
+import { rng } from "./rng.js";
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + (b - a) * t;
+export function noise3(seed) {
+    const r = rng(seed);
+    const perm = new Uint8Array(512);
+    const p = Array.from({ length: 256 }, (_, i) => i);
+    for (let i = 255; i > 0; i--) {
+        const j = Math.floor(r() * (i + 1));
+        [p[i], p[j]] = [p[j] ?? 0, p[i] ?? 0];
+    }
+    for (let i = 0; i < 512; i++)
+        perm[i] = p[i & 255] ?? 0;
+    const values = Float32Array.from({ length: 256 }, () => r() * 2 - 1);
+    const at = (x, y, z) => values[perm[(perm[(perm[x & 255] ?? 0) + (y & 255)] ?? 0) + (z & 255)] ?? 0] ?? 0;
+    return (x, y, z) => {
+        const xi = Math.floor(x);
+        const yi = Math.floor(y);
+        const zi = Math.floor(z);
+        const u = fade(x - xi);
+        const v = fade(y - yi);
+        const w = fade(z - zi);
+        const x00 = lerp(at(xi, yi, zi), at(xi + 1, yi, zi), u);
+        const x10 = lerp(at(xi, yi + 1, zi), at(xi + 1, yi + 1, zi), u);
+        const x01 = lerp(at(xi, yi, zi + 1), at(xi + 1, yi, zi + 1), u);
+        const x11 = lerp(at(xi, yi + 1, zi + 1), at(xi + 1, yi + 1, zi + 1), u);
+        return lerp(lerp(x00, x10, v), lerp(x01, x11, v), w);
+    };
+}
+/** Two octaves: broad shapes plus finer detail, still in [-1, 1]. */
+export function fbm(noise, x, y, z) {
+    return (noise(x, y, z) * 2 + noise(x * 2.03, y * 2.03, z * 1.7)) / 3;
+}

package/dist/backgrounds/runtime/rng.d.ts

@@ -0,0 +1,10 @@
+/** A function returning numbers in [0, 1), the same sequence for the same seed. */
+export type Rng = () => number;
+/** mulberry32: tiny, fast, good enough for placing decoration. */
+export declare function rng(seed: number): Rng;
+/** A number in [min, max). */
+export declare function between(r: Rng, min: number, max: number): number;
+/** One item of a non-empty list. */
+export declare function pick<T>(r: Rng, items: readonly [T, ...T[]]): T;
+/** Round to `digits` decimals, so generated inline styles stay short and stable. */
+export declare function round(n: number, digits?: number): number;

package/dist/backgrounds/runtime/rng.js

@@ -0,0 +1,29 @@
+// ---------------------------------------------------------------------------
+// Seeded randomness. Effects made of many elements place them with `rng(seed)`
+// instead of Math.random(), so the server and the client render the same
+// markup (no hydration mismatch) and tests can check the output.
+// ---------------------------------------------------------------------------
+/** mulberry32: tiny, fast, good enough for placing decoration. */
+export function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** A number in [min, max). */
+export function between(r, min, max) {
+    return min + r() * (max - min);
+}
+/** One item of a non-empty list. */
+export function pick(r, items) {
+    return items[Math.floor(r() * items.length)] ?? items[0];
+}
+/** Round to `digits` decimals, so generated inline styles stay short and stable. */
+export function round(n, digits = 2) {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+}

package/dist/backgrounds/runtime/rootCss.d.ts

@@ -0,0 +1,3 @@
+/** Tailwind's layer order. Every package stylesheet that may be the first on the page starts with it. */
+export declare const LAYER_ORDER = "@layer theme, base, components, utilities;";
+export declare const ROOT_CSS = "@layer theme, base, components, utilities;\n@layer components {\n  :where([data-sx-bg-root]) {\n    position: absolute;\n    inset: 0;\n    z-index: -1;\n    overflow: hidden;\n    pointer-events: none;\n    contain: layout paint;\n    container-type: size;\n  }\n  :where([data-sx-bg-root] [data-sx-bg]) {\n    position: absolute;\n    inset: 0;\n    overflow: hidden;\n    container-type: size;\n    opacity: var(--sx-bg-opacity, 1);\n    mix-blend-mode: var(--sx-bg-blend, normal);\n    mask-image: var(--sx-bg-mask, none);\n  }\n  :where([data-sx-bg-root] [data-sx-bg-part=\"media\"]),\n  :where([data-sx-bg-root] [data-sx-bg-part=\"canvas\"]),\n  :where([data-sx-bg-root] [data-sx-bg-part=\"svg\"]) {\n    position: absolute;\n    inset: 0;\n    inline-size: 100%;\n    block-size: 100%;\n    object-fit: cover;\n  }\n  :where([data-sx-bg-root][data-sx-paused]) *,\n  :where([data-sx-bg-root][data-sx-paused]) *::before,\n  :where([data-sx-bg-root][data-sx-paused]) *::after {\n    animation-play-state: paused !important;\n  }\n  @media (prefers-reduced-motion: reduce) {\n    :where([data-sx-bg-root][data-sx-reduce=\"still\"]) *,\n    :where([data-sx-bg-root][data-sx-reduce=\"still\"]) *::before,\n    :where([data-sx-bg-root][data-sx-reduce=\"still\"]) *::after {\n      animation-play-state: paused !important;\n    }\n    :where([data-sx-bg-root][data-sx-reduce=\"slow\"]) {\n      --sx-bg-tempo: 0.35;\n    }\n  }\n}";

package/dist/backgrounds/runtime/rootCss.js

@@ -0,0 +1,66 @@
+// The stylesheet every Background.Root brings: positioning, the shared layer
+// knobs (opacity, blend, mask), and the pause / reduced-motion switches.
+//
+// The root sits at z-index -1, so its parent must form a stacking context
+// (`position: relative; isolation: isolate`, Tailwind `relative isolate`):
+// the background then paints above the parent's own background colour and
+// below all of its content, with no z-index on the content.
+//
+// React inserts `<style precedence>` at the TOP of <head>, before the app's own
+// stylesheet. Cascade-layer order is fixed by the first time a layer name
+// appears, so without the statement below our `components` would be declared
+// first and rank BELOW Tailwind's `base` reset (which sets `border: 0`). The
+// statement pins Tailwind's order; Tailwind's identical statement later is a
+// no-op, and a project without Tailwind just gets empty layers.
+//
+// Both the root and each layer are size containers. A container's OWN
+// properties cannot measure it (cq units there resolve against the next
+// container up, or the viewport), so a layer rule like `gap: 2cqmin` needs the
+// root to be one too. Root and layer are the same size, so the units agree.
+/** Tailwind's layer order. Every package stylesheet that may be the first on the page starts with it. */
+export const LAYER_ORDER = "@layer theme, base, components, utilities;";
+export const ROOT_CSS = `${LAYER_ORDER}
+@layer components {
+  :where([data-sx-bg-root]) {
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    overflow: hidden;
+    pointer-events: none;
+    contain: layout paint;
+    container-type: size;
+  }
+  :where([data-sx-bg-root] [data-sx-bg]) {
+    position: absolute;
+    inset: 0;
+    overflow: hidden;
+    container-type: size;
+    opacity: var(--sx-bg-opacity, 1);
+    mix-blend-mode: var(--sx-bg-blend, normal);
+    mask-image: var(--sx-bg-mask, none);
+  }
+  :where([data-sx-bg-root] [data-sx-bg-part="media"]),
+  :where([data-sx-bg-root] [data-sx-bg-part="canvas"]),
+  :where([data-sx-bg-root] [data-sx-bg-part="svg"]) {
+    position: absolute;
+    inset: 0;
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+  :where([data-sx-bg-root][data-sx-paused]) *,
+  :where([data-sx-bg-root][data-sx-paused]) *::before,
+  :where([data-sx-bg-root][data-sx-paused]) *::after {
+    animation-play-state: paused !important;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-bg-root][data-sx-reduce="still"]) *,
+    :where([data-sx-bg-root][data-sx-reduce="still"]) *::before,
+    :where([data-sx-bg-root][data-sx-reduce="still"]) *::after {
+      animation-play-state: paused !important;
+    }
+    :where([data-sx-bg-root][data-sx-reduce="slow"]) {
+      --sx-bg-tempo: 0.35;
+    }
+  }
+}`;

package/dist/backgrounds/runtime/scroll.d.ts

@@ -0,0 +1,25 @@
+/** Two views of where the box is. Both 0–1, clamped. */
+export interface ScrollState {
+    /**
+     * `--sx-scroll`: 0 when the box's top edge reaches the bottom of the
+     * viewport, 1 when its bottom edge leaves the top. The same range as a
+     * native `view()` timeline (`cover`). Best for sections mid-page.
+     */
+    progress: number;
+    /**
+     * `--sx-scroll-exit`: 0 while the box's top is at or below the top of the
+     * viewport, 1 once the whole box has scrolled past it. Best for a hero that
+     * starts at the top of the page (its `progress` starts near 0.5).
+     */
+    exit: number;
+}
+/** Where scroll effects rest: on the server, before the first measure, and under reduced motion `still`. */
+export declare const RESTING_SCROLL: Readonly<ScrollState>;
+/** `top` and `height` of the box (from getBoundingClientRect) and the viewport height, all px. */
+export declare function scrollProgress(top: number, height: number, viewport: number): ScrollState;
+/**
+ * The layer variables a scroll effect reads: `--sx-bg-p` (the chosen progress,
+ * 0–1) and `--sx-bg-p0` (its resting value, so `p - p0` is 0 at rest). The
+ * fallbacks are the resting values, so server HTML renders the resting frame.
+ */
+export declare function scrollVars(range: "cover" | "exit"): Record<"--sx-bg-p" | "--sx-bg-p0", string | number>;