@kgdiff/scene 0.0.0-stage → 0.2.0

package/src/theme.ts

@@ -0,0 +1,185 @@
+/**
+ * Design tokens (docs/visual-language.md §Color tokens, §Typography, motion).
+ *
+ * Four frozen themes: dark ("night") / light ("paper") × default / colorblind palette.
+ * Contrast requirements are asserted by `test/theme.test.ts`.
+ */
+import { KgdiffError } from '@kgdiff/core';
+import { withAlpha } from './color.js';
+import type { ChangeFamily, FamilyColors, PaletteName, Theme, ThemeName } from './types.js';
+
+export const FONT_FAMILY =
+  'Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", ' +
+  '"Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", system-ui, sans-serif';
+export const FONT_MONO = '"JetBrains Mono", "SF Mono", ui-monospace, Menlo, Consolas, monospace';
+
+const MOTION: Theme['motion'] = { fast: 120, base: 220, slow: 420, easing: [0.2, 0, 0, 1] };
+const FONT: Theme['font'] = {
+  family: FONT_FAMILY,
+  mono: FONT_MONO,
+  size: 12,
+  weightRegular: 400,
+  weightStrong: 600,
+};
+
+type FamilyTable = Readonly<Record<ChangeFamily, FamilyColors>>;
+
+const DARK_FAMILIES: FamilyTable = {
+  added: { base: '#34D399', strong: '#6EE7B7', soft: 'rgba(52,211,153,0.16)', text: '#6EE7B7' },
+  removed: { base: '#F87171', strong: '#FCA5A5', soft: 'rgba(248,113,113,0.15)', text: '#FCA5A5' },
+  content: { base: '#FBBF24', strong: '#FCD34D', soft: 'rgba(251,191,36,0.15)', text: '#FCD34D' },
+  structure: { base: '#38BDF8', strong: '#7DD3FC', soft: 'rgba(56,189,248,0.15)', text: '#7DD3FC' },
+  identity: { base: '#A78BFA', strong: '#C4B5FD', soft: 'rgba(167,139,250,0.17)', text: '#C4B5FD' },
+};
+
+const LIGHT_FAMILIES: FamilyTable = {
+  // text: spec #15803D measures 4.20:1 over its soft tint on the canvas (badges); one step
+  // darker, same hue → 4.54:1.
+  added: { base: '#16A34A', strong: '#15803D', soft: 'rgba(22,163,74,0.11)', text: '#147A3A' },
+  removed: { base: '#DC2626', strong: '#B91C1C', soft: 'rgba(220,38,38,0.09)', text: '#B91C1C' },
+  // Spec value #D97706 measures 2.998:1 on #F7F8FA (needs ≥ 3:1); one step darker passes (3.06:1)
+  // and is visually indistinguishable. The soft tint keeps the original hue.
+  content: { base: '#D87506', strong: '#B45309', soft: 'rgba(217,119,6,0.11)', text: '#92400E' },
+  structure: { base: '#0284C7', strong: '#0369A1', soft: 'rgba(2,132,199,0.10)', text: '#075985' },
+  identity: { base: '#7C3AED', strong: '#6D28D9', soft: 'rgba(124,58,237,0.10)', text: '#5B21B6' },
+};
+
+/**
+ * Okabe–Ito based palette (spec gives base / text). Derived tokens follow the default palette's
+ * pattern: dark `strong` = `text` (as in every default dark family); light `strong` = the sRGB
+ * midpoint of base and text (between mark and text, like content / structure / identity);
+ * `soft` = base at the default palette's per-family tint alpha.
+ */
+function okabeIto(
+  base: Record<ChangeFamily, readonly [base: string, text: string, strong: string]>,
+  soft: Readonly<Record<ChangeFamily, number>>,
+): FamilyTable {
+  const make = (f: ChangeFamily): FamilyColors => {
+    const [b, text, strong] = base[f];
+    return { base: b, strong, soft: withAlpha(b, soft[f]), text };
+  };
+  return {
+    added: make('added'),
+    removed: make('removed'),
+    content: make('content'),
+    structure: make('structure'),
+    identity: make('identity'),
+  };
+}
+
+const DARK_SOFT = { added: 0.16, removed: 0.15, content: 0.15, structure: 0.15, identity: 0.17 };
+const LIGHT_SOFT = { added: 0.11, removed: 0.09, content: 0.11, structure: 0.1, identity: 0.1 };
+
+const DARK_COLORBLIND = okabeIto(
+  {
+    added: ['#56B4E9', '#8FD0F5', '#8FD0F5'],
+    removed: ['#E69F00', '#F5C45C', '#F5C45C'],
+    content: ['#F0E442', '#F5EC85', '#F5EC85'],
+    structure: ['#009E73', '#3CC79E', '#3CC79E'],
+    identity: ['#CC79A7', '#E0A6C6', '#E0A6C6'],
+  },
+  DARK_SOFT,
+);
+
+const LIGHT_COLORBLIND = okabeIto(
+  {
+    added: ['#0072B2', '#005A8C', '#00669F'],
+    removed: ['#D55E00', '#A84A00', '#BF5400'],
+    content: ['#9A8700', '#6E6100', '#847400'],
+    structure: ['#00805C', '#006248', '#007152'],
+    identity: ['#A3477F', '#83335F', '#933D6F'],
+  },
+  LIGHT_SOFT,
+);
+
+function dark(palette: PaletteName): Theme {
+  return {
+    name: 'dark',
+    palette,
+    canvas: { background: '#0B0E14', grid: 'rgba(148, 163, 184, 0.07)' },
+    surface: {
+      panel: '#11151D',
+      raised: '#171C26',
+      overlay: 'rgba(17, 21, 29, 0.78)',
+      border: 'rgba(255,255,255,0.07)',
+      borderStrong: 'rgba(255,255,255,0.13)',
+      controlBorder: '#5E687C',
+      shadow: '0 8px 32px rgba(0,0,0,0.45), 0 1px 0 rgba(255,255,255,0.04) inset',
+    },
+    // muted: spec #737D8F measures 4.11:1 on raised; same hue, lighter → ≥ 4.5:1 everywhere.
+    text: { primary: '#E7EBF3', secondary: '#A6AFBF', muted: '#7A8495' },
+    accent: { base: '#7C9CFF', strong: '#A3BAFF', soft: 'rgba(124,156,255,0.16)', text: '#A9BEFF' },
+    neutral: { node: '#4B5568', nodeStroke: '#5E687C', edge: '#323A4A', label: '#8B94A6' },
+    family: palette === 'colorblind' ? DARK_COLORBLIND : DARK_FAMILIES,
+    glow: true,
+    font: FONT,
+    motion: MOTION,
+  };
+}
+
+function light(palette: PaletteName): Theme {
+  return {
+    name: 'light',
+    palette,
+    canvas: { background: '#F7F8FA', grid: 'rgba(15, 23, 42, 0.07)' },
+    surface: {
+      panel: '#FFFFFF',
+      raised: '#FFFFFF',
+      overlay: 'rgba(255, 255, 255, 0.82)',
+      border: 'rgba(15,23,42,0.08)',
+      borderStrong: 'rgba(15,23,42,0.15)',
+      controlBorder: '#8690A3',
+      shadow: '0 8px 28px rgba(15,23,42,0.10), 0 1px 2px rgba(15,23,42,0.06)',
+    },
+    // muted: spec #7B8597 measures 3.50:1 on the canvas; same hue, darker → ≥ 4.5:1 everywhere.
+    text: { primary: '#0F172A', secondary: '#475569', muted: '#687284' },
+    accent: { base: '#3B5BDB', strong: '#2F49B5', soft: 'rgba(59,91,219,0.10)', text: '#2F49B5' },
+    neutral: { node: '#A7B0BF', nodeStroke: '#8C96A8', edge: '#D3D9E2', label: '#5F6B7D' },
+    family: palette === 'colorblind' ? LIGHT_COLORBLIND : LIGHT_FAMILIES,
+    glow: false,
+    font: FONT,
+    motion: MOTION,
+  };
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const v of Object.values(value)) deepFreeze(v);
+  }
+  return value;
+}
+
+const cache = new Map<string, Theme>();
+
+export const THEME_NAMES: readonly ThemeName[] = ['dark', 'light'];
+export const PALETTE_NAMES: readonly PaletteName[] = ['default', 'colorblind'];
+
+/**
+ * Design tokens for a theme / palette pair (docs/visual-language.md §Color).
+ * Returns a deeply frozen, cached object: the same pair always yields the same instance,
+ * so it can key caches.
+ *
+ * @throws KgdiffError(`invalid-input`) for an unknown theme or palette name.
+ */
+export function getTheme(name: ThemeName, palette: PaletteName = 'default'): Theme {
+  if (!THEME_NAMES.includes(name)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `Unknown theme "${String(name)}" (expected "dark" or "light").`,
+    );
+  }
+  if (!PALETTE_NAMES.includes(palette)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `Unknown palette "${String(palette)}" (expected "default" or "colorblind").`,
+    );
+  }
+  const key = `${name}/${palette}`;
+  let theme = cache.get(key);
+  if (theme === undefined) {
+    theme = deepFreeze(name === 'dark' ? dark(palette) : light(palette));
+    cache.set(key, theme);
+  }
+  return theme;
+}

