@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/backgrounds/effects/scroll/cinematicReveal.js

@@ -0,0 +1,82 @@
+import { defineCssEffect, duration } from "../define.js";
+export const CINEMATIC_REVEAL_META = {
+    id: "cinematic-reveal",
+    label: "Cinematic Hero Section In-View Animation",
+    category: "scroll",
+    family: "css",
+    cost: { kb: "<1 KB (no GSAP / Motion)", cpu: 1, gpu: 1 },
+    tier: "all",
+    note: "Plays once when it first comes into view (the runtime's off-screen pause holds it until then).",
+};
+// A one-shot sequence: letterbox bars open from the middle, a glow settles
+// in from a slight zoom, and a light sweep crosses once. Nothing here starts
+// it: the root pauses every CSS animation while it is off screen, so the
+// sequence waits at its first frame until the section scrolls into view.
+// The resting styles ARE the final frame (fill-mode both shows the first frame
+// before the start), so under reduced motion `animation: none` shows the
+// finished picture instead of closed bars.
+const CSS = `@layer components {
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="glow"]) {
+    position: absolute;
+    inset: -10%;
+    background: radial-gradient(ellipse 60% 55% at 50% 55%, var(--sx-bg-glow), transparent 70%);
+    animation: sx-bg-reveal-glow ${duration("1.9s")} cubic-bezier(0.2, 0.7, 0.2, 1) calc(var(--sx-bg-delay) + 0.3s) both;
+  }
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="sweep"]) {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    inline-size: 40%;
+    background: linear-gradient(100deg, transparent, color-mix(in oklab, var(--sx-bg-glow) 60%, transparent), transparent);
+    opacity: 0;
+    animation: sx-bg-reveal-sweep ${duration("1.4s")} ease-in-out calc(var(--sx-bg-delay) + 1s) both;
+  }
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="bar-start"]),
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="bar-end"]) {
+    position: absolute;
+    inset-inline: 0;
+    block-size: 50.5%;
+    background: var(--sx-bg-bars);
+    transform: scaleY(0);
+    animation: sx-bg-reveal-bar ${duration("1.2s")} cubic-bezier(0.7, 0, 0.2, 1) var(--sx-bg-delay) both;
+  }
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="bar-start"]) {
+    inset-block-start: 0;
+    transform-origin: 50% 0;
+  }
+  :where([data-sx-bg="cinematic-reveal"] [data-sx-bg-part="bar-end"]) {
+    inset-block-end: 0;
+    transform-origin: 50% 100%;
+  }
+  :where([dir="rtl"] [data-sx-bg="cinematic-reveal"] [data-sx-bg-part="sweep"]) {
+    scale: -1 1;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-reduce="still"] [data-sx-bg="cinematic-reveal"] [data-sx-bg-part]) {
+      animation: none;
+    }
+  }
+  @keyframes sx-bg-reveal-bar {
+    from { transform: scaleY(1); }
+  }
+  @keyframes sx-bg-reveal-glow {
+    from { transform: scale(1.25); opacity: 0; }
+  }
+  @keyframes sx-bg-reveal-sweep {
+    from { transform: translate3d(-100%, 0, 0); opacity: 0; }
+    30% { opacity: 1; }
+    to { transform: translate3d(260%, 0, 0); opacity: 0; }
+  }
+}`;
+/** Letterbox bars open, a glow settles, a light sweeps across: once, when the section comes into view. */
+export function cinematicReveal(options = {}) {
+    return defineCssEffect(CINEMATIC_REVEAL_META, CSS, options, {
+        vars: {
+            "--sx-bg-delay": `${options.delay ?? 0}s`,
+            "--sx-bg-bars": options.bars ?? "var(--color-sx-secondary)",
+            "--sx-bg-glow": options.glow ?? "color-mix(in oklab, var(--color-sx-accent) 45%, transparent)",
+        },
+        // back to front: glow, sweep, then the two bars on top
+        nodes: [{ part: "glow", vars: {} }, { part: "sweep", vars: {} }, { part: "bar-start", vars: {} }, { part: "bar-end", vars: {} }],
+    });
+}

