@cueloop/client 0.1.0-alpha.32 → 0.1.0-alpha.34

package/src/test-support.ts

@@ -61,53 +61,127 @@ export async function typeText(setup: TestRendererSetup, text: string): Promise<
   await settle(setup);
 }
 
-const WAIT_DEADLINE_MS = 30_000;
+// Below the 60s per-test budget so a genuinely stuck wait throws its frame
+// error (useful) before bun's bare "timed out" fires. Generous because a
+// contended CI runner starves the render loop and daemon round-trips.
+const WAIT_DEADLINE_MS = 45_000;
+
+/** One macrotask turn: hands the event loop back so the in-process daemon can
+ *  read its socket and apply the write before the next poll. Tight render-pass
+ *  bursts starve that read on a contended CI runner - the round-trip then never
+ *  lands and the wait hangs the whole budget. */
+function yieldEventLoop(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 2));
+}
+
+/** Log a still-waiting line at most this often, so only genuinely slow (i.e.
+ *  flaking) waits are noisy; fast waits stay silent. */
+const PROGRESS_LOG_MS = 4000;
+
+/** The last render frame's tail, so a progress line shows what is on screen. */
+function frameTail(frame: string, rows = 6): string {
+  return frame.split("\n").slice(-rows).join("\n");
+}
 
 /**
- * waitForFrame gives up as soon as the renderer is idle, but external timers
- * (the parser's bare-ESC window, daemon IO, spawned editors) settle on the
- * event loop while nothing is scheduled. Between attempts, one real
- * event-loop turn plus a render pass lets those land; the deadline bounds
- * the whole wait.
+ * Poll gently: one render pass, one frame check, one macrotask yield. No
+ * multi-pass bursts, so the daemon (same event loop) always gets a turn to
+ * process IO between checks. The deadline bounds the whole wait. Slow waits log
+ * progress (poll count + frame-change count) so a CI stall shows whether the
+ * render froze or the content simply never arrived.
  */
 async function waitForFramePredicate(
   setup: TestRendererSetup,
   predicate: (frame: string) => boolean,
+  label: string,
 ): Promise<string> {
   allowEventLoopUpdates();
-  const deadline = Date.now() + WAIT_DEADLINE_MS;
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
   for (;;) {
-    try {
-      return await setup.waitForFrame(predicate, { maxPasses: 50 });
-    } catch (error) {
-      if (Date.now() > deadline) throw error;
-      await new Promise((resolve) => setTimeout(resolve, 1));
-      await setup.renderOnce();
+    await setup.renderOnce();
+    const frame = setup.captureCharFrame();
+    polls++;
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
     }
+    if (predicate(frame)) return frame;
+    const now = Date.now();
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+      throw new Error(
+        `waitFor ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitFor] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes\n${frameTail(frame)}`,
+      );
+    }
+    await yieldEventLoop();
   }
 }
 
 /** Wait until a state predicate holds (daemon round-trips included). */
-export async function waitForState(setup: TestRendererSetup, predicate: () => boolean): Promise<void> {
+export async function waitForState(
+  setup: TestRendererSetup,
+  predicate: () => boolean,
+  label = "state",
+): Promise<void> {
   allowEventLoopUpdates();
-  const deadline = Date.now() + WAIT_DEADLINE_MS;
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
   for (;;) {
-    try {
-      return await setup.waitFor(predicate, { maxPasses: 50 });
-    } catch (error) {
-      if (Date.now() > deadline) throw error;
-      await new Promise((resolve) => setTimeout(resolve, 1));
-      await setup.renderOnce();
+    if (predicate()) return;
+    await setup.renderOnce();
+    const frame = setup.captureCharFrame();
+    polls++;
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
+    }
+    if (predicate()) return;
+    const now = Date.now();
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+      throw new Error(
+        `waitForState ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitForState] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes`,
+      );
     }
+    await yieldEventLoop();
   }
 }
 
 /** Wait until the frame contains the needle (daemon round-trips included). */
 export async function waitForText(setup: TestRendererSetup, needle: string): Promise<string> {
-  return waitForFramePredicate(setup, (frame) => frame.includes(needle));
+  return waitForFramePredicate(
+    setup,
+    (frame) => frame.includes(needle),
+    `text ${JSON.stringify(needle)}`,
+  );
 }
 
 /** Wait until the frame no longer contains the needle. */
 export async function waitForTextGone(setup: TestRendererSetup, needle: string): Promise<string> {
-  return waitForFramePredicate(setup, (frame) => !frame.includes(needle));
+  return waitForFramePredicate(
+    setup,
+    (frame) => !frame.includes(needle),
+    `text-gone ${JSON.stringify(needle)}`,
+  );
 }