package/src/timeline.ts

@@ -0,0 +1,391 @@
+/**
+ * Review / replay order and the replay timeline (docs/algorithms.md §10).
+ */
+import type { HunkKind, Rect, ReplayPhase } from '@kgdiff/core';
+import { TIMELINE } from './constants.js';
+import { BoundsBuilder } from './geometry.js';
+import type { Timeline, TimelineChapter, TimelineWindow } from './types.js';
+
+export const PHASE_ORDER: readonly ReplayPhase[] = ['remove', 'restructure', 'modify', 'add'];
+
+export interface TourHunk {
+  readonly phase: ReplayPhase;
+  /** Changed nodes + edges. */
+  readonly size: number;
+  /** Default review order from core (tie-breaker). */
+  readonly order: number;
+  /** Anchor position. */
+  readonly x: number;
+  readonly y: number;
+  /** Indices (into the same array) of hunks that must come first (core `Hunk.requires`). */
+  readonly requires: readonly number[];
+}
+
+/** Lexicographic (squared distance, default order) comparison: true when a beats b. */
+const better = (d2a: number, oa: number, d2b: number, ob: number): boolean =>
+  d2a < d2b || (d2a === d2b && oa < ob);
+
+/**
+ * Uniform grid over a set of points supporting "nearest eligible point" queries. Points start
+ * ineligible; `activate` makes one eligible (its requirements are placed), `take` removes it.
+ * Ties are broken by `order`. Expected O(1) cells per query for spread points.
+ */
+class NearestGrid {
+  private readonly minX: number;
+  private readonly minY: number;
+  private readonly cw: number;
+  private readonly ch: number;
+  private readonly gw: number;
+  private readonly gh: number;
+  private readonly cellStart: Int32Array;
+  private readonly cellItems: Int32Array;
+  private readonly cellAlive: Int32Array;
+  private readonly alive: Uint8Array;
+  private remaining: number;
+
+  constructor(
+    private readonly items: readonly TourHunk[],
+    private readonly members: readonly number[],
+  ) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const m of members) {
+      const it = items[m] as TourHunk;
+      minX = Math.min(minX, it.x);
+      minY = Math.min(minY, it.y);
+      maxX = Math.max(maxX, it.x);
+      maxY = Math.max(maxY, it.y);
+    }
+    const side = Math.max(1, Math.ceil(Math.sqrt(members.length)));
+    this.gw = side;
+    this.gh = side;
+    this.minX = minX;
+    this.minY = minY;
+    // Guard against zero / underflowing extents (e.g. coordinates a denormal apart).
+    const cw = (maxX - minX) / side;
+    const ch = (maxY - minY) / side;
+    this.cw = cw > 0 && Number.isFinite(cw) ? cw : 1;
+    this.ch = ch > 0 && Number.isFinite(ch) ? ch : 1;
+    const cells = this.gw * this.gh;
+    const counts = new Int32Array(cells + 1);
+    const cellOf = new Int32Array(members.length);
+    for (let k = 0; k < members.length; k++) {
+      const it = items[members[k] as number] as TourHunk;
+      const c = this.cellIndex(it.x, it.y);
+      cellOf[k] = c;
+      counts[c + 1] = (counts[c + 1] as number) + 1;
+    }
+    for (let c = 0; c < cells; c++)
+      counts[c + 1] = (counts[c + 1] as number) + (counts[c] as number);
+    this.cellStart = counts;
+    const fill = counts.slice(0, cells);
+    this.cellItems = new Int32Array(members.length);
+    for (let k = 0; k < members.length; k++) {
+      const c = cellOf[k] as number;
+      this.cellItems[fill[c] as number] = k;
+      fill[c] = (fill[c] as number) + 1;
+    }
+    this.cellAlive = new Int32Array(cells);
+    this.alive = new Uint8Array(members.length);
+    this.remaining = 0;
+  }
+
+  private cellX(x: number): number {
+    const c = Math.floor((x - this.minX) / this.cw);
+    return c >= 0 ? (c >= this.gw ? this.gw - 1 : c) : 0;
+  }
+
+  private cellY(y: number): number {
+    const c = Math.floor((y - this.minY) / this.ch);
+    return c >= 0 ? (c >= this.gh ? this.gh - 1 : c) : 0;
+  }
+
+  private cellIndex(x: number, y: number): number {
+    return this.cellY(y) * this.gw + this.cellX(x);
+  }
+
+  get size(): number {
+    return this.remaining;
+  }
+
+  /** Make member slot `k` (index into `members`) eligible. */
+  activate(k: number): void {
+    if (this.alive[k] === 1) return;
+    this.alive[k] = 1;
+    this.remaining++;
+    const it = this.items[this.members[k] as number] as TourHunk;
+    const c = this.cellIndex(it.x, it.y);
+    this.cellAlive[c] = (this.cellAlive[c] as number) + 1;
+  }
+
+  /** Remove eligible member slot `k`. */
+  take(k: number): void {
+    if (this.alive[k] === 0) return;
+    this.alive[k] = 0;
+    this.remaining--;
+    const it = this.items[this.members[k] as number] as TourHunk;
+    const c = this.cellIndex(it.x, it.y);
+    this.cellAlive[c] = (this.cellAlive[c] as number) - 1;
+  }
+
+  /** Eligible member slot with the largest size (ties → lowest order), or -1. O(members). */
+  largest(): number {
+    let best = -1;
+    for (let k = 0; k < this.members.length; k++) {
+      if (this.alive[k] === 0) continue;
+      const a = this.items[this.members[k] as number] as TourHunk;
+      const b = best < 0 ? undefined : (this.items[this.members[best] as number] as TourHunk);
+      if (b === undefined || a.size > b.size || (a.size === b.size && a.order < b.order)) best = k;
+    }
+    return best;
+  }
+
+  /** Member slot of the nearest remaining point (ties → lowest order), or -1. */
+  nearest(x: number, y: number): number {
+    if (this.remaining === 0) return -1;
+    const qx = this.cellX(x);
+    const qy = this.cellY(y);
+    const minCell = Math.min(this.cw, this.ch);
+    let best = -1;
+    let bestD2 = Number.POSITIVE_INFINITY;
+    let bestOrder = Number.POSITIVE_INFINITY;
+    const maxRing = Math.max(this.gw, this.gh);
+    for (let ring = 0; ring <= maxRing; ring++) {
+      const x0 = qx - ring;
+      const x1 = qx + ring;
+      const y0 = qy - ring;
+      const y1 = qy + ring;
+      for (let cy = y0; cy <= y1; cy++) {
+        if (cy < 0 || cy >= this.gh) continue;
+        const edgeRow = cy === y0 || cy === y1;
+        for (let cx = x0; cx <= x1; cx += edgeRow ? 1 : x1 - x0 || 1) {
+          if (cx < 0 || cx >= this.gw) continue;
+          const c = cy * this.gw + cx;
+          if (this.cellAlive[c] === 0) continue;
+          for (let p = this.cellStart[c] as number; p < (this.cellStart[c + 1] as number); p++) {
+            const k = this.cellItems[p] as number;
+            if (this.alive[k] === 0) continue;
+            const it = this.items[this.members[k] as number] as TourHunk;
+            const dx = it.x - x;
+            const dy = it.y - y;
+            const d2 = dx * dx + dy * dy;
+            if (better(d2, it.order, bestD2, bestOrder)) {
+              best = k;
+              bestD2 = d2;
+              bestOrder = it.order;
+            }
+          }
+        }
+      }
+      // Every cell at ring ≥ ring + 1 is at least ring·minCell away; strict so ties keep searching.
+      const bound = ring * minCell;
+      if (best >= 0 && bestD2 < bound * bound) break;
+    }
+    return best;
+  }
+}
+
+/**
+ * Order hunks as a short spatial tour (docs/algorithms.md §10) that respects `requires`:
+ *
+ * - Only *ready* hunks (every requirement already placed) are candidates.
+ * - Phase is a preference, not a barrier: the candidates are the ready hunks of the earliest
+ *   phase that has any, so a hunk may follow a later-phase hunk it requires.
+ * - The very first hunk is the largest candidate; every next one is the candidate nearest the
+ *   previous anchor (greedy nearest neighbour), which also starts each phase near where the
+ *   previous one ended.
+ * - Ties are broken by the default `order`. Unknown or self requirements are ignored; a cycle
+ *   (never produced by core) is broken by releasing its lowest-`order` hunk.
+ *
+ * Returns indices into `hunks`. ~O((H + R) √H) worst case, near-linear typically.
+ */
+export function tourOrder(hunks: readonly TourHunk[]): number[] {
+  const H = hunks.length;
+  const phaseRank = (p: ReplayPhase): number => PHASE_ORDER.indexOf(p);
+  // Per-phase grids over all hunks of the phase; slots activate once their hunk is ready.
+  const members: number[][] = PHASE_ORDER.map(() => []);
+  for (let i = 0; i < H; i++) members[phaseRank((hunks[i] as TourHunk).phase)]?.push(i);
+  for (const m of members)
+    m.sort((a, b) => (hunks[a] as TourHunk).order - (hunks[b] as TourHunk).order);
+  const grids = members.map((m) => new NearestGrid(hunks, m));
+  const slotOf = new Int32Array(H);
+  for (const m of members) for (let k = 0; k < m.length; k++) slotOf[m[k] as number] = k;
+  // Pending requirement counts and reverse edges (deduplicated).
+  const pending = new Int32Array(H);
+  const dependents: number[][] = Array.from({ length: H }, () => []);
+  for (let i = 0; i < H; i++) {
+    for (const r of new Set((hunks[i] as TourHunk).requires)) {
+      if (r === i || r < 0 || r >= H) continue;
+      pending[i] = (pending[i] as number) + 1;
+      (dependents[r] as number[]).push(i);
+    }
+  }
+  const placed = new Uint8Array(H);
+  const activate = (i: number): void => {
+    grids[phaseRank((hunks[i] as TourHunk).phase)]?.activate(slotOf[i] as number);
+  };
+  for (let i = 0; i < H; i++) if (pending[i] === 0) activate(i);
+
+  const result: number[] = [];
+  let last: TourHunk | null = null;
+  while (result.length < H) {
+    let g = grids.findIndex((grid) => grid.size > 0);
+    if (g < 0) {
+      // A requirement cycle: release the unplaced hunk with the lowest default order.
+      let pick = -1;
+      for (let i = 0; i < H; i++) {
+        if (placed[i] === 1) continue;
+        if (pick < 0 || (hunks[i] as TourHunk).order < (hunks[pick] as TourHunk).order) pick = i;
+      }
+      pending[pick] = 0;
+      activate(pick);
+      g = phaseRank((hunks[pick] as TourHunk).phase);
+    }
+    const grid = grids[g] as NearestGrid;
+    const slot = last === null ? grid.largest() : grid.nearest(last.x, last.y);
+    grid.take(slot);
+    const idx = (members[g] as number[])[slot] as number;
+    placed[idx] = 1;
+    result.push(idx);
+    last = hunks[idx] as TourHunk;
+    for (const d of dependents[idx] as number[]) {
+      if (placed[d] === 1) continue;
+      pending[d] = (pending[d] as number) - 1;
+      if (pending[d] === 0) activate(d);
+    }
+  }
+  return result;
+}
+
+/**
+ * Chapter of each hunk (hunks in a requirement-respecting order, e.g. the tour) for `chapters`
+ * mode: one chapter per phase present, in replay order; a hunk that requires a hunk of a later
+ * chapter moves to that chapter (the earliest chapter not before any requirement). O(H + R).
+ */
+export function chapterPlan(
+  hunks: readonly { readonly phase: ReplayPhase; readonly requires: readonly number[] }[],
+): Int32Array {
+  const present = PHASE_ORDER.filter((p) => hunks.some((h) => h.phase === p));
+  const chapter = new Int32Array(hunks.length);
+  for (let i = 0; i < hunks.length; i++) {
+    const h = hunks[i] as (typeof hunks)[number];
+    let c = present.indexOf(h.phase);
+    for (const r of h.requires) {
+      // Requirements placed earlier in the order have their chapter already.
+      if (r >= 0 && r < i) c = Math.max(c, chapter[r] as number);
+    }
+    chapter[i] = c;
+  }
+  return chapter;
+}
+
+const KIND_FACTOR: Readonly<Record<HunkKind, number>> = {
+  add: 0.85,
+  remove: 0.85,
+  modify: 0.8,
+  relations: 0.95,
+  merge: 1.3,
+  split: 1.3,
+};
+
+/** Times are rounded to µs so results do not depend on last-ulp differences between engines. */
+const roundMs = (ms: number): number => Math.round(ms * 1000) / 1000;
+
+/** Play time of one hunk in `hunks` mode: `pace · kindFactor · clamp(√size, 1, 2.2)`. */
+export function hunkDuration(kind: HunkKind, size: number, pace: number): number {
+  return roundMs(pace * KIND_FACTOR[kind] * Math.min(2.2, Math.max(1, Math.sqrt(size))));
+}
+
+/** Length of a chapter of `n` hunks in `chapters` mode: `pace · clamp(1.2 + log₂ n, 1.2, 4)`. */
+export function chapterDuration(n: number, pace: number): number {
+  return roundMs(pace * Math.min(4, Math.max(1.2, 1.2 + Math.log2(Math.max(1, n)))));
+}
+
+export interface TimelineHunk {
+  readonly kind: HunkKind;
+  readonly phase: ReplayPhase;
+  readonly size: number;
+  readonly bounds: Rect;
+  /** Indices (into the same array) of hunks that must play first. */
+  readonly requires: readonly number[];
+}
+
+function chapterBounds(hunks: readonly TimelineHunk[], members: readonly number[]): Rect {
+  const b = new BoundsBuilder();
+  for (const h of members) b.addRect((hunks[h] as TimelineHunk).bounds);
+  return b.rect();
+}
+
+export const timelineMode = (hunkCount: number, chapterThreshold: number): Timeline['mode'] =>
+  hunkCount > chapterThreshold ? 'chapters' : 'hunks';
+
+/**
+ * Replay schedule for hunks already in play order (docs/algorithms.md §10). The order must
+ * respect `requires` (the tour does; in `chapters` mode, stable-sort the tour by `chapterPlan`).
+ *
+ * - `hunks` mode (≤ `chapterThreshold` hunks): one hunk at a time, 160 ms apart, so every hunk
+ *   starts after its requirements end. Chapters are the consecutive runs of one phase, reported
+ *   for scrubber grouping.
+ * - `chapters` mode: one chapter per `chapterPlan` value, of length
+ *   `pace · clamp(1.2 + log₂ n, 1.2, 4)`; its hunks play together, staggered in play order over
+ *   `35% · (n − 1) / n` of the chapter, so a hunk requiring another of its chapter starts later.
+ *   A chapter's `phase` is the phase it was planned for. Chapters are 160 ms apart.
+ */
+export function buildTimeline(
+  hunks: readonly TimelineHunk[],
+  pace: number,
+  chapterThreshold: number,
+): Timeline {
+  const mode = timelineMode(hunks.length, chapterThreshold);
+  const windows: TimelineWindow[] = [];
+  const chapters: TimelineChapter[] = [];
+  const plan = mode === 'chapters' ? chapterPlan(hunks) : null;
+  const present = PHASE_ORDER.filter((p) => hunks.some((h) => h.phase === p));
+  // Runs of consecutive hunks sharing a phase (hunks mode) or a planned chapter (chapters mode).
+  const runs: { key: number; phase: ReplayPhase; members: number[] }[] = [];
+  for (let h = 0; h < hunks.length; h++) {
+    const hunk = hunks[h] as TimelineHunk;
+    const key = plan === null ? PHASE_ORDER.indexOf(hunk.phase) : (plan[h] as number);
+    const run = runs[runs.length - 1];
+    if (run !== undefined && run.key === key) run.members.push(h);
+    else {
+      const phase = plan === null ? hunk.phase : (present[key] ?? hunk.phase);
+      runs.push({ key, phase, members: [h] });
+    }
+  }
+  let cursor = 0;
+  for (let c = 0; c < runs.length; c++) {
+    const { phase, members: run } = runs[c] as (typeof runs)[number];
+    if (c > 0) cursor = roundMs(cursor + TIMELINE.gap);
+    const start = cursor;
+    if (mode === 'hunks') {
+      for (let k = 0; k < run.length; k++) {
+        if (k > 0) cursor = roundMs(cursor + TIMELINE.gap);
+        const h = hunks[run[k] as number] as TimelineHunk;
+        const end = roundMs(cursor + hunkDuration(h.kind, h.size, pace));
+        windows.push({ hunk: run[k] as number, start: cursor, end, chapter: c });
+        cursor = end;
+      }
+    } else {
+      const n = run.length;
+      const length = chapterDuration(n, pace);
+      const span = (TIMELINE.maxStagger * length * (n - 1)) / n;
+      const step = n > 1 ? span / (n - 1) : 0;
+      const windowLength = length - span;
+      for (let k = 0; k < n; k++) {
+        const ws = roundMs(start + k * step);
+        windows.push({
+          hunk: run[k] as number,
+          start: ws,
+          end: roundMs(ws + windowLength),
+          chapter: c,
+        });
+      }
+      cursor = roundMs(start + length);
+    }
+    chapters.push({ phase, start, end: cursor, hunks: run, bounds: chapterBounds(hunks, run) });
+  }
+  return { duration: cursor, windows, chapters, mode };
+}