package/dist/backgrounds/effects/scroll/cinematicReveal.schema.d.ts

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

package/dist/backgrounds/effects/scroll/cinematicReveal.schema.js

@@ -0,0 +1,14 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField } from "../../../schema/common.js";
+export const CINEMATIC_REVEAL_SCHEMA = defineSchema()({
+    id: "cinematic-reveal",
+    family: "background",
+    factory: "cinematicReveal",
+    fields: {
+        ...layerFields(),
+        speed: { ...speedField(), autoNote: "1 (a 2.4 s sequence)" },
+        delay: { kind: "number", label: "Delay", min: 0, max: 5, step: 0.1, unit: "s", default: 0, help: "After coming into view." },
+        bars: { kind: "color", label: "Letterbox bars", default: "var(--color-sx-secondary)" },
+        glow: { kind: "color", label: "Glow", default: "color-mix(in oklab, var(--color-sx-accent) 45%, transparent)" },
+    },
+});

package/dist/backgrounds/effects/scroll/parallax.d.ts

@@ -0,0 +1,14 @@
+import type { CssEffect, EffectMeta, LayerOptions, ScrollRange } from "../../types.js";
+export declare const PARALLAX_META: EffectMeta;
+export interface ParallaxOptions extends LayerOptions {
+    /** Number of depth planes, far to near (1–5). */
+    readonly planes?: number;
+    /** Largest shift, as a fraction of the layer height. */
+    readonly depth?: number;
+    /** `cover` (default) for a section mid-page, `exit` for a hero at the top. */
+    readonly range?: ScrollRange;
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** Planes of dots at different depths that move apart as the page scrolls. */
+export declare function parallax(options?: ParallaxOptions): CssEffect;

package/dist/backgrounds/effects/scroll/parallax.js

@@ -0,0 +1,60 @@
+import { between, rng, round } from "../../runtime/rng.js";
+import { scrollVars } from "../../runtime/scroll.js";
+import { defineCssEffect } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+export const PARALLAX_META = {
+    id: "parallax",
+    label: "Parallax layers",
+    category: "scroll",
+    family: "css",
+    cost: { kb: "<1 KB", cpu: 1, gpu: 1 },
+    tier: "all",
+    needs: { scroll: true },
+    note: "Transform-only; one shared scroll listener for every layer on the page.",
+};
+// Planes of dots, each a tiled radial gradient. As the box scrolls, far
+// planes drift down against the scroll (they lag: distance) and near ones
+// up with it (they lead), by `--depth` × how far the box is from rest. Each
+// plane overhangs the layer by its depth, so no edge is ever bared.
+const CSS = `@layer components {
+  :where([data-sx-bg="parallax"] [data-sx-bg-part="plane"]) {
+    position: absolute;
+    inset-inline: 0;
+    inset-block: calc(-1 * var(--reach));
+    background-image: radial-gradient(circle, var(--c) var(--dot), transparent calc(var(--dot) + 0.6px));
+    background-size: var(--gap) var(--gap);
+    background-position: var(--ox) var(--oy);
+    opacity: var(--o);
+    transform: translate3d(0, calc((var(--sx-bg-p) - var(--sx-bg-p0)) * var(--depth)), 0);
+  }
+}`;
+/** Planes of dots at different depths that move apart as the page scrolls. */
+export function parallax(options = {}) {
+    const r = rng(options.seed ?? 2);
+    const planes = Math.min(5, Math.max(1, Math.round(options.planes ?? 3)));
+    const depth = Math.min(1, Math.max(0, options.depth ?? 0.45)) * 100;
+    const palette = paletteVars(options.colors);
+    const nodes = [];
+    for (let i = 0; i < planes; i++) {
+        const t = planes === 1 ? 1 : i / (planes - 1); // 0 = far, 1 = near
+        // far planes lag (+), near planes lead (−)
+        const shift = round(depth * (0.6 - t * 1.1), 1);
+        nodes.push({
+            part: "plane",
+            vars: {
+                "--c": paletteRef(i, palette.count),
+                "--depth": `${shift}cqb`,
+                "--reach": `${round(Math.abs(shift) + 2, 1)}cqb`,
+                "--dot": `${round(1 + t * 2.5, 1)}px`,
+                "--gap": `${round(22 + t * 34, 0)}px`,
+                "--ox": `${round(between(r, 0, 40), 0)}px`,
+                "--oy": `${round(between(r, 0, 40), 0)}px`,
+                "--o": round(0.35 + t * 0.5),
+            },
+        });
+    }
+    return defineCssEffect(PARALLAX_META, CSS, options, {
+        vars: { ...palette.vars, ...scrollVars(options.range ?? "cover") },
+        nodes,
+    });
+}

package/dist/backgrounds/effects/scroll/parallax.schema.d.ts

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

package/dist/backgrounds/effects/scroll/parallax.schema.js

@@ -0,0 +1,15 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, seedField, colorsField } from "../../../schema/common.js";
+export const PARALLAX_SCHEMA = defineSchema()({
+    id: "parallax",
+    family: "background",
+    factory: "parallax",
+    fields: {
+        ...layerFields(),
+        planes: { kind: "integer", label: "Depth planes", min: 1, max: 5, default: 3 },
+        depth: { kind: "number", label: "Largest shift", min: 0, max: 1, step: 0.01, default: 0.45, help: "A fraction of the layer height." },
+        range: { kind: "choice", label: "Scroll range", values: ["cover", "exit"], labels: { "cover": "While the section crosses the screen", "exit": "From the top of the page (a hero)" }, default: "cover" },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 60%, var(--color-sx-secondary))"], 1, 6) },
+        seed: seedField(2),
+    },
+});

