@scenar/core 0.0.1

package/scenario/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Core scenario data types.
+ *
+ * These types define the contract between scenario authors and the
+ * playback engine. They are framework-agnostic — no React, no DOM.
+ */
+import type { StepAction } from "./step-action.js";
+/**
+ * A single step in a scenario timeline.
+ *
+ * @typeParam T - The data shape passed to the render function at this step.
+ */
+export interface ScenarioStep<T> {
+    /** Milliseconds to wait before revealing this step. */
+    readonly delayMs: number;
+    /** Data snapshot at this point in the timeline. */
+    readonly data: T;
+    /** Short label shown below the demo content describing the current action. */
+    readonly caption?: string;
+    /**
+     * Narration script for TTS generation. Consumed by the build script
+     * to produce audio files — not rendered at runtime.
+     */
+    readonly narration?: string;
+    /**
+     * Timed interactions to execute while this step is active. Each
+     * interaction fires at a specific point during the step's duration
+     * (controlled by {@link StepAction.atPercent}).
+     *
+     * Interactions are executed in order. When multiple interactions
+     * share the same atPercent, they fire in array order.
+     */
+    readonly interactions?: readonly StepAction[];
+}
+//# sourceMappingURL=types.d.ts.map

package/scenario/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC/C"}

package/scenario/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core scenario data types.
+ *
+ * These types define the contract between scenario authors and the
+ * playback engine. They are framework-agnostic — no React, no DOM.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/scenario/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/src/cursor/compute-position.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { computeCursorPosition } from "./compute-position.js";
+
+function mockContainer(rect: DOMRect, offsetWidth: number): HTMLElement {
+  return {
+    getBoundingClientRect: () => rect,
+    offsetWidth,
+  } as unknown as HTMLElement;
+}
+
+function mockElement(rect: DOMRect): Element {
+  return {
+    getBoundingClientRect: () => rect,
+  } as unknown as Element;
+}
+
+describe("computeCursorPosition", () => {
+  it("computes center position relative to container without zoom", () => {
+    const container = mockContainer(new DOMRect(100, 50, 800, 600), 800);
+    const el = mockElement(new DOMRect(300, 200, 40, 20));
+
+    const pos = computeCursorPosition(container, el);
+    expect(pos.x).toBe(300 - 100 + 20); // (left - containerLeft + width/2) / zoom
+    expect(pos.y).toBe(200 - 50 + 10);
+  });
+
+  it("accounts for CSS zoom", () => {
+    // Container renders at 2x CSS zoom: 400px offsetWidth but 800px client width
+    const container = mockContainer(new DOMRect(0, 0, 800, 600), 400);
+    const el = mockElement(new DOMRect(200, 100, 40, 20));
+
+    const pos = computeCursorPosition(container, el);
+    const zoom = 800 / 400; // 2x
+    expect(pos.x).toBe((200 + 20) / zoom);
+    expect(pos.y).toBe((100 + 10) / zoom);
+  });
+
+  it("returns origin when element is at container top-left with zero size", () => {
+    const container = mockContainer(new DOMRect(0, 0, 800, 600), 800);
+    const el = mockElement(new DOMRect(0, 0, 0, 0));
+
+    const pos = computeCursorPosition(container, el);
+    expect(pos.x).toBe(0);
+    expect(pos.y).toBe(0);
+  });
+});

package/src/cursor/compute-position.ts

@@ -0,0 +1,23 @@
+/** A 2D point in CSS coordinate space. */
+export interface Position {
+  x: number;
+  y: number;
+}
+
+/**
+ * Compute cursor position relative to the container, accounting for
+ * CSS zoom on ancestors. `getBoundingClientRect` returns viewport
+ * coordinates (post-zoom), but `position: absolute` inside a
+ * CSS-zoomed container uses pre-zoom coordinates. Dividing by the
+ * effective zoom converts viewport offsets back to CSS space.
+ */
+export function computeCursorPosition(container: HTMLElement, el: Element): Position {
+  const cRect = container.getBoundingClientRect();
+  const eRect = el.getBoundingClientRect();
+  const zoom = cRect.width / container.offsetWidth || 1;
+
+  return {
+    x: (eRect.left - cRect.left + eRect.width / 2) / zoom,
+    y: (eRect.top - cRect.top + eRect.height / 2) / zoom,
+  };
+}

