@multitrack/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Easing function: takes a progress value (0-1) and returns an eased value (0-1).
+ */
+type EasingFunction = (t: number) => number;
+/**
+ * Built-in easing preset names.
+ */
+type EasingPreset = "snap" | "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * User-provided step configuration. Declarative — consumers define animations
+ * as data, not imperative code.
+ *
+ * Inspired by video editing: each step occupies a duration on a named track.
+ */
+interface StepConfig {
+    /** Unique identifier for this step. Use "buffer" for spacers (auto-renamed). */
+    name: string;
+    /** How many viewport-heights this step lasts. */
+    duration: number;
+    /** Which timeline track this step belongs to. */
+    track: string;
+    /** Easing for opacity transitions. Defaults to "snap" (binary 0 or 1). */
+    easing?: EasingPreset | EasingFunction;
+    /** Optional predicate — if provided, step is only included when this returns true. */
+    condition?: () => boolean;
+    /** Named breakpoint this step belongs to. Only included when that breakpoint matches. */
+    when?: string;
+}
+/**
+ * A step with computed absolute positions on the timeline.
+ * Produced by `resolveSteps()` from user-provided `StepConfig[]`.
+ */
+interface Step {
+    name: string;
+    start: number;
+    end: number;
+    track: string;
+    easing: EasingPreset | EasingFunction;
+}
+/**
+ * Maps step names to their current opacity (0-1).
+ * Generic so TypeScript can infer step names from user config.
+ */
+type Opacities<T extends string = string> = Record<T, number>;
+interface StepEventPayload {
+    name: string;
+    track: string;
+    start: number;
+    end: number;
+}
+interface ScrollEventPayload {
+    scrollPercentage: number;
+    currentStep: number;
+}
+interface ReconfigureEventPayload {
+    steps: Step[];
+    totalSteps: number;
+}
+interface TimelineEventMap {
+    "step:enter": StepEventPayload;
+    "step:exit": StepEventPayload;
+    scroll: ScrollEventPayload;
+    "timeline:reconfigure": ReconfigureEventPayload;
+}
+type TimelineEventType = keyof TimelineEventMap;
+type TimelineEventHandler<T extends TimelineEventType> = (payload: TimelineEventMap[T]) => void;
+interface ScrollDriverOptions {
+    /** Element to listen for scroll events on. Defaults to `window`. */
+    target?: HTMLElement | Window;
+}
+interface TimelineOptions<T extends string = string> {
+    config: StepConfig[];
+    /** Enable devtools integration (exposes state on window.__MULTITRACK_DEVTOOLS__) */
+    devtools?: boolean;
+    /** Named breakpoints mapping to CSS media queries for responsive step inclusion. */
+    breakpoints?: Record<string, string>;
+}
+interface DevtoolsState {
+    steps: Step[];
+    currentStep: number;
+    totalSteps: number;
+    opacities: Opacities;
+    scrollPercentage: number;
+}
+
+/**
+ * Collects disposer functions (unsubscribes) so they can be
+ * cleaned up in a single `dispose()` call.
+ *
+ * Inspired by GSAP's gsap.context() — moves cleanup from a
+ * discipline problem to an API guarantee.
+ */
+declare class Scope {
+    private disposers;
+    /** Track a disposer function for later cleanup. */
+    add(disposer: () => void): void;
+    /** Call all tracked disposers and clear the list. Idempotent. */
+    dispose(): void;
+    /** Number of tracked disposers. */
+    get size(): number;
+}
+
+/**
+ * Event passed to middleware functions during step transitions.
+ */
+interface MiddlewareEvent {
+    type: "step:enter" | "step:exit";
+    payload: StepEventPayload;
+}
+/**
+ * Middleware function signature.
+ * Call `next()` to continue the chain; skip it to swallow the event.
+ */
+type MiddlewareFn = (event: MiddlewareEvent, next: () => void) => void;
+
+/**
+ * Timeline: the main facade that ties everything together.
+ *
+ * Usage:
+ * ```ts
+ * const timeline = new Timeline({
+ *   config: [
+ *     { name: "intro", duration: 3, track: "main", easing: "linear" },
+ *     { name: "content", duration: 5, track: "main" },
+ *     { name: "caption", duration: 2, track: "text" },
+ *   ],
+ * });
+ *
+ * timeline.start(); // begins listening to scroll
+ * timeline.on("scroll", ({ scrollPercentage }) => {
+ *   const opacities = timeline.getOpacities(scrollPercentage);
+ * });
+ * ```
+ */
+declare class Timeline {
+    private _steps;
+    private _totalSteps;
+    private config;
+    private scrollDriver;
+    private emitter;
+    private activeSteps;
+    private devtoolsEnabled;
+    private scrollUnsubscribe;
+    private _activeScope;
+    private middleware;
+    private breakpointManager;
+    private breakpointUnsub;
+    constructor(options: TimelineOptions);
+    /** Resolved steps (re-computed on breakpoint changes). */
+    get steps(): Step[];
+    /** Total steps across all tracks (re-computed on breakpoint changes). */
+    get totalSteps(): number;
+    /** Start listening to scroll events. */
+    start(): void;
+    /** Stop listening and clean up all resources. */
+    destroy(): void;
+    /**
+     * Register middleware that intercepts step:enter/step:exit events.
+     * Call `next()` to pass through, or skip it to swallow the event.
+     *
+     * ```ts
+     * timeline.use((event, next) => {
+     *   analytics.track(event.type, event.payload.name);
+     *   next();
+     * });
+     * ```
+     */
+    use(fn: MiddlewareFn): () => void;
+    /** Subscribe to timeline events. Returns an unsubscribe function. */
+    on<T extends TimelineEventType>(event: T, handler: TimelineEventHandler<T>): () => void;
+    /**
+     * Collect all subscriptions created inside `fn` into a Scope.
+     * Call `scope.dispose()` to clean them all up at once.
+     *
+     * ```ts
+     * const ctx = timeline.scope(() => {
+     *   timeline.on('step:enter', handleEnter);
+     *   timeline.on('scroll', handleScroll);
+     * });
+     * // later: ctx.dispose() cleans up both listeners
+     * ```
+     */
+    scope(fn: () => void): Scope;
+    /** Current scroll progress (0 to 1). */
+    get scrollPercentage(): number;
+    /** Current step position (0 to totalSteps). */
+    get currentStep(): number;
+    /** Calculate opacities for all steps at a given scroll position. */
+    getOpacities<T extends string = string>(scrollPercentage?: number): Opacities<T>;
+    /** Get the start/end range for a named step. */
+    getStepRange(name: string): {
+        start: number;
+        end: number;
+    };
+    /** Get all steps that are active at a given position. */
+    getCurrentSteps(position?: number): {
+        name: string;
+        track: string;
+        start: number;
+        end: number;
+    }[];
+    /** Enable devtools integration (exposes state on window.__MULTITRACK_DEVTOOLS__). */
+    enableDevtools(): void;
+    /**
+     * Filter config by active breakpoints and resolve steps.
+     * Steps without `when` are always included.
+     * Steps with `when` are included only if that breakpoint currently matches.
+     */
+    private resolveWithBreakpoints;
+    /**
+     * Re-resolve steps after a breakpoint change.
+     * Clears active steps and emits timeline:reconfigure.
+     */
+    private reconfigure;
+    private updateDevtools;
+}
+
+type ScrollCallback = (scrollPercentage: number) => void;
+/**
+ * Manages scroll event listening and converts scroll position to a 0-1 progress value.
+ *
+ * Extracted and generalized from sinking-china MainMap.tsx scroll handler.
+ * The original was tightly coupled to window.scrollY and React state — this
+ * version attaches to any scrollable element and uses a subscription API.
+ */
+declare class ScrollDriver {
+    private target;
+    private callbacks;
+    private bound;
+    private _scrollPercentage;
+    constructor(options?: ScrollDriverOptions);
+    /** Current scroll progress (0 to 1). */
+    get scrollPercentage(): number;
+    /**
+     * Subscribe to scroll updates. Returns an unsubscribe function.
+     */
+    onScroll(callback: ScrollCallback): () => void;
+    /**
+     * Start listening for scroll events.
+     */
+    start(): void;
+    /**
+     * Stop listening and clean up.
+     */
+    destroy(): void;
+    private calculateProgress;
+}
+
+/**
+ * Resolve declarative step configs into absolute timeline positions.
+ *
+ * Each track maintains its own independent cursor. Steps are placed
+ * sequentially within their track, producing parallel timelines that
+ * can overlap across tracks.
+ *
+ * Extracted and generalized from sinking-china App.tsx:transformStepConfig()
+ */
+declare function resolveSteps(config: StepConfig[]): Step[];
+/**
+ * Get the total number of steps (the maximum end position across all tracks).
+ */
+declare function getTotalSteps(steps: Step[]): number;
+
+/**
+ * Calculate the opacity for a single step at a given scroll position.
+ *
+ * The easing function controls how opacity transitions within the step range:
+ * - "snap": binary 0 or 1 (instant appear/disappear)
+ * - "linear": smooth 0→1 over the step duration
+ * - Custom easing function: any (t: number) => number mapping
+ *
+ * Extracted and generalized from sinking-china utils.ts:calculateScrollBasedOpacity()
+ */
+declare function calculateStepOpacity(step: Step, totalSteps: number, scrollPercentage: number): number;
+/**
+ * Calculate opacities for all steps at a given scroll position.
+ *
+ * Returns a record mapping step names to their current opacity (0-1).
+ *
+ * Extracted from sinking-china utils.ts:calculateAllOpacities()
+ */
+declare function calculateAllOpacities<T extends string = string>(scrollPercentage: number, steps: Step[]): Opacities<T>;
+/**
+ * Get the start/end range for a named step.
+ *
+ * Extracted from sinking-china utils.ts:getStepRange()
+ */
+declare function getStepRange(stepName: string, steps: Step[]): {
+    start: number;
+    end: number;
+};
+/**
+ * Get info about all steps that are active at a given position.
+ *
+ * Extracted from sinking-china utils.ts:getCurrentStepInfo()
+ */
+declare function getCurrentSteps(currentStep: number, steps: Step[]): Array<{
+    name: string;
+    track: string;
+    start: number;
+    end: number;
+}>;
+
+/**
+ * Binary snap: opacity is 1 when inside range, 0 outside.
+ * This was the default behavior in the original engine (isLinear: false).
+ */
+declare const snap: EasingFunction;
+/**
+ * Linear interpolation from 0 to 1 over the step duration.
+ * This was `isLinear: true` in the original engine.
+ */
+declare const linear: EasingFunction;
+/** Quadratic ease-in: slow start, fast end. */
+declare const easeIn: EasingFunction;
+/** Quadratic ease-out: fast start, slow end. */
+declare const easeOut: EasingFunction;
+/** Quadratic ease-in-out: slow start and end, fast middle. */
+declare const easeInOut: EasingFunction;
+/** Map of preset names to easing functions. */
+declare const easingPresets: Record<EasingPreset, EasingFunction>;
+/**
+ * Resolve an easing value (preset name or custom function) to an EasingFunction.
+ */
+declare function resolveEasing(easing: EasingPreset | EasingFunction | undefined): EasingFunction;
+
+declare class MultitrackError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+
+/** Clear emitted warnings. Exposed for testing. */
+declare function resetWarnings(): void;
+
+/**
+ * Minimal typed event emitter for timeline events.
+ */
+declare class Emitter {
+    private listeners;
+    on<T extends TimelineEventType>(event: T, handler: TimelineEventHandler<T>): () => void;
+    emit<T extends TimelineEventType>(event: T, payload: TimelineEventMap[T]): void;
+    removeAllListeners(): void;
+}
+
+export { type DevtoolsState, type EasingFunction, type EasingPreset, Emitter, type MiddlewareEvent, type MiddlewareFn, MultitrackError, type Opacities, type ReconfigureEventPayload, Scope, ScrollDriver, type ScrollDriverOptions, type ScrollEventPayload, type Step, type StepConfig, type StepEventPayload, Timeline, type TimelineEventHandler, type TimelineEventMap, type TimelineEventType, type TimelineOptions, calculateAllOpacities, calculateStepOpacity, easeIn, easeInOut, easeOut, easingPresets, getCurrentSteps, getStepRange, getTotalSteps, linear, resetWarnings, resolveEasing, resolveSteps, snap };