package/dist/backgrounds/effects/scroll/scrollColor.d.ts

@@ -0,0 +1,10 @@
+import type { CssEffect, EffectMeta, LayerOptions, ScrollRange } from "../../types.js";
+export declare const SCROLL_COLOR_META: EffectMeta;
+export interface ScrollColorOptions extends LayerOptions {
+    /** The colours to pass through, first to last (2–6). */
+    readonly colors?: readonly string[];
+    /** `cover` (default): first colour as the box enters, last as it leaves. `exit`: from the top of the page. */
+    readonly range?: ScrollRange;
+}
+/** The background colour changes as the section scrolls through the viewport. */
+export declare function scrollColor(options?: ScrollColorOptions): CssEffect;

package/dist/backgrounds/effects/scroll/scrollColor.js

@@ -0,0 +1,41 @@
+import { scrollVars } from "../../runtime/scroll.js";
+import { defineCssEffect } from "../define.js";
+export const SCROLL_COLOR_META = {
+    id: "scroll-color",
+    label: "Change background colour with GSAP ScrollTrigger",
+    category: "scroll",
+    family: "css",
+    cost: { kb: "<1 KB (no GSAP)", cpu: 1, gpu: 1 },
+    tier: "all",
+    needs: { scroll: true },
+    note: "No GSAP: stacked colour planes cross-fade on the shared scroll progress (opacity only).",
+};
+// One full-bleed plane per colour, stacked. Plane i fades in over its share
+// of the scroll: opacity = clamp(0, p × (n − 1) − (i − 1), 1), so exactly one
+// pair is cross-fading at any moment. Opacity only, never a repainted
+// background colour. The first plane uses i = −1 and is always opaque.
+const CSS = `@layer components {
+  :where([data-sx-bg="scroll-color"] [data-sx-bg-part="color"]) {
+    position: absolute;
+    inset: 0;
+    background: var(--c);
+    opacity: clamp(0, calc(var(--sx-bg-p) * var(--sx-bg-steps) - var(--i)), 1);
+  }
+}`;
+const DEFAULT_COLORS = [
+    "var(--color-sx-secondary)",
+    "color-mix(in oklab, var(--color-sx-accent) 35%, var(--color-sx-secondary))",
+    "color-mix(in oklab, var(--color-sx-primary) 45%, var(--color-sx-secondary))",
+];
+/** The background colour changes as the section scrolls through the viewport. */
+export function scrollColor(options = {}) {
+    const colors = options.colors && options.colors.length >= 2 ? options.colors.slice(0, 6) : DEFAULT_COLORS;
+    const nodes = colors.map((c, i) => ({
+        part: "color",
+        vars: { "--c": c, "--i": i === 0 ? -1 : i - 1 },
+    }));
+    return defineCssEffect(SCROLL_COLOR_META, CSS, options, {
+        vars: { ...scrollVars(options.range ?? "cover"), "--sx-bg-steps": colors.length - 1 },
+        nodes,
+    });
+}