package/src/dom/scroll.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { findScrollParent } from "./scroll.js";
+
+describe("findScrollParent", () => {
+  it("returns null when no scrollable ancestor exists", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    expect(findScrollParent(el)).toBe(null);
+    el.remove();
+  });
+
+  it("finds the nearest scrollable ancestor", () => {
+    const scrollable = document.createElement("div");
+    scrollable.style.overflowY = "auto";
+    const child = document.createElement("div");
+    scrollable.appendChild(child);
+    document.body.appendChild(scrollable);
+
+    expect(findScrollParent(child)).toBe(scrollable);
+    scrollable.remove();
+  });
+
+  it("skips non-scrollable intermediaries", () => {
+    const scrollable = document.createElement("div");
+    scrollable.style.overflowY = "scroll";
+    const middle = document.createElement("div");
+    const child = document.createElement("div");
+    scrollable.appendChild(middle);
+    middle.appendChild(child);
+    document.body.appendChild(scrollable);
+
+    expect(findScrollParent(child)).toBe(scrollable);
+    scrollable.remove();
+  });
+});

package/src/dom/scroll.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared scroll helpers used by both the Cursor component and
+ * the step-interactions hook.
+ */
+
+/**
+ * Walk up the DOM tree to find the nearest scrollable ancestor
+ * of the given element (one with `overflow-y: auto` or `scroll`).
+ */
+export function findScrollParent(el: Element): Element | null {
+  let parent = el.parentElement;
+  while (parent) {
+    const { overflowY } = getComputedStyle(parent);
+    if (overflowY === "auto" || overflowY === "scroll") return parent;
+    parent = parent.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Scroll the target element into view inside its nearest scrollable
+ * ancestor using the browser's native `scrollIntoView`. This handles
+ * CSS `zoom` correctly (manual `scrollTop` arithmetic does not).
+ *
+ * After scrolling the internal container, page scroll is immediately
+ * restored so the demo block doesn't jump on the page.
+ *
+ * @returns `true` when scrolling was necessary.
+ */
+export function scrollTargetIntoView(el: Element): boolean {
+  const scrollParent = findScrollParent(el);
+  if (!scrollParent) return false;
+
+  const pRect = scrollParent.getBoundingClientRect();
+  const eRect = el.getBoundingClientRect();
+  const isVisible = eRect.top >= pRect.top && eRect.bottom <= pRect.bottom;
+  if (isVisible) return false;
+
+  const pageX = window.scrollX;
+  const pageY = window.scrollY;
+  el.scrollIntoView({ block: "center", behavior: "smooth" });
+  window.scrollTo(pageX, pageY);
+  return true;
+}
+
+/**
+ * Instant-scroll variant for video export where smooth scrolling
+ * doesn't work across Remotion frames. Sets `scrollTop` directly
+ * on the nearest scrollable ancestor.
+ */
+export function scrollTargetIntoViewInstant(el: Element): void {
+  const scrollParent = findScrollParent(el);
+  if (!scrollParent) return;
+
+  const pRect = scrollParent.getBoundingClientRect();
+  const eRect = el.getBoundingClientRect();
+  const isVisible = eRect.top >= pRect.top && eRect.bottom <= pRect.bottom;
+  if (isVisible) return;
+
+  const pageX = window.scrollX;
+  const pageY = window.scrollY;
+  el.scrollIntoView({ block: "center", behavior: "instant" });
+  window.scrollTo(pageX, pageY);
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// @scenar/core — public API
+// Pure TypeScript types, timing, and utilities for scenario playback.
+
+// Scenario types
+export type { ScenarioStep } from "./scenario/types.js";
+export type {
+  ActionType,
+  StepAction,
+  UseStepInteractionsOptions,
+} from "./scenario/step-action.js";
+
+// Narration types
+export type { NarrationEntry, NarrationManifest } from "./narration/types.js";
+
+// Viewport types
+export type { ViewportTransform } from "./viewport/transform.js";
+export { VIEWPORT_TRANSFORM_IDENTITY } from "./viewport/transform.js";
+
+// Cursor types
+export type { Position } from "./cursor/compute-position.js";
+export { computeCursorPosition } from "./cursor/compute-position.js";
+
+// Timeline
+export type { StepTimeline } from "./timeline/compute-step-timeline.js";
+export { computeStepTimeline } from "./timeline/compute-step-timeline.js";
+export { deriveStepFromTime } from "./timeline/derive-step.js";
+export { getStepDurationMs } from "./timeline/step-duration.js";
+
+// Timing constants
+export {
+  CLICK_DELAY_MS,
+  TYPE_CHAR_DELAY_MS,
+  HOVER_HOLD_MS,
+  DRAG_SETTLE_MS,
+  VIEWPORT_SETTLE_MS,
+} from "./timing/constants.js";
+
+// DOM scroll utilities
+export {
+  findScrollParent,
+  scrollTargetIntoView,
+  scrollTargetIntoViewInstant,
+} from "./dom/scroll.js";
+
+// Data-attribute targeting contract
+export {
+  CURSOR_TARGET_ATTRIBUTE,
+  SCROLL_TARGET_ATTRIBUTE,
+  HOVER_STATE_ATTRIBUTE,
+  DRAG_STATE_ATTRIBUTE,
+  cursorTargetSelector,
+  scrollTargetSelector,
+} from "./targeting/data-attributes.js";

package/src/narration/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime narration audio data produced by a TTS build script.
+ *
+ * ScenarioPlayer consumes a {@link NarrationManifest} to play audio
+ * clips synced to step progression. Step authors write narration text
+ * on scenario steps — the build script reads that text, generates
+ * audio files, and writes a manifest that maps step indices to audio
+ * URLs and durations.
+ */
+
+/** A single audio clip for one scenario step. */
+export interface NarrationEntry {
+  /** URL of the audio file (e.g. "/demos/approval-flow/step-0.mp3"). */
+  src: string;
+  /** Duration of the audio clip in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Per-scenario manifest mapping step indices to narration audio.
+ *
+ * Array position corresponds to the step index. Steps without
+ * narration use `null`.
+ */
+export interface NarrationManifest {
+  steps: (NarrationEntry | null)[];
+}

package/src/scenario/step-action.ts

@@ -0,0 +1,113 @@
+import type { NarrationManifest } from "../narration/types.js";
+import type { ViewportTransform } from "../viewport/transform.js";
+import type { ScenarioStep } from "./types.js";
+
+/**
+ * The set of interaction types the engine understands.
+ *
+ * Values match the proto `ActionType` enum names (`ai.scenar.scenario.v1`)
+ * so that proto ↔ engine mapping is a direct string copy.
+ */
+export type ActionType =
+  | "scroll_to"
+  | "set_cursor"
+  | "clear_cursor"
+  | "click"
+  | "type"
+  | "hover"
+  | "drag"
+  | "viewport_transition";
+
+/** A single timed interaction within a step. */
+export interface StepAction {
+  /**
+   * When to fire, as a fraction of the step's narration duration
+   * (0.0 = step start, 1.0 = narration end). The hook reads the
+   * narration manifest to compute the real millisecond time.
+   *
+   * When no narration is available (muted / no manifest), the next
+   * step's `delayMs` is used as the fallback step duration.
+   */
+  readonly atPercent: number;
+  /** Action type. */
+  readonly type: ActionType;
+  /**
+   * Target element identifier.
+   * - For `scroll_to`: matches `[data-scroll-target="<target>"]`
+   * - For `set_cursor` / `click` / `type` / `hover`: matches `[data-cursor-target="<target>"]`
+   * - For `drag`: matches `[data-cursor-target="<target>"]` (drag source)
+   */
+  readonly target?: string;
+  /**
+   * Drag destination element identifier. Only used by `drag` actions.
+   * Matches `[data-cursor-target="<dragTarget>"]`.
+   */
+  readonly dragTarget?: string;
+  /** Text to type character-by-character. Only used by `type` actions. */
+  readonly text?: string;
+  /**
+   * Milliseconds between characters for `type` actions.
+   * Defaults to {@link TYPE_CHAR_DELAY_MS} (50 ms).
+   */
+  readonly typeDelay?: number;
+  /**
+   * Milliseconds to hold the cursor over the target during a `hover`
+   * action, between enter-event dispatch and leave-event dispatch.
+   * Defaults to {@link HOVER_HOLD_MS} (1500 ms).
+   */
+  readonly hoverDuration?: number;
+  /**
+   * Zoom scale factor for `viewport_transition` actions.
+   * Values > 1 zoom in, < 1 zoom out. Defaults to 1.5.
+   * Ignored when {@link viewportReset} is `true`.
+   */
+  readonly viewportZoom?: number;
+  /**
+   * When `true`, a `viewport_transition` action resets the viewport
+   * to the identity transform (scale 1, no translation). `target`
+   * and `viewportZoom` are ignored.
+   */
+  readonly viewportReset?: boolean;
+}
+
+/** Configuration for the useStepInteractions hook. */
+export interface UseStepInteractionsOptions<T> {
+  /** Current active step index from ScenarioPlayer. */
+  stepIndex: number;
+  /** Narration manifest for duration lookup. */
+  narrationManifest: NarrationManifest | undefined;
+  /** Container ref for DOM queries. */
+  containerRef: { current: HTMLElement | null };
+  /** Callback to change the cursor target mid-step. */
+  setCursorTarget: (target: string | undefined) => void;
+  /**
+   * The full steps array. Interactions are read from each step's
+   * `interactions` field. Step `delayMs` is used as fallback duration
+   * when narration is unavailable.
+   */
+  steps: readonly ScenarioStep<T>[];
+  /**
+   * Playback speed multiplier (default 1). Browser-path timeouts are
+   * divided by this value so interactions fire proportionally earlier
+   * at higher speeds.
+   */
+  playbackRate?: number;
+  /**
+   * Optional callback to control the Cursor's click ripple. The
+   * `hover` action calls `setShowRipple(false)` before moving the
+   * cursor and `setShowRipple(true)` after hover leave events fire.
+   */
+  setShowRipple?: (show: boolean) => void;
+  /**
+   * Optional callback to control the Cursor's drag visual. The
+   * `drag` action calls `setDragging(true)` after pressing at the
+   * source and `setDragging(false)` after releasing at the destination.
+   */
+  setDragging?: (dragging: boolean) => void;
+  /**
+   * Optional callback to apply a viewport transform (zoom/pan). The
+   * `viewport_transition` action computes scale and translate values
+   * needed to center the target element and calls this callback.
+   */
+  setViewportTransform?: (transform: ViewportTransform) => void;
+}

package/src/scenario/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Core scenario data types.
+ *
+ * These types define the contract between scenario authors and the
+ * playback engine. They are framework-agnostic — no React, no DOM.
+ */
+
+import type { StepAction } from "./step-action.js";
+
+/**
+ * A single step in a scenario timeline.
+ *
+ * @typeParam T - The data shape passed to the render function at this step.
+ */
+export interface ScenarioStep<T> {
+  /** Milliseconds to wait before revealing this step. */
+  readonly delayMs: number;
+  /** Data snapshot at this point in the timeline. */
+  readonly data: T;
+  /** Short label shown below the demo content describing the current action. */
+  readonly caption?: string;
+  /**
+   * Narration script for TTS generation. Consumed by the build script
+   * to produce audio files — not rendered at runtime.
+   */
+  readonly narration?: string;
+  /**
+   * Timed interactions to execute while this step is active. Each
+   * interaction fires at a specific point during the step's duration
+   * (controlled by {@link StepAction.atPercent}).
+   *
+   * Interactions are executed in order. When multiple interactions
+   * share the same atPercent, they fire in array order.
+   */
+  readonly interactions?: readonly StepAction[];
+}

package/src/targeting/data-attributes.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import {
+  CURSOR_TARGET_ATTRIBUTE,
+  SCROLL_TARGET_ATTRIBUTE,
+  cursorTargetSelector,
+  scrollTargetSelector,
+} from "./data-attributes.js";
+
+describe("data-attributes", () => {
+  it("exports correct attribute names", () => {
+    expect(CURSOR_TARGET_ATTRIBUTE).toBe("data-cursor-target");
+    expect(SCROLL_TARGET_ATTRIBUTE).toBe("data-scroll-target");
+  });
+
+  it("builds correct cursor target selectors", () => {
+    expect(cursorTargetSelector("submit-btn")).toBe('[data-cursor-target="submit-btn"]');
+  });
+
+  it("builds correct scroll target selectors", () => {
+    expect(scrollTargetSelector("results")).toBe('[data-scroll-target="results"]');
+  });
+});

package/src/targeting/data-attributes.ts

@@ -0,0 +1,30 @@
+/**
+ * Centralized data-attribute contract for the scenario engine.
+ *
+ * The engine identifies interactive elements in the DOM via these
+ * data attributes. This module is the single source of truth for
+ * attribute names and selector builders — consumers never hard-code
+ * attribute strings.
+ */
+
+/** Attribute name for cursor-targetable elements. */
+export const CURSOR_TARGET_ATTRIBUTE = "data-cursor-target";
+
+/** Attribute name for scroll-targetable elements. */
+export const SCROLL_TARGET_ATTRIBUTE = "data-scroll-target";
+
+/** Attribute set on elements during hover interactions. */
+export const HOVER_STATE_ATTRIBUTE = "data-hover";
+
+/** Attribute set on elements during drag interactions. */
+export const DRAG_STATE_ATTRIBUTE = "data-dragging";
+
+/** Build a CSS selector for a cursor target by its ID. */
+export function cursorTargetSelector(id: string): string {
+  return `[${CURSOR_TARGET_ATTRIBUTE}="${id}"]`;
+}
+
+/** Build a CSS selector for a scroll target by its ID. */
+export function scrollTargetSelector(id: string): string {
+  return `[${SCROLL_TARGET_ATTRIBUTE}="${id}"]`;
+}

package/src/timeline/compute-step-timeline.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { computeStepTimeline } from "./compute-step-timeline.js";
+
+describe("computeStepTimeline", () => {
+  it("returns zero duration for a single step with no narration", () => {
+    const tl = computeStepTimeline([{ delayMs: 0 }], null);
+    expect(tl.stepStartTimesMs).toEqual([0]);
+    expect(tl.totalDurationMs).toBe(3000);
+  });
+
+  it("uses delayMs when no narration manifest is provided", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 1000 }, { delayMs: 2000 }],
+      null,
+    );
+    expect(tl.stepStartTimesMs).toEqual([0, 1000, 3000]);
+    expect(tl.totalDurationMs).toBe(3000 + 3000);
+  });
+
+  it("uses narration duration when it exceeds delayMs", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 500 }, { delayMs: 500 }],
+      { steps: [{ src: "a.mp3", durationMs: 2000 }, { src: "b.mp3", durationMs: 1000 }, null] },
+    );
+    // Step 1 starts after max(500, 2000) = 2000
+    expect(tl.stepStartTimesMs[1]).toBe(2000);
+    // Step 2 starts after 2000 + max(500, 1000) = 3000
+    expect(tl.stepStartTimesMs[2]).toBe(3000);
+  });
+
+  it("uses delayMs when it exceeds narration duration", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 5000 }],
+      { steps: [{ src: "a.mp3", durationMs: 1000 }, null] },
+    );
+    expect(tl.stepStartTimesMs[1]).toBe(5000);
+  });
+
+  it("handles null entries in the manifest", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 1000 }],
+      { steps: [null, null] },
+    );
+    expect(tl.stepStartTimesMs).toEqual([0, 1000]);
+  });
+
+  it("uses last step narration for total duration when it exceeds dwell", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 1000 }],
+      { steps: [null, { src: "b.mp3", durationMs: 5000 }] },
+    );
+    expect(tl.totalDurationMs).toBe(1000 + 5000);
+  });
+
+  it("handles empty steps array", () => {
+    const tl = computeStepTimeline([], null);
+    expect(tl.stepStartTimesMs).toEqual([0]);
+    expect(tl.totalDurationMs).toBe(3000);
+  });
+});

