@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/input/ref-autocomplete.d.ts

@@ -0,0 +1,77 @@
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from '@earendil-works/pi-tui';
+import type { RefMeta } from '../../../core/runtime/broker-protocol.js';
+import { type FrecencyStore } from './completion-frecency.js';
+/** The caret's classification for completion purposes. `null` means the caret
+ *  is not touching any slash token at all (every other autocomplete mode —
+ *  file, `@`, etc. — is unaffected and this provider fully delegates). */
+export type RefCompletionContext = {
+    kind: 'leading';
+    startCol: number;
+    endCol: number;
+    prefix: string;
+} | {
+    kind: 'ref';
+    startCol: number;
+    endCol: number;
+    prefix: string;
+};
+/**
+ * Classify the slash token (if any) touching the caret at
+ * `(cursorLine, cursorCol)` in the editor's logical `lines`. Joins the lines
+ * with `\n` (the editor's own logical-text convention — no grammar character
+ * is `\n`, so a token can never straddle a line boundary) and delegates the
+ * actual token detection to the shared `findRefTokenAtCaret`.
+ *
+ * `kind: 'leading'` means the token's `/` sits at the very start of the whole
+ * message (global offset 0) — the existing command-only leading-completion
+ * context, which this provider must not touch. Anything else — including a
+ * `/` at the start of a LATER logical line, where the preceding joined-text
+ * character is `\n`, not "start of input" — is `kind: 'ref'`.
+ *
+ * Returns `null` when the caret is not touching a token at all: it is not at
+ * a token-starting `/` (offset zero or after ASCII whitespace only), it is
+ * after non-whitespace, or it has moved past the end of the grammar run.
+ */
+export declare function findRefCompletionContext(lines: readonly string[], cursorLine: number, cursorCol: number): RefCompletionContext | null;
+/**
+ * Wraps an existing command-only `AutocompleteProvider` (in practice always a
+ * `CombinedAutocompleteProvider`) so that:
+ *
+ * - Leading-command context (`kind: 'leading'`) and every non-ref context
+ *   (`context === null`, e.g. file/`@` completion) delegate verbatim — byte-
+ *   for-byte unchanged command/file/`@` completion.
+ * - A non-leading ref context (`kind: 'ref'`) is served entirely from the
+ *   supplied `refs` inventory instead: case-sensitive prefix filtering by the
+ *   typed surface form, `shortForm` as the row description, and a completion
+ *   that replaces only the detected token range with no trailing separator.
+ *
+ * Refs are never merged into the wrapped provider's command list, so leading
+ * `/` completion always remains commands-only even when a ref shares a name
+ * with something in `refs`.
+ */
+export declare class RefAwareAutocompleteProvider implements AutocompleteProvider {
+    private readonly refs;
+    private readonly refNames;
+    private readonly delegate;
+    private readonly frecency;
+    constructor(refs: ReadonlyArray<RefMeta>, delegate: AutocompleteProvider, frecency: FrecencyStore);
+    /** Pass through unchanged — pi-tui's editor explicitly discards `/` as a
+     *  trigger character regardless, and `CombinedAutocompleteProvider` doesn't
+     *  declare any of its own, so this is normally `undefined`. */
+    get triggerCharacters(): string[] | undefined;
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number, options: {
+        signal: AbortSignal;
+        force?: boolean;
+    }): Promise<AutocompleteSuggestions | null>;
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+    };
+    /** Admits forced (Tab) completion in a non-leading ref context, where
+     *  pi-tui's own leading-slash short-circuit doesn't apply (the current
+     *  line's text before the cursor doesn't start with `/`, so its Tab
+     *  handler routes through the forced-file path gated by this method).
+     *  Every other case delegates unchanged. */
+    shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number): boolean;
+}

package/dist/clients/attach/input/ref-autocomplete.js

