@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/transitions/effects/stage/kit.d.ts

@@ -0,0 +1,20 @@
+import type { CarouselFrame, SlotFrameBuffer } from "../../../carousel/engine/types.js";
+/** Add to the main-axis offset (`x` for a horizontal carousel, `y` for a vertical one). */
+export declare function addMain(buf: SlotFrameBuffer, frame: CarouselFrame, value: number): void;
+/** Add to the cross-axis offset. */
+export declare function addCross(buf: SlotFrameBuffer, frame: CarouselFrame, value: number): void;
+/**
+ * Turn the card around the cross axis by `deg`, so a positive turn faces it
+ * towards where the next card comes from (right, or down on a vertical
+ * carousel): `rotateY(deg)` on x, `rotateX(-deg)` on y.
+ */
+export declare function turn(buf: SlotFrameBuffer, frame: CarouselFrame, deg: number): void;
+/** Spin in the card's own plane (`rotateZ`), mirrored on a vertical carousel so it still leans "forward". */
+export declare function spin(buf: SlotFrameBuffer, frame: CarouselFrame, deg: number): void;
+/** Set the transform origin along the main axis (0 = start edge, 1 = end edge). */
+export declare function originMain(buf: SlotFrameBuffer, frame: CarouselFrame, value: number): void;
+/** Set the transform origin along the cross axis. */
+export declare function originCross(buf: SlotFrameBuffer, frame: CarouselFrame, value: number): void;
+export declare function clamp01(v: number): number;
+/** `filter: brightness()` that skips the string when nothing is dimmed. */
+export declare function dim(buf: SlotFrameBuffer, amount: number): void;

package/dist/transitions/effects/stage/kit.js

@@ -0,0 +1,52 @@
+// Small axis-aware helpers shared by the stage layouts. Pure; no React, no DOM.
+/** Add to the main-axis offset (`x` for a horizontal carousel, `y` for a vertical one). */
+export function addMain(buf, frame, value) {
+    if (frame.axis === "x")
+        buf.x += value;
+    else
+        buf.y += value;
+}
+/** Add to the cross-axis offset. */
+export function addCross(buf, frame, value) {
+    if (frame.axis === "x")
+        buf.y += value;
+    else
+        buf.x += value;
+}
+/**
+ * Turn the card around the cross axis by `deg`, so a positive turn faces it
+ * towards where the next card comes from (right, or down on a vertical
+ * carousel): `rotateY(deg)` on x, `rotateX(-deg)` on y.
+ */
+export function turn(buf, frame, deg) {
+    if (frame.axis === "x")
+        buf.rotateY = deg;
+    else
+        buf.rotateX = -deg;
+}
+/** Spin in the card's own plane (`rotateZ`), mirrored on a vertical carousel so it still leans "forward". */
+export function spin(buf, frame, deg) {
+    buf.rotateZ = frame.axis === "x" ? deg : -deg;
+}
+/** Set the transform origin along the main axis (0 = start edge, 1 = end edge). */
+export function originMain(buf, frame, value) {
+    if (frame.axis === "x")
+        buf.originX = value;
+    else
+        buf.originY = value;
+}
+/** Set the transform origin along the cross axis. */
+export function originCross(buf, frame, value) {
+    if (frame.axis === "x")
+        buf.originY = value;
+    else
+        buf.originX = value;
+}
+export function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** `filter: brightness()` that skips the string when nothing is dimmed. */
+export function dim(buf, amount) {
+    if (amount > 0.001)
+        buf.filter = `brightness(${(1 - amount).toFixed(3)})`;
+}

package/dist/transitions/effects/stage/push.d.ts

@@ -0,0 +1,15 @@
+import { type CarouselLayout } from "../../../carousel/layout/types.js";
+export interface PushOptions {
+    /** How far the leaving card travels, as a fraction of its size. `1` = a plain push. Default `0.3`. */
+    readonly travel?: number;
+    /** Scale the leaving card shrinks to. Default `0.94`. */
+    readonly scale?: number;
+    /** How much the leaving card darkens, 0–1. Default `0.35`. */
+    readonly shade?: number;
+}
+/**
+ * Directional enter / exit: the new card slides in from the side the user is
+ * heading to and covers the old one, which drifts a little the same way,
+ * shrinks and darkens. Going back plays it the other way round.
+ */
+export declare function push(options?: PushOptions): CarouselLayout;

