Scroll for the modern web.

createScrollProgress

Subscribe an element. onProgress fires whenever the mapped progress changes. The returned handle's destroy() unsubscribes. Repeated equal values are de-duped.

import { createScrollProgress } from "@vysmo/scroll";

interface ScrollProgressOptions {
  // Element whose bounding box is tracked.
  element: HTMLElement;
  // Optional remap of the raw [0, 1] progress. Default: linear.
  ease?: (t: number) => number;
  // Invoked whenever progress changes (de-duped — repeated equal
  // values do not re-fire).
  onProgress: (progress: number) => void;
}

declare function createScrollProgress(opts: ScrollProgressOptions): {
  destroy(): void;
};

createScrollTransition

Drive a transition's progress through the section's sweep. You hand in the runner; we wire the render() call. Multiple scroll-transitions can share one runner.

import { createScrollTransition, scrollPlateau } from "@vysmo/scroll";
import { Runner, crossZoom } from "@vysmo/transitions";

const runner = new Runner({ canvas });

// Drive a transition's progress through the section's scroll sweep.
const handle = createScrollTransition({
  section,                 // section whose scroll-past drives the run
  runner,                  // YOU own the canvas; you own the runner
  transition: crossZoom,   // any @vysmo/transitions shader
  from, to,                // TextureSource pair (image, canvas, video)
  params: { speed: 1.2 },  // optional uniform overrides
  ease: scrollPlateau(0.3, 0.7),
});

// handle.destroy() unsubscribes; the runner you passed in is
// untouched — dispose it on your own schedule.

createScrollEffect

Drive an effect's params from progress. paramsAt decouples the scroll package from effect-specific knowledge — the caller maps progress to whichever uniform makes sense.

import { createScrollEffect, scrollZones } from "@vysmo/scroll";
import { Runner, blur } from "@vysmo/effects";

const runner = new Runner({ canvas });

// Drive an effect's params from scroll progress through your envelope.
// "paramsAt" decouples the scroll package from effect-specific knowledge:
// the caller picks which param is animated and how.
const handle = createScrollEffect({
  section,
  runner,
  effect: blur,
  source,                                  // image / canvas / video
  paramsAt: (p) => ({ radius: p * 24 }),
  ease: scrollZones(0.25, 0.75),           // bathtub: ramp in / clean / ramp out
});

Envelopes — scrollRange / scrollZones / scrollPlateau

Pure functions that reshape [0, 1]. Use them as the ease argument on any primitive (scrollPlateau for transitions that hold mid-section, scrollZones for effects that go quiet in the middle, scrollRange for clamped sub-ranges). smoothstep is the default ramp shape.

import { scrollRange, scrollZones, scrollPlateau, smoothstep } from "@vysmo/scroll";

// Clamp progress to a sub-range. Outside it, output stays flat.
//   scrollRange(0.1, 0.5) — plays between 10% and 50%, stays at the
//   end state past 50%.
scrollRange(start, end, ease?);

// Three-zone bathtub envelope. 1 → 0 → 1 across the section.
//   scrollZones(0.25, 0.85) — effect at full at the entry, zero
//   through the clear zone, full again at exit.
scrollZones(clearStart, clearEnd, ease?);

// Three-zone plateau envelope — the inverse of zones.
//   scrollPlateau(0.3, 0.7) — 0 → 1 entering, hold at 1 across the
//   plateau, 1 → 0 exiting.
scrollPlateau(clearStart, clearEnd, ease?);

// The default ramp shape used by all three zone helpers — C¹-continuous
// S-curve that decelerates smoothly into the plateaus.
smoothstep;  // (t) => t * t * (3 - 2t)

sharedScrollObserver / ScrollObserver

The singleton (use it for everything) and the class (for isolated observers in unusual cases). flush() is exposed so callers can force a redraw after changing local state (e.g., a slider that reshapes an envelope) without waiting for the next scroll event.

import { sharedScrollObserver, ScrollObserver } from "@vysmo/scroll";

// One singleton observer per page is enough for any number of
// subscribers. The window listeners attach on first subscribe and
// detach when the last subscriber unsubscribes — so importing this
// module costs nothing if you never call subscribe().
const observer = sharedScrollObserver();

const unsubscribe = observer.subscribe(element, {
  onScroll(rect, viewport) {
    // rect:    DOMRect of element
    // viewport: { width, height } of window
    // Called once per rAF; identical positions are not de-duped here —
    // callers do that themselves (see createScrollProgress).
  },
});

// observer.flush() runs every subscriber synchronously with the
// current scroll position — useful for forcing a redraw after
// changing local state (e.g., a slider that reshapes an envelope).

// Need an isolated observer instead of the singleton? Construct one:
const local = new ScrollObserver();

Types

EaseFn = (t: number) => number — structurally compatible with @vysmo/easings.EasingFn, kept local so this package has zero runtime coupling. Handle = { destroy(): void } — the uniform return shape of every primitive. Always call destroy() on unmount.