@@ -0,0 +1,176 @@
+// input/ref-autocomplete.ts — T1: the terminal attach viewer's ref-aware completion
+// provider (design: inline memory references, Terminal completion provider /
+// D5). Wraps the existing command-only `CombinedAutocompleteProvider` rather
+// than subclassing or changing it: leading-slash completion stays commands-
+// only (unchanged), while a non-leading `/prefix` token offers the broker-
+// supplied memory-ref inventory instead. Refs never join the command list and
+// never dispatch — see `applyCompletion` below.
+//
+// The caret classification below is a thin adapter over the shared grammar's
+// `findRefTokenAtCaret` (`../../../shared/inline-ref-grammar.ts`, the C1
+// contract): it maps the editor's `(lines, cursorLine, cursorCol)` shape to
+// the grammar's flat-text/caret-offset shape and back, and adds exactly one
+// extra classification the grammar itself doesn't know about — whether the
+// token sits at the very start of the whole message (`start === 0`, "leading
+// command context") or anywhere else ("non-leading ref context"). It does not
+// reimplement `[A-Za-z0-9_:-]`, trimming, or boundary detection.
+import { findRefTokenAtCaret, formatRefToken } from '../../../shared/inline-ref-grammar.js';
+import { leafFirstSearchable, normalizeRefQuery, rankByFuzzyFrecency, } from './completion-frecency.js';
+/**
+ * Classify the slash token (if any) touching the caret at
+ * `(cursorLine, cursorCol)` in the editor's logical `lines`. Joins the lines
+ * with `\n` (the editor's own logical-text convention — no grammar character
+ * is `\n`, so a token can never straddle a line boundary) and delegates the
+ * actual token detection to the shared `findRefTokenAtCaret`.
+ *
+ * `kind: 'leading'` means the token's `/` sits at the very start of the whole
+ * message (global offset 0) — the existing command-only leading-completion
+ * context, which this provider must not touch. Anything else — including a
+ * `/` at the start of a LATER logical line, where the preceding joined-text
+ * character is `\n`, not "start of input" — is `kind: 'ref'`.
+ *
+ * Returns `null` when the caret is not touching a token at all: it is not at
+ * a token-starting `/` (offset zero or after ASCII whitespace only), it is
+ * after non-whitespace, or it has moved past the end of the grammar run.
+ */
+export function findRefCompletionContext(lines, cursorLine, cursorCol) {
+    const text = lines.join('\n');
+    let lineStart = 0;
+    for (let i = 0; i < cursorLine && i < lines.length; i++) {
+        lineStart += lines[i].length + 1; // +1 for the '\n' joining it to the next line
+    }
+    const caret = lineStart + cursorCol;
+    const token = findRefTokenAtCaret(text, caret);
+    if (!token)
+        return null;
+    const startCol = token.start - lineStart;
+    const endCol = token.end - lineStart;
+    const kind = token.start === 0 ? 'leading' : 'ref';
+    return { kind, startCol, endCol, prefix: token.surfacePrefix };
+}
+/**
+ * Wraps an existing command-only `AutocompleteProvider` (in practice always a
+ * `CombinedAutocompleteProvider`) so that:
+ *
+ * - Leading-command context (`kind: 'leading'`) and every non-ref context
+ *   (`context === null`, e.g. file/`@` completion) delegate verbatim — byte-
+ *   for-byte unchanged command/file/`@` completion.
+ * - A non-leading ref context (`kind: 'ref'`) is served entirely from the
+ *   supplied `refs` inventory instead: case-sensitive prefix filtering by the
+ *   typed surface form, `shortForm` as the row description, and a completion
+ *   that replaces only the detected token range with no trailing separator.
+ *
+ * Refs are never merged into the wrapped provider's command list, so leading
+ * `/` completion always remains commands-only even when a ref shares a name
+ * with something in `refs`.
+ */
+export class RefAwareAutocompleteProvider {
+    refs;
+    refNames;
+    delegate;
+    frecency;
+    constructor(refs, delegate, frecency) {
+        this.refs = refs;
+        this.refNames = new Set(refs.map((ref) => ref.name));
+        this.delegate = delegate;
+        this.frecency = frecency;
+    }
+    /** Pass through unchanged — pi-tui's editor explicitly discards `/` as a
+     *  trigger character regardless, and `CombinedAutocompleteProvider` doesn't
+     *  declare any of its own, so this is normally `undefined`. */
+    get triggerCharacters() {
+        return this.delegate.triggerCharacters;
+    }
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+        const context = findRefCompletionContext(lines, cursorLine, cursorCol);
+        if (!context) {
+            return this.delegate.getSuggestions(lines, cursorLine, cursorCol, options);
+        }
+        if (context.kind === 'leading') {
+            // Leading command-name completion. On a forced (Tab) trigger pi-tui runs
+            // file completion instead of command completion, so that must delegate
+            // verbatim.
+            if (options.force) {
+                return this.delegate.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+            // The delegate still CONSTRUCTS the items (reusing its description and
+            // argumentHint formatting), but it filters them by a subsequence over the
+            // raw command name, which cannot match a namespaced command by its leaf:
+            // `deva` never matches `acme:dev` because the `a` comes first in the
+            // raw string. So ask it for the whole list — an empty query matches
+            // everything — and apply the same leaf-first fuzzy match plus slight
+            // frecency bias the ref path uses. A one-token query over a name with no
+            // separator scores exactly as pi-tui scored it, so plain commands keep
+            // their previous order and frecency is the only perturbation there.
+            // `applyCompletion` slices back by `prefix.length`, so the query and the
+            // returned prefix are both the text before the cursor — exactly what pi-tui
+            // matches on and returns for this branch. A leading token starts at global
+            // offset 0, so that text always begins with the `/`.
+            const textBeforeCursor = (lines[cursorLine] ?? '').slice(0, cursorCol);
+            const all = await this.delegate.getSuggestions(['/'], 0, 1, options);
+            if (!all)
+                return null;
+            const items = rankByFuzzyFrecency(all.items, textBeforeCursor.slice(1), {
+                searchableOf: (item) => leafFirstSearchable(item.value),
+                idOf: (item) => `command:${item.value}`,
+                store: this.frecency,
+            });
+            if (items.length === 0)
+                return null;
+            return { items, prefix: textBeforeCursor };
+        }
+        // Non-leading ref completion: fuzzy match (leaf-first searchable) with a
+        // slight frecency bias, replacing the former case-sensitive prefix filter.
+        const matches = rankByFuzzyFrecency(this.refs, normalizeRefQuery(context.prefix.slice(1)), {
+            searchableOf: (ref) => leafFirstSearchable(ref.name),
+            idOf: (ref) => `ref:${ref.name}`,
+            store: this.frecency,
+        });
+        if (matches.length === 0)
+            return null;
+        const items = matches.map((ref) => ({
+            value: ref.name,
+            label: formatRefToken(ref.name),
+            description: ref.shortForm || undefined,
+        }));
+        // Matching above used a normalized query, but the RETURNED prefix is the
+        // typed surface form with its leading '/' stripped. pi-tui's `handleInput`
+        // (tui.select.confirm
+        // branch) falls through to `submitValue()` whenever `autocompletePrefix`
+        // (set verbatim from this return value) starts with '/' — that's its own
+        // leading-command-completion submit shortcut, and a non-leading ref
+        // completion must never trigger it: Enter-confirming a ref token is supposed
+        // to accept the token and return to editing, not submit the message. A bare
+        // prefix also happens to be the CORRECT comparand for `item.value`, which is
+        // already the bare `ref.name` (no slash). `applyCompletion` below never reads
+        // its `prefix` argument (it recomputes the token position fresh each call
+        // via `findRefCompletionContext`), so this change has no effect on
+        // replacement correctness.
+        return { items, prefix: context.prefix.slice(1) };
+    }
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+        const context = findRefCompletionContext(lines, cursorLine, cursorCol);
+        if (context && context.kind === 'ref' && this.refNames.has(item.value)) {
+            const replacement = formatRefToken(item.value);
+            const line = lines[cursorLine] ?? '';
+            const newLine = line.slice(0, context.startCol) + replacement + line.slice(context.endCol);
+            const newLines = lines.slice();
+            newLines[cursorLine] = newLine;
+            return { lines: newLines, cursorLine, cursorCol: context.startCol + replacement.length };
+        }
+        return this.delegate.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    }
+    /** Admits forced (Tab) completion in a non-leading ref context, where
+     *  pi-tui's own leading-slash short-circuit doesn't apply (the current
+     *  line's text before the cursor doesn't start with `/`, so its Tab
+     *  handler routes through the forced-file path gated by this method).
+     *  Every other case delegates unchanged. */
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+        const context = findRefCompletionContext(lines, cursorLine, cursorCol);
+        if (context && context.kind === 'ref')
+            return true;
+        return this.delegate.shouldTriggerFileCompletion
+            ? this.delegate.shouldTriggerFileCompletion(lines, cursorLine, cursorCol)
+            : false;
+    }
+}

