Open transcript URLs on modifier click

Markdown prose stays terminal-owned: its renderers expose no text-leaf API to highlight or hit-test.

Author: TheGreatAxios

docs/TUI.md

@@ -819,6 +819,28 @@ running its own selection. Two chords cover remaining copy needs:
   52 escape sequence when no helper is available, e.g. over SSH). On a
   coalesced tool lane the copy resolves to the most recent call's full
   output; a single-call row copies its own output, exactly as before.
+- **URL click-through (CL-7346).** Holding the platform modifier over an
+  `http(s)` URL in a plain or structured-text transcript row underlines it;
+  pressing and releasing on the same URL opens it in the default browser,
+  while a press that releases anywhere else stays a selection gesture:
+  - **macOS: Cmd+click.** The terminal itself owns this chord: every link
+    span carries OSC-8 metadata, so the emulator opens the URL and the app
+    never sees the press.
+  - **Linux/Windows: Ctrl+click.** The app opens the URL through the
+    platform opener (`open` on macOS as fallback, `xdg-open`, `cmd /c
+start`).
+  - Without the modifier, nothing changes: clicks still expand rows and
+    drags still select-and-copy. With mouse capture off (Alt+M), the
+    terminal owns every click and the app sees none, so there is nothing to
+    fight over. Non-`http(s)` targets (`file:`, `mailto:`, `javascript:`,
+    …) never open anywhere — the gate parses the scheme, it does not
+    prefix-match. Hover highlighting needs pointer-motion reports, so the
+    main shell enables them (`enableMouseMovement`, DEC ?1003) alongside
+    the existing capture; the pickers and setup screens stay opted out.
+  - Markdown prose (assistant messages) is not covered: the renderer paints
+    it through childless code renderers with no stable text-leaf API to
+    highlight or hit-test, so those links stay terminal business until the
+    library exposes one.
 
 Arrow keys never scroll anything — inside the prompt they are caret motion
 or, at the buffer's edges, prompt-history recall; inside an open overlay's
@@ -889,7 +911,11 @@ terminal. It cannot observe:
   Alt+letter, or similar modifier combinations depends on the terminal
   negotiating the kitty keyboard protocol (or an equivalent) with the actual
   host terminal emulator — the headless harness has no such negotiation to
-  fail or succeed at.
+  fail or succeed at. URL click-through (CL-7346) inherits this: the unit
+  and headless suites pin the gating (Ctrl+press opens, plain click and
+  Ctrl+drag do not, non-`http(s)` never opens) with a mocked opener, but
+  only a real terminal can show whether it delivers the held Ctrl on motion
+  and press events, or resolves the `open`/`xdg-open` spawn into a browser.
 - **The system clipboard.** `system-clipboard.ts`'s helper-binary spawns and
   OSC 52 fallback are exercised with mocked spawn functions in tests; no
   test round-trips through a real `pbcopy`/`xclip`/terminal clipboard.

src/tui/product-host.ts

