@north-light/crouter 0.3.154

package/dist/clients/attach/input/titled-editor.js

@@ -0,0 +1,801 @@
+// input/titled-editor.ts — the `crtr surface attach` input editor with two bits of chrome pi's
+// stock editor doesn't give us:
+//   1. the session name painted INTO the top border as a solid-background chip,
+//      so it stays pinned to the editor instead of scrolling off as a free badge;
+//   2. a border color that tracks the agent's thinking level (set by viewer.ts
+//      on each state update), mirroring pi's `getThinkingBorderColor`.
+// Both are pure render-layer chrome; nothing here touches the socket or session.
+import { statSync } from 'node:fs';
+import { CustomEditor } from '@earendil-works/pi-coding-agent';
+import { CURSOR_MARKER, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from '@earendil-works/pi-tui';
+// Deep import: `wordWrapLine` implements pi-tui's exact word-wrap algorithm but is
+// not re-exported from the package root (only `Editor`/`EditorTheme`/`EditorOptions`
+// are). The package has no `"exports"` field, so a deep subpath import is not
+// blocked by Node's resolution. We need the EXACT wrap algorithm (not a
+// reimplementation) to recompute layout for ref-highlight decoration below —
+// see `buildRefLayoutChunks`.
+import { wordWrapLine } from '@earendil-works/pi-tui/dist/components/editor.js';
+import { findRefTokens } from '../../../core/memory/inline-ref-grammar.js';
+import { findRefCompletionContext } from './ref-autocomplete.js';
+const LOADED_COMMAND_PREVIEW_MAX_LINES = 8;
+const LOADED_COMMAND_PREVIEW_MIN_WIDTH = 24;
+const LOADED_COMMAND_PREVIEW_MAX_CHARS = 8_192;
+/** Strip terminal controls from inline chrome only. The exact, unmodified
+ * prompt remains available through the inspector. */
+function sanitizeLoadedCommandPreview(content, limit) {
+    const bounded = content.slice(0, limit);
+    const truncated = content.length > limit;
+    // CSI, OSC (BEL or ST terminated), and every remaining C0/C1 control other
+    // than newline are inert in a Text component, never terminal instructions.
+    const text = bounded
+        .replace(/\x1b\](?:[^\x07\x1b]*)(?:\x07|\x1b\\)?/g, '')
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+        .replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, '');
+    return { text, truncated };
+}
+/** Keep inline command disclosure compact and bounded before wrapping; the
+ * inspector remains the unbounded, exact-prompt surface. */
+export function compactLoadedCommandPreview(content, width) {
+    if (width < LOADED_COMMAND_PREVIEW_MIN_WIDTH)
+        return [];
+    const limit = Math.min(LOADED_COMMAND_PREVIEW_MAX_CHARS, Math.max(256, width * LOADED_COMMAND_PREVIEW_MAX_LINES * 4));
+    const safe = sanitizeLoadedCommandPreview(content, limit);
+    const wrapped = wrapTextWithAnsi(safe.text, width);
+    if (!safe.truncated && wrapped.length <= LOADED_COMMAND_PREVIEW_MAX_LINES)
+        return wrapped;
+    const visible = wrapped.slice(0, LOADED_COMMAND_PREVIEW_MAX_LINES - 1);
+    visible.push(truncateToWidth('… truncated · inspect for full prompt', width));
+    return visible;
+}
+/** The standard thinking levels form a deliberate cool→warm ramp between blue
+ *  and its orange complement. `max` is a distinct, intense cyan endpoint so it
+ *  never falls back to the neutral default border. `off` alone falls back to
+ *  the caller's default border color. The colors double as title-chip
+ *  BACKGROUNDS under bold white text, so each must remain dark enough for the
+ *  label to read clearly. */
+const THINKING_START = [46, 92, 190]; // deep blue
+const THINKING_END = [166, 98, 24]; // deep amber
+const THINKING_MAX = [0, 145, 170]; // intense cyan
+function interpolateRgb(start, end, t) {
+    return [
+        Math.round(start[0] + (end[0] - start[0]) * t),
+        Math.round(start[1] + (end[1] - start[1]) * t),
+        Math.round(start[2] + (end[2] - start[2]) * t),
+    ];
+}
+const THINKING_RGB = {
+    off: undefined, // default border color
+    minimal: interpolateRgb(THINKING_START, THINKING_END, 0 / 4),
+    low: interpolateRgb(THINKING_START, THINKING_END, 1 / 4),
+    medium: interpolateRgb(THINKING_START, THINKING_END, 2 / 4),
+    high: interpolateRgb(THINKING_START, THINKING_END, 3 / 4),
+    xhigh: interpolateRgb(THINKING_START, THINKING_END, 4 / 4),
+    max: THINKING_MAX,
+};
+/** Named colours `/color` accepts, as RGB — mirrors the tmux colour-name table
+ *  (so the chip and the pane border read as the same hue). */
+const NAMED_RGB = {
+    black: [0, 0, 0],
+    red: [205, 49, 49],
+    green: [13, 188, 121],
+    yellow: [229, 229, 16],
+    blue: [36, 114, 200],
+    magenta: [188, 63, 188],
+    cyan: [17, 168, 205],
+    white: [229, 229, 229],
+    orange: [228, 152, 68],
+    grey: [128, 128, 128],
+    gray: [128, 128, 128],
+    brightred: [241, 76, 76],
+    brightgreen: [35, 209, 139],
+    brightyellow: [245, 245, 67],
+    brightblue: [59, 142, 234],
+    brightmagenta: [214, 112, 214],
+    brightcyan: [41, 184, 219],
+};
+/** Build a title-chip styler for a `/color` token (a tmux colour name, `#rrggbb`,
+ *  or `colourN`): the colour as the chip BACKGROUND with contrast-picked bold
+ *  text, matching the thinking-chip treatment. `undefined` for an unrenderable
+ *  token (e.g. `default`) — the caller keeps its fallback style. */
+export function colorChipStyle(token) {
+    const t = token.trim().toLowerCase();
+    const c256 = /^colour(\d{1,3})$/.exec(t);
+    if (c256 !== null)
+        return (s) => `\x1b[48;5;${c256[1]}m\x1b[97m\x1b[1m ${s} \x1b[0m`;
+    let rgb;
+    const hex = /^#([0-9a-f]{6})$/.exec(t);
+    if (hex !== null) {
+        const h = hex[1];
+        rgb = [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+    }
+    else {
+        rgb = NAMED_RGB[t];
+    }
+    if (rgb === undefined)
+        return undefined;
+    const [r, g, b] = rgb;
+    // Pick black-on-light / white-on-dark so the name stays readable on any hue.
+    const luma = 0.299 * r + 0.587 * g + 0.114 * b;
+    const fg = luma > 160 ? '\x1b[30m' : '\x1b[97m';
+    return (s) => `\x1b[48;2;${r};${g};${b}m${fg}\x1b[1m ${s} \x1b[0m`;
+}
+/** The default (thinking `off`) title chip: reverse video + a space of padding
+ *  each side, so the name reads as a label sitting on the border rule. Used as
+ *  the fallback when no thinking color applies. */
+export const defaultTitleStyle = (s) => `\x1b[7m ${s} \x1b[27m`;
+/** Resolve the editor border colorizer for a thinking level. Unknown / `off` →
+ *  the supplied `fallback` (the theme's default border color). */
+export function thinkingBorderColor(level, fallback) {
+    const rgb = level === undefined ? undefined : THINKING_RGB[level];
+    if (rgb === undefined)
+        return fallback;
+    const [r, g, b] = rgb;
+    return (s) => `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m`;
+}
+/** Resolve the title-chip styler for a thinking level: the level's color as the
+ *  chip BACKGROUND with bold white text (a space of padding each side), so the
+ *  session name reads as a solid label in the same hue as the border. Unknown /
+ *  `off` → the supplied `fallback` (the reverse-video default chip). */
+export function thinkingTitleStyle(level, fallback) {
+    const rgb = level === undefined ? undefined : THINKING_RGB[level];
+    if (rgb === undefined)
+        return fallback;
+    const [r, g, b] = rgb;
+    return (s) => `\x1b[48;2;${r};${g};${b}m\x1b[97m\x1b[1m ${s} \x1b[0m`;
+}
+/** Compose the replacement top-border line: solid title chip + border rule +
+ *  info chip, never wider than `width` (pi-tui hard-crashes on an over-wide
+ *  line). The info chip yields entirely when the chip leaves it almost no room,
+ *  and truncates when it only partially fits. Exported pure for the overflow
+ *  regression test. */
+export function composeTopBorder(width, title, info, titleStyle, borderColor) {
+    const chip = title ? titleStyle(truncateToWidth(title, Math.max(1, width - 4), '…')) : '';
+    const chipW = visibleWidth(chip);
+    const avail = width - chipW;
+    let infoChip = '';
+    if (info && avail > 4) {
+        infoChip = visibleWidth(info) <= avail ? info : truncateToWidth(info, avail, '…');
+    }
+    const fill = Math.max(0, width - chipW - visibleWidth(infoChip));
+    return chip + borderColor('─'.repeat(fill)) + infoChip;
+}
+/** The stock pi-tui editor paints its fake cursor as a solid reverse-video
+ *  block (`\x1b[7m…\x1b[0m`) unconditionally — in a wall of attach panes every
+ *  pane shows an identical solid white cursor, and nothing tells you which one
+ *  keys actually go to. When the hosting pane/terminal is UNFOCUSED we rewrite
+ *  that cell into a MUTED cursor, mirroring how real terminals de-emphasize
+ *  the hardware cursor on blur. A pixel-true full-cell outline isn't possible
+ *  in text cells, and hollow-box glyphs (▯/⍘/□) render undersized, so the
+ *  muted form is a full-size block in a dim gray background — same footprint
+ *  as the focused cursor, clearly not the bright active one (ruling: tried the
+ *  glyphs, Silas preferred the dim block). The rewrite anchors on pi-tui's
+ *  zero-width CURSOR_MARKER (emitted right before the fake cursor while the
+ *  editor component has TUI focus) so it can never touch reverse video
+ *  elsewhere in the line. Returns undefined when the line carries no cursor.
+ *  Exported pure for tests. */
+const SOLID_CURSOR_PREFIX = '\x1b[7m';
+const SOLID_CURSOR_RESET = '\x1b[0m';
+/** Dim gray bg, default fg — the char under the cursor stays readable. */
+const MUTED_CURSOR_ON = '\x1b[48;5;240m';
+export function outlineCursorLine(line) {
+    const m = line.indexOf(CURSOR_MARKER);
+    if (m === -1)
+        return undefined;
+    const start = m + CURSOR_MARKER.length;
+    if (!line.startsWith(SOLID_CURSOR_PREFIX, start))
+        return undefined;
+    const gStart = start + SOLID_CURSOR_PREFIX.length;
+    const end = line.indexOf(SOLID_CURSOR_RESET, gStart);
+    if (end === -1)
+        return undefined;
+    const grapheme = line.slice(gStart, end);
+    const replacement = `${MUTED_CURSOR_ON}${grapheme}\x1b[0m`;
+    return line.slice(0, start) + replacement + line.slice(end + SOLID_CURSOR_RESET.length);
+}
+/** Image file extensions a dragged path is recognized by. */
+const IMAGE_PATH_RE = /\.(png|jpe?g|gif|webp|bmp)$/i;
+/** Recognize a single input chunk as a filesystem path to an image file — how a
+ *  terminal delivers a file DRAGGED into the pane (the escaped path pasted in
+ *  bulk, optionally wrapped in bracketed-paste markers). Returns the resolved
+ *  path, or null when the chunk isn't a lone image path (normal typing, multi-
+ *  line text, a non-image path, or a path that doesn't point at a real file).
+ *  Conservative on purpose: it must never transform ordinary typed input. */
+export function detectDroppedImagePath(data) {
+    // Unwrap bracketed paste (\x1b[200~ … \x1b[201~) when the terminal uses it.
+    const bracketed = data.match(/\x1b\[200~([\s\S]*?)\x1b\[201~/);
+    let payload = (bracketed ? bracketed[1] : data).trim();
+    if (payload.length < 2)
+        return null; // a lone keystroke is never a drop
+    if (/[\u0000-\u0008\u000e-\u001f]/.test(payload))
+        return null; // control chars → not a path
+    // Terminals wrap a dropped path in quotes or backslash-escape its spaces.
+    if ((payload.startsWith("'") && payload.endsWith("'")) ||
+        (payload.startsWith('"') && payload.endsWith('"'))) {
+        payload = payload.slice(1, -1);
+    }
+    const path = payload.replace(/\\(.)/g, '$1');
+    if (/\n/.test(path) || !IMAGE_PATH_RE.test(path))
+        return null;
+    try {
+        if (!statSync(path).isFile())
+            return null;
+    }
+    catch {
+        return null; // not a real file → treat as ordinary pasted text
+    }
+    return path;
+}
+/** Recompute the exact layout pi-tui's `Editor.render` will produce for
+ *  `lines` at `layoutWidth`, faithfully porting the private `layoutText`
+ *  algorithm (empty-editor special case; per-line whole-fit vs `wordWrapLine`
+ *  branch; cursor-in-chunk assignment for wrapped lines). `wordWrapLine` here
+ *  is called WITHOUT the base editor's private paste-marker-aware
+ *  presegmentation, so a wrapped line containing a paste marker can
+ *  theoretically diverge from the real render's chunk boundaries — harmless,
+ *  because `decorateRow`'s verify-before-splice check means any divergence
+ *  simply drops that row's decoration rather than corrupting it. */
+export function buildRefLayoutChunks(lines, layoutWidth, cursorLine, cursorCol) {
+    const chunks = [];
+    if (lines.length === 0 || (lines.length === 1 && lines[0] === '')) {
+        chunks.push({ logicalLine: 0, startIndex: 0, endIndex: 0, text: '', hasCursor: true, cursorPos: 0 });
+        return chunks;
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const isCurrentLine = i === cursorLine;
+        if (visibleWidth(line) <= layoutWidth) {
+            chunks.push({
+                logicalLine: i,
+                startIndex: 0,
+                endIndex: line.length,
+                text: line,
+                hasCursor: isCurrentLine,
+                cursorPos: isCurrentLine ? cursorCol : 0,
+            });
+            continue;
+        }
+        const wrapped = wordWrapLine(line, layoutWidth);
+        for (let chunkIndex = 0; chunkIndex < wrapped.length; chunkIndex++) {
+            const chunk = wrapped[chunkIndex];
+            if (!chunk)
+                continue;
+            const isLastChunk = chunkIndex === wrapped.length - 1;
+            let hasCursorInChunk = false;
+            let adjustedCursorPos = 0;
+            if (isCurrentLine) {
+                if (isLastChunk) {
+                    hasCursorInChunk = cursorCol >= chunk.startIndex;
+                    adjustedCursorPos = cursorCol - chunk.startIndex;
+                }
+                else {
+                    hasCursorInChunk = cursorCol >= chunk.startIndex && cursorCol < chunk.endIndex;
+                    if (hasCursorInChunk) {
+                        adjustedCursorPos = cursorCol - chunk.startIndex;
+                        if (adjustedCursorPos > chunk.text.length)
+                            adjustedCursorPos = chunk.text.length;
+                    }
+                }
+            }
+            chunks.push({
+                logicalLine: i,
+                startIndex: chunk.startIndex,
+                endIndex: chunk.endIndex,
+                text: chunk.text,
+                hasCursor: hasCursorInChunk,
+                cursorPos: adjustedCursorPos,
+            });
+        }
+    }
+    return chunks;
+}
+/** Resolved-ref candidate spans in one logical line: exact, case-sensitive
+ *  membership in `names` (the broker-supplied inventory of visible canonical
+ *  names) — never a fuzzy or prefix match. */
+function resolvedSpansForLine(line, names) {
+    return findRefTokens(line)
+        .filter((t) => names.has(t.candidate))
+        .map((t) => ({ start: t.start, end: t.end }));
+}
+/** Zero-width SGR for a resolved ref: underline + dim on, and ONLY those two
+ *  attributes off again — never a blanket `\x1b[0m` reset, which would erase
+ *  the cursor's own reverse-video/mute styling if a span ever abuts it. */
+const REF_STYLE_ON = '\x1b[4m\x1b[2m';
+const REF_STYLE_OFF = '\x1b[24m\x1b[22m';
+const refGraphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** Best-effort length (in UTF-16 code units) of the first grapheme of `text`.
+ *  Not paste-marker aware (unlike the base editor's own segmenter) — doesn't
+ *  need to be: any mismatch is caught by `decorateRow`'s verify-before-splice
+ *  check, which only ever causes a span to be left undecorated. */
+function firstGraphemeLength(text) {
+    for (const seg of refGraphemeSegmenter.segment(text))
+        return seg.segment.length;
+    return 0;
+}
+/** Locate the cursor's own reverse-video cell within a single rendered content
+ *  row, so ref decoration can be positioned around it without ever touching
+ *  its bytes. Handles both the focused form (`SOLID_CURSOR_PREFIX`) and the
+ *  blurred, muted form `outlineCursorLine` rewrites it to (`MUTED_CURSOR_ON`)
+ *  — decoration always runs AFTER that rewrite, so both must be recognized.
+ *  Returns null when no cursor cell can be found (e.g. the row isn't the
+ *  cursor's row after all, or the base editor changed its cursor markup). */
+function locateCursorCell(row) {
+    const markerIdx = row.indexOf(CURSOR_MARKER);
+    const searchFrom = markerIdx === -1 ? 0 : markerIdx + CURSOR_MARKER.length;
+    let prefixIdx = row.indexOf(SOLID_CURSOR_PREFIX, searchFrom);
+    let prefixLen = SOLID_CURSOR_PREFIX.length;
+    if (prefixIdx === -1) {
+        prefixIdx = row.indexOf(MUTED_CURSOR_ON, searchFrom);
+        prefixLen = MUTED_CURSOR_ON.length;
+    }
+    if (prefixIdx === -1)
+        return null;
+    const resetIdx = row.indexOf(SOLID_CURSOR_RESET, prefixIdx + prefixLen);
+    if (resetIdx === -1)
+        return null;
+    return { start: markerIdx !== -1 ? markerIdx : prefixIdx, end: resetIdx + SOLID_CURSOR_RESET.length };
+}
+/** Splice underline/dim styling around every resolved-ref span that survives
+ *  chrome-safety verification. `rowStr` is one already-rendered content row
+ *  (plain, or carrying exactly the cursor's own cell markup); `chunk` is the
+ *  layout entry it was built from; `spans` are candidate resolved-ref spans
+ *  already filtered to lie within `chunk`'s logical range; `line` is the full
+ *  logical line text (used only to verify a span's characters still match at
+ *  the row offset we computed — never spliced in directly). Exported pure for
+ *  direct testing. */
+export function decorateRow(rowStr, chunk, spans, line, paddingX) {
+    const insertions = [];
+    if (!chunk.hasCursor) {
+        for (const span of spans) {
+            const absStart = paddingX + (span.start - chunk.startIndex);
+            const absEnd = paddingX + (span.end - chunk.startIndex);
+            if (rowStr.slice(absStart, absEnd) === line.slice(span.start, span.end)) {
+                insertions.push({ absStart, absEnd });
+            }
+        }
+    }
+    else {
+        const cell = locateCursorCell(rowStr);
+        if (cell === null)
+            return rowStr; // can't safely locate the cursor -> decorate nothing on this row
+        const afterChunkText = chunk.text.slice(chunk.cursorPos);
+        const graphemeLen = afterChunkText.length === 0 ? 0 : firstGraphemeLength(afterChunkText);
+        const consumedEnd = chunk.cursorPos + graphemeLen;
+        for (const span of spans) {
+            const localStart = span.start - chunk.startIndex;
+            const localEnd = span.end - chunk.startIndex;
+            if (localEnd <= chunk.cursorPos) {
+                const absStart = paddingX + localStart;
+                const absEnd = paddingX + localEnd;
+                if (absEnd <= cell.start && rowStr.slice(absStart, absEnd) === line.slice(span.start, span.end)) {
+                    insertions.push({ absStart, absEnd });
+                }
+            }
+            else if (localStart >= consumedEnd) {
+                const absStart = cell.end + (localStart - consumedEnd);
+                const absEnd = cell.end + (localEnd - consumedEnd);
+                if (absStart >= cell.end && rowStr.slice(absStart, absEnd) === line.slice(span.start, span.end)) {
+                    insertions.push({ absStart, absEnd });
+                }
+            }
+            // else: span overlaps the cursor cell itself -> leave plain (design-sanctioned degrade)
+        }
+    }
+    if (insertions.length === 0)
+        return rowStr;
+    insertions.sort((a, b) => b.absStart - a.absStart); // rightmost first so earlier offsets stay valid
+    let out = rowStr;
+    for (const ins of insertions) {
+        out = out.slice(0, ins.absStart) + REF_STYLE_ON + out.slice(ins.absStart, ins.absEnd) + REF_STYLE_OFF + out.slice(ins.absEnd);
+    }
+    return out;
+}
+/** Mirrors `dispatchSlashCommand`'s (`slash/dispatch.ts`) own leading-name
+ *  parse EXACTLY — not a looser grammar-based extraction, since dispatch's
+ *  name charset (`\S+`) differs from the ref grammar's (`[A-Za-z0-9_:-]`) and
+ *  a grammar-based extraction would under-suppress for a command name
+ *  containing e.g. `.`. Duplicated intentionally: input/titled-editor.ts owns only
+ *  render/input, and this two-line regex is the whole surface of that
+ *  contract. */
+function extractLeadingCommandName(text) {
+    const m = /^\/(\S+)\s*([\s\S]*)$/.exec(text.trim());
+    return m ? m[1] : null;
+}
+/** Mirrors the broker's `isLeadingEngineCommand` (`core/runtime/broker.ts`)
+ *  leading-token rule EXACTLY for classification purposes (review Minor 10):
+ *  the RAW, un-trimmed `text` must itself start with `/` — no `.trim()` — for
+ *  ANY token to be a candidate, matching the broker's own untrimmed
+ *  `text.startsWith('/')` checks byte-for-byte (space-based name split,
+ *  `/skill:` 7-character prefix). `engineNames` is the broker's own
+ *  `engineLeadingCommandNames` enumeration (`ListMemoryRefsData`, populated
+ *  per `list_memory_refs` reply) — exact extension-command invocation names
+ *  and prompt-template names bare, skills as `skill:<name>`, exactly what
+ *  `engineLeadingCommandTokens` emits. This is viewer-side, best-effort
+ *  classification for render suppression ONLY (see `decorateResolvedRefs`)
+ *  — the broker remains the sole authority at actual submission time
+ *  regardless of any viewer-side mismatch. */
+function matchesEngineLeadingCommand(text, engineNames) {
+    if (!text.startsWith('/'))
+        return false;
+    const spaceIndex = text.indexOf(' ');
+    const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+    if (engineNames.has(commandName))
+        return true;
+    if (text.startsWith('/skill:')) {
+        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        if (engineNames.has(`skill:${skillName}`))
+            return true;
+    }
+    return false;
+}
+export class TitledEditor extends CustomEditor {
+    /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
+     *  against. We keep a reference so `handleInput` can resolve the newline chord
+     *  here, independent of the editor's (possibly separate) pi-tui module global. */
+    km;
+    /** The raw (untrimmed) text `submitValue()` is ABOUT to trim away, captured by
+     *  the `submitValue` monkeypatch just below it runs, and consumed exactly once
+     *  by the `onSubmit` accessor wrapper. See the constructor for why. */
+    pendingRawSubmitText;
+    /** The REAL caller-supplied `onSubmit` handler (what `InputController` wires
+     *  via `this.editor.onSubmit = ...`) — stored here because `onSubmit` itself is
+     *  converted to an accessor below whose getter always returns our substitution
+     *  wrapper, not this value directly. */
+    realOnSubmit;
+    // CustomEditor's ctor signature; captured so we own the newline chord (see
+    // handleInput). The keybindings param is typed as pi's app-subclass manager,
+    // but the attach viewer feeds it pi-tui's base manager — hence the cast.
+    constructor(tui, theme, keybindings, options) {
+        super(tui, theme, keybindings, options);
+        this.km = keybindings;
+        // Preserve raw (untrimmed) submit text end-to-end (review Major 4). The base
+        // `Editor.submitValue()` — private in the `.d.ts` (blocking a normal TS
+        // `override`), hence the structural cast, same pattern as the other private-
+        // internals casts throughout this file (`scrollOffset`, `historyIndex`,
+        // `tryTriggerAutocomplete`) — computes `expandPasteMarkers(lines.join('\n'))`,
+        // `.trim()`s it, THEN calls `this.onSubmit(trimmed)`: the trimmed text is all
+        // any caller-supplied `onSubmit` handler ever sees today. `getExpandedText()`
+        // IS public and its implementation is byte-for-byte the same pre-`.trim()`
+        // computation, so calling it here — immediately before delegating to the real
+        // `submitValue` — captures the exact untrimmed text about to be lost, and
+        // must happen INSIDE this wrapper (not earlier in `handleInput`): a Tab/
+        // Enter-confirm command completion can mutate `state.lines` in the SAME
+        // `handleInput` call, in statements that run before `submitValue()` fires
+        // (pi-tui's `tui.select.confirm` leading-command fallthrough), so anything
+        // captured earlier could be stale pre-completion text.
+        const inheritedSubmitValue = this.submitValue.bind(this);
+        this.submitValue = () => {
+            const withExpanded = this;
+            this.pendingRawSubmitText = withExpanded.getExpandedText();
+            inheritedSubmitValue();
+        };
+        // `onSubmit` is a plain PUBLIC optional class field on the base `Editor`
+        // (`onSubmit?: (text: string) => void;`) — an own, configurable instance
+        // property installed during base field initialization, before this
+        // constructor body runs — so converting it to an accessor here is safe.
+        // `InputController` does `this.editor.onSubmit = (text) => ...`, which now
+        // goes through the setter below (stored as `realOnSubmit`); the value the
+        // base class actually reads and calls from inside `submitValue()` is ALWAYS
+        // this wrapper closure, which substitutes the captured raw text for
+        // whatever (trimmed) argument pi-tui passes.
+        Object.defineProperty(this, 'onSubmit', {
+            configurable: true,
+            get: () => {
+                return (text) => {
+                    const raw = this.pendingRawSubmitText ?? text;
+                    this.pendingRawSubmitText = undefined;
+                    this.realOnSubmit?.(raw);
+                };
+            },
+            set: (handler) => {
+                this.realOnSubmit = handler;
+            },
+        });
+    }
+    /** Insert a newline on the newLine chord (Alt+Enter / Shift+Enter) using crtr's
+     *  OWN keybindings manager, then defer everything else to the stock editor.
+     *
+     *  The base `Editor` resolves newLine against `getKeybindings()` on ITS pi-tui
+     *  instance, which in a non-deduped install is a DIFFERENT module than the one
+     *  carrying crtr's `alt+enter` override — so the override can silently never
+     *  reach it and Alt+Enter falls through to submit (issue #11). crtr's `km` (the
+     *  same manager CustomEditor matches `app.*` against) always carries the
+     *  override, so matching the chord here makes the newline behavior independent
+     *  of cross-instance keybinding mirroring. Skipped while the autocomplete popup
+     *  is open so Enter-to-confirm keeps working. */
+    /** Set by the input controller: called when a bulk input chunk is recognized
+     *  as a filesystem path to an image file (a file DRAGGED into the pane, which
+     *  the terminal delivers as bracketed-paste TEXT, not an image event). Returns
+     *  true when it consumed the drop, so the raw path is never inserted as text. */
+    onPasteImagePath;
+    /** Width of an `[Image #N]` token sitting immediately before the cursor on the
+     *  current line, or 0 when the cursor isn't at the end of such a token — used to
+     *  delete/skip the token atomically. The token's separating space is a normal,
+     *  reachable character, deliberately NOT part of the atom. */
+    imageTokenWidthBeforeCursor() {
+        const { line, col } = this.getCursor();
+        const text = this.getLines()[line];
+        if (text === undefined)
+            return 0;
+        const match = text.slice(0, col).match(/\[Image #\d+\]$/);
+        return match ? match[0].length : 0;
+    }
+    /** Width of an `[Image #N]` token sitting immediately after the cursor on the
+     *  current line, or 0 when the cursor isn't at the start of such a token — used
+     *  to skip the token with the right arrow. */
+    imageTokenWidthAfterCursor() {
+        const { line, col } = this.getCursor();
+        const text = this.getLines()[line];
+        if (text === undefined)
+            return 0;
+        const match = text.slice(col).match(/^\[Image #\d+\]/);
+        return match ? match[0].length : 0;
+    }
+    handleInput(data) {
+        // Keep ↓ on the editor's native focused-input path. Only when its own
+        // wrap-aware cursor and prompt-history navigation make no change does the
+        // adjacent roster get a chance to take over.
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.cursorDown')) {
+            const internals = this;
+            const beforeCursor = this.getCursor();
+            const beforeHistory = internals.historyIndex;
+            super.handleInput(data);
+            const afterCursor = this.getCursor();
+            if (internals.historyIndex === beforeHistory
+                && afterCursor.line === beforeCursor.line
+                && afterCursor.col === beforeCursor.col) {
+                this.onCursorDownAtBottom?.();
+            }
+            return;
+        }
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.input.newLine')) {
+            this.insertTextAtCursor('\n');
+            return;
+        }
+        // Backspace over an `[Image #N]` token deletes the WHOLE token (and its
+        // trailing space) in one keypress, not one character at a time — the token is
+        // a single atom to the user. We replay the backspace across the token's full
+        // width so the base editor's cursor/undo bookkeeping stays correct.
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.deleteCharBackward')) {
+            const width = this.imageTokenWidthBeforeCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        // Left/right arrow steps OVER an `[Image #N]` token in one keypress — the
+        // token reads as a single character, so the caret never lands inside it. We
+        // replay the arrow across the token's full width so cursor bookkeeping stays
+        // correct.
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.cursorLeft')) {
+            const width = this.imageTokenWidthBeforeCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.cursorRight')) {
+            const width = this.imageTokenWidthAfterCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        // A file dragged into the pane arrives as a bulk paste of its (shell-escaped)
+        // path, NOT as an image on the clipboard, so onPasteImage never fires. Detect
+        // an image-file path here and hand it to the controller so it becomes an
+        // `[Image #N]` token like a clipboard paste, instead of the raw temp path.
+        const droppedPath = detectDroppedImagePath(data);
+        if (droppedPath && this.onPasteImagePath?.(droppedPath))
+            return;
+        const { line: beforeLine, col: beforeCol } = this.getCursor();
+        const beforeText = this.getLines()[beforeLine] ?? '';
+        super.handleInput(data);
+        this.maybeTriggerNonLeadingRefAutocomplete(beforeLine, beforeCol, beforeText);
+    }
+    /** The base editor auto-triggers autocomplete for a LEADING slash context
+     *  (`isInSlashCommandContext`, `insertCharacter`) whenever the text before
+     *  the cursor — from the very start of the line — begins with `/`. A
+     *  non-leading ref elsewhere in ordinary text (`hey check /dev`) never
+     *  satisfies that check, so it would otherwise require an explicit Tab.
+     *  This bridges exactly that gap: after an ordinary single-character
+     *  insertion, if the caret now sits in a non-leading ref token
+     *  (`findRefCompletionContext` — T1's shared caret classifier, not
+     *  reimplemented here), nudge the same private trigger the base editor uses
+     *  for its own leading case. Detected purely by before/after cursor and
+     *  text-length diffing, so it's mechanism-agnostic (typed key or decoded
+     *  printable key alike) and naturally excludes multi-character paste
+     *  (`handlePaste` already suppresses autocomplete itself, and the exact +1
+     *  length-delta check here would reject it anyway). Leading context is
+     *  deliberately left untouched — triggering it again here would double the
+     *  base editor's own native trigger for that case. */
+    maybeTriggerNonLeadingRefAutocomplete(beforeLine, beforeCol, beforeText) {
+        if (this.isShowingAutocomplete())
+            return;
+        const cursor = this.getCursor();
+        if (cursor.line !== beforeLine || cursor.col !== beforeCol + 1)
+            return;
+        const afterText = this.getLines()[cursor.line] ?? '';
+        if (afterText.length !== beforeText.length + 1)
+            return;
+        const inserted = afterText[beforeCol];
+        if (inserted === undefined || (inserted !== '/' && !/[A-Za-z0-9_:-]/.test(inserted)))
+            return;
+        const context = findRefCompletionContext(this.getLines(), cursor.line, cursor.col);
+        if (!context || context.kind !== 'ref')
+            return;
+        this.tryTriggerAutocomplete();
+    }
+    /** Called after native ↓ navigation proves the editor and prompt history are
+     * both exhausted. Attach uses this boundary handoff to enter its node roster. */
+    onCursorDownAtBottom;
+    /** Fully-expanded prompt template currently loaded by the editor's leading
+     * slash token. It renders inside the editor outline before submission, so the
+     * user can inspect the exact payload while arguments are still editable. */
+    loadedCommand;
+    /** Session-name chip painted into the LEFT of the top border. Empty → plain. */
+    title = '';
+    /** Pre-styled context string painted into the RIGHT of the top border (cwd /
+     *  branch / git status). Already colorized by the caller; empty → omitted. */
+    info = '';
+    /** Editor-mode badge painted into the bottom-right of the outline. Empty → omitted. */
+    mode = '';
+    /** Node and workspace badge painted at the far bottom-right of the outline. */
+    contextBadge = '';
+    /** Paint the chip solid so the name reads as a label sitting on the border
+     *  rule. Defaults to the reverse-video chip; viewer.ts swaps in a
+     *  thinking-colored background (bold white text) on each state update. */
+    titleStyle = defaultTitleStyle;
+    /** Editor-mode badge colorizer, matched to the current mode type. */
+    modeStyle = defaultTitleStyle;
+    /** Node and workspace badge colorizer, matched to the editor frame. */
+    contextBadgeStyle = defaultTitleStyle;
+    /** Whether the hosting tmux pane / terminal window has FOCUS (terminal focus
+     *  reporting, DECSET 1004 — viewer.ts flips this on `\x1b[I` / `\x1b[O`).
+     *  Distinct from TUI component focus: the editor keeps component focus while
+     *  its pane is blurred. False → the fake cursor renders as an outline. */
+    paneFocused = true;
+    /** Canonical names the broker currently resolves — the exact-membership set
+     *  a candidate ref token must be in to render as a resolved highlight.
+     *  Empty by default (no decoration) until the caller (T3, out of scope for
+     *  this wave) supplies the broker-supplied inventory. */
+    resolvedRefNames = new Set();
+    /** Command names the VIEWER dispatches ENTIRELY locally (never reach the
+     *  engine as prose) — checked against the TRIMMED leading-name rule
+     *  (`extractLeadingCommandName`, which mirrors `slash/dispatch.ts`'s own
+     *  `text.trim()`-based dispatch parse). Exactly
+     *  `locallyConsumedCommandNames()` from `slash/dispatch.ts` — independent
+     *  of `remote` and of the broker's `get_commands` reply (see that
+     *  function's doc comment). Deliberately NEVER the merged display/
+     *  completion list (review Major 6 — `slashCommandList` is a different,
+     *  remote-filtered, broker-augmented list, not a dispatch predicate). */
+    localCommandNames = new Set();
+    /** Leading tokens the ENGINE (broker) independently consumes as a leading
+     *  command/skill/template dispatch — the broker's own
+     *  `engineLeadingCommandNames` (design: inline memory references, review
+     *  Major 6), checked against the UNTRIMMED leading-name rule
+     *  (`matchesEngineLeadingCommand`, mirroring the broker's own
+     *  `isLeadingEngineCommand` — review Minor 10). Populated from each
+     *  `list_memory_refs` reply, alongside `resolvedRefNames`. */
+    engineCommandNames = new Set();
+    setResolvedRefNames(names) {
+        this.resolvedRefNames = new Set(names);
+    }
+    setLocalCommandNames(names) {
+        this.localCommandNames = new Set(names);
+    }
+    setEngineCommandNames(names) {
+        this.engineCommandNames = new Set(names);
+    }
+    /** Render-only decoration pass: underlines every resolved-ref span visible
+     *  in the already-rendered content rows, using a from-scratch layout
+     *  recompute (`buildRefLayoutChunks`) that mirrors the base editor's own
+     *  private `layoutText`/`scrollOffset`/`maxVisibleLines` math so row/column
+     *  offsets line up. Never mutates stored text; a span whose recomputed
+     *  offset doesn't verify against the real rendered row (see `decorateRow`)
+     *  is simply left undecorated. Suppressed entirely (command-wide) whenever
+     *  the composer's own leading token dispatches — as a LOCAL viewer command
+     *  (`localCommandNames`, TRIMMED rule) or as an ENGINE-consumed leading
+     *  command/skill/template (`engineCommandNames`, UNTRIMMED rule, review
+     *  Minor 10) — the ref grammar and slash-dispatch's name charset differ, so
+     *  highlighting a ref inside a command that's about to dispatch would be
+     *  misleading chrome for text the command, not memory resolution, is about
+     *  to consume. The two rules are kept deliberately SEPARATE (review Major
+     *  6) rather than collapsed into one set/predicate: they classify against
+     *  different text (trimmed vs. raw) and different authorities (this
+     *  viewer's own dispatch vs. the broker's). */
+    decorateResolvedRefs(lines, width) {
+        if (this.resolvedRefNames.size === 0)
+            return;
+        const text = this.getText();
+        const trimmedLeadingName = extractLeadingCommandName(text);
+        if (trimmedLeadingName !== null && this.localCommandNames.has(trimmedLeadingName))
+            return;
+        if (matchesEngineLeadingCommand(text, this.engineCommandNames))
+            return;
+        const maxPadding = Math.max(0, Math.floor((width - 1) / 2));
+        const paddingX = Math.min(this.getPaddingX(), maxPadding);
+        const contentWidth = Math.max(1, width - paddingX * 2);
+        const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));
+        const logicalLines = this.getLines();
+        const cursor = this.getCursor();
+        const chunks = buildRefLayoutChunks(logicalLines, layoutWidth, cursor.line, cursor.col);
+        // Private on the base `Editor`; render() above has already called
+        // `super.render(width)`, so this reflects the scrollOffset THIS render
+        // settled on — the same structural-cast pattern used elsewhere in this
+        // file (e.g. the `historyIndex` cast in titled-editor-preview.test.ts).
+        const scrollOffset = this.scrollOffset;
+        const maxVisibleLines = Math.max(5, Math.floor(this.tui.terminal.rows * 0.3));
+        const visibleCount = Math.min(Math.max(0, chunks.length - scrollOffset), maxVisibleLines);
+        if (visibleCount <= 0 || lines.length < 1 + visibleCount)
+            return; // mismatch -> skip entirely
+        const spansByLine = new Map();
+        for (let r = 0; r < visibleCount; r++) {
+            const chunk = chunks[scrollOffset + r];
+            if (!chunk)
+                continue;
+            let spans = spansByLine.get(chunk.logicalLine);
+            if (spans === undefined) {
+                spans = resolvedSpansForLine(logicalLines[chunk.logicalLine] ?? '', this.resolvedRefNames);
+                spansByLine.set(chunk.logicalLine, spans);
+            }
+            const contained = spans.filter((s) => s.start >= chunk.startIndex && s.end <= chunk.endIndex);
+            if (contained.length === 0)
+                continue;
+            const rowStr = lines[1 + r];
+            if (rowStr === undefined)
+                continue;
+            lines[1 + r] = decorateRow(rowStr, chunk, contained, logicalLines[chunk.logicalLine] ?? '', paddingX);
+        }
+    }
+    render(width) {
+        const lines = super.render(width);
+        if (!this.paneFocused) {
+            for (let i = 0; i < lines.length; i++) {
+                const hollowed = outlineCursorLine(lines[i]);
+                if (hollowed !== undefined) {
+                    lines[i] = hollowed;
+                    break;
+                }
+            }
+        }
+        this.decorateResolvedRefs(lines, width);
+        if (this.loadedCommand !== undefined && lines.length >= 2 && width >= 8) {
+            const innerWidth = width - 4;
+            const body = compactLoadedCommandPreview(this.loadedCommand.content, innerWidth);
+            // At narrow widths the disclosure is suppressed rather than clipping away
+            // its inspect affordance. Put that affordance first when it does render.
+            if (body.length === 0)
+                return lines;
+            const label = ` ${this.loadedCommand.inspectHint} · /${this.loadedCommand.name} loaded `;
+            const framed = body.map((line) => {
+                const clipped = truncateToWidth(line, innerWidth);
+                return `${this.borderColor('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${this.borderColor('│')}`;
+            });
+            const dividerText = truncateToWidth(label, width - 2);
+            const remaining = Math.max(0, width - 2 - visibleWidth(dividerText));
+            const divider = this.borderColor(`├${dividerText}${'─'.repeat(remaining)}┤`);
+            lines.splice(1, 0, divider, ...framed, this.borderColor(`├${'─'.repeat(width - 2)}┤`));
+        }
+        if ((this.title || this.info) && lines.length > 0) {
+            // Replace the stock top border; dashes in the current (thinking-aware)
+            // border color.
+            lines[0] = composeTopBorder(width, this.title, this.info, this.titleStyle, (s) => this.borderColor(s));
+        }
+        if ((this.mode || this.contextBadge) && lines.length > 0) {
+            // Context stays at the far edge; an active editor mode sits immediately
+            // to its left as the local state badge for this input surface.
+            const modeBadge = this.mode ? this.modeStyle(this.mode) : '';
+            const contextBadge = this.contextBadge ? this.contextBadgeStyle(this.contextBadge) : '';
+            const badge = modeBadge + contextBadge;
+            const badgeWidth = visibleWidth(badge);
+            if (badgeWidth + 2 < width) {
+                const last = lines.length - 1;
+                lines[last] = truncateToWidth(lines[last], width - badgeWidth, '') + badge;
+            }
+        }
+        return lines;
+    }
+}