package/dist/transitions/effects/stage/push.js

@@ -0,0 +1,28 @@
+import { composeLayout } from "../../../carousel/layout/types.js";
+import { stack } from "../../../carousel/layout/modifiers/stack.js";
+import { addMain, dim } from "./kit.js";
+/**
+ * Directional enter / exit: the new card slides in from the side the user is
+ * heading to and covers the old one, which drifts a little the same way,
+ * shrinks and darkens. Going back plays it the other way round.
+ */
+export function push(options = {}) {
+    const travel = options.travel ?? 0.3;
+    const scale = options.scale ?? 0.94;
+    const shade = options.shade ?? 0.35;
+    return composeLayout("push", stack(), (buf, slot, frame) => {
+        if (buf.opacity === 0)
+            return;
+        const d = slot.distance;
+        const size = frame.slotMain;
+        if (d > 0) {
+            addMain(buf, frame, d * size);
+        }
+        else {
+            const a = -d;
+            addMain(buf, frame, d * size * travel);
+            buf.scaleX = buf.scaleY = 1 - (1 - scale) * a;
+            dim(buf, a * shade);
+        }
+    });
+}

package/dist/transitions/effects/stage/push.schema.d.ts

@@ -0,0 +1 @@
+export declare const PUSH_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/transitions/effects/stage/push.schema.js

@@ -0,0 +1,11 @@
+import { defineSchema } from "../../../schema/define.js";
+export const PUSH_SCHEMA = defineSchema()({
+    id: "push",
+    family: "transition",
+    factory: "push",
+    fields: {
+        travel: { kind: "number", label: "Travel", min: 0, max: 1, step: 0.01, default: 0.3, help: "How far the leaving card drifts: 1 is a plain push." },
+        scale: { kind: "number", label: "Shrink to", min: 0.5, max: 1, step: 0.01, default: 0.94 },
+        shade: { kind: "number", label: "Darken", min: 0, max: 1, step: 0.01, default: 0.35 },
+    },
+});

package/dist/transitions/effects/stage/tinder.d.ts

@@ -0,0 +1,13 @@
+import { type CarouselLayout } from "../../../carousel/layout/types.js";
+export interface TinderOptions {
+    /** Degrees the card turns by the time it has left. Default `16`. */
+    readonly angle?: number;
+    /** Cards waiting behind the top one. Default `2`. */
+    readonly depth?: number;
+}
+/**
+ * Swipe cards: the top card is thrown off to the side, turning around its
+ * bottom edge and dropping a little, and uncovers the next one, which grows to
+ * full size. Dragging scrubs the throw; dragging back brings the card back.
+ */
+export declare function tinder(options?: TinderOptions): CarouselLayout;

package/dist/transitions/effects/stage/tinder.js

@@ -0,0 +1,32 @@
+import { composeLayout } from "../../../carousel/layout/types.js";
+import { stack } from "../../../carousel/layout/modifiers/stack.js";
+import { addCross, addMain, clamp01, originCross, spin } from "./kit.js";
+/**
+ * Swipe cards: the top card is thrown off to the side, turning around its
+ * bottom edge and dropping a little, and uncovers the next one, which grows to
+ * full size. Dragging scrubs the throw; dragging back brings the card back.
+ */
+export function tinder(options = {}) {
+    const angle = options.angle ?? 16;
+    const depth = options.depth ?? 2;
+    return {
+        ...composeLayout("tinder", stack({ order: "outgoing", ahead: depth }), (buf, slot, frame) => {
+            if (buf.opacity === 0)
+                return;
+            const d = slot.distance;
+            if (d >= 0) {
+                buf.scaleX = buf.scaleY = 1 - Math.min(d, depth) * 0.05;
+                if (d > depth)
+                    buf.opacity = clamp01(depth + 1 - d);
+            }
+            else {
+                const size = frame.slotMain;
+                addMain(buf, frame, d * size * 1.25);
+                addCross(buf, frame, -d * size * 0.08);
+                spin(buf, frame, d * angle);
+                originCross(buf, frame, 1);
+            }
+        }),
+        reach: depth + 1,
+    };
+}

package/dist/transitions/effects/stage/tinder.schema.d.ts

