@sphynxoid/stepwise 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Sphynx
+
+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

@@ -1,3 +1,150 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @sphynxoid/stepwise
+
+A kit for interactive, narrated, step-driven visualizations — one primitive (`useSteps`) at every scale.
+
+Frames in a trace, chapters in a lesson, lessons in a notebook, and tour steps are the same thing at the core: a clamped cursor over an ordered sequence. Timers, tour effects, scroll tracking, and third-party presenters are policies and adapters layered on top.
+
+- **Headless core.** The hooks never render; the styled components are optional and theme-injectable.
+- **One dependency by default.** The root barrel needs only React. GSAP and driver.js integrations are opt-in via adapter subpaths.
+
+## Install
+
+```bash
+npm install @sphynxoid/stepwise
+```
+
+Optional adapters (install only what you use):
+
+```bash
+npm install gsap        # @sphynxoid/stepwise/adapters/gsap
+npm install driver.js   # @sphynxoid/stepwise/adapters/driver-js
+# @sphynxoid/stepwise/adapters/scroll is dependency-free
+```
+
+## Styling — pick one
+
+The hooks are headless. The styled components (`PlayerBar`, `TourCard`, `Term`, …) ship Tailwind class strings, and there are three ways to get them styled:
+
+**1. No Tailwind — import the precompiled stylesheet** (once, at your app entry):
+
+```ts
+import "@sphynxoid/stepwise/styles.css";
+```
+
+It contains exactly the CSS the components use, no global reset (a small preflight is scoped to the components' `[data-stepwise]` roots), and light/dark defaults that follow `prefers-color-scheme` or a `.dark` / `[data-theme="dark"]` switch. Re-color it with CSS variables:
+
+```css
+:root {
+  --stepwise-primary: #7c3aed;      /* play button, active segment, rings */
+  --stepwise-accent: #0ea5e9;       /* "accent" tone, links, wait hints */
+}
+```
+
+Tokens: `--stepwise-background`, `-foreground`, `-card`, `-popover`, `-primary`, `-primary-foreground`, `-accent`, `-destructive`, `-ring`, `-shade` (overlay/code-block tint).
+
+**2. Tailwind + shadcn/ui — copy the components in with the shadcn CLI:**
+
+```bash
+npx shadcn@latest add https://stepwise-demo.vercel.app/r/player-bar.json
+```
+
+Items: `player-bar`, `code-block`, `tour`, `glossary`, `chapter-nav`, `lesson-pager`, `shortcuts-dialog` — or `stepwise` for all of them. The presentation source lands in `components/stepwise/` (plus `lib/stepwise-theme.ts`), where Tailwind scans it automatically; hooks and types stay imported from this package. Colors come from your shadcn tokens.
+
+**3. Tailwind, using the components from npm** — register the package so Tailwind generates its classes (v4 skips `node_modules`):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@sphynxoid/stepwise/dist";
+```
+
+Token contract, Tailwind v3 setup and the "everything renders unstyled" checklist: [TAILWIND-SETUP.md](https://github.com/TheSphynxoid/stepwise/blob/master/docs/TAILWIND-SETUP.md).
+
+## Quick start — a narrated player
+
+```tsx
+"use client";
+import { useTrace, PlayerBar, CodeBlock, type StepwiseStep } from "@sphynxoid/stepwise";
+
+// Your domain payload rides along with the presentation fields.
+const frames: StepwiseStep<{ code: string[] }>[] = [
+  { tone: "write", label: "Initialize", code: ["let i = 0;"] },
+  { tone: "neutral", label: "Loop", code: ["while (i < n) { … }"] },
+  { tone: "good", label: "Done", code: ["return arr;"] },
+];
+
+export function Demo() {
+  const trace = useTrace(frames, { autoPlay: true, syncHash: "frame" });
+
+  return (
+    <>
+      <CodeBlock lines={trace.step!.code} />
+      <PlayerBar player={trace.player} toneAt={trace.toneAt} titleAt={trace.titleAt} />
+    </>
+  );
+}
+```
+
+`useTrace` binds a player to a typed trace: `step` is the frame to render (frame 0 before playback starts), and `toneAt` / `titleAt` feed the scrubber. Under it, `useStepPlayer` gives you a timer-driven playhead with play/pause/seek, speed control, and optional `#frame=2` deep links — or hand it an `engine` to drive the playhead from GSAP or scroll instead. Two end-state flavors: `atEnd` (cursor parked on the last frame, seeks included) and `ended` (playback ran to the finish, via the `onEnd` callback option) — clearing on any cursor movement, so a completion summary knows the demo actually finished. `autoPlay` respects `prefers-reduced-motion` (lands on frame 0, paused; opt out with `respectReducedMotion: false`), and `syncHash` writes only its own key, so it coexists with anchors and other players' keys.
+
+## The three scales
+
+| Scale | Hook | Presentation |
+|---|---|---|
+| **Player** — auto-played frames in a trace | `useStepPlayer` (+ `PlayerEngine` adapters) | `PlayerBar`, `StepScrubber`, `CodeBlock` |
+| **Tour** — steps that mutate app state via `onEnter` | `useGuidedTour` (+ `TourDriver` adapters) | `TourSpotlight`, `TourCard` |
+| **Chapters** — scroll-tracked sections | `useChapters`, `flattenChapters` | `ChapterNav`, `LessonPager` |
+
+All three compose the same `useSteps` cursor, so movement, clamping, and boundary flags behave identically everywhere.
+
+Tours are small state machines: a step may declare `when` (skip on arrival when false), `gate` (block `next()` — and expose `blocked` — until the user actually does the thing), and `next` (edge override to another step's `id`, enabling branches and loops). `gotoId(id)` navigates by identity; programmatic navigation never trips gates.
+
+## Show-once tutorials (led discovery)
+
+Pair `useDiscoveries` with `useGuidedTour` to auto-play a tour the first time a user encounters a feature:
+
+```tsx
+const { discovered, ready, markDiscovered } = useDiscoveries();
+const tour = useGuidedTour(steps);
+
+// when this build carries an undiscovered feature, play its tour once
+useEffect(() => {
+  if (ready && !tour.active && !discovered.has("search:v1")) tour.start();
+}, [ready, tour.active, discovered]);
+
+// mark on completion (or explicit dismiss) — never on mere trigger
+useEffect(() => {
+  if (launched && !tour.active) markDiscovered("search:v1");
+}, [tour.active]);
+```
+
+The ledger is a set of opaque ids behind a `DiscoveryStore` seam: `localStorageStore` (default), `cookieStore` (when SSR markup must know), `memoryStore` (tests), or your own store backed by an API for cross-device discovery.
+
+## Supporting pieces
+
+- `useGlobalKeys` — global keyboard bindings with a form-control guard
+- `useFocusTrap` — dialog/tour focus containment
+- `usePrefersReducedMotion` — motion preference gate
+- `useDiscoveries` (+ `localStorageStore` / `cookieStore` / `memoryStore`) — persisted discovery ledger with a swappable storage seam
+- `GlossaryProvider` / `Term` / `GlossaryAppendix` — recursive, depth-capped term tooltips with an auto-collecting appendix
+- `ShortcutsDialog` — keyboard shortcut reference
+- `defaultTheme` / `StepwiseTheme` — the default styling, overridable per component via a `theme` prop (swap in any design system)
+
+## Adapters
+
+Import adapters from their subpaths — never from the root barrel:
+
+```ts
+import { createGsapPlayerEngine } from "@sphynxoid/stepwise/adapters/gsap";
+import { createDriverJsTourDriver } from "@sphynxoid/stepwise/adapters/driver-js";
+import { createScrollPlayerEngine } from "@sphynxoid/stepwise/adapters/scroll";
+```
+
+An adapter plugs into a tiny port (`PlayerEngine` / `TourDriver`), so you can write your own for Shepherd, Framer Motion, or anything else without touching the kit.
+
+## React
+
+Supports React 18 and 19. All hooks are SSR-safe (`"use client"` modules, no window access at module evaluation) and every public hook returns referentially stable callbacks.
+
+## License
+
+MIT

package/dist/adapters/driver-js.d.ts

@@ -0,0 +1,23 @@
+import { T as TourDriver } from '../types-IT_9L8On.js';
+import 'react';
+
+interface DriverJsTourOptions {
+    /** Extra class for the driver.js popover, e.g. to blend with the app theme. */
+    popoverClass?: string;
+}
+/**
+ * TourDriver backed by driver.js. The hook still owns state coupling (onEnter
+ * effects fire per step); driver.js only presents the spotlight + popover.
+ *
+ * Caveats vs the built-in presenter:
+ *  - every step needs a `target` (driver.js anchors a popover to an element);
+ *    targetless steps are presented as empty passes — prefer the built-in
+ *    presenter for tours with intro/outro steps.
+ *  - step bodies must be plain strings.
+ *
+ *   const driver = useMemo(() => createDriverJsTourDriver(), []);
+ *   const tour = useGuidedTour(steps, { driver });
+ */
+declare function createDriverJsTourDriver(opts?: DriverJsTourOptions): TourDriver;
+
+export { type DriverJsTourOptions, createDriverJsTourDriver };

package/dist/adapters/driver-js.js

@@ -0,0 +1,45 @@
+"use client";
+"use client";
+
+// src/adapters/driver-js.ts
+import { driver } from "driver.js";
+import "driver.js/dist/driver.css";
+function createDriverJsTourDriver(opts = {}) {
+  let instance = null;
+  const destroy = () => {
+    if (instance?.isActive()) instance.destroy();
+    instance = null;
+  };
+  return {
+    show(step, ctx) {
+      destroy();
+      if (!step.target || !document.querySelector(`[data-tour="${step.target}"]`)) return;
+      instance = driver({
+        popoverClass: opts.popoverClass,
+        showProgress: false,
+        allowClose: true,
+        showButtons: ["next", "previous", "close"],
+        nextBtnText: "Next",
+        prevBtnText: "Back",
+        doneBtnText: "Finish",
+        onNextClick: () => ctx.next(),
+        onPrevClick: () => ctx.back(),
+        onCloseClick: () => ctx.end()
+      });
+      const stepConfig = {
+        element: `[data-tour="${step.target}"]`,
+        popover: {
+          title: step.title,
+          description: typeof step.body === "string" ? step.body : ""
+        },
+        waitForElement: 500
+      };
+      instance.highlight(stepConfig);
+    },
+    hide: destroy
+  };
+}
+export {
+  createDriverJsTourDriver
+};
+//# sourceMappingURL=driver-js.js.map

package/dist/adapters/driver-js.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/driver-js.ts"],"sourcesContent":["\"use client\";\n\nimport { driver, type DriveStep } from \"driver.js\";\nimport \"driver.js/dist/driver.css\";\nimport type { TourDriver, TourStepInput } from \"../types\";\n\nexport interface DriverJsTourOptions {\n  /** Extra class for the driver.js popover, e.g. to blend with the app theme. */\n  popoverClass?: string;\n}\n\n/**\n * TourDriver backed by driver.js. The hook still owns state coupling (onEnter\n * effects fire per step); driver.js only presents the spotlight + popover.\n *\n * Caveats vs the built-in presenter:\n *  - every step needs a `target` (driver.js anchors a popover to an element);\n *    targetless steps are presented as empty passes — prefer the built-in\n *    presenter for tours with intro/outro steps.\n *  - step bodies must be plain strings.\n *\n *   const driver = useMemo(() => createDriverJsTourDriver(), []);\n *   const tour = useGuidedTour(steps, { driver });\n */\nexport function createDriverJsTourDriver(opts: DriverJsTourOptions = {}): TourDriver {\n  let instance: ReturnType<typeof driver> | null = null;\n\n  const destroy = () => {\n    if (instance?.isActive()) instance.destroy();\n    instance = null;\n  };\n\n  return {\n    show(step: TourStepInput, ctx) {\n      destroy();\n      if (!step.target || !document.querySelector(`[data-tour=\"${step.target}\"]`)) return;\n      instance = driver({\n        popoverClass: opts.popoverClass,\n        showProgress: false,\n        allowClose: true,\n        showButtons: [\"next\", \"previous\", \"close\"],\n        nextBtnText: \"Next\",\n        prevBtnText: \"Back\",\n        doneBtnText: \"Finish\",\n        onNextClick: () => ctx.next(),\n        onPrevClick: () => ctx.back(),\n        onCloseClick: () => ctx.end(),\n      });\n      const stepConfig = {\n        element: `[data-tour=\"${step.target}\"]`,\n        popover: {\n          title: step.title,\n          description: typeof step.body === \"string\" ? step.body : \"\",\n        },\n        waitForElement: 500,\n      } as DriveStep;\n      instance.highlight(stepConfig);\n    },\n    hide: destroy,\n  };\n}\n"],"mappings":";;;;AAEA,SAAS,cAA8B;AACvC,OAAO;AAqBA,SAAS,yBAAyB,OAA4B,CAAC,GAAe;AACnF,MAAI,WAA6C;AAEjD,QAAM,UAAU,MAAM;AACpB,QAAI,UAAU,SAAS,EAAG,UAAS,QAAQ;AAC3C,eAAW;AAAA,EACb;AAEA,SAAO;AAAA,IACL,KAAK,MAAqB,KAAK;AAC7B,cAAQ;AACR,UAAI,CAAC,KAAK,UAAU,CAAC,SAAS,cAAc,eAAe,KAAK,MAAM,IAAI,EAAG;AAC7E,iBAAW,OAAO;AAAA,QAChB,cAAc,KAAK;AAAA,QACnB,cAAc;AAAA,QACd,YAAY;AAAA,QACZ,aAAa,CAAC,QAAQ,YAAY,OAAO;AAAA,QACzC,aAAa;AAAA,QACb,aAAa;AAAA,QACb,aAAa;AAAA,QACb,aAAa,MAAM,IAAI,KAAK;AAAA,QAC5B,aAAa,MAAM,IAAI,KAAK;AAAA,QAC5B,cAAc,MAAM,IAAI,IAAI;AAAA,MAC9B,CAAC;AACD,YAAM,aAAa;AAAA,QACjB,SAAS,eAAe,KAAK,MAAM;AAAA,QACnC,SAAS;AAAA,UACP,OAAO,KAAK;AAAA,UACZ,aAAa,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO;AAAA,QAC3D;AAAA,QACA,gBAAgB;AAAA,MAClB;AACA,eAAS,UAAU,UAAU;AAAA,IAC/B;AAAA,IACA,MAAM;AAAA,EACR;AACF;","names":[]}