package/src/timeline/compute-step-timeline.ts

@@ -0,0 +1,49 @@
+import type { NarrationManifest } from "../narration/types.js";
+
+/**
+ * Minimal step shape for timeline computation. Accepts any
+ * ScenarioStep<T> without caring about the data payload.
+ */
+interface StepTiming {
+  delayMs: number;
+}
+
+/** Dwell time on the final step so viewers can absorb the result. */
+const FINAL_DWELL_MS = 3_000;
+
+export interface StepTimeline {
+  /** Start time of each step in milliseconds (index 0 is always 0). */
+  stepStartTimesMs: number[];
+  /** Total playback duration in milliseconds. */
+  totalDurationMs: number;
+}
+
+/**
+ * Pre-compute step start times and total duration from step definitions
+ * and an optional narration manifest.
+ *
+ * Step N+1 starts after `max(steps[N+1].delayMs, manifest.steps[N].durationMs)` —
+ * whichever is longer, the base delay or the narration clip for the current step.
+ *
+ * Shared between browser ScenarioPlayer (progress bar) and Remotion
+ * video export (frame-based timeline).
+ */
+export function computeStepTimeline(
+  steps: readonly StepTiming[],
+  manifest: NarrationManifest | null | undefined,
+): StepTimeline {
+  const stepStartTimesMs: number[] = [0];
+
+  for (let i = 1; i < steps.length; i++) {
+    const prevStart = stepStartTimesMs[i - 1]!;
+    const baseDelay = steps[i]!.delayMs;
+    const narrationMs = manifest?.steps[i - 1]?.durationMs ?? 0;
+    stepStartTimesMs.push(prevStart + Math.max(baseDelay, narrationMs));
+  }
+
+  const lastStepStart = stepStartTimesMs[stepStartTimesMs.length - 1] ?? 0;
+  const lastNarrationMs = manifest?.steps[steps.length - 1]?.durationMs ?? 0;
+  const totalDurationMs = lastStepStart + Math.max(FINAL_DWELL_MS, lastNarrationMs);
+
+  return { stepStartTimesMs, totalDurationMs };
+}

