@vysmo/scroll 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maesto LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @vysmo/scroll
+
+Three primitives that bind scroll progress to the rest of the ecosystem: `createScrollProgress` (raw 0–1 emitter), `createScrollTransition` (drives any `@vysmo/transitions` render), `createScrollEffect` (drives any `@vysmo/effects` params). One shared rAF-throttled observer underneath. Headless — you own the canvas.
+
+[Live demos](https://vysmo.com/scroll) · [Source](https://github.com/vysmodev)
+
+## Install
+
+```bash
+pnpm add @vysmo/scroll
+```
+
+For `createScrollTransition` / `createScrollEffect` you also need the corresponding consumer package:
+
+```bash
+pnpm add @vysmo/transitions   # for createScrollTransition
+pnpm add @vysmo/effects       # for createScrollEffect
+```
+
+## Quick start
+
+### Raw scroll progress
+
+```ts
+import { createScrollProgress } from "@vysmo/scroll";
+
+const handle = createScrollProgress({
+  element: document.querySelector(".hero")!,
+  onProgress: (p) => console.log(p), // 0..1 as the element sweeps the viewport
+});
+
+// later
+handle.destroy();
+```
+
+`progress` runs from `0` (element's top edge at the viewport's bottom) to `1` (element's bottom edge at the viewport's top). Pass `ease: (t) => …` to remap — anything from `@vysmo/easings` works.
+
+### Drive a transition with scroll
+
+```ts
+import { Runner, crossZoom } from "@vysmo/transitions";
+import { createScrollTransition } from "@vysmo/scroll";
+
+const canvas = document.querySelector("canvas")!;
+const runner = new Runner({ canvas });
+
+createScrollTransition({
+  section: document.querySelector(".scroll-section")!,
+  runner,
+  transition: crossZoom,
+  from: imageA,
+  to: imageB,
+});
+// renders crossZoom on every scroll tick, automatically passing progress
+```
+
+### Drive an effect with scroll
+
+```ts
+import { Runner, blur } from "@vysmo/effects";
+import { createScrollEffect } from "@vysmo/scroll";
+
+const runner = new Runner({ canvas });
+
+createScrollEffect({
+  section: document.querySelector(".hero")!,
+  runner,
+  effect: blur,
+  source: image,
+  paramsAt: (progress) => ({ radius: progress * 20 }), // unblur as user scrolls down
+});
+```
+
+## Zone helpers
+
+Most scroll-driven UIs don't want a single linear 0..1 — they want phases (intro → hold → outro). The `zones.ts` helpers compose:
+
+```ts
+import { scrollPlateau, scrollRange, scrollZones, smoothstep } from "@vysmo/scroll";
+
+scrollRange(0.2, 0.8);          // remap [0.2, 0.8] → [0, 1]; clamp outside
+scrollPlateau(0.4, 0.6);        // 0..1 with a flat 1.0 plateau between [0.4, 0.6]
+scrollZones(0.2, 0.8);          // inverse of plateau — peaks at the edges, 0 in the middle
+smoothstep;                     // t² (3 - 2t) — common easing for scroll
+```
+
+All return plain `(progress: number) => number` functions — pipe through `createScrollProgress`'s `ease` option, or use directly.
+
+## Shared observer
+
+Every primitive registers with one rAF-throttled `IntersectionObserver` + `scroll` listener — N elements cost one rAF tick per frame, not N. Access directly if you need it:
+
+```ts
+import { sharedScrollObserver } from "@vysmo/scroll";
+
+const obs = sharedScrollObserver();
+obs.subscribe(element, { onScroll: (rect, vp) => /* ... */ });
+```
+
+## Characteristics
+
+- **DOM-only.** Browser scrolling is the substrate; no Node fallback (the SSR test asserts the module loads, not that it functions without DOM).
+- **Tiny.** ~2 KB gzipped for the full bundle; ~1 KB for `createScrollProgress` alone.
+- **Tree-shakable.** `createScrollTransition` and `createScrollEffect` only pull in their respective peer libraries' types.
+- **One rAF.** Observer is shared across all primitives.
+- **SSR-safe at module load.** Guarded `typeof window` checks; observer is lazy-instantiated.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createScrollProgress } from "./progress.js";
+export { createScrollTransition } from "./scroll-transition.js";
+export type { ScrollTransitionOptions } from "./scroll-transition.js";
+export { createScrollEffect } from "./scroll-effect.js";
+export type { ScrollEffectOptions } from "./scroll-effect.js";
+export { sharedScrollObserver, ScrollObserver } from "./observer.js";
+export type { ScrollSubscriber } from "./observer.js";
+export { scrollPlateau, scrollRange, scrollZones, smoothstep } from "./zones.js";
+export type { EaseFn, Handle, ScrollProgressOptions } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACjF,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createScrollProgress } from "./progress.js";
+export { createScrollTransition } from "./scroll-transition.js";
+export { createScrollEffect } from "./scroll-effect.js";
+export { sharedScrollObserver, ScrollObserver } from "./observer.js";
+export { scrollPlateau, scrollRange, scrollZones, smoothstep } from "./zones.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/observer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared rAF-throttled scroll / resize observer. Every primitive in this
+ * package (progress, parallax, sticky-pin, horizontal-section) registers
+ * its element here; the observer keeps one passive `scroll` listener on
+ * `window` for the lifetime of any subscription and tears it down once
+ * the last subscriber unsubscribes.
+ *
+ * Safe to import at module load: no window access happens until
+ * `subscribe()` is called.
+ */
+export interface ScrollSubscriber {
+    onScroll(rect: DOMRect, viewport: {
+        readonly width: number;
+        readonly height: number;
+    }): void;
+}
+export declare class ScrollObserver {
+    private subs;
+    private listening;
+    private rafId;
+    private readonly scheduler;
+    constructor();
+    subscribe(element: HTMLElement, subscriber: ScrollSubscriber): () => void;
+    private start;
+    private stop;
+    private scheduleUpdate;
+    /**
+     * Run every subscriber's callback with the current viewport + element
+     * rect. Exposed for tests that need deterministic flushes without
+     * waiting on rAF.
+     */
+    flush(): void;
+}
+/** Lazy singleton — first call creates the observer. SSR-safe. */
+export declare function sharedScrollObserver(): ScrollObserver;
+//# sourceMappingURL=observer.d.ts.map