package/dist/backgrounds/effects/scroll/scrollColor.schema.d.ts

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

package/dist/backgrounds/effects/scroll/scrollColor.schema.js

@@ -0,0 +1,25 @@
+import { defineSchema } from "../../../schema/define.js";
+import { colorsField, layerFields } from "../../../schema/common.js";
+export const SCROLL_COLOR_SCHEMA = defineSchema()({
+    id: "scroll-color",
+    family: "background",
+    factory: "scrollColor",
+    fields: {
+        ...layerFields(),
+        colors: {
+            ...colorsField([
+                "var(--color-sx-secondary)",
+                "color-mix(in oklab, var(--color-sx-accent) 35%, var(--color-sx-secondary))",
+                "color-mix(in oklab, var(--color-sx-primary) 45%, var(--color-sx-secondary))",
+            ], 2, 6),
+            help: "Passed through first to last.",
+        },
+        range: {
+            kind: "choice",
+            label: "Range",
+            values: ["cover", "exit"],
+            labels: { cover: "While the section crosses the screen", exit: "From the top of the page" },
+            default: "cover",
+        },
+    },
+});

package/dist/backgrounds/effects/scroll/scrollMorph.d.ts

@@ -0,0 +1,13 @@
+import type { CssEffect, EffectMeta, LayerOptions, ScrollRange } from "../../types.js";
+export declare const SCROLL_MORPH_META: EffectMeta;
+export interface ScrollMorphOptions extends LayerOptions {
+    /** Number of dots (6–60). */
+    readonly count?: number;
+    /** `exit` (default) for a hero at the top of the page, `cover` for a section further down. */
+    readonly range?: ScrollRange;
+    /** Colours along the arc (up to 6). */
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** Dots that gather from a scatter into a circle, then fan out into a rainbow arc as the page scrolls. */
+export declare function scrollMorph(options?: ScrollMorphOptions): CssEffect;

package/dist/backgrounds/effects/scroll/scrollMorph.js

@@ -0,0 +1,104 @@
+import { between, rng, round } from "../../runtime/rng.js";
+import { scrollVars } from "../../runtime/scroll.js";
+import { defineCssEffect, liteMeta } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+export const SCROLL_MORPH_META = {
+    id: "scroll-morph",
+    label: "Scroll Morph Hero",
+    category: "scroll",
+    family: "css",
+    cost: { kb: "<1 KB (no Motion)", cpu: 2, gpu: 2 },
+    tier: "mid",
+    needs: { scroll: true },
+    note: "Scattered → circle → rainbow arc. Many elements restyled on every scroll frame.",
+};
+const SCROLL_MORPH_LITE_META = liteMeta({ ...SCROLL_MORPH_META, needs: {} }, "The circle stage, still: no scroll tracking.");
+/**
+ * Where the morph starts and how fast it runs, per range. The scroll
+ * progress p becomes s = (p − start) × rate; the dots go scattered → circle
+ * as s goes 0 → 1 and circle → arc as s goes 1 → 2.
+ * - exit: s = 2 once 60% of the hero has scrolled away.
+ * - cover: s runs 0 → 2 while p goes 0.2 → 0.8, the stretch where the box is in view.
+ */
+const PACE = {
+    exit: { start: 0, rate: 2 / 0.6 },
+    cover: { start: 0.2, rate: 2 / 0.6 },
+};
+// Each dot knows three positions: scattered (x0/y0, % of the layer from its
+// centre), on a circle and on an arc (x1/y1, x2/y2, in cqmin so both stay
+// round on any aspect ratio). Two clamped ramps blend them:
+// t1 = clamp(0, s, 1), t2 = clamp(0, s − 1, 1), and
+// pos = scattered × (1 − t1) + circle × (t1 − t2) + arc × t2.
+// One transform per dot, no keyframes. The light version pins t1 = 1, t2 = 0.
+const css = (id) => `@layer components {
+  :where([data-sx-bg="${id}"]) {
+    --s: calc((var(--sx-bg-p) - var(--sx-bg-start)) * var(--sx-bg-rate));
+    --t1: clamp(0, var(--s), 1);
+    --t2: clamp(0, calc(var(--s) - 1), 1);
+    --sx-bg-dir: 1;
+  }
+  :where([dir="rtl"] [data-sx-bg="${id}"]) {
+    --sx-bg-dir: -1;
+  }
+  :where([data-sx-bg="${id}"] [data-sx-bg-part="dot"]) {
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    inline-size: var(--sx-bg-size);
+    aspect-ratio: 1;
+    margin-block-start: calc(-0.5 * var(--sx-bg-size));
+    margin-inline-start: calc(-0.5 * var(--sx-bg-size));
+    border-radius: 50%;
+    background: var(--c);
+    transform: translate3d(
+      calc(var(--sx-bg-dir) * ((var(--x0) * (1 - var(--t1))) * 1cqi + (var(--x1) * (var(--t1) - var(--t2)) + var(--x2) * var(--t2)) * 1cqmin)),
+      calc((var(--y0) * (1 - var(--t1))) * 1cqb + (var(--y1) * (var(--t1) - var(--t2)) + var(--y2) * var(--t2)) * 1cqmin),
+      0
+    );
+  }
+}`;
+/** Colour at `u` (0–1) along the palette, mixed between neighbours: a smooth rainbow along the arc. */
+function blend(u, count) {
+    const pos = u * (count - 1);
+    const a = Math.min(count - 1, Math.floor(pos));
+    const f = pos - a;
+    if (f < 0.01 || a === count - 1)
+        return paletteRef(a, count);
+    return `color-mix(in oklab, ${paletteRef(a, count)} ${round((1 - f) * 100, 0)}%, ${paletteRef(a + 1, count)})`;
+}
+/** Dots that gather from a scatter into a circle, then fan out into a rainbow arc as the page scrolls. */
+export function scrollMorph(options = {}) {
+    const r = rng(options.seed ?? 31);
+    const count = Math.min(60, Math.max(6, Math.round(options.count ?? 28)));
+    const range = options.range ?? "exit";
+    const palette = paletteVars(options.colors);
+    const nodes = [];
+    for (let i = 0; i < count; i++) {
+        const u = i / (count - 1); // order along the arc, and around the circle
+        const ring = u * Math.PI * 2 - Math.PI / 2;
+        const arc = Math.PI + u * Math.PI; // left end, over the top, right end
+        nodes.push({
+            part: "dot",
+            vars: {
+                "--c": blend(u, palette.count),
+                "--x0": round(between(r, -46, 46), 1),
+                "--y0": round(between(r, -44, 44), 1),
+                "--x1": round(Math.cos(ring) * 28, 2),
+                "--y1": round(Math.sin(ring) * 28, 2),
+                "--x2": round(Math.cos(arc) * 42, 2),
+                "--y2": round(Math.sin(arc) * 42 + 18, 2),
+            },
+        });
+    }
+    const pace = PACE[range];
+    const shared = { ...palette.vars, "--sx-bg-size": "2.6cqmin" };
+    return defineCssEffect(SCROLL_MORPH_META, css(SCROLL_MORPH_META.id), options, {
+        vars: { ...shared, ...scrollVars(range), "--sx-bg-start": pace.start, "--sx-bg-rate": round(pace.rate, 4) },
+        nodes,
+        fallback: defineCssEffect(SCROLL_MORPH_LITE_META, css(SCROLL_MORPH_LITE_META.id), options, {
+            // p = 1 / rate makes s = 1: exactly the circle
+            vars: { ...shared, "--sx-bg-p": round(1 / pace.rate + pace.start, 4), "--sx-bg-start": pace.start, "--sx-bg-rate": round(pace.rate, 4) },
+            nodes,
+        }),
+    });
+}

package/dist/backgrounds/effects/scroll/scrollMorph.schema.d.ts

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

package/dist/backgrounds/effects/scroll/scrollMorph.schema.js

@@ -0,0 +1,14 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, seedField, colorsField } from "../../../schema/common.js";
+export const SCROLL_MORPH_SCHEMA = defineSchema()({
+    id: "scroll-morph",
+    family: "background",
+    factory: "scrollMorph",
+    fields: {
+        ...layerFields(),
+        count: { kind: "integer", label: "Dots", min: 6, max: 60, default: 28 },
+        range: { kind: "choice", label: "Scroll range", values: ["exit", "cover"], labels: { "exit": "From the top of the page (a hero)", "cover": "While the section crosses the screen" }, default: "exit" },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 60%, var(--color-sx-secondary))"], 1, 6) },
+        seed: seedField(31),
+    },
+});