@@ -280,10 +280,14 @@ export async function mountProductHost(
         // Cost accepted: this suppresses the terminal's *native* drag-select
         // in the main shell. OpenTUI selection still works and auto-copies
         // on mouse-up; Alt+M hands the mouse back when native select is wanted.
-        // enableMouseMovement stays off (no ?1003): only clicks and wheel
-        // are needed.
+        // enableMouseMovement stays on (?1003): URL hover highlighting
+        // (CL-7346) needs pointer motion with the modifier held — clicks and
+        // wheel alone never report where an unpressed pointer is. Cost
+        // accepted alongside the native-drag-select one above: a motion event
+        // per pointer move while capture is on; Alt+M still hands the mouse
+        // back when native select is wanted.
         useMouse: config.useMouse ?? true,
-        enableMouseMovement: false,
+        enableMouseMovement: true,
         // A plain terminal sends a bare CR for both Enter and Shift+Enter, so
         // the modifier only arrives once the kitty keyboard protocol is
         // negotiated. Empty object, not explicit flags: this matches what

src/tui/shell/row-retext.ts

@@ -7,7 +7,6 @@
  */
 import {
   BoxRenderable,
-  StyledText,
   TextRenderable,
   TextTableRenderable,
   bold as boldChunk,
@@ -17,6 +16,7 @@ import {
 } from "@opentui/core";
 import { stringWidth } from "../view/height.js";
 import { viewToTableContent, type McpStructuredView } from "../mcp-view.js";
+import { splitLinkSpans, paintLinkLine } from "../url-links.js";
 import {
   splitTrailingArrow,
   expandedRowLines,
@@ -125,13 +125,15 @@ function retextBodyLine(
   const split = splitTrailingArrow(line);
   if (node instanceof TextRenderable) {
     if (split !== null) return false;
-    node.content = new StyledText(diffLineChunks(line));
+    // A URL appearing or disappearing repaints on the same node; re-arming
+    // refreshes the hit ranges, so hover never resolves against stale text.
+    paintLinkLine(node, [splitLinkSpans(line)]);
     return true;
   }
   if (!(node instanceof BoxRenderable) || split === null) return false;
   const [bodyNode] = node.getChildren();
   if (!(bodyNode instanceof TextRenderable)) return false;
-  bodyNode.content = new StyledText(diffLineChunks(split.body));
+  paintLinkLine(bodyNode, [splitLinkSpans(split.body)]);
   return true;
 }
 

src/tui/shell/transcript.ts

@@ -12,6 +12,12 @@ import {
 } from "@opentui/core";
 import { stringWidth } from "../view/height.js";
 import { viewToTableContent, type McpStructuredView } from "../mcp-view.js";
+import {
+  buildLinkLine,
+  findLinks,
+  paintLinkLine,
+  splitLinkSpans,
+} from "../url-links.js";
 import {
   splitAtSettledHeading,
   withholdIncompleteHeading,
@@ -198,7 +204,7 @@ function retextStreamRowBody(
     return false;
   if (node instanceof TextRenderable) {
     if (isMarkdownRow(row)) return false;
-    node.content = paintStreamRow(row, layout).content;
+    paintPlainRowNode(node, paintStreamRow(row, layout));
     return true;
   }
 
@@ -347,11 +353,7 @@ export function buildRowNode(
   }
 
   if (!isMarkdownRow(row)) {
-    const painted = paintStreamRow(row, layout);
-    return new TextRenderable(ctx, {
-      content: painted.content,
-      fg: painted.fg,
-    });
+    return buildPlainRowNode(ctx, paintStreamRow(row, layout));
   }
 
   const gutter = streamRowGutter(row, layout);
@@ -375,6 +377,44 @@ function markdownBodyOptions(gutter: PaintedStreamLine, width: number) {
   } as const;
 }
 
+/**
+ * A literal-text row's paint node: always a single text node, as before. Rows
+ * holding URLs paint styled text (URL spans carry OSC-8 metadata) and arm as
+ * Ctrl+click targets; URL-free rows paint the plain string they always have.
+ */
+function buildPlainRowNode(
+  ctx: CliRenderer,
+  painted: PaintedStreamLine,
+): TextRenderable {
+  const node = new TextRenderable(ctx, {
+    content: painted.content,
+    fg: painted.fg,
+  });
+  paintPlainRowNode(node, painted);
+  return node;
+}
+
+/**
+ * Rewrite a plain row's text on its existing node. The node never changes
+ * shape, so a URL appearing or disappearing repaints in place instead of
+ * forcing a rebuild.
+ */
+function paintPlainRowNode(
+  node: TextRenderable,
+  painted: PaintedStreamLine,
+): void {
+  const lines = painted.content.split("\n");
+  if (!lines.some((line) => findLinks(line).length > 0)) {
+    node.content = painted.content;
+    node.fg = painted.fg;
+    return;
+  }
+  paintLinkLine(
+    node,
+    lines.map((line) => splitLinkSpans([{ text: line, fg: painted.fg }])),
+  );
+}
+
 /**
  * A markdown row's body. Most rows have no settled heading yet (no heading at
  * all, or the only one is still the open tail), and paint through a single
@@ -396,10 +436,10 @@ function createMarkdownBody(
   const content = markdownContent(row);
   const split = splitAtSettledHeading(content);
   if (split === null) {
+    // Native incremental block stability: only the trailing block is unstable.
     return new MarkdownRenderable(ctx, {
       ...markdownBodyOptions(gutter, width),
       content,
-      // Native incremental block stability: only the trailing block is unstable.
       streaming: row.streaming === true,
     });
   }
@@ -454,8 +494,9 @@ function createStyledLinesRowRenderable(
 
 /**
  * One painted body line. A line ending in an expand arrow is split so the
- * arrow is its own renderable and can answer a click; every other line is a
- * single text node, as before.
+ * arrow is its own renderable and can answer a click; a line holding URLs
+ * paints styled text and arms as a Ctrl+click target (see url-links.ts);
+ * every other line is a single text node, as before.
  */
 function bodyLineNode(
   ctx: CliRenderer,
@@ -464,17 +505,12 @@ function bodyLineNode(
 ): TextRenderable | BoxRenderable {
   const split = onToggle === undefined ? null : splitTrailingArrow(line);
   if (split === null || onToggle === undefined) {
-    return new TextRenderable(ctx, {
-      content: new StyledText(diffLineChunks(line)),
-    });
+    return buildLinkLine(ctx, splitLinkSpans(line));
   }
   const wrapper = new BoxRenderable(ctx, { flexDirection: "row", flexGrow: 1 });
-  wrapper.add(
-    new TextRenderable(ctx, {
-      content: new StyledText(diffLineChunks(split.body)),
-      flexShrink: 0,
-    }),
-  );
+  const body = buildLinkLine(ctx, splitLinkSpans(split.body));
+  body.flexShrink = 0;
+  wrapper.add(body);
   wrapper.add(
     new TextRenderable(ctx, {
       content: new StyledText(diffLineChunks([split.arrow])),

src/tui/url-click.test.ts

@@ -0,0 +1,126 @@
+/**
+ * URL click-through (CL-7346): Ctrl+click opens an http(s) URL in the
+ * default browser; a plain click keeps today's row behavior.
+ *
+ * The opener is mocked (setUrlOpener) — no test spawns a real browser.
+ * Whether a real terminal reports the Ctrl modifier is a harness blind
+ * spot (docs/TUI.md); headless, the mock delivers it like any click.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { defined } from "../../tests/helpers/defined.js";
+import { withTestRenderer } from "./harness";
+import { appendStreamRow } from "./shell/chrome";
+import { createAppShell } from "./shell/index";
+import { isUnderlined, resetUrlOpener, setUrlOpener } from "./url-links";
+import { type StreamRow } from "./stream";
+
+const CALL: StreamRow = {
+  role: "tool",
+  text: "",
+  meta: "web_fetch",
+  verb: "Web Fetch",
+  summary: "see https://www.example.com/docs for details",
+  detail: [[{ text: "url: https://www.example.com/docs", fg: "#f7ead5" }]],
+};
+
+/** Screen position of the first cell of `needle`, or null when not painted. */
+function findCell(
+  frame: string,
+  needle: string,
+): { readonly x: number; readonly y: number } | null {
+  const lines = frame.split("\n");
+  for (const [y, line] of lines.entries()) {
+    const x = line.indexOf(needle);
+    if (x !== -1) return { x, y };
+  }
+  return null;
+}
+
+describe("Ctrl+clicking a transcript URL", () => {
+  test("opens it, while plain click and Ctrl+drag do not", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "idle",
+        });
+        const opened: string[] = [];
+        setUrlOpener((url) => {
+          opened.push(url);
+        });
+        try {
+          appendStreamRow(shell, CALL);
+          await h.renderOnce();
+
+          const link = findCell(h.captureCharFrame(), "example.com");
+          expect(link).not.toBeNull();
+          const at = defined(link);
+
+          await h.mockMouse.click(at.x, at.y, 0, {
+            modifiers: { ctrl: true },
+          });
+          await h.renderOnce();
+          expect(opened).toEqual(["https://www.example.com/docs"]);
+
+          opened.length = 0;
+          await h.mockMouse.click(at.x, at.y);
+          await h.renderOnce();
+          expect(opened).toEqual([]);
+          expect(shell.streamLog[0]?.expanded).not.toBe(true);
+
+          await h.mockMouse.drag(at.x, at.y, at.x + 12, at.y, 0, {
+            modifiers: { ctrl: true },
+          });
+          await h.renderOnce();
+          expect(opened).toEqual([]);
+        } finally {
+          resetUrlOpener();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
+  test("Ctrl+hover underlines the link until the pointer leaves it", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "idle",
+        });
+        try {
+          appendStreamRow(shell, CALL);
+          await h.renderOnce();
+
+          const link = findCell(h.captureCharFrame(), "example.com");
+          expect(link).not.toBeNull();
+          const at = defined(link);
+
+          const linkSpanUnderlined = (): boolean =>
+            defined(h.captureSpans().lines[at.y]).spans.some(
+              (span) =>
+                span.text.includes("example.com") &&
+                isUnderlined(span.attributes),
+            );
+
+          await h.mockMouse.moveTo(at.x, at.y, {
+            modifiers: { ctrl: true },
+          });
+          await h.renderOnce();
+          expect(linkSpanUnderlined()).toBe(true);
+
+          await h.mockMouse.moveTo(at.x, at.y);
+          await h.renderOnce();
+          expect(linkSpanUnderlined()).toBe(false);
+        } finally {
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+});