@cueloop/client 0.1.0-alpha.8 → 0.1.0-alpha.81

package/src/use-terminal-virtualizer.ts

@@ -0,0 +1,233 @@
+/**
+ * Row virtualization for an OpenTUI scrollbox, driven by @tanstack/virtual-core.
+ * The core is DOM-free at heart: it only reaches the scroll container through the
+ * observe/scroll callbacks given here, so a terminal scrollbox stands in for the
+ * element - offsets and sizes are terminal rows, the "scroll event" is the
+ * renderer's frame event, and a mounted row's height is read off its renderable.
+ * Callers render `items` with a spacer of `items[0].start` rows above and
+ * `totalSize - last.end` below, and hand each row's box to `measureRef(index)`.
+ */
+
+import { useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
+import type { BoxRenderable, ScrollBoxRenderable } from "@opentui/core";
+import { useRenderer } from "@opentui/react";
+import { Virtualizer, type VirtualItem } from "@tanstack/virtual-core";
+
+export interface TerminalVirtualizerOptions {
+  scrollbox: RefObject<ScrollBoxRenderable | null>;
+  count: number;
+  /** Rows an item occupies before it is measured (its wrapped visual lines). */
+  estimateSize: (index: number) => number;
+  /** Items this many rows beyond the viewport stay mounted, so a scroll step never shows a gap. */
+  overscan: number;
+}
+
+export interface TerminalVirtualizer {
+  items: VirtualItem[];
+  totalSize: number;
+  /** Ref callback for an item's row box, so its real height (cards included) replaces the estimate. */
+  measureRef: (index: number) => (renderable: BoxRenderable | null) => void | (() => void);
+  /** Scroll the item into view; "auto" only scrolls when it is off screen. */
+  scrollToIndex: (index: number, align?: "auto" | "start" | "center" | "end") => void;
+}
+
+/**
+ * The scroll container as the core reads it: the offset and the extents it clamps a scroll
+ * target with. These are the `Element` members of the same names, so the view passes as one.
+ */
+interface ScrollContainerView {
+  readonly scrollTop: number;
+  readonly scrollHeight: number;
+  readonly clientHeight: number;
+  readonly scrollWidth: number;
+  readonly clientWidth: number;
+}
+
+/** A mounted row as the core measures it: its height under the `Element` member name. */
+interface RowView {
+  readonly clientHeight: number;
+}
+
+type CoreVirtualizer = Virtualizer<Element, Element>;
+
+function scrollContainerView(scrollbox: ScrollBoxRenderable): ScrollContainerView {
+  return {
+    get scrollTop() {
+      return scrollbox.scrollTop;
+    },
+    get scrollHeight() {
+      return scrollbox.scrollHeight;
+    },
+    get clientHeight() {
+      return scrollbox.viewport.height;
+    },
+    get scrollWidth() {
+      return scrollbox.scrollWidth;
+    },
+    get clientWidth() {
+      return scrollbox.viewport.width;
+    },
+  };
+}
+
+function rowView(renderable: BoxRenderable): RowView {
+  return {
+    get clientHeight() {
+      return renderable.height;
+    },
+  };
+}
+
+/**
+ * The core's element generics are DOM-typed, but every way it touches the container or a row
+ * (rect, offset, scroll, measurement, index lookup) is replaced here with a renderable-aware
+ * callback, so a view exposing just the members it reads stands in for the element.
+ */
+function asElement(view: ScrollContainerView | RowView): Element {
+  // SAFETY: the core never calls DOM methods on this value; its DOM defaults are all overridden.
+  return view as Element;
+}
+
+export function useTerminalVirtualizer(options: TerminalVirtualizerOptions): TerminalVirtualizer {
+  const renderer = useRenderer();
+  const [, setRevision] = useState(0);
+  // one stable view per mounted row box, so the core's element cache keeps its identity
+  const viewOfRenderable = useRef(new WeakMap<BoxRenderable, Element>());
+  const indexOfView = useRef(new WeakMap<Element, number>());
+  const container = useRef<{ scrollbox: ScrollBoxRenderable; view: Element } | null>(null);
+
+  const scrollContainer = (): Element | null => {
+    const scrollbox = options.scrollbox.current;
+
+    if (!scrollbox) return null;
+    if (container.current?.scrollbox !== scrollbox) {
+      container.current = { scrollbox, view: asElement(scrollContainerView(scrollbox)) };
+    }
+
+    return container.current.view;
+  };
+  const viewFor = (renderable: BoxRenderable): Element => {
+    const known = viewOfRenderable.current.get(renderable);
+
+    if (known) return known;
+    const view = asElement(rowView(renderable));
+
+    viewOfRenderable.current.set(renderable, view);
+
+    return view;
+  };
+
+  // the offset reporter the core registered, so a scroll the core asks for reports at once
+  const reportOffset = useRef<(() => void) | null>(null);
+
+  // a frame-event poll stands in for scroll and resize events: the renderer fires it after every
+  // render, and the callbacks only fire the core when the value actually changed
+  const onFrame = (read: () => void): (() => void) => {
+    read();
+    renderer?.on("frame", read);
+
+    return () => renderer?.off("frame", read);
+  };
+
+  const coreOptions = () => ({
+    count: options.count,
+    overscan: options.overscan,
+    estimateSize: options.estimateSize,
+    getScrollElement: scrollContainer,
+    observeElementRect: (
+      _instance: CoreVirtualizer,
+      callback: (rect: { width: number; height: number }) => void,
+    ) => {
+      let last = { width: -1, height: -1 };
+
+      return onFrame(() => {
+        const scrollbox = options.scrollbox.current;
+
+        if (!scrollbox) return;
+        const next = { width: scrollbox.viewport.width, height: scrollbox.viewport.height };
+
+        if (next.width === last.width && next.height === last.height) return;
+        last = next;
+        callback(next);
+      });
+    },
+    observeElementOffset: (
+      _instance: CoreVirtualizer,
+      callback: (offset: number, isScrolling: boolean) => void,
+    ) => {
+      let last = -1;
+      const report = (): void => {
+        const scrollbox = options.scrollbox.current;
+
+        if (!scrollbox || scrollbox.scrollTop === last) return;
+        last = scrollbox.scrollTop;
+        callback(last, false);
+      };
+      const stop = onFrame(report);
+
+      reportOffset.current = report;
+
+      return () => {
+        reportOffset.current = null;
+        stop();
+      };
+    },
+    // report the new offset in the same tick: the item window then follows the scroll at once,
+    // instead of one frame later with the target rows still unmounted
+    scrollToFn: (offset: number) => {
+      options.scrollbox.current?.scrollTo({ x: 0, y: Math.max(0, Math.round(offset)) });
+      reportOffset.current?.();
+    },
+    // a box measures 0 until Yoga has laid it out; keep the estimate rather than collapse the row
+    measureElement: (element: Element) =>
+      element.clientHeight > 0
+        ? element.clientHeight
+        : options.estimateSize(indexOfView.current.get(element) ?? -1),
+    onChange: () => setRevision((revision) => revision + 1),
+  });
+
+  const [virtualizer] = useState<CoreVirtualizer>(() => {
+    const instance = new Virtualizer<Element, Element>(coreOptions());
+
+    // the core looks an item's index up through a DOM attribute; ours is remembered per row view
+    instance.indexFromElement = (element) => indexOfView.current.get(element) ?? -1;
+
+    return instance;
+  });
+
+  virtualizer.setOptions(coreOptions());
+  useLayoutEffect(() => {
+    virtualizer._willUpdate();
+  });
+  useEffect(() => virtualizer._didMount(), [virtualizer]);
+  // no ResizeObserver here: a mounted row's height settles after layout and grows when a card
+  // opens under it, so every frame re-reads the mounted rows (the core only notifies on change)
+  useEffect(
+    () =>
+      onFrame(() => {
+        for (const element of virtualizer.elementsCache.values()) {
+          virtualizer.measureElement(element);
+        }
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [virtualizer, renderer],
+  );
+
+  return {
+    items: virtualizer.getVirtualItems(),
+    totalSize: virtualizer.getTotalSize(),
+    measureRef: (index) => (renderable) => {
+      if (!renderable) return;
+      const view = viewFor(renderable);
+
+      indexOfView.current.set(view, index);
+      virtualizer.measureElement(view);
+
+      // the row unmounted: forget its view so the frame re-measure stops reading it
+      return () => {
+        if (virtualizer.elementsCache.get(index) === view) virtualizer.elementsCache.delete(index);
+      };
+    },
+    scrollToIndex: (index, align = "auto") => virtualizer.scrollToIndex(index, { align }),
+  };
+}

package/src/use-thread-body-editing.tsx

@@ -0,0 +1,58 @@
+/**
+ * The thread pane's inline edit mode: owns whether the native markdown editor is
+ * open over the body, the editor element itself, and the open and exit handles.
+ * Opening is gated to an editable thread (the caller passes canEdit - owner,
+ * unresolved, not a diff); exiting saves the edited body as the working copy
+ * through the controller, so leaving the editor never loses work. The header
+ * edit/normal toggle exits through requestExit; switching threads closes the
+ * editor. Rendering the editor lives here too, so the pane pulls in one concept
+ * rather than wiring the component and its handle ref by hand.
+ */
+
+import React, { useRef, useState } from "react";
+import type { Theme } from "./theme";
+import type { ReviewController } from "./thread-controller";
+import { MarkdownThreadEditor, type MarkdownEditorHandle } from "./components/MarkdownThreadEditor";
+
+export interface ThreadBodyEditing {
+  /** True while the inline markdown editor owns the thread pane and its keys. */
+  editing: boolean;
+  /** Open the editor when the active thread is editable; a no-op otherwise. */
+  openEditor: () => void;
+  /** Save the current text and close - the header edit/normal toggle's exit. */
+  requestExit: () => void;
+  /** The editor element for the thread pane, bound to the working copy and theme. */
+  renderEditor: (theme: Theme) => React.ReactNode;
+}
+
+export function useThreadBodyEditing(options: {
+  controller: ReviewController;
+  sessionId: string | undefined;
+  canEdit: boolean;
+}): ThreadBodyEditing {
+  const { controller, sessionId, canEdit } = options;
+  // key editing by thread id so a thread switch closes the editor with no effect or ref
+  const [editingSessionId, setEditingSessionId] = useState<string | null>(null);
+  const handleRef = useRef<MarkdownEditorHandle | null>(null);
+  const editing = editingSessionId !== null && editingSessionId === sessionId;
+  const exitEditor = (text: string): void => {
+    controller.saveEditedBody(text);
+    setEditingSessionId(null);
+  };
+
+  return {
+    editing,
+    openEditor: () => {
+      if (canEdit && sessionId !== undefined) setEditingSessionId(sessionId);
+    },
+    requestExit: () => handleRef.current?.requestExit(),
+    renderEditor: (theme) => (
+      <MarkdownThreadEditor
+        ref={handleRef}
+        initialText={controller.working()}
+        theme={theme}
+        onExitEditor={exitEditor}
+      />
+    ),
+  };
+}

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.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { diffRowAnchor, diffRows } from "./view-diff";
+import { makeAnchor, type Annotation, type Thread } from "@cueloop/schema";
+import {
+  changesMarks,
+  diffRowAnchor,
+  diffRowBlocks,
+  diffRows,
+  fileRowRange,
+  fileTargetMarks,
+} from "./view-diff";
 
 const PATCH = `diff --git a/src/store.ts b/src/store.ts
 index 111..222 100644
@@ -21,23 +29,32 @@ index 111..222 100644
 
 describe("diffRows", () => {
   test("flattens files, hunks, and signed lines with line numbers", () => {
+    // Act
     const rows = diffRows(PATCH);
-    expect(rows[0]).toMatchObject({ t: "file", file: "src/store.ts" });
-    expect(rows[1]!.t).toBe("hunk");
-    const del = rows.find((r) => r.t === "del")!;
+
+    // Assert
+    expect(rows[0]).toMatchObject({ kind: "file", file: "src/store.ts" });
+    expect(rows[1]!.kind).toBe("hunk");
+    const del = rows.find((row) => row.kind === "del")!;
+
     expect(del.text).toContain("private items = [];");
     expect(del.oldLine).toBe(3);
-    const adds = rows.filter((r) => r.t === "add");
+    const adds = rows.filter((row) => row.kind === "add");
+
     expect(adds[0]!.text).toContain("new Map()");
     expect(adds[0]!.newLine).toBe(3);
     expect(adds[1]!.newLine).toBe(4);
     // two hunks
-    expect(rows.filter((r) => r.t === "hunk").length).toBe(2);
+    expect(rows.filter((row) => row.kind === "hunk").length).toBe(2);
   });
 
   test("context lines carry both line numbers", () => {
+    // Act
     const rows = diffRows(PATCH);
-    const ctx = rows.find((r) => r.t === "ctx")!;
+
+    // Assert
+    const ctx = rows.find((row) => row.kind === "ctx")!;
+
     expect(ctx.oldLine).toBe(1);
     expect(ctx.newLine).toBe(1);
   });
@@ -45,11 +62,122 @@ describe("diffRows", () => {
 
 describe("diffRowAnchor", () => {
   test("quote is the line, neighbors are the context selectors", () => {
+    // Arrange
     const rows = diffRows(PATCH);
-    const idx = rows.findIndex((r) => r.text.includes("new Map()"));
-    const anchor = diffRowAnchor(rows, idx);
+    const rowIndex = rows.findIndex((row) => row.text.includes("new Map()"));
+
+    // Act
+    const anchor = diffRowAnchor(rows, rowIndex);
+
+    // Assert
     expect(anchor.quote).toContain("new Map()");
     expect(anchor.prefix.length).toBeGreaterThan(0);
     expect(anchor.suffix.length).toBeGreaterThan(0);
   });
 });
+
+describe("fileTargetMarks", () => {
+  // two files whose added line is byte-identical; a note on one must never mark the other
+  const TWO_FILE = `diff --git a/a.ts b/a.ts
+--- a/a.ts
++++ b/a.ts
+@@ -1,1 +1,2 @@
+ const keep = 0;
++const dup = 1;
+diff --git a/b.ts b/b.ts
+--- a/b.ts
++++ b/b.ts
+@@ -1,1 +1,2 @@
+ const keep = 0;
++const dup = 1;
+`;
+
+  test("a file-target note marks only its own file, never identical text in another", () => {
+    // Arrange - anchor the added line inside a.ts, file-relative like the controller does
+    const rows = diffRows(TWO_FILE);
+    const range = fileRowRange(rows, "a.ts")!;
+    const fileRows = rows.slice(range.start, range.end);
+    const addRelative = fileRows.findIndex((row) => row.kind === "add");
+    const quote = fileRows[addRelative]!.text.replace(/\n$/, "");
+    const anchor = makeAnchor(diffRowBlocks(fileRows), addRelative, 0, quote.length, addRelative);
+    const annotation: Annotation = {
+      id: "a1",
+      kind: "comment",
+      anchor,
+      target: { kind: "file", path: "a.ts", rev: "worktree" },
+      body: "note",
+      createdAt: "2026-01-01T00:00:00Z",
+    };
+
+    // Act
+    const marked = [...fileTargetMarks([annotation], rows).keys()];
+
+    // Assert - every marked row sits inside a.ts's range, and b.ts's identical line is untouched
+    expect(marked.length).toBeGreaterThan(0);
+    expect(marked.every((index) => index >= range.start && index < range.end)).toBe(true);
+  });
+});
+
+describe("changesMarks", () => {
+  const PATCH = `diff --git a/x.ts b/x.ts
+--- a/x.ts
++++ b/x.ts
+@@ -1,1 +1,2 @@
+ const keep = 0;
++const added = 1;
+`;
+
+  function diffThread(meta: Thread["artifact"]["meta"], annotations: Annotation[]): Thread {
+    return {
+      schemaVersion: "1",
+      id: "s_changes",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "diff", content: PATCH, meta },
+      revisions: [{ revision: 1, content: PATCH, submittedAt: "2026-01-01T00:00:00Z" }],
+      annotations,
+      message: null,
+      status: "pending",
+      createdAt: "2026-01-01T00:00:00Z",
+    };
+  }
+
+  function fileNote(rows: ReturnType<typeof diffRows>): Annotation {
+    const range = fileRowRange(rows, "x.ts")!;
+    const fileRows = rows.slice(range.start, range.end);
+    const addRelative = fileRows.findIndex((row) => row.kind === "add");
+    const quote = fileRows[addRelative]!.text.replace(/\n$/, "");
+    const anchor = makeAnchor(diffRowBlocks(fileRows), addRelative, 0, quote.length, addRelative);
+
+    return {
+      id: "f1",
+      kind: "comment",
+      anchor,
+      target: { kind: "file", path: "x.ts", rev: "worktree" },
+      body: "note",
+      createdAt: "2026-01-01T00:00:00Z",
+    };
+  }
+
+  test("a workbench thread paints its file-targeted working-tree notes", () => {
+    const rows = diffRows(PATCH);
+    const session = diffThread({ workbench: true }, [fileNote(rows)]);
+
+    expect([...changesMarks(session, rows).keys()].length).toBeGreaterThan(0);
+  });
+
+  test("a pinned diff review paints only artifact notes, not the working tree's file targets", () => {
+    const rows = diffRows(PATCH);
+    const session = diffThread({}, [fileNote(rows)]);
+
+    // the same file-targeted note is not an artifact note, so a frozen review leaves it unpainted
+    expect([...changesMarks(session, rows).keys()].length).toBe(0);
+  });
+
+  test("a shared snapshot still paints the workbench's file-targeted feedback", () => {
+    const rows = diffRows(PATCH);
+    // a served/shared snapshot keeps the workbench marker, so its notes stay file-targeted and visible
+    const session = diffThread({ workbench: true, snapshot: true }, [fileNote(rows)]);
+
+    expect([...changesMarks(session, rows).keys()].length).toBeGreaterThan(0);
+  });
+});