package/dist/backgrounds/effects/scroll/scrollTimeline.d.ts

@@ -0,0 +1,10 @@
+import type { CssEffect, EffectMeta, LayerOptions } from "../../types.js";
+export declare const SCROLL_TIMELINE_META: EffectMeta;
+export interface ScrollTimelineOptions extends LayerOptions {
+    /** Number of colour orbs (1–6). */
+    readonly orbs?: number;
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** Colour orbs that cross the section and a light sweep that turns, all tied to scroll position. */
+export declare function scrollTimeline(options?: ScrollTimelineOptions): CssEffect;

package/dist/backgrounds/effects/scroll/scrollTimeline.js

@@ -0,0 +1,104 @@
+import { between, rng, round } from "../../runtime/rng.js";
+import { RESTING_SCROLL } from "../../runtime/scroll.js";
+import { defineCssEffect } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+export const SCROLL_TIMELINE_META = {
+    id: "scroll-timeline",
+    label: "Native CSS scroll-driven animations",
+    category: "scroll",
+    family: "css",
+    cost: { kb: "0 KB JS where supported", cpu: 1, gpu: 1 },
+    tier: "all",
+    needs: { scroll: "native" },
+    note: "Runs off the main thread where animation-timeline is supported; elsewhere --sx-scroll drives the same keyframes.",
+};
+/** Each animated part: [part name, keyframes name, keyframes body]. */
+const PARTS = [
+    ["orb", "sx-bg-scroll-orb", `
+    from { transform: translate3d(var(--x0), var(--y0), 0) scale(0.55); }
+    to { transform: translate3d(var(--x1), var(--y1), 0) scale(1.15); }`],
+    ["sweep", "sx-bg-scroll-sweep", `
+    from { transform: rotate(-60deg); }
+    to { transform: rotate(240deg); }`],
+];
+const part = (name) => `[data-sx-bg="scroll-timeline"] [data-sx-bg-part="${name}"]`;
+// One set of keyframes, two clocks:
+//  - native: the root declares a view timeline (`view-timeline`), the parts
+//    play along it (`animation-timeline`). No JS runs at all. The root, not
+//    the layer, owns the timeline because the root is a scroll container
+//    (overflow: hidden), and a view() timeline on a child would follow it.
+//  - fallback: where the native timeline cannot work (no support, or an
+//    `overflow: hidden` ancestor that never scrolls), the host marks the layer
+//    `data-sx-scroll="js"` and the runtime writes --sx-scroll. A paused 1 s
+//    animation with a delay of -progress seconds shows exactly that frame.
+// The fallback and the reduced-motion rule use a second keyframes name
+// (`-js`): Chrome does not rebuild an animation whose timeline switches from
+// a named view timeline to the document's, so only a new name restarts it.
+// Under reduced motion `still` both show the resting frame.
+const CSS = `@layer components {
+  :where([data-sx-bg-root]:has(> [data-sx-bg="scroll-timeline"])) {
+    view-timeline: --sx-bg-view block;
+  }
+  :where(${part("orb")}) {
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    inline-size: 70cqmax;
+    aspect-ratio: 1;
+    margin-block-start: -35cqmax;
+    margin-inline-start: -35cqmax;
+    border-radius: 50%;
+    background: radial-gradient(closest-side, var(--c), transparent);
+    opacity: 0.7;
+  }
+  :where(${part("sweep")}) {
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    inline-size: 160cqmax;
+    aspect-ratio: 1;
+    margin-block-start: -80cqmax;
+    margin-inline-start: -80cqmax;
+    background: conic-gradient(from 0deg, transparent, color-mix(in oklab, var(--sx-bg-c1) 35%, transparent) 25%, transparent 50%);
+  }
+${PARTS.map(([name, kf, body]) => `  :where(${part(name)}) {
+    animation: ${kf} auto linear both;
+    animation-timeline: --sx-bg-view;
+  }
+  :where([data-sx-bg="scroll-timeline"][data-sx-scroll="js"] [data-sx-bg-part="${name}"]) {
+    animation: ${kf}-js 1s linear both paused;
+    animation-delay: calc(var(--sx-scroll, ${RESTING_SCROLL.progress}) * -1s);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-sx-reduce="still"] ${part(name)}) {
+      animation: ${kf}-js 1s linear both paused;
+      animation-delay: -${RESTING_SCROLL.progress}s;
+    }
+  }
+  @keyframes ${kf} {${body}
+  }
+  @keyframes ${kf}-js {${body}
+  }`).join("\n")}
+}`;
+/** Colour orbs that cross the section and a light sweep that turns, all tied to scroll position. */
+export function scrollTimeline(options = {}) {
+    const r = rng(options.seed ?? 14);
+    const orbs = Math.min(6, Math.max(1, Math.round(options.orbs ?? 3)));
+    const palette = paletteVars(options.colors);
+    const cq = (n) => `${round(n, 1)}cqi`;
+    const nodes = [{ part: "sweep", vars: {} }];
+    for (let i = 0; i < orbs; i++) {
+        const side = i % 2 === 0 ? -1 : 1;
+        nodes.push({
+            part: "orb",
+            vars: {
+                "--c": paletteRef(i, palette.count),
+                "--x0": cq(side * between(r, 25, 45)),
+                "--y0": `${round(between(r, 10, 35), 1)}cqb`,
+                "--x1": cq(-side * between(r, 15, 40)),
+                "--y1": `${round(between(r, -35, -10), 1)}cqb`,
+            },
+        });
+    }
+    return defineCssEffect(SCROLL_TIMELINE_META, CSS, options, { vars: palette.vars, nodes });
+}

