@cueloop/client 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/view-diff.ts

@@ -1,5 +1,5 @@
 /**
- * Diff artifact projection (#18 slice 3): flatten @pierre/diffs' parsed
+ * Diff artifact projection: flatten @pierre/diffs' parsed
  * patch model into render rows. Line-anchored annotations use the same
  * quote-primary anchors as plans: quote = the line content, prefix/suffix =
  * the neighbor lines - so the whole anchor/feedback pipeline is shared.
@@ -7,10 +7,10 @@
 
 import { parsePatchFiles, type FileDiffMetadata } from "@pierre/diffs";
 
-export type DiffRowType = "file" | "hunk" | "ctx" | "add" | "del";
+export type DiffRowKind = "file" | "hunk" | "ctx" | "add" | "del";
 
 export interface DiffRow {
-  t: DiffRowType;
+  kind: DiffRowKind;
   text: string;
   file: string;
   oldLine?: number;
@@ -22,35 +22,35 @@ export function diffRows(patchText: string): DiffRow[] {
   const patches = parsePatchFiles(patchText);
   for (const patch of patches) {
     for (const file of patch.files) {
-      rows.push({ t: "file", text: fileLabel(file), file: file.name });
+      rows.push({ kind: "file", text: fileLabel(file), file: file.name });
       for (const hunk of file.hunks) {
-        rows.push({ t: "hunk", text: hunk.hunkSpecs ?? "@@", file: file.name });
+        rows.push({ kind: "hunk", text: hunk.hunkSpecs ?? "@@", file: file.name });
         let oldLine = hunk.deletionStart;
         let newLine = hunk.additionStart;
-        for (const seg of hunk.hunkContent) {
-          if (seg.type === "context") {
-            for (let i = 0; i < seg.lines; i++) {
+        for (const segment of hunk.hunkContent) {
+          if (segment.type === "context") {
+            for (let i = 0; i < segment.lines; i++) {
               rows.push({
-                t: "ctx",
-                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                kind: "ctx",
+                text: file.additionLines[segment.additionLineIndex + i] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
                 newLine: newLine++,
               });
             }
           } else {
-            for (let i = 0; i < seg.deletions; i++) {
+            for (let i = 0; i < segment.deletions; i++) {
               rows.push({
-                t: "del",
-                text: file.deletionLines[seg.deletionLineIndex + i] ?? "",
+                kind: "del",
+                text: file.deletionLines[segment.deletionLineIndex + i] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
               });
             }
-            for (let i = 0; i < seg.additions; i++) {
+            for (let i = 0; i < segment.additions; i++) {
               rows.push({
-                t: "add",
-                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                kind: "add",
+                text: file.additionLines[segment.additionLineIndex + i] ?? "",
                 file: file.name,
                 newLine: newLine++,
               });
@@ -68,14 +68,14 @@ function fileLabel(file: FileDiffMetadata): string {
 }
 
 /** Quote-primary anchor for a diff row: neighbors as context selectors. */
