@grundyjs/algiviz 0.2.0 → 0.4.0

package/dist/canvas/index.js

@@ -1,14 +1,37 @@
+import { createSceneRenderer } from "../scene/index.js";
+/** Adapts array identities to the same public scene contract used by custom objects. */
+export function arrayScene(state) {
+    return Object.freeze({
+        objects: Object.freeze([...positions(state)].map(([id, data]) => Object.freeze({ id, type: "bar", data: Object.freeze(data) })))
+    });
+}
 const palettes = {
-    dark: { background: "#101827", text: "#f1f5f9", bar: "#94a3b8", sorted: "#34d399", active: "#fbbf24", held: "#c4b5fd" },
-    light: { background: "#f8fafc", text: "#0f172a", bar: "#475569", sorted: "#047857", active: "#b45309", held: "#7c3aed" }
+    dark: {
+        background: "#101827",
+        text: "#f1f5f9",
+        bar: "#94a3b8",
+        sorted: "#34d399",
+        active: "#fbbf24",
+        held: "#c4b5fd"
+    },
+    light: {
+        background: "#f8fafc",
+        text: "#0f172a",
+        bar: "#475569",
+        sorted: "#047857",
+        active: "#b45309",
+        held: "#7c3aed"
+    }
 };
+export { createSortRenderer as createArrayRenderer };
 function positions(state) {
     const result = new Map();
-    state.slots.forEach((item, index) => { if (item)
-        result.set(item.id, { item, index, held: false }); });
+    state.slots.forEach((item, index) => {
+        if (item)
+            result.set(item.id, { item, index, held: false });
+    });
     if (state.held)
-        result.set(state.held.id, { item: state.held,
-            index: state.slots.indexOf(null), held: true });
+        result.set(state.held.id, { item: state.held, index: state.slots.indexOf(null), held: true });
     return result;
 }
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
@@ -19,7 +42,6 @@ export function createSortRenderer(options) {
             const { width, height } = ctx.canvas;
             if (width <= 0 || height <= 0)
                 return;
-            const before = positions(frame.previous);
             const after = positions(frame.current);
             const items = [...after.values()];
             const count = frame.current.slots.length;
@@ -46,23 +68,42 @@ export function createSortRenderer(options) {
                 ctx.fillText(`AlgiViz · ${event.type} · ${frame.stepIndex}`, margin, height * 0.07);
                 if (!count)
                     ctx.fillText("Empty array", margin, baseline);
-                for (const [id, next] of after) {
-                    const old = before.get(id) ?? next;
-                    const x = margin + ((old.index + (next.index - old.index) * p) + 0.5) * cell;
-                    const size = Math.max(4, Math.abs(next.item.value) / maxMagnitude * available);
-                    const active = event.type === "compare" ? id === event.leftId || id === event.rightId :
-                        "itemId" in event && event.itemId === id;
-                    ctx.fillStyle = next.held ? colors.held : active ? colors.active :
-                        next.index < frame.current.sortedPrefixLength ? colors.sorted : colors.bar;
-                    ctx.fillRect(x - barWidth / 2, baseline - size, barWidth, size);
-                    if (cell < 24)
-                        continue;
-                    ctx.fillStyle = colors.text;
-                    ctx.font = `${fontSize}px sans-serif`;
-                    ctx.textAlign = "center";
-                    ctx.fillText(String(next.item.value), x, baseline - size - fontSize, cell * 0.95);
-                    ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
-                }
+                const sceneRenderer = createSceneRenderer({
+                    bar(ctx, transition) {
+                        const object = transition.current ?? transition.previous;
+                        const id = object.id;
+                        const next = object.data;
+                        const old = transition.previous?.data ?? next;
+                        const x = margin + (old.index + (next.index - old.index) * p + 0.5) * cell;
+                        const size = Math.max(4, (Math.abs(next.item.value) / maxMagnitude) * available);
+                        const active = event.type === "highlight"
+                            ? event.itemIds.includes(id)
+                            : event.type === "compare" || event.type === "swap"
+                                ? id === event.leftId || id === event.rightId
+                                : "itemId" in event && event.itemId === id;
+                        ctx.fillStyle = next.held
+                            ? colors.held
+                            : active
+                                ? colors.active
+                                : next.index < frame.current.sortedPrefixLength ||
+                                    next.index >= count - (frame.current.sortedSuffixLength ?? 0)
+                                    ? colors.sorted
+                                    : colors.bar;
+                        ctx.fillRect(x - barWidth / 2, baseline - size, barWidth, size);
+                        if (cell < 24)
+                            return;
+                        ctx.fillStyle = colors.text;
+                        ctx.font = `${fontSize}px sans-serif`;
+                        ctx.textAlign = "center";
+                        ctx.fillText(String(next.item.value), x, baseline - size - fontSize, cell * 0.95);
+                        ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
+                    }
+                });
+                sceneRenderer.render(ctx, {
+                    ...frame,
+                    previous: arrayScene(frame.previous),
+                    current: arrayScene(frame.current)
+                });
                 ctx.textAlign = "left";
                 ctx.font = `${Math.max(11, Math.min(18, width * 0.03))}px sans-serif`;
                 ctx.fillStyle = colors.text;

package/dist/compat/algorithms.d.ts

@@ -0,0 +1,2 @@
+export declare const insertion: import("../array/trace.js").ArrayAlgorithm;
+export declare const bubble: import("../array/trace.js").ArrayAlgorithm;

package/dist/compat/algorithms.js

@@ -0,0 +1,36 @@
+import { defineArrayAlgorithm } from "../array/trace.js";
+// Legacy core exports only. New consumers provide algorithms like examples/algorithms.mjs.
+export const insertion = defineArrayAlgorithm(function* (array) {
+    yield array.start({ sortedPrefixLength: Math.min(1, array.length) });
+    for (let i = 1; i < array.length; i++) {
+        const key = array.at(i);
+        yield array.select(i, { sortedPrefixLength: i });
+        let hole = i;
+        while (hole > 0) {
+            yield array.compare(hole - 1, 'held');
+            if (array.at(hole - 1).value <= key.value)
+                break;
+            yield array.shift(hole - 1, hole, { sortedPrefixLength: hole - 1 });
+            hole--;
+        }
+        yield array.insert(hole, { sortedPrefixLength: i + 1 });
+    }
+    yield array.done({ sortedPrefixLength: array.length });
+});
+export const bubble = defineArrayAlgorithm(function* (array) {
+    yield array.start({ sortedSuffixLength: array.length < 2 ? array.length : 0 });
+    for (let end = array.length - 1; end > 0; end--) {
+        let swapped = false;
+        for (let left = 0; left < end; left++) {
+            yield array.compare(left, left + 1);
+            if (array.at(left).value <= array.at(left + 1).value)
+                continue;
+            yield array.swap(left, left + 1);
+            swapped = true;
+        }
+        yield array.pass(end, { sortedSuffixLength: swapped ? array.length - end : array.length });
+        if (!swapped)
+            break;
+    }
+    yield array.done({ sortedSuffixLength: array.length });
+});

package/dist/core/bubble-sort.d.ts

@@ -0,0 +1,4 @@
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export declare const bubbleSortSteps: (values: readonly number[]) => readonly import("./types.js").SortStep[];
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export declare const iterateBubbleSortSteps: (values: readonly number[]) => Generator<import("./types.js").SortStep, void, unknown>;

package/dist/core/bubble-sort.js

@@ -0,0 +1,5 @@
+import { bubble } from "../compat/algorithms.js";
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export const bubbleSortSteps = bubble.steps;
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export const iterateBubbleSortSteps = bubble.iterate;

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
+export { bubbleSortSteps, iterateBubbleSortSteps } from "./bubble-sort.js";
 export type { Item, SortEvent, SortSnapshot, SortStep } from "./types.js";
 export { createSortTimeline } from "./timeline.js";
 export type { SortFrame, SortTimeline } from "./timeline.js";

package/dist/core/index.js

@@ -1,3 +1,4 @@
 export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
+export { bubbleSortSteps, iterateBubbleSortSteps } from "./bubble-sort.js";
 export { createSortTimeline } from "./timeline.js";
 export { createSortPlayer } from "./player.js";

package/dist/core/insertion-sort.d.ts

@@ -1,8 +1,4 @@
-import type { SortStep } from "./types.js";
-/** Creates a stable ascending insertion-sort trace without modifying the input. */
-export declare function insertionSortSteps(values: readonly number[]): readonly SortStep[];
-/**
- * Yields immutable snapshots without retaining history.
- * Input is copied and validated on the first next(), not when creating the iterator.
- */
-export declare function iterateInsertionSortSteps(values: readonly number[]): Generator<SortStep, void, unknown>;
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export declare const insertionSortSteps: (values: readonly number[]) => readonly import("./types.js").SortStep[];
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export declare const iterateInsertionSortSteps: (values: readonly number[]) => Generator<import("./types.js").SortStep, void, unknown>;

package/dist/core/insertion-sort.js

@@ -1,65 +1,5 @@
-/** Creates a stable ascending insertion-sort trace without modifying the input. */
-export function insertionSortSteps(values) {
-    return Object.freeze([...iterateInsertionSortSteps(values)]);
-}
-/**
- * Yields immutable snapshots without retaining history.
- * Input is copied and validated on the first next(), not when creating the iterator.
- */
-export function* iterateInsertionSortSteps(values) {
-    // Array.from also exposes sparse holes as undefined for validation.
-    const input = Array.from(values);
-    for (let i = 0; i < input.length; i++) {
-        if (typeof input[i] !== "number" || !Number.isFinite(input[i])) {
-            throw new TypeError(`Expected a finite number at index ${i}`);
-        }
-    }
-    const slots = input.map((value, index) => Object.freeze({ id: `item-${index}`, value }));
-    let index = 0;
-    let held = null;
-    let sortedPrefixLength = Math.min(1, slots.length);
-    let comparisons = 0;
-    let writes = 0;
-    const emit = (event) => {
-        return Object.freeze({
-            index: index++,
-            event: Object.freeze(event),
-            state: Object.freeze({
-                slots: Object.freeze(slots.slice()),
-                held,
-                sortedPrefixLength,
-                comparisons,
-                writes
-            })
-        });
-    };
-    yield emit({ type: "start" });
-    for (let i = 1; i < slots.length; i++) {
-        const key = slots[i];
-        held = key;
-        slots[i] = null;
-        sortedPrefixLength = i;
-        yield emit({ type: "select", itemId: key.id, from: i });
-        let hole = i;
-        while (hole > 0) {
-            const left = slots[hole - 1];
-            comparisons++;
-            yield emit({ type: "compare", leftId: left.id, rightId: key.id });
-            if (left.value <= key.value)
-                break;
-            slots[hole] = left;
-            slots[hole - 1] = null;
-            writes++;
-            sortedPrefixLength = hole - 1;
-            yield emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
-            hole--;
-        }
-        slots[hole] = key;
-        held = null;
-        writes++;
-        sortedPrefixLength = i + 1;
-        yield emit({ type: "insert", itemId: key.id, to: hole });
-    }
-    sortedPrefixLength = slots.length;
-    yield emit({ type: "done" });
-}
+import { insertion } from "../compat/algorithms.js";
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export const insertionSortSteps = insertion.steps;
+/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
+export const iterateInsertionSortSteps = insertion.iterate;

package/dist/core/player.d.ts

@@ -1,15 +1,10 @@
-import type { SortStep } from "./types.js";
+import { type Player } from "../playback/index.js";
+import type { SortStep, SortSnapshot, SortEvent } from "./types.js";
 import type { SortFrame } from "./timeline.js";
-export interface SortPlayer {
-    readonly frame: SortFrame;
-    readonly finished: boolean;
-    /** Advance by playback time; pass zero to redraw without consuming steps. */
-    advance(deltaMs: number): SortFrame;
-    /** Close the source early. The last frame remains readable. */
-    dispose(): void;
-}
-/** Forward-only playback. The source must end with a `done` event. */
+export type SortPlayer = Player<SortSnapshot, SortEvent>;
+/** Compatibility adapter for array steps ending in done. */
 export declare function createSortPlayer(steps: Iterable<SortStep>, options: {
     stepDurationMs: number;
     finalHoldMs: number;
+    render?: (frame: SortFrame) => void;
 }): SortPlayer;

package/dist/core/player.js

@@ -1,88 +1,5 @@
-/** Forward-only playback. The source must end with a `done` event. */
+import { createPlayer } from "../playback/index.js";
+/** Compatibility adapter for array steps ending in done. */
 export function createSortPlayer(steps, options) {
-    const { stepDurationMs, finalHoldMs } = options;
-    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
-        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
-        throw new RangeError("Expected positive step duration and non-negative final hold");
-    }
-    const iterator = steps[Symbol.iterator]();
-    let closed = false;
-    const close = () => {
-        if (!closed) {
-            closed = true;
-            iterator.return?.();
-        }
-    };
-    let current;
-    try {
-        const first = iterator.next();
-        if (first.done)
-            throw new RangeError("Player requires at least one step");
-        current = first.value;
-    }
-    catch (error) {
-        close();
-        throw error;
-    }
-    let previous = current;
-    let elapsed = stepDurationMs;
-    let hold = 0;
-    let disposed = false;
-    let finished = false;
-    const complete = () => {
-        if (current.event.type === "done" && elapsed === stepDurationMs) {
-            previous = current;
-            close();
-            finished = hold >= finalHoldMs;
-        }
-    };
-    complete();
-    const frame = () => Object.freeze({
-        previous: previous.state, current: current.state,
-        progress: elapsed / stepDurationMs,
-        stepIndex: current.index, event: current.event
-    });
-    return Object.freeze({
-        get frame() { return frame(); },
-        get finished() { return finished; },
-        advance(deltaMs) {
-            if (disposed)
-                throw new Error("Player has been disposed");
-            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
-                throw new RangeError("Expected finite non-negative playback time");
-            }
-            try {
-                let remaining = deltaMs;
-                while (remaining > 0 && !finished) {
-                    if (elapsed === stepDurationMs) {
-                        if (current.event.type === "done") {
-                            hold += Math.min(remaining, finalHoldMs - hold);
-                            complete();
-                            break;
-                        }
-                        const next = iterator.next();
-                        if (next.done)
-                            throw new RangeError("Step source ended without a done event");
-                        previous = current;
-                        current = next.value;
-                        elapsed = 0;
-                    }
-                    const amount = Math.min(remaining, stepDurationMs - elapsed);
-                    elapsed += amount;
-                    remaining -= amount;
-                    complete();
-                }
-                return frame();
-            }
-            catch (error) {
-                disposed = true;
-                close();
-                throw error;
-            }
-        },
-        dispose() {
-            disposed = true;
-            close();
-        }
-    });
+    return createPlayer(steps, { ...options, isTerminal: step => step.event.type === "done" });
 }