package/dist/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CACN,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAC5D,IAAI,CAAC;CACT;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAA4C;IACxD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;;IAMvC,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAUzE,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,cAAc;IAStB;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAUd;AAID,kEAAkE;AAClE,wBAAgB,oBAAoB,IAAI,cAAc,CAGrD"}

package/dist/observer.js

@@ -0,0 +1,82 @@
+/**
+ * Shared rAF-throttled scroll / resize observer. Every primitive in this
+ * package (progress, parallax, sticky-pin, horizontal-section) registers
+ * its element here; the observer keeps one passive `scroll` listener on
+ * `window` for the lifetime of any subscription and tears it down once
+ * the last subscriber unsubscribes.
+ *
+ * Safe to import at module load: no window access happens until
+ * `subscribe()` is called.
+ */
+export class ScrollObserver {
+    subs = new Map();
+    listening = false;
+    rafId = null;
+    scheduler;
+    constructor() {
+        this.scheduler = () => this.scheduleUpdate();
+    }
+    subscribe(element, subscriber) {
+        this.subs.set(element, subscriber);
+        if (!this.listening)
+            this.start();
+        this.scheduleUpdate();
+        return () => {
+            this.subs.delete(element);
+            if (this.subs.size === 0)
+                this.stop();
+        };
+    }
+    start() {
+        if (typeof window === "undefined")
+            return;
+        window.addEventListener("scroll", this.scheduler, { passive: true });
+        window.addEventListener("resize", this.scheduler, { passive: true });
+        this.listening = true;
+    }
+    stop() {
+        if (typeof window === "undefined")
+            return;
+        window.removeEventListener("scroll", this.scheduler);
+        window.removeEventListener("resize", this.scheduler);
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        this.listening = false;
+    }
+    scheduleUpdate() {
+        if (this.rafId !== null)
+            return;
+        if (typeof requestAnimationFrame === "undefined")
+            return;
+        this.rafId = requestAnimationFrame(() => {
+            this.rafId = null;
+            this.flush();
+        });
+    }
+    /**
+     * Run every subscriber's callback with the current viewport + element
+     * rect. Exposed for tests that need deterministic flushes without
+     * waiting on rAF.
+     */
+    flush() {
+        if (typeof window === "undefined")
+            return;
+        const viewport = {
+            width: window.innerWidth,
+            height: window.innerHeight,
+        };
+        for (const [el, sub] of this.subs) {
+            sub.onScroll(el.getBoundingClientRect(), viewport);
+        }
+    }
+}
+let _shared = null;
+/** Lazy singleton — first call creates the observer. SSR-safe. */
+export function sharedScrollObserver() {
+    if (!_shared)
+        _shared = new ScrollObserver();
+    return _shared;
+}
+//# sourceMappingURL=observer.js.map