-export function diffRowAnchor(rows: DiffRow[], idx: number): { quote: string; prefix: string; suffix: string } {
-  const row = rows[idx]!;
-  const prev = rows[idx - 1];
-  const next = rows[idx + 1];
+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.t === "ctx" || prev.t === "add" || prev.t === "del") ? prev.text.slice(-24) : "",
-    suffix: next && (next.t === "ctx" || next.t === "add" || next.t === "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

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "bun:test";
+import {
+  blockRuns,
+  buildDisplay,
+  displayText,
+  marksByDisplay,
+  nextWorkBlock,
+  overlayMarks,
+  renderedOffsetFor,
+  spanKey,
+  startSpan,
+  workRangeForRendered,
+} from "./view-plan";
+import { cutBlock, parseBlocks, restoreBlock, restoreLine, type Annotation } from "@cueloop/schema";
+
+const BASE = `# Plan
+
+## Context
+
+The daemon persists sessions to disk atomically.
+
+- first item
+- second item
+`;
+
+describe("buildDisplay reconciliation", () => {
+  test("no working copy: everything is same", () => {
+    const display = buildDisplay(BASE);
+    expect(display.every((block) => block.type === "same")).toBe(true);
+  });
+
+  test("reworded block pairs as mod (similar)", () => {
+    const working = BASE.replace("persists sessions to disk", "writes sessions to disk");
+    const display = buildDisplay(BASE, working);
+    const mod = display.find((block) => block.type === "mod")!;
+    expect(mod.base!.text).toContain("persists");
+    expect(mod.work!.text).toContain("writes");
+  });
+
+  test("unrelated cut + insert do NOT merge into a mod", () => {
+    const working = BASE.replace("- second item\n", "") + "\nA totally new closing note.\n";
+    const display = buildDisplay(BASE, working);
+    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);
+  });
+
+  test("ordered list items get running numbers", () => {
+    const display = buildDisplay("1. one\n2. two\n3. three\n");
+    expect(display.map((block) => block.orderedItemNumber)).toEqual([1, 2, 3]);
+  });
+});
+
+describe("blockRuns + overlayMarks", () => {
+  test("mod blocks emit word-diff runs that reconstruct both sides", () => {
+    const block = buildDisplay("plain old text here\n", "plain new text here\n")[0]!;
+    const runs = blockRuns(block, true);
+    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");
+  });
+
+  test("marks bind to working-text offsets and skip del runs", () => {
+    const block = buildDisplay("old words linger\n", "new words linger\n")[0]!;
+    const runs = blockRuns(block, true);
+    const marked = overlayMarks(runs, [{ start: 4, end: 9, role: "mark-comment" }]); // "words"
+    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);
+  });
+
+  test("marks never override ins emphasis", () => {
+    const block = buildDisplay("keep\n", "keep added\n")[0]!;
+    const runs = overlayMarks(blockRuns(block, true), [{ start: 0, end: 10, role: "mark-comment" }]);
+    expect(runs.some((run) => run.role === "ins")).toBe(true);
+  });
+});
+
+describe("marksByDisplay", () => {
+  test("annotations resolve into display coordinates", () => {
+    const working = BASE.replace("first item", "first item edited beyond recognition of it");
+    const display = buildDisplay(BASE, working);
+    const ann: Annotation = {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "atomically", prefix: "to disk ", suffix: "." },
+      body: "define atomically",
+      createdAt: "",
+    };
+    const map = marksByDisplay([ann], display);
+    const [displayIndex, marks] = [...map.entries()][0]!;
+    expect(displayText(display[displayIndex]!)).toContain("atomically");
+    expect(marks[0]!.annotationId).toBe("a1");
+  });
+
+  test("orphaned annotations produce no marks", () => {
+    const display = buildDisplay(BASE);
+    const ann: Annotation = {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "text that is gone", prefix: "", suffix: "" },
+      body: "",
+      createdAt: "",
+    };
+    expect(marksByDisplay([ann], display).size).toBe(0);
+  });
+});
+
+describe("rendered/work offset mapping", () => {
+  test("plain blocks map 1:1 in both directions", () => {
+    const block = buildDisplay("alpha beta gamma\n")[0]!;
+    const runs = blockRuns(block, true);
+    expect(renderedOffsetFor(runs, 6)).toBe(6);
+    expect(workRangeForRendered(runs, 6, 10)).toEqual({ start: 6, end: 10 });
+  });
+
+  test("inline del runs shift rendered offsets in word-diffed blocks", () => {
+    // rendered: "old new words linger" - "old " is a del run without offsets
+    const block = buildDisplay("old words linger\n", "new words linger\n")[0]!;
+    const runs = blockRuns(block, true);
+    const workText = displayText(block);
+    const wordsAt = workText.indexOf("words");
+    const rendered = renderedOffsetFor(runs, wordsAt)!;
+    const renderedText = runs.map((run) => run.text).join("");
+    expect(renderedText.slice(rendered, rendered + "words".length)).toBe("words");
+    // reading a rendered selection over "words" recovers the work range
+    expect(workRangeForRendered(runs, rendered, rendered + "words".length)).toEqual({
+      start: wordsAt,
+      end: wordsAt + "words".length,
+    });
+  });
+
+  test("a rendered selection spanning a del run keeps only positioned text", () => {
+    const block = buildDisplay("old words\n", "new words\n")[0]!;
+    const runs = blockRuns(block, true);
+    const renderedText = runs.map((run) => run.text).join("");
+    // select everything rendered: the work range is the whole work text
+    const range = workRangeForRendered(runs, 0, renderedText.length)!;
+    expect(displayText(block).slice(range.start, range.end)).toBe(displayText(block));
+  });
+
+  test("offsets outside any positioned run map to null", () => {
+    const runs = blockRuns(buildDisplay("short\n")[0]!, true);
+    expect(renderedOffsetFor(runs, 99)).toBeNull();
+    expect(workRangeForRendered(runs, 90, 99)).toBeNull();
+  });
+});
+
+describe("span mode", () => {
+  const text = "one two three four";
+  test("v selects the first word; l grows; w slides; $ to end", () => {
+    let span = startSpan(0, text)!;
+    expect(text.slice(span.start, span.end)).toBe("one");
+    span = spanKey(span, "l", text);
+    expect(text.slice(span.start, span.end)).toBe("one two");
+    span = spanKey(span, "w", text);
+    expect(text.slice(span.start, span.end)).toBe("two three");
+    span = spanKey(span, "$", text);
+    expect(text.slice(span.start, span.end)).toBe("two three four");
+  });
+});
+
+describe("cut / restore round-trip", () => {
+  test("cut removes the block lines; restore puts them back", () => {
+    const blocks = parseBlocks(BASE);
+    const listItem = blocks.find((candidate) => candidate.text === "second item")!;
+    const cut = cutBlock(BASE, listItem);
+    expect(cut).not.toContain("second item");
+    const display = buildDisplay(BASE, cut);
+    const deletedIndex = display.findIndex((block) => block.type === "del");
+    const line = restoreLine(nextWorkBlock(display, deletedIndex), cut.split("\n").length);
+    // undefined = the working copy round-tripped back to the submitted revision
+    const restored = restoreBlock(BASE, cut, listItem, line);
+    expect(restored).toBeUndefined();
+    expect(buildDisplay(BASE, restored).every((block) => block.type === "same")).toBe(true);
+  });
+});

