@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/ui/playback.js

@@ -4,23 +4,44 @@
 
 /**
  * @typedef {{ op: " ", text: string } | { op: "+" | "-", text: string, change: number }} HunkLine
- * @typedef {{ kind: "hunk", id: string, path: string, body: HunkLine[] }
- *   | { kind: "file" | "mode", id: string, path: string }} Unit
+ * @typedef {{ mode: string, blob: string }} Entry
+ * @typedef {{ kind: "hunk", id: string, path: string, oldStart?: number, body: HunkLine[] }
+ *   | { kind: "file", id: string, path: string, reason: string, before: Entry | null, after: Entry | null }
+ *   | { kind: "mode", id: string, path: string, from: string, to: string }} Unit
  * @typedef {{ kind: "rest" } | { kind: "lines", changes: number[] }} Selection
- * @typedef {{ unit: string, select: Selection, narration?: string }} Ref
- * @typedef {{ index: number, message: string, narration?: string, refs: Ref[] }} Commit
- * @typedef {{ kind: "commit", commit: number, say: string }
- *   | { kind: "unit", commit: number, unit: string, say: string | null }
- *   | { kind: "line", commit: number, unit: string, line: number, change: number, op: "+" | "-" }} Step
- * @typedef {"hidden" | "shown" | "gone"} LineState
+ * @typedef {{ unit: string, select: Selection, narration?: string, diagram?: string }} Ref
+ * @typedef {{ index: number, message: string, narration?: string, diagram?: string, refs: Ref[] }} Commit
+ *
+ * A beat is one thing the reviewer attends to: a commit's intro, one chunk of its change, or the
+ * held finished commit. lines are indices into the hunk body, removals the subset that are "-"
+ * lines; f_ and m_ chunks have neither. added counts the non-blank "+" lines.
+ * @typedef {{ kind: "intro", commit: number, message: string, narration: string | null }
+ *   | { kind: "chunk", commit: number, unit: string, lines: number[], narration: string | null,
+ *       removals: number[], label: string, added: number }
+ *   | { kind: "outro", commit: number, next: string | null }} Beat
+ *
+ * A step is a timed slice of a beat. "say" shows the narration card and speaks it, lasting ms or
+ * until speech ends plus tail, whichever is later. "show" reveals a chunk's lines. "rest" is the
+ * pause after a chunk, "hold" the finished commit.
+ * @typedef {{ kind: "say", beat: number, text: string, ms: number, tail: number }
+ *   | { kind: "show" | "rest" | "hold", beat: number, ms: number }} Step
+ *
+ * @typedef {"hidden" | "shown" | "struck"} LineState
  * @typedef {{ name: string, lang: string, default: boolean }} VoiceInfo
  */
 
-export const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2, 3];
+export const SPEEDS = [0.75, 1, 1.5, 2];
 
