@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/transitions/scroll/css.js

@@ -0,0 +1,192 @@
+// ---------------------------------------------------------------------------
+// Stylesheets of the scroll compositions. Pure strings, shipped by each part
+// with <PartStyle> (React hoists them into <head> once per page) next to the
+// transitions' base sheet.
+//
+// Same rules as the transition CSS: @layer components, every selector inside
+// :where() (any utility class wins), logical properties, colours from sx
+// tokens, keyframes named sx-tr-*.
+//
+// Two paths for the scroll-driven parts:
+// - native: a view timeline animates the real properties (scale, opacity,
+//   clip-path, transform) with keyframes, never an inherited `--sx-p`. The
+//   browser can run scale and opacity off the main thread, and nothing else
+//   restyles each frame (animating `--sx-p` restyled every element under it,
+//   every frame: measured 200-300 ms/s of style work at 4x CPU throttling).
+// - JS fallback (useScrub.ts): `data-sx-scroll="js"` on the part's driven
+//   element stops those animations, and the part writes the same properties
+//   inline (one formula each, in the part's TSX).
+// Under reduced motion the structure stays (sticky, pinned) and only the
+// movement goes: each part shows its resting state.
+// ---------------------------------------------------------------------------
+const layer = (body) => `@layer components {\n${body}\n}`;
+// Curtain: every panel after the first sticks to the bottom of the viewport,
+// under the one before it (z-index from the part), so the panel above scrolls
+// away and uncovers it. A panel taller than the viewport sticks by its top
+// instead (--sx-curtain-h, measured), so it is read from the start.
+export const CURTAIN_CSS = layer(`  :where([data-sx-curtain]) { position: relative; isolation: isolate; }
+  :where([data-sx-curtain-panel]) { position: relative; background-color: var(--color-sx-secondary, Canvas); }
+  :where([data-sx-curtain-panel] ~ [data-sx-curtain-panel]) {
+    position: sticky;
+    inset-block-end: min(0px, calc(100dvh - var(--sx-curtain-h, 100dvh)));
+  }`);
+// StackCards: each card sticks a little lower than the one before; its
+// content shrinks and a veil of the surface colour fades in as the next card
+// covers it (the next card's view timeline, shared through timeline-scope on
+// the part and handed to each card as --sx-stack-tl). The veil is a real
+// element, not ::after: an animated pseudo-element restyled every frame
+// (measured: 150-240 ms/s of style work at 4x throttling, 60-80 without it).
+export const STACK_CSS = `${layer(`  :where([data-sx-stack]) { display: flex; flex-direction: column; gap: var(--sx-stack-gap, 0px); }
+  :where([data-sx-stack-card]) {
+    position: sticky;
+    inset-block-start: calc(var(--sx-stack-top) + var(--sx-i) * var(--sx-stack-peek));
+  }
+  :where([data-sx-stack-inner]) { position: relative; transform-origin: 50% 0; }
+  :where([data-sx-stack-veil]) {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    border-radius: inherit;
+    background: var(--color-sx-secondary, Canvas);
+    opacity: 0;
+  }
+  :where([data-sx-stack-inner][data-sx-stack-next]), :where([data-sx-stack-next] > [data-sx-stack-veil]) {
+    animation: linear both;
+    animation-timeline: var(--sx-stack-tl);
+    animation-range: entry 0% cover calc(100vh - var(--sx-stack-next-top));
+  }
+  :where([data-sx-stack-inner][data-sx-stack-next]) { animation-name: sx-tr-stack-shrink; }
+  :where([data-sx-stack-next] > [data-sx-stack-veil]) { animation-name: sx-tr-stack-veil; }
+  :where([data-sx-stack-inner][data-sx-scroll="js"]), :where([data-sx-scroll="js"] > [data-sx-stack-veil]) { animation: none; }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-stack-inner]), :where([data-sx-stack-veil]) { animation: none; }
+    :where([data-sx-stack-veil]) { opacity: 0; }
+  }`)}
+@keyframes sx-tr-stack-shrink {
+  from { scale: 1; }
+  to { scale: calc(1 - var(--sx-stack-shrink)); }
+}
+@keyframes sx-tr-stack-veil {
+  from { opacity: 0; }
+  to { opacity: var(--sx-stack-dim); }
+}`;
+// PinnedExpand: a tall wrapper (its view timeline), a sticky full-screen stage,
+// a frame clipped to a rounded box that opens to the whole screen while the
+// picture inside settles from a slight zoom.
+export const PIN_CSS = `${layer(`  :where([data-sx-pin]) { position: relative; view-timeline-name: --sx-pin; }
+  :where([data-sx-pin-stage]) { position: sticky; inset-block-start: 0; block-size: 100dvh; overflow: clip; }
+  :where([data-sx-pin-frame]) { position: absolute; inset: 0; }
+  :where([data-sx-pin-frame] > img) { display: block; inline-size: 100%; block-size: 100%; object-fit: cover; }
+  :where([data-sx-pin-frame]), :where([data-sx-pin-frame] > img) {
+    animation: linear both;
+    animation-timeline: --sx-pin;
+    animation-range: contain 0% contain 100%;
+  }
+  :where([data-sx-pin-frame]) { animation-name: sx-tr-pin-open; }
+  :where([data-sx-pin-frame] > img) { animation-name: sx-tr-pin-settle; }
+  :where([data-sx-scroll="js"] [data-sx-pin-frame]), :where([data-sx-scroll="js"] [data-sx-pin-frame] > img) { animation: none; }
+  :where([data-sx-pin-content]) { position: relative; block-size: 100%; }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-pin-frame]), :where([data-sx-pin-frame] > img) { animation: none; }
+  }`)}
+@keyframes sx-tr-pin-open {
+  from { clip-path: inset(var(--sx-pin-y) var(--sx-pin-x) round var(--sx-pin-r)); }
+  to { clip-path: inset(0px 0px round 0px); }
+}
+@keyframes sx-tr-pin-settle {
+  from { scale: calc(1 + var(--sx-pin-zoom)); }
+  to { scale: 1; }
+}`;
+// TextMaskZoom: the picture underneath; over it a cover in the background
+// colour with the text cut out (an SVG mask: white keeps the cover, the black
+// text is the hole). The whole cover scales up with the cube of the progress
+// (keyframe stops on p³, the same curve the JS fallback computes) and fades
+// out over the last fifth: transform and opacity on one HTML-level element,
+// which the browser can animate off the main thread. (Scaling the text inside
+// the mask instead re-rendered the mask every frame: ~50 fps at 4x throttling.)
+export const TEXT_MASK_CSS = `${layer(`  :where([data-sx-tmz]) { position: relative; view-timeline-name: --sx-tmz; }
+  :where([data-sx-tmz-stage]) { position: sticky; inset-block-start: 0; block-size: 100dvh; overflow: clip; }
+  :where([data-sx-tmz-image]) {
+    position: absolute;
+    inset: 0;
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+  :where([data-sx-tmz-veil]) {
+    position: absolute;
+    inset: 0;
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+    transform-origin: 50% 50%;
+    animation: linear both;
+    animation-timeline: --sx-tmz, --sx-tmz;
+    animation-name: sx-tr-tmz-grow, sx-tr-tmz-clear;
+    animation-range: contain 0% contain 100%, contain 80% contain 100%;
+  }
+  :where([data-sx-tmz-keep]) { fill: white; }
+  :where([data-sx-tmz-veil] text) {
+    font-size: min(22vw, 38dvh);
+    font-weight: 900;
+    fill: black;
+  }
+  :where([data-sx-tmz-cover]) { fill: var(--sx-tmz-bg, var(--color-sx-secondary, Canvas)); }
+  :where([data-sx-scroll="js"] [data-sx-tmz-veil]) { animation: none; }
+  :where([data-sx-tmz-content]) { position: relative; block-size: 100%; }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-tmz-veil]) { animation: none; opacity: 0; }
+  }`)}
+@keyframes sx-tr-tmz-grow {
+  0% { transform: scale(calc(1 + 0 * (var(--sx-tmz-scale) - 1))); }
+  20% { transform: scale(calc(1 + 0.008 * (var(--sx-tmz-scale) - 1))); }
+  40% { transform: scale(calc(1 + 0.064 * (var(--sx-tmz-scale) - 1))); }
+  55% { transform: scale(calc(1 + 0.166375 * (var(--sx-tmz-scale) - 1))); }
+  70% { transform: scale(calc(1 + 0.343 * (var(--sx-tmz-scale) - 1))); }
+  80% { transform: scale(calc(1 + 0.512 * (var(--sx-tmz-scale) - 1))); }
+  90% { transform: scale(calc(1 + 0.729 * (var(--sx-tmz-scale) - 1))); }
+  95% { transform: scale(calc(1 + 0.857375 * (var(--sx-tmz-scale) - 1))); }
+  100% { transform: scale(calc(1 + 1 * (var(--sx-tmz-scale) - 1))); }
+}
+@keyframes sx-tr-tmz-clear {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}`;
+// SplitText: each line slides up out of its own clipped box (or each word
+// rises and fades in), one after another, once the part is in view. While the
+// lines are being measured the words are laid out but invisible.
+export const SPLIT_CSS = layer(`  :where([data-sx-split="measuring"]) { visibility: hidden; }
+  :where([data-sx-split-line]) {
+    display: block;
+    overflow: clip;
+    padding-block-end: 0.12em;
+    margin-block-end: -0.12em;
+  }
+  :where([data-sx-split-inner]), :where([data-sx-split-word]) {
+    --sx-p: 0;
+    transition: --sx-p var(--sx-split-duration, 0.8s) var(--ease-sx-out, cubic-bezier(0.22, 0.7, 0.2, 1))
+      calc(var(--sx-split-delay, 0s) + var(--sx-i, 0) * var(--sx-split-stagger, 0.08s));
+  }
+  :where([data-sx-split-inner]) { display: block; translate: 0 calc((1 - var(--sx-p)) * 110%); }
+  :where([data-sx-split-word]) { display: inline-block; }
+  :where([data-sx-split="words"] [data-sx-split-word]) {
+    translate: 0 calc((1 - var(--sx-p)) * 0.5em);
+    opacity: var(--sx-p);
+  }
+  :where([data-sx-in] [data-sx-split-inner]), :where([data-sx-in] [data-sx-split-word]) { --sx-p: 1; }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-split-inner]), :where([data-sx-split-word]) { translate: none; opacity: var(--sx-p); transition-duration: 0.3s; }
+  }`);
+/** Text for screen readers only: the part's real words, read once and in order. */
+export const SR_ONLY = {
+    position: "absolute",
+    inlineSize: "1px",
+    blockSize: "1px",
+    margin: "-1px",
+    padding: 0,
+    overflow: "hidden",
+    clip: "rect(0 0 0 0)",
+    whiteSpace: "nowrap",
+    border: 0,
+};