package/dist/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,OAAO,cAAc;IACjB,IAAI,GAAG,IAAI,GAAG,EAAiC,CAAC;IAChD,SAAS,GAAG,KAAK,CAAC;IAClB,KAAK,GAAkB,IAAI,CAAC;IACnB,SAAS,CAAa;IAEvC;QACE,IAAI,CAAC,SAAS,GAAG,GAAS,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;IACrD,CAAC;IAED,SAAS,CAAC,OAAoB,EAAE,UAA4B;QAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC1B,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QACxC,CAAC,CAAC;IACJ,CAAC;IAEO,KAAK;QACX,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAC1C,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAEO,IAAI;QACV,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAC1C,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;IAEO,cAAc;QACpB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO;QAChC,IAAI,OAAO,qBAAqB,KAAK,WAAW;YAAE,OAAO;QACzD,IAAI,CAAC,KAAK,GAAG,qBAAqB,CAAC,GAAG,EAAE;YACtC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAC1C,MAAM,QAAQ,GAAG;YACf,KAAK,EAAE,MAAM,CAAC,UAAU;YACxB,MAAM,EAAE,MAAM,CAAC,WAAW;SAClB,CAAC;QACX,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAClC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,qBAAqB,EAAE,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AAED,IAAI,OAAO,GAA0B,IAAI,CAAC;AAE1C,kEAAkE;AAClE,MAAM,UAAU,oBAAoB;IAClC,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;IAC7C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/progress.d.ts

@@ -0,0 +1,14 @@
+import type { Handle, ScrollProgressOptions } from "./types.js";
+/**
+ * Emits a continuous [0, 1] value as `element` sweeps across the viewport.
+ *
+ *   progress = 0  → element's top edge is at the viewport's bottom edge
+ *                   (element has just entered from below)
+ *   progress = 1  → element's bottom edge is at the viewport's top edge
+ *                   (element has just exited through the top)
+ *
+ * The curve is linear by default; pass `ease: (t) => ...` to remap —
+ * any easing from `@vysmo/easings` works without importing it here.
+ */
+export declare function createScrollProgress(options: ScrollProgressOptions): Handle;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,MAAM,CAsBR"}

package/dist/progress.js