@@ -0,0 +1 @@
+export declare const TINDER_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/transitions/effects/stage/tinder.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const TINDER_SCHEMA = defineSchema()({
+    id: "tinder",
+    family: "transition",
+    factory: "tinder",
+    fields: {
+        angle: { kind: "number", label: "Throw turn", min: 0, max: 45, step: 1, unit: "°", default: 16 },
+        depth: { kind: "integer", label: "Cards behind", min: 1, max: 5, default: 2 },
+    },
+});

package/dist/transitions/hosts/ShaderStage.d.ts

@@ -0,0 +1,30 @@
+import type { ShaderTransition } from "../types.js";
+/** What to draw now. */
+export interface ShaderFrame {
+    readonly from: string | undefined;
+    readonly to: string | undefined;
+    /** 0 = only `from`, 1 = only `to`. */
+    readonly progress: number;
+    /** Pictures needed next, most likely first: decoded ahead, and kept on the GPU while there is room. */
+    readonly ahead: readonly (string | undefined)[];
+}
+export interface ShaderDriver {
+    read(): ShaderFrame;
+    /** Call `changed` whenever `read()` may give something new; returns a stop function. */
+    watch(changed: () => void): () => void;
+}
+export interface ShaderStageProps {
+    readonly effect: ShaderTransition;
+    readonly driver: ShaderDriver;
+    /** Where it plays: a carousel writes the fallback's `--sx-p`; a reveal's inherits it. */
+    readonly mode: "carousel" | "reveal";
+    /** Redraw when this changes (new items, a new picture function). */
+    readonly version?: unknown;
+    readonly className?: string;
+}
+/**
+ * The transition on a canvas, or, without WebGL (or below its tier, or after
+ * the context failed), its CSS fallback on two `<img>`s. The context follows
+ * `gpu/surface.ts`: created once on screen, handed back after 3 s off it.
+ */
+export declare function ShaderStage({ effect, driver, mode, version, className }: ShaderStageProps): import("react").JSX.Element;

package/dist/transitions/hosts/ShaderStage.js

