Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(terminal): link a path an agent wrapped under a hanging indent
review0f617f6699fb
diff --git a/CLAUDE.md b/CLAUDE.mdindex 35ed39d83..a41a11577 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1633,7 +1633,11 @@ session.never guesses from the browser. Standalone `ssh` terminal nodes remain URL-only because theyhave no remote fs API with which to verify a token; relay tabs do have a core-bound, jailed fsAPI and therefore support file links. Windows existence matching is case-insensitive and accepts- both separators; UNC tokens are refused whole before they can be reinterpreted as cwd-relative.+ both separators; UNC tokens are refused whole before they can be reinterpreted as cwd-relative. A path an+ agent TUI wrapped under a **hanging indent** (Codex: 2 spaces, broken after a `/` or at a space)+ is neither a soft nor a hard wrap, so it is offered as extra READINGS (`hangingReadings` — the+ seam as nothing, and as one space), tried BEFORE the plain row's tokens by both the provider and+ `linkAtCell`; existence decides, and a click on the indent is not a click on the path.**Right-click on a link** opens a link menu (pure `terminal/link-menu.ts`; the listener is`installLinkContextMenu`, beside the Cmd+click fallback and sharing its `linkAtCell` hit-test):Open / Reveal in Explorer / Download / Copy path for a file, Open in browser / canvas browser /diff --git a/src/renderer/terminal/file-links.hanging.test.ts b/src/renderer/terminal/file-links.hanging.test.tsnew file mode 100644index 000000000..22573a783--- /dev/null+++ b/src/renderer/terminal/file-links.hanging.test.ts@@ -0,0 +1,283 @@+// @vitest-environment jsdom+// Hanging-indent wraps: an agent TUI (Codex) wraps its own reply at a word boundary or after a `/`+// and indents the continuation under the bullet. Nothing in the buffer marks that — no wrapped+// flag, the row is not full, the next row starts with blanks — so neither half of a path wrapped+// that way linked. The seam is offered as extra READINGS, tried before the plain paragraph, and+// existence decides.+import { describe, expect, it } from "vitest";+import type { ILink, Terminal } from "@xterm/xterm";+import {+ createFileLinkProvider,+ installLinkClickFallback,+ installLinkContextMenu,+ linkAtCell,+ type LinkHit,+ type LinkHitDeps,+} from "./file-links";++const CELL_W = 10;+const CELL_H = 20;+const WIDE = /[ᄀ-ᅟ⺀-가-힣豈--⦆]/u;++interface FakeCell {+ chars: string;+ width: number;+}++function toCells(row: string, cols: number): FakeCell[] {+ const out: FakeCell[] = [];+ for (const ch of row) {+ if (WIDE.test(ch))+ out.push({ chars: ch, width: 2 }, { chars: "", width: 0 });+ else out.push({ chars: ch, width: 1 });+ }+ while (out.length < cols) out.push({ chars: "", width: 1 });+ return out.slice(0, cols);+}++/** A terminal whose buffer answers per cell (getChars/getWidth), plus the DOM the listeners use. */+function fakeTerm(rows: string[], cols = 40) {+ const cellRows = rows.map((r) => toCells(r, cols));+ const host = document.createElement("div");+ const screen = document.createElement("div");+ screen.className = "xterm-screen";+ screen.getBoundingClientRect = () =>+ ({+ left: 0,+ top: 0,+ width: cols * CELL_W,+ height: rows.length * CELL_H,+ }) as DOMRect;+ host.appendChild(screen);+ document.body.appendChild(host);+ const term = {+ cols,+ rows: rows.length,+ element: host,+ modes: { mouseTrackingMode: "vt200" },+ clearSelection: () => {},+ buffer: {+ active: {+ viewportY: 0,+ length: rows.length,+ getLine: (r: number) => {+ const cells = cellRows[r];+ if (!cells) return undefined;+ const str = cells+ .filter((c) => c.width !== 0)+ .map((c) => c.chars || " ")+ .join("");+ return {+ isWrapped: false,+ length: cols,+ translateToString: (trim: boolean) =>+ trim ? str.replace(/ +$/, "") : str,+ getCell: (x: number) => {+ const c = cells[x];+ return c && { getChars: () => c.chars, getWidth: () => c.width };+ },+ };+ },+ },+ },+ _core: { _oscLinkService: { getLinkData: () => undefined } },+ } as unknown as Terminal;+ return { term, host, screen };+}++const deps = (over: Partial<LinkHitDeps> = {}): LinkHitDeps => ({+ getCwd: () => "/home/me/proj",+ convention: () => ({}),+ fileEnabled: () => true,+ ...over,+});++type Fs = Record<string, "file" | "dir">;++const provide = (term: Terminal, row: number, fs: Fs): Promise<ILink[]> =>+ new Promise((resolve) => {+ createFileLinkProvider(term, {+ getCwd: () => "/home/me/proj",+ lookup: async (abs) => ({ exists: abs in fs, dir: fs[abs] === "dir" }),+ activate: () => {},+ }).provideLinks(row, (links) => resolve(links ?? []));+ });++function fire(+ target: HTMLElement,+ type: string,+ row: number,+ col: number,+ button: number,+ mod = false,+) {+ const ev = new MouseEvent(type, {+ bubbles: true,+ cancelable: true,+ button,+ metaKey: mod,+ clientX: col * CELL_W + 2,+ clientY: row * CELL_H + 2,+ });+ target.dispatchEvent(ev);+ return ev;+}+const settle = () => new Promise((r) => setTimeout(r, 0));++const clickOpens = async (+ rows: string[],+ cols: number,+ fs: Fs,+ row: number,+ col: number,+) => {+ const { term, host, screen } = fakeTerm(rows, cols);+ const opened: string[] = [];+ installLinkClickFallback(term, host, {+ ...deps(),+ lookup: async (abs) => ({ exists: abs in fs, dir: fs[abs] === "dir" }),+ activateFile: (abs) => opened.push(abs),+ openUrl: () => {},+ });+ const ev = fire(screen, "mouseup", row, col, 0, true);+ await settle();+ return { opened, swallowed: ev.defaultPrevented };+};++describe("a path the agent wrapped onto an indented row (the Codex report)", () => {+ // Measured shape, shortened to 62 columns: the break came after a `/`, with a 2-space hanging+ // indent, and the path has a space in it.+ const COLS = 62;+ const rows = [+ "• The file is at /Users/me/Claude/Claude Code/demo/feature-x/",+ " docs/gui-proposal/TEAM-ACCESS.md",+ ];+ const FILE =+ "/Users/me/Claude/Claude Code/demo/feature-x/docs/gui-proposal/TEAM-ACCESS.md";+ const fs: Fs = {+ [FILE]: "file",+ // The first row names a real directory on its own — it must not win over the file.+ "/Users/me/Claude/Claude Code/demo/feature-x/": "dir",+ "/Users/me/Claude/Claude Code/demo/feature-x": "dir",+ };++ it("the rows really are not a soft or hard wrap", () => {+ expect(rows[0].length).toBeLessThan(COLS);+ expect(+ rows[0].length + 1 + "docs/gui-proposal/TEAM-ACCESS.md".length,+ ).toBeGreaterThan(COLS);+ });++ it("hovering either row links the whole file, across both rows", async () => {+ const { term } = fakeTerm(rows, COLS);+ for (const row of [1, 2]) {+ const links = await provide(term, row, fs);+ expect(links.map((l) => [l.text, l.range])).toEqual([+ [+ "/Users/me/Claude/Claude Code/demo/feature-x/docs/gui-proposal/TEAM-ACCESS.md",+ { start: { x: 18, y: 1 }, end: { x: 34, y: 2 } },+ ],+ ]);+ }+ });++ it("Cmd+click on either half opens the file", async () => {+ for (const [row, col] of [+ [0, 20],+ [0, 40],+ [1, 5],+ ] as const) {+ expect((await clickOpens(rows, COLS, fs, row, col)).opened).toEqual([+ FILE,+ ]);+ }+ });++ it("the right-click hit names the joined path first", () => {+ const { term } = fakeTerm(rows, COLS);+ const hit = linkAtCell(term, 1, 5, deps()) as Extract<+ LinkHit,+ { kind: "path" }+ >;+ expect(hit.token).toBe(FILE);+ // The plain row's own reading is still there to fall back on.+ expect(hit.alternatives).toContain("docs/gui-proposal/TEAM-ACCESS.md");+ });++ it("a click on the indent is not a click on the path", async () => {+ const { term } = fakeTerm(rows, COLS);+ expect(linkAtCell(term, 1, 0, deps())).toBeNull();+ expect((await clickOpens(rows, COLS, fs, 1, 1)).swallowed).toBe(false);+ });+});++describe("a wrap that ate a space", () => {+ const COLS = 40;+ const rows = ["• see /data/My", " Documents/notes.md for it"];+ // `/data/My` fits on row 0 (14 cells); the wrapper broke because `Documents/notes.md` did not.+ const rowsAtWidth = ["• see /data/My Big", " Documents/notes.md for it"];++ it("links the spaced path when that is what exists", async () => {+ const { term } = fakeTerm(rowsAtWidth, 20);+ const links = await provide(term, 1, {+ "/data/My Big Documents/notes.md": "file",+ });+ expect(links.map((l) => l.text)).toEqual([+ "/data/My Big Documents/notes.md",+ ]);+ });++ it("does not join after a short line: an indented list is not a wrap", async () => {+ const { term } = fakeTerm(rows, COLS);+ const links = await provide(term, 1, {+ "/data/MyDocuments/notes.md": "file",+ "/data/My Documents/notes.md": "file",+ "/data/My": "dir",+ });+ expect(links.map((l) => l.text)).toEqual(["/data/My"]);+ });+});++describe("what stays exactly as it was", () => {+ it("a path on one row with nothing indented after it", async () => {+ const { term } = fakeTerm(["open src/a.ts now", "next line"], 40);+ const links = await provide(term, 1, { "/home/me/proj/src/a.ts": "file" });+ expect(links.map((l) => l.text)).toEqual(["src/a.ts"]);+ expect(linkAtCell(term, 0, 6, deps())).toEqual({+ kind: "path",+ token: "src/a.ts",+ abs: "/home/me/proj/src/a.ts",+ });+ });++ it("a joined reading that does not exist costs the plain links nothing", async () => {+ const rows = ["• edited /tmp/one/two.ts and then", " src/b.ts next"];+ const { term } = fakeTerm(rows, 36);+ const links = await provide(term, 1, {+ "/tmp/one/two.ts": "file",+ "/home/me/proj/src/b.ts": "file",+ });+ expect(links.map((l) => l.text)).toEqual(["/tmp/one/two.ts"]);+ const second = await provide(term, 2, {+ "/tmp/one/two.ts": "file",+ "/home/me/proj/src/b.ts": "file",+ });+ expect(second.map((l) => l.text)).toEqual(["src/b.ts"]);+ });++ it("a right-click under a hanging row still falls back to the row's own path", () => {+ const rows = ["• wrote /tmp/one/two/three.ts", " and-more-words-here.txt"];+ const { term, host, screen } = fakeTerm(rows, 36);+ const opened: LinkHit[] = [];+ installLinkContextMenu(term, host, {+ ...deps(),+ openMenu: (hit) => opened.push(hit),+ });+ fire(screen, "mousedown", 0, 10, 2);+ fire(screen, "contextmenu", 0, 10, 2);+ expect(opened[0]).toMatchObject({ kind: "path" });+ expect(opened[0].kind === "path" && opened[0].alternatives).toContain(+ "/tmp/one/two/three.ts",+ );+ });+});diff --git a/src/renderer/terminal/file-links.ts b/src/renderer/terminal/file-links.tsindex c8621c00c..225a3cdbb 100644--- a/src/renderer/terminal/file-links.ts+++ b/src/renderer/terminal/file-links.ts@@ -23,6 +23,8 @@// genuinely cannot distinguish a repainted wrap from prose that exactly fills the row),// gated tightly and capped at MAX_JOIN_ROWS, and the regex still has to match across the// seam for a link to result.+// A third kind — an agent TUI wrapping its own prose under a hanging indent — is NOT joined into+// the paragraph: it is offered as extra readings that existence decides (`hangingReadings`).import type { ILink, ILinkHandler, ILinkProvider, Terminal } from '@xterm/xterm'import { linkOpenIntent } from './link-hover'@@ -525,6 +527,138 @@ export function paragraphContaining(view: BufferView, row: number): Paragraph |return { text, startRow: start, rows: r - start + 1, cellStart, cellEnd }}+// ── Hanging-indent wraps ───────────────────────────────────────────────────────────────────────+// A third way a token spans rows, and the one agent TUIs use for prose: the CLI wraps its reply+// itself, at a word boundary or after a `/`, and indents every continuation row under the bullet+// (Codex: a 2-space hanging indent). Nothing in the buffer marks it — no wrapped flag, the row is+// not full, the next row starts with spaces — so neither join above fires, and a path wrapped+// that way linked neither half. Unlike those joins it is NOT one reading of the text: the seam may+// have eaten a space (`My\n Docs`) or nothing (`feature-x/\n docs`), and an indented row after a+// short one is just as often a new list item. So it never replaces the paragraph; it adds READINGS+// (`hangingReadings`) whose tokens are offered BEFORE the plain paragraph's, and existence decides+// — the model the rest of this file already follows for overlapping tokens.++/** Widest hanging indent treated as a continuation (a bullet, a number, a nested bullet). */+const MAX_HANGING_INDENT = 8++/** Cells a row's content occupies, trailing blanks excluded. */+function contentCells(cells: BufferCell[], cols: number): number {+ let n = Math.min(cells.length, cols)+ while (n > 0 && isBlank(cells[n - 1]) && cells[n - 1].width !== 0) n--+ return n+}++/**+ * Whether `row` ends a paragraph that the TUI wrapped onto an indented `row + 1`: the next row is+ * indented by 1..MAX_HANGING_INDENT blanks and then has text, `row` has text, and the next row's+ * first word would NOT have fit after it — the one thing a word-wrapper's break always leaves+ * behind, and what an ordinary indented list after a short line does not. Returns the indent+ * (in cells), or 0.+ */+function hangingIndentAfter(view: BufferView, row: number): number {+ if (continuesOnNextRow(view, row)) return 0+ const cur = rowCells(view, row)+ const next = rowCells(view, row + 1)+ if (!cur || !next) return 0+ const used = contentCells(cur, view.cols)+ if (used === 0) return 0+ let indent = 0+ while (indent < next.length && isBlank(next[indent]) && next[indent].width !== 0) indent+++ if (indent === 0 || indent > MAX_HANGING_INDENT || indent >= next.length) return 0+ let word = indent+ while (word < next.length && !isBlank(next[word])) word+++ return used + 1 + (word - indent) > view.cols ? indent : 0+}++/** A paragraph built across hanging seams, and where in its text each seam sits. */+export interface HangingReading {+ paragraph: Paragraph+ /** Text index of each seam: the joining space (`' '` reading), or the first unit after it. */+ seams: number[]+}++/**+ * The hanging-indent readings of the text around `row`: the plain paragraphs chained across every+ * hanging seam (bounded by MAX_JOIN_ROWS in total), once with each seam read as NOTHING and once+ * as ONE SPACE. Empty when `row` sits on no hanging seam. A seam's indent cells are not text, and+ * the `' '` reading's space shares the cell of the unit before it.+ */+export function hangingReadings(view: BufferView, row: number): HangingReading[] {+ const first = paragraphContaining(view, row)+ if (!first) return []+ const chain: Array<{ p: Paragraph; indent: number }> = [{ p: first, indent: 0 }]+ let rows = first.rows+ // Up: the paragraph ending just above this one's first row, if it hangs into it.+ for (;;) {+ const top = chain[0].p+ if (top.startRow === 0) break+ const indent = hangingIndentAfter(view, top.startRow - 1)+ if (!indent) break+ const prev = paragraphContaining(view, top.startRow - 1)+ if (!prev || rows + prev.rows > MAX_JOIN_ROWS) break+ chain[0].indent = indent+ chain.unshift({ p: prev, indent: 0 })+ rows += prev.rows+ }+ // Down.+ for (;;) {+ const bottom = chain[chain.length - 1].p+ const last = bottom.startRow + bottom.rows - 1+ const indent = hangingIndentAfter(view, last)+ if (!indent) break+ const next = paragraphContaining(view, last + 1)+ if (!next || next.startRow !== last + 1 || rows + next.rows > MAX_JOIN_ROWS) break+ chain.push({ p: next, indent })+ rows += next.rows+ }+ if (chain.length < 2) return []+ const startRow = chain[0].p.startRow+ return (['', ' '] as const).map((seam) => {+ let text = ''+ const cellStart: number[] = []+ const cellEnd: number[] = []+ const seams: number[] = []+ for (const { p, indent } of chain) {+ const base = (p.startRow - startRow) * view.cols+ let from = 0+ if (indent) {+ // The indent is `indent` blank cells, one text unit each (blanks are never wide).+ from = indent+ seams.push(text.length)+ if (seam) {+ // The eaten space owns no cell of its own: it sits on the cell of the unit before it,+ // so the indent is never part of a link (and never claims a click).+ text += seam+ cellStart.push(cellEnd[cellEnd.length - 1] ?? base)+ cellEnd.push(cellEnd[cellEnd.length - 1] ?? base)+ }+ }+ text += p.text.slice(from)+ for (let i = from; i < p.text.length; i++) {+ cellStart.push(base + p.cellStart[i])+ cellEnd.push(base + p.cellEnd[i])+ }+ }+ const rowsSpanned = chain[chain.length - 1].p.startRow + chain[chain.length - 1].p.rows - startRow+ return { paragraph: { text, startRow, rows: rowsSpanned, cellStart, cellEnd }, seams }+ })+}++/** Does the token at `startIndex..+len` run across one of `seams`? Only those tokens are new —+ * the rest are already the plain paragraph's. */+function crossesSeam(seams: number[], startIndex: number, len: number): boolean {+ return seams.some((s) => startIndex < s && s < startIndex + len)+}++/** Does the token cover `cell` with one of its own units? Stricter than `tokenCovers`, which+ * takes the whole cell span — across a hanging seam that span includes the trailing blanks of+ * one row and the indent of the next, and a click there is not a click on the path. */+function tokenOwnsCell(p: Paragraph, startIndex: number, len: number, cell: number): boolean {+ for (let i = startIndex; i < startIndex + len; i++)+ if (cell >= p.cellStart[i] && cell <= p.cellEnd[i]) return true+ return false+}+/** ILink range (1-based, inclusive) for a token at `startIndex..+len` of a paragraph. */function tokenRange(p: Paragraph,@@ -546,20 +680,40 @@ function tokenCovers(p: Paragraph, startIndex: number, len: number, cell: number}/**- * Among links resolved from OVERLAPPING candidates (a spaced path and its pieces), keep the first- * in preference order and drop any later one that overlaps a kept one. Candidates arrive sorted by- * start, longer first, so a spaced path that exists wins over its fragments.+ * Among links resolved from OVERLAPPING candidates (a spaced path and its pieces, a hanging-seam+ * reading and the plain one), keep the first in preference order and drop any later one that+ * overlaps a kept one. Overlap is in absolute buffer cells (`first..last`), because candidates may+ * come from different readings of the text. Within a reading candidates arrive sorted by start,+ * longer first, so a spaced path that exists wins over its fragments; hanging readings come first,+ * so a path wrapped under a bullet wins over the directory its first row happens to name.*/-function dropShadowed<T extends { startIndex: number; len: number }>(found: T[]): T[] {+function dropShadowed<T extends { first: number; last: number }>(found: T[]): T[] {const kept: T[] = []for (const f of found) {- if (kept.some((k) => f.startIndex < k.startIndex + k.len && k.startIndex < f.startIndex + f.len))- continue+ if (kept.some((k) => f.first <= k.last && k.first <= f.last)) continuekept.push(f)}return kept}+/** Every file-token candidate of the text around `row`, in preference order: the tokens of each+ * hanging reading that cross a seam (bare filenames excluded — a word split by a wrap is not+ * what that join exists for), then the plain paragraph's. */+function fileCandidates(+ view: BufferView,+ row: number,+ plain: Paragraph,+ convention: PathConventionOpts+): Array<{ p: Paragraph; t: FileToken }> {+ const out: Array<{ p: Paragraph; t: FileToken }> = []+ for (const { paragraph, seams } of hangingReadings(view, row)) {+ for (const t of matchFileTokens(paragraph.text, convention))+ if (!t.bare && crossesSeam(seams, t.startIndex, t.text.length)) out.push({ p: paragraph, t })+ }+ for (const t of matchFileTokens(plain.text, convention)) out.push({ p: plain, t })+ return out+}+/** xterm link provider for file paths. Register once per terminal with a reachable filesystem. */export function createFileLinkProvider(term: Terminal, deps: FileLinkDeps): ILinkProvider {return {@@ -576,23 +730,23 @@ export function createFileLinkProvider(term: Terminal, deps: FileLinkDeps): ILincallback(undefined)return}- const tokens = matchFileTokens(logical.text, convention)- if (!tokens.length) {+ const candidates = fileCandidates(bufferView(term), bufferLineNumber - 1, logical, convention)+ if (!candidates.length) {callback(undefined)return}const cols = term.colsvoid Promise.all(- tokens.map(async (t): Promise<(ILink & { startIndex: number; len: number }) | null> => {+ candidates.map(async ({ p, t }): Promise<(ILink & { first: number; last: number }) | null> => {const found = await findExistingPath(t.path, convention, deps)if (!found.found) return nullconst { abs, dir } = foundconst sink = deps.hoverSinkreturn {- startIndex: t.startIndex,- len: t.text.length,+ first: p.startRow * cols + p.cellStart[t.startIndex],+ last: p.startRow * cols + p.cellEnd[t.startIndex + t.text.length - 1],text: t.text,- range: tokenRange(logical, cols, t.startIndex, t.text.length),+ range: tokenRange(p, cols, t.startIndex, t.text.length),activate: (event: MouseEvent) => {const intent = linkOpenIntent(event)if (intent === 'none') return@@ -616,7 +770,7 @@ export function createFileLinkProvider(term: Terminal, deps: FileLinkDeps): ILin})).then((links) => {const real = dropShadowed(links.filter((l) => !!l)).map(- ({ startIndex: _s, len: _l, ...link }): ILink => link+ ({ first: _f, last: _l, ...link }): ILink => link)callback(real.length ? real : undefined)})@@ -810,10 +964,16 @@ export function linkAtCell(const convention = deps.convention ? deps.convention() : { windows: deps.windows }if (!convention) return null// Every candidate under the cell, in preference order: the first is the hit, the rest its- // fallbacks (the pieces of a spaced path that may not exist).- const under = matchFileTokens(logical.text, convention).filter((t) =>- inRange(t.startIndex, t.text.length)- )+ // fallbacks (the pieces of a spaced path that may not exist). A hanging-seam reading's tokens+ // come first — the same order the provider uses, so hover and click agree — and claim only the+ // cells their own text sits on.+ const under = fileCandidates(bufferView(term), row, logical, convention)+ .filter(({ p, t }) =>+ p === logical+ ? inRange(t.startIndex, t.text.length)+ : tokenOwnsCell(p, t.startIndex, t.text.length, (row - p.startRow) * term.cols + col)+ )+ .map(({ t }) => t)const [t, ...others] = underif (!t) return nullconst abs = resolveFileToken(t.path, deps.getCwd(), convention)