@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.91

package/src/thread-selection.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isCollapsed,
+  isDoubleClick,
+  nextWordStart,
+  orderedSpan,
+  positionAt,
+  previousWordStart,
+  snapSpanToWords,
+  snapToWords,
+  spanRangeInBlock,
+  tightenSpan,
+  wordRangeAt,
+  type LineGeometry,
+} from "./thread-selection";
+
+const TEXT = "All persistence lives in a new module.";
+const BULLET = "store.ts - the store";
+// block 3 wraps onto two rows, a blank row, then bullet block 4 on one row
+const LINES: LineGeometry[] = [
+  { blockIndex: 3, start: 0, end: 21, x: 4, y: 10 },
+  { blockIndex: 3, start: 22, end: 38, x: 4, y: 11 },
+  { blockIndex: 4, start: 0, end: 20, x: 6, y: 13 },
+];
+const textLengthOf = (blockIndex: number): number =>
+  blockIndex === 3 ? TEXT.length : BULLET.length;
+
+describe("positionAt", () => {
+  test("maps a cell inside a line to the character under it", () => {
+    // Act
+    const position = positionAt(LINES, 4 + 6, 10);
+
+    // Assert: column 6 of the first line is the "r" in "persistence"
+    expect(position).toEqual({ blockIndex: 3, char: 6 });
+    expect(TEXT[6]).toBe("r");
+  });
+
+  test("past the right edge resolves to the position after the line's last char", () => {
+    // Assert
+    expect(positionAt(LINES, 90, 10)).toEqual({ blockIndex: 3, char: 21 });
+  });
+
+  test("a row without text resolves to the end of the closest line above", () => {
+    // Assert: the blank row between the blocks, and a row below everything
+    expect(positionAt(LINES, 30, 12)).toEqual({ blockIndex: 3, char: 38 });
+    expect(positionAt(LINES, 30, 40)).toEqual({ blockIndex: 4, char: 20 });
+  });
+
+  test("rows above all text resolve to the first character", () => {
+    // Assert
+    expect(positionAt(LINES, 30, 2)).toEqual({ blockIndex: 3, char: 0 });
+  });
+
+  test("a row of another block maps into that block", () => {
+    // Act
+    const position = positionAt(LINES, 6 + 3, 13);
+
+    // Assert
+    expect(position).toEqual({ blockIndex: 4, char: 3 });
+    expect(positionAt([], 5, 10)).toBeNull();
+  });
+});
+
+describe("orderedSpan and tightenSpan", () => {
+  test("a backward drag normalizes to document order", () => {
+    // Act
+    const span = orderedSpan({
+      anchor: { blockIndex: 4, char: 5 },
+      head: { blockIndex: 3, char: 6 },
+    });
+
+    // Assert
+    expect(span).toEqual({
+      start: { blockIndex: 3, char: 6 },
+      end: { blockIndex: 4, char: 5 },
+    });
+  });
+
+  test("a collapsed selection is no span", () => {
+    // Arrange
+    const selection = {
+      anchor: { blockIndex: 3, char: 6 },
+      head: { blockIndex: 3, char: 6 },
+    };
+
+    // Assert
+    expect(isCollapsed(selection)).toBe(true);
+    expect(orderedSpan(selection)).toBeNull();
+  });
+
+  test("a span opening at a block's end moves onto the next block", () => {
+    // Act: the pointer sat on the blank row above the bullet when the press landed
+    const tightened = tightenSpan(
+      {
+        start: { blockIndex: 3, char: TEXT.length },
+        end: { blockIndex: 4, char: 5 },
+      },
+      textLengthOf,
+    );
+
+    // Assert
+    expect(tightened).toEqual({
+      start: { blockIndex: 4, char: 0 },
+      end: { blockIndex: 4, char: 5 },
+    });
+  });
+
+  test("a span closing at a block's start moves back onto the previous block", () => {
+    // Act
+    const tightened = tightenSpan(
+      { start: { blockIndex: 3, char: 10 }, end: { blockIndex: 4, char: 0 } },
+      textLengthOf,
+    );
+
+    // Assert
+    expect(tightened).toEqual({
+      start: { blockIndex: 3, char: 10 },
+      end: { blockIndex: 3, char: TEXT.length },
+    });
+  });
+
+  test("a span with nothing left in it is null", () => {
+    // Assert
+    expect(
+      tightenSpan(
+        {
+          start: { blockIndex: 3, char: TEXT.length },
+          end: { blockIndex: 4, char: 0 },
+        },
+        textLengthOf,
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("spanRangeInBlock", () => {
+  const span = {
+    start: { blockIndex: 3, char: 22 },
+    end: { blockIndex: 5, char: 4 },
+  };
+
+  test("the first block runs from the start to its end, middles fully, the last to the end char", () => {
+    // Assert
+    expect(spanRangeInBlock(span, 3, TEXT.length)).toEqual({
+      start: 22,
+      end: TEXT.length,
+    });
+    expect(spanRangeInBlock(span, 4, BULLET.length)).toEqual({
+      start: 0,
+      end: BULLET.length,
+    });
+    expect(spanRangeInBlock(span, 5, 30)).toEqual({ start: 0, end: 4 });
+  });
+
+  test("blocks outside the span have no range", () => {
+    // Assert
+    expect(spanRangeInBlock(span, 2, 10)).toBeNull();
+    expect(spanRangeInBlock(span, 6, 10)).toBeNull();
+  });
+});
+
+describe("word rules", () => {
+  test("the boundary rule attributes trailing whitespace to the preceding word", () => {
+    // Assert: char 3 is the space after "All"
+    expect(wordRangeAt(TEXT, 3)).toEqual({ start: 0, end: 3 });
+  });
+
+  test("snapToWords grows a partial range to whole words on both sides", () => {
+    // Assert: "rsistence liv" -> "persistence lives"
+    expect(snapToWords(TEXT, { start: 6, end: 19 })).toEqual({
+      start: 4,
+      end: 21,
+    });
+  });
+
+  test("snapSpanToWords snaps each end of a cross-block span within its own block", () => {
+    // Act: "rsistence ... st" -> "persistence ... store.ts"
+    const snapped = snapSpanToWords(
+      { start: { blockIndex: 3, char: 6 }, end: { blockIndex: 4, char: 2 } },
+      (blockIndex) => (blockIndex === 3 ? TEXT : BULLET),
+    );
+
+    // Assert
+    expect(snapped).toEqual({
+      start: { blockIndex: 3, char: 4 },
+      end: { blockIndex: 4, char: 8 },
+    });
+  });
+
+  test("word starts step in both directions and stop at the ends", () => {
+    // Assert
+    expect(nextWordStart(TEXT, 0)).toBe(4);
+    expect(nextWordStart(TEXT, 31)).toBeNull();
+    expect(previousWordStart(TEXT, 22)).toBe(16);
+    expect(previousWordStart(TEXT, 0)).toBeNull();
+  });
+});
+
+describe("isDoubleClick", () => {
+  test("same cell within the window counts, a moved or late press does not", () => {
+    // Arrange
+    const first = { time: 1000, x: 5, y: 7 };
+
+    // Assert
+    expect(isDoubleClick(first, { time: 1300, x: 5, y: 7 })).toBe(true);
+    expect(isDoubleClick(first, { time: 1300, x: 6, y: 7 })).toBe(false);
+    expect(isDoubleClick(first, { time: 1500, x: 5, y: 7 })).toBe(false);
+    expect(isDoubleClick(null, { time: 1300, x: 5, y: 7 })).toBe(false);
+  });
+});

package/src/thread-selection.ts

@@ -0,0 +1,243 @@
+/**
+ * The thread view's text-selection model: a pure, renderer-free description
+ * of where the caret is and what is marked, plus the hit-testing that maps a
+ * pointer cell onto a character. Character-precise (partial words), spanning
+ * wrapped lines and consecutive blocks, normalized for backward drags. Word snapping
+ * happens only where the grammar asks for it: the typing anchor for a bare
+ * caret, and double-click word mode.
+ *
+ * Isolated on purpose: the interaction can be unit-tested and benchmarked
+ * without a terminal, and the view layer only wires events to it.
+ */
+
+export interface TextPosition {
+  blockIndex: number;
+  char: number;
+}
+
+/** Where one visual line of a block sits on screen, in cells. */
+export interface LineGeometry {
+  blockIndex: number;
+  /** Char range of the block's text this line shows. */
+  start: number;
+  end: number;
+  x: number;
+  y: number;
+}
+
+/** The held selection: `anchor` is where the press landed, `head` follows the pointer. */
+export interface Selection {
+  anchor: TextPosition;
+  head: TextPosition;
+}
+
+export interface CharRange {
+  start: number;
+  end: number;
+}
+
+/** An ordered stretch of text, possibly across consecutive blocks. */
+export interface TextSpan {
+  start: TextPosition;
+  end: TextPosition;
+}
+
+/** Document order: block first, then character. */
+export function comparePositions(left: TextPosition, right: TextPosition): number {
+  return left.blockIndex - right.blockIndex || left.char - right.char;
+}
+
+/** Word boundaries of a block's text. */
+export function wordRanges(text: string): CharRange[] {
+  const ranges: CharRange[] = [];
+  const matcher = /\S+/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = matcher.exec(text)) !== null) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+
+  return ranges;
+}
+
+/**
+ * The marked word for a char offset: the word containing it, or - when the
+ * caret sits in the whitespace immediately after a word - that preceding
+ * word, never the next one.
+ */
+export function wordIndexAt(text: string, char: number): number {
+  const words = wordRanges(text);
+
+  for (let index = 0; index < words.length; index++) {
+    if (char < words[index]!.start) return Math.max(0, index - 1);
+    if (char < words[index]!.end) return index;
+  }
+
+  return Math.max(0, words.length - 1);
+}
+
+/** The word range the boundary rule assigns to a char offset; null for empty text. */
+export function wordRangeAt(text: string, char: number): CharRange | null {
+  const words = wordRanges(text);
+
+  return words[wordIndexAt(text, char)] ?? null;
+}
+
+/**
+ * Map a pointer cell to a text position over every registered line. A row
+ * without text (a blank row, a card) resolves to the end of the closest line
+ * above it, rows above all text to the first character, and a cell past a
+ * line's last cell to the position after that line's last character, so a
+ * drag that runs off the right edge still selects to the line end.
+ */
+export function positionAt(lines: LineGeometry[], x: number, y: number): TextPosition | null {
+  if (lines.length === 0) return null;
+  const ordered = lines.toSorted((left, right) => left.y - right.y || left.x - right.x);
+  const onRow = ordered.find((line) => line.y === y);
+
+  if (onRow) {
+    const column = Math.max(0, Math.min(onRow.end - onRow.start, x - onRow.x));
+
+    return { blockIndex: onRow.blockIndex, char: onRow.start + column };
+  }
+  const above = ordered.findLast((line) => line.y < y);
+
+  if (above) return { blockIndex: above.blockIndex, char: above.end };
+  const first = ordered[0]!;
+
+  return { blockIndex: first.blockIndex, char: first.start };
+}
+
+/** True when nothing is held: the caret is a point, not a range. */
+export function isCollapsed(selection: Selection): boolean {
+  return comparePositions(selection.anchor, selection.head) === 0;
+}
+
+/** The selection in document order, or null when collapsed. */
+export function orderedSpan(selection: Selection): TextSpan | null {
+  if (isCollapsed(selection)) return null;
+
+  return comparePositions(selection.anchor, selection.head) < 0
+    ? { start: selection.anchor, end: selection.head }
+    : { start: selection.head, end: selection.anchor };
+}
+
+/**
+ * Pull a span's edges off block boundaries: opening at a block's end or
+ * closing at a block's start marks nothing there, so the edge moves onto the
+ * neighbouring block. Null when nothing remains.
+ */
+export function tightenSpan(
+  span: TextSpan,
+  textLengthOf: (blockIndex: number) => number,
+): TextSpan | null {
+  let { start, end } = span;
+
+  while (start.blockIndex < end.blockIndex && start.char >= textLengthOf(start.blockIndex)) {
+    start = { blockIndex: start.blockIndex + 1, char: 0 };
+  }
+  while (end.blockIndex > start.blockIndex && end.char === 0) {
+    end = {
+      blockIndex: end.blockIndex - 1,
+      char: textLengthOf(end.blockIndex - 1),
+    };
+  }
+  const clampedEnd = {
+    blockIndex: end.blockIndex,
+    char: Math.min(end.char, textLengthOf(end.blockIndex)),
+  };
+
+  return comparePositions(start, clampedEnd) < 0 ? { start, end: clampedEnd } : null;
+}
+
+/** The part of a span that falls on one block, as a char range; null when none. */
+export function spanRangeInBlock(
+  span: TextSpan,
+  blockIndex: number,
+  textLength: number,
+): CharRange | null {
+  if (blockIndex < span.start.blockIndex || blockIndex > span.end.blockIndex) return null;
+  const start = blockIndex === span.start.blockIndex ? span.start.char : 0;
+  const end = blockIndex === span.end.blockIndex ? Math.min(span.end.char, textLength) : textLength;
+
+  return end > start ? { start, end } : null;
+}
+
+/** Grow a char range outward to the word boundaries it touches (double-click word mode). */
+export function snapToWords(text: string, range: CharRange): CharRange {
+  const words = wordRanges(text);
+  const first = words.find((word) => range.start < word.end) ?? words[words.length - 1];
+  const last = words.toReversed().find((word) => range.end > word.start) ?? words[0];
+
+  if (!first || !last) return range;
+
+  return {
+    start: Math.min(first.start, range.start),
+    end: Math.max(last.end, range.end),
+  };
+}
+
+/** Snap both ends of a span to word boundaries, each within its own block. */
+export function snapSpanToWords(span: TextSpan, textOf: (blockIndex: number) => string): TextSpan {
+  if (span.start.blockIndex === span.end.blockIndex) {
+    const snapped = snapToWords(textOf(span.start.blockIndex), {
+      start: span.start.char,
+      end: span.end.char,
+    });
+
+    return {
+      start: { blockIndex: span.start.blockIndex, char: snapped.start },
+      end: { blockIndex: span.end.blockIndex, char: snapped.end },
+    };
+  }
+  const startText = textOf(span.start.blockIndex);
+  const endText = textOf(span.end.blockIndex);
+
+  return {
+    start: {
+      blockIndex: span.start.blockIndex,
+      char: snapToWords(startText, {
+        start: span.start.char,
+        end: startText.length,
+      }).start,
+    },
+    end: {
+      blockIndex: span.end.blockIndex,
+      char: snapToWords(endText, { start: 0, end: span.end.char }).end,
+    },
+  };
+}
+
+export interface ClickStamp {
+  time: number;
+  x: number;
+  y: number;
+}
+
+/** Two presses on the same cell inside this window read as a double-click. */
+export const DOUBLE_CLICK_WINDOW_MS = 400;
+
+export function isDoubleClick(previous: ClickStamp | null, current: ClickStamp): boolean {
+  return (
+    previous !== null &&
+    previous.x === current.x &&
+    previous.y === current.y &&
+    current.time - previous.time <= DOUBLE_CLICK_WINDOW_MS
+  );
+}
+
+/** Next word start after `char`, or null past the last word. */
+export function nextWordStart(text: string, char: number): number | null {
+  const next = wordRanges(text).find((word) => word.start > char);
+
+  return next ? next.start : null;
+}
+
+/** Previous word start before `char`, or null before the first word. */
+export function previousWordStart(text: string, char: number): number | null {
+  const previous = wordRanges(text)
+    .toReversed()
+    .find((word) => word.start < char);
+
+  return previous ? previous.start : null;
+}

package/src/tree-view.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import {
+  appendEntry,
+  createBranch,
+  historyFromLinear,
+  labelTip,
+  navigateTo,
+  switchBranch,
+  tipOf,
+  type SessionHistory,
+} from "@cueloop/schema";
+import { entryTarget, treeRows } from "./tree-view";
+
+const AT = "2026-09-01T10:00:00.000Z";
+const LATER = "2026-09-01T11:00:00.000Z";
+
+/** rev1 -> comment a1 on main; a branch "alt" off a1 with its own comment; main continues with rev2. */
+function forked(): SessionHistory {
+  let history = historyFromLinear({
+    id: "ses_1",
+    revisions: [{ revision: 1, content: "v1", submittedAt: AT }],
+    annotations: [],
+    message: null,
+    createdAt: AT,
+  });
+
+  history = appendEntry(history, { type: "comment", annotationId: "a1", createdAt: AT }).history;
+  history = labelTip(history, "start");
+  history = createBranch(history, "alt");
+  history = appendEntry(history, { type: "comment", annotationId: "b1", createdAt: AT }).history;
+  history = switchBranch(history, "main");
+  history = appendEntry(history, {
+    type: "revision",
+    by: "agent",
+    content: "v2",
+    createdAt: LATER,
+  }).history;
+
+  return history;
+}
+
+describe("treeRows", () => {
+  test("the current branch is the trunk; other segments indent under the entry they grew from", () => {
+    // Act
+    const rows = treeRows(forked());
+
+    // Assert: rev1, a1 (labelled, alt hangs off it), the alt comment indented, then rev2 as main's tip
+    expect(rows.map((row) => [row.depth, row.text, row.onPath])).toEqual([
+      [0, "revision 1", true],
+      [0, "comment", true],
+      [1, "comment", false],
+      [0, "revision 2", true],
+    ]);
+    expect(rows[1]!.label).toBe("start");
+    expect(rows[2]!.tips).toEqual(["alt"]);
+    expect(rows[3]!.tips).toEqual(["main"]);
+    expect(rows[3]!.isCurrentTip).toBe(true);
+  });
+
+  test("on the other branch the trunk follows it and main's continuation indents", () => {
+    // Act
+    const rows = treeRows(switchBranch(forked(), "alt"));
+
+    // Assert
+    expect(rows.map((row) => [row.depth, row.text, row.onPath])).toEqual([
+      [0, "revision 1", true],
+      [0, "comment", true],
+      [1, "revision 2", false],
+      [0, "comment", true],
+    ]);
+    expect(rows[3]!.isCurrentTip).toBe(true);
+  });
+
+  test("a branch summary reads as a return with its text", () => {
+    // Arrange
+    const history = navigateTo(forked(), forked().entries[0]!.id, { summary: "too early" });
+
+    // Act
+    const rows = treeRows(history);
+
+    // Assert: the summary hangs under rev1 as the trunk, the abandoned segment indents
+    expect(rows.find((row) => row.glyph === "↩")?.text).toBe('"too early"');
+    expect(rows.find((row) => row.glyph === "↩")?.isCurrentTip).toBe(true);
+  });
+});
+
+describe("entryTarget", () => {
+  test("the tip is here, another tip is a switch, an ancestor is a navigate on its branch", () => {
+    // Arrange
+    const history = forked();
+    const [rev1, a1, altComment, rev2] = history.entries;
+
+    // Assert
+    expect(entryTarget(history, rev2!.id)).toEqual({ kind: "here" });
+    expect(entryTarget(history, altComment!.id)).toEqual({ kind: "switch", branch: "alt" });
+    expect(entryTarget(history, a1!.id)).toEqual({
+      kind: "navigate",
+      entryId: a1!.id,
+      branch: "main",
+    });
+    expect(entryTarget(history, rev1!.id)?.kind).toBe("navigate");
+    expect(tipOf(history)).toBe(rev2!.id);
+  });
+
+  test("an entry only another branch reaches is a navigate on that branch", () => {
+    // Arrange: alt gets a second comment so its first is no longer a tip
+    let history = switchBranch(forked(), "alt");
+
+    history = appendEntry(history, {
+      type: "comment",
+      annotationId: "b2",
+      createdAt: LATER,
+    }).history;
+    const altFirst = history.entries.find(
+      (entry) => entry.type === "comment" && entry.annotationId === "b1",
+    )!;
+
+    history = switchBranch(history, "main");
+
+    // Assert
+    expect(entryTarget(history, altFirst.id)).toEqual({
+      kind: "navigate",
+      entryId: altFirst.id,
+      branch: "alt",
+    });
+    expect(entryTarget(history, "e_nope")).toBeNull();
+  });
+});