@cueloop/client 0.1.0-alpha.33 → 0.1.0-alpha.35

package/src/share.ts

@@ -6,7 +6,12 @@
  * Share button, so the two share exactly the same path.
  */
 
-import { DEFAULT_SHARE_HOST, DEFAULT_SHARE_PORT, SHARE_UPLOAD_USER, packSessionBlob } from "@cueloop/daemon/share-blob";
+import {
+  DEFAULT_SHARE_HOST,
+  DEFAULT_SHARE_PORT,
+  SHARE_UPLOAD_USER,
+  packSessionBlob,
+} from "@cueloop/daemon/share-blob";
 import type { Annotation, ReviewSession } from "@cueloop/schema";
 import { copyToClipboard } from "./clipboard";
 
@@ -28,9 +33,17 @@ export function shareIdFromLine(line: string): string | undefined {
 }
 
 /** Upload the session to the gateway and copy the resulting ssh line. */
-export async function publishShare(session: ReviewSession, target: ShareTarget = {}): Promise<ShareResult> {
-  const { stdout, stderr, code } = await runShareSsh("cueloop-share", packSessionBlob(session), target);
-  if (code !== 0) throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
+export async function publishShare(
+  session: ReviewSession,
+  target: ShareTarget = {},
+): Promise<ShareResult> {
+  const { stdout, stderr, code } = await runShareSsh(
+    "cueloop-share",
+    packSessionBlob(session),
+    target,
+  );
+  if (code !== 0)
+    throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
   const line = stdout.trim();
   if (!line.startsWith("ssh ")) throw new Error(`unexpected gateway reply: ${line || "(empty)"}`);
   const copied = await copyToClipboard(line);
@@ -58,17 +71,37 @@ export function collaboratorAnnotations(session: ReviewSession): Annotation[] {
  * them on their next refresh. Owner-gated at the gateway; the notes stay
  * unauthored (the planner's), unioned by id.
  */
-export async function pushShare(shareId: string, annotations: Array<Omit<Annotation, "createdAt">>, target: ShareTarget = {}): Promise<void> {
-  const { stderr, code } = await runShareSsh("cueloop-push", Buffer.from(JSON.stringify({ shareId, annotations })), target);
+export async function pushShare(
+  shareId: string,
+  annotations: Array<Omit<Annotation, "createdAt">>,
+  target: ShareTarget = {},
+): Promise<void> {
+  const { stderr, code } = await runShareSsh(
+    "cueloop-push",
+    Buffer.from(JSON.stringify({ shareId, annotations })),
+    target,
+  );
   if (code !== 0) throw new Error(`gateway push failed: ${stderr.trim() || `ssh exited ${code}`}`);
 }
 
 /** Run one `share@host:port` ssh command with `stdin`; hand back its streams and exit code. */
-async function runShareSsh(command: string, stdin: Buffer, target: ShareTarget): Promise<{ stdout: string; stderr: string; code: number }> {
+async function runShareSsh(
+  command: string,
+  stdin: Buffer,
+  target: ShareTarget,
+): Promise<{ stdout: string; stderr: string; code: number }> {
   const host = target.host ?? DEFAULT_SHARE_HOST;
   const port = target.port ?? DEFAULT_SHARE_PORT;
   const proc = Bun.spawn(
-    ["ssh", "-p", String(port), "-o", "StrictHostKeyChecking=accept-new", `${SHARE_UPLOAD_USER}@${host}`, command],
+    [
+      "ssh",
+      "-p",
+      String(port),
+      "-o",
+      "StrictHostKeyChecking=accept-new",
+      `${SHARE_UPLOAD_USER}@${host}`,
+      command,
+    ],
     { stdin, stdout: "pipe", stderr: "pipe" },
   );
   const [stdout, stderr, code] = await Promise.all([

package/src/test-support.ts

@@ -113,7 +113,7 @@ async function waitForFramePredicate(
     if (predicate(frame)) return frame;
     const now = Date.now();
     if (now > deadline) {
-      const frozen = frameChanges <= 1 ? " — render never advanced (frozen)" : "";
+      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}`,
       );
@@ -121,7 +121,7 @@ async function waitForFramePredicate(
     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)}`,
+        `[waitFor] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes\n${frameTail(frame)}`,
       );
     }
     await yieldEventLoop();
@@ -153,14 +153,16 @@ export async function waitForState(
     if (predicate()) return;
     const now = Date.now();
     if (now > deadline) {
-      const frozen = frameChanges <= 1 ? " — render never advanced (frozen)" : "";
+      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`);
+      console.error(
+        `[waitForState] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes`,
+      );
     }
     await yieldEventLoop();
   }
@@ -168,10 +170,18 @@ export async function waitForState(
 
 /** 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), `text ${JSON.stringify(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), `text-gone ${JSON.stringify(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/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.");

package/src/walk.ts

@@ -35,7 +35,10 @@ export function walkFiles(rows: DiffRow[]): WalkFile[] {
     if (row.kind === "add") file.added += 1;
     else file.removed += 1;
     if (file.preview.length < WALK_PREVIEW_ROWS) {
-      file.preview.push({ sign: row.kind === "add" ? "+" : "-", text: row.text.replace(/\n$/, "") });
+      file.preview.push({
+        sign: row.kind === "add" ? "+" : "-",
+        text: row.text.replace(/\n$/, ""),
+      });
     }
   }
   return files;
@@ -61,5 +64,7 @@ export function viewedCount(files: WalkFile[], viewedPaths: ReadonlySet<string>)
  * quote is the file path (the note contract in the shared review core).
  */
 export function noteForFile(annotations: Annotation[], path: string): string | undefined {
-  return annotations.find((annotation) => annotation.kind === "note" && annotation.anchor.quote === path)?.body;
+  return annotations.find(
+    (annotation) => annotation.kind === "note" && annotation.anchor.quote === path,
+  )?.body;
 }