package/dist/transitions/scroll/progress.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A pinned section (PinnedExpand, TextMaskZoom): a tall wrapper whose sticky
+ * stage stays on screen while the wrapper scrolls past. 0 when the wrapper's
+ * top reaches the top of the viewport, 1 when its bottom reaches the bottom.
+ * Native twin: `animation-range: contain 0% contain 100%`.
+ */
+export declare function pinProgress(top: number, height: number, viewport: number, insetTop?: number, insetBottom?: number): number;
+/**
+ * A stacked card is covered by the next one: 0 when the next card's top
+ * enters at the bottom of the viewport, 1 when it reaches its sticky `stickTop`.
+ * Native twin: `animation-range: entry 0% cover calc(100vh - stickTop)` on the
+ * next card's view timeline.
+ */
+export declare function stackProgress(nextTop: number, stickTop: number, viewport: number, insetBottom?: number): number;

package/dist/transitions/scroll/progress.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// Scroll progress for the scroll compositions, as pure functions: the JS twins
+// of the native view-timeline ranges each part's CSS uses, for browsers (or
+// `overflow: hidden` ancestors) where the native timeline does not run.
+// All take px from getBoundingClientRect and the viewport height; `insetTop` /
+// `insetBottom` are the page's scroll-padding, which a native view timeline
+// leaves out of the viewport (see Reveal's scrubProgress).
+// ---------------------------------------------------------------------------
+const clamp01 = (n) => (n <= 0 ? 0 : n >= 1 ? 1 : n);
+/**
+ * A pinned section (PinnedExpand, TextMaskZoom): a tall wrapper whose sticky
+ * stage stays on screen while the wrapper scrolls past. 0 when the wrapper's
+ * top reaches the top of the viewport, 1 when its bottom reaches the bottom.
+ * Native twin: `animation-range: contain 0% contain 100%`.
+ */
+export function pinProgress(top, height, viewport, insetTop = 0, insetBottom = 0) {
+    const view = viewport - insetTop - insetBottom;
+    const travel = height - view;
+    return travel > 0 ? clamp01((insetTop - top) / travel) : top <= insetTop ? 1 : 0;
+}
+/**
+ * A stacked card is covered by the next one: 0 when the next card's top
+ * enters at the bottom of the viewport, 1 when it reaches its sticky `stickTop`.
+ * Native twin: `animation-range: entry 0% cover calc(100vh - stickTop)` on the
+ * next card's view timeline.
+ */
+export function stackProgress(nextTop, stickTop, viewport, insetBottom = 0) {
+    const bottom = viewport - insetBottom;
+    const travel = bottom - stickTop;
+    return travel > 0 ? clamp01((bottom - nextTop) / travel) : 1;
+}