package/dist/adapters/gsap.d.ts

@@ -0,0 +1,23 @@
+import { P as PlayerEngine } from '../types-IT_9L8On.js';
+import 'react';
+
+interface GsapEngineOptions {
+    /** Frames in the current timeline. Recreate the engine when it changes. */
+    total: number;
+    /** Wall-clock time per frame at 1× speed. */
+    baseDelayMs?: number;
+}
+/**
+ * PlayerEngine backed by a GSAP tween. The playhead maps 1:1 onto frame
+ * indices, so play/pause/seek/rate come from GSAP and frames stream back
+ * through onUpdate. Swap-in for useStepPlayer's built-in timer:
+ *
+ *   const engine = useMemo(
+ *     () => createGsapPlayerEngine({ total: frames.length, baseDelayMs: 900 }),
+ *     [frames.length]
+ *   );
+ *   const player = useStepPlayer({ total: frames.length, engine });
+ */
+declare function createGsapPlayerEngine(opts: GsapEngineOptions): PlayerEngine;
+
+export { type GsapEngineOptions, createGsapPlayerEngine };

package/dist/adapters/gsap.js

@@ -0,0 +1,51 @@
+"use client";
+"use client";
+
+// src/adapters/gsap.ts
+import gsap from "gsap";
+function createGsapPlayerEngine(opts) {
+  return {
+    connect(api) {
+      const last = Math.max(0, opts.total - 1);
+      const proxy = { frame: 0 };
+      const duration = Math.max(1e-3, opts.total * (opts.baseDelayMs ?? 900) / 1e3);
+      let endFired = false;
+      const tween = gsap.to(proxy, {
+        frame: last,
+        duration,
+        ease: "none",
+        paused: true,
+        onUpdate: () => {
+          const frame = Math.min(Math.max(Math.floor(proxy.frame), 0), api.total - 1);
+          api.onFrame(frame);
+          if (!endFired && frame >= api.total - 1) {
+            endFired = true;
+            api.onEnd();
+          }
+        }
+      });
+      return {
+        play: () => {
+          tween.play();
+        },
+        pause: () => {
+          tween.pause();
+        },
+        seek: (frame) => {
+          tween.pause(Math.min(frame, last));
+          if (frame < last) endFired = false;
+        },
+        setRate: (rate) => {
+          tween.timeScale(rate);
+        },
+        disconnect: () => {
+          tween.kill();
+        }
+      };
+    }
+  };
+}
+export {
+  createGsapPlayerEngine
+};
+//# sourceMappingURL=gsap.js.map