package/dist/core/timeline.d.ts

@@ -1,16 +1,7 @@
+import { type Frame, type Timeline } from "../playback/index.js";
 import type { SortEvent, SortSnapshot, SortStep } from "./types.js";
-export interface SortFrame {
-    readonly previous: SortSnapshot;
-    readonly current: SortSnapshot;
-    readonly progress: number;
-    readonly stepIndex: number;
-    readonly event: SortEvent;
-}
-export interface SortTimeline {
-    readonly durationMs: number;
-    sample(timeMs: number): SortFrame;
-}
-/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+export type SortFrame = Frame<SortSnapshot, SortEvent>;
+export type SortTimeline = Timeline<SortSnapshot, SortEvent>;
 export declare function createSortTimeline(steps: readonly SortStep[], options: {
     stepDurationMs: number;
     finalHoldMs: number;

package/dist/core/timeline.js

@@ -1,30 +1,4 @@
-/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+import { createTimeline } from "../playback/index.js";
 export function createSortTimeline(steps, options) {
-    if (!steps.length)
-        throw new RangeError("Timeline requires at least one step");
-    const { stepDurationMs, finalHoldMs } = options;
-    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
-        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
-        throw new RangeError("Expected positive step duration and non-negative final hold");
-    }
-    const history = steps.slice();
-    const end = (history.length - 1) * stepDurationMs;
-    const durationMs = end + finalHoldMs;
-    if (!Number.isFinite(durationMs))
-        throw new RangeError("Timeline duration is too large");
-    return Object.freeze({
-        durationMs,
-        sample(timeMs) {
-            if (!Number.isFinite(timeMs))
-                throw new TypeError("Time must be finite");
-            const time = Math.max(0, Math.min(timeMs, durationMs));
-            const index = Math.min(history.length - 1, Math.ceil(time / stepDurationMs));
-            const step = history[index];
-            const previous = time >= end || index === 0 ? step : history[index - 1];
-            const progress = previous === step ? 1 :
-                Math.min(1, (time - (index - 1) * stepDurationMs) / stepDurationMs);
-            return Object.freeze({ previous: previous.state, current: step.state,
-                progress, stepIndex: index, event: step.event });
-        }
-    });
+    return createTimeline(steps, options);
 }

package/dist/core/types.d.ts

@@ -1,41 +1 @@
-export type Item = Readonly<{
-    id: string;
-    value: number;
-}>;
-export type SortEvent = Readonly<{
-    type: "start";
-} | {
-    type: "select";
-    itemId: string;
-    from: number;
-} | {
-    type: "compare";
-    leftId: string;
-    rightId: string;
-} | {
-    type: "shift";
-    itemId: string;
-    from: number;
-    to: number;
-} | {
-    type: "insert";
-    itemId: string;
-    to: number;
-} | {
-    type: "done";
-}>;
-export interface SortSnapshot {
-    readonly slots: readonly (Item | null)[];
-    readonly held: Item | null;
-    /** Sorted leading occupied slots; during insertion it ends at the hole. */
-    readonly sortedPrefixLength: number;
-    readonly comparisons: number;
-    /** Writes into array slots; selecting a key does not count as a write. */
-    readonly writes: number;
-}
-export interface SortStep {
-    readonly index: number;
-    readonly event: SortEvent;
-    /** Complete immutable state immediately after the event. */
-    readonly state: SortSnapshot;
-}
+export type { Item, SortEvent, SortSnapshot, SortStep } from "../array/types.js";

package/dist/playback/index.d.ts

@@ -0,0 +1,4 @@
+export { createPlayer } from "./player.js";
+export type { Player } from "./player.js";
+export { createTimeline } from "./timeline.js";
+export type { Step, Frame, Timeline } from "./types.js";

package/dist/playback/index.js

@@ -0,0 +1,2 @@
+export { createPlayer } from "./player.js";
+export { createTimeline } from "./timeline.js";

package/dist/playback/player.d.ts

@@ -0,0 +1,18 @@
+import type { Step } from "./types.js";
+import type { Frame } from "./types.js";
+export interface Player<S, E> {
+    readonly frame: Frame<S, E>;
+    readonly finished: boolean;
+    /** Advance by playback time; pass zero to redraw without consuming steps. */
+    advance(deltaMs: number): Frame<S, E>;
+    /** Close the source early. The last frame remains readable. */
+    dispose(): void;
+}
+/** Forward-only playback. The source must reach a step accepted by isTerminal. */
+export declare function createPlayer<S, E>(steps: Iterable<Step<S, E>>, options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+    isTerminal: (step: Step<S, E>) => boolean;
+    /** Called initially and on each advance, including advance(0). */
+    render?: (frame: Frame<S, E>) => void;
+}): Player<S, E>;