package/dist/transitions/scroll/split.d.ts

@@ -0,0 +1,2 @@
+export { splitWords, lineStarts } from "../../text/split.js";
+export type { SplitPiece } from "../../text/split.js";

package/dist/transitions/scroll/split.js

@@ -0,0 +1,2 @@
+// SplitText's splitter now lives with the text effects (text/split.ts), shared with Text and the button labels.
+export { splitWords, lineStarts } from "../../text/split.js";

package/dist/transitions/scroll/useScrub.d.ts

@@ -0,0 +1,31 @@
+import { type RefObject } from "react";
+/** Viewport height and the page's scroll-padding, which a native view timeline leaves out. */
+export interface ScrollView {
+    readonly height: number;
+    readonly insetTop: number;
+    readonly insetBottom: number;
+}
+export interface ScrubTarget {
+    /** Gets `data-sx-scroll="js"` (and `--sx-p`, unless `apply` is given). */
+    readonly el: HTMLElement;
+    /** Its progress now, 0–1. */
+    readonly progress: (view: ScrollView) => number;
+    /** Write the progress as the part's own properties instead of `--sx-p`. */
+    readonly apply?: (p: number) => void;
+    /** Undo `apply` (the fallback is switched off or the part unmounts). */
+    readonly reset?: () => void;
+}
+export interface ScrubOptions {
+    /** Off: the part is not scroll-driven right now. */
+    readonly enabled?: boolean;
+    /** Does the native path work here? Default: `nativeScrollTimelineWorks(root)`. */
+    readonly native?: (root: HTMLElement) => boolean;
+    /** The progress written while the user prefers reduced motion. */
+    readonly reduced: number;
+}
+/**
+ * @param rootRef the part's outer element (watched for nearness, checked for scroll containers)
+ * @param targets called once the elements exist: who gets `--sx-p`, and how to measure it
+ * @param deps re-run when these change (the number of cards …)
+ */
+export declare function useScrubFallback(rootRef: RefObject<HTMLElement | null>, targets: () => readonly ScrubTarget[], options: ScrubOptions, deps: readonly unknown[]): void;