package/dist/adapters/gsap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/gsap.ts"],"sourcesContent":["\"use client\";\n\nimport gsap from \"gsap\";\nimport type { PlayerEngine, PlayerEngineApi, PlayerEngineHandle } from \"../types\";\n\nexport interface GsapEngineOptions {\n  /** Frames in the current timeline. Recreate the engine when it changes. */\n  total: number;\n  /** Wall-clock time per frame at 1× speed. */\n  baseDelayMs?: number;\n}\n\n/**\n * PlayerEngine backed by a GSAP tween. The playhead maps 1:1 onto frame\n * indices, so play/pause/seek/rate come from GSAP and frames stream back\n * through onUpdate. Swap-in for useStepPlayer's built-in timer:\n *\n *   const engine = useMemo(\n *     () => createGsapPlayerEngine({ total: frames.length, baseDelayMs: 900 }),\n *     [frames.length]\n *   );\n *   const player = useStepPlayer({ total: frames.length, engine });\n */\nexport function createGsapPlayerEngine(opts: GsapEngineOptions): PlayerEngine {\n  return {\n    connect(api: PlayerEngineApi): PlayerEngineHandle {\n      const last = Math.max(0, opts.total - 1);\n      const proxy = { frame: 0 };\n      const duration = Math.max(0.001, (opts.total * (opts.baseDelayMs ?? 900)) / 1000);\n      // Port contract: onEnd fires once per run, on the transition into the\n      // final frame — not on every parked tick. Rewinding (seek below the\n      // last frame) re-arms it.\n      let endFired = false;\n      const tween = gsap.to(proxy, {\n        frame: last,\n        duration,\n        ease: \"none\",\n        paused: true,\n        onUpdate: () => {\n          const frame = Math.min(Math.max(Math.floor(proxy.frame), 0), api.total - 1);\n          api.onFrame(frame);\n          if (!endFired && frame >= api.total - 1) {\n            endFired = true;\n            api.onEnd();\n          }\n        },\n      });\n      return {\n        play: () => {\n          tween.play();\n        },\n        pause: () => {\n          tween.pause();\n        },\n        seek: (frame) => {\n          tween.pause(Math.min(frame, last));\n          if (frame < last) endFired = false;\n        },\n        setRate: (rate) => {\n          tween.timeScale(rate);\n        },\n        disconnect: () => {\n          tween.kill();\n        },\n      };\n    },\n  };\n}\n"],"mappings":";;;;AAEA,OAAO,UAAU;AAqBV,SAAS,uBAAuB,MAAuC;AAC5E,SAAO;AAAA,IACL,QAAQ,KAA0C;AAChD,YAAM,OAAO,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC;AACvC,YAAM,QAAQ,EAAE,OAAO,EAAE;AACzB,YAAM,WAAW,KAAK,IAAI,MAAQ,KAAK,SAAS,KAAK,eAAe,OAAQ,GAAI;AAIhF,UAAI,WAAW;AACf,YAAM,QAAQ,KAAK,GAAG,OAAO;AAAA,QAC3B,OAAO;AAAA,QACP;AAAA,QACA,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,UAAU,MAAM;AACd,gBAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,QAAQ,CAAC;AAC1E,cAAI,QAAQ,KAAK;AACjB,cAAI,CAAC,YAAY,SAAS,IAAI,QAAQ,GAAG;AACvC,uBAAW;AACX,gBAAI,MAAM;AAAA,UACZ;AAAA,QACF;AAAA,MACF,CAAC;AACD,aAAO;AAAA,QACL,MAAM,MAAM;AACV,gBAAM,KAAK;AAAA,QACb;AAAA,QACA,OAAO,MAAM;AACX,gBAAM,MAAM;AAAA,QACd;AAAA,QACA,MAAM,CAAC,UAAU;AACf,gBAAM,MAAM,KAAK,IAAI,OAAO,IAAI,CAAC;AACjC,cAAI,QAAQ,KAAM,YAAW;AAAA,QAC/B;AAAA,QACA,SAAS,CAAC,SAAS;AACjB,gBAAM,UAAU,IAAI;AAAA,QACtB;AAAA,QACA,YAAY,MAAM;AAChB,gBAAM,KAAK;AAAA,QACb;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/adapters/scroll.d.ts

