@vysmo/scroll 0.1.0

package/dist/zones.js

@@ -0,0 +1,94 @@
+/**
+ * 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 const smoothstep = (t) => t * t * (3 - 2 * t);
+/**
+ * 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 function scrollRange(start, end, ease = smoothstep) {
+    if (end <= start)
+        return (p) => (p < start ? 0 : 1);
+    const span = end - start;
+    return (p) => {
+        if (p <= start)
+            return 0;
+        if (p >= end)
+            return 1;
+        return ease((p - start) / span);
+    };
+}
+/**
+ * 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 function scrollZones(clearStart, clearEnd, ease = smoothstep) {
+    return (p) => {
+        if (p < clearStart) {
+            if (clearStart <= 0)
+                return 0;
+            return 1 - ease(p / clearStart);
+        }
+        if (p > clearEnd) {
+            if (clearEnd >= 1)
+                return 0;
+            return ease((p - clearEnd) / (1 - clearEnd));
+        }
+        return 0;
+    };
+}
+/**
+ * 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 function scrollPlateau(clearStart, clearEnd, ease = smoothstep) {
+    return (p) => {
+        if (p < clearStart) {
+            if (clearStart <= 0)
+                return 1;
+            return ease(p / clearStart);
+        }
+        if (p > clearEnd) {
+            if (clearEnd >= 1)
+                return 1;
+            return 1 - ease((p - clearEnd) / (1 - clearEnd));
+        }
+        return 1;
+    };
+}
+//# sourceMappingURL=zones.js.map

package/dist/zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.js","sourceRoot":"","sources":["../src/zones.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAW,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,GAAW,EACX,OAAe,UAAU;IAEzB,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,CAAC;IACzB,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,IAAI,KAAK;YAAE,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG;YAAE,OAAO,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,UAAkB,EAClB,QAAgB,EAChB,OAAe,UAAU;IAEzB,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC;YACnB,IAAI,UAAU,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjB,IAAI,QAAQ,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YAC5B,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,QAAgB,EAChB,OAAe,UAAU;IAEzB,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC;YACnB,IAAI,UAAU,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjB,IAAI,QAAQ,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;YAC5B,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vysmo/scroll",
+  "version": "0.1.0",
+  "description": "Scroll-driven primitives that compose with the ecosystem: bind scroll progress to any @vysmo/transitions or @vysmo/effects render. Shared rAF-throttled observer, headless.",
+  "license": "MIT",
+  "keywords": [
+    "scroll",
+    "scroll-driven",
+    "progress",
+    "scroll-transition",
+    "scroll-effect",
+    "webgl",
+    "headless"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@vysmo/effects": "0.1.0",
+    "@vysmo/transitions": "0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/browser": "^3.2.4",
+    "esbuild": "^0.28.0",
+    "playwright": "^1.59.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:browser": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest",
+    "size": "node scripts/check-bundle-size.mjs"
+  }
+}

package/src/__tests__/observer.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ScrollObserver, sharedScrollObserver } from "../index.js";
+
+let el: HTMLElement;
+
+beforeEach(() => {
+  el = document.createElement("div");
+  el.style.height = "200px";
+  el.style.width = "200px";
+  document.body.appendChild(el);
+});
+
+afterEach(() => {
+  el.remove();
+});
+
+describe("ScrollObserver", () => {
+  it("delivers the current rect + viewport on flush", () => {
+    const observer = new ScrollObserver();
+    const onScroll = vi.fn();
+    observer.subscribe(el, { onScroll });
+    observer.flush();
+    expect(onScroll).toHaveBeenCalledTimes(1);
+    const [rect, viewport] = onScroll.mock.calls[0]!;
+    expect(rect).toBeInstanceOf(DOMRect);
+    expect(viewport.width).toBe(window.innerWidth);
+    expect(viewport.height).toBe(window.innerHeight);
+  });
+
+  it("notifies multiple subscribers on one flush", () => {
+    const observer = new ScrollObserver();
+    const el2 = document.createElement("div");
+    document.body.appendChild(el2);
+    const a = vi.fn();
+    const b = vi.fn();
+    observer.subscribe(el, { onScroll: a });
+    observer.subscribe(el2, { onScroll: b });
+    observer.flush();
+    expect(a).toHaveBeenCalledTimes(1);
+    expect(b).toHaveBeenCalledTimes(1);
+    el2.remove();
+  });
+
+  it("unsubscribing stops further notifications for that element", () => {
+    const observer = new ScrollObserver();
+    const onScroll = vi.fn();
+    const unsub = observer.subscribe(el, { onScroll });
+    observer.flush();
+    expect(onScroll).toHaveBeenCalledTimes(1);
+    unsub();
+    observer.flush();
+    expect(onScroll).toHaveBeenCalledTimes(1);
+  });
+
+  it("sharedScrollObserver returns a stable singleton", () => {
+    const a = sharedScrollObserver();
+    const b = sharedScrollObserver();
+    expect(a).toBe(b);
+  });
+});

package/src/__tests__/progress.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ScrollObserver } from "../observer.js";
+import { createScrollProgress } from "../progress.js";
+
+let el: HTMLElement;
+let spacerBefore: HTMLElement;
+let spacerAfter: HTMLElement;
+
+beforeEach(() => {
+  spacerBefore = document.createElement("div");
+  spacerBefore.style.cssText = "height:2000px;";
+  document.body.appendChild(spacerBefore);
+
+  el = document.createElement("div");
+  el.style.cssText = "width:100%;height:400px;background:red;";
+  document.body.appendChild(el);
+
+  // Trailing spacer ensures the document is tall enough for scrollTo()
+  // to actually reach large Y values without hitting the scroll maximum.
+  spacerAfter = document.createElement("div");
+  spacerAfter.style.cssText = "height:5000px;";
+  document.body.appendChild(spacerAfter);
+
+  window.scrollTo(0, 0);
+});
+
+afterEach(() => {
+  spacerBefore.remove();
+  el.remove();
+  spacerAfter.remove();
+  window.scrollTo(0, 0);
+});
+
+describe("createScrollProgress", () => {
+  it("starts at 0 when the element is below the viewport", async () => {
+    const onProgress = vi.fn();
+    const h = createScrollProgress({ element: el, onProgress });
+    await waitForFrame();
+    expect(onProgress).toHaveBeenCalled();
+    expect(onProgress.mock.calls.at(-1)![0]).toBe(0);
+    h.destroy();
+  });
+
+  it("advances as the user scrolls through the element", async () => {
+    const values: number[] = [];
+    const h = createScrollProgress({
+      element: el,
+      onProgress: (p) => values.push(p),
+    });
+    await waitForFrame();
+    window.scrollTo(0, 1500);
+    await waitForFrame();
+    window.scrollTo(0, 2400);
+    await waitForFrame();
+    expect(values[0]).toBe(0);
+    expect(values.at(-1)!).toBeGreaterThan(values[0]!);
+    h.destroy();
+  });
+
+  it("reaches 1 after fully scrolling past the element", async () => {
+    const values: number[] = [];
+    const h = createScrollProgress({
+      element: el,
+      onProgress: (p) => values.push(p),
+    });
+    await waitForFrame();
+    window.scrollTo(0, 5000);
+    await waitForFrame();
+    expect(values.at(-1)!).toBe(1);
+    h.destroy();
+  });
+
+  it("clamps progress into [0, 1]", async () => {
+    const values: number[] = [];
+    const h = createScrollProgress({
+      element: el,
+      onProgress: (p) => values.push(p),
+    });
+    await waitForFrame();
+    for (const y of [0, 100, 1500, 3000, 10000]) {
+      window.scrollTo(0, y);
+      await waitForFrame();
+    }
+    for (const p of values) {
+      expect(p).toBeGreaterThanOrEqual(0);
+      expect(p).toBeLessThanOrEqual(1);
+    }
+    h.destroy();
+  });
+
+  it("applies the ease() callback to remap the raw value", () => {
+    const observer = new ScrollObserver();
+    const onProgress = vi.fn();
+    observer.subscribe(el, {
+      onScroll(rect, viewport) {
+        const raw = (viewport.height - rect.top) / (viewport.height + rect.height);
+        const clamped = Math.max(0, Math.min(1, raw));
+        // Mirror the internal calculation: ease(clamped) = clamped * 2
+        const mapped = clamped * 2;
+        onProgress(mapped);
+      },
+    });
+    observer.flush();
+    expect(onProgress).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-emit when the clamped value is unchanged", async () => {
+    const onProgress = vi.fn();
+    const h = createScrollProgress({ element: el, onProgress });
+    await waitForFrame();
+    // Two identical rAF ticks at the same scroll position should collapse.
+    const before = onProgress.mock.calls.length;
+    await waitForFrame();
+    await waitForFrame();
+    const after = onProgress.mock.calls.length;
+    expect(after).toBe(before);
+    h.destroy();
+  });
+});
+
+async function waitForFrame(): Promise<void> {
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+  // A second rAF gives the observer time to run its flush after the
+  // scroll event has been dispatched synchronously.
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+}

package/src/__tests__/scroll-effect.test.ts

@@ -0,0 +1,135 @@
+import type { Runner as EffectRunner, Effect } from "@vysmo/effects";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createScrollEffect } from "../scroll-effect.js";
+
+function mockRunner(): EffectRunner & { calls: Array<{ effect: unknown; args: unknown }> } {
+  const calls: Array<{ effect: unknown; args: unknown }> = [];
+  const runner = {
+    calls,
+    render(effect: unknown, args: unknown) {
+      calls.push({ effect, args });
+    },
+  };
+  return runner as unknown as EffectRunner & typeof runner;
+}
+
+const FAKE_EFFECT = {
+  name: "fake-blur",
+  defaults: { radius: 0 },
+  shader: { glsl: "" },
+} as unknown as Effect<{ radius: number }>;
+
+let spacerBefore: HTMLElement;
+let section: HTMLElement;
+let spacerAfter: HTMLElement;
+
+beforeEach(() => {
+  spacerBefore = document.createElement("div");
+  spacerBefore.style.cssText = "height:2000px;";
+  document.body.appendChild(spacerBefore);
+
+  section = document.createElement("div");
+  section.style.cssText = "width:100%;height:400px;";
+  document.body.appendChild(section);
+
+  spacerAfter = document.createElement("div");
+  spacerAfter.style.cssText = "height:5000px;";
+  document.body.appendChild(spacerAfter);
+
+  window.scrollTo(0, 0);
+});
+
+afterEach(() => {
+  spacerBefore.remove();
+  section.remove();
+  spacerAfter.remove();
+  window.scrollTo(0, 0);
+});
+
+async function waitForFrame(): Promise<void> {
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+}
+
+describe("createScrollEffect", () => {
+  it("invokes paramsAt with progress 0 when the section is below the viewport", async () => {
+    const runner = mockRunner();
+    const paramsSeen: number[] = [];
+    const h = createScrollEffect({
+      section,
+      runner,
+      effect: FAKE_EFFECT,
+      source: {} as unknown as HTMLImageElement,
+      paramsAt: (p) => {
+        paramsSeen.push(p);
+        return { radius: p * 10 };
+      },
+    });
+    await waitForFrame();
+    expect(paramsSeen[0]).toBe(0);
+    const last = runner.calls.at(-1)!;
+    expect((last.args as { params: { radius: number } }).params).toEqual({ radius: 0 });
+    h.destroy();
+  });
+
+  it("maps progress through paramsAt as the user scrolls", async () => {
+    const runner = mockRunner();
+    const h = createScrollEffect({
+      section,
+      runner,
+      effect: FAKE_EFFECT,
+      source: {} as unknown as HTMLImageElement,
+      paramsAt: (p) => ({ radius: p * 20 }),
+    });
+    await waitForFrame();
+    window.scrollTo(0, 5000);
+    await waitForFrame();
+    const lastRadius = (runner.calls.at(-1)!.args as { params: { radius: number } }).params
+      .radius;
+    expect(lastRadius).toBe(20);
+    h.destroy();
+  });
+
+  it("respects ease() before calling paramsAt", async () => {
+    const runner = mockRunner();
+    const easeCalls: number[] = [];
+    const paramsAtInputs: number[] = [];
+    const h = createScrollEffect({
+      section,
+      runner,
+      effect: FAKE_EFFECT,
+      source: {} as unknown as HTMLImageElement,
+      ease: (t) => {
+        easeCalls.push(t);
+        return t * t;
+      },
+      paramsAt: (p) => {
+        paramsAtInputs.push(p);
+        return { radius: p };
+      },
+    });
+    await waitForFrame();
+    expect(easeCalls.length).toBeGreaterThan(0);
+    expect(paramsAtInputs.length).toBeGreaterThan(0);
+    // paramsAt input is the eased value, not the raw.
+    expect(paramsAtInputs[0]).toBeCloseTo(0, 5);
+    h.destroy();
+  });
+
+  it("destroy() unsubscribes — no further renders after scroll", async () => {
+    const runner = mockRunner();
+    const h = createScrollEffect({
+      section,
+      runner,
+      effect: FAKE_EFFECT,
+      source: {} as unknown as HTMLImageElement,
+      paramsAt: (p) => ({ radius: p * 10 }),
+    });
+    await waitForFrame();
+    h.destroy();
+    const before = runner.calls.length;
+    window.scrollTo(0, 5000);
+    await waitForFrame();
+    expect(runner.calls.length).toBe(before);
+  });
+});

package/src/__tests__/scroll-transition.test.ts

@@ -0,0 +1,167 @@
+import type { Runner as TransitionRunner, Transition, UniformParams } from "@vysmo/transitions";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createScrollTransition } from "../scroll-transition.js";
+
+/**
+ * Mock Runner — satisfies the narrow shape `createScrollTransition` uses
+ * without touching WebGL. The test asserts that scroll drives render() with
+ * the correct progress / args, which is the whole contract here.
+ */
+function mockRunner(): TransitionRunner & { calls: Array<{ transition: unknown; args: unknown }> } {
+  const calls: Array<{ transition: unknown; args: unknown }> = [];
+  const runner = {
+    calls,
+    render(transition: unknown, args: unknown) {
+      calls.push({ transition, args });
+    },
+  };
+  return runner as unknown as TransitionRunner & typeof runner;
+}
+
+const FAKE_TRANSITION = {
+  name: "fake",
+  defaults: { amount: 0.5 },
+  shader: { glsl: "" },
+} as unknown as Transition<{ amount: number }>;
+
+let spacerBefore: HTMLElement;
+let section: HTMLElement;
+let spacerAfter: HTMLElement;
+
+beforeEach(() => {
+  spacerBefore = document.createElement("div");
+  spacerBefore.style.cssText = "height:2000px;";
+  document.body.appendChild(spacerBefore);
+
+  section = document.createElement("div");
+  section.style.cssText = "width:100%;height:400px;";
+  document.body.appendChild(section);
+
+  spacerAfter = document.createElement("div");
+  spacerAfter.style.cssText = "height:5000px;";
+  document.body.appendChild(spacerAfter);
+
+  window.scrollTo(0, 0);
+});
+
+afterEach(() => {
+  spacerBefore.remove();
+  section.remove();
+  spacerAfter.remove();
+  window.scrollTo(0, 0);
+});
+
+async function waitForFrame(): Promise<void> {
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+}
+
+describe("createScrollTransition", () => {
+  it("renders at progress 0 when the section is below the viewport", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as UniformParams extends never ? never : HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+    });
+    await waitForFrame();
+    expect(runner.calls.length).toBeGreaterThanOrEqual(1);
+    const last = runner.calls.at(-1)!;
+    expect(last.transition).toBe(FAKE_TRANSITION);
+    expect((last.args as { progress: number }).progress).toBe(0);
+    h.destroy();
+  });
+
+  it("drives progress from 0 → 1 as the user scrolls past", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+    });
+    await waitForFrame();
+    window.scrollTo(0, 5000);
+    await waitForFrame();
+    const progresses = runner.calls.map((c) => (c.args as { progress: number }).progress);
+    expect(progresses[0]).toBe(0);
+    expect(progresses.at(-1)).toBe(1);
+    h.destroy();
+  });
+
+  it("forwards params through to the runner", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+      params: { amount: 0.75 },
+    });
+    await waitForFrame();
+    const last = runner.calls.at(-1)!;
+    expect((last.args as { params: { amount: number } }).params).toEqual({ amount: 0.75 });
+    h.destroy();
+  });
+
+  it("applies ease() to the raw progress", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+      // raw 0.5 → eased 0.25
+      ease: (t) => t * t,
+    });
+    await waitForFrame();
+    // Scroll midway.
+    window.scrollTo(0, 2400);
+    await waitForFrame();
+    const mids = runner.calls.map((c) => (c.args as { progress: number }).progress);
+    for (const p of mids) {
+      expect(p).toBeGreaterThanOrEqual(0);
+      expect(p).toBeLessThanOrEqual(1);
+    }
+    h.destroy();
+  });
+
+  it("does not re-render when the clamped progress hasn't changed", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+    });
+    await waitForFrame();
+    const before = runner.calls.length;
+    await waitForFrame();
+    await waitForFrame();
+    expect(runner.calls.length).toBe(before);
+    h.destroy();
+  });
+
+  it("destroy() unsubscribes — no further renders after scroll", async () => {
+    const runner = mockRunner();
+    const h = createScrollTransition({
+      section,
+      runner,
+      transition: FAKE_TRANSITION,
+      from: {} as unknown as HTMLImageElement,
+      to: {} as unknown as HTMLImageElement,
+    });
+    await waitForFrame();
+    h.destroy();
+    const before = runner.calls.length;
+    window.scrollTo(0, 5000);
+    await waitForFrame();
+    expect(runner.calls.length).toBe(before);
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+describe("SSR safety", () => {
+  it("window is undefined in this runtime", () => {
+    expect(typeof window).toBe("undefined");
+  });
+
+  it("the narrowed factory set imports without touching DOM", async () => {
+    const mod = await import("../index.js");
+    expect(typeof mod.createScrollProgress).toBe("function");
+    expect(typeof mod.createScrollTransition).toBe("function");
+    expect(typeof mod.createScrollEffect).toBe("function");
+    expect(typeof mod.sharedScrollObserver).toBe("function");
+    expect(typeof mod.scrollRange).toBe("function");
+    expect(typeof mod.scrollZones).toBe("function");
+    expect(typeof mod.scrollPlateau).toBe("function");
+    expect(typeof mod.smoothstep).toBe("function");
+  });
+
+  it("scroll zone helpers run purely in Node", async () => {
+    const { scrollRange, scrollZones, scrollPlateau, smoothstep } =
+      await import("../index.js");
+    expect(scrollRange(0.1, 0.5)(0.3)).toBeCloseTo(0.5, 5);
+    expect(scrollZones(0.25, 0.85)(0.5)).toBe(0);
+    expect(scrollPlateau(0.3, 0.7)(0.5)).toBe(1);
+    expect(smoothstep(0.5)).toBeCloseTo(0.5, 5);
+    expect(smoothstep(0.25)).toBeCloseTo(0.15625, 5);
+  });
+
+  it("sharedScrollObserver can be constructed without window access", async () => {
+    const { sharedScrollObserver } = await import("../index.js");
+    const obs = sharedScrollObserver();
+    expect(obs).toBeDefined();
+    // flush() with no window is a no-op rather than a throw.
+    expect(() => obs.flush()).not.toThrow();
+  });
+});