package/dist/transitions/scroll/useScrub.js

@@ -0,0 +1,90 @@
+"use client";
+// The JS fallback every scroll-driven part shares (Reveal trigger="scroll",
+// StackCards, PinnedExpand, TextMaskZoom). Their CSS animates with a native
+// view timeline; where that cannot run (no support, or an ancestor's
+// `overflow: hidden` makes a scroll container that never scrolls), this marks
+// each target `data-sx-scroll="js"` (its CSS animation stops) and applies the
+// progress from a measure, at most once per frame, only when it changed, and
+// only while the part is near the screen. By default it writes `--sx-p`
+// inline; a part can write its final properties itself (`apply`), which
+// restyles one element instead of everything under it (--sx-p inherits).
+import { useEffect } from "react";
+import { cancelFrame, frame } from "motion/react";
+import { nativeScrollTimelineWorks } from "../../backgrounds/hosts/useLayerNeeds.js";
+/**
+ * @param rootRef the part's outer element (watched for nearness, checked for scroll containers)
+ * @param targets called once the elements exist: who gets `--sx-p`, and how to measure it
+ * @param deps re-run when these change (the number of cards …)
+ */
+export function useScrubFallback(rootRef, targets, options, deps) {
+    const { enabled = true, native = nativeScrollTimelineWorks, reduced } = options;
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!enabled || !root || native(root))
+            return;
+        const list = targets();
+        for (const t of list)
+            t.el.setAttribute("data-sx-scroll", "js");
+        const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+        let near = true;
+        let view = { height: innerHeight, insetTop: 0, insetBottom: 0 };
+        const readView = () => {
+            const s = getComputedStyle(document.documentElement);
+            view = {
+                height: innerHeight,
+                insetTop: Number.parseFloat(s.scrollPaddingTop) || 0,
+                insetBottom: Number.parseFloat(s.scrollPaddingBottom) || 0,
+            };
+        };
+        // Every read before any write (a write between two reads would force a
+        // layout each time), and only the values that changed: of a stack of cards
+        // one moves at a time, the rest sit at 0 or 1.
+        const written = [];
+        const measure = () => {
+            const values = list.map((t) => Math.round((reduce.matches ? reduced : t.progress(view)) * 10000) / 10000);
+            list.forEach((t, i) => {
+                const value = values[i];
+                if (written[i] === value)
+                    return;
+                written[i] = value;
+                if (t.apply)
+                    t.apply(value);
+                else
+                    t.el.style.setProperty("--sx-p", String(value));
+            });
+        };
+        const schedule = () => {
+            if (near)
+                frame.read(measure);
+        };
+        const onResize = () => {
+            readView();
+            schedule();
+        };
+        const io = typeof IntersectionObserver === "undefined"
+            ? undefined
+            : new IntersectionObserver((entries) => {
+                near = entries.some((e) => e.isIntersecting);
+                schedule();
+            }, { rootMargin: "25% 0px" });
+        io?.observe(root);
+        readView();
+        measure();
+        window.addEventListener("scroll", schedule, { passive: true, capture: true });
+        window.addEventListener("resize", onResize);
+        reduce.addEventListener("change", schedule);
+        return () => {
+            io?.disconnect();
+            cancelFrame(measure);
+            window.removeEventListener("scroll", schedule, { capture: true });
+            window.removeEventListener("resize", onResize);
+            reduce.removeEventListener("change", schedule);
+            for (const t of list) {
+                t.el.removeAttribute("data-sx-scroll");
+                t.el.style.removeProperty("--sx-p");
+                t.reset?.();
+            }
+        };
+        // targets / native are read once per run; deps say when to run again
+    }, [rootRef, enabled, reduced, ...deps]);
+}

