@wodzik/cubecore 0.1.0

package/solve/twophase.js

@@ -0,0 +1,229 @@
+/**
+ * Kociemba's two-phase algorithm, in TypeScript — solves any state in about
+ * 20 face turns, fast enough to make random-state scrambles.
+ *
+ * Phase 1 brings the cube into G1 = ⟨U, D, R2, L2, F2, B2⟩ (all twists and
+ * flips 0, the four middle-layer edges in the middle layer); phase 2 solves
+ * it using only G1 moves. Both are IDA* searches over small coordinates with
+ * pruning tables:
+ *
+ *   phase 1: twist (3^7), flip (2^11), slice position (C(12,4) = 495)
+ *   phase 2: corner permutation (8!), U/D edge permutation (8!), slice permutation (4!)
+ *
+ * Tables (~9 MB, move + pruning) are built once, on first use (about a
+ * second); build them early with `TwoPhase.create()` or in a worker.
+ * Pieces use the Kociemba numbering of core `cubies.ts`.
+ */
+import { parity, permRank, permUnrank, relativeState, toCubies, transformMoves } from "../core/index.js";
+import { MOVES, MOVE_CC, SOLVED_CC, mul } from "./pieces.js";
+export { MOVES };
+// ─── coordinates ───
+const N_TWIST = 2187, N_FLIP = 2048, N_SLICE = 495, N_PERM8 = 40320, N_SLICEPERM = 24;
+const twistOf = (c) => c.co.slice(0, 7).reduce((a, t) => a * 3 + t, 0);
+const flipOf = (c) => c.eo.slice(0, 11).reduce((a, f) => a * 2 + f, 0);
+const C = (n, k) => {
+    if (k < 0 || k > n)
+        return 0;
+    let r = 1;
+    for (let i = 0; i < k; i++)
+        r = (r * (n - i)) / (i + 1);
+    return r;
+};
+/** Which 4 of the 12 edge positions hold the middle-layer edges (8..11), as a combination rank. */
+function sliceOf(c) {
+    let r = 0, k = 0;
+    for (let i = 0; i < 12; i++)
+        if (c.ep[i] >= 8)
+            r += C(i, ++k);
+    return r;
+}
+const SOLVED_SLICE = C(8, 1) + C(9, 2) + C(10, 3) + C(11, 4);
+function withTwist(t) {
+    const co = new Array(8).fill(0);
+    for (let i = 6; i >= 0; i--, t = Math.floor(t / 3))
+        co[i] = t % 3;
+    co[7] = (3 - (co.reduce((a, b) => a + b, 0) % 3)) % 3;
+    return { ...SOLVED_CC, co };
+}
+function withFlip(f) {
+    const eo = new Array(12).fill(0);
+    for (let i = 10; i >= 0; i--, f = Math.floor(f / 2))
+        eo[i] = f % 2;
+    eo[11] = eo.reduce((a, b) => a + b, 0) % 2;
+    return { ...SOLVED_CC, eo };
+}
+function withSlice(r) {
+    const positions = [];
+    for (let k = 4, i = 11; k > 0; i--) {
+        if (r >= C(i, k)) {
+            r -= C(i, k);
+            positions.push(i);
+            k--;
+        }
+    }
+    const ep = new Array(12).fill(-1);
+    positions.sort((a, b) => a - b).forEach((p, j) => (ep[p] = 8 + j));
+    let e = 0;
+    for (let i = 0; i < 12; i++)
+        if (ep[i] < 0)
+            ep[i] = e++;
+    return { ...SOLVED_CC, ep };
+}
+// Phase 2 only turns with G1 moves.
+const P2_MOVES = [0, 1, 2, 9, 10, 11, 4, 13, 7, 16];
+function moveTable(n, make, coord, moves) {
+    const t = new Uint16Array(n * moves.length);
+    for (let i = 0; i < n; i++) {
+        const c = make(i);
+        moves.forEach((m, j) => (t[i * moves.length + j] = coord(mul(c, MOVE_CC[m]))));
+    }
+    return t;
+}
+/** Breadth-first distances over a product of two coordinates. */
+function pruneTable(n1, n2, move1, move2, moveCount, start) {
+    const dist = new Int8Array(n1 * n2).fill(-1);
+    const queue = new Int32Array(n1 * n2);
+    let head = 0, tail = 0;
+    dist[start] = 0;
+    queue[tail++] = start;
+    while (head < tail) {
+        const s = queue[head++];
+        const a = Math.floor(s / n2), b = s % n2, d = dist[s] + 1;
+        for (let m = 0; m < moveCount; m++) {
+            const next = move1[a * moveCount + m] * n2 + move2[b * moveCount + m];
+            if (dist[next] < 0) {
+                dist[next] = d;
+                queue[tail++] = next;
+            }
+        }
+    }
+    return dist;
+}
+function buildTables() {
+    const all18 = MOVES.map((_, i) => i);
+    const twistMove = moveTable(N_TWIST, withTwist, twistOf, all18);
+    const flipMove = moveTable(N_FLIP, withFlip, flipOf, all18);
+    const sliceMove = moveTable(N_SLICE, withSlice, sliceOf, all18);
+    const cornerMove = moveTable(N_PERM8, (i) => ({ ...SOLVED_CC, cp: permUnrank(i, 8) }), (c) => permRank(c.cp), all18);
+    const udEdgeMove = moveTable(N_PERM8, (i) => ({ ...SOLVED_CC, ep: [...permUnrank(i, 8), 8, 9, 10, 11] }), (c) => permRank(c.ep.slice(0, 8)), P2_MOVES);
+    const slicePermMove = Uint8Array.from(moveTable(N_SLICEPERM, (i) => ({ ...SOLVED_CC, ep: [0, 1, 2, 3, 4, 5, 6, 7, ...permUnrank(i, 4).map((e) => e + 8)] }), (c) => permRank(c.ep.slice(8).map((e) => e - 8)), P2_MOVES));
+    // Phase-2 pruning walks P2 moves: pick the corner-table columns for them.
+    const cornerP2 = new Uint16Array(N_PERM8 * P2_MOVES.length);
+    for (let i = 0; i < N_PERM8; i++)
+        P2_MOVES.forEach((m, j) => (cornerP2[i * P2_MOVES.length + j] = cornerMove[i * 18 + m]));
+    return {
+        twistMove,
+        flipMove,
+        sliceMove,
+        cornerMove,
+        udEdgeMove,
+        slicePermMove,
+        pruneTwist: pruneTable(N_SLICE, N_TWIST, sliceMove, twistMove, 18, SOLVED_SLICE * N_TWIST),
+        pruneFlip: pruneTable(N_SLICE, N_FLIP, sliceMove, flipMove, 18, SOLVED_SLICE * N_FLIP),
+        pruneCorner: pruneTable(N_SLICEPERM, N_PERM8, slicePermMove, cornerP2, P2_MOVES.length, 0),
+        pruneEdge: pruneTable(N_SLICEPERM, N_PERM8, slicePermMove, udEdgeMove, P2_MOVES.length, 0),
+    };
+}
+const faceOf = (m) => Math.floor(m / 3);
+/** Skip a turn of the same face, and the second of two opposite faces in the "wrong" order (U D ok, D U not). */
+const redundant = (face, last) => last >= 0 && (face === last || face === last - 3);
+export class TwoPhase {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    /** Build the tables (about a second) — do it once, early, or in a worker. */
+    static create() {
+        return new TwoPhase(buildTables());
+    }
+    /** A solution for `state` (face turns, applied to `state` they solve it), or null. */
+    solve(state, options = {}) {
+        const cubies = toCubies(state);
+        if (!cubies)
+            return null;
+        // Solve the cube as seen with its centres at home, then say the same moves in the cube's own frame.
+        const c = { cp: cubies.cp, co: cubies.co, ep: cubies.ep, eo: cubies.eo };
+        if (parity(c.cp) !== parity(c.ep) || c.co.reduce((a, b) => a + b, 0) % 3 || c.eo.reduce((a, b) => a + b, 0) % 2)
+            return null;
+        const moves = this.search(c, options.maxLength ?? 21, performance.now() + (options.timeoutMs ?? 5000));
+        if (!moves)
+            return null;
+        return cubies.frame.id === 0 ? moves : transformMoves(moves, cubies.frame);
+    }
+    /** Moves taking `from` to `to` (e.g. from the cube's current state to a scramble's target). */
+    solveBetween(from, to, options = {}) {
+        return this.solve(relativeState(from, to), options);
+    }
+    search(c, maxLength, deadline) {
+        const t = this.t;
+        const path1 = [];
+        const path2 = [];
+        let nodes = 0;
+        let timedOut = false;
+        const phase2 = (corner, edge, slice, depth, last) => {
+            if (depth === 0)
+                return corner === 0 && edge === 0 && slice === 0;
+            const h = Math.max(t.pruneCorner[slice * N_PERM8 + corner], t.pruneEdge[slice * N_PERM8 + edge]);
+            if (h > depth)
+                return false;
+            for (let j = 0; j < P2_MOVES.length; j++) {
+                const m = P2_MOVES[j];
+                const f = faceOf(m);
+                if (redundant(f, last))
+                    continue;
+                path2.push(m);
+                if (phase2(t.cornerMove[corner * 18 + m], t.udEdgeMove[edge * 10 + j], t.slicePermMove[slice * 10 + j], depth - 1, f))
+                    return true;
+                path2.pop();
+            }
+            return false;
+        };
+        const startPhase2 = (budget) => {
+            let g1 = c;
+            for (const m of path1)
+                g1 = mul(g1, MOVE_CC[m]);
+            const corner = permRank(g1.cp), edge = permRank(g1.ep.slice(0, 8)), slice = permRank(g1.ep.slice(8).map((e) => e - 8));
+            const last = path1.length ? faceOf(path1[path1.length - 1]) : -1;
+            for (let d = 0; d <= Math.min(budget, 18); d++)
+                if (phase2(corner, edge, slice, d, last))
+                    return true;
+            return false;
+        };
+        const phase1 = (twist, flip, slice, depth, last, total) => {
+            if ((++nodes & 4095) === 0 && performance.now() > deadline)
+                timedOut = true;
+            if (timedOut)
+                return false;
+            if (depth === 0) {
+                if (twist !== 0 || flip !== 0 || slice !== SOLVED_SLICE)
+                    return false;
+                // A phase-1 path ending in a G1 move is a longer copy of one already tried.
+                const lm = path1[path1.length - 1];
+                if (path1.length && P2_MOVES.includes(lm))
+                    return false;
+                return startPhase2(total - path1.length);
+            }
+            const h = Math.max(t.pruneTwist[slice * N_TWIST + twist], t.pruneFlip[slice * N_FLIP + flip]);
+            if (h > depth)
+                return false;
+            for (let m = 0; m < 18; m++) {
+                const f = faceOf(m);
+                if (redundant(f, last))
+                    continue;
+                path1.push(m);
+                if (phase1(t.twistMove[twist * 18 + m], t.flipMove[flip * 18 + m], t.sliceMove[slice * 18 + m], depth - 1, f, total))
+                    return true;
+                path1.pop();
+            }
+            return false;
+        };
+        const twist = twistOf(c), flip = flipOf(c), slice = sliceOf(c);
+        for (let d1 = 0; d1 <= maxLength; d1++) {
+            if (phase1(twist, flip, slice, d1, -1, maxLength))
+                return [...path1, ...path2].map((m) => MOVES[m]);
+            if (timedOut)
+                return null;
+        }
+        return null;
+    }
+}