@@ -0,0 +1,268 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Draws a shader transition between two pictures. Who decides which pictures
+// and how far along is a `ShaderDriver`: the carousel (its position) or a
+// Reveal (its --sx-p). Imports nothing from the carousel.
+import { useEffect, useRef, useState } from "react";
+import { cancelFrame, frame } from "motion/react";
+import { createColorResolver, watchTheme } from "../../backgrounds/runtime/color.js";
+import { createGpuSurface } from "../../gpu/surface.js";
+import { CROSSFADE_FRAGMENT, readsScroll, transitionProgram } from "../shader/program.js";
+import { scrollSpeed, watchScrollSpeed } from "../shader/scrollSpeed.js";
+import { createTexturePool, decodeImage } from "../shader/textures.js";
+import { TransitionNodes, TransitionStyle, transitionStyle, useTransition } from "./shared.js";
+/** Backing pixels per CSS pixel, at most. */
+const MAX_DPR = 2;
+/** Largest canvas side in backing pixels. */
+const MAX_CANVAS_SIDE = 4096;
+/**
+ * Layout as inline styles, not utility classes: if the canvas box ever took
+ * its size from the canvas (a page whose CSS lacks the classes), the canvas
+ * would grow its own box, the resize observer would grow the canvas, and so
+ * on without end. Inline, the box always comes from the parent.
+ */
+const FILL = { position: "absolute", inset: 0, overflow: "hidden" };
+const CANVAS = { position: "absolute", inset: 0, display: "block", width: "100%", height: "100%" };
+const HOST = { ...FILL, pointerEvents: "none" };
+const PICTURE = { position: "absolute", inset: 0, width: "100%", height: "100%", objectFit: "cover" };
+/**
+ * The transition on a canvas, or, without WebGL (or below its tier, or after
+ * the context failed), its CSS fallback on two `<img>`s. The context follows
+ * `gpu/surface.ts`: created once on screen, handed back after 3 s off it.
+ */
+export function ShaderStage({ effect, driver, mode, version, className = "" }) {
+    const picked = useTransition(effect);
+    const [generation, setGeneration] = useState(0);
+    const [failed, setFailed] = useState(false);
+    const losses = useRef([]);
+    if (picked.kind !== "webgl" || failed) {
+        return (_jsx(FallbackStage, { transition: picked.kind === "webgl" ? picked.fallback : picked, driver: driver, mode: mode, version: version, className: className }));
+    }
+    return (_jsx(GlStage, { effect: picked, driver: driver, version: version, className: className, renew: () => setGeneration((g) => g + 1), fail: () => setFailed(true), losses: losses }, generation));
+}
+function GlStage({ effect, driver, version, className, renew, fail, losses }) {
+    const hostRef = useRef(null);
+    const canvasRef = useRef(null);
+    const driverRef = useRef(driver);
+    driverRef.current = driver;
+    const hooks = useRef({ renew, fail });
+    hooks.current = { renew, fail };
+    const redraw = useRef(() => { });
+    useEffect(() => {
+        redraw.current();
+    }, [driver, version]);
+    useEffect(() => {
+        const host = hostRef.current;
+        const canvas = canvasRef.current;
+        if (!host || !canvas)
+            return;
+        const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+        // reduced motion: every look is a plain cross-fade (atlas rule 6)
+        const look = reduce.matches
+            ? { ...effect, fragment: CROSSFADE_FRAGMENT, uniforms: {}, colors: [], map: undefined }
+            : effect;
+        const program = transitionProgram(look);
+        const resolver = createColorResolver(host);
+        const resolveColors = () => look.colors.map((c) => {
+            const [r, g, b, a] = resolver.resolve(c);
+            return [r / 255, g / 255, b / 255, a];
+        });
+        let colors = resolveColors();
+        const rtl = getComputedStyle(host).direction === "rtl";
+        let origin = [0.5, 0.5];
+        let onScreen = false;
+        let visible = false;
+        let unwatch = null;
+        // a fragment that reads the scroll speed redraws while the page scrolls
+        const followsScroll = readsScroll(look.fragment);
+        let unscroll = null;
+        let pending = false;
+        let drawn = false;
+        const draw = () => {
+            pending = false;
+            const live = surface.live;
+            if (!live)
+                return;
+            const { gl, state } = live;
+            const f = driverRef.current.read();
+            // capped, so a box that is somehow unsized (or huge) can never ask the GPU for a giant canvas
+            const dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR);
+            const width = Math.min(MAX_CANVAS_SIDE, Math.max(1, Math.round(host.clientWidth * dpr)));
+            const height = Math.min(MAX_CANVAS_SIDE, Math.max(1, Math.round(host.clientHeight * dpr)));
+            if (canvas.width !== width || canvas.height !== height) {
+                canvas.width = width;
+                canvas.height = height;
+            }
+            state.pictures.resize(width, height);
+            state.maps.resize(width, height);
+            state.pictures.want([f.from, f.to, ...f.ahead]);
+            for (const url of f.ahead)
+                if (url)
+                    decodeImage(url).catch(() => { });
+            if (look.map)
+                state.maps.want([look.map]);
+            const from = state.pictures.get(f.from);
+            const to = state.pictures.get(f.to);
+            // A picture this frame shows that is still loading: keep the last frame
+            // (the canvas holds it) rather than flash it as transparent.
+            const missing = (f.from && !from && f.progress < 1) || (f.to && !to && f.progress > 0);
+            if (missing && drawn)
+                return;
+            program.draw(gl, state.program, {
+                width,
+                height,
+                progress: f.progress,
+                from,
+                to,
+                map: look.map ? state.maps.get(look.map) : null,
+                origin,
+                rtl,
+                colors,
+                scroll: followsScroll ? scrollSpeed() : 0,
+            });
+            drawn = true;
+        };
+        const schedule = () => {
+            if (pending)
+                return;
+            pending = true;
+            frame.render(draw);
+        };
+        const surface = createGpuSurface(canvas, {
+            api: "webgl",
+            label: effect.id,
+            init: (gl) => ({
+                program: program.init(gl),
+                pictures: createTexturePool(gl, { onReady: schedule }),
+                maps: createTexturePool(gl, { onReady: schedule, max: 1 }),
+            }),
+            dispose: (gl, state) => {
+                state.pictures.dispose();
+                state.maps.dispose();
+                program.dispose(gl, state.program);
+            },
+            isVisible: () => visible,
+            onRelease: () => {
+                unwatch?.();
+                unwatch = null;
+                unscroll?.();
+                unscroll = null;
+            },
+            renew: () => hooks.current.renew(),
+            fail: () => hooks.current.fail(),
+            losses,
+        });
+        const sync = () => {
+            visible = onScreen && !document.hidden;
+            if (!visible) {
+                unwatch?.();
+                unwatch = null;
+                unscroll?.();
+                unscroll = null;
+                surface.hidden();
+                return;
+            }
+            if (!surface.shown())
+                return; // a fresh canvas is coming
+            if (!surface.ensure())
+                return;
+            unwatch ?? (unwatch = driverRef.current.watch(schedule));
+            if (followsScroll)
+                unscroll ?? (unscroll = watchScrollSpeed(schedule));
+            schedule();
+        };
+        const io = new IntersectionObserver((entries) => {
+            const entry = entries[entries.length - 1];
+            if (entry)
+                onScreen = entry.isIntersecting;
+            sync();
+        });
+        io.observe(host);
+        document.addEventListener("visibilitychange", sync);
+        const renewOnReduce = () => hooks.current.renew();
+        reduce.addEventListener("change", renewOnReduce);
+        const stopTheme = watchTheme(() => {
+            colors = resolveColors();
+            schedule();
+        });
+        const ro = new ResizeObserver(schedule);
+        ro.observe(host);
+        // Where the last tap inside the box landed, for looks that start from it
+        // (ripple). The canvas takes no pointer events (the cards above it do),
+        // so listen on the window and keep the taps that fall inside its box.
+        const onTap = (event) => {
+            const r = host.getBoundingClientRect();
+            const x = (event.clientX - r.left) / r.width;
+            const y = (event.clientY - r.top) / r.height;
+            if (x >= 0 && x <= 1 && y >= 0 && y <= 1)
+                origin = [x, 1 - y];
+        };
+        window.addEventListener("pointerdown", onTap, { capture: true, passive: true });
+        redraw.current = schedule;
+        return () => {
+            redraw.current = () => { };
+            io.disconnect();
+            document.removeEventListener("visibilitychange", sync);
+            reduce.removeEventListener("change", renewOnReduce);
+            stopTheme();
+            ro.disconnect();
+            window.removeEventListener("pointerdown", onTap, { capture: true });
+            unwatch?.();
+            unscroll?.();
+            cancelFrame(draw);
+            surface.destroy();
+            resolver.dispose();
+        };
+    }, [effect.signature, losses]);
+    return (_jsx("div", { ref: hostRef, "data-sx-shader": effect.id, "aria-hidden": true, className: className || undefined, style: HOST, children: _jsx("canvas", { ref: canvasRef, "data-sx-shader-part": "canvas", style: CANVAS }) }));
+}
+const round = (n) => String(Math.round(n * 10000) / 10000);
+function setSource(img, url) {
+    if (!img || (img.getAttribute("src") ?? undefined) === url)
+        return;
+    if (url)
+        img.setAttribute("src", url);
+    else
+        img.removeAttribute("src");
+    img.hidden = !url;
+}
+/**
+ * No WebGL: the old picture as an `<img>`, the new one in a layer that plays
+ * the fallback CSS transition. A carousel writes its `--sx-p` from the
+ * driver; inside a Reveal it inherits the Reveal's own.
+ */
+function FallbackStage({ transition, driver, mode, version, className, }) {
+    const fromRef = useRef(null);
+    const toRef = useRef(null);
+    const layerRef = useRef(null);
+    const first = driver.read();
+    useEffect(() => {
+        let pending = false;
+        const apply = () => {
+            pending = false;
+            const f = driver.read();
+            setSource(fromRef.current, f.from);
+            setSource(toRef.current, f.to);
+            if (mode === "carousel")
+                layerRef.current?.style.setProperty("--sx-p", round(f.progress));
+            for (const url of f.ahead)
+                if (url)
+                    decodeImage(url).catch(() => { });
+        };
+        apply();
+        // a reveal's progress is CSS all the way: nothing to follow
+        if (mode === "reveal")
+            return;
+        const stop = driver.watch(() => {
+            if (pending)
+                return;
+            pending = true;
+            frame.render(apply);
+        });
+        return () => {
+            stop();
+            cancelFrame(apply);
+        };
+    }, [driver, mode, version]);
+    return (_jsxs("div", { "data-sx-shader-fallback": transition.id, "aria-hidden": true, className: className || undefined, style: HOST, children: [_jsx(TransitionStyle, { transition: transition }), _jsx("img", { ref: fromRef, src: first.from, hidden: !first.from, alt: "", draggable: false, style: PICTURE }), _jsxs("div", { ref: layerRef, "data-sx-tr": transition.id, "data-sx-tr-mode": mode === "carousel" ? "carousel" : undefined, style: { ...FILL, ...transitionStyle(transition, first.to) }, children: [_jsx("img", { ref: toRef, src: first.to, hidden: !first.to, alt: "", draggable: false, style: PICTURE }), _jsx(TransitionNodes, { transition: transition, image: first.to })] })] }));
+}

