@multitrack/core 0.1.0

package/dist/index.js

@@ -0,0 +1,608 @@
+// src/errors.ts
+var MultitrackError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`[@multitrack] ${code}: ${message}`);
+    this.code = code;
+    this.name = "MultitrackError";
+  }
+};
+function stepNotFound(name) {
+  return new MultitrackError(
+    "STEP_NOT_FOUND",
+    `Step "${name}" not found in resolved steps. Check that the step name matches your config.`
+  );
+}
+function emptyConfig() {
+  return new MultitrackError(
+    "EMPTY_CONFIG",
+    "No step configurations provided. Pass at least one StepConfig to create a timeline."
+  );
+}
+function duplicateStepName(name) {
+  return new MultitrackError(
+    "DUPLICATE_STEP_NAME",
+    `Step name "${name}" is used more than once. Non-buffer step names must be unique.`
+  );
+}
+
+// src/warnings.ts
+var SNAP_LONG_THRESHOLD = 5;
+var emitted = /* @__PURE__ */ new Set();
+function warn(code, message) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
+  const key = `${code}:${message}`;
+  if (emitted.has(key)) return;
+  emitted.add(key);
+  console.warn(`[@multitrack] ${code}: ${message}`);
+}
+function resetWarnings() {
+  emitted.clear();
+}
+function validateStepConfigs(config) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
+  const trackCounts = /* @__PURE__ */ new Map();
+  for (const step of config) {
+    if (step.duration <= 0 && step.name !== "buffer") {
+      warn(
+        "ZERO_DURATION",
+        `Step "${step.name}" has duration ${step.duration}. This is probably unintentional.`
+      );
+    }
+    const easing = step.easing ?? "snap";
+    if (easing === "snap" && step.duration > SNAP_LONG_THRESHOLD && step.name !== "buffer") {
+      warn(
+        "SNAP_LONG_STEP",
+        `Step "${step.name}" uses snap easing with duration ${step.duration}. Snap on long steps looks jarring \u2014 consider "linear" or "easeInOut".`
+      );
+    }
+    if (step.name !== "buffer") {
+      trackCounts.set(step.track, (trackCounts.get(step.track) ?? 0) + 1);
+    }
+  }
+  if (trackCounts.size > 1) {
+    for (const [track, count] of trackCounts) {
+      if (count === 1) {
+        warn(
+          "LONE_TRACK",
+          `Track "${track}" has only one step. Is this a typo?`
+        );
+      }
+    }
+  }
+}
+function validateBreakpointRefs(config, breakpointNames) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
+  const known = new Set(breakpointNames);
+  for (const step of config) {
+    if (step.when && !known.has(step.when)) {
+      warn(
+        "UNKNOWN_BREAKPOINT",
+        `Step "${step.name}" references breakpoint "${step.when}" which is not defined. Known breakpoints: ${breakpointNames.join(", ") || "(none)"}`
+      );
+    }
+  }
+}
+
+// src/resolve-steps.ts
+function resolveSteps(config) {
+  if (config.length === 0) {
+    throw emptyConfig();
+  }
+  validateStepConfigs(config);
+  const filtered = config.filter((step) => {
+    if (step.condition) return step.condition();
+    return true;
+  });
+  const trackCursors = {};
+  let bufferIndex = 0;
+  const seen = /* @__PURE__ */ new Set();
+  const steps = filtered.map((stepConfig) => {
+    const name = stepConfig.name === "buffer" ? `buffer_${++bufferIndex}` : stepConfig.name;
+    if (stepConfig.name !== "buffer") {
+      if (seen.has(name)) {
+        throw duplicateStepName(name);
+      }
+      seen.add(name);
+    }
+    const track = stepConfig.track;
+    const start = trackCursors[track] ?? 0;
+    const end = start + stepConfig.duration;
+    trackCursors[track] = end;
+    return {
+      name,
+      start,
+      end,
+      track,
+      easing: stepConfig.easing ?? "snap"
+    };
+  });
+  return steps;
+}
+function getTotalSteps(steps) {
+  return Math.max(...steps.map((s) => s.end));
+}
+
+// src/easings.ts
+var snap = () => 1;
+var linear = (t) => t;
+var easeIn = (t) => t * t;
+var easeOut = (t) => t * (2 - t);
+var easeInOut = (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+var easingPresets = {
+  snap,
+  linear,
+  easeIn,
+  easeOut,
+  easeInOut
+};
+function resolveEasing(easing) {
+  if (easing === void 0) return snap;
+  if (typeof easing === "function") return easing;
+  return easingPresets[easing];
+}
+
+// src/opacity.ts
+function calculateStepOpacity(step, totalSteps, scrollPercentage) {
+  const normalizedScroll = scrollPercentage * totalSteps;
+  if (normalizedScroll < step.start || normalizedScroll > step.end) {
+    return 0;
+  }
+  const isLastStep = step.end === totalSteps;
+  if (isLastStep && normalizedScroll >= step.start) {
+    const easing2 = resolveEasing(step.easing);
+    if (step.easing === "snap" || step.easing === void 0) return 1;
+    const duration2 = step.end - step.start;
+    if (duration2 === 0) return 1;
+    const progress2 = Math.min((normalizedScroll - step.start) / duration2, 1);
+    return easing2(progress2);
+  }
+  const easing = resolveEasing(step.easing);
+  if (step.easing === "snap" || step.easing === void 0) {
+    return 1;
+  }
+  const duration = step.end - step.start;
+  if (duration === 0) return 1;
+  const progress = (normalizedScroll - step.start) / duration;
+  return easing(Math.max(0, Math.min(1, progress)));
+}
+function calculateAllOpacities(scrollPercentage, steps) {
+  const totalSteps = Math.max(...steps.map((s) => s.end));
+  return steps.reduce(
+    (acc, step) => {
+      acc[step.name] = calculateStepOpacity(
+        step,
+        totalSteps,
+        scrollPercentage
+      );
+      return acc;
+    },
+    {}
+  );
+}
+function getStepRange(stepName, steps) {
+  const step = steps.find((s) => s.name === stepName);
+  if (!step) {
+    throw stepNotFound(stepName);
+  }
+  return { start: step.start, end: step.end };
+}
+function getCurrentSteps(currentStep, steps) {
+  const active = steps.filter(
+    (s) => currentStep >= s.start && currentStep < s.end
+  );
+  if (active.length > 0) {
+    return active.map((s) => ({
+      name: s.name,
+      track: s.track,
+      start: s.start,
+      end: s.end
+    }));
+  }
+  return [];
+}
+
+// src/scroll-driver.ts
+var ScrollDriver = class {
+  target;
+  callbacks = /* @__PURE__ */ new Set();
+  bound = null;
+  _scrollPercentage = 0;
+  constructor(options = {}) {
+    this.target = options.target ?? window;
+  }
+  /** Current scroll progress (0 to 1). */
+  get scrollPercentage() {
+    return this._scrollPercentage;
+  }
+  /**
+   * Subscribe to scroll updates. Returns an unsubscribe function.
+   */
+  onScroll(callback) {
+    this.callbacks.add(callback);
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+  /**
+   * Start listening for scroll events.
+   */
+  start() {
+    if (this.bound) return;
+    this.bound = () => {
+      this._scrollPercentage = this.calculateProgress();
+      this.callbacks.forEach((cb) => cb(this._scrollPercentage));
+    };
+    this.target.addEventListener("scroll", this.bound, { passive: true });
+    this.bound();
+  }
+  /**
+   * Stop listening and clean up.
+   */
+  destroy() {
+    if (this.bound) {
+      this.target.removeEventListener("scroll", this.bound);
+      this.bound = null;
+    }
+    this.callbacks.clear();
+  }
+  calculateProgress() {
+    if (this.target === window || this.target instanceof Window) {
+      const maxScroll2 = document.documentElement.scrollHeight - window.innerHeight;
+      if (maxScroll2 <= 0) return 0;
+      return Math.max(0, Math.min(1, window.scrollY / maxScroll2));
+    }
+    const el = this.target;
+    const maxScroll = el.scrollHeight - el.clientHeight;
+    if (maxScroll <= 0) return 0;
+    return Math.max(0, Math.min(1, el.scrollTop / maxScroll));
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, handler) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler);
+    return () => {
+      this.listeners.get(event)?.delete(handler);
+    };
+  }
+  emit(event, payload) {
+    this.listeners.get(event)?.forEach((handler) => handler(payload));
+  }
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+};
+
+// src/scope.ts
+var Scope = class {
+  disposers = [];
+  /** Track a disposer function for later cleanup. */
+  add(disposer) {
+    this.disposers.push(disposer);
+  }
+  /** Call all tracked disposers and clear the list. Idempotent. */
+  dispose() {
+    for (let i = this.disposers.length - 1; i >= 0; i--) {
+      this.disposers[i]();
+    }
+    this.disposers.length = 0;
+  }
+  /** Number of tracked disposers. */
+  get size() {
+    return this.disposers.length;
+  }
+};
+
+// src/middleware.ts
+var MiddlewareChain = class {
+  fns = [];
+  /** Add middleware. Returns a function to remove it. */
+  add(fn) {
+    this.fns.push(fn);
+    return () => {
+      const idx = this.fns.indexOf(fn);
+      if (idx !== -1) this.fns.splice(idx, 1);
+    };
+  }
+  /**
+   * Run the middleware chain. If all middleware call `next()`,
+   * `finalAction` executes (emitting the event to listeners).
+   * If any middleware skips `next()`, the event is swallowed.
+   */
+  run(event, finalAction) {
+    let index = 0;
+    const fns = this.fns;
+    const next = () => {
+      if (index < fns.length) {
+        fns[index++](event, next);
+      } else {
+        finalAction();
+      }
+    };
+    next();
+  }
+  /** Remove all middleware. */
+  clear() {
+    this.fns.length = 0;
+  }
+};
+
+// src/breakpoints.ts
+var BreakpointManager = class {
+  queries = /* @__PURE__ */ new Map();
+  listeners = [];
+  constructor(breakpoints) {
+    if (typeof globalThis.matchMedia !== "function") return;
+    for (const [name, query] of Object.entries(breakpoints)) {
+      this.queries.set(name, globalThis.matchMedia(query));
+    }
+  }
+  /** Whether a named breakpoint currently matches. */
+  isActive(name) {
+    return this.queries.get(name)?.matches ?? false;
+  }
+  /** All registered breakpoint names. */
+  get names() {
+    return [...this.queries.keys()];
+  }
+  /**
+   * Subscribe to breakpoint changes. Returns unsubscribe function.
+   * The callback fires whenever any breakpoint's match state changes.
+   */
+  onChange(callback) {
+    const handler = () => callback();
+    this.listeners.push(handler);
+    for (const mql of this.queries.values()) {
+      mql.addEventListener("change", handler);
+    }
+    return () => {
+      for (const mql of this.queries.values()) {
+        mql.removeEventListener("change", handler);
+      }
+      const idx = this.listeners.indexOf(handler);
+      if (idx !== -1) this.listeners.splice(idx, 1);
+    };
+  }
+  /** Remove all change listeners. */
+  destroy() {
+    for (const handler of this.listeners) {
+      for (const mql of this.queries.values()) {
+        mql.removeEventListener("change", handler);
+      }
+    }
+    this.listeners.length = 0;
+  }
+};
+
+// src/timeline.ts
+var Timeline = class {
+  _steps;
+  _totalSteps;
+  config;
+  scrollDriver;
+  emitter = new Emitter();
+  activeSteps = /* @__PURE__ */ new Set();
+  devtoolsEnabled;
+  scrollUnsubscribe = null;
+  _activeScope = null;
+  middleware = new MiddlewareChain();
+  breakpointManager = null;
+  breakpointUnsub = null;
+  constructor(options) {
+    this.config = options.config;
+    this.devtoolsEnabled = options.devtools ?? false;
+    if (options.breakpoints && Object.keys(options.breakpoints).length > 0) {
+      this.breakpointManager = new BreakpointManager(options.breakpoints);
+      validateBreakpointRefs(options.config, this.breakpointManager.names);
+    }
+    this._steps = this.resolveWithBreakpoints();
+    this._totalSteps = getTotalSteps(this._steps);
+    this.scrollDriver = new ScrollDriver();
+  }
+  /** Resolved steps (re-computed on breakpoint changes). */
+  get steps() {
+    return this._steps;
+  }
+  /** Total steps across all tracks (re-computed on breakpoint changes). */
+  get totalSteps() {
+    return this._totalSteps;
+  }
+  /** Start listening to scroll events. */
+  start() {
+    this.scrollUnsubscribe?.();
+    if (this.breakpointManager) {
+      this.breakpointUnsub?.();
+      this.breakpointUnsub = this.breakpointManager.onChange(() => {
+        this.reconfigure();
+      });
+    }
+    this.scrollUnsubscribe = this.scrollDriver.onScroll((scrollPercentage) => {
+      const currentStep = scrollPercentage * this._totalSteps;
+      this.emitter.emit("scroll", { scrollPercentage, currentStep });
+      const nowActive = /* @__PURE__ */ new Set();
+      for (const step of this._steps) {
+        if (currentStep >= step.start && currentStep < step.end) {
+          nowActive.add(step.name);
+          if (!this.activeSteps.has(step.name)) {
+            const payload = {
+              name: step.name,
+              track: step.track,
+              start: step.start,
+              end: step.end
+            };
+            this.middleware.run(
+              { type: "step:enter", payload },
+              () => this.emitter.emit("step:enter", payload)
+            );
+          }
+        }
+      }
+      for (const name of this.activeSteps) {
+        if (!nowActive.has(name)) {
+          const step = this._steps.find((s) => s.name === name);
+          if (step) {
+            const payload = {
+              name: step.name,
+              track: step.track,
+              start: step.start,
+              end: step.end
+            };
+            this.middleware.run(
+              { type: "step:exit", payload },
+              () => this.emitter.emit("step:exit", payload)
+            );
+          }
+        }
+      }
+      this.activeSteps = nowActive;
+      if (this.devtoolsEnabled && typeof window !== "undefined") {
+        this.updateDevtools(scrollPercentage, currentStep);
+      }
+    });
+    if (this.devtoolsEnabled && typeof window !== "undefined") {
+      this.updateDevtools(0, 0);
+    }
+    this.scrollDriver.start();
+  }
+  /** Stop listening and clean up all resources. */
+  destroy() {
+    this.scrollUnsubscribe?.();
+    this.scrollUnsubscribe = null;
+    this.breakpointUnsub?.();
+    this.breakpointUnsub = null;
+    this.breakpointManager?.destroy();
+    this.scrollDriver.destroy();
+    this.emitter.removeAllListeners();
+    this.middleware.clear();
+    this.activeSteps.clear();
+    if (this.devtoolsEnabled && typeof window !== "undefined" && window.__MULTITRACK_DEVTOOLS__) {
+      delete window.__MULTITRACK_DEVTOOLS__;
+    }
+  }
+  /**
+   * 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) {
+    const unsub = this.middleware.add(fn);
+    this._activeScope?.add(unsub);
+    return unsub;
+  }
+  /** Subscribe to timeline events. Returns an unsubscribe function. */
+  on(event, handler) {
+    const unsub = this.emitter.on(event, handler);
+    this._activeScope?.add(unsub);
+    return unsub;
+  }
+  /**
+   * 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) {
+    const scope = new Scope();
+    const previousScope = this._activeScope;
+    this._activeScope = scope;
+    try {
+      fn();
+    } finally {
+      this._activeScope = previousScope;
+    }
+    return scope;
+  }
+  /** Current scroll progress (0 to 1). */
+  get scrollPercentage() {
+    return this.scrollDriver.scrollPercentage;
+  }
+  /** Current step position (0 to totalSteps). */
+  get currentStep() {
+    return this.scrollDriver.scrollPercentage * this._totalSteps;
+  }
+  /** Calculate opacities for all steps at a given scroll position. */
+  getOpacities(scrollPercentage) {
+    return calculateAllOpacities(
+      scrollPercentage ?? this.scrollDriver.scrollPercentage,
+      this._steps
+    );
+  }
+  /** Get the start/end range for a named step. */
+  getStepRange(name) {
+    return getStepRange(name, this._steps);
+  }
+  /** Get all steps that are active at a given position. */
+  getCurrentSteps(position) {
+    return getCurrentSteps(position ?? this.currentStep, this._steps);
+  }
+  /** Enable devtools integration (exposes state on window.__MULTITRACK_DEVTOOLS__). */
+  enableDevtools() {
+    this.devtoolsEnabled = true;
+  }
+  /**
+   * 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.
+   */
+  resolveWithBreakpoints() {
+    const filtered = this.breakpointManager ? this.config.filter(
+      (step) => !step.when || this.breakpointManager.isActive(step.when)
+    ) : this.config;
+    return resolveSteps(filtered);
+  }
+  /**
+   * Re-resolve steps after a breakpoint change.
+   * Clears active steps and emits timeline:reconfigure.
+   */
+  reconfigure() {
+    this._steps = this.resolveWithBreakpoints();
+    this._totalSteps = getTotalSteps(this._steps);
+    this.activeSteps.clear();
+    this.emitter.emit("timeline:reconfigure", {
+      steps: this._steps,
+      totalSteps: this._totalSteps
+    });
+    if (this.devtoolsEnabled && typeof window !== "undefined") {
+      this.updateDevtools(this.scrollPercentage, this.currentStep);
+    }
+  }
+  updateDevtools(scrollPercentage, currentStep) {
+    const serializableSteps = this._steps.map((s) => ({
+      name: s.name,
+      start: s.start,
+      end: s.end,
+      track: s.track,
+      easing: typeof s.easing === "function" ? "custom" : s.easing
+    }));
+    const state = {
+      steps: serializableSteps,
+      currentStep,
+      totalSteps: this._totalSteps,
+      opacities: this.getOpacities(scrollPercentage),
+      scrollPercentage
+    };
+    window.__MULTITRACK_DEVTOOLS__ = state;
+  }
+};
+
+export { Emitter, MultitrackError, Scope, ScrollDriver, Timeline, calculateAllOpacities, calculateStepOpacity, easeIn, easeInOut, easeOut, easingPresets, getCurrentSteps, getStepRange, getTotalSteps, linear, resetWarnings, resolveEasing, resolveSteps, snap };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map