march-cli 0.1.12 → 0.1.14

package/src/agent/turn/turn-events.mjs

@@ -1,3 +1,5 @@
+import { formatToolStartLine, formatToolSuccessSummary } from "../tool-summary.mjs";
+
 export function createTurnEventState() {
   return {
     draft: "",
@@ -5,6 +7,8 @@ export function createTurnEventState() {
     thinkingAccumulator: "",
     recallCursor: { draftLength: 0, thinkingLength: 0 },
     assistantReplyOpen: false,
+    assistantContextParts: [],
+    activeToolContextPart: null,
   };
 }
 
@@ -14,9 +18,11 @@ export function handleRunnerSessionEvent(event, { ui, engine, state }) {
   }
   if (event.type === "tool_execution_start") {
     closeAssistantReply({ ui, state });
+    appendToolStartContext(state, event.toolName, event.args);
     ui.toolStart(event.toolName, event.args);
   }
   if (event.type === "tool_execution_end") {
+    updateToolEndContext(state, event.toolName, event.isError, event.result);
     ui.toolEnd(event.toolName, event.isError, event.result);
   }
   if (event.type === "auto_retry_start") {
@@ -45,6 +51,7 @@ export function closeAssistantReply({ ui, state }) {
 function handleAssistantMessageEvent(event, { ui, state }) {
   if (event.type === "text_delta") {
     state.draft += event.delta;
+    appendAssistantContextText(state, event.delta, "output");
     state.assistantReplyOpen = true;
     ui.textDelta(event.delta);
   }
@@ -54,6 +61,7 @@ function handleAssistantMessageEvent(event, { ui, state }) {
   }
   if (event.type === "thinking_delta") {
     state.thinkingText += event.delta;
+    appendAssistantContextText(state, event.delta, "thinking");
     ui.thinkingDelta(event.delta);
   }
   if (event.type === "thinking_end" && state.thinkingText) {
@@ -63,3 +71,41 @@ function handleAssistantMessageEvent(event, { ui, state }) {
     state.thinkingText = "";
   }
 }
+
+export function compactAssistantContext(state) {
+  return (state?.assistantContextParts ?? [])
+    .map((part) => part?.text ?? "")
+    .join("")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function appendAssistantContextText(state, text, type) {
+  if (!text) return;
+  const parts = state.assistantContextParts;
+  const last = parts.at(-1);
+  if (last?.type === type) {
+    last.text += text;
+    return;
+  }
+  if (last && !last.text.endsWith("\n")) last.text += "\n";
+  parts.push({ type, text });
+}
+
+function appendToolStartContext(state, name, args) {
+  const parts = state.assistantContextParts;
+  const last = parts.at(-1);
+  if (last && !last.text.endsWith("\n")) last.text += "\n";
+  const part = { type: "tool", name, text: `${formatToolStartLine(name, args)}\n` };
+  parts.push(part);
+  state.activeToolContextPart = part;
+}
+
+function updateToolEndContext(state, name, isError, result) {
+  const part = state.activeToolContextPart;
+  if (!part || part.name !== name) return;
+  const summary = isError ? "failed" : formatToolSuccessSummary(name, result, "");
+  if (summary && summary !== "done") part.text = `${part.text.trimEnd()} (${summary})\n`;
+  state.activeToolContextPart = null;
+}

package/src/agent/turn/turn-runner.mjs

@@ -1,5 +1,5 @@
 import { resolveImageAttachmentReferences } from "../../session/attachment-references.mjs";
-import { closeAssistantReply, createTurnEventState, handleRunnerSessionEvent } from "./turn-events.mjs";
+import { closeAssistantReply, compactAssistantContext, createTurnEventState, handleRunnerSessionEvent } from "./turn-events.mjs";
 
 export async function runRunnerTurn({
   prompt,
@@ -122,6 +122,7 @@ function finalizeTurn({ prompt, userMessage, userRecallHints, currentProject, me
   engine.recordTurn({
     userMessage: userMessage ?? prompt.slice(0, 300),
     assistantMessage: turnState.draft,
+    assistantContext: compactAssistantContext(turnState),
     userRecallHints,
     assistantRecallHints: recordedAssistantRecallHints,
   });

package/src/agent/vision-capability.mjs

@@ -0,0 +1,14 @@
+export function modelSupportsImageInput(model) {
+  if (!model || typeof model !== "object") return false;
+  if (Array.isArray(model.input) && model.input.includes("image")) return true;
+  if (model.capabilities?.images === true || model.capabilities?.vision === true) return true;
+  return false;
+}
+
+export function currentModelImageInputError(getCurrentModel) {
+  if (typeof getCurrentModel !== "function") return null;
+  const model = getCurrentModel();
+  if (modelSupportsImageInput(model)) return null;
+  const label = model ? `${model.name || model.id || "unknown"} (${model.provider || "unknown provider"})` : "unknown";
+  return `Current model does not support image input: ${label}. Switch to a vision-capable model before using read_image or screen.`;
+}

package/src/cli/args.mjs

@@ -11,6 +11,8 @@ export function parseCliArgs(argv) {
       extension: { type: "string", short: "e", multiple: true },
       extension: { type: "string", short: "e", multiple: true },
       config: { type: "boolean" },
+      "include-key": { type: "boolean" },
+      "profile-only": { type: "boolean" },
       "dump-context": { type: "boolean" },
       "pi-sessions": { type: "boolean" },
       "pi-runtime-host": { type: "boolean" },
@@ -33,6 +35,8 @@ export function parseCliArgs(argv) {
     extensions: values.extension ?? [],
     dumpContext: values["dump-context"] ?? false,
     providerConfig: values.config ?? false,
+    includeKey: values["include-key"] ?? false,
+    profileOnly: values["profile-only"] ?? false,
     piSessions: values["pi-sessions"] ?? false,
     piRuntimeHost: values["pi-runtime-host"] ?? false,
     shellRuntime: values["no-shell-runtime"] ? false : true,
@@ -50,6 +54,8 @@ Usage:
   march [options]            (starts REPL)
   march login [provider]     Login to an OAuth provider
   march provider --config    Configure provider credentials
+  march provider share [id]  Share a provider profile
+  march provider accept <token>
   march websearch --config  Configure web search credentials
 
 Options:
@@ -58,6 +64,8 @@ Options:
   --resume <id>        Resume a pi session by default
   --json               JSON output mode (no TUI)
   --config             With provider/websearch command, open configuration
+  --include-key        With provider share, include API key
+  --profile-only       With provider share, omit API key
   --dump-context       Write every prompt sent to the model under .march/context-dumps/
   --pi-sessions        Force pi JSONL SessionManager persistence
   --pi-runtime-host    Force pi AgentSessionRuntime host path

package/src/cli/commands/copy-command.mjs

@@ -61,13 +61,27 @@ export function writeSystemClipboardAsync(text, { platform = process.platform }
   });
 }
 
-function clipboardCommand(platform) {
+export function clipboardCommand(platform) {
   if (platform === "win32") {
     return {
       bin: "powershell.exe",
-      args: ["-NoProfile", "-Command", "Set-Clipboard -Value ([Console]::In.ReadToEnd())"],
+      args: ["-NoProfile", "-EncodedCommand", encodePowerShellCommand(readUtf8StdinToClipboardScript())],
     };
   }
   if (platform === "darwin") return { bin: "pbcopy", args: [] };
   return { bin: "sh", args: ["-lc", "command -v wl-copy >/dev/null && wl-copy || xclip -selection clipboard || xsel --clipboard --input"] };
 }
+
+function readUtf8StdinToClipboardScript() {
+  return [
+    "$stdin = [Console]::OpenStandardInput()",
+    "$memory = New-Object System.IO.MemoryStream",
+    "$stdin.CopyTo($memory)",
+    "$text = [System.Text.Encoding]::UTF8.GetString($memory.ToArray())",
+    "Set-Clipboard -Value $text",
+  ].join("; ");
+}
+
+function encodePowerShellCommand(script) {
+  return Buffer.from(script, "utf16le").toString("base64");
+}

package/src/cli/commands/status-command.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { MODES, formatModeLabel } from "../input/mode-state.mjs";
-import { PREFIX, R } from "../tui/ui-theme.mjs";
+import { modeLabel, PREFIX, R } from "../tui/ui-theme.mjs";
 
 export function statusCommand({
   runner,
@@ -78,9 +78,7 @@ export function formatStatusBarLine({
 
   const C = PREFIX; // foreground-only color prefixes (no reset)
   const DIM = C.brightBlack;
-  const OK = "\x1b[32m";  // green, no reset
-  const WARN = "\x1b[33m"; // yellow, no reset
-  const modeSegment = `${mode === MODES.DISCUSS ? WARN : OK}${formatModeLabel(mode)}`;
+  const modeSegment = formatModeSegment(mode);
   const runtime = `${C.cyan}${model}${DIM}·${thinking}`;
   const segments = [modeSegment, runtime];
   const lspText = formatLspSegment(lspStatus);
@@ -94,6 +92,11 @@ export function formatStatusBarLine({
   return `${inner}${R}`;
 }
 
+function formatModeSegment(mode) {
+  const label = formatModeLabel(mode);
+  return (modeLabel[mode] ?? modeLabel.fallback)(label);
+}
+
 export function formatLspSegment(lspStatus) {
   if (!lspStatus) return "";
   const servers = lspStatus.servers ?? [];

package/src/cli/commands/thinking-command.mjs

@@ -55,9 +55,9 @@ export async function handleThinkingCommand(parsed, { runner, ui = null } = {})
       runner.getThinkingLevel?.(),
     );
   }
-  if (parsed.type === "select") return [selectThinkingByIndex(parsed.index, { runner })];
+  if (parsed.type === "select") return [await selectThinkingByIndexAsync(parsed.index, { runner })];
   if (parsed.type === "set") {
-    const level = runner.setThinkingLevel(parsed.level);
+    const level = await runner.setThinkingLevel(parsed.level);
     return [`thinking: ${level}`];
   }
   if (parsed.type === "error") return [`Error: ${parsed.message}`];
@@ -76,5 +76,12 @@ async function selectThinkingInteractively({ runner, ui }) {
     suppressInitialConfirm: true,
   });
   if (!item) return "thinking: unchanged";
-  return `thinking: ${runner.setThinkingLevel(item.level)}`;
+  return `thinking: ${await runner.setThinkingLevel(item.level)}`;
+}
+
+async function selectThinkingByIndexAsync(index, { runner }) {
+  const levels = runner.getAvailableThinkingLevels?.() || THINKING_LEVELS;
+  const level = levels[index - 1];
+  if (!level) return `Error: thinking index out of range: ${index}`;
+  return `thinking: ${await runner.setThinkingLevel(level)}`;
 }

package/src/cli/repl-loop.mjs

@@ -119,7 +119,9 @@ export async function runInteractiveRepl({
 export function contextTokenRefreshOptions(slashResult, runner) {
   if (!slashResult?.refreshContextTokens) return undefined;
   if (typeof runner.estimateContextTokens !== "function") return undefined;
-  return { contextTokens: runner.estimateContextTokens("") };
+  const contextTokens = runner.estimateContextTokens("");
+  if (contextTokens && typeof contextTokens.then === "function") return undefined;
+  return { contextTokens };
 }
 
 function handleInlineCommand(trimmed, { cwd, ui, lastInlineShellCommand }) {

package/src/cli/startup/create-runtime-runner.mjs

@@ -0,0 +1,61 @@
+import { createRunner } from "../../agent/runner.mjs";
+import { createRunnerProcessClient } from "../../agent/runtime/runner-process-client.mjs";
+import { resolvePiSessionManager } from "../../session/pi-manager.mjs";
+
+export async function createRuntimeRunner({
+  useRuntimeProcess = false,
+  runnerOptions,
+  ui,
+  memoryStore,
+  memoryTools,
+  shellRuntime,
+  mcpTools,
+  mcpInjections,
+  mcpClientManager,
+  webTools,
+  usePiSessions,
+  usePiRuntimeHost,
+  authStorage,
+  permissionController,
+  modelContextDumper,
+  turnNotifier,
+  logger,
+  refreshStatusBar,
+} = {}) {
+  const onModelPayload = ({ estimatedTokens }) => {
+    refreshStatusBar?.({ contextTokens: estimatedTokens });
+  };
+
+  const runner = useRuntimeProcess
+    ? (await createRunnerProcessClient({ runnerOptions, ui, onModelPayload })).runner
+    : await createRunner({
+      ...runnerOptions,
+      ui,
+      memoryStore,
+      memoryTools,
+      shellRuntime,
+      mcpTools,
+      mcpInjections,
+      mcpClientManager,
+      webTools,
+      sessionManager: resolvePiSessionManager({
+        cwd: runnerOptions.cwd,
+        projectMarchDir: runnerOptions.projectMarchDir,
+        enabled: usePiSessions,
+      }),
+      useRuntimeHost: usePiRuntimeHost,
+      syncPiSidecar: usePiSessions || usePiRuntimeHost,
+      authStorage,
+      maxTurns: runnerOptions.config?.maxTurns ?? undefined,
+      trimBatch: runnerOptions.config?.trimBatch ?? undefined,
+      hostedTools: runnerOptions.config?.hostedTools,
+      permissionController,
+      modelContextDumper,
+      turnNotifier,
+      logger,
+      onModelPayload,
+    });
+
+  runner.shellRuntime ??= shellRuntime;
+  return runner;
+}

package/src/cli/startup/startup-banner.mjs

@@ -1,17 +1,71 @@
-import { MODES } from "../input/mode-state.mjs";
-import { bold, brightBlack, cyan } from "../tui/ui-theme.mjs";
+import { createRequire } from "node:module";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { MODES, formatModeLabel } from "../input/mode-state.mjs";
+import { brightBlack, cyan, modeLabel, white } from "../tui/ui-theme.mjs";
+
+const CARD_WIDTH = 76;
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const { version: packageVersion = "0.1" } = createRequire(import.meta.url)("../../../package.json");
 
 export function formatStartupBanner({ cwd, modelId = "model?", thinkingLevel = "thinking?", mode = MODES.DO, dumpContextPath = null } = {}) {
-  const nextMode = mode === MODES.DISCUSS ? "Do" : "Discuss";
-  const hint = dumpContextPath
-    ? brightBlack(`dumps: ${dumpContextPath}`)
-    : brightBlack(`Tab to ${nextMode} · /help`);
+  const nextMode = mode === MODES.DISCUSS ? MODES.DO : MODES.DISCUSS;
+  const tip = dumpContextPath
+    ? `${brightBlack("Tip:")} ${cyan("dumps:")} ${brightBlack(dumpContextPath)}`
+    : `${brightBlack("Tip:")} ${brightBlack("Tab to")} ${formatModeTip(nextMode)} ${brightBlack("·")} ${cyan("/help")} ${brightBlack("for commands")}`;
   return [
-    `${cyan("  █▙  ▟█")}   ${bold("March")}`,
-    `${cyan("  █▜▙▟▛█")}   ${brightBlack(`${modelId} · ${thinkingLevel}`)}`,
-    `${cyan("  ▀    ▀")}   ${brightBlack(cwd ?? "")}`,
     "",
-    `  ${hint}`,
+    ...renderStartupCard([
+      `${cyan("  █▙  ▟█")}   ${white("March")} ${brightBlack(`v${packageVersion}`)}`,
+      `${cyan("  █▜▙▟▛█")}   ${brightBlack("Describe a task to get started.")}`,
+      `${cyan("  ▀    ▀")}`,
+      "",
+      tip,
+      brightBlack("March uses AI. Check for mistakes."),
+    ]),
     "",
   ];
 }
+
+function formatModeTip(mode) {
+  const label = formatModeLabel(mode);
+  return (modeLabel[mode] ?? modeLabel.fallback)(label);
+}
+
+function renderStartupCard(contentLines, width = CARD_WIDTH) {
+  const safeWidth = Math.max(24, Math.trunc(width));
+  const innerWidth = safeWidth - 4;
+  return [
+    white(`╭${"─".repeat(safeWidth - 2)}╮`),
+    ...contentLines.map((line) => white("│ ") + padAnsi(line, innerWidth) + white(" │")),
+    white(`╰${"─".repeat(safeWidth - 2)}╯`),
+  ];
+}
+
+function padAnsi(text, width) {
+  const clipped = clipAnsi(text, width);
+  const padding = Math.max(0, width - visibleWidth(stripAnsi(clipped)));
+  return `${clipped}${" ".repeat(padding)}`;
+}
+
+function clipAnsi(text, width) {
+  let output = "";
+  let plainWidth = 0;
+  let inAnsi = false;
+  for (const ch of Array.from(String(text ?? ""))) {
+    if (ch === "\x1b") inAnsi = true;
+    if (inAnsi) {
+      output += ch;
+      if (/[@-~]/.test(ch)) inAnsi = false;
+      continue;
+    }
+    const charWidth = visibleWidth(ch);
+    if (plainWidth + charWidth > width) break;
+    output += ch;
+    plainWidth += charWidth;
+  }
+  return output;
+}
+
+function stripAnsi(text) {
+  return String(text ?? "").replace(ANSI_RE, "");
+}

package/src/cli/tui/layout/main-pane-layout.mjs

@@ -9,19 +9,28 @@ export class MainPaneLayout {
 
   render(width) {
     const safeWidth = Math.max(1, Math.trunc(width));
-    const statusLines = this.statusBar.render(safeWidth);
-    const editorLines = this.editor.render(safeWidth);
-    const fixedHeight = statusLines.length + editorLines.length;
+    const statusTopLines = this.statusBar.renderTop?.(safeWidth) ?? this.statusBar.render(safeWidth);
+    const rawEditorLines = this.editor.render(safeWidth);
+    const editorLines = this.statusBar.renderInputLines?.(rawEditorLines, safeWidth)
+      ?? rawEditorLines.map((line) => this.statusBar.renderInputLine?.(line, safeWidth) ?? line);
+    const statusBottomLines = this.statusBar.renderBottom?.(safeWidth) ?? [];
+    const fixedHeight = statusTopLines.length + editorLines.length + statusBottomLines.length;
     const viewportHeight = Math.max(1, (this.terminal?.rows || 30) - fixedHeight);
     this.output.setViewportHeight(viewportHeight);
     const outputLines = this.output.render(safeWidth);
     const outputTop = Math.max(0, viewportHeight - outputLines.length);
-    this.selection?.setViewport({ topRow: outputTop, leftCol: 0, width: safeWidth, lines: outputLines });
-    const selectedOutputLines = this.selection?.apply(outputLines) ?? outputLines;
+    const editorTop = viewportHeight + statusTopLines.length;
+    this.selection?.setRegions?.([
+      { id: "output", topRow: outputTop, leftCol: 0, width: safeWidth, lines: outputLines },
+      { id: "editor", topRow: editorTop, leftCol: 0, width: safeWidth, lines: editorLines },
+    ]);
+    const selectedOutputLines = this.selection?.applyRegion?.("output", outputLines) ?? outputLines;
+    const selectedEditorLines = this.selection?.applyRegion?.("editor", editorLines) ?? editorLines;
     return [
       ...padToHeight(selectedOutputLines, viewportHeight),
-      ...statusLines,
-      ...editorLines,
+      ...statusTopLines,
+      ...selectedEditorLines,
+      ...statusBottomLines,
     ];
   }
 

package/src/cli/tui/selection-screen.mjs

@@ -9,30 +9,37 @@ export class ScreenSelection {
     this.active = false;
     this.anchor = null;
     this.focus = null;
-    this.lines = [];
-    this._plainLines = [];
+    this.regions = [];
+    this._plainLines = new Map();
     this.viewport = { topRow: 0, leftCol: 0, width: Infinity, height: 0 };
   }
 
   setLines(lines) {
-    this.lines = [...lines];
-    this._plainLines = [];
-    this.viewport = { topRow: 0, leftCol: 0, width: Infinity, height: this.lines.length };
+    this.setViewport({ topRow: 0, leftCol: 0, width: Infinity, lines });
   }
 
   setViewport({ topRow = 0, leftCol = 0, width = Infinity, lines = [] } = {}) {
-    this.lines = lines;
-    this._plainLines = [];
-    this.viewport = {
-      topRow: Math.max(0, Math.trunc(topRow)),
-      leftCol: Math.max(0, Math.trunc(leftCol)),
-      width: Number.isFinite(width) ? Math.max(1, Math.trunc(width)) : Infinity,
-      height: this.lines.length,
-    };
+    this.setRegions([{ id: "default", topRow, leftCol, width, lines }]);
+  }
+
+  setRegions(regions = []) {
+    let docRow = 0;
+    this.regions = regions
+      .map((region, index) => normalizeRegion(region, index))
+      .filter((region) => region.lines.length > 0)
+      .sort((a, b) => a.topRow - b.topRow || a.leftCol - b.leftCol)
+      .map((region) => {
+        const normalized = { ...region, docStart: docRow };
+        docRow += region.lines.length;
+        return normalized;
+      });
+    this.lines = this.regions.flatMap((region) => region.lines);
+    this._plainLines = new Map();
+    this.viewport = { topRow: 0, leftCol: 0, width: Infinity, height: this.lines.length };
   }
 
   start(point) {
-    const normalized = normalizePoint(point, this.viewport, true);
+    const normalized = normalizePoint(point, this.regions, true);
     if (!normalized) {
       this.clear();
       return false;
@@ -45,13 +52,13 @@ export class ScreenSelection {
 
   update(point) {
     if (!this.active || !this.anchor) return false;
-    this.focus = normalizePoint(point, this.viewport, true) ?? this.focus;
+    this.focus = normalizePoint(point, this.regions, true) ?? this.focus;
     return true;
   }
 
   finish(point, { clear = true } = {}) {
     if (!this.active || !this.anchor) return "";
-    this.focus = normalizePoint(point, this.viewport, true) ?? this.focus;
+    this.focus = normalizePoint(point, this.regions, true) ?? this.focus;
     const text = this.text();
     if (clear) this.clear();
     else this.active = false;
@@ -80,21 +87,27 @@ export class ScreenSelection {
   }
 
   apply(lines) {
+    return this.applyRegion("default", lines);
+  }
+
+  applyRegion(id, lines) {
     const range = this.range();
-    if (!range) return lines;
+    const region = this.regions.find((candidate) => candidate.id === id);
+    if (!range || !region) return lines;
     return lines.map((line, row) => {
-      if (row < range.start.row || row > range.end.row) return line;
-      const plain = this._plainLine(row);
-      const startCol = row === range.start.row ? range.start.col : 0;
-      const endCol = row === range.end.row ? range.end.col : visibleWidth(plain);
+      const docRow = region.docStart + row;
+      if (docRow < range.start.row || docRow > range.end.row) return line;
+      const plain = this._plainLine(docRow);
+      const startCol = docRow === range.start.row ? range.start.col : 0;
+      const endCol = docRow === range.end.row ? range.end.col : visibleWidth(plain);
       if (endCol <= startCol) return line;
       return highlightAnsiLine(line, startCol, endCol);
     });
   }
 
   _plainLine(row) {
-    if (this._plainLines[row] == null) this._plainLines[row] = stripAnsi(this.lines[row] ?? "");
-    return this._plainLines[row];
+    if (!this._plainLines.has(row)) this._plainLines.set(row, stripAnsi(this.lines[row] ?? ""));
+    return this._plainLines.get(row);
   }
 
   range() {
@@ -111,19 +124,55 @@ export function stripAnsi(text) {
   return String(text ?? "").replace(CONTROL_RE, "");
 }
 
-function normalizePoint({ row, col }, viewport, clamp) {
+function normalizeRegion(region, index) {
+  const lines = [...(region.lines ?? [])];
+  const width = Number.isFinite(region.width) ? Math.max(1, Math.trunc(region.width)) : Infinity;
+  return {
+    id: region.id ?? `region-${index}`,
+    lines,
+    topRow: Math.max(0, Math.trunc(region.topRow ?? 0)),
+    leftCol: Math.max(0, Math.trunc(region.leftCol ?? 0)),
+    width,
+  };
+}
+
+function normalizePoint({ row, col }, regions, clamp) {
   const screenRow = Math.trunc(row) - 1;
   const screenCol = Math.trunc(col) - 1;
-  const height = viewport?.height ?? 0;
-  if (height <= 0) return null;
-
-  let localRow = screenRow - (viewport?.topRow ?? 0);
-  let localCol = screenCol - (viewport?.leftCol ?? 0);
-  const maxCol = Number.isFinite(viewport?.width) ? viewport.width : Infinity;
-  if (!clamp && (localRow < 0 || localRow >= height || localCol < 0 || localCol > maxCol)) return null;
-  localRow = clampNumber(localRow, 0, height - 1);
-  localCol = clampNumber(localCol, 0, maxCol);
-  return { row: localRow, col: localCol };
+  if (regions.length === 0) return null;
+
+  for (const region of regions) {
+    const localRow = screenRow - region.topRow;
+    const localCol = screenCol - region.leftCol;
+    const maxCol = Number.isFinite(region.width) ? region.width : Infinity;
+    if (localRow >= 0 && localRow < region.lines.length) {
+      if (!clamp && (localCol < 0 || localCol > maxCol)) return null;
+      return {
+        row: region.docStart + localRow,
+        col: clampNumber(localCol, 0, maxCol),
+      };
+    }
+  }
+
+  if (!clamp) return null;
+  const first = regions[0];
+  const last = regions.at(-1);
+  if (screenRow < first.topRow) return { row: first.docStart, col: 0 };
+  if (screenRow > last.topRow + last.lines.length - 1) {
+    return { row: last.docStart + last.lines.length - 1, col: last.width };
+  }
+
+  let nearest = null;
+  for (const region of regions) {
+    const beforeDistance = Math.abs(screenRow - region.topRow);
+    const afterDistance = Math.abs(screenRow - (region.topRow + region.lines.length - 1));
+    const before = { row: region.docStart, col: 0, distance: beforeDistance };
+    const after = { row: region.docStart + region.lines.length - 1, col: region.width, distance: afterDistance };
+    for (const candidate of [before, after]) {
+      if (!nearest || candidate.distance < nearest.distance) nearest = candidate;
+    }
+  }
+  return nearest ? { row: nearest.row, col: nearest.col } : null;
 }
 
 function comparePoints(a, b) {