package/src/theme-presets.ts

@@ -0,0 +1,168 @@
+/**
+ * Named theme presets selectable from Settings and `[ui] theme`. The branded
+ * "cueloop" default keeps the transparent terminal-through look; each of the
+ * well-known palettes paints its own opaque background so it reads exactly like
+ * the published theme. Every preset fills the full Theme token contract, so a
+ * `[theme]` per-token override still layers cleanly on top of the chosen base.
+ *
+ * Each palette maps its first-party spec onto cueloop's semantic slots. Where a
+ * palette has no dedicated green (Rosé Pine), additions use its positive accent
+ * by that palette's own convention.
+ */
+
+import { DARK, type Theme } from "./theme";
+
+/** Selectable theme name; the persisted `[ui] theme` value and cycle key. */
+export type ThemeName =
+  | "cueloop"
+  | "rose-pine-moon"
+  | "catppuccin-mocha"
+  | "tokyo-night"
+  | "gruvbox-dark"
+  | "nord";
+
+/** The branded default; the base every layered config starts from. */
+export const DEFAULT_THEME_NAME: ThemeName = "cueloop";
+
+/** Rosé Pine Moon - rosepinetheme.com. Foam stands in for additions (no green in the palette). */
+const ROSE_PINE_MOON: Theme = {
+  background: "#232136",
+  panel: "#232136",
+  elevated: "#2a273f",
+  border: "#44415a",
+  text: "#e0def4",
+  textMuted: "#908caa",
+  textDim: "#6e6a86",
+  accent: "#ea9a97",
+  accentInk: "#232136",
+  green: "#9ccfd8",
+  red: "#eb6f92",
+  blue: "#3e8fb0",
+  cursorBackground: "#382a2f",
+  markCommentBackground: "#382a37",
+  insertedForeground: "#9ccfd8",
+  deletedForeground: "#eb6f92",
+  backdrop: "transparent",
+};
+
+/** Catppuccin Mocha - catppuccin.com. Mauve is the signature accent. */
+const CATPPUCCIN_MOCHA: Theme = {
+  background: "#1e1e2e",
+  panel: "#1e1e2e",
+  elevated: "#313244",
+  border: "#45475a",
+  text: "#cdd6f4",
+  textMuted: "#a6adc8",
+  textDim: "#6c7086",
+  accent: "#cba6f7",
+  accentInk: "#1e1e2e",
+  green: "#a6e3a1",
+  red: "#f38ba8",
+  blue: "#89b4fa",
+  cursorBackground: "#2e2740",
+  markCommentBackground: "#33222b",
+  insertedForeground: "#a6e3a1",
+  deletedForeground: "#f38ba8",
+  backdrop: "transparent",
+};
+
+/** Tokyo Night - the folke "night" variant. Magenta is the signature accent. */
+const TOKYO_NIGHT: Theme = {
+  background: "#1a1b26",
+  panel: "#1a1b26",
+  elevated: "#292e42",
+  border: "#3b4261",
+  text: "#c0caf5",
+  textMuted: "#a9b1d6",
+  textDim: "#565f89",
+  accent: "#bb9af7",
+  accentInk: "#1a1b26",
+  green: "#9ece6a",
+  red: "#f7768e",
+  blue: "#7aa2f7",
+  cursorBackground: "#2b2740",
+  markCommentBackground: "#2f2230",
+  insertedForeground: "#9ece6a",
+  deletedForeground: "#f7768e",
+  backdrop: "transparent",
+};
+
+/** Gruvbox Dark - morhetz/gruvbox, medium contrast. Orange is the warm signature accent. */
+const GRUVBOX_DARK: Theme = {
+  background: "#282828",
+  panel: "#282828",
+  elevated: "#3c3836",
+  border: "#504945",
+  text: "#ebdbb2",
+  textMuted: "#d5c4a1",
+  textDim: "#928374",
+  accent: "#fe8019",
+  accentInk: "#282828",
+  green: "#b8bb26",
+  red: "#fb4934",
+  blue: "#83a598",
+  cursorBackground: "#3a2f20",
+  markCommentBackground: "#3a2823",
+  insertedForeground: "#b8bb26",
+  deletedForeground: "#fb4934",
+  backdrop: "transparent",
+};
+
+/** Nord - nordtheme.com, the official 16-color spec. Frost cyan is the signature accent. */
+const NORD: Theme = {
+  background: "#2e3440",
+  panel: "#2e3440",
+  elevated: "#3b4252",
+  border: "#434c5e",
+  text: "#eceff4",
+  textMuted: "#d8dee9",
+  textDim: "#4c566a",
+  accent: "#88c0d0",
+  accentInk: "#2e3440",
+  green: "#a3be8c",
+  red: "#bf616a",
+  blue: "#81a1c1",
+  cursorBackground: "#2a3540",
+  markCommentBackground: "#3a2f33",
+  insertedForeground: "#a3be8c",
+  deletedForeground: "#bf616a",
+  backdrop: "transparent",
+};
+
+/** All selectable themes by name; "cueloop" is the branded transparent default. */
+export const THEME_PRESETS: Record<ThemeName, Theme> = {
+  cueloop: DARK,
+  "rose-pine-moon": ROSE_PINE_MOON,
+  "catppuccin-mocha": CATPPUCCIN_MOCHA,
+  "tokyo-night": TOKYO_NIGHT,
+  "gruvbox-dark": GRUVBOX_DARK,
+  nord: NORD,
+};
+
+/** Cycle order for the Settings theme row; the registry's insertion order, branded default first. */
+export const THEME_NAMES: ThemeName[] = Object.keys(THEME_PRESETS) as ThemeName[];
+
+/** Human labels for the Settings cycle row, keyed by the persisted name. */
+export const THEME_LABELS: Record<ThemeName, string> = {
+  cueloop: "cueloop",
+  "rose-pine-moon": "Rosé Pine Moon",
+  "catppuccin-mocha": "Catppuccin Mocha",
+  "tokyo-night": "Tokyo Night",
+  "gruvbox-dark": "Gruvbox Dark",
+  nord: "Nord",
+};
+
+/** Resolve a persisted theme name to its token set; unknown names fall back to the branded default. */
+export function themeForName(name: string): Theme {
+  return THEME_PRESETS[name as ThemeName] ?? DARK;
+}
+
+/** A preset with the user's `[theme]` per-token overrides layered on top - the live-switch equivalent of config load. */
+export function composeTheme(name: string, overrides: Partial<Theme>): Theme {
+  return { ...themeForName(name), ...overrides };
+}
+
+/** True when the name is a known preset (guards a persisted `[ui] theme` value). */
+export function isThemeName(name: string): name is ThemeName {
+  return name in THEME_PRESETS;
+}