-const LINES_PER_SECOND = 4;
-const COMMIT_BEAT_MS = 700;
-const UNIT_BEAT_MS = 350;
+/** Context lines that may sit between two change lines of one chunk. */
+const MAX_GAP = 3;
+/** A longer run is cut at the first blank or closing line once it has this many lines. */
+const SPLIT_AFTER = 8;
+const MAX_CHUNK = 12;
+
+const BEAT_MS = 600;
+const HOLD_MS = 2500;
+const INTRO_TAIL_MS = 500;
+const MAX_SPEECH_RATE = 1.5;
 const WORDS_PER_SECOND = 2.5;
 
 /**
@@ -32,63 +53,248 @@ export function lineKey(unit, line) {
   return `${unit}:${line}`;
 }
 
+/** @param {string} message */
+export function titleOf(message) {
+  return message.split("\n")[0] ?? "";
+}
+
+/** @param {string} text */
+function wordCount(text) {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
 /**
- * What is spoken when a commit starts: its narration, else its title.
- * @param {Commit} commit
+ * Milliseconds to read a text at 1x: about 200 words a minute plus a second to settle.
+ * @param {string} text
  */
-export function commitNarration(commit) {
-  const narration = commit.narration?.trim();
-  if (narration) return narration;
-  return commit.message.split("\n")[0] ?? "";
+export function readMs(text) {
+  return Math.max(2000, 1000 + 300 * wordCount(text));
 }
 
 /**
- * Every step of the playback in order: a commit begins, each of its units begins, and each of
- * the commit's own change lines appears (+) or fades out (-) in hunk order.
+ * Milliseconds to take in a chunk at 1x. New code costs more to read than removed code.
+ * @param {number} added non-blank added lines
+ * @param {number} removed
+ */
+export function codeMs(added, removed) {
+  return Math.min(9000, Math.max(2000, 1500 + 400 * added + 200 * removed));
+}
+
+/** @param {string | undefined} text */
+function present(text) {
+  const trimmed = text?.trim();
+  return trimmed ? trimmed : null;
+}
+
+/** @param {readonly Commit[]} commits */
+export function hasNarration(commits) {
+  return commits.some(
+    (c) => present(c.narration) !== null || c.refs.some((r) => present(r.narration) !== null),
+  );
+}
+
+/** @param {HunkLine | undefined} line */
+function textOf(line) {
+  return (line?.text ?? "").replace(/\r?\n$/, "");
+}
+
+/**
+ * Runs of a ref's own change lines with at most MAX_GAP other lines between them, each cut to at
+ * most MAX_CHUNK lines, preferably right after a blank or closing line.
+ * @param {readonly HunkLine[]} body
+ * @param {ReadonlySet<number>} mine
+ */
+function runsOf(body, mine) {
+  /** @type {number[][]} */
+  const runs = [];
+  let gap = Number.POSITIVE_INFINITY;
+  body.forEach((line, i) => {
+    if (line.op === " " || !mine.has(line.change)) {
+      gap += 1;
+      return;
+    }
+    const last = runs.at(-1);
+    if (last !== undefined && gap <= MAX_GAP) last.push(i);
+    else runs.push([i]);
+    gap = 0;
+  });
+  return runs.flatMap((run) => {
+    /** @type {number[][]} */
+    const pieces = [];
+    let rest = run;
+    while (rest.length > MAX_CHUNK) {
+      const found = rest.findIndex(
+        (i, k) => k >= SPLIT_AFTER && k < MAX_CHUNK && /^\s*[}\])]*[;,]?\s*$/.test(textOf(body[i])),
+      );
+      const cut = found === -1 ? MAX_CHUNK : found + 1;
+      pieces.push(rest.slice(0, cut));
+      rest = rest.slice(cut);
+    }
+    if (rest.length > 0) pieces.push(rest);
+    return pieces;
+  });
+}
+
+const DECLARATION =
+  /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|def|fn|func|interface|struct|enum|impl|trait|module)\s+([A-Za-z_$][\w$]*)/;
+
+/**
+ * The function or class a hunk line sits in: the nearest declaration at or above it. Lines removed in the hunk are skipped; they no longer exist at the tip.
+ * @param {readonly HunkLine[]} body
+ * @param {number} last
+ */
+export function scopeOf(body, last) {
+  for (let i = last; i >= 0; i -= 1) {
+    const line = body[i];
+    if (line === undefined || line.op === "-") continue;
+    const name = DECLARATION.exec(textOf(line))?.[1];
+    if (name !== undefined) return name;
+  }
+  return null;
+}
+
+/** @param {number} n @param {string} word */
+function count(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+/**
+ * @param {string} path
+ * @param {number} added
+ * @param {number} removed
+ * @param {string | null} name
+ */
+function hunkLabel(path, added, removed, name) {
+  const what =
+    removed === 0
+      ? `adds ${count(added, "line")}`
+      : added === 0
+        ? `removes ${count(removed, "line")}`
+        : `adds ${count(added, "line")}, removes ${removed}`;
+  return `${path} · ${what}${name === null ? "" : ` in ${name}`}`;
+}
+
+/** @param {Exclude<Unit, { kind: "hunk" }>} unit */
+function wholeLabel(unit) {
+  if (unit.kind === "mode") return `${unit.path} · mode ${unit.from} → ${unit.to}`;
+  const change = unit.before === null ? "added" : unit.after === null ? "deleted" : "changed";
+  return `${unit.path} · ${unit.reason} file ${change}`;
+}
+
+/**
+ * The beats of the whole plan: per commit an intro, one chunk per run of its own change lines
+ * (one per whole-file or mode unit), and an outro. A unit's narration goes on its first chunk.
  * @param {readonly Commit[]} commits
  * @param {readonly Unit[]} units
- * @returns {Step[]}
+ * @returns {Beat[]}
  */
 export function buildScript(commits, units) {
   const byId = new Map(units.map((u) => [u.id, u]));
-  /** @type {Step[]} */
-  const steps = [];
-  for (const commit of commits) {
-    steps.push({ kind: "commit", commit: commit.index, say: commitNarration(commit) });
+  /** @type {Beat[]} */
+  const beats = [];
+  commits.forEach((commit, k) => {
+    beats.push({
+      kind: "intro",
+      commit: commit.index,
+      message: commit.message,
+      narration: present(commit.narration),
+    });
     for (const ref of commit.refs) {
       const unit = byId.get(ref.unit);
       if (unit === undefined) continue;
-      const say = ref.narration?.trim() || null;
-      steps.push({ kind: "unit", commit: commit.index, unit: unit.id, say });
-      if (unit.kind !== "hunk" || ref.select.kind !== "lines") continue;
-      const mine = new Set(ref.select.changes);
-      unit.body.forEach((line, i) => {
-        if (line.op === " " || !mine.has(line.change)) return;
-        steps.push({
-          kind: "line",
+      const narration = present(ref.narration);
+      if (unit.kind !== "hunk") {
+        beats.push({
+          kind: "chunk",
+          commit: commit.index,
+          unit: unit.id,
+          lines: [],
+          removals: [],
+          narration,
+          label: wholeLabel(unit),
+          added: 0,
+        });
+        continue;
+      }
+      const mine = new Set(
+        ref.select.kind === "lines"
+          ? ref.select.changes
+          : unit.body.flatMap((l) => (l.op === " " ? [] : [l.change])),
+      );
+      runsOf(unit.body, mine).forEach((lines, n) => {
+        const additions = lines.filter((i) => unit.body[i]?.op === "+");
+        const removals = lines.filter((i) => unit.body[i]?.op === "-");
+        const name = scopeOf(unit.body, lines.at(-1) ?? 0);
+        beats.push({
+          kind: "chunk",
           commit: commit.index,
           unit: unit.id,
-          line: i,
-          change: line.change,
-          op: line.op,
+          lines,
+          removals,
+          narration: n === 0 ? narration : null,
+          label: hunkLabel(unit.path, additions.length, removals.length, name),
+          added: additions.filter((i) => textOf(unit.body[i]).trim() !== "").length,
         });
       });
     }
-  }
-  return steps;
+    const next = commits[k + 1];
+    beats.push({
+      kind: "outro",
+      commit: commit.index,
+      next: next === undefined ? null : titleOf(next.message),
+    });
+  });
+  return beats;
 }
 
 /**
- * How long to rest after a step at the given speed. Lines arrive a few per second; removals
- * take half as long because nothing new needs reading.
- * @param {Step} step
+ * The timed steps of the beats at a speed, which divides every dwell, beat and hold. A commit
+ * without narration speaks its title and stays up long enough to read its whole message.
+ * @param {readonly Beat[]} beats
  * @param {number} speed
+ * @returns {Step[]}
+ */
+export function schedule(beats, speed) {
+  /** @type {(ms: number) => number} */
+  const at = (ms) => Math.round(ms / speed);
+  return beats.flatMap((beat, i) => {
+    if (beat.kind === "intro") {
+      const text = beat.narration ?? titleOf(beat.message);
+      const ms = at(readMs(beat.narration ?? beat.message));
+      return [{ kind: "say", beat: i, text, ms, tail: at(INTRO_TAIL_MS) }];
+    }
+    if (beat.kind === "outro") return [{ kind: "hold", beat: i, ms: at(HOLD_MS) }];
+    /** @type {Step[]} */
+    const steps = [];
+    if (beat.narration !== null) {
+      steps.push({
+        kind: "say",
+        beat: i,
+        text: beat.narration,
+        ms: at(readMs(beat.narration)),
+        tail: 0,
+      });
+    }
+    steps.push({ kind: "show", beat: i, ms: at(codeMs(beat.added, beat.removals.length)) });
+    steps.push({ kind: "rest", beat: i, ms: at(BEAT_MS) });
+    return steps;
+  });
+}
+
+/**
+ * Silent playing time of the steps, the floor of what playback takes with speech on.
+ * @param {readonly Step[]} steps
  */
-export function stepDelay(step, speed) {
-  if (step.kind === "commit") return COMMIT_BEAT_MS / speed;
-  if (step.kind === "unit") return UNIT_BEAT_MS / speed;
-  const line = 1000 / (LINES_PER_SECOND * speed);
-  return step.op === "+" ? line : line / 2;
+export function duration(steps) {
+  return steps.reduce((sum, s) => sum + s.ms, 0);
+}
+
+/**
+ * Synthetic voices are hard to follow above 1.5x, so speech caps there while dwells keep scaling.
+ * @param {number} speed
+ */
+export function speechRate(speed) {
+  return Math.min(speed, MAX_SPEECH_RATE);
 }
 
 /**
@@ -98,53 +304,251 @@ export function stepDelay(step, speed) {
  * @param {number} speed
  */
 export function speechTimeout(text, speed) {
-  const words = text.split(/\s+/).filter(Boolean).length;
-  return (2 * 1000 * words) / (WORDS_PER_SECOND * speed) + 2000;
+  return (2 * 1000 * wordCount(text)) / (WORDS_PER_SECOND * speechRate(speed)) + 2000;
 }
 
 /**
- * The first step of a commit, clamped to the script. Seeking past the end lands on the end.
- * @param {readonly Step[]} script
- * @param {number} commit
+ * The beat on screen at a step position; past the last step that is beats.length, the end.
+ * @param {readonly Step[]} steps
+ * @param {number} position
  */
-export function commitStart(script, commit) {
-  const at = script.findIndex((s) => s.kind === "commit" && s.commit === commit);
-  if (at !== -1) return at;
-  return commit < 0 ? 0 : script.length;
+export function beatAt(steps, position) {
+  const step = steps[position];
+  if (step !== undefined) return step.beat;
+  return (steps.at(-1)?.beat ?? -1) + 1;
 }
 
 /**
- * The commit on screen at a position: the one whose step was performed last.
- * @param {readonly Step[]} script
- * @param {number} position
+ * The first step of a beat, clamped to the steps. A beat past the end lands on the end.
+ * @param {readonly Step[]} steps
+ * @param {number} beat
+ */
+export function beatStart(steps, beat) {
+  if (beat < 0) return 0;
+  const at = steps.findIndex((s) => s.beat === beat);
+  return at === -1 ? steps.length : at;
+}
+
+/**
+ * The commit a beat belongs to; the end belongs to the last commit.
+ * @param {readonly Beat[]} beats
+ * @param {number} beat
+ */
+export function commitOf(beats, beat) {
+  return (beats[Math.min(beat, beats.length - 1)] ?? beats.at(-1))?.commit ?? 0;
+}
+
+/**
+ * The intro beat of a commit, clamped: before the first is 0, after the last is the end.
+ * @param {readonly Beat[]} beats
+ * @param {number} commit
  */
-export function commitAt(script, position) {
-  return script[Math.max(0, Math.min(position, script.length) - 1)]?.commit ?? 0;
+export function introOf(beats, commit) {
+  if (commit < 0) return 0;
+  const at = beats.findIndex((b) => b.kind === "intro" && b.commit === commit);
+  return at === -1 ? beats.length : at;
 }
 
 /**
- * How each change line of a commit looks after `position` steps, and which line was written
- * last. Added lines are hidden until typed; removed lines stay shown until their step.
- * @param {readonly Step[]} script
+ * How each change line of a commit looks at a step position. Lines are hidden until their chunk
+ * shows them; removals then stay as struck lines. Chunks not yet shown, the current one during
+ * its narration included, report a placeholder at their first line with their line count.
+ * current is the chunk beat on screen, or null during the intro and outro.
+ * @param {readonly Beat[]} beats
+ * @param {readonly Step[]} steps
  * @param {number} position
  * @param {number} commit
- * @returns {{ states: Map<string, LineState>, current: string | null }}
+ * @returns {{ states: Map<string, LineState>, upcoming: Map<string, number>, current: number | null }}
  */
-export function lineStates(script, position, commit) {
+export function lineStates(beats, steps, position, commit) {
   /** @type {Map<string, LineState>} */
   const states = new Map();
-  /** @type {string | null} */
-  let current = null;
-  script.forEach((step, i) => {
-    if (step.kind !== "line" || step.commit !== commit) return;
-    const key = lineKey(step.unit, step.line);
-    const done = i < position;
-    if (step.op === "+") states.set(key, done ? "shown" : "hidden");
-    else states.set(key, done ? "gone" : "shown");
-    if (done) current = key;
+  /** @type {Map<string, number>} */
+  const upcoming = new Map();
+  const now = beatAt(steps, position);
+  beats.forEach((beat, i) => {
+    if (beat.kind !== "chunk" || beat.commit !== commit || beat.lines.length === 0) return;
+    const show = steps.findIndex((s) => s.kind === "show" && s.beat === i);
+    const shown = position >= steps.length || (show !== -1 && show <= position);
+    const first = beat.lines[0];
+    if (!shown && first !== undefined) upcoming.set(lineKey(beat.unit, first), beat.lines.length);
+    const removals = new Set(beat.removals);
+    for (const line of beat.lines) {
+      const look = !shown ? "hidden" : removals.has(line) ? "struck" : "shown";
+      states.set(lineKey(beat.unit, line), look);
+    }
+  });
+  const beat = beats[now];
+  const current = beat?.kind === "chunk" && beat.commit === commit ? now : null;
+  return { states, upcoming, current };
+}
+
+/**
+ * How a hunk reads in one commit. The commit's own lines are the change. Lines earlier commits
+ * added are now part of the file and read as context; lines they removed are gone. Lines later
+ * commits remove are still there as context, and lines later commits add fold into one row per
+ * run and owner.
+ * @param {readonly HunkLine[]} body
+ * @param {readonly (number | undefined)[]} owners owning commit per change index
+ * @param {number} commit
+ * @returns {({ kind: "line", line: number, mine: boolean } | { kind: "fold", lines: number[], commit: number })[]}
+ */
+export function rowsOf(body, owners, commit) {
+  /** @type {ReturnType<typeof rowsOf>} */
+  const rows = [];
+  body.forEach((line, i) => {
+    const owner = line.op === " " ? undefined : owners[line.change];
+    if (line.op === " " || owner === undefined || owner === commit) {
+      rows.push({ kind: "line", line: i, mine: owner === commit });
+      return;
+    }
+    const later = owner > commit;
+    if (line.op === "-" ? later : !later) {
+      rows.push({ kind: "line", line: i, mine: false });
+      return;
+    }
+    if (line.op === "-") return;
+    const last = rows.at(-1);
+    if (last?.kind === "fold" && last.commit === owner) last.lines.push(i);
+    else rows.push({ kind: "fold", lines: [i], commit: owner });
   });
-  if (commitAt(script, position) !== commit) current = null;
-  return { states, current };
+  return rows;
+}
+
+/**
+ * The diagram beside the code: while a chunk of a unit with a diagram plays, that unit's; else
+ * the commit's; while browsing a commit without one, its first unit's. null when none applies.
+ * @param {Commit | undefined} commit
+ * @param {Beat | undefined} beat the beat on screen, undefined while browsing
+ * @returns {{ source: string, unit: string | null } | null}
+ */
+export function diagramAt(commit, beat) {
+  if (commit === undefined) return null;
+  const refs = commit.refs.filter((r) => present(r.diagram) !== null);
+  const playing = beat?.kind === "chunk" ? refs.find((r) => r.unit === beat.unit) : undefined;
+  const own = present(commit.diagram);
+  const ref = playing ?? (own === null && beat === undefined ? refs[0] : undefined);
+  if (ref?.diagram !== undefined) return { source: ref.diagram, unit: ref.unit };
+  return own === null ? null : { source: own, unit: null };
+}
+
+/** @param {readonly Commit[]} commits */
+export function hasDiagrams(commits) {
+  return commits.some(
+    (c) => present(c.diagram) !== null || c.refs.some((r) => present(r.diagram) !== null),
+  );
+}
+
+/**
+ * File line numbers of every hunk line, 1-based: old in the base file, new in the branch tip. A
+ * removed line has no new number and an added line no old one. A hunk's tip start is its base
+ * start shifted by the lines earlier hunks of the same file add or remove.
+ * @param {readonly Unit[]} units
+ * @returns {Map<string, { old: number | null, new: number | null }[]>}
+ */
+export function lineNumbers(units) {
+  /** @type {Map<string, { old: number | null, new: number | null }[]>} */
+  const numbers = new Map();
+  const hunks = units.flatMap((u) => (u.kind === "hunk" ? [u] : []));
+  const sorted = [...hunks].sort((a, b) => (a.oldStart ?? 0) - (b.oldStart ?? 0));
+  /** @type {Map<string, number>} */
+  const shift = new Map();
+  for (const hunk of sorted) {
+    const start = hunk.oldStart ?? 0;
+    let oldLine = start + 1;
+    let newLine = start + 1 + (shift.get(hunk.path) ?? 0);
+    numbers.set(
+      hunk.id,
+      hunk.body.map((line) => {
+        if (line.op === "-") return { old: oldLine++, new: null };
+        if (line.op === "+") return { old: null, new: newLine++ };
+        return { old: oldLine++, new: newLine++ };
+      }),
+    );
+    const delta = hunk.body.reduce((d, l) => d + (l.op === "+" ? 1 : l.op === "-" ? -1 : 0), 0);
+    shift.set(hunk.path, (shift.get(hunk.path) ?? 0) + delta);
+  }
+  return numbers;
+}
+
+/**
+ * How a comment names the lines it is on: tip line numbers, with removed lines by their old
+ * number, runs collapsed. "line 4", "lines 4-5", "lines 4-5, old 3".
+ * @param {readonly HunkLine[]} body
+ * @param {readonly { old: number | null, new: number | null }[]} numbers
+ * @param {readonly number[]} changes
+ */
+export function describeLines(body, numbers, changes) {
+  const picked = new Set(changes);
+  /** @type {{ side: "new" | "old", n: number }[]} */
+  const marks = [];
+  body.forEach((line, i) => {
+    if (line.op === " " || !picked.has(line.change)) return;
+    const side = line.op === "+" ? "new" : "old";
+    const n = numbers[i]?.[side];
+    if (n !== null && n !== undefined) marks.push({ side, n });
+  });
+  /** @param {"new" | "old"} side */
+  const ranges = (side) => {
+    const ns = marks.filter((m) => m.side === side).map((m) => m.n);
+    /** @type {string[]} */
+    const parts = [];
+    ns.forEach((n, i) => {
+      if (i > 0 && n === (ns[i - 1] ?? 0) + 1) {
+        const last = parts.pop() ?? "";
+        parts.push(`${last.split("-")[0]}-${n}`);
+      } else parts.push(String(n));
+    });
+    return parts;
+  };
+  const added = ranges("new");
+  const removed = ranges("old");
+  const many = marks.length > 1;
+  const text = [
+    ...(added.length > 0 ? [`${many ? "lines" : "line"} ${added.join(", ")}`] : []),
+    ...(removed.length > 0
+      ? [`${added.length > 0 ? "old" : many ? "old lines" : "old line"} ${removed.join(", ")}`]
+      : []),
+  ];
+  return text.join(", ");
+}
+
+/**
+ * One progress segment per commit, weighted by its chunk count, filled by the share of its
+ * beats already behind the current one.
+ * @param {readonly Beat[]} beats
+ * @param {number} beat
+ * @returns {{ commit: number, weight: number, filled: number }[]}
+ */
+export function progress(beats, beat) {
+  /** @type {Map<number, { chunks: number, total: number, behind: number }>} */
+  const tally = new Map();
+  beats.forEach((b, i) => {
+    const t = tally.get(b.commit) ?? { chunks: 0, total: 0, behind: 0 };
+    tally.set(b.commit, {
+      chunks: t.chunks + (b.kind === "chunk" ? 1 : 0),
+      total: t.total + 1,
+      behind: t.behind + (i < beat ? 1 : 0),
+    });
+  });
+  return [...tally].map(([commit, t]) => ({
+    commit,
+    weight: Math.max(1, t.chunks),
+    filled: t.behind / t.total,
+  }));
+}
+
+/**
+ * Which chunk of its commit a beat is, 1-based, or null for an intro, outro or the end.
+ * @param {readonly Beat[]} beats
+ * @param {number} beat
+ * @returns {{ index: number, count: number } | null}
+ */
+export function chunkOf(beats, beat) {
+  const here = beats[beat];
+  if (here?.kind !== "chunk") return null;
+  const mine = beats.flatMap((b, i) => (b.kind === "chunk" && b.commit === here.commit ? [i] : []));
+  return { index: mine.indexOf(beat) + 1, count: mine.length };
 }
 
 /**