package/dist/transitions/hosts/shared.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { LayoutTransition } from "../../carousel/layout/types.js";
+import type { DeviceTier } from "../../backgrounds/types.js";
+/** The first transition in the fallback chain that the device runs. */
+export declare function pickTransition<T extends LayoutTransition>(transition: T, device: DeviceTier): T;
+/**
+ * The transition this device should play. Detects the tier only when the
+ * transition is not `all` (detection makes one throwaway WebGL context).
+ */
+export declare function useTransition<T extends LayoutTransition>(transition: T): T;
+export declare function useTransition<T extends LayoutTransition>(transition: T | undefined): T | undefined;
+/** The progress contract and the transition's own CSS (none for a shader), hoisted into <head> once per page by React. */
+export declare function TransitionStyle({ transition }: {
+    readonly transition: LayoutTransition;
+}): import("react").JSX.Element;
+/** A scroll composition's stylesheet (`scroll/css.ts`) with the base sheet it relies on (`--sx-p`, `sx-tr-scrub`). */
+export declare function PartStyle({ id, css }: {
+    readonly id: string;
+    readonly css: string;
+}): import("react").JSX.Element;
+/** Inline style for the element that plays the transition. */
+export declare function transitionStyle(transition: LayoutTransition, image: string | undefined): CSSProperties;
+/** The transition's generated nodes, after the content. */
+export declare function TransitionNodes({ transition, image }: {
+    readonly transition: LayoutTransition;
+    readonly image?: string | undefined;
+}): ReactNode;