package/dist/playback/player.js

@@ -0,0 +1,97 @@
+/** Forward-only playback. The source must reach a step accepted by isTerminal. */
+export function createPlayer(steps, options) {
+    const { stepDurationMs, finalHoldMs } = options;
+    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
+        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
+        throw new RangeError("Expected positive step duration and non-negative final hold");
+    }
+    const iterator = steps[Symbol.iterator]();
+    let closed = false;
+    const close = () => {
+        if (!closed) {
+            closed = true;
+            iterator.return?.();
+        }
+    };
+    let current;
+    try {
+        const first = iterator.next();
+        if (first.done)
+            throw new RangeError("Player requires at least one step");
+        current = first.value;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    let previous = current;
+    let elapsed = stepDurationMs;
+    let hold = 0;
+    let disposed = false;
+    let finished = false;
+    const complete = () => {
+        if (options.isTerminal(current) && elapsed === stepDurationMs) {
+            previous = current;
+            close();
+            finished = hold >= finalHoldMs;
+        }
+    };
+    const frame = () => Object.freeze({
+        previous: previous.state, current: current.state,
+        progress: elapsed / stepDurationMs,
+        stepIndex: current.index, event: current.event
+    });
+    try {
+        complete();
+        options.render?.(frame());
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    return Object.freeze({
+        get frame() { return frame(); },
+        get finished() { return finished; },
+        advance(deltaMs) {
+            if (disposed)
+                throw new Error("Player has been disposed");
+            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+                throw new RangeError("Expected finite non-negative playback time");
+            }
+            try {
+                let remaining = deltaMs;
+                while (remaining > 0 && !finished) {
+                    if (elapsed === stepDurationMs) {
+                        if (options.isTerminal(current)) {
+                            hold += Math.min(remaining, finalHoldMs - hold);
+                            complete();
+                            break;
+                        }
+                        const next = iterator.next();
+                        if (next.done)
+                            throw new RangeError("Step source ended without a terminal step");
+                        previous = current;
+                        current = next.value;
+                        elapsed = 0;
+                    }
+                    const amount = Math.min(remaining, stepDurationMs - elapsed);
+                    elapsed += amount;
+                    remaining -= amount;
+                    complete();
+                }
+                const result = frame();
+                options.render?.(result);
+                return result;
+            }
+            catch (error) {
+                disposed = true;
+                close();
+                throw error;
+            }
+        },
+        dispose() {
+            disposed = true;
+            close();
+        }
+    });
+}