package/src/theme.ts

@@ -20,7 +20,6 @@ export interface Theme {
   blue: string;
   cursorBackground: string;
   markCommentBackground: string;
-  markSuggestionBackground: string;
   insertedForeground: string;
   deletedForeground: string;
   /** Layer behind centered dialogs; transparent keeps the session visible. */
@@ -62,8 +61,7 @@ export const DARK: Theme = {
   blue: "#84a6e8",
   cursorBackground: "#33262a",
   markCommentBackground: "#3d2a2e",
-  markSuggestionBackground: "#20351f",
   insertedForeground: "#62d96b",
   deletedForeground: "#ff6b6b",
   backdrop: "transparent",
-}
+};

package/src/version.ts

@@ -0,0 +1,5 @@
+/** The published client version, read from the package manifest. */
+
+import manifest from "../package.json" with { type: "json" };
+
+export const CLIENT_VERSION: string = manifest.version;

package/src/view-diff.ts

@@ -64,18 +64,29 @@ export function diffRows(patchText: string): DiffRow[] {
 }
 
 function fileLabel(file: FileDiffMetadata): string {
-  return file.prevName && file.prevName !== file.name ? `${file.prevName} → ${file.name}` : file.name;
+  return file.prevName && file.prevName !== file.name
+    ? `${file.prevName} → ${file.name}`
+    : file.name;
 }
 
 /** Quote-primary anchor for a diff row: neighbors as context selectors. */