@@ -0,0 +1,23 @@
+import { P as PlayerEngine } from '../types-IT_9L8On.js';
+import 'react';
+
+interface ScrollEngineOptions {
+    /** The scrollytelling section whose scroll progress drives the frames. */
+    getContainer: () => HTMLElement | null;
+    /** Frames in the current timeline. Recreate the engine when it changes. */
+    total: number;
+}
+/**
+ * PlayerEngine driven by scroll progress through a container section — the
+ * scrollytelling mode. Scrolling maps to frame indices; manual stepping seeks
+ * the scroll position; "play" smooth-scrolls to the end of the section.
+ * Dependency-free (a scrollama replacement for this specific job).
+ *
+ *   const engine = useMemo(
+ *     () => createScrollPlayerEngine({ getContainer: () => sectionRef.current, total: frames.length }),
+ *     [frames.length]
+ *   );
+ */
+declare function createScrollPlayerEngine(opts: ScrollEngineOptions): PlayerEngine;
+
+export { type ScrollEngineOptions, createScrollPlayerEngine };

package/dist/adapters/scroll.js

@@ -0,0 +1,71 @@
+"use client";
+"use client";
+
+// src/adapters/scroll.ts
+function createScrollPlayerEngine(opts) {
+  return {
+    connect(api) {
+      let playing = false;
+      let silent = false;
+      const progressToFrame = (progress) => Math.min(api.total - 1, Math.max(0, Math.floor(progress * api.total)));
+      const emitFromScroll = () => {
+        if (silent || !api) return;
+        const el = opts.getContainer();
+        if (!el) return;
+        const rect = el.getBoundingClientRect();
+        const scrollable = rect.height - window.innerHeight;
+        if (scrollable <= 0) return;
+        const progress = Math.min(1, Math.max(0, -rect.top / scrollable));
+        const frame = progressToFrame(progress);
+        api.onFrame(frame);
+        if (playing && frame >= api.total - 1) {
+          playing = false;
+          api.onEnd();
+        }
+      };
+      const scrollToProgress = (progress, smooth) => {
+        const el = opts.getContainer();
+        if (!el) return;
+        const rect = el.getBoundingClientRect();
+        const scrollable = rect.height - window.innerHeight;
+        if (scrollable <= 0) return;
+        const top = window.scrollY + rect.top + scrollable * Math.min(1, Math.max(0, progress));
+        silent = true;
+        window.scrollTo({ top, behavior: smooth ? "smooth" : "auto" });
+        window.setTimeout(() => {
+          silent = false;
+        }, smooth ? 700 : 50);
+      };
+      const onScroll = () => emitFromScroll();
+      window.addEventListener("scroll", onScroll, { passive: true });
+      window.addEventListener("resize", onScroll);
+      return {
+        play: () => {
+          playing = true;
+          const el = opts.getContainer();
+          if (!el) return;
+          scrollToProgress(1, true);
+        },
+        pause: () => {
+          playing = false;
+        },
+        seek: (frame) => {
+          const progress = api.total > 1 ? frame / api.total : 0;
+          scrollToProgress(progress, false);
+          api.onFrame(Math.min(frame, api.total - 1));
+        },
+        setRate: () => {
+        },
+        disconnect: () => {
+          playing = false;
+          window.removeEventListener("scroll", onScroll);
+          window.removeEventListener("resize", onScroll);
+        }
+      };
+    }
+  };
+}
+export {
+  createScrollPlayerEngine
+};
+//# sourceMappingURL=scroll.js.map