package/dist/playback/timeline.d.ts

@@ -0,0 +1,6 @@
+import type { Step, Timeline } from "./types.js";
+/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+export declare function createTimeline<S, E>(steps: readonly Step<S, E>[], options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+}): Timeline<S, E>;

package/dist/playback/timeline.js

@@ -0,0 +1,30 @@
+/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+export function createTimeline(steps, options) {
+    if (!steps.length)
+        throw new RangeError("Timeline requires at least one step");
+    const { stepDurationMs, finalHoldMs } = options;
+    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
+        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
+        throw new RangeError("Expected positive step duration and non-negative final hold");
+    }
+    const history = steps.slice();
+    const end = (history.length - 1) * stepDurationMs;
+    const durationMs = end + finalHoldMs;
+    if (!Number.isFinite(durationMs))
+        throw new RangeError("Timeline duration is too large");
+    return Object.freeze({
+        durationMs,
+        sample(timeMs) {
+            if (!Number.isFinite(timeMs))
+                throw new TypeError("Time must be finite");
+            const time = Math.max(0, Math.min(timeMs, durationMs));
+            const index = Math.min(history.length - 1, Math.ceil(time / stepDurationMs));
+            const step = history[index];
+            const previous = time >= end || index === 0 ? step : history[index - 1];
+            const progress = previous === step ? 1 :
+                Math.min(1, (time - (index - 1) * stepDurationMs) / stepDurationMs);
+            return Object.freeze({ previous: previous.state, current: step.state,
+                progress, stepIndex: index, event: step.event });
+        }
+    });
+}