@multitrack/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Jack Hsu
+
+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,96 @@
+# @multitrack/react
+
+React bindings for [`@multitrack/core`](https://github.com/jakhsu/multitrack/tree/main/packages/core) — a scroll-driven animation engine with a multi-track timeline architecture.
+
+## Install
+
+```bash
+npm install @multitrack/core @multitrack/react
+```
+
+## Quick start
+
+```tsx
+import { MultitrackProvider, ScrollContainer, FixedStage, Show, useStep } from "@multitrack/react";
+import type { StepConfig } from "@multitrack/core";
+
+const config: StepConfig[] = [
+  { name: "intro", duration: 3, track: "main", easing: "linear" },
+  { name: "feature", duration: 5, track: "main" },
+  { name: "outro", duration: 3, track: "main", easing: "linear" },
+];
+
+function App() {
+  return (
+    <MultitrackProvider config={config}>
+      <ScrollContainer>
+        <FixedStage>
+          <Show when="intro">
+            <IntroSection />
+          </Show>
+          <Show when="feature">
+            <FeatureSection />
+          </Show>
+        </FixedStage>
+      </ScrollContainer>
+    </MultitrackProvider>
+  );
+}
+
+function IntroSection() {
+  const { opacity } = useStep("intro");
+  return (
+    <div style={{ opacity, transform: `translateY(${(1 - opacity) * 40}px)` }}>
+      <h1>Welcome</h1>
+    </div>
+  );
+}
+```
+
+## API
+
+### `<MultitrackProvider>`
+
+Wraps your app and creates the timeline instance. All hooks and components must be used within this provider.
+
+```tsx
+<MultitrackProvider config={config} breakpoints={breakpoints} devtools>
+  {children}
+</MultitrackProvider>
+```
+
+### Hooks
+
+#### `useStep(name)`
+
+Returns `{ opacity, isActive }` for a single step. Re-renders only when the step's values change.
+
+#### `useOpacities()`
+
+Returns an `Opacities` record (`{ [stepName]: number }`) for all steps.
+
+#### `useScrollProgress()`
+
+Returns the current scroll progress (0–1).
+
+#### `useTimeline()`
+
+Returns the underlying `Timeline` instance for advanced use cases.
+
+### Components
+
+#### `<ScrollContainer>`
+
+The scrollable container that drives the timeline. Renders a `<div>` with the correct scroll height.
+
+#### `<FixedStage>`
+
+A fixed-position overlay inside `ScrollContainer` for content that stays in the viewport while scrolling.
+
+#### `<Show when="stepName">`
+
+Conditionally renders children when the named step is active (opacity > 0).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,141 @@
+'use strict';
+
+var react = require('react');
+var core = require('@multitrack/core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/provider.tsx
+var MultitrackContext = react.createContext(
+  null
+);
+function MultitrackProvider({
+  config,
+  devtools = false,
+  breakpoints,
+  children
+}) {
+  const timelineRef = react.useRef(null);
+  const timeline = react.useMemo(() => {
+    timelineRef.current?.destroy();
+    const t = new core.Timeline({ config, devtools, breakpoints });
+    timelineRef.current = t;
+    return t;
+  }, [config, devtools, breakpoints]);
+  const [state, setState] = react.useState({
+    scrollPercentage: 0,
+    currentStep: 0,
+    opacities: timeline.getOpacities(0)
+  });
+  react.useEffect(() => {
+    const ctx = timeline.scope(() => {
+      timeline.on("scroll", ({ scrollPercentage, currentStep }) => {
+        setState({
+          scrollPercentage,
+          currentStep,
+          opacities: timeline.getOpacities(scrollPercentage)
+        });
+      });
+      timeline.on("timeline:reconfigure", () => {
+        setState({
+          scrollPercentage: timeline.scrollPercentage,
+          currentStep: timeline.currentStep,
+          opacities: timeline.getOpacities()
+        });
+      });
+    });
+    timeline.start();
+    return () => {
+      ctx.dispose();
+      timeline.destroy();
+    };
+  }, [timeline]);
+  const contextValue = {
+    timeline,
+    steps: timeline.steps,
+    totalSteps: timeline.totalSteps,
+    scrollPercentage: state.scrollPercentage,
+    currentStep: state.currentStep,
+    opacities: state.opacities
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(MultitrackContext.Provider, { value: contextValue, children });
+}
+function useMultitrackContext() {
+  const ctx = react.useContext(MultitrackContext);
+  if (!ctx) {
+    throw new Error(
+      "[@multitrack/react] useTimeline must be used within a <MultitrackProvider>"
+    );
+  }
+  return ctx;
+}
+function useTimeline() {
+  return useMultitrackContext().timeline;
+}
+function useOpacities() {
+  return useMultitrackContext().opacities;
+}
+function useStep(name) {
+  const { opacities } = useMultitrackContext();
+  const opacity = opacities[name] ?? 0;
+  return { opacity, isActive: opacity > 0 };
+}
+function useScrollProgress() {
+  const { scrollPercentage, currentStep, totalSteps } = useMultitrackContext();
+  return { scrollPercentage, currentStep, totalSteps };
+}
+function ScrollContainer({
+  children,
+  className,
+  style
+}) {
+  const { totalSteps } = useScrollProgress();
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      style: { height: `${totalSteps * 100}vh`, position: "relative", ...style },
+      className,
+      children
+    }
+  );
+}
+function FixedStage({
+  children,
+  className,
+  style
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100vh",
+        touchAction: "pan-y",
+        ...style
+      },
+      className,
+      children
+    }
+  );
+}
+function Show({
+  when,
+  children
+}) {
+  const { isActive } = useStep(when);
+  if (!isActive) return null;
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+}
+
+exports.FixedStage = FixedStage;
+exports.MultitrackProvider = MultitrackProvider;
+exports.ScrollContainer = ScrollContainer;
+exports.Show = Show;
+exports.useOpacities = useOpacities;
+exports.useScrollProgress = useScrollProgress;
+exports.useStep = useStep;
+exports.useTimeline = useTimeline;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/provider.tsx","../src/hooks.ts","../src/components.tsx"],"names":["createContext","useRef","useMemo","Timeline","useState","useEffect","useContext","jsx","Fragment"],"mappings":";;;;;;;AAYO,IAAM,iBAAA,GAAoBA,mBAAA;AAAA,EAC/B;AACF,CAAA;ACUO,SAAS,kBAAA,CAAmB;AAAA,EACjC,MAAA;AAAA,EACA,QAAA,GAAW,KAAA;AAAA,EACX,WAAA;AAAA,EACA;AACF,CAAA,EAA4B;AAC1B,EAAA,MAAM,WAAA,GAAcC,aAAwB,IAAI,CAAA;AAGhD,EAAA,MAAM,QAAA,GAAWC,cAAQ,MAAM;AAC7B,IAAA,WAAA,CAAY,SAAS,OAAA,EAAQ;AAC7B,IAAA,MAAM,IAAI,IAAIC,aAAA,CAAS,EAAE,MAAA,EAAQ,QAAA,EAAU,aAAa,CAAA;AACxD,IAAA,WAAA,CAAY,OAAA,GAAU,CAAA;AACtB,IAAA,OAAO,CAAA;AAAA,EACT,CAAA,EAAG,CAAC,MAAA,EAAQ,QAAA,EAAU,WAAW,CAAC,CAAA;AAElC,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAIC,cAAA,CAAS;AAAA,IACjC,gBAAA,EAAkB,CAAA;AAAA,IAClB,WAAA,EAAa,CAAA;AAAA,IACb,SAAA,EAAW,QAAA,CAAS,YAAA,CAAa,CAAC;AAAA,GACnC,CAAA;AAED,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,MAAM,GAAA,GAAM,QAAA,CAAS,KAAA,CAAM,MAAM;AAC/B,MAAA,QAAA,CAAS,GAAG,QAAA,EAAU,CAAC,EAAE,gBAAA,EAAkB,aAAY,KAAM;AAC3D,QAAA,QAAA,CAAS;AAAA,UACP,gBAAA;AAAA,UACA,WAAA;AAAA,UACA,SAAA,EAAW,QAAA,CAAS,YAAA,CAAa,gBAAgB;AAAA,SAClD,CAAA;AAAA,MACH,CAAC,CAAA;AAGD,MAAA,QAAA,CAAS,EAAA,CAAG,wBAAwB,MAAM;AACxC,QAAA,QAAA,CAAS;AAAA,UACP,kBAAkB,QAAA,CAAS,gBAAA;AAAA,UAC3B,aAAa,QAAA,CAAS,WAAA;AAAA,UACtB,SAAA,EAAW,SAAS,YAAA;AAAa,SAClC,CAAA;AAAA,MACH,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAED,IAAA,QAAA,CAAS,KAAA,EAAM;AAEf,IAAA,OAAO,MAAM;AACX,MAAA,GAAA,CAAI,OAAA,EAAQ;AACZ,MAAA,QAAA,CAAS,OAAA,EAAQ;AAAA,IACnB,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,QAAQ,CAAC,CAAA;AAEb,EAAA,MAAM,YAAA,GAAuC;AAAA,IAC3C,QAAA;AAAA,IACA,OAAO,QAAA,CAAS,KAAA;AAAA,IAChB,YAAY,QAAA,CAAS,UAAA;AAAA,IACrB,kBAAkB,KAAA,CAAM,gBAAA;AAAA,IACxB,aAAa,KAAA,CAAM,WAAA;AAAA,IACnB,WAAW,KAAA,CAAM;AAAA,GACnB;AAEA,EAAA,sCACG,iBAAA,CAAkB,QAAA,EAAlB,EAA2B,KAAA,EAAO,cAChC,QAAA,EACH,CAAA;AAEJ;ACpFA,SAAS,oBAAA,GAAuB;AAC9B,EAAA,MAAM,GAAA,GAAMC,iBAAW,iBAAiB,CAAA;AACxC,EAAA,IAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT;AAKO,SAAS,WAAA,GAAwB;AACtC,EAAA,OAAO,sBAAqB,CAAE,QAAA;AAChC;AAKO,SAAS,YAAA,GAAwD;AACtE,EAAA,OAAO,sBAAqB,CAAE,SAAA;AAChC;AAKO,SAAS,QAAQ,IAAA,EAAsD;AAC5E,EAAA,MAAM,EAAE,SAAA,EAAU,GAAI,oBAAA,EAAqB;AAC3C,EAAA,MAAM,OAAA,GAAU,SAAA,CAAU,IAAI,CAAA,IAAK,CAAA;AACnC,EAAA,OAAO,EAAE,OAAA,EAAS,QAAA,EAAU,OAAA,GAAU,CAAA,EAAE;AAC1C;AAKO,SAAS,iBAAA,GAId;AACA,EAAA,MAAM,EAAE,gBAAA,EAAkB,WAAA,EAAa,UAAA,KACrC,oBAAA,EAAqB;AACvB,EAAA,OAAO,EAAE,gBAAA,EAAkB,WAAA,EAAa,UAAA,EAAW;AACrD;ACtCO,SAAS,eAAA,CAAgB;AAAA,EAC9B,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAA,EAIG;AACD,EAAA,MAAM,EAAE,UAAA,EAAW,GAAI,iBAAA,EAAkB;AAEzC,EAAA,uBACEC,cAAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,EAAE,MAAA,EAAQ,CAAA,EAAG,UAAA,GAAa,GAAG,CAAA,EAAA,CAAA,EAAM,QAAA,EAAU,UAAA,EAAY,GAAG,KAAA,EAAM;AAAA,MACzE,SAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ;AASO,SAAS,UAAA,CAAW;AAAA,EACzB,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAA,EAIG;AACD,EAAA,uBACEA,cAAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO;AAAA,QACL,QAAA,EAAU,OAAA;AAAA,QACV,GAAA,EAAK,CAAA;AAAA,QACL,IAAA,EAAM,CAAA;AAAA,QACN,KAAA,EAAO,MAAA;AAAA,QACP,MAAA,EAAQ,OAAA;AAAA,QACR,WAAA,EAAa,OAAA;AAAA,QACb,GAAG;AAAA,OACL;AAAA,MACA,SAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ;AAQO,SAAS,IAAA,CAAK;AAAA,EACnB,IAAA;AAAA,EACA;AACF,CAAA,EAIG;AACD,EAAA,MAAM,EAAE,QAAA,EAAS,GAAI,OAAA,CAAQ,IAAI,CAAA;AACjC,EAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AACtB,EAAA,uBAAOA,cAAAA,CAAAC,mBAAA,EAAA,EAAG,QAAA,EAAS,CAAA;AACrB","file":"index.cjs","sourcesContent":["import { createContext } from \"react\";\nimport type { Timeline, Opacities, Step } from \"@multitrack/core\";\n\nexport interface MultitrackContextValue {\n  timeline: Timeline;\n  steps: Step[];\n  totalSteps: number;\n  scrollPercentage: number;\n  currentStep: number;\n  opacities: Opacities;\n}\n\nexport const MultitrackContext = createContext<MultitrackContextValue | null>(\n  null,\n);\n","import {\n  useRef,\n  useState,\n  useEffect,\n  useMemo,\n  type ReactNode,\n} from \"react\";\nimport { Timeline, type StepConfig } from \"@multitrack/core\";\nimport { MultitrackContext, type MultitrackContextValue } from \"./context.js\";\n\nexport interface MultitrackProviderProps {\n  /** Step configuration array. */\n  config: StepConfig[];\n  /** Enable devtools integration. */\n  devtools?: boolean;\n  /** Named breakpoints for responsive step inclusion. */\n  breakpoints?: Record<string, string>;\n  children: ReactNode;\n}\n\n/**\n * Provides timeline state to all child components via React context.\n * Manages scroll listening and re-renders children when scroll position changes.\n */\nexport function MultitrackProvider({\n  config,\n  devtools = false,\n  breakpoints,\n  children,\n}: MultitrackProviderProps) {\n  const timelineRef = useRef<Timeline | null>(null);\n\n  // Create timeline instance (stable across renders unless config changes)\n  const timeline = useMemo(() => {\n    timelineRef.current?.destroy();\n    const t = new Timeline({ config, devtools, breakpoints });\n    timelineRef.current = t;\n    return t;\n  }, [config, devtools, breakpoints]);\n\n  const [state, setState] = useState({\n    scrollPercentage: 0,\n    currentStep: 0,\n    opacities: timeline.getOpacities(0),\n  });\n\n  useEffect(() => {\n    const ctx = timeline.scope(() => {\n      timeline.on(\"scroll\", ({ scrollPercentage, currentStep }) => {\n        setState({\n          scrollPercentage,\n          currentStep,\n          opacities: timeline.getOpacities(scrollPercentage),\n        });\n      });\n\n      // Re-render when breakpoints change and steps are reconfigured\n      timeline.on(\"timeline:reconfigure\", () => {\n        setState({\n          scrollPercentage: timeline.scrollPercentage,\n          currentStep: timeline.currentStep,\n          opacities: timeline.getOpacities(),\n        });\n      });\n    });\n\n    timeline.start();\n\n    return () => {\n      ctx.dispose();\n      timeline.destroy();\n    };\n  }, [timeline]);\n\n  const contextValue: MultitrackContextValue = {\n    timeline,\n    steps: timeline.steps,\n    totalSteps: timeline.totalSteps,\n    scrollPercentage: state.scrollPercentage,\n    currentStep: state.currentStep,\n    opacities: state.opacities,\n  };\n\n  return (\n    <MultitrackContext.Provider value={contextValue}>\n      {children}\n    </MultitrackContext.Provider>\n  );\n}\n","import { useContext } from \"react\";\nimport type { Timeline, Opacities } from \"@multitrack/core\";\nimport { MultitrackContext } from \"./context.js\";\n\nfunction useMultitrackContext() {\n  const ctx = useContext(MultitrackContext);\n  if (!ctx) {\n    throw new Error(\n      \"[@multitrack/react] useTimeline must be used within a <MultitrackProvider>\",\n    );\n  }\n  return ctx;\n}\n\n/**\n * Access the Timeline instance directly.\n */\nexport function useTimeline(): Timeline {\n  return useMultitrackContext().timeline;\n}\n\n/**\n * Get current opacities for all steps.\n */\nexport function useOpacities<T extends string = string>(): Opacities<T> {\n  return useMultitrackContext().opacities as Opacities<T>;\n}\n\n/**\n * Get opacity and active state for a single named step.\n */\nexport function useStep(name: string): { opacity: number; isActive: boolean } {\n  const { opacities } = useMultitrackContext();\n  const opacity = opacities[name] ?? 0;\n  return { opacity, isActive: opacity > 0 };\n}\n\n/**\n * Get raw scroll progress and current step position.\n */\nexport function useScrollProgress(): {\n  scrollPercentage: number;\n  currentStep: number;\n  totalSteps: number;\n} {\n  const { scrollPercentage, currentStep, totalSteps } =\n    useMultitrackContext();\n  return { scrollPercentage, currentStep, totalSteps };\n}\n","import type { ReactNode, CSSProperties } from \"react\";\nimport { useScrollProgress, useStep } from \"./hooks.js\";\n\n/**\n * Creates the tall scrollable container that drives the timeline.\n * Height = totalSteps * 100vh.\n *\n * Extracted from sinking-china MainMap.tsx line 193:\n * `<div style={{ height: `${totalSteps * 100}vh` }} className=\"relative\">`\n */\nexport function ScrollContainer({\n  children,\n  className,\n  style,\n}: {\n  children: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}) {\n  const { totalSteps } = useScrollProgress();\n\n  return (\n    <div\n      style={{ height: `${totalSteps * 100}vh`, position: \"relative\", ...style }}\n      className={className}\n    >\n      {children}\n    </div>\n  );\n}\n\n/**\n * Fixed viewport stage that stays in place while the user scrolls.\n * All animated content lives inside this.\n *\n * Extracted from sinking-china MainMap.tsx lines 200-207:\n * `<div style={{ position: \"fixed\", width: \"100%\", height: \"100vh\", touchAction: \"pan-y\" }}>`\n */\nexport function FixedStage({\n  children,\n  className,\n  style,\n}: {\n  children: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}) {\n  return (\n    <div\n      style={{\n        position: \"fixed\",\n        top: 0,\n        left: 0,\n        width: \"100%\",\n        height: \"100vh\",\n        touchAction: \"pan-y\",\n        ...style,\n      }}\n      className={className}\n    >\n      {children}\n    </div>\n  );\n}\n\n/**\n * Conditionally renders children based on a step's opacity.\n * Unmounts children when the step is inactive (opacity 0) for performance.\n *\n * Extracted from sinking-china ConditionalRender.tsx.\n */\nexport function Show({\n  when,\n  children,\n}: {\n  /** Step name to check. Children render when this step's opacity > 0. */\n  when: string;\n  children: ReactNode;\n}) {\n  const { isActive } = useStep(when);\n  if (!isActive) return null;\n  return <>{children}</>;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+import { StepConfig, Opacities, Timeline } from '@multitrack/core';
+export { EasingPreset, Opacities, StepConfig } from '@multitrack/core';
+
+interface MultitrackProviderProps {
+    /** Step configuration array. */
+    config: StepConfig[];
+    /** Enable devtools integration. */
+    devtools?: boolean;
+    /** Named breakpoints for responsive step inclusion. */
+    breakpoints?: Record<string, string>;
+    children: ReactNode;
+}
+/**
+ * Provides timeline state to all child components via React context.
+ * Manages scroll listening and re-renders children when scroll position changes.
+ */
+declare function MultitrackProvider({ config, devtools, breakpoints, children, }: MultitrackProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Timeline instance directly.
+ */
+declare function useTimeline(): Timeline;
+/**
+ * Get current opacities for all steps.
+ */
+declare function useOpacities<T extends string = string>(): Opacities<T>;
+/**
+ * Get opacity and active state for a single named step.
+ */
+declare function useStep(name: string): {
+    opacity: number;
+    isActive: boolean;
+};
+/**
+ * Get raw scroll progress and current step position.
+ */
+declare function useScrollProgress(): {
+    scrollPercentage: number;
+    currentStep: number;
+    totalSteps: number;
+};
+
+/**
+ * Creates the tall scrollable container that drives the timeline.
+ * Height = totalSteps * 100vh.
+ *
+ * Extracted from sinking-china MainMap.tsx line 193:
+ * `<div style={{ height: `${totalSteps * 100}vh` }} className="relative">`
+ */
+declare function ScrollContainer({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Fixed viewport stage that stays in place while the user scrolls.
+ * All animated content lives inside this.
+ *
+ * Extracted from sinking-china MainMap.tsx lines 200-207:
+ * `<div style={{ position: "fixed", width: "100%", height: "100vh", touchAction: "pan-y" }}>`
+ */
+declare function FixedStage({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Conditionally renders children based on a step's opacity.
+ * Unmounts children when the step is inactive (opacity 0) for performance.
+ *
+ * Extracted from sinking-china ConditionalRender.tsx.
+ */
+declare function Show({ when, children, }: {
+    /** Step name to check. Children render when this step's opacity > 0. */
+    when: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+
+export { FixedStage, MultitrackProvider, type MultitrackProviderProps, ScrollContainer, Show, useOpacities, useScrollProgress, useStep, useTimeline };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+import { StepConfig, Opacities, Timeline } from '@multitrack/core';
+export { EasingPreset, Opacities, StepConfig } from '@multitrack/core';
+
+interface MultitrackProviderProps {
+    /** Step configuration array. */
+    config: StepConfig[];
+    /** Enable devtools integration. */
+    devtools?: boolean;
+    /** Named breakpoints for responsive step inclusion. */
+    breakpoints?: Record<string, string>;
+    children: ReactNode;
+}
+/**
+ * Provides timeline state to all child components via React context.
+ * Manages scroll listening and re-renders children when scroll position changes.
+ */
+declare function MultitrackProvider({ config, devtools, breakpoints, children, }: MultitrackProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Timeline instance directly.
+ */
+declare function useTimeline(): Timeline;
+/**
+ * Get current opacities for all steps.
+ */
+declare function useOpacities<T extends string = string>(): Opacities<T>;
+/**
+ * Get opacity and active state for a single named step.
+ */
+declare function useStep(name: string): {
+    opacity: number;
+    isActive: boolean;
+};
+/**
+ * Get raw scroll progress and current step position.
+ */
+declare function useScrollProgress(): {
+    scrollPercentage: number;
+    currentStep: number;
+    totalSteps: number;
+};
+
+/**
+ * Creates the tall scrollable container that drives the timeline.
+ * Height = totalSteps * 100vh.
+ *
+ * Extracted from sinking-china MainMap.tsx line 193:
+ * `<div style={{ height: `${totalSteps * 100}vh` }} className="relative">`
+ */
+declare function ScrollContainer({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Fixed viewport stage that stays in place while the user scrolls.
+ * All animated content lives inside this.
+ *
+ * Extracted from sinking-china MainMap.tsx lines 200-207:
+ * `<div style={{ position: "fixed", width: "100%", height: "100vh", touchAction: "pan-y" }}>`
+ */
+declare function FixedStage({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Conditionally renders children based on a step's opacity.
+ * Unmounts children when the step is inactive (opacity 0) for performance.
+ *
+ * Extracted from sinking-china ConditionalRender.tsx.
+ */
+declare function Show({ when, children, }: {
+    /** Step name to check. Children render when this step's opacity > 0. */
+    when: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+
+export { FixedStage, MultitrackProvider, type MultitrackProviderProps, ScrollContainer, Show, useOpacities, useScrollProgress, useStep, useTimeline };

package/dist/index.js

@@ -0,0 +1,132 @@
+import { createContext, useRef, useMemo, useState, useEffect, useContext } from 'react';
+import { Timeline } from '@multitrack/core';
+import { jsx, Fragment } from 'react/jsx-runtime';
+
+// src/provider.tsx
+var MultitrackContext = createContext(
+  null
+);
+function MultitrackProvider({
+  config,
+  devtools = false,
+  breakpoints,
+  children
+}) {
+  const timelineRef = useRef(null);
+  const timeline = useMemo(() => {
+    timelineRef.current?.destroy();
+    const t = new Timeline({ config, devtools, breakpoints });
+    timelineRef.current = t;
+    return t;
+  }, [config, devtools, breakpoints]);
+  const [state, setState] = useState({
+    scrollPercentage: 0,
+    currentStep: 0,
+    opacities: timeline.getOpacities(0)
+  });
+  useEffect(() => {
+    const ctx = timeline.scope(() => {
+      timeline.on("scroll", ({ scrollPercentage, currentStep }) => {
+        setState({
+          scrollPercentage,
+          currentStep,
+          opacities: timeline.getOpacities(scrollPercentage)
+        });
+      });
+      timeline.on("timeline:reconfigure", () => {
+        setState({
+          scrollPercentage: timeline.scrollPercentage,
+          currentStep: timeline.currentStep,
+          opacities: timeline.getOpacities()
+        });
+      });
+    });
+    timeline.start();
+    return () => {
+      ctx.dispose();
+      timeline.destroy();
+    };
+  }, [timeline]);
+  const contextValue = {
+    timeline,
+    steps: timeline.steps,
+    totalSteps: timeline.totalSteps,
+    scrollPercentage: state.scrollPercentage,
+    currentStep: state.currentStep,
+    opacities: state.opacities
+  };
+  return /* @__PURE__ */ jsx(MultitrackContext.Provider, { value: contextValue, children });
+}
+function useMultitrackContext() {
+  const ctx = useContext(MultitrackContext);
+  if (!ctx) {
+    throw new Error(
+      "[@multitrack/react] useTimeline must be used within a <MultitrackProvider>"
+    );
+  }
+  return ctx;
+}
+function useTimeline() {
+  return useMultitrackContext().timeline;
+}
+function useOpacities() {
+  return useMultitrackContext().opacities;
+}
+function useStep(name) {
+  const { opacities } = useMultitrackContext();
+  const opacity = opacities[name] ?? 0;
+  return { opacity, isActive: opacity > 0 };
+}
+function useScrollProgress() {
+  const { scrollPercentage, currentStep, totalSteps } = useMultitrackContext();
+  return { scrollPercentage, currentStep, totalSteps };
+}
+function ScrollContainer({
+  children,
+  className,
+  style
+}) {
+  const { totalSteps } = useScrollProgress();
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: { height: `${totalSteps * 100}vh`, position: "relative", ...style },
+      className,
+      children
+    }
+  );
+}
+function FixedStage({
+  children,
+  className,
+  style
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100vh",
+        touchAction: "pan-y",
+        ...style
+      },
+      className,
+      children
+    }
+  );
+}
+function Show({
+  when,
+  children
+}) {
+  const { isActive } = useStep(when);
+  if (!isActive) return null;
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+
+export { FixedStage, MultitrackProvider, ScrollContainer, Show, useOpacities, useScrollProgress, useStep, useTimeline };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/provider.tsx","../src/hooks.ts","../src/components.tsx"],"names":["jsx"],"mappings":"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","file":"index.js","sourcesContent":["import { createContext } from \"react\";\nimport type { Timeline, Opacities, Step } from \"@multitrack/core\";\n\nexport interface MultitrackContextValue {\n  timeline: Timeline;\n  steps: Step[];\n  totalSteps: number;\n  scrollPercentage: number;\n  currentStep: number;\n  opacities: Opacities;\n}\n\nexport const MultitrackContext = createContext<MultitrackContextValue | null>(\n  null,\n);\n","import {\n  useRef,\n  useState,\n  useEffect,\n  useMemo,\n  type ReactNode,\n} from \"react\";\nimport { Timeline, type StepConfig } from \"@multitrack/core\";\nimport { MultitrackContext, type MultitrackContextValue } from \"./context.js\";\n\nexport interface MultitrackProviderProps {\n  /** Step configuration array. */\n  config: StepConfig[];\n  /** Enable devtools integration. */\n  devtools?: boolean;\n  /** Named breakpoints for responsive step inclusion. */\n  breakpoints?: Record<string, string>;\n  children: ReactNode;\n}\n\n/**\n * Provides timeline state to all child components via React context.\n * Manages scroll listening and re-renders children when scroll position changes.\n */\nexport function MultitrackProvider({\n  config,\n  devtools = false,\n  breakpoints,\n  children,\n}: MultitrackProviderProps) {\n  const timelineRef = useRef<Timeline | null>(null);\n\n  // Create timeline instance (stable across renders unless config changes)\n  const timeline = useMemo(() => {\n    timelineRef.current?.destroy();\n    const t = new Timeline({ config, devtools, breakpoints });\n    timelineRef.current = t;\n    return t;\n  }, [config, devtools, breakpoints]);\n\n  const [state, setState] = useState({\n    scrollPercentage: 0,\n    currentStep: 0,\n    opacities: timeline.getOpacities(0),\n  });\n\n  useEffect(() => {\n    const ctx = timeline.scope(() => {\n      timeline.on(\"scroll\", ({ scrollPercentage, currentStep }) => {\n        setState({\n          scrollPercentage,\n          currentStep,\n          opacities: timeline.getOpacities(scrollPercentage),\n        });\n      });\n\n      // Re-render when breakpoints change and steps are reconfigured\n      timeline.on(\"timeline:reconfigure\", () => {\n        setState({\n          scrollPercentage: timeline.scrollPercentage,\n          currentStep: timeline.currentStep,\n          opacities: timeline.getOpacities(),\n        });\n      });\n    });\n\n    timeline.start();\n\n    return () => {\n      ctx.dispose();\n      timeline.destroy();\n    };\n  }, [timeline]);\n\n  const contextValue: MultitrackContextValue = {\n    timeline,\n    steps: timeline.steps,\n    totalSteps: timeline.totalSteps,\n    scrollPercentage: state.scrollPercentage,\n    currentStep: state.currentStep,\n    opacities: state.opacities,\n  };\n\n  return (\n    <MultitrackContext.Provider value={contextValue}>\n      {children}\n    </MultitrackContext.Provider>\n  );\n}\n","import { useContext } from \"react\";\nimport type { Timeline, Opacities } from \"@multitrack/core\";\nimport { MultitrackContext } from \"./context.js\";\n\nfunction useMultitrackContext() {\n  const ctx = useContext(MultitrackContext);\n  if (!ctx) {\n    throw new Error(\n      \"[@multitrack/react] useTimeline must be used within a <MultitrackProvider>\",\n    );\n  }\n  return ctx;\n}\n\n/**\n * Access the Timeline instance directly.\n */\nexport function useTimeline(): Timeline {\n  return useMultitrackContext().timeline;\n}\n\n/**\n * Get current opacities for all steps.\n */\nexport function useOpacities<T extends string = string>(): Opacities<T> {\n  return useMultitrackContext().opacities as Opacities<T>;\n}\n\n/**\n * Get opacity and active state for a single named step.\n */\nexport function useStep(name: string): { opacity: number; isActive: boolean } {\n  const { opacities } = useMultitrackContext();\n  const opacity = opacities[name] ?? 0;\n  return { opacity, isActive: opacity > 0 };\n}\n\n/**\n * Get raw scroll progress and current step position.\n */\nexport function useScrollProgress(): {\n  scrollPercentage: number;\n  currentStep: number;\n  totalSteps: number;\n} {\n  const { scrollPercentage, currentStep, totalSteps } =\n    useMultitrackContext();\n  return { scrollPercentage, currentStep, totalSteps };\n}\n","import type { ReactNode, CSSProperties } from \"react\";\nimport { useScrollProgress, useStep } from \"./hooks.js\";\n\n/**\n * Creates the tall scrollable container that drives the timeline.\n * Height = totalSteps * 100vh.\n *\n * Extracted from sinking-china MainMap.tsx line 193:\n * `<div style={{ height: `${totalSteps * 100}vh` }} className=\"relative\">`\n */\nexport function ScrollContainer({\n  children,\n  className,\n  style,\n}: {\n  children: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}) {\n  const { totalSteps } = useScrollProgress();\n\n  return (\n    <div\n      style={{ height: `${totalSteps * 100}vh`, position: \"relative\", ...style }}\n      className={className}\n    >\n      {children}\n    </div>\n  );\n}\n\n/**\n * Fixed viewport stage that stays in place while the user scrolls.\n * All animated content lives inside this.\n *\n * Extracted from sinking-china MainMap.tsx lines 200-207:\n * `<div style={{ position: \"fixed\", width: \"100%\", height: \"100vh\", touchAction: \"pan-y\" }}>`\n */\nexport function FixedStage({\n  children,\n  className,\n  style,\n}: {\n  children: ReactNode;\n  className?: string;\n  style?: CSSProperties;\n}) {\n  return (\n    <div\n      style={{\n        position: \"fixed\",\n        top: 0,\n        left: 0,\n        width: \"100%\",\n        height: \"100vh\",\n        touchAction: \"pan-y\",\n        ...style,\n      }}\n      className={className}\n    >\n      {children}\n    </div>\n  );\n}\n\n/**\n * Conditionally renders children based on a step's opacity.\n * Unmounts children when the step is inactive (opacity 0) for performance.\n *\n * Extracted from sinking-china ConditionalRender.tsx.\n */\nexport function Show({\n  when,\n  children,\n}: {\n  /** Step name to check. Children render when this step's opacity > 0. */\n  when: string;\n  children: ReactNode;\n}) {\n  const { isActive } = useStep(when);\n  if (!isActive) return null;\n  return <>{children}</>;\n}\n"]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@multitrack/react",
+  "version": "0.1.0",
+  "description": "React bindings for @multitrack/core",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@multitrack/core": "^0.1.0"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "Jack Hsu",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jakhsu/multitrack.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/jakhsu/multitrack/tree/main/packages/react",
+  "bugs": {
+    "url": "https://github.com/jakhsu/multitrack/issues"
+  },
+  "keywords": [
+    "scroll-animation",
+    "scroll-driven",
+    "timeline",
+    "react",
+    "react-hooks",
+    "scrollytelling",
+    "multi-track"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}