package/dist/transitions/shader/program.d.ts

@@ -0,0 +1,56 @@
+import type { GpuContext, Rgba01 } from "../../backgrounds/types.js";
+import { type Linked } from "../../backgrounds/runtime/webgl.js";
+import type { ShaderTransition } from "../types.js";
+/** The uniforms every shader transition gets without declaring them. */
+export declare const SHADER_UNIFORMS: readonly ["u_from", "u_to", "u_progress", "u_resolution", "u_origin", "u_rtl"];
+export declare const SHADER_HEADER = "#ifdef GL_FRAGMENT_PRECISION_HIGH\nprecision highp float;\n#else\nprecision mediump float;\n#endif\nvarying vec2 v_uv;\nuniform sampler2D u_from;\nuniform sampler2D u_to;\nuniform float u_progress;\nuniform vec2 u_resolution;\nuniform vec2 u_origin;\nuniform float u_rtl;\nconst float SX_PI = 3.14159265;\nvec4 getFrom(vec2 uv) { return texture2D(u_from, uv); }\nvec4 getTo(vec2 uv) { return texture2D(u_to, uv); }\nfloat sx_aspect() { return u_resolution.x / u_resolution.y; }\nvec2 sx_dir(vec2 d) { return vec2(u_rtl > 0.5 ? -d.x : d.x, d.y); }\n\nfloat sx_hash(vec2 p) {\n  vec3 p3 = fract(vec3(p.xyx) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfloat sx_noise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(sx_hash(i), sx_hash(i + vec2(1.0, 0.0)), u.x),\n             mix(sx_hash(i + vec2(0.0, 1.0)), sx_hash(i + vec2(1.0, 1.0)), u.x), u.y);\n}\nfloat sx_fbm(vec2 p) {\n  float v = 0.0;\n  float a = 0.5;\n  for (int i = 0; i < 5; i++) {\n    v += a * sx_noise(p);\n    p = p * 2.02 + vec2(1.7, 9.2);\n    a *= 0.5;\n  }\n  return v / 0.97;\n}\n";
+export declare const SHADER_FOOTER = "\nvoid main() {\n  gl_FragColor = transition(v_uv);\n}";
+/** The full fragment source of a transition. */
+export declare const fragmentSource: (fragment: string) => string;
+/** Played instead of any look while the user prefers reduced motion. */
+export declare const CROSSFADE_FRAGMENT = "\nvec4 transition(vec2 uv) {\n  return mix(getFrom(uv), getTo(uv), u_progress);\n}\n";
+/** One frame: the textures (null = not ready: drawn as transparent) and where the host is. */
+export interface ShaderDraw {
+    readonly width: number;
+    readonly height: number;
+    readonly progress: number;
+    readonly from: WebGLTexture | null;
+    readonly to: WebGLTexture | null;
+    readonly map: WebGLTexture | null;
+    /** 0–1, y up. */
+    readonly origin: readonly [number, number];
+    readonly rtl: boolean;
+    readonly colors: readonly Rgba01[];
+    /** The page's scroll speed, for fragments that declare `u_scroll`. */
+    readonly scroll: number;
+}
+export interface ShaderState {
+    readonly linked: Linked;
+    readonly triangle: {
+        draw(): void;
+        dispose(): void;
+    };
+    /** 1×1 transparent: what a picture that is not ready yet looks like. */
+    readonly blank: WebGLTexture;
+    readonly colorLocs: readonly (WebGLUniformLocation | null)[];
+    /** The fragment samples `u_map` (and says whether it has one with `u_hasMap`). */
+    readonly usesMap: boolean;
+    readonly flagsMap: boolean;
+    /** The fragment reads the scroll speed: the host redraws while it changes. */
+    readonly usesScroll: boolean;
+}
+/** Settings for a texture holding a picture: no mipmaps (any size works in WebGL1), clamped, linear. */
+export declare function pictureTexture(gl: GpuContext, texture: WebGLTexture): void;
+/**
+ * Compiles a transition's fragment (throws `WebglUnavailable` when it does not
+ * compile) and draws frames with it. Its own uniforms are set once; the
+ * standard ones and the textures per frame.
+ */
+export declare function transitionProgram(effect: Pick<ShaderTransition, "fragment" | "uniforms" | "colors">): {
+    init(gl: GpuContext): ShaderState;
+    draw(gl: GpuContext, s: ShaderState, d: ShaderDraw): void;
+    dispose(gl: GpuContext, s: ShaderState): void;
+};
+export type TransitionProgram = ReturnType<typeof transitionProgram>;
+/** Whether a fragment reads the page's scroll speed (the host then follows it). */
+export declare const readsScroll: (fragment: string) => boolean;