package/src/view-plan.ts

@@ -0,0 +1,362 @@
+/**
+ * The plan projection pipeline: parse → display blocks (base vs working
+ * copy reconciled) → styled runs. Pure functions - the TUI renders the runs
+ * (the native text primitive wraps them), tests assert on them directly.
+ * One planning layer: rendering, navigation, and selection all derive from
+ * this module; the rendered/work offset mappings keep the native selection
+ * addressable over word-diffed blocks.
+ */
+
+import {
+  lcsDiff,
+  parseBlocks,
+  resolveAnchor,
+  wordDiff,
+  type Annotation,
+  type Block,
+} from "@cueloop/schema";
+
+// ── display model ─────────────────────────────
+
+export type DisplayType = "same" | "mod" | "del" | "add";
+
+export interface DisplayBlock {
+  type: DisplayType;
+  kind: Block["kind"];
+  /** Block in the working copy (absent for del). */
+  work?: Block;
+  /** Block in the submitted revision (absent for add). */
+  base?: Block;
+  orderedItemNumber?: number;
+}
+
+export function displayText(block: DisplayBlock): string {
+  return (block.work ?? block.base)!.text;
+}
+
+/** Word-overlap similarity gate: an unrelated cut + insert must not merge. */
+function similar(baseBlock: Block, workBlock: Block): boolean {
+  if (baseBlock.kind !== workBlock.kind) return false;
+  const words = (text: string) => new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
+  const baseWords = words(baseBlock.text);
+  const workWords = words(workBlock.text);
+  let intersection = 0;
+  for (const word of baseWords) if (workWords.has(word)) intersection++;
+  const union = baseWords.size + workWords.size - intersection;
+  return union === 0 ? true : intersection / union >= 0.3;
+}
+
+/** Reconcile base blocks vs working blocks into the display list. */
+export function buildDisplay(baseContent: string, workingContent?: string): DisplayBlock[] {
+  const baseBlocks = parseBlocks(baseContent);
+  if (workingContent === undefined) {
+    const display: DisplayBlock[] = baseBlocks.map((block) => ({
+      type: "same",
+      kind: block.kind,
+      work: block,
+      base: block,
+    }));
+    numberOrderedListItems(display);
+    return display;
+  }
+  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 display: DisplayBlock[] = [];
+  let opIndex = 0;
+  while (opIndex < ops.length) {
+    const op = ops[opIndex]!;
+    if (op.kind === "ctx") {
+      display.push({ type: "same", kind: op.newValue!.kind, work: op.newValue, base: op.oldValue });
+      opIndex++;
+      continue;
+    }
+    const deletedBlocks: Block[] = [];
+    const addedBlocks: Block[] = [];
+    while (opIndex < ops.length && ops[opIndex]!.kind !== "ctx") {
+      const changeOp = ops[opIndex]!;
+      if (changeOp.kind === "del") deletedBlocks.push(changeOp.oldValue!);
+      else addedBlocks.push(changeOp.newValue!);
+      opIndex++;
+    }
+    let deletedIndex = 0;
+    let addedIndex = 0;
+    while (deletedIndex < deletedBlocks.length && addedIndex < addedBlocks.length) {
+      if (similar(deletedBlocks[deletedIndex]!, addedBlocks[addedIndex]!)) {
+        display.push({
+          type: "mod",
+          kind: addedBlocks[addedIndex]!.kind,
+          base: deletedBlocks[deletedIndex]!,
+          work: addedBlocks[addedIndex]!,
+        });
+        deletedIndex++;
+        addedIndex++;
+      } else if (deletedBlocks.length - deletedIndex >= addedBlocks.length - addedIndex) {
+        display.push({ type: "del", kind: deletedBlocks[deletedIndex]!.kind, base: deletedBlocks[deletedIndex]! });
+        deletedIndex++;
+      } else {
+        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++]! });
+    }
+    while (addedIndex < addedBlocks.length) {
+      display.push({ type: "add", kind: addedBlocks[addedIndex]!.kind, work: addedBlocks[addedIndex++]! });
+    }
+  }
+  numberOrderedListItems(display);
+  return display;
+}
+
+function numberOrderedListItems(display: DisplayBlock[]): void {
+  let runLength = 0;
+  for (const block of display) {
+    if (block.kind === "oli") block.orderedItemNumber = ++runLength;
+    else runLength = 0;
+  }
+}
+
+// ── marks (annotation highlights + keyboard span) ──
+
+export type RunRole =
+  | "plain"
+  | "ins"
+  | "del"
+  | "mark-comment"
+  | "mark-suggestion"
+  | "kspan"
+  | "mark-focus";
+
+export interface StyleRun {
+  text: string;
+  role: RunRole;
+  /** Offset of this run in the block's working text; null for del runs. */
+  start: number | null;
+  annotationId?: string;
+}
+
+export interface Mark {
+  start: number;
+  end: number;
+  role: RunRole;
+  annotationId?: string;
+}
+
+/**
+ * Resolve annotations against the working blocks and group marks per display
+ * index. Working blocks are the blocks of (workingCopy ?? artifact) - the
+ * same list buildDisplay derived work entries from.
+ */
+export function marksByDisplay(
+  annotations: Annotation[],
+  display: DisplayBlock[],
+  focusedId?: string,
+): Map<number, Mark[]> {
+  // block list in "work space": display entries that carry a work block, in order
+  const workEntries = display
+    .map((block, displayIndex) => ({ block, displayIndex }))
+    .filter((entry) => entry.block.work !== undefined);
+  const workBlocks = workEntries.map((entry) => entry.block.work!);
+  const marksByIndex = new Map<number, Mark[]>();
+  for (const annotation of annotations) {
+    const resolved = resolveAnchor(annotation.anchor, workBlocks);
+    if (!resolved) continue;
+    const entry = workEntries[resolved.blockIndex];
+    if (!entry) continue;
+    const marks = marksByIndex.get(entry.displayIndex) ?? [];
+    marks.push({
+      start: resolved.start,
+      end: resolved.end,
+      role:
+        annotation.id === focusedId
+          ? "mark-focus"
+          : annotation.kind === "suggestion"
+            ? "mark-suggestion"
+            : "mark-comment",
+      annotationId: annotation.id,
+    });
+    marksByIndex.set(entry.displayIndex, marks);
+  }
+  return marksByIndex;
+}
+
+/** 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 runs: StyleRun[] = [];
+    let workOffset = 0;
+    for (const op of ops) {
+      if (op.kind === "del") {
+        runs.push({ text: op.oldValue!, role: "del", start: null });
+      } else {
+        runs.push({ text: op.newValue!, role: op.kind === "add" ? "ins" : "plain", start: workOffset });
+        workOffset += op.newValue!.length;
+      }
+    }
+    return runs;
+  }
+  return [{ text: displayText(block), role: "plain", start: 0 }];
+}
+
+/** Split runs at mark boundaries; marks only bind to runs with offsets. */
+export function overlayMarks(runs: StyleRun[], marks: Mark[]): StyleRun[] {
+  if (!marks.length) return runs;
+  const splitRuns: StyleRun[] = [];
+  for (const run of runs) {
+    if (run.start === null) {
+      splitRuns.push(run);
+      continue;
+    }
+    const bounds = new Set<number>([0, run.text.length]);
+    for (const mark of marks) {
+      const boundStart = Math.max(0, mark.start - run.start);
+      const boundEnd = Math.min(run.text.length, mark.end - run.start);
+      if (boundStart < boundEnd) {
+        bounds.add(boundStart);
+        bounds.add(boundEnd);
+      }
+    }
+    const runStart = run.start;
+    const boundaries = [...bounds].sort((left, right) => left - right);
+    for (let boundaryIndex = 0; boundaryIndex < boundaries.length - 1; boundaryIndex++) {
+      const sliceStart = boundaries[boundaryIndex]!;
+      const sliceEnd = boundaries[boundaryIndex + 1]!;
+      if (sliceStart >= sliceEnd) continue;
+      const absoluteStart = runStart + sliceStart;
+      const mark = marks.find(
+        (candidate) => candidate.start <= absoluteStart && runStart + sliceEnd <= candidate.end,
+      );
+      splitRuns.push({
+        text: run.text.slice(sliceStart, sliceEnd),
+        // a mark never overrides ins/del emphasis; it rides on plain text
+        role: mark && run.role === "plain" ? mark.role : run.role,
+        start: absoluteStart,
+        annotationId: mark?.annotationId ?? run.annotationId,
+      });
+    }
+  }
+  return splitRuns;
+}
+
+/**
+ * Rendered-text offset of a work-text offset within a block's runs. The
+ * rendered text is every run's text in order (inline del runs included);
+ * only positioned runs carry work offsets. Drives the renderer's native
+ * selection from keyboard span offsets - the quote-anchor path depends on
+ * this mapping staying exact.
+ */
+export function renderedOffsetFor(runs: StyleRun[], workOffset: number): number | null {
+  let rendered = 0;
+  for (const run of runs) {
+    if (run.start !== null && workOffset >= run.start && workOffset < run.start + run.text.length) {
+      return rendered + (workOffset - run.start);
+    }
+    rendered += run.text.length;
+  }
+  return null;
+}
+
+/**
+ * Work-text range covered by a rendered-text selection [start, end). Del runs
+ * and other unpositioned text inside the selection contribute nothing; the
+ * result is the tightest work range whose text the selection touched.
+ */
+export function workRangeForRendered(
+  runs: StyleRun[],
+  renderedStart: number,
+  renderedEnd: number,
+): { start: number; end: number } | null {
+  let rendered = 0;
+  let range: { start: number; end: number } | null = null;
+  for (const run of runs) {
+    const runRenderedStart = rendered;
+    const runRenderedEnd = rendered + run.text.length;
+    rendered = runRenderedEnd;
+    if (run.start === null) continue;
+    const overlapStart = Math.max(renderedStart, runRenderedStart);
+    const overlapEnd = Math.min(renderedEnd, runRenderedEnd);
+    if (overlapEnd <= overlapStart) continue;
+    const workStart = run.start + (overlapStart - runRenderedStart);
+    const workEnd = run.start + (overlapEnd - runRenderedStart);
+    if (!range) range = { start: workStart, end: workEnd };
+    else {
+      range.start = Math.min(range.start, workStart);
+      range.end = Math.max(range.end, workEnd);
+    }
+  }
+  return range;
+}
+
+/** Line delta between two revision contents, for the sheet-header summary. */
+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;
+  for (const op of ops) {
+    if (op.kind === "add") added++;
+    else if (op.kind === "del") removed++;
+  }
+  return { added, removed };
+}
+
+// ── keyboard span mode ────────────────────────
+
+export interface SpanState {
+  displayIndex: number;
+  wordIndex: number;
+  wordEnd: number;
+  start: number;
+  end: number;
+}
+
+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]);
+  return ranges;
+}
+
+export function startSpan(displayIndex: number, text: string): SpanState | null {
+  const words = wordRanges(text);
+  if (!words.length) return null;
+  return { displayIndex, wordIndex: 0, wordEnd: 0, start: words[0]![0], end: words[0]![1] };
+}
+
+export function spanKey(span: SpanState, key: string, text: string): SpanState {
+  const words = wordRanges(text);
+  const nextSpan = { ...span };
+  const width = nextSpan.wordEnd - nextSpan.wordIndex;
+  if (key === "l") nextSpan.wordEnd = Math.min(words.length - 1, nextSpan.wordEnd + 1);
+  else if (key === "h") nextSpan.wordEnd = Math.max(nextSpan.wordIndex, nextSpan.wordEnd - 1);
+  else if (key === "w") {
+    const slidTo = Math.min(words.length - 1 - width, nextSpan.wordIndex + 1);
+    nextSpan.wordIndex = slidTo;
+    nextSpan.wordEnd = slidTo + width;
+  } else if (key === "b") {
+    const slidTo = Math.max(0, nextSpan.wordIndex - 1);
+    nextSpan.wordIndex = slidTo;
+    nextSpan.wordEnd = slidTo + width;
+  } else if (key === "$") nextSpan.wordEnd = words.length - 1;
+  else if (key === "0") {
+    nextSpan.wordEnd = width;
+    nextSpan.wordIndex = 0;
+  } else return span;
+  nextSpan.start = words[nextSpan.wordIndex]![0];
+  nextSpan.end = words[nextSpan.wordEnd]![1];
+  return nextSpan;
+}
+
+// ── working-copy block operations ─────────────
+
+/** The next work block after a display index (a del block re-enters before it). */
+export function nextWorkBlock(display: DisplayBlock[], displayIndex: number): Block | undefined {
+  for (let candidateIndex = displayIndex + 1; candidateIndex < display.length; candidateIndex++) {
+    const workBlock = display[candidateIndex]!.work;
+    if (workBlock) return workBlock;
+  }
+  return undefined;
+}