package/dist/clients/attach/input/titled-editor.d.ts

@@ -0,0 +1,225 @@
+import { CustomEditor } from '@earendil-works/pi-coding-agent';
+import { type EditorOptions, type EditorTheme, type TUI } from '@earendil-works/pi-tui';
+/** Keep inline command disclosure compact and bounded before wrapping; the
+ * inspector remains the unbounded, exact-prompt surface. */
+export declare function compactLoadedCommandPreview(content: string, width: number): string[];
+/** Thinking levels pi cycles through (shift+tab), lowest → highest budget. */
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** 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 declare function colorChipStyle(token: string): ((s: string) => string) | undefined;
+/** 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 declare const defaultTitleStyle: (s: string) => string;
+/** Resolve the editor border colorizer for a thinking level. Unknown / `off` →
+ *  the supplied `fallback` (the theme's default border color). */
+export declare function thinkingBorderColor(level: string | undefined, fallback: (s: string) => string): (s: string) => string;
+/** 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 declare function thinkingTitleStyle(level: string | undefined, fallback: (s: string) => string): (s: string) => string;
+/** 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 declare function composeTopBorder(width: number, title: string, info: string, titleStyle: (s: string) => string, borderColor: (s: string) => string): string;
+export declare function outlineCursorLine(line: string): string | undefined;
+/** 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 declare function detectDroppedImagePath(data: string): string | null;
+/** One projected layout entry — a faithful port of pi-tui's private
+ *  `Editor.prototype.layoutText`, extended with the logical line each entry
+ *  came from (the base algorithm processes one editor at a time and never
+ *  needs to report this, since it already owns `this.state.lines`). */
+export interface RefLayoutChunk {
+    logicalLine: number;
+    startIndex: number;
+    endIndex: number;
+    text: string;
+    hasCursor: boolean;
+    cursorPos: number;
+}
+/** 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 declare function buildRefLayoutChunks(lines: readonly string[], layoutWidth: number, cursorLine: number, cursorCol: number): RefLayoutChunk[];
+/** 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 declare function decorateRow(rowStr: string, chunk: RefLayoutChunk, spans: ReadonlyArray<{
+    start: number;
+    end: number;
+}>, line: string, paddingX: number): string;
+export declare 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. */
+    private readonly 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. */
+    private 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. */
+    private realOnSubmit;
+    /** A line ending held back to learn whether more input follows it within
+     *  `PASTE_BURST_MS` — see `handleInput`'s unbracketed-paste rescue. More input
+     *  means it was a line break inside a paste (insert a newline); silence means
+     *  a human pressed Enter (submit). */
+    private pendingReturn;
+    /** How long a line ending is held before it counts as a real Enter. An
+     *  unbracketed paste floods `handleInput` within one event-loop tick, so its
+     *  next character always lands far inside this window; a human's next
+     *  keystroke after Enter is ~30ms+ away at the very fastest. Short enough that
+     *  the added submit latency is imperceptible. */
+    private static readonly PASTE_BURST_MS;
+    constructor(tui: TUI, theme: EditorTheme, keybindings: ConstructorParameters<typeof CustomEditor>[2], options?: EditorOptions);
+    /** 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. 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?: (path: string) => boolean;
+    /** Settle a line ending held by the unbracketed-paste rescue. `'newline'` (more
+     *  input arrived, so it was a paste's own line break) inserts it in place;
+     *  `'submit'` (the hold window expired in silence, so a human pressed Enter)
+     *  replays it through the stock editor and repaints, because this runs outside
+     *  the TUI's own post-`handleInput` render request. No-op when nothing is
+     *  held. */
+    private settleHeldReturn;
+    /** 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. */
+    private imageTokenWidthBeforeCursor;
+    /** 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. */
+    private imageTokenWidthAfterCursor;
+    handleInput(data: string): void;
+    /** 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. */
+    private maybeTriggerNonLeadingRefAutocomplete;
+    /** Called after native ↓ navigation proves the editor and prompt history are
+     * both exhausted. Attach uses this boundary handoff to enter its node roster. */
+    onCursorDownAtBottom?: () => void;
+    /** 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: {
+        name: string;
+        content: string;
+        inspectHint: string;
+    } | undefined;
+    /** Session-name chip painted into the LEFT of the top border. Empty → plain. */
+    title: string;
+    /** Pre-styled context string painted into the RIGHT of the top border (cwd /
+     *  branch / git status). Already colorized by the caller; empty → omitted. */
+    info: string;
+    /** Node and workspace badge painted at the far bottom-right of the outline. */
+    contextBadge: string;
+    /** 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: (s: string) => string;
+    /** Node and workspace badge colorizer, matched to the editor frame. */
+    contextBadgeStyle: (s: string) => string;
+    /** 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: boolean;
+    /** 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 supplies the
+     *  broker-supplied inventory. */
+    private resolvedRefNames;
+    /** 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 (`slashCommandList` is a different, remote-filtered,
+     *  broker-augmented list, not a dispatch predicate). */
+    private localCommandNames;
+    /** Leading tokens the ENGINE (broker) independently consumes as a leading
+     *  command/skill/template dispatch — the broker's own
+     *  `engineLeadingCommandNames`, checked against the UNTRIMMED leading-name
+     *  rule (`matchesEngineLeadingCommand`, mirroring the broker's own
+     *  `isLeadingEngineCommand`). Populated from each
+     *  `list_memory_refs` reply, alongside `resolvedRefNames`. */
+    private engineCommandNames;
+    setResolvedRefNames(names: Iterable<string>): void;
+    /** The canonical names of memory refs currently resolvable in this session —
+     *  used to record ref usage on submit without counting non-ref slash tokens. */
+    getResolvedRefNames(): ReadonlySet<string>;
+    setLocalCommandNames(names: Iterable<string>): void;
+    setEngineCommandNames(names: Iterable<string>): void;
+    /** 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) — 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 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). */
+    private decorateResolvedRefs;
+    render(width: number): string[];
+}