package/dist/transitions/shader/program.js

@@ -0,0 +1,132 @@
+// ---------------------------------------------------------------------------
+// The GPU side of a shader transition: what every fragment gets, and the
+// program that draws one frame from two textures. Needs a GL context (the
+// tests pass a fake one); no DOM, no React.
+//
+// A transition's fragment defines `vec4 transition(vec2 uv)` (premultiplied
+// colour) and may use:
+//
+//   getFrom(uv) / getTo(uv)  the two pictures, already cropped to the canvas
+//                            (cover fit), so uv 0–1 is the whole picture
+//   u_progress               0 = only `from`, 1 = only `to`
+//   u_resolution             canvas size, px
+//   u_origin                 0–1, y up: the last tap on the host (the centre until then)
+//   u_rtl                    1 in a right-to-left context
+//   u_scroll                 only if declared: the page's scroll speed, viewport heights per
+//                            second, + when scrolling down, smoothed (shader/scrollSpeed.ts)
+//   sx_aspect()              width / height
+//   sx_dir(d)                a reading-order direction made physical (x mirrored under RTL)
+//   sx_hash / sx_noise / sx_fbm, SX_PI
+// ---------------------------------------------------------------------------
+import { FULLSCREEN_VERTEX, declaredUniforms, fullscreenTriangle, link, setUniform, } from "../../backgrounds/runtime/webgl.js";
+import { GLSL_NOISE } from "../../backgrounds/effects/shaderKit.js";
+/** The uniforms every shader transition gets without declaring them. */
+export const SHADER_UNIFORMS = ["u_from", "u_to", "u_progress", "u_resolution", "u_origin", "u_rtl"];
+export const SHADER_HEADER = `#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+varying vec2 v_uv;
+uniform sampler2D u_from;
+uniform sampler2D u_to;
+uniform float u_progress;
+uniform vec2 u_resolution;
+uniform vec2 u_origin;
+uniform float u_rtl;
+const float SX_PI = 3.14159265;
+vec4 getFrom(vec2 uv) { return texture2D(u_from, uv); }
+vec4 getTo(vec2 uv) { return texture2D(u_to, uv); }
+float sx_aspect() { return u_resolution.x / u_resolution.y; }
+vec2 sx_dir(vec2 d) { return vec2(u_rtl > 0.5 ? -d.x : d.x, d.y); }
+${GLSL_NOISE}`;
+export const SHADER_FOOTER = `
+void main() {
+  gl_FragColor = transition(v_uv);
+}`;
+/** The full fragment source of a transition. */
+export const fragmentSource = (fragment) => SHADER_HEADER + fragment + SHADER_FOOTER;
+/** Played instead of any look while the user prefers reduced motion. */
+export const CROSSFADE_FRAGMENT = `
+vec4 transition(vec2 uv) {
+  return mix(getFrom(uv), getTo(uv), u_progress);
+}
+`;
+/** A 1×1 texture of one premultiplied colour. */
+function solidTexture(gl, rgba) {
+    const texture = gl.createTexture();
+    if (!texture)
+        throw new Error("could not create a texture");
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array(rgba));
+    return texture;
+}
+/** Settings for a texture holding a picture: no mipmaps (any size works in WebGL1), clamped, linear. */
+export function pictureTexture(gl, texture) {
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+}
+const bind = (gl, where, texture, unit) => {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    if (where)
+        gl.uniform1i(where, unit);
+};
+/**
+ * Compiles a transition's fragment (throws `WebglUnavailable` when it does not
+ * compile) and draws frames with it. Its own uniforms are set once; the
+ * standard ones and the textures per frame.
+ */
+export function transitionProgram(effect) {
+    const declared = new Set(declaredUniforms(effect.fragment));
+    return {
+        init(gl) {
+            const linked = link(gl, FULLSCREEN_VERTEX, fragmentSource(effect.fragment));
+            const triangle = fullscreenTriangle(gl);
+            const blank = solidTexture(gl, [0, 0, 0, 0]);
+            pictureTexture(gl, blank);
+            gl.useProgram(linked.program);
+            for (const [name, value] of Object.entries(effect.uniforms))
+                setUniform(gl, linked.loc(name), value);
+            return {
+                linked,
+                triangle,
+                blank,
+                colorLocs: effect.colors.map((_, i) => linked.loc(`u_c${i}`)),
+                usesMap: declared.has("u_map"),
+                flagsMap: declared.has("u_hasMap"),
+                usesScroll: declared.has("u_scroll"),
+            };
+        },
+        draw(gl, s, d) {
+            const { linked } = s;
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            gl.viewport(0, 0, d.width, d.height);
+            gl.useProgram(linked.program);
+            bind(gl, linked.loc("u_from"), d.from ?? s.blank, 0);
+            bind(gl, linked.loc("u_to"), d.to ?? s.blank, 1);
+            if (s.usesMap)
+                bind(gl, linked.loc("u_map"), d.map ?? s.blank, 2);
+            if (s.flagsMap)
+                setUniform(gl, linked.loc("u_hasMap"), d.map ? 1 : 0);
+            setUniform(gl, linked.loc("u_progress"), d.progress);
+            setUniform(gl, linked.loc("u_resolution"), [d.width, d.height]);
+            setUniform(gl, linked.loc("u_origin"), d.origin);
+            setUniform(gl, linked.loc("u_rtl"), d.rtl ? 1 : 0);
+            if (s.usesScroll)
+                setUniform(gl, linked.loc("u_scroll"), d.scroll);
+            s.colorLocs.forEach((where, i) => setUniform(gl, where, d.colors[i] ?? [0, 0, 0, 1]));
+            s.triangle.draw();
+        },
+        dispose(gl, s) {
+            gl.deleteTexture(s.blank);
+            s.triangle.dispose();
+            s.linked.dispose();
+        },
+    };
+}
+/** Whether a fragment reads the page's scroll speed (the host then follows it). */
+export const readsScroll = (fragment) => declaredUniforms(fragment).includes("u_scroll");