@@ -0,0 +1,36 @@
+import { sharedScrollObserver } from "./observer.js";
+/**
+ * Emits a continuous [0, 1] value as `element` sweeps across the viewport.
+ *
+ *   progress = 0  → element's top edge is at the viewport's bottom edge
+ *                   (element has just entered from below)
+ *   progress = 1  → element's bottom edge is at the viewport's top edge
+ *                   (element has just exited through the top)
+ *
+ * The curve is linear by default; pass `ease: (t) => ...` to remap —
+ * any easing from `@vysmo/easings` works without importing it here.
+ */
+export function createScrollProgress(options) {
+    const observer = sharedScrollObserver();
+    let lastProgress = Number.NaN;
+    const unsubscribe = observer.subscribe(options.element, {
+        onScroll(rect, viewport) {
+            const span = viewport.height + rect.height;
+            if (span <= 0)
+                return;
+            const raw = (viewport.height - rect.top) / span;
+            const clamped = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+            const mapped = options.ease ? options.ease(clamped) : clamped;
+            if (mapped === lastProgress)
+                return;
+            lastProgress = mapped;
+            options.onProgress(mapped);
+        },
+    });
+    return {
+        destroy() {
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA8B;IAE9B,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAC;IACxC,IAAI,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC;IAE9B,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE;QACtD,QAAQ,CAAC,IAAI,EAAE,QAAQ;YACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC;gBAAE,OAAO;YACtB,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAChD,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAChD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9D,IAAI,MAAM,KAAK,YAAY;gBAAE,OAAO;YACpC,YAAY,GAAG,MAAM,CAAC;YACtB,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;YACL,WAAW,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/scroll-effect.d.ts

@@ -0,0 +1,37 @@
+import type { Effect, Runner, TextureSource, UniformParams } from "@vysmo/effects";
+import type { EaseFn, Handle } from "./types.js";
+export interface ScrollEffectOptions<P extends UniformParams> {
+    /**
+     * Section whose scroll-past drives the effect. Progress spans the
+     * full viewport sweep, same as `createScrollProgress`.
+     */
+    section: HTMLElement;
+    /** Effects runner; caller owns the canvas + WebGL context. */
+    runner: Runner;
+    /** Effect to render on every scroll frame. */
+    effect: Effect<P>;
+    /** Source texture to filter — image, video, canvas. */
+    source: TextureSource;
+    /**
+     * Maps the scroll progress [0, 1] to the effect's uniform params.
+     * Keeps the scroll package free of effect-specific knowledge — the
+     * caller decides which param to animate and how.
+     *
+     *   paramsAt: (p) => ({ radius: p * 20 })
+     */
+    paramsAt: (progress: number) => Partial<P>;
+    /** Remap the raw [0, 1] progress before it reaches `paramsAt`. */
+    ease?: EaseFn;
+}
+/**
+ * Bind the scroll position through `section` to a continuous render of
+ * `effect` on `runner`, where the effect's params are a function of
+ * progress. Typical use: blur / chromatic-aberration / colour-grade
+ * intensity ramps up as the user scrolls into a section and back down
+ * as they scroll out.
+ *
+ * Same ownership model as `createScrollTransition`: you pass a Runner,
+ * scroll drives its `render()`. No re-render when progress is unchanged.
+ */
+export declare function createScrollEffect<P extends UniformParams>(options: ScrollEffectOptions<P>): Handle;
+//# sourceMappingURL=scroll-effect.d.ts.map

package/dist/scroll-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-effect.d.ts","sourceRoot":"","sources":["../src/scroll-effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,MAAM,EACN,aAAa,EACb,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,aAAa;IAC1D;;;OAGG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAClB,uDAAuD;IACvD,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3C,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,aAAa,EACxD,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,MAAM,CA0BR"}

package/dist/scroll-effect.js

@@ -0,0 +1,39 @@
+import { sharedScrollObserver } from "./observer.js";
+/**
+ * Bind the scroll position through `section` to a continuous render of
+ * `effect` on `runner`, where the effect's params are a function of
+ * progress. Typical use: blur / chromatic-aberration / colour-grade
+ * intensity ramps up as the user scrolls into a section and back down
+ * as they scroll out.
+ *
+ * Same ownership model as `createScrollTransition`: you pass a Runner,
+ * scroll drives its `render()`. No re-render when progress is unchanged.
+ */
+export function createScrollEffect(options) {
+    const observer = sharedScrollObserver();
+    let lastProgress = Number.NaN;
+    const unsubscribe = observer.subscribe(options.section, {
+        onScroll(rect, viewport) {
+            const span = viewport.height + rect.height;
+            if (span <= 0)
+                return;
+            const raw = (viewport.height - rect.top) / span;
+            const clamped = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+            const mapped = options.ease ? options.ease(clamped) : clamped;
+            if (mapped === lastProgress)
+                return;
+            lastProgress = mapped;
+            const params = options.paramsAt(mapped);
+            options.runner.render(options.effect, {
+                source: options.source,
+                params,
+            });
+        },
+    });
+    return {
+        destroy() {
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=scroll-effect.js.map

package/dist/scroll-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-effect.js","sourceRoot":"","sources":["../src/scroll-effect.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA2BrD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA+B;IAE/B,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAC;IACxC,IAAI,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC;IAE9B,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE;QACtD,QAAQ,CAAC,IAAI,EAAE,QAAQ;YACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC;gBAAE,OAAO;YACtB,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAChD,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAChD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9D,IAAI,MAAM,KAAK,YAAY;gBAAE,OAAO;YACpC,YAAY,GAAG,MAAM,CAAC;YACtB,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACxC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE;gBACpC,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM;aACP,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;YACL,WAAW,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/scroll-transition.d.ts

@@ -0,0 +1,38 @@
+import type { Runner, TextureSource, Transition, UniformParams } from "@vysmo/transitions";
+import type { EaseFn, Handle } from "./types.js";
+export interface ScrollTransitionOptions<P extends UniformParams> {
+    /**
+     * Section whose scroll-past drives the transition. Progress is 0 when
+     * the section's top enters the viewport bottom and 1 when its bottom
+     * exits the viewport top — same curve as `createScrollProgress`.
+     */
+    section: HTMLElement;
+    /**
+     * Transitions runner. The caller owns the WebGL context and its
+     * canvas — that keeps this primitive composable (multiple
+     * scroll-transitions can share one runner) and decouples lifecycle.
+     */
+    runner: Runner;
+    /** Transition to render across the scroll range. */
+    transition: Transition<P>;
+    /** Starting source — shown at progress 0. */
+    from: TextureSource;
+    /** Ending source — shown at progress 1. */
+    to: TextureSource;
+    /** Overrides for the transition's uniform params. */
+    params?: Partial<P>;
+    /** Remap the raw [0, 1] progress. Default: linear. */
+    ease?: EaseFn;
+}
+/**
+ * Bind the vertical scroll position through `section` to a full transition
+ * run on `runner`. As the section sweeps past the viewport, `from` morphs
+ * into `to` via the chosen transition. One rAF per scroll frame, no
+ * re-render when the clamped progress hasn't changed.
+ *
+ * The scroll package does not import the transitions runtime — only its
+ * types. You pass in your own `Runner`, so the transitions library only
+ * lands in bundles that actually call this primitive.
+ */
+export declare function createScrollTransition<P extends UniformParams>(options: ScrollTransitionOptions<P>): Handle;
+//# sourceMappingURL=scroll-transition.d.ts.map

package/dist/scroll-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-transition.d.ts","sourceRoot":"","sources":["../src/scroll-transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,aAAa,EACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,aAAa;IAC9D;;;;OAIG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,aAAa,CAAC;IACpB,2CAA2C;IAC3C,EAAE,EAAE,aAAa,CAAC;IAClB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,aAAa,EAC5D,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,MAAM,CAiCR"}

package/dist/scroll-transition.js

@@ -0,0 +1,42 @@
+import { sharedScrollObserver } from "./observer.js";
+/**
+ * Bind the vertical scroll position through `section` to a full transition
+ * run on `runner`. As the section sweeps past the viewport, `from` morphs
+ * into `to` via the chosen transition. One rAF per scroll frame, no
+ * re-render when the clamped progress hasn't changed.
+ *
+ * The scroll package does not import the transitions runtime — only its
+ * types. You pass in your own `Runner`, so the transitions library only
+ * lands in bundles that actually call this primitive.
+ */
+export function createScrollTransition(options) {
+    const observer = sharedScrollObserver();
+    let lastProgress = Number.NaN;
+    const unsubscribe = observer.subscribe(options.section, {
+        onScroll(rect, viewport) {
+            const span = viewport.height + rect.height;
+            if (span <= 0)
+                return;
+            const raw = (viewport.height - rect.top) / span;
+            const clamped = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+            const mapped = options.ease ? options.ease(clamped) : clamped;
+            if (mapped === lastProgress)
+                return;
+            lastProgress = mapped;
+            const args = {
+                from: options.from,
+                to: options.to,
+                progress: mapped,
+            };
+            if (options.params !== undefined)
+                args.params = options.params;
+            options.runner.render(options.transition, args);
+        },
+    });
+    return {
+        destroy() {
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=scroll-transition.js.map

package/dist/scroll-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-transition.js","sourceRoot":"","sources":["../src/scroll-transition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA4BrD;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAC;IACxC,IAAI,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC;IAE9B,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE;QACtD,QAAQ,CAAC,IAAI,EAAE,QAAQ;YACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC;gBAAE,OAAO;YACtB,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAChD,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAChD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9D,IAAI,MAAM,KAAK,YAAY;gBAAE,OAAO;YACpC,YAAY,GAAG,MAAM,CAAC;YACtB,MAAM,IAAI,GAKN;gBACF,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,EAAE,EAAE,OAAO,CAAC,EAAE;gBACd,QAAQ,EAAE,MAAM;aACjB,CAAC;YACF,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAC/D,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAClD,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;YACL,WAAW,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+/** Signature compatible with `@vysmo/easings.EasingFn`, kept local so this package has zero runtime coupling to the easings lib. */
+export type EaseFn = (t: number) => number;
+export interface Handle {
+    destroy(): void;
+}
+export interface ScrollProgressOptions {
+    /**
+     * Element whose bounding box is tracked. Progress is 0 when its top is
+     * at the viewport bottom and 1 when its bottom is at the viewport top
+     * — i.e. a full sweep across the viewport.
+     */
+    element: HTMLElement;
+    /** Remap the raw [0, 1] progress. Default: linear. */
+    ease?: EaseFn;
+    /** Invoked on every frame the element's position changes. */
+    onProgress: (progress: number) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oIAAoI;AACpI,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3C,MAAM,WAAW,MAAM;IACrB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/zones.d.ts

@@ -0,0 +1,56 @@
+import type { EaseFn } from "./types.js";
+/**
+ * Smoothstep — `t² · (3 − 2t)`. C1-continuous S-curve that matches
+ * linear at 0, 0.5, and 1 but eases in and out near the boundaries.
+ * Used as the default ramp shape for every zone helper so transitions
+ * and effects decelerate smoothly into their plateaus instead of
+ * snapping on the derivative discontinuity of a pure linear ramp.
+ *
+ * Exported so callers can reach for it explicitly, or compose it.
+ */
+export declare const smoothstep: EaseFn;
+/**
+ * Clamp progress to a sub-range. Outside the range, the output stays flat
+ * (0 before `start`, 1 after `end`). Inside, progress is remapped from
+ * `[start, end]` to `[0, 1]` through the supplied ease (default:
+ * {@link smoothstep}).
+ *
+ *   scrollRange(0.1, 0.5) — transition plays between 10% and 50% of the
+ *   full viewport sweep; does nothing before, stays at its final state
+ *   after. Pass `ease: (t) => t` for a linear clamp.
+ *
+ * Designed for `createScrollTransition` so the transition completes at a
+ * point the author chooses — typically well before the section exits the
+ * viewport — and then holds its final state while the user keeps scrolling.
+ */
+export declare function scrollRange(start: number, end: number, ease?: EaseFn): EaseFn;
+/**
+ * Three-zone bathtub envelope for effects.
+ *
+ *   scrollZones(0.25, 0.85) — effect ramps from max at `p = 0` down to
+ *   zero at `p = 0.25` (smoothly by default), stays at zero through the
+ *   clear zone (`0.25 ≤ p ≤ 0.85`), then ramps back up to max by
+ *   `p = 1`.
+ *
+ * Designed for `createScrollEffect` where "identity" is zero intensity —
+ * so the image reads cleanly while the section is visible and the effect
+ * only appears as it enters and exits the viewport. Pass `ease: (t) => t`
+ * for a linear ramp; default is {@link smoothstep}.
+ */
+export declare function scrollZones(clearStart: number, clearEnd: number, ease?: EaseFn): EaseFn;
+/**
+ * Three-zone plateau envelope — the inverse of {@link scrollZones}.
+ *
+ *   scrollPlateau(0.3, 0.7) — rises from 0 at `p = 0` up to 1 at
+ *   `p = 0.3` (smoothly by default), holds at 1 across the clear zone
+ *   (`0.3 ≤ p ≤ 0.7`), then falls back to 0 by `p = 1`.
+ *
+ * Designed for `createScrollTransition` where "identity" is the fully
+ * transitioned state (progress 1). The transition plays in as the
+ * section enters, holds its final frame across the clear zone, then
+ * plays back out (reverse) as the section exits. Smoothstep default
+ * prevents the harsh snap that a linear ramp produces at the plateau
+ * boundaries.
+ */
+export declare function scrollPlateau(clearStart: number, clearEnd: number, ease?: EaseFn): EaseFn;
+//# sourceMappingURL=zones.d.ts.map

package/dist/zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.d.ts","sourceRoot":"","sources":["../src/zones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAmC,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,MAAmB,GACxB,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAmB,GACxB,MAAM,CAYR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAmB,GACxB,MAAM,CAYR"}