package/dist/backgrounds/effects/scroll/scrollTimeline.schema.d.ts

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

package/dist/backgrounds/effects/scroll/scrollTimeline.schema.js

@@ -0,0 +1,13 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, seedField, colorsField } from "../../../schema/common.js";
+export const SCROLL_TIMELINE_SCHEMA = defineSchema()({
+    id: "scroll-timeline",
+    family: "background",
+    factory: "scrollTimeline",
+    fields: {
+        ...layerFields(),
+        orbs: { kind: "integer", label: "Orbs", min: 1, max: 6, default: 3 },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 60%, var(--color-sx-secondary))"], 1, 6) },
+        seed: seedField(14),
+    },
+});

package/dist/backgrounds/effects/scroll/videoScrub.d.ts

@@ -0,0 +1,22 @@
+import type { EffectMeta, LayerOptions, MediaEffect, ScrollRange } from "../../types.js";
+export declare const VIDEO_SCRUB_META: EffectMeta;
+export interface VideoScrubOptions extends LayerOptions {
+    /** A video (one URL, or `{ src, type }` sources). Encode with frequent keyframes, or seeking stutters. */
+    readonly src?: string | readonly {
+        readonly src: string;
+        readonly type?: string;
+    }[];
+    /** Or an image sequence, one URL per frame, drawn on a canvas. Smoother than seeking a video. */
+    readonly frames?: readonly string[];
+    /** Shown before the first frame, on weaker devices and under reduced motion. */
+    readonly poster?: string;
+    readonly fit?: "cover" | "contain";
+    readonly position?: string;
+    /** `cover` (default): first frame as the box enters, last as it leaves. `exit`: from the top of the page. */
+    readonly range?: ScrollRange;
+}
+/**
+ * A video or image sequence whose current frame follows the scroll position.
+ * Weaker devices get the poster (or the first frame) as a still image.
+ */
+export declare function videoScrub(options?: VideoScrubOptions): MediaEffect;