package/dist/transitions/hosts/shared.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// What both hosts (carousel slots and Reveal) render for a CSS transition.
+// Imports nothing from the carousel, so the carousel parts can use it.
+import { useId } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { renderSvgElement } from "../../backgrounds/hosts/svgElement.js";
+import { useDeviceTier } from "../../backgrounds/runtime/hooks.js";
+import { tierAllows } from "../../backgrounds/runtime/tier.js";
+import { TRANSITION_BASE_CSS, motionOnly } from "../progress.js";
+/** The first transition in the fallback chain that the device runs. */
+export function pickTransition(transition, device) {
+    let t = transition;
+    while (t) {
+        if (tierAllows(device, t.tier))
+            return t;
+        t = t.fallback;
+    }
+    // nothing allowed: the last link (every chain ends on an `all` transition)
+    let last = transition;
+    while (last.fallback)
+        last = last.fallback;
+    return last;
+}
+export function useTransition(transition) {
+    const device = useDeviceTier(transition && transition.tier !== "all" ? "auto" : "high");
+    return transition ? pickTransition(transition, device) : undefined;
+}
+/** The progress contract and the transition's own CSS (none for a shader), hoisted into <head> once per page by React. */
+export function TransitionStyle({ transition }) {
+    const css = transition.css ? motionOnly(transition.css) : "";
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("tr-base", TRANSITION_BASE_CSS), precedence: "sx", children: TRANSITION_BASE_CSS }), css ? (_jsx("style", { href: styleHref(`tr-${transition.id}`, css), precedence: "sx", children: css })) : null] }));
+}
+/** A scroll composition's stylesheet (`scroll/css.ts`) with the base sheet it relies on (`--sx-p`, `sx-tr-scrub`). */
+export function PartStyle({ id, css }) {
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("tr-base", TRANSITION_BASE_CSS), precedence: "sx", children: TRANSITION_BASE_CSS }), _jsx("style", { href: styleHref(`part-${id}`, css), precedence: "sx", children: css })] }));
+}
+/** Inline style for the element that plays the transition. */
+export function transitionStyle(transition, image) {
+    return (image ? { ...transition.vars, "--sx-tr-image": `url("${image}")` } : transition.vars);
+}
+/** `{uid}` in a node's var values becomes the element's id prefix (`url(#{uid}-goo)`). */
+function withUid(vars, uid) {
+    if (!vars)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(vars))
+        out[k] = typeof v === "string" ? v.split("{uid}").join(uid) : v;
+    return out;
+}
+function renderNode(node, key, uid, image) {
+    return (_jsxs("span", { "data-sx-tr-node": node.part, "aria-hidden": true, style: withUid(node.vars, uid), children: [node.media && image ? _jsx("img", { src: image, alt: "", draggable: false, decoding: "async" }) : null, node.svg ? (_jsx("svg", { viewBox: node.svg.viewBox, preserveAspectRatio: node.svg.preserveAspectRatio, focusable: "false", children: node.svg.children.map((el, i) => renderSvgElement(el, uid, i, "data-sx-tr-part")) })) : null, node.children?.map((child, i) => renderNode(child, i, uid, image))] }, key));
+}
+/** The transition's generated nodes, after the content. */
+export function TransitionNodes({ transition, image }) {
+    // ids for filters inside nodes, unique per element and valid in url(#…)
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    return transition.nodes.map((node, i) => renderNode(node, i, uid, image));
+}