package/src/timeline/derive-step.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { deriveStepFromTime } from "./derive-step.js";
+
+describe("deriveStepFromTime", () => {
+  const starts = [0, 1000, 3000, 6000];
+  const maxIndex = 3;
+
+  it("returns 0 for time before all steps", () => {
+    expect(deriveStepFromTime(-1, starts, maxIndex)).toBe(0);
+  });
+
+  it("returns 0 at time 0", () => {
+    expect(deriveStepFromTime(0, starts, maxIndex)).toBe(0);
+  });
+
+  it("returns the correct step for times within each range", () => {
+    expect(deriveStepFromTime(500, starts, maxIndex)).toBe(0);
+    expect(deriveStepFromTime(1000, starts, maxIndex)).toBe(1);
+    expect(deriveStepFromTime(2500, starts, maxIndex)).toBe(1);
+    expect(deriveStepFromTime(3000, starts, maxIndex)).toBe(2);
+    expect(deriveStepFromTime(6000, starts, maxIndex)).toBe(3);
+    expect(deriveStepFromTime(99999, starts, maxIndex)).toBe(3);
+  });
+
+  it("clamps result to maxIndex", () => {
+    expect(deriveStepFromTime(6000, starts, 1)).toBe(1);
+  });
+
+  it("returns 0 for empty start times", () => {
+    expect(deriveStepFromTime(5000, [], 0)).toBe(0);
+  });
+
+  it("handles single step", () => {
+    expect(deriveStepFromTime(0, [0], 0)).toBe(0);
+    expect(deriveStepFromTime(5000, [0], 0)).toBe(0);
+  });
+});

package/src/timeline/derive-step.ts

@@ -0,0 +1,15 @@
+/**
+ * Find the active step for a given playback time by scanning the
+ * pre-computed step start times in reverse. Returns `0` if the
+ * time precedes all steps.
+ */
+export function deriveStepFromTime(
+  currentTimeMs: number,
+  stepStartTimesMs: readonly number[],
+  maxIndex: number,
+): number {
+  for (let i = stepStartTimesMs.length - 1; i >= 0; i--) {
+    if (currentTimeMs >= stepStartTimesMs[i]!) return Math.min(i, maxIndex);
+  }
+  return 0;
+}