-export function diffRowAnchor(rows: DiffRow[], rowIndex: number): { quote: string; prefix: string; suffix: string } {
+export function diffRowAnchor(
+  rows: DiffRow[],
+  rowIndex: number,
+): { quote: string; prefix: string; suffix: string } {
   const row = rows[rowIndex]!;
   const prev = rows[rowIndex - 1];
   const next = rows[rowIndex + 1];
   return {
     quote: row.text,
-    prefix: prev && (prev.kind === "ctx" || prev.kind === "add" || prev.kind === "del") ? prev.text.slice(-24) : "",
-    suffix: next && (next.kind === "ctx" || next.kind === "add" || next.kind === "del") ? next.text.slice(0, 24) : "",
+    prefix:
+      prev && (prev.kind === "ctx" || prev.kind === "add" || prev.kind === "del")
+        ? prev.text.slice(-24)
+        : "",
+    suffix:
+      next && (next.kind === "ctx" || next.kind === "add" || next.kind === "del")
+        ? next.text.slice(0, 24)
+        : "",
   };
 }
 

package/src/view-plan.test.ts

@@ -7,6 +7,7 @@ import {
   nextWorkBlock,
   overlayMarks,
   renderedOffsetFor,
+  spanFromRange,
   spanKey,
   startSpan,
   workRangeForRendered,
@@ -53,8 +54,12 @@ describe("buildDisplay reconciliation", () => {
     const display = buildDisplay(BASE, working);
 
     // Assert
-    expect(display.some((block) => block.type === "del" && block.base!.text === "second item")).toBe(true);
-    expect(display.some((block) => block.type === "add" && block.work!.text.includes("closing note"))).toBe(true);
+    expect(
+      display.some((block) => block.type === "del" && block.base!.text === "second item"),
+    ).toBe(true);
+    expect(
+      display.some((block) => block.type === "add" && block.work!.text.includes("closing note")),
+    ).toBe(true);
     expect(display.some((block) => block.type === "mod")).toBe(false);
   });
 
@@ -76,8 +81,14 @@ describe("blockRuns + overlayMarks", () => {
     const runs = blockRuns(block, true);
 
     // Assert
-    const oldSide = runs.filter((run) => run.role !== "ins").map((run) => run.text).join("");
-    const newSide = runs.filter((run) => run.role !== "del").map((run) => run.text).join("");
+    const oldSide = runs
+      .filter((run) => run.role !== "ins")
+      .map((run) => run.text)
+      .join("");
+    const newSide = runs
+      .filter((run) => run.role !== "del")
+      .map((run) => run.text)
+      .join("");
     expect(oldSide).toBe("plain old text here");
     expect(newSide).toBe("plain new text here");
   });
@@ -91,7 +102,10 @@ describe("blockRuns + overlayMarks", () => {
     const marked = overlayMarks(runs, [{ start: 4, end: 9, role: "mark-comment" }]); // "words"
 
     // Assert
-    const markedText = marked.filter((run) => run.role === "mark-comment").map((run) => run.text).join("");
+    const markedText = marked
+      .filter((run) => run.role === "mark-comment")
+      .map((run) => run.text)
+      .join("");
     expect(markedText).toBe("words");
     // del run text untouched
     expect(marked.some((run) => run.role === "del" && run.text === "old")).toBe(true);
@@ -102,7 +116,9 @@ describe("blockRuns + overlayMarks", () => {
     const block = buildDisplay("keep\n", "keep added\n")[0]!;
 
     // Act
-    const runs = overlayMarks(blockRuns(block, true), [{ start: 0, end: 10, role: "mark-comment" }]);
+    const runs = overlayMarks(blockRuns(block, true), [
+      { start: 0, end: 10, role: "mark-comment" },
+    ]);
 
     // Assert
     expect(runs.some((run) => run.role === "ins")).toBe(true);
@@ -230,6 +246,24 @@ describe("span mode", () => {
     // Assert
     expect(text.slice(span.start, span.end)).toBe("two three four");
   });
+
+  test("spanFromRange snaps a mid-word mouse drag to whole words", () => {
+    // Arrange - a drag from inside "two" to inside "three"
+    const dragStart = text.indexOf("two") + 1;
+    const dragEnd = text.indexOf("three") + 2;
+
+    // Act
+    const span = spanFromRange(0, text, dragStart, dragEnd)!;
+
+    // Assert - snaps outward to cover both touched words, ready for w/b/l/h
+    expect(text.slice(span.start, span.end)).toBe("two three");
+    expect(spanKey(span, "l", text)).toMatchObject({ wordEnd: 3 });
+  });
+
+  test("spanFromRange returns null when the range covers no word", () => {
+    // Assert - a range past the last word has nothing to select
+    expect(spanFromRange(0, text, text.length, text.length)).toBeNull();
+  });
 });
 
 describe("cut / restore round-trip", () => {

package/src/view-plan.ts

@@ -12,10 +12,10 @@ import {
   lcsDiff,
   parseBlocks,
   resolveAnchor,
-  wordDiff,
   type Annotation,
   type Block,
 } from "@cueloop/schema";
+import { wordLevelChanges } from "./diff-intraline";
 
 // ── display model ─────────────────────────────
 
@@ -62,7 +62,11 @@ export function buildDisplay(baseContent: string, workingContent?: string): Disp
   }
   const workBlocks = parseBlocks(workingContent);
   const signature = (block: Block) => block.kind + "\0" + block.text;
-  const ops = lcsDiff(baseBlocks, workBlocks, (baseBlock, workBlock) => signature(baseBlock) === signature(workBlock));
+  const ops = lcsDiff(
+    baseBlocks,
+    workBlocks,
+    (baseBlock, workBlock) => signature(baseBlock) === signature(workBlock),
+  );
   const display: DisplayBlock[] = [];
   let opIndex = 0;
   while (opIndex < ops.length) {
@@ -93,18 +97,34 @@ export function buildDisplay(baseContent: string, workingContent?: string): Disp
         deletedIndex++;
         addedIndex++;
       } else if (deletedBlocks.length - deletedIndex >= addedBlocks.length - addedIndex) {
-        display.push({ type: "del", kind: deletedBlocks[deletedIndex]!.kind, base: deletedBlocks[deletedIndex]! });
+        display.push({
+          type: "del",
+          kind: deletedBlocks[deletedIndex]!.kind,
+          base: deletedBlocks[deletedIndex]!,
+        });
         deletedIndex++;
       } else {
-        display.push({ type: "add", kind: addedBlocks[addedIndex]!.kind, work: addedBlocks[addedIndex]! });
+        display.push({
+          type: "add",
+          kind: addedBlocks[addedIndex]!.kind,
+          work: addedBlocks[addedIndex]!,
+        });
         addedIndex++;
       }
     }
     while (deletedIndex < deletedBlocks.length) {
-      display.push({ type: "del", kind: deletedBlocks[deletedIndex]!.kind, base: deletedBlocks[deletedIndex++]! });
+      display.push({
+        type: "del",
+        kind: deletedBlocks[deletedIndex]!.kind,
+        base: deletedBlocks[deletedIndex++]!,
+      });
     }
     while (addedIndex < addedBlocks.length) {
-      display.push({ type: "add", kind: addedBlocks[addedIndex]!.kind, work: addedBlocks[addedIndex++]! });
+      display.push({
+        type: "add",
+        kind: addedBlocks[addedIndex]!.kind,
+        work: addedBlocks[addedIndex++]!,
+      });
     }
   }
   numberOrderedListItems(display);
@@ -121,14 +141,7 @@ function numberOrderedListItems(display: DisplayBlock[]): void {
 
 // ── marks (annotation highlights + keyboard span) ──
 
-export type RunRole =
-  | "plain"
-  | "ins"
-  | "del"
-  | "mark-comment"
-  | "mark-suggestion"
-  | "kspan"
-  | "mark-focus";
+export type RunRole = "plain" | "ins" | "del" | "mark-comment" | "kspan" | "mark-focus";
 
 export interface StyleRun {
   text: string;
@@ -172,12 +185,7 @@ export function marksByDisplay(
     marks.push({
       start: resolved.start,
       end: resolved.end,
-      role:
-        annotation.id === focusedId
-          ? "mark-focus"
-          : annotation.kind === "suggestion"
-            ? "mark-suggestion"
-            : "mark-comment",
+      role: annotation.id === focusedId ? "mark-focus" : "mark-comment",
       annotationId: annotation.id,
     });
     marksByIndex.set(entry.displayIndex, marks);
@@ -188,15 +196,19 @@ export function marksByDisplay(
 /** Base runs for a display block: plain text, or word-diff for mod blocks. */
 export function blockRuns(block: DisplayBlock, markup: boolean): StyleRun[] {
   if (block.type === "mod" && markup) {
-    const ops = wordDiff(block.base!.text, block.work!.text);
+    const changes = wordLevelChanges(block.base!.text, block.work!.text);
     const runs: StyleRun[] = [];
     let workOffset = 0;
-    for (const op of ops) {
-      if (op.kind === "del") {
-        runs.push({ text: op.oldValue!, role: "del", start: null });
+    for (const change of changes) {
+      if (change.kind === "removed") {
+        runs.push({ text: change.text, role: "del", start: null });
       } else {
-        runs.push({ text: op.newValue!, role: op.kind === "add" ? "ins" : "plain", start: workOffset });
-        workOffset += op.newValue!.length;
+        runs.push({
+          text: change.text,
+          role: change.kind === "added" ? "ins" : "plain",
+          start: workOffset,
+        });
+        workOffset += change.text.length;
       }
     }
     return runs;
@@ -294,7 +306,10 @@ export function workRangeForRendered(
 }
 
 /** Line delta between two revision contents, for the sheet-header summary. */
-export function revisionDelta(previousContent: string, nextContent: string): { added: number; removed: number } {
+export function revisionDelta(
+  previousContent: string,
+  nextContent: string,
+): { added: number; removed: number } {
   const ops = lcsDiff(previousContent.split("\n"), nextContent.split("\n"));
   let added = 0;
   let removed = 0;
@@ -319,7 +334,8 @@ export function wordRanges(text: string): [number, number][] {
   const ranges: [number, number][] = [];
   const wordPattern = /\S+/g;
   let match: RegExpExecArray | null;
-  while ((match = wordPattern.exec(text))) ranges.push([match.index, match.index + match[0]!.length]);
+  while ((match = wordPattern.exec(text)))
+    ranges.push([match.index, match.index + match[0]!.length]);
   return ranges;
 }
 
@@ -329,6 +345,33 @@ export function startSpan(displayIndex: number, text: string): SpanState | null
   return { displayIndex, wordIndex: 0, wordEnd: 0, start: words[0]![0], end: words[0]![1] };
 }
 
+/**
+ * Build a word-granular span from a raw char range (a mouse drag-selection),
+ * snapping to every word the range overlaps so w/b/l/h keep working after. Null
+ * when the range covers no word.
+ */
+export function spanFromRange(
+  displayIndex: number,
+  text: string,
+  start: number,
+  end: number,
+): SpanState | null {
+  const words = wordRanges(text);
+  const wordIndex = words.findIndex((word) => word[1] > start);
+  if (wordIndex === -1) return null;
+  let wordEnd = wordIndex;
+  for (let index = wordIndex; index < words.length && words[index]![0] < end; index++) {
+    wordEnd = index;
+  }
+  return {
+    displayIndex,
+    wordIndex,
+    wordEnd,
+    start: words[wordIndex]![0],
+    end: words[wordEnd]![1],
+  };
+}
+
 export function spanKey(span: SpanState, key: string, text: string): SpanState {
   const words = wordRanges(text);
   const nextSpan = { ...span };

package/src/walk.test.ts

@@ -72,7 +72,9 @@ describe("firstUnviewedIndex", () => {
   });
 
   test("all viewed resumes on the end card, not the first file", () => {
-    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts", "src/c.ts"]))).toBe(files.length);
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts", "src/c.ts"]))).toBe(
+      files.length,
+    );
   });
 });
 
@@ -93,7 +95,10 @@ describe("noteForFile", () => {
 
   test("finds the note anchored at the file path", () => {
     // Arrange
-    const annotations = [note("src/a.ts", "Renames b and adds c."), note("src/b.ts", "Swaps the line.")];
+    const annotations = [
+      note("src/a.ts", "Renames b and adds c."),
+      note("src/b.ts", "Swaps the line."),
+    ];
 
     // Assert
     expect(noteForFile(annotations, "src/b.ts")).toBe("Swaps the line.");