@cueloop/client 0.1.0-alpha.92 → 0.1.0-alpha.93

package/src/components/editor-grid.test.ts

@@ -3,10 +3,14 @@ import {
   addTab,
   changesTab,
   closeTab,
+  countEditorGroups,
   containsGroup,
   fileTab,
   firstGroupId,
+  keepFileTab,
   makeGroup,
+  MAX_EDITOR_GROUPS,
+  openFileTab,
   splitGroup,
   type EditorBranch,
   type EditorGroup,
@@ -38,6 +42,42 @@ describe("editor grid", () => {
     expect(next.activeTabId).toBe(file.id);
   });
 
+  test("a new preview replaces the group's previous preview", () => {
+    const group = makeGroup([changesTab()]);
+    const first = asGroup(openFileTab(group, group.id, "src/a.ts", "contents", false).tree);
+    const second = asGroup(openFileTab(first, group.id, "src/b.ts", "contents", false).tree);
+
+    expect(second.tabs.map((tab) => tab.path)).toEqual([undefined, "src/b.ts"]);
+    expect(second.tabs[1]?.preview).toBe(true);
+  });
+
+  test("keeping a preview makes subsequent previews open beside it", () => {
+    const group = makeGroup([changesTab()]);
+    const preview = asGroup(openFileTab(group, group.id, "src/a.ts", "contents", false).tree);
+    const kept = asGroup(keepFileTab(preview, group.id, preview.activeTabId!));
+    const next = asGroup(openFileTab(kept, group.id, "src/b.ts", "contents", false).tree);
+
+    expect(next.tabs.map((tab) => tab.path)).toEqual([undefined, "src/a.ts", "src/b.ts"]);
+    expect(next.tabs[1]?.preview).toBe(false);
+  });
+
+  test("reopening a file focuses its existing tab across groups and changes its view", () => {
+    const group = makeGroup([changesTab()]);
+    const open = asGroup(openFileTab(group, group.id, "src/a.ts", "contents", true).tree);
+    const { tree } = splitGroup(open, group.id, "right");
+    const branch = asBranch(tree);
+    const right = asGroup(branch.children[1]!);
+    const reopened = openFileTab(tree, group.id, "src/a.ts", "diff", false);
+
+    expect(reopened.focusGroupId).toBe(right.id);
+    expect(asGroup(asBranch(reopened.tree).children[1]!).tabs).toHaveLength(1);
+    expect(asGroup(asBranch(reopened.tree).children[1]!).tabs[0]).toMatchObject({
+      path: "src/a.ts",
+      fileView: "diff",
+      preview: false,
+    });
+  });
+
   test("splitting right makes a horizontal branch and focuses the new group", () => {
     const group = makeGroup([fileTab("App.tsx", "src/App.tsx", "diff")]);
     const { tree, focusGroupId } = splitGroup(group, group.id, "right");
@@ -48,6 +88,7 @@ describe("editor grid", () => {
     // the new group is the second child (right edge) and takes focus
     expect(branch.children[1]!.id).toBe(focusGroupId);
     expect(firstGroupId(tree)).toBe(group.id);
+    expect(asGroup(branch.children[0]!).tabs.some((tab) => tab.path === "src/App.tsx")).toBe(false);
   });
 
   test("splitting up makes a vertical branch with the new group first", () => {
@@ -58,6 +99,32 @@ describe("editor grid", () => {
     expect(branch.children[0]!.id).toBe(focusGroupId);
   });
 
+  test("splitting a file-only group keeps the Changes tab unique", () => {
+    const changes = makeGroup([changesTab()]);
+    const file = makeGroup([fileTab("a.ts", "a.ts", "diff")]);
+    const tree: EditorNode = {
+      type: "branch",
+      id: "two-groups",
+      orientation: "horizontal",
+      children: [changes, file],
+    };
+    const split = splitGroup(tree, file.id, "down");
+
+    expect(asBranch(split.tree).children[0]).toBe(changes);
+    expect(asBranch(asBranch(split.tree).children[1]!).children[0]).toMatchObject({
+      tabs: [{ kind: "welcome" }],
+    });
+  });
+
+  test("splitting Changes moves it to the new group", () => {
+    const group = makeGroup([changesTab()]);
+    const split = splitGroup(group, group.id, "right");
+    const branch = asBranch(split.tree);
+
+    expect(asGroup(branch.children[0]!).tabs[0]?.kind).toBe("welcome");
+    expect(asGroup(branch.children[1]!).tabs[0]?.kind).toBe("changes");
+  });
+
   test("closing the last tab of a split collapses the branch back to one group", () => {
     const group = makeGroup([fileTab("a.ts", "a.ts", "diff")]);
     const { tree } = splitGroup(group, group.id, "right");
@@ -83,4 +150,24 @@ describe("editor grid", () => {
     const collapsed = closeTab(tree, rightGroup.id, rightGroup.tabs[0]!.id);
     expect(containsGroup(asGroup(collapsed), rightGroup.id)).toBe(false);
   });
+
+  test("mixed split directions stop at eight editor groups", () => {
+    const first = makeGroup([changesTab()]);
+    let tree: EditorNode = first;
+    let focusGroupId = first.id;
+    const directions = ["right", "up", "left", "down"] as const;
+
+    for (const direction of [...directions, ...directions]) {
+      const result = splitGroup(tree, focusGroupId, direction);
+
+      tree = result.tree;
+      focusGroupId = result.focusGroupId;
+    }
+
+    expect(countEditorGroups(tree)).toBe(MAX_EDITOR_GROUPS);
+    const excess = splitGroup(tree, focusGroupId, "right");
+
+    expect(excess.tree).toBe(tree);
+    expect(excess.focusGroupId).toBe(focusGroupId);
+  });
 });

package/src/components/editor-grid.ts

@@ -1,6 +1,6 @@
 // The Changes pane's editor layout: a tree of nodes where a leaf is an editor group (a tab strip plus
-// its one active tab) and a branch splits child nodes along an orientation. Splitting an editor group
-// moves its active tab into a new group; a group is pruned when its last tab closes, collapsing the
+// its one active tab) and a branch splits child nodes along an orientation. Splitting a file tab
+// moves it into a new group; a group is pruned when its last tab closes, collapsing the
 // branch that held it.
 
 /** One editor in a group's tab strip: the Changes tab (the whole diff), a per-file tab, or Welcome. */
@@ -12,6 +12,8 @@ export interface EditorTab {
   path?: string;
   /** A file tab shows either a single-file diff or the file's plain contents. */
   fileView?: "diff" | "contents";
+  /** A preview is replaced by the next file opened in its group. */
+  preview?: boolean;
 }
 
 /** A leaf of the grid: one editor group holding tabs, with the active tab id. */
@@ -35,6 +37,9 @@ export type EditorNode = EditorGroup | EditorBranch;
 /** Which edge a split places the new group on; Left/Right split horizontally, Up/Down vertically. */
 export type SplitDirection = "left" | "right" | "up" | "down";
 
+/** The editor grid stops at eight groups so every tile remains usable. */
+export const MAX_EDITOR_GROUPS = 8;
+
 /** A split's outcome: the new grid and the id of the group that should take focus. */
 export interface SplitResult {
   tree: EditorNode;
@@ -59,8 +64,13 @@ export function welcomeTab(): EditorTab {
 }
 
 /** A file tab, opened from a tree; a diff view for a changed file, plain contents otherwise. */
-export function fileTab(label: string, path: string, fileView: "diff" | "contents"): EditorTab {
-  return { id: freshId(), kind: "file", label, path, fileView };
+export function fileTab(
+  label: string,
+  path: string,
+  fileView: "diff" | "contents",
+  preview = false,
+): EditorTab {
+  return { id: freshId(), kind: "file", label, path, fileView, preview };
 }
 
 /** The id of the first editor group in reading order; the fallback focus target. */
@@ -74,6 +84,13 @@ export function containsGroup(node: EditorNode, groupId: string): boolean {
   return node.children.some((child) => containsGroup(child, groupId));
 }
 
+/** Count editor tiles, including groups inside nested horizontal and vertical splits. */
+export function countEditorGroups(node: EditorNode): number {
+  if (node.type === "group") return 1;
+
+  return node.children.reduce((count, child) => count + countEditorGroups(child), 0);
+}
+
 function replaceGroup(
   node: EditorNode,
   id: string,
@@ -97,6 +114,111 @@ export function addTab(node: EditorNode, groupId: string, tab: EditorTab): Edito
   }));
 }
 
+/** Activate the one Changes tab, or add it beside the active group's existing tabs. */
+export function openChangesTab(node: EditorNode, groupId: string): SplitResult {
+  const existing = findTabByKind(node, "changes");
+
+  if (existing) {
+    return {
+      tree: activateTab(node, existing.groupId, existing.tab.id),
+      focusGroupId: existing.groupId,
+    };
+  }
+
+  return { tree: addTab(node, groupId, changesTab()), focusGroupId: groupId };
+}
+
+function findTabByKind(
+  node: EditorNode,
+  kind: EditorTab["kind"],
+): { groupId: string; tab: EditorTab } | null {
+  if (node.type === "group") {
+    const tab = node.tabs.find((candidate) => candidate.kind === kind);
+
+    return tab ? { groupId: node.id, tab } : null;
+  }
+
+  for (const child of node.children) {
+    const found = findTabByKind(child, kind);
+
+    if (found) return found;
+  }
+
+  return null;
+}
+
+interface FileTabLocation {
+  groupId: string;
+  tab: EditorTab;
+}
+
+/** A file path is one editor tab across the grid, even when the groups are split. */
+function findFileTab(node: EditorNode, path: string): FileTabLocation | null {
+  if (node.type === "group") {
+    const tab = node.tabs.find((candidate) => candidate.kind === "file" && candidate.path === path);
+
+    return tab ? { groupId: node.id, tab } : null;
+  }
+
+  for (const child of node.children) {
+    const found = findFileTab(child, path);
+
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/** Open a file once, replacing only a preview; reopening focuses its existing tab. */
+export function openFileTab(
+  node: EditorNode,
+  groupId: string,
+  path: string,
+  fileView: "diff" | "contents",
+  persistent: boolean,
+): SplitResult {
+  const existing = findFileTab(node, path);
+
+  if (existing) {
+    return {
+      tree: replaceGroup(node, existing.groupId, (group) => ({
+        ...group,
+        tabs: group.tabs.map((tab) =>
+          tab.id === existing.tab.id
+            ? { ...tab, fileView, preview: persistent ? false : tab.preview }
+            : tab,
+        ),
+        activeTabId: existing.tab.id,
+      })),
+      focusGroupId: existing.groupId,
+    };
+  }
+
+  const label = path.split("/").pop() ?? path;
+  const tab = fileTab(label, path, fileView, !persistent);
+
+  return {
+    tree: replaceGroup(node, groupId, (group) => {
+      const previewIndex = persistent ? -1 : group.tabs.findIndex((item) => item.preview);
+      const tabs = [...group.tabs];
+
+      if (previewIndex >= 0) tabs.splice(previewIndex, 1, tab);
+      else tabs.push(tab);
+
+      return { ...group, tabs, activeTabId: tab.id };
+    }),
+    focusGroupId: groupId,
+  };
+}
+
+/** Keep a preview file tab open when its tab is double-clicked. */
+export function keepFileTab(node: EditorNode, groupId: string, tabId: string): EditorNode {
+  return replaceGroup(node, groupId, (group) => ({
+    ...group,
+    tabs: group.tabs.map((tab) => (tab.id === tabId ? { ...tab, preview: false } : tab)),
+  }));
+}
+
 /** Drop empty groups and collapse a branch that ends up with one child; null when nothing remains. */
 export function pruneEmpty(node: EditorNode): EditorNode | null {
   if (node.type === "group") return node.tabs.length > 0 ? node : null;
@@ -122,16 +244,30 @@ export function splitGroup(
   groupId: string,
   direction: SplitDirection,
 ): SplitResult {
+  if (countEditorGroups(node) >= MAX_EDITOR_GROUPS) return { tree: node, focusGroupId: groupId };
+
   let focusGroupId = groupId;
   const tree = replaceGroup(node, groupId, (group) => {
     const active = group.tabs.find((tab) => tab.id === group.activeTabId) ?? group.tabs[0];
     if (active === undefined) return group;
-    const movedTab: EditorTab = { ...active, id: freshId() };
+    const movedTab: EditorTab =
+      active.kind === "welcome" ? { ...active, id: freshId() } : { ...active, preview: false };
     const newGroup = makeGroup([movedTab]);
     focusGroupId = newGroup.id;
     const orientation = direction === "left" || direction === "right" ? "horizontal" : "vertical";
     const newFirst = direction === "left" || direction === "up";
-    const children = newFirst ? [newGroup, group] : [group, newGroup];
+    const remainingTabs =
+      active.kind === "welcome" ? group.tabs : group.tabs.filter((tab) => tab.id !== active.id);
+    const sourceTabs =
+      remainingTabs.length > 0
+        ? remainingTabs
+        : [findTabByKind(node, "changes") ? welcomeTab() : changesTab()];
+    const sourceGroup = {
+      ...group,
+      tabs: sourceTabs,
+      activeTabId: sourceTabs[0]!.id,
+    };
+    const children = newFirst ? [newGroup, sourceGroup] : [sourceGroup, newGroup];
     return { type: "branch", id: freshId(), orientation, children };
   });
   return { tree, focusGroupId };

package/src/components/primitives/Tree.tsx

@@ -1,7 +1,8 @@
 // OpenTUI renderer for the headless tree-model; the caller owns expansion and selection.
 
-import React from "react";
+import React, { useRef } from "react";
 import { DARK, type Theme } from "../../theme";
+import { isDoubleClick, type ClickStamp } from "../../thread-selection";
 import { flattenTree, statusMeta, type TreeNode, type TreeTone } from "./tree-model";
 import { NERD_TREE_ICONS, type TreeIcons } from "./icons";
 
@@ -13,11 +14,14 @@ export interface TreeProps {
   showStatus?: boolean;
   /** Drop the folder/file glyph prefix, for a plain text tree (e.g. the settings nav). */
   hideIcons?: boolean;
+  /** Keep file navigator entries to one visual row, truncating long names. */
+  singleLine?: boolean;
   /** The selected row's backdrop; defaults to `elevated` (invisible on an elevated dialog, use `border` there). */
   selectedBackground?: string;
   indentWidth?: number;
   icons?: TreeIcons;
   onSelect?: (id: string) => void;
+  onDoubleSelect?: (id: string) => void;
   onToggle?: (id: string) => void;
   theme?: Theme;
 }
@@ -43,16 +47,19 @@ export function Tree({
   flattenEmptyDirectories,
   showStatus,
   hideIcons,
+  singleLine = false,
   selectedBackground,
   indentWidth = 2,
   icons = NERD_TREE_ICONS,
   onSelect,
+  onDoubleSelect,
   onToggle,
   theme,
 }: TreeProps): React.ReactNode {
   const tokens = theme ?? DARK;
   const selectedBackdrop = selectedBackground ?? tokens.elevated;
   const rows = flattenTree(nodes, { expandedIds, flattenEmptyDirectories });
+  const lastClick = useRef<{ id: string; stamp: ClickStamp } | null>(null);
 
   return (
     <box style={{ flexDirection: "column" }}>
@@ -73,25 +80,54 @@ export function Tree({
             id={`tree-row-${row.id}`}
             style={{
               flexDirection: "row",
+              justifyContent: "space-between",
+              height: singleLine ? 1 : undefined,
+              overflow: singleLine ? "hidden" : undefined,
               paddingLeft: 1 + row.depth * indentWidth,
-              paddingRight: 1,
+              paddingRight: singleLine && status ? 0 : 1,
               backgroundColor: selected ? selectedBackdrop : undefined,
             }}
-            onMouseUp={() => (row.isFolder ? onToggle?.(row.id) : onSelect?.(row.id))}
+            onMouseUp={(event) => {
+              const stamp = { time: Date.now(), x: event.x, y: event.y };
+              const doubleClick =
+                lastClick.current?.id === row.id && isDoubleClick(lastClick.current.stamp, stamp);
+
+              lastClick.current = { id: row.id, stamp };
+              if (row.isFolder) onToggle?.(row.id);
+              else {
+                onSelect?.(row.id);
+                if (doubleClick) onDoubleSelect?.(row.id);
+              }
+            }}
           >
-            {hideIcons ? null : (
-              <text fg={row.isFolder ? tokens.blue : tokens.textDim}>
-                {row.icon ?? rowGlyph(row.isFolder, row.expanded, icons)}{" "}
-              </text>
-            )}
-            <box style={{ flexShrink: 1, minWidth: 0 }}>
-              <text fg={selected ? tokens.accent : labelColor} truncate>
-                {row.label}
-              </text>
+            <box
+              style={{
+                flexDirection: "row",
+                flexShrink: 1,
+                minWidth: 0,
+                overflow: singleLine ? "hidden" : undefined,
+              }}
+            >
+              {hideIcons ? null : (
+                <text fg={row.isFolder ? tokens.blue : tokens.textDim}>
+                  {row.icon ?? rowGlyph(row.isFolder, row.expanded, icons)}{" "}
+                </text>
+              )}
+              <box style={{ flexShrink: 1, minWidth: 0 }}>
+                <text
+                  id={`tree-label-${row.id}`}
+                  fg={selected ? tokens.accent : labelColor}
+                  wrapMode={singleLine ? "none" : undefined}
+                  truncate={!singleLine}
+                >
+                  {singleLine ? `${row.label}  ` : row.label}
+                </text>
+              </box>
+            </box>
+            <box style={{ flexDirection: "row", flexShrink: 0 }}>
+              {row.badge !== undefined ? <text fg={tokens.textDim}>{row.badge}</text> : null}
+              {status ? <text fg={toneColor(status.tone, tokens)}> {status.letter}</text> : null}
             </box>
-            <box style={{ flexGrow: 1 }} />
-            {row.badge !== undefined ? <text fg={tokens.textDim}>{row.badge}</text> : null}
-            {status ? <text fg={toneColor(status.tone, tokens)}> {status.letter}</text> : null}
           </box>
         );
       })}

package/src/thread-controller.curate.test.ts

@@ -431,6 +431,33 @@ function tailSession(): Thread {
 }
 
 describe("diff file fold", () => {
+  test("added and deleted files with a zero-sided hunk retain their expand action", async () => {
+    const patch = [
+      "diff --git a/src/new.ts b/src/new.ts",
+      "--- /dev/null",
+      "+++ b/src/new.ts",
+      "@@ -0,0 +1,1 @@",
+      "+new line",
+      "diff --git a/src/gone.ts b/src/gone.ts",
+      "--- a/src/gone.ts",
+      "+++ /dev/null",
+      "@@ -1,1 +0,0 @@",
+      "-old line",
+      "",
+    ].join("\n");
+    const files: DiffFileContents[] = [
+      { path: "src/new.ts", oldContents: "", newContents: "new line\n", status: "added" },
+      { path: "src/gone.ts", oldContents: "old line\n", newContents: "", status: "deleted" },
+    ];
+    const session = diffSession(files);
+    session.artifact.content = patch;
+    session.revisions[0]!.content = patch;
+    const { controller } = await connected(session);
+
+    expect(controller.canExpandFile("src/new.ts")).toBe(true);
+    expect(controller.canExpandFile("src/gone.ts")).toBe(true);
+  });
+
   test("collapse leaves only the file band; expand restores the body", async () => {
     // Arrange
     const { controller } = await connected(tailSession());

package/src/thread-controller.ts

@@ -293,8 +293,8 @@ export interface ReviewController {
   isFileExpanded(file: string): boolean;
   /** Whether the file carries the full contents weaving needs (curatable diffs do). */
   canExpandFile(file: string): boolean;
-  /** Copy a file's path to the clipboard; reports the outcome via status. */
-  copyFilePath(file: string): void;
+  /** Copy a file's path to the clipboard; the control reports the outcome. */
+  copyFilePath(file: string): Promise<boolean>;
   /** Per-file added/removed line counts from the base rows (survives collapse). */
   fileStats(): Map<string, { additions: number; deletions: number }>;
   /** The walk's step list, derived from the diff rows. */
@@ -782,10 +782,8 @@ class Controller implements ReviewController {
     return (this.foldFiles() ?? []).some((entry) => entry.path === file);
   }
 
-  copyFilePath(file: string): void {
-    void copyToClipboard(file).then((copied) =>
-      this.setStatus(copied ? `copied ${file}` : "no clipboard tool available"),
-    );
+  copyFilePath(file: string): Promise<boolean> {
+    return copyToClipboard(file);
   }
 
   fileStats(): Map<string, { additions: number; deletions: number }> {

package/src/use-annotation-surface.tsx

@@ -14,7 +14,8 @@
 
 import React, { useContext, useEffect, useRef, useState } from "react";
 import type { KeyEvent, MouseEvent as TerminalMouseEvent, TextRenderable } from "@opentui/core";
-import { useKeyboard } from "@opentui/react";
+import { flushSync } from "@opentui/react";
+import { useSharedKeyboard } from "./use-shared-keyboard";
 import type { Annotation, Thread } from "@cueloop/schema";
 import type { Mark } from "./view-plan";
 import type { QuickAction } from "./config";
@@ -97,6 +98,13 @@ export interface AnnotationSurfaceOptions {
   onObserverBlocked?: (reason: "observer" | "resolved") => void;
   /** Reports the caret's block, so block-level primitives (cut, restore) act where the caret is. */
   onCursorChange?: (blockIndex: number) => void;
+  /** Scroll a visual row before crossing a tall gap; true defers the caret move. */
+  onVerticalStep?: (
+    fromBlock: number,
+    toBlock: number,
+    direction: -1 | 1,
+    targetY?: number,
+  ) => boolean;
   /** The rail's focused card; the discussion holding it takes focus here. */
   focusedAnnotationId?: string;
   /** Reports the focused discussion's root comment, so the rail follows. */
@@ -129,6 +137,10 @@ export interface AnnotationSurface {
   focusedDiscussion: string | null;
   /** The block to keep in view: an opening card, a focused discussion, else the caret. */
   revealBlockIndex: number;
+  /** Screen row of the mounted visual line carrying the caret. */
+  headVisualY: () => number | undefined;
+  /** Capture mounted lines before a viewport scroll, then keep an exiting caret at its visible edge. */
+  prepareViewportScroll: () => (delta: number, top: number, bottom: number) => void;
   /** The text a span covers, blocks joined by a space, for previews. */
   spanQuote: (span: TextSpan) => string;
   /** Ref callback for one visual line, so a drag can hit-test it. */
@@ -192,6 +204,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     onComposingChange,
     onObserverBlocked,
     onCursorChange,
+    onVerticalStep,
     focusedAnnotationId,
     onFocusAnnotation,
     onAnnotate,
@@ -336,15 +349,55 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       x: entry.renderable.x,
       y: entry.renderable.y,
     }));
-  const verticalTextPosition = (position: TextPosition, direction: -1 | 1): TextPosition | null => {
+  const headVisualY = (): number | undefined => {
+    const textLength = textLengthOf(head.blockIndex);
+    const cell = Math.max(0, Math.min(textLength - 1, head.char));
+
+    return allGeometry().find(
+      (line) =>
+        line.blockIndex === head.blockIndex &&
+        line.start <= cell &&
+        (cell < line.end || line.start === line.end),
+    )?.y;
+  };
+  const prepareViewportScroll = (): ((delta: number, top: number, bottom: number) => void) => {
+    const lines = allGeometry().filter((line) => source.annotatable(line.blockIndex));
+    const oldHeadY = headVisualY();
+
+    return (delta, top, bottom) => {
+      if (delta === 0 || oldHeadY === undefined || compose || focusedDiscussion || caretIsSelection)
+        return;
+      const shiftedHeadY = oldHeadY - delta;
+
+      if (shiftedHeadY >= top && shiftedHeadY <= bottom) return;
+      const visible = lines
+        .filter((line) => line.y - delta >= top && line.y - delta <= bottom)
+        .toSorted((left, right) => left.y - right.y || left.x - right.x);
+      const target = delta < 0 ? visible.at(-1) : visible[0];
+
+      if (!target) return;
+      const next = { blockIndex: target.blockIndex, char: target.start };
+
+      flushSync(() => {
+        setCaret({ head: next, anchor: next });
+        setCursor(next.blockIndex);
+      });
+    };
+  };
+  const verticalTextPosition = (
+    position: TextPosition,
+    direction: -1 | 1,
+  ): { position: TextPosition; y: number } | null => {
+    const textLength = textLengthOf(position.blockIndex);
+    const cell = Math.max(0, Math.min(textLength - 1, position.char));
     const lines = allGeometry()
       .filter((line) => source.annotatable(line.blockIndex))
       .toSorted((left, right) => left.y - right.y || left.x - right.x);
     const currentIndex = lines.findIndex(
       (line) =>
         line.blockIndex === position.blockIndex &&
-        line.start <= position.char &&
-        position.char <= line.end,
+        line.start <= cell &&
+        (cell < line.end || line.start === line.end),
     );
     const target = currentIndex === -1 ? undefined : lines[currentIndex + direction];
 
@@ -353,8 +406,11 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     const column = Math.max(0, position.char - current.start);
 
     return {
-      blockIndex: target.blockIndex,
-      char: Math.min(target.end, target.start + column),
+      position: {
+        blockIndex: target.blockIndex,
+        char: Math.min(target.end, target.start + column),
+      },
+      y: target.y,
     };
   };
 
@@ -671,22 +727,31 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     );
   };
 
+  const moveCaretVertical = (key: KeyEvent, vertical: -1 | 1): void => {
+    const nextBlock = nearestAnnotatable(source, cursor, vertical);
+    const visualTarget = verticalTextPosition(head, vertical);
+
+    if (!visualTarget && nextBlock === head.blockIndex) return;
+    const nextHead = visualTarget?.position ?? {
+      blockIndex: nextBlock,
+      char: key.shift ? Math.min(head.char, textLengthOf(nextBlock)) : 0,
+    };
+
+    if (onVerticalStep?.(head.blockIndex, nextHead.blockIndex, vertical, visualTarget?.y)) return;
+
+    setCaret({
+      head: nextHead,
+      anchor: key.shift ? caret.anchor : nextHead,
+    });
+    setFocusedDiscussion(null);
+    setCursor(nextHead.blockIndex);
+  };
+
   const handleCaretKey = (key: KeyEvent): boolean => {
     const vertical = verticalCaretDelta(key);
 
     if (vertical !== 0) {
-      const nextBlock = nearestAnnotatable(source, cursor, vertical);
-      const nextHead = verticalTextPosition(head, vertical) ?? {
-        blockIndex: nextBlock,
-        char: key.shift ? Math.min(head.char, textLengthOf(nextBlock)) : 0,
-      };
-
-      setCaret({
-        head: nextHead,
-        anchor: key.shift ? caret.anchor : nextHead,
-      });
-      setFocusedDiscussion(null);
-      setCursor(nextHead.blockIndex);
+      moveCaretVertical(key, vertical);
 
       return true;
     }
@@ -726,7 +791,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     openNewCompose(sequence);
   };
 
-  useKeyboard((key) => {
+  useSharedKeyboard((key) => {
     if (suspended) return;
     if (key.ctrl && key.name === "q") return onExit();
     const activeCompose = composeRef.current;
@@ -963,6 +1028,8 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     navMode,
     focusedDiscussion,
     revealBlockIndex,
+    headVisualY,
+    prepareViewportScroll,
     spanQuote,
     registerLine,
     onLineMouseDown,