package/dist/adapters/scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/scroll.ts"],"sourcesContent":["\"use client\";\n\nimport type { PlayerEngine, PlayerEngineApi, PlayerEngineHandle } from \"../types\";\n\nexport interface ScrollEngineOptions {\n  /** The scrollytelling section whose scroll progress drives the frames. */\n  getContainer: () => HTMLElement | null;\n  /** Frames in the current timeline. Recreate the engine when it changes. */\n  total: number;\n}\n\n/**\n * PlayerEngine driven by scroll progress through a container section — the\n * scrollytelling mode. Scrolling maps to frame indices; manual stepping seeks\n * the scroll position; \"play\" smooth-scrolls to the end of the section.\n * Dependency-free (a scrollama replacement for this specific job).\n *\n *   const engine = useMemo(\n *     () => createScrollPlayerEngine({ getContainer: () => sectionRef.current, total: frames.length }),\n *     [frames.length]\n *   );\n */\nexport function createScrollPlayerEngine(opts: ScrollEngineOptions): PlayerEngine {\n  return {\n    connect(api: PlayerEngineApi): PlayerEngineHandle {\n      let playing = false;\n      let silent = false;\n\n      const progressToFrame = (progress: number) =>\n        Math.min(api.total - 1, Math.max(0, Math.floor(progress * api.total)));\n\n      const emitFromScroll = () => {\n        if (silent || !api) return;\n        const el = opts.getContainer();\n        if (!el) return;\n        const rect = el.getBoundingClientRect();\n        const scrollable = rect.height - window.innerHeight;\n        if (scrollable <= 0) return;\n        const progress = Math.min(1, Math.max(0, -rect.top / scrollable));\n        const frame = progressToFrame(progress);\n        api.onFrame(frame);\n        if (playing && frame >= api.total - 1) {\n          playing = false;\n          api.onEnd();\n        }\n      };\n\n      /** Scroll the window so the section sits at `progress` (0..1). */\n      const scrollToProgress = (progress: number, smooth: boolean) => {\n        const el = opts.getContainer();\n        if (!el) return;\n        const rect = el.getBoundingClientRect();\n        const scrollable = rect.height - window.innerHeight;\n        if (scrollable <= 0) return;\n        const top = window.scrollY + rect.top + scrollable * Math.min(1, Math.max(0, progress));\n        silent = true;\n        window.scrollTo({ top, behavior: smooth ? \"smooth\" : \"auto\" });\n        // Silence the synthetic scroll events until the scroll settles.\n        window.setTimeout(() => {\n          silent = false;\n        }, smooth ? 700 : 50);\n      };\n\n      const onScroll = () => emitFromScroll();\n\n      window.addEventListener(\"scroll\", onScroll, { passive: true });\n      window.addEventListener(\"resize\", onScroll);\n\n      return {\n        play: () => {\n          playing = true;\n          const el = opts.getContainer();\n          if (!el) return;\n          scrollToProgress(1, true);\n        },\n        pause: () => {\n          playing = false;\n        },\n        seek: (frame) => {\n          const progress = api.total > 1 ? frame / api.total : 0;\n          scrollToProgress(progress, false);\n          api.onFrame(Math.min(frame, api.total - 1));\n        },\n        setRate: () => {\n          // Scroll position is user-driven; rate has no meaning here.\n        },\n        disconnect: () => {\n          playing = false;\n          window.removeEventListener(\"scroll\", onScroll);\n          window.removeEventListener(\"resize\", onScroll);\n        },\n      };\n    },\n  };\n}\n"],"mappings":";;;;AAsBO,SAAS,yBAAyB,MAAyC;AAChF,SAAO;AAAA,IACL,QAAQ,KAA0C;AAChD,UAAI,UAAU;AACd,UAAI,SAAS;AAEb,YAAM,kBAAkB,CAAC,aACvB,KAAK,IAAI,IAAI,QAAQ,GAAG,KAAK,IAAI,GAAG,KAAK,MAAM,WAAW,IAAI,KAAK,CAAC,CAAC;AAEvE,YAAM,iBAAiB,MAAM;AAC3B,YAAI,UAAU,CAAC,IAAK;AACpB,cAAM,KAAK,KAAK,aAAa;AAC7B,YAAI,CAAC,GAAI;AACT,cAAM,OAAO,GAAG,sBAAsB;AACtC,cAAM,aAAa,KAAK,SAAS,OAAO;AACxC,YAAI,cAAc,EAAG;AACrB,cAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,KAAK,MAAM,UAAU,CAAC;AAChE,cAAM,QAAQ,gBAAgB,QAAQ;AACtC,YAAI,QAAQ,KAAK;AACjB,YAAI,WAAW,SAAS,IAAI,QAAQ,GAAG;AACrC,oBAAU;AACV,cAAI,MAAM;AAAA,QACZ;AAAA,MACF;AAGA,YAAM,mBAAmB,CAAC,UAAkB,WAAoB;AAC9D,cAAM,KAAK,KAAK,aAAa;AAC7B,YAAI,CAAC,GAAI;AACT,cAAM,OAAO,GAAG,sBAAsB;AACtC,cAAM,aAAa,KAAK,SAAS,OAAO;AACxC,YAAI,cAAc,EAAG;AACrB,cAAM,MAAM,OAAO,UAAU,KAAK,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC;AACtF,iBAAS;AACT,eAAO,SAAS,EAAE,KAAK,UAAU,SAAS,WAAW,OAAO,CAAC;AAE7D,eAAO,WAAW,MAAM;AACtB,mBAAS;AAAA,QACX,GAAG,SAAS,MAAM,EAAE;AAAA,MACtB;AAEA,YAAM,WAAW,MAAM,eAAe;AAEtC,aAAO,iBAAiB,UAAU,UAAU,EAAE,SAAS,KAAK,CAAC;AAC7D,aAAO,iBAAiB,UAAU,QAAQ;AAE1C,aAAO;AAAA,QACL,MAAM,MAAM;AACV,oBAAU;AACV,gBAAM,KAAK,KAAK,aAAa;AAC7B,cAAI,CAAC,GAAI;AACT,2BAAiB,GAAG,IAAI;AAAA,QAC1B;AAAA,QACA,OAAO,MAAM;AACX,oBAAU;AAAA,QACZ;AAAA,QACA,MAAM,CAAC,UAAU;AACf,gBAAM,WAAW,IAAI,QAAQ,IAAI,QAAQ,IAAI,QAAQ;AACrD,2BAAiB,UAAU,KAAK;AAChC,cAAI,QAAQ,KAAK,IAAI,OAAO,IAAI,QAAQ,CAAC,CAAC;AAAA,QAC5C;AAAA,QACA,SAAS,MAAM;AAAA,QAEf;AAAA,QACA,YAAY,MAAM;AAChB,oBAAU;AACV,iBAAO,oBAAoB,UAAU,QAAQ;AAC7C,iBAAO,oBAAoB,UAAU,QAAQ;AAAA,QAC/C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}