package/solve/worker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The solver worker's entry point: tables are built here, off the main
+ * thread, and stay warm for the worker's lifetime. Use it through
+ * `createSolverWorker()` (client.ts).
+ */
+export {};

package/solve/worker.js

@@ -0,0 +1,15 @@
+/**
+ * The solver worker's entry point: tables are built here, off the main
+ * thread, and stay warm for the worker's lifetime. Use it through
+ * `createSolverWorker()` (client.ts).
+ */
+import { handle } from "./handle.js";
+self.onmessage = async (e) => {
+    const { id, request } = e.data;
+    try {
+        self.postMessage({ id, ok: true, value: await handle(request) });
+    }
+    catch (err) {
+        self.postMessage({ id, ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+};

package/timeline/codec.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compact, URL-safe encoding of a Recording (e.g. for share links or storing
+ * many solves). Version 1, base64url without padding:
+ *   byte    version
+ *   varint  totalMs
+ *   varint  scramble length, then 6-bit move symbols
+ *   varint  move count,      then 6-bit move symbols
+ *   varint× per move: time since the previous move in 10 ms ticks (rounded on
+ *           the absolute time, so rounding never accumulates)
+ * A move symbol = family index (MOVE_FAMILIES order) × 3 + amount (1, ', 2),
+ * so every move family — slices, wide turns, rotations — fits.
+ * Decoding is strict: unknown version, truncation, trailing bytes, absurd sizes
+ * and bad symbols return null.
+ */
+import { ByteReader } from "../core/index.js";
+import type { Recording } from "./recording.js";
+export declare const CODEC_VERSION = 1;
+/** Append a recording's bytes (everything after the version byte). */
+export declare function writeRecording(out: number[], rec: Recording): void;
+/** Read what `writeRecording` wrote; null on anything malformed. */
+export declare function readRecording(r: ByteReader): Recording | null;
+export declare function encodeRecording(rec: Recording): string;
+export declare function decodeRecording(text: string): Recording | null;

package/timeline/codec.js

@@ -0,0 +1,84 @@
+/**
+ * Compact, URL-safe encoding of a Recording (e.g. for share links or storing
+ * many solves). Version 1, base64url without padding:
+ *   byte    version
+ *   varint  totalMs
+ *   varint  scramble length, then 6-bit move symbols
+ *   varint  move count,      then 6-bit move symbols
+ *   varint× per move: time since the previous move in 10 ms ticks (rounded on
+ *           the absolute time, so rounding never accumulates)
+ * A move symbol = family index (MOVE_FAMILIES order) × 3 + amount (1, ', 2),
+ * so every move family — slices, wide turns, rotations — fits.
+ * Decoding is strict: unknown version, truncation, trailing bytes, absurd sizes
+ * and bad symbols return null.
+ */
+import { ByteReader, MOVE_FAMILIES, fromBase64Url, packBits, toBase64Url, writeVarint } from "../core/index.js";
+export const CODEC_VERSION = 1;
+const TICK_MS = 10;
+const AMOUNTS = [1, -1, 2];
+const MAX_MOVES = 10_000;
+const MAX_TIME = 24 * 3600 * 1000;
+const symbolOf = (m) => MOVE_FAMILIES.indexOf(m.family) * 3 + AMOUNTS.indexOf(m.amount);
+const moveOf = (s) => {
+    const family = MOVE_FAMILIES[Math.floor(s / 3)];
+    return family ? { family, amount: AMOUNTS[s % 3] } : null;
+};
+/** Append a recording's bytes (everything after the version byte). */
+export function writeRecording(out, rec) {
+    writeVarint(out, rec.totalMs);
+    writeVarint(out, rec.scramble.length);
+    packBits(out, rec.scramble.map(symbolOf), 6);
+    writeVarint(out, rec.moves.length);
+    packBits(out, rec.moves.map((m) => symbolOf(m.move)), 6);
+    let prev = 0;
+    for (const m of rec.moves) {
+        const tick = Math.max(prev, Math.round(Math.max(0, m.t) / TICK_MS));
+        writeVarint(out, tick - prev);
+        prev = tick;
+    }
+}
+/** Read what `writeRecording` wrote; null on anything malformed. */
+export function readRecording(r) {
+    const totalMs = r.varint();
+    if (totalMs === null || totalMs > MAX_TIME)
+        return null;
+    const sLen = r.varint();
+    if (sLen === null || sLen > MAX_MOVES)
+        return null;
+    const scramble = r.packed(sLen, 6)?.map(moveOf);
+    if (!scramble || scramble.some((m) => m === null))
+        return null;
+    const n = r.varint();
+    if (n === null || n > MAX_MOVES)
+        return null;
+    const moves = r.packed(n, 6)?.map(moveOf);
+    if (!moves || moves.some((m) => m === null))
+        return null;
+    const timed = [];
+    let tick = 0;
+    for (let i = 0; i < n; i++) {
+        const d = r.varint();
+        if (d === null)
+            return null;
+        tick += d;
+        timed.push({ move: moves[i], t: tick * TICK_MS });
+    }
+    if (timed.length && timed.at(-1).t > totalMs + TICK_MS)
+        return null;
+    return { scramble: scramble, moves: timed, totalMs };
+}
+export function encodeRecording(rec) {
+    const out = [CODEC_VERSION];
+    writeRecording(out, rec);
+    return toBase64Url(out);
+}
+export function decodeRecording(text) {
+    const bytes = fromBase64Url(text);
+    if (!bytes)
+        return null;
+    const r = new ByteReader(bytes);
+    if (r.byte() !== CODEC_VERSION)
+        return null;
+    const rec = readRecording(r);
+    return rec && r.done ? rec : null;
+}

package/timeline/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./recording.js";
+export * from "./codec.js";
+export * from "./replay.js";
+export * from "./timings.js";
+export * from "./share.js";
+export * from "./segments.js";
+export * from "./stats.js";

package/timeline/index.js

@@ -0,0 +1,7 @@
+export * from "./recording.js";
+export * from "./codec.js";
+export * from "./replay.js";
+export * from "./timings.js";
+export * from "./share.js";
+export * from "./segments.js";
+export * from "./stats.js";

package/timeline/recording.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A recorded solve: the scramble and every move with the time it was made
+ * (ms since the timer started), plus the final time. Smart cubes report a
+ * move when it finishes, so `t` is the moment the move COMPLETED.
+ */
+import { type Move } from "../core/index.js";
+export interface TimedMove {
+    move: Move;
+    /** ms since the timer started, when the move completed. Non-decreasing. */
+    t: number;
+}
+export interface Recording {
+    scramble: Move[];
+    moves: TimedMove[];
+    /** Final time in ms (≥ the last move's t). */
+    totalMs: number;
+}
+/** Convenience builder: `recording("R U", [["R", 120], ["U'", 300]], 450)`. */
+export declare function recording(scramble: string, moves: readonly [string, number][], totalMs?: number): Recording;

package/timeline/recording.js

@@ -0,0 +1,20 @@
+/**
+ * A recorded solve: the scramble and every move with the time it was made
+ * (ms since the timer started), plus the final time. Smart cubes report a
+ * move when it finishes, so `t` is the moment the move COMPLETED.
+ */
+import { parseAlg } from "../core/index.js";
+/** Convenience builder: `recording("R U", [["R", 120], ["U'", 300]], 450)`. */
+export function recording(scramble, moves, totalMs) {
+    const timed = moves.map(([m, t]) => {
+        const parsed = parseAlg(m);
+        if (parsed.length !== 1)
+            throw new Error(`"${m}" is not a single move`);
+        return { move: parsed[0], t };
+    });
+    for (let i = 1; i < timed.length; i++)
+        if (timed[i].t < timed[i - 1].t)
+            throw new Error(`Move ${i} goes back in time`);
+    const last = timed.at(-1)?.t ?? 0;
+    return { scramble: parseAlg(scramble), moves: timed, totalMs: Math.max(totalMs ?? last, last) };
+}

package/timeline/replay.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Time-accurate replay. A move's animation ENDS at its recorded time (smart
+ * cubes report a move when it completes) and lasts at most `maxAnimMs`, never
+ * overlapping the previous move — so fast triggers stay fast and pauses stay
+ * pauses, unlike a fixed-tempo player.
+ */
+import type { Recording } from "./recording.js";
+export interface ReplayOptions {
+    /** Longest a single move animates (ms of recording time). Default 150. */
+    maxAnimMs?: number;
+}
+export interface Position {
+    /** Moves fully done at this time. */
+    applied: number;
+    /** The move animating right now, if any, with progress 0..1. */
+    active?: {
+        index: number;
+        progress: number;
+    };
+}
+/** Animation window [start, end] of every move. */
+export declare function moveWindows(rec: Recording, options?: ReplayOptions): [number, number][];
+export declare function positionAt(rec: Recording, timeMs: number, options?: ReplayOptions): Position;
+export interface ClockHost {
+    now(): number;
+    /** Ask for a callback on the next frame; returns a cancel function. */
+    frame(cb: () => void): () => void;
+}
+type Listener = (time: number, position: Position) => void;
+/**
+ * Drives a replay in real time. `rate` scales playback (2 = twice as fast)
+ * keeping the proportions of pauses. Listeners get the recording time and
+ * the position on every frame and after every seek.
+ */
+export declare class ReplayClock {
+    readonly recording: Recording;
+    private readonly options;
+    private readonly host;
+    private time;
+    private playing;
+    private anchorReal;
+    private anchorTime;
+    private cancel;
+    private listeners;
+    private _rate;
+    constructor(recording: Recording, options?: ReplayOptions, host?: ClockHost);
+    get currentTime(): number;
+    get isPlaying(): boolean;
+    get rate(): number;
+    set rate(r: number);
+    onChange(listener: Listener): () => void;
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): void;
+    /** Jump to the moment move `index` completed (−1 = start). */
+    seekToMove(index: number): void;
+    private rebase;
+    private tick;
+    private loop;
+    private emit;
+}
+/**
+ * A recording with every pause longer than `maxPauseMs` shortened to it —
+ * long recognitions (or a break mid-solve) don't drag the replay. Moves keep
+ * their order and the gaps up to the cap; the total shrinks accordingly.
+ */
+export declare function compressPauses(rec: Recording, maxPauseMs: number): Recording;
+export {};

package/timeline/replay.js

@@ -0,0 +1,145 @@
+/**
+ * Time-accurate replay. A move's animation ENDS at its recorded time (smart
+ * cubes report a move when it completes) and lasts at most `maxAnimMs`, never
+ * overlapping the previous move — so fast triggers stay fast and pauses stay
+ * pauses, unlike a fixed-tempo player.
+ */
+/** Animation window [start, end] of every move. */
+export function moveWindows(rec, options = {}) {
+    const max = options.maxAnimMs ?? 150;
+    let prevEnd = 0;
+    return rec.moves.map(({ t }) => {
+        const start = Math.max(t - max, prevEnd);
+        prevEnd = t;
+        return [start, t];
+    });
+}
+export function positionAt(rec, timeMs, options = {}) {
+    const windows = moveWindows(rec, options);
+    let applied = 0;
+    while (applied < windows.length && windows[applied][1] <= timeMs)
+        applied++;
+    const next = windows[applied];
+    if (next && timeMs > next[0]) {
+        const span = next[1] - next[0];
+        return { applied, active: { index: applied, progress: span > 0 ? (timeMs - next[0]) / span : 1 } };
+    }
+    return { applied };
+}
+const browserHost = {
+    now: () => performance.now(),
+    frame: (cb) => {
+        const id = requestAnimationFrame(() => cb());
+        return () => cancelAnimationFrame(id);
+    },
+};
+/**
+ * Drives a replay in real time. `rate` scales playback (2 = twice as fast)
+ * keeping the proportions of pauses. Listeners get the recording time and
+ * the position on every frame and after every seek.
+ */
+export class ReplayClock {
+    recording;
+    options;
+    host;
+    time = 0;
+    playing = false;
+    anchorReal = 0;
+    anchorTime = 0;
+    cancel = null;
+    listeners = new Set();
+    _rate = 1;
+    constructor(recording, options = {}, host = browserHost) {
+        this.recording = recording;
+        this.options = options;
+        this.host = host;
+    }
+    get currentTime() {
+        return this.time;
+    }
+    get isPlaying() {
+        return this.playing;
+    }
+    get rate() {
+        return this._rate;
+    }
+    set rate(r) {
+        this.rebase();
+        this._rate = r;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    play() {
+        if (this.playing)
+            return;
+        if (this.time >= this.recording.totalMs)
+            this.time = 0;
+        this.playing = true;
+        this.rebase();
+        this.loop();
+    }
+    pause() {
+        this.tick();
+        this.playing = false;
+        this.cancel?.();
+        this.cancel = null;
+    }
+    seek(timeMs) {
+        this.time = Math.min(Math.max(0, timeMs), this.recording.totalMs);
+        this.rebase();
+        this.emit();
+    }
+    /** Jump to the moment move `index` completed (−1 = start). */
+    seekToMove(index) {
+        this.seek(index < 0 ? 0 : this.recording.moves[Math.min(index, this.recording.moves.length - 1)].t);
+    }
+    rebase() {
+        this.anchorReal = this.host.now();
+        this.anchorTime = this.time;
+    }
+    tick() {
+        if (!this.playing)
+            return;
+        this.time = Math.min(this.anchorTime + (this.host.now() - this.anchorReal) * this._rate, this.recording.totalMs);
+        this.emit();
+        if (this.time >= this.recording.totalMs) {
+            this.playing = false;
+            this.cancel?.();
+            this.cancel = null;
+        }
+    }
+    loop() {
+        this.cancel = this.host.frame(() => {
+            this.tick();
+            if (this.playing)
+                this.loop();
+        });
+    }
+    emit() {
+        const pos = positionAt(this.recording, this.time, this.options);
+        for (const l of this.listeners)
+            l(this.time, pos);
+    }
+}
+/**
+ * A recording with every pause longer than `maxPauseMs` shortened to it —
+ * long recognitions (or a break mid-solve) don't drag the replay. Moves keep
+ * their order and the gaps up to the cap; the total shrinks accordingly.
+ */
+export function compressPauses(rec, maxPauseMs) {
+    let removed = 0;
+    let prev = 0;
+    const moves = rec.moves.map((m) => {
+        const gap = m.t - prev;
+        prev = m.t;
+        if (gap > maxPauseMs)
+            removed += gap - maxPauseMs;
+        return { move: m.move, t: m.t - removed };
+    });
+    const tail = rec.totalMs - prev;
+    if (tail > maxPauseMs)
+        removed += tail - maxPauseMs;
+    return { scramble: rec.scramble, moves, totalMs: rec.totalMs - removed };
+}

package/timeline/segments.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Segments — sections of a timeline for a progress bar: where each part
+ * starts and ends, what it's called, and optionally where "looking" turns
+ * into "turning". Plain data, independent of any method: a player shows
+ * whatever segments it's given (guide chapters, stored stage times…);
+ * `stageSegments` computes them from a recorded solve for any Method.
+ */
+import type { Method } from "../core/index.js";
+import type { Recording } from "./recording.js";
+export interface Segment {
+    /** ms of recording time. */
+    start: number;
+    end: number;
+    label: string;
+    /** Stable id — becomes ::part(segment-<id>) for styling. */
+    id?: string;
+    /** Extra detail, e.g. the F2L slot or the OLL case. */
+    detail?: string;
+    /** End of the recognition pause (start ≤ split ≤ end): the part before it was looking, after it turning. */
+    split?: number;
+    /** Moves in the segment. */
+    moves?: number;
+    /** A colour of your own (else the player's palette). */
+    color?: string;
+}
+/** The stages of `method` in a recorded solve as segments (skipped stages — no time of their own — left out). */
+export declare function stageSegments(method: Method, rec: Recording): Segment[];
+/** The segment `time` falls in (index), or −1. */
+export declare function segmentAt(segments: readonly Segment[], time: number): number;
+/** How much of a segment has played at `time` (0..1). */
+export declare function segmentPlayed(s: Segment, time: number): number;