package/dist/transitions/progress.d.ts

@@ -0,0 +1,15 @@
+export declare const TRANSITION_BASE_CSS = "@layer theme, base, components, utilities;\n@property --sx-p {\n  syntax: \"<number>\";\n  inherits: true;\n  initial-value: 1;\n}\n@layer components {\n  :where([data-sx-tr-mode=\"carousel\"]) {\n    --sx-p: calc(1 - clamp(0, var(--sx-distance, 0), 1));\n  }\n  :where([data-sx-tr-mode=\"reveal\"]) {\n    position: relative;\n    --sx-p: 0;\n    transition: --sx-p var(--sx-tr-duration, 0.9s) var(--sx-tr-ease, var(--ease-sx-out, cubic-bezier(0.22, 0.7, 0.2, 1))) var(--sx-tr-delay, 0s);\n  }\n  :where([data-sx-in] > [data-sx-tr-mode=\"reveal\"]) {\n    --sx-p: 1;\n  }\n  :where([data-sx-reveal] > [data-sx-tr-mode=\"reveal\"]) {\n    block-size: 100%;\n  }\n  :where([data-sx-reveal][data-sx-scrub]) {\n    view-timeline-name: --sx-tr-view;\n  }\n  :where([data-sx-tr-trigger=\"scroll\"]) {\n    transition: none;\n    animation: sx-tr-scrub linear both;\n    animation-timeline: --sx-tr-view;\n    animation-range: entry 0% cover 50%;\n  }\n  :where([data-sx-tr-trigger=\"scroll\"][data-sx-tr-range=\"entry\"]) {\n    animation-range: entry 0% entry 100%;\n  }\n  :where([data-sx-tr-trigger=\"scroll\"][data-sx-scroll=\"js\"]) {\n    animation: none;\n  }\n  :where([data-sx-tr-node]) {\n    position: absolute;\n    pointer-events: none;\n  }\n  @media (prefers-reduced-motion: reduce) {\n    :where([data-sx-tr-mode=\"reveal\"]) {\n      opacity: var(--sx-p);\n      transition-duration: 0.3s;\n    }\n    :where([data-sx-tr-node]) {\n      display: none;\n    }\n    :where([data-sx-tr-trigger=\"scroll\"]) {\n      animation: none;\n      --sx-p: 1;\n    }\n  }\n}\n@keyframes sx-tr-scrub {\n  from { --sx-p: 0; }\n  to { --sx-p: 1; }\n}";
+/** Where a scroll reveal ends: its centre at the viewport centre (`cover`), or the moment it is fully in (`entry`). */
+export type ScrubRange = "cover" | "entry";
+/**
+ * The JS twin of the native timeline, for the fallback: `top` / `height` of
+ * the box (getBoundingClientRect) and the viewport height, px. 0 when the top
+ * edge reaches the bottom of the viewport, matching `animation-range`:
+ * `entry 0% cover 50%` (cover) or `entry 0% entry 100%` (entry; a box taller
+ * than the viewport is "in" once it fills it). `insetTop` / `insetBottom` are
+ * the page's scroll-padding (a sticky header): a native view timeline leaves
+ * them out of the viewport, so the twin does too. Pure; tested.
+ */
+export declare function scrubProgress(top: number, height: number, viewport: number, range: ScrubRange, insetTop?: number, insetBottom?: number): number;
+/** An effect's stylesheet as shipped: only applies when the user has not asked for reduced motion. */
+export declare function motionOnly(css: string): string;