package/dist/transitions/shader/scrollSpeed.d.ts

@@ -0,0 +1,11 @@
+/** Fastest speed reported, viewport heights per second either way. */
+export declare const MAX_SCROLL_SPEED = 4;
+/**
+ * One easing step: from the reported speed towards the measured one, at a
+ * rate that does not depend on the frame rate (half-way in about 60 ms).
+ */
+export declare function smoothSpeed(current: number, measured: number, dtMs: number): number;
+/** The current speed (0 at rest). */
+export declare function scrollSpeed(): number;
+/** `changed` runs every frame while the speed moves (and once more when it reaches 0). */
+export declare function watchScrollSpeed(changed: () => void): () => void;

package/dist/transitions/shader/scrollSpeed.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// The page's scroll speed, for shaders that react to it (`u_scroll`, e.g.
+// ScrollDistort). One passive window listener however many pictures listen;
+// a frame loop runs only while the page scrolls and the speed settles back to
+// zero, then stops.
+//
+// Units: viewport heights per second, positive when scrolling down, eased so
+// a single wheel tick does not jerk. `smoothSpeed` is the pure step (tested).
+// ---------------------------------------------------------------------------
+import { onFrame } from "../../backgrounds/runtime/clock.js";
+/** Fastest speed reported, viewport heights per second either way. */
+export const MAX_SCROLL_SPEED = 4;
+/** Below this the speed counts as stopped. */
+const REST = 0.002;
+/**
+ * One easing step: from the reported speed towards the measured one, at a
+ * rate that does not depend on the frame rate (half-way in about 60 ms).
+ */
+export function smoothSpeed(current, measured, dtMs) {
+    const target = Math.max(-MAX_SCROLL_SPEED, Math.min(MAX_SCROLL_SPEED, measured));
+    const k = 1 - Math.pow(0.5, dtMs / 60);
+    const next = current + (target - current) * k;
+    return Math.abs(next) < REST && Math.abs(target) < REST ? 0 : next;
+}
+/** Scroll events further apart than this mean the page stopped in between. */
+const GAP_MS = 100;
+const listeners = new Set();
+let speed = 0;
+/** The speed the scroll events measured, and the last event. */
+let measured = 0;
+let lastY = 0;
+let lastT = -Infinity;
+let stop = null;
+const tick = (deltaMs) => {
+    // no scroll event for a while: the page has stopped, ease back to 0
+    if (performance.now() - lastT > GAP_MS)
+        measured = 0;
+    speed = smoothSpeed(speed, measured, deltaMs);
+    for (const listener of listeners)
+        listener();
+    if (speed === 0 && measured === 0) {
+        stop?.();
+        stop = null;
+    }
+};
+// Speed is measured between scroll events (distance over time), never from
+// one frame's position: the first frame after an event would see no movement.
+const onScroll = () => {
+    const now = performance.now();
+    const y = window.scrollY;
+    const dt = now - lastT;
+    measured = dt > 0 && dt <= GAP_MS ? (y - lastY) / Math.max(1, window.innerHeight) / (dt / 1000) : 0;
+    lastY = y;
+    lastT = now;
+    stop ?? (stop = onFrame(tick));
+};
+/** The current speed (0 at rest). */
+export function scrollSpeed() {
+    return speed;
+}
+/** `changed` runs every frame while the speed moves (and once more when it reaches 0). */
+export function watchScrollSpeed(changed) {
+    if (listeners.size === 0)
+        window.addEventListener("scroll", onScroll, { passive: true });
+    listeners.add(changed);
+    return () => {
+        listeners.delete(changed);
+        if (listeners.size > 0)
+            return;
+        window.removeEventListener("scroll", onScroll);
+        stop?.();
+        stop = null;
+        speed = 0;
+        measured = 0;
+    };
+}