package/dist/backgrounds/effects/scroll/videoScrub.js

@@ -0,0 +1,53 @@
+import { defineCssEffect, layerVars, liteMeta } from "../define.js";
+import { image } from "../media/media.js";
+export const VIDEO_SCRUB_META = {
+    id: "video-scrub",
+    label: "Video / image-sequence scrub on scroll",
+    category: "scroll",
+    family: "media",
+    cost: { kb: "your file (2–20 MB typical)", cpu: 2, gpu: 2 },
+    tier: "mid",
+    needs: { scroll: true },
+    note: "Apple-style product scroll. Very heavy download; frames load only once the layer is on screen.",
+};
+const VIDEO_SCRUB_LITE_META = liteMeta({ ...VIDEO_SCRUB_META, family: "css", needs: {} }, "No file at all: a quiet tinted surface until a poster or first frame is given.");
+const LITE_CSS = `@layer components {
+  :where([data-sx-bg="video-scrub-lite"]) {
+    background: linear-gradient(to bottom, color-mix(in oklab, var(--color-sx-accent) 12%, transparent), transparent);
+  }
+}`;
+/**
+ * A video or image sequence whose current frame follows the scroll position.
+ * Weaker devices get the poster (or the first frame) as a still image.
+ */
+export function videoScrub(options = {}) {
+    const fit = options.fit ?? "cover";
+    const still = options.poster ?? options.frames?.[0];
+    const fallback = still
+        ? image({ src: still, fit, loading: "eager", ...(options.position !== undefined ? { position: options.position } : {}), ...layerVarsOptions(options) })
+        : defineCssEffect(VIDEO_SCRUB_LITE_META, LITE_CSS, options);
+    const src = options.src ?? [];
+    return {
+        kind: "media",
+        meta: VIDEO_SCRUB_META,
+        media: {
+            type: "scrub",
+            sources: typeof src === "string" ? [{ src }] : src,
+            fit,
+            range: options.range ?? "cover",
+            ...(options.frames !== undefined ? { frames: options.frames } : {}),
+            ...(options.poster !== undefined ? { poster: options.poster } : {}),
+            ...(options.position !== undefined ? { position: options.position } : {}),
+        },
+        vars: layerVars(options),
+        fallback,
+    };
+}
+/** The shared layer options only (image() takes them too). */
+function layerVarsOptions(options) {
+    return {
+        ...(options.opacity !== undefined ? { opacity: options.opacity } : {}),
+        ...(options.blend !== undefined ? { blend: options.blend } : {}),
+        ...(options.mask !== undefined ? { mask: options.mask } : {}),
+    };
+}

package/dist/backgrounds/effects/scroll/videoScrub.schema.d.ts

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

package/dist/backgrounds/effects/scroll/videoScrub.schema.js

@@ -0,0 +1,16 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields } from "../../../schema/common.js";
+export const VIDEO_SCRUB_SCHEMA = defineSchema()({
+    id: "video-scrub",
+    family: "background",
+    factory: "videoScrub",
+    fields: {
+        ...layerFields(),
+        src: { kind: "text", label: "Video", url: true, autoNote: "none: the frames or the poster", help: "Encode with frequent keyframes, or seeking stutters." },
+        frames: { kind: "texts", label: "Image sequence", min: 2, max: 2000, url: true, autoNote: "none", help: "One address per frame: smoother than a video." },
+        poster: { kind: "text", label: "Poster", url: true, autoNote: "the first frame" },
+        fit: { kind: "choice", label: "Fit", values: ["cover", "contain"], default: "cover" },
+        position: { kind: "text", label: "Position", placeholder: "center", autoNote: "center", advanced: true },
+        range: { kind: "choice", label: "Scroll range", values: ["cover", "exit"], labels: { "cover": "While the section crosses the screen", "exit": "From the top of the page (a hero)" }, default: "cover" },
+    },
+});