@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/render/tool-calls.js

@@ -0,0 +1,350 @@
+// render/tool-calls.ts — attach-viewer call headers for the plain agent tools.
+//
+// pi's builtin renderers name a tool with a bold word (`read <path>`,
+// `$ <the entire command line>`). In the crtr viewer a tool call is a card the
+// human scans, not a shell echo (inline-ui-placement rule 12): each tool gets
+// its own Nerd Font glyph, and `bash` gets a compact, syntax-colored ONE-LINE
+// summary instead of dumping a multi-line command into the transcript. The
+// full command is still one ctrl+o away (rule 10: terse by default, reveal on
+// demand).
+//
+// Only the CALL is re-skinned here; every result renderer stays pi's builtin,
+// so output, truncation, timing and error chrome are untouched.
+import { createBashToolDefinition, createReadToolDefinition, createWriteToolDefinition } from '@earendil-works/pi-coding-agent';
+import { Text, getCapabilities, hyperlink, truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { normalizeBashJobPurpose } from '../../../core/bash-jobs.js';
+import { TOOL_ICON } from '../../../core/preview-registry.js';
+import { stripCdPrefix } from '../../../shared/strip-cd-prefix.js';
+function str(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** How long a bash command must have been running before the transcript offers
+ *  the backgrounding gesture under it. */
+const BACKGROUND_HINT_AFTER_MS = 5_000;
+/** The backgrounding affordance, under the running call it applies to, once the
+ *  command has been running long enough that waiting it out is a real choice.
+ *  Empty for a finished command, one short of the threshold, or a viewer that
+ *  cannot invoke the handoff — the transcript is the user/assistant exchange,
+ *  so this row exists only while it is actionable. */
+function backgroundHintLines(theme, startedAt, hint, width) {
+    if (startedAt === undefined || Date.now() - startedAt < BACKGROUND_HINT_AFTER_MS)
+        return [];
+    const text = hint?.() ?? null;
+    if (text === null)
+        return [];
+    return [truncateToWidth(`  ${theme.fg('muted', `⧗ ${text}`)}`, width, '…')];
+}
+export class FoldedToolCallController {
+    folded = false;
+    component;
+    setFolded(folded) {
+        this.folded = folded;
+    }
+    capture(component) {
+        this.component = component;
+        return component;
+    }
+    callComponent() {
+        return this.component;
+    }
+}
+/** Count file lines the way a diff does: a trailing newline terminates the last
+ *  line instead of creating an extra empty one. */
+function countFileLines(content) {
+    if (content.length === 0)
+        return 0;
+    const newlines = content.match(/\n/g)?.length ?? 0;
+    return newlines + (content.endsWith('\n') ? 0 : 1);
+}
+/** The green/red changed-line suffix shown after a folded edit path. */
+function lineChangesDisplay(changes, theme) {
+    if (!changes)
+        return '';
+    const counts = [];
+    if (changes.added > 0)
+        counts.push(theme.fg('toolDiffAdded', `+${changes.added}`));
+    if (changes.removed > 0)
+        counts.push(theme.fg('toolDiffRemoved', `-${changes.removed}`));
+    return counts.length > 0 ? ` ${counts.join(' ')}` : '';
+}
+/** A write has no before/after diff, so report every output line as added. */
+function lineCountDisplay(lines, theme) {
+    if (lines === undefined)
+        return '';
+    return ` ${theme.fg('toolDiffAdded', `+${lines}`)}`;
+}
+/** The one-line folded form of a file tool's call: `<icon> <label> <path>`,
+ *  optionally followed by its green/red changed-line counts. */
+export function foldedFileCallLine(tool, rawPath, theme, cwd, changes) {
+    return `${header(TOOL_ICON[tool], tool, theme)} ${pathDisplay(rawPath, theme, cwd)}${lineChangesDisplay(changes, theme)}`;
+}
+/** `~`-shorten an absolute path the way pi's renderToolPath does (its
+ *  render-utils module is not exported from the package root). */
+function shortenPath(path) {
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+/** Plain, OSC-8-linked path — the same affordance pi gives file tools. */
+function pathDisplay(rawPath, theme, cwd) {
+    if (!rawPath)
+        return theme.fg('toolOutput', '...');
+    const path = shortenPath(rawPath);
+    if (!getCapabilities().hyperlinks)
+        return path;
+    const absolute = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+    return hyperlink(path, pathToFileURL(absolute).href);
+}
+/** `<icon> <label>` — the glyph in accent, the tool name in pi's tool title style. */
+function header(icon, label, theme) {
+    return `${theme.fg('accent', icon)} ${theme.fg('toolTitle', theme.bold(label))}`;
+}
+/** Add an icon to a tool call without mutating the imported renderer's private
+ *  text storage. The imported component remains responsible for its own body. */
+class IconPrefixedToolCall {
+    child;
+    prefix;
+    constructor(child, prefix) {
+        this.child = child;
+        this.prefix = prefix;
+    }
+    update(child, prefix) {
+        this.child = child;
+        this.prefix = prefix;
+    }
+    invalidate() {
+        this.child.invalidate();
+    }
+    render(width) {
+        const prefixWidth = visibleWidth(this.prefix);
+        const lines = this.child.render(Math.max(1, width - prefixWidth));
+        if (lines.length === 0)
+            return [truncateToWidth(this.prefix.trimEnd(), width, '')];
+        return lines.map((line, index) => index === 0 ? truncateToWidth(`${this.prefix}${line}`, width, '') : line);
+    }
+}
+// read
+/** Attach-viewer `read`: an icon + the path (plus any `:offset-limit` range).
+ *  The call is a single line by construction, so a folded read shows exactly
+ *  what it read and nothing else. */
+export function createCrtrReadToolDefinition(cwd, fold = new FoldedToolCallController()) {
+    const builtin = createReadToolDefinition(cwd);
+    return {
+        name: 'read',
+        label: 'read',
+        description: 'Render read calls with a crtr icon header in the attach viewer.',
+        parameters: {},
+        renderCall(args, theme, context) {
+            const a = args;
+            const raw = str(a?.file_path ?? a?.path);
+            let range = '';
+            if (a?.offset !== undefined || a?.limit !== undefined) {
+                const start = typeof a?.offset === 'number' ? a.offset : 1;
+                const end = typeof a?.limit === 'number' ? start + a.limit - 1 : undefined;
+                range = theme.fg('warning', `:${start}${end !== undefined ? `-${end}` : ''}`);
+            }
+            const line = `${header(TOOL_ICON.read, 'read', theme)} ${pathDisplay(raw, theme, context.cwd ?? cwd)}${range}`;
+            const component = context.lastComponent ?? new Text('', 0, 0);
+            component.setText(line);
+            return fold.capture(component);
+        },
+        renderResult(result, options, theme, context) {
+            return builtin.renderResult(result, options, theme, context);
+        },
+    };
+}
+// write
+/** Attach-viewer `write`: pi's builtin call renderer (it owns the
+ *  syntax-highlighted content preview and its expand hint) with the icon
+ *  prefixed onto its header line. Folded, only that header survives. */
+export function createCrtrWriteToolDefinition(cwd, fold = new FoldedToolCallController()) {
+    const builtin = createWriteToolDefinition(cwd);
+    let builtinCall;
+    let decoratedCall;
+    return {
+        name: 'write',
+        label: 'write',
+        description: 'Render write calls with a crtr icon header in the attach viewer.',
+        parameters: {},
+        renderCall(args, theme, context) {
+            if (fold.folded) {
+                const a = args;
+                const lines = context.isError ? undefined : countFileLines(str(a?.content));
+                const line = foldedFileCallLine('write', str(a?.file_path ?? a?.path), theme, context.cwd ?? cwd) +
+                    lineCountDisplay(lines, theme);
+                return fold.capture(new Text(line, 0, 0));
+            }
+            builtinCall = builtin.renderCall(args, theme, { ...context, lastComponent: builtinCall });
+            const prefix = `${theme.fg('accent', TOOL_ICON.write)} `;
+            if (decoratedCall)
+                decoratedCall.update(builtinCall, prefix);
+            else
+                decoratedCall = new IconPrefixedToolCall(builtinCall, prefix);
+            return fold.capture(decoratedCall);
+        },
+        renderResult(result, options, theme, context) {
+            return builtin.renderResult(result, options, theme, context);
+        },
+    };
+}
+// bash (non-crtr commands; `crtr ...` invocations get the command card in
+// render/crtr-output.ts)
+const OPERATOR_RE = /^(&&|\|\||\||;|>>|>|<|2>&1|&)$/;
+/** Split a command into shell-ish tokens, keeping quoted spans whole. */
+function tokenize(line) {
+    return line.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\S+/g) ?? [];
+}
+/** Color a single command line so it reads at a glance: program name first,
+ *  operators marking the pipeline joints, flags and quoted strings toned to
+ *  their own hues, everything else plain tool output. */
+function styleCommandLine(line, theme) {
+    const tokens = tokenize(line);
+    let atSegmentStart = true;
+    const styled = tokens.map((token) => {
+        if (OPERATOR_RE.test(token)) {
+            atSegmentStart = true;
+            return theme.fg('syntaxOperator', token);
+        }
+        if (atSegmentStart && !token.includes('=')) {
+            atSegmentStart = false;
+            return theme.fg('syntaxFunction', theme.bold(token));
+        }
+        atSegmentStart = false;
+        if (token.startsWith('-'))
+            return theme.fg('muted', token);
+        if (/^["']/.test(token))
+            return theme.fg('syntaxString', token);
+        return theme.fg('toolOutput', token);
+    });
+    return styled.join(' ');
+}
+/** The bash call header. Collapsed it is exactly ONE line — icon, the command's
+ *  first line styled, truncated to the pane with a muted `+N lines` count when
+ *  there is more. Expanded (ctrl+o) it prints every line of the command, wrapped
+ *  (never clipped — expanded is the raw truth) into the pane with continuations
+ *  hanging under the icon. A line wider than the pane would desync pi-tui's line
+ *  accounting against the terminal's own wrapping and garble the frame.
+ *
+ *  FOLDED, a call that supplied a `purpose` shows that clause INSTEAD of the
+ *  command: the fold is a dense index of what the turn did, and the agent's own
+ *  words for why it ran this read better there than `rg -n … | head -30`. The
+ *  command itself is never lost — unfolding (or ctrl+o) shows it verbatim. */
+class BashCallComponent {
+    command = '';
+    purpose;
+    expanded = false;
+    folded = false;
+    timeout;
+    theme;
+    startedAt;
+    hint;
+    /** Nothing is cached across paints (render recomputes from the fields), so
+     *  pi's cache-drop hook has nothing to do here. */
+    invalidate() { }
+    update(theme, command, purpose, expanded, folded, timeout, startedAt, hint) {
+        this.theme = theme;
+        this.command = command;
+        this.purpose = purpose;
+        this.expanded = expanded;
+        this.folded = folded;
+        this.timeout = timeout;
+        this.startedAt = startedAt;
+        this.hint = hint;
+    }
+    /** The backgrounding affordance, under the call it applies to, once this
+     *  command has been running long enough that waiting it out is a real choice.
+     *  Empty for a command that has finished, one that has not reached the
+     *  threshold, or a viewer that cannot invoke the handoff — the transcript is
+     *  the user/assistant exchange, so this row exists only while it is
+     *  actionable. */
+    /** The backgrounding row for this call. Rendered by the tool component that
+     *  OWNS this call, after the whole block, so it lands outside the highlighted
+     *  band the block paints rather than inside it. */
+    backgroundHintLines(width) {
+        const theme = this.theme;
+        return theme === undefined ? [] : backgroundHintLines(theme, this.startedAt, this.hint, width);
+    }
+    render(width) {
+        const theme = this.theme;
+        if (!theme)
+            return [];
+        const icon = theme.fg('accent', TOOL_ICON.bash);
+        if (this.purpose !== undefined) {
+            return [truncateToWidth(`${icon} ${theme.fg('toolOutput', this.purpose)}`, width, '…')];
+        }
+        const trimmed = this.command.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+        const lines = this.folded ? trimmed.map(stripCdPrefix) : trimmed;
+        const suffix = this.timeout ? theme.fg('muted', ` (timeout ${this.timeout}s)`) : '';
+        if (lines.length === 0)
+            return [`${icon} ${theme.fg('toolOutput', '...')}`];
+        if (this.expanded) {
+            const prefixWidth = visibleWidth(`${icon} `);
+            const indent = ' '.repeat(prefixWidth);
+            const inner = Math.max(1, width - prefixWidth);
+            const body = [];
+            for (let i = 0; i < lines.length; i++) {
+                let styled = styleCommandLine(lines[i], theme);
+                if (i === lines.length - 1)
+                    styled += suffix;
+                const wrapped = wrapTextWithAnsi(styled, inner);
+                for (let j = 0; j < wrapped.length; j++) {
+                    body.push(`${i === 0 && j === 0 ? `${icon} ` : indent}${wrapped[j]}`);
+                }
+            }
+            // Final backstop: at a pane narrower than the prefix itself the wrap
+            // budget bottoms out at 1 and a wrapped line can still overhang.
+            return body.map((line) => truncateToWidth(line, width, ''));
+        }
+        const more = lines.length > 1 ? theme.fg('muted', ` +${lines.length - 1} lines`) : '';
+        const fixed = visibleWidth(`${icon} `) + visibleWidth(more) + visibleWidth(suffix);
+        const budget = Math.max(8, width - fixed);
+        const first = lines[0];
+        const shown = first.length > budget ? `${first.slice(0, Math.max(1, budget - 1))}…` : first;
+        return [truncateToWidth(`${icon} ${styleCommandLine(shown, theme)}${more}${suffix}`, width)];
+    }
+}
+/** The backgrounding row for a tool component's captured call — nothing unless
+ *  that call is a bash command still running past the threshold. The owning tool
+ *  component renders it after its whole block, which is what keeps the row
+ *  outside the highlighted band. */
+export function bashCallBackgroundHintLines(call, width) {
+    return call instanceof BashCallComponent ? call.backgroundHintLines(width) : [];
+}
+/** Attach-viewer `bash` for anything that is not a `crtr` invocation. */
+export function createCrtrPlainBashToolDefinition(cwd, fold = new FoldedToolCallController(), backgroundHint) {
+    const builtin = createBashToolDefinition(cwd);
+    return {
+        name: 'bash',
+        label: 'bash',
+        description: 'Render plain bash calls as a compact styled command line in the attach viewer.',
+        parameters: {},
+        renderCall(args, theme, context) {
+            const a = args;
+            // pi's builtin bash result renderer reads the elapsed clock off this shared
+            // state, which its own renderCall would have started — keep stamping it so a
+            // running command still shows its duration.
+            const state = context.state;
+            if (state && context.executionStarted && state.startedAt === undefined) {
+                state.startedAt = Date.now();
+                state.endedAt = undefined;
+            }
+            const component = context.lastComponent instanceof BashCallComponent ? context.lastComponent : new BashCallComponent();
+            // Running = execution started and no result has stamped `endedAt`. The
+            // hint row lives on that fact, so it disappears the moment the command
+            // returns without anything having to clear it.
+            const running = state?.startedAt !== undefined && state.endedAt === undefined;
+            component.update(theme, str(a?.command), 
+            // The purpose stands in for the command only while folded; it is normalized
+            // here because it is model-supplied text painted straight into the frame.
+            fold.folded ? normalizeBashJobPurpose(a?.purpose) ?? undefined : undefined, 
+            // Folded wins over ctrl+o expansion: a folded bash is always its one-line form.
+            Boolean(context.expanded) && !fold.folded, fold.folded, typeof a?.timeout === 'number' ? a.timeout : undefined, running ? state?.startedAt : undefined, backgroundHint);
+            return fold.capture(component);
+        },
+        renderResult(result, options, theme, context) {
+            return builtin.renderResult(result, options, theme, context);
+        },
+    };
+}

package/dist/clients/attach/render/transcript-copy.d.ts

@@ -0,0 +1,9 @@
+import type { ChatView } from './chat-view.js';
+import type { ViewportSource } from './measured-container.js';
+import type { TranscriptViewport } from './viewport.js';
+export type CopyTarget = 'message' | 'last-assistant' | 'tool' | 'transcript';
+export interface TranscriptCopy {
+    /** Copy `target`; returns the status-region confirmation to show. */
+    copy(target: CopyTarget): string;
+}
+export declare function createTranscriptCopy(chat: ChatView, viewport: TranscriptViewport, source: ViewportSource): TranscriptCopy;

package/dist/clients/attach/render/transcript-copy.js

@@ -0,0 +1,81 @@
+import { writeClipboardTextEverywhere } from '../../../core/clipboard-text.js';
+function hasText(text) {
+    return text !== undefined && text.trim() !== '';
+}
+function lineCount(text) {
+    return text.split('\n').length;
+}
+function copiedTo(system, tmux) {
+    if (system && tmux)
+        return 'clipboard + tmux buffer';
+    if (system)
+        return 'clipboard';
+    if (tmux)
+        return 'tmux buffer';
+    return undefined;
+}
+/** Resolves the newest copyable block wholly visible before falling back to one
+ * merely intersecting the current viewport. */
+function visibleMessageText(chat, viewport, source) {
+    const { first, last, lastFullyVisible } = viewport.visibleBlocks();
+    const textAt = (index) => {
+        const block = source.blockAt(index);
+        return block ? chat.blockText(block) : undefined;
+    };
+    for (let index = Math.min(last, lastFullyVisible); index >= first; index--) {
+        const text = textAt(index);
+        if (hasText(text))
+            return text;
+    }
+    for (let index = last; index >= first; index--) {
+        const text = textAt(index);
+        if (hasText(text))
+            return text;
+    }
+    return undefined;
+}
+export function createTranscriptCopy(chat, viewport, source) {
+    return {
+        copy(target) {
+            let resolved;
+            let emptyNotice;
+            switch (target) {
+                case 'message': {
+                    const text = visibleMessageText(chat, viewport, source);
+                    if (hasText(text))
+                        resolved = { text, label: 'message' };
+                    emptyNotice = 'Nothing to copy — no visible message';
+                    break;
+                }
+                case 'last-assistant': {
+                    const text = chat.getLastAssistantText();
+                    if (hasText(text))
+                        resolved = { text, label: 'last assistant message' };
+                    emptyNotice = 'Nothing to copy — no assistant message yet';
+                    break;
+                }
+                case 'tool': {
+                    const text = chat.getLastToolOutputText();
+                    if (hasText(text))
+                        resolved = { text, label: 'tool output' };
+                    emptyNotice = 'Nothing to copy — no tool output yet';
+                    break;
+                }
+                case 'transcript': {
+                    const text = chat.getTranscriptPlainText();
+                    if (hasText(text))
+                        resolved = { text, label: 'transcript' };
+                    emptyNotice = 'Nothing to copy — transcript is empty';
+                    break;
+                }
+            }
+            if (!resolved)
+                return emptyNotice;
+            const { system, tmux } = writeClipboardTextEverywhere(resolved.text);
+            const destination = copiedTo(system, tmux);
+            if (!destination)
+                return 'Copy failed — no clipboard tool found';
+            return `Copied ${resolved.label} (${lineCount(resolved.text)} lines) — ${destination}`;
+        },
+    };
+}

package/dist/clients/attach/render/transcript-search.d.ts

@@ -0,0 +1,28 @@
+import type { ViewportSource } from './measured-container.js';
+/** One hit: an absolute content line and the cells it covers on that line. */
+export interface SearchMatch {
+    line: number;
+    from: number;
+    to: number;
+}
+export interface TranscriptSearchModel {
+    /** Replace the query; matches and the current hit are recomputed lazily. */
+    setQuery(query: string, near: number | undefined): void;
+    query(): string;
+    /** Every hit, oldest to newest, against the current content. */
+    matches(width: number): readonly SearchMatch[];
+    /** The selected hit, or undefined when the query finds nothing. */
+    current(width: number): SearchMatch | undefined;
+    /** Number of hits and the 1-indexed position of the selected one. */
+    status(width: number): {
+        index: number;
+        total: number;
+    };
+    /** Step the selection; wraps at both ends. Returns the new selection. */
+    step(width: number, direction: 1 | -1): SearchMatch | undefined;
+    /** Re-select the first hit at or after `line`, else the last one. */
+    selectNear(width: number, line: number): SearchMatch | undefined;
+    /** Paint hits onto one rendered transcript row. Identity without a query. */
+    decorate(line: number, rendered: string, width: number): string;
+}
+export declare function createTranscriptSearchModel(source: ViewportSource): TranscriptSearchModel;

package/dist/clients/attach/render/transcript-search.js

@@ -0,0 +1,152 @@
+// render/transcript-search.ts — the transcript search match model.
+//
+// Search runs over the RENDERED lines of the viewport source, not over a
+// separate text record, so it finds exactly what is on screen: a collapsed tool
+// group contributes no blocks to `ViewportSource`, so its output is not
+// searchable while it is folded, and folding it back open makes it searchable
+// again with no bookkeeping here.
+//
+// Matches are held as absolute content lines and terminal cell ranges, which is
+// what the viewport needs to scroll to one and what `highlightCells` needs to
+// paint one.
+import { styleCells, walkRow } from '../ansi-cells.js';
+/** Hits are painted as backgrounds with black text, the way an editor marks
+ *  find results: white for every hit, amber for the one you are standing on, so
+ *  a screen full of hits still says which of them `n` will leave. */
+const HIT_STYLE = { on: '\x1b[107m\x1b[30m', off: '', restore: true };
+const SELECTED_HIT_STYLE = { on: '\x1b[48;5;214m\x1b[30m', off: '', restore: true };
+function plainRow(line) {
+    let text = '';
+    const cells = [];
+    const width = walkRow(line, {
+        onGlyph: (glyph) => {
+            // One entry per code unit, so a string index maps straight back to a cell
+            // even across wide graphemes and surrogate pairs.
+            for (let i = 0; i < glyph.text.length; i++)
+                cells.push(glyph.cell);
+            text += glyph.text;
+        },
+    });
+    return { text, cells, width };
+}
+/** Vim smartcase: an all-lowercase query ignores case, any uppercase pins it. */
+function caseSensitive(query) {
+    return query !== query.toLowerCase();
+}
+function rowMatches(row, query, sensitive, line, out) {
+    const haystack = sensitive ? row.text : row.text.toLowerCase();
+    const needle = sensitive ? query : query.toLowerCase();
+    let at = haystack.indexOf(needle);
+    while (at !== -1) {
+        const end = at + needle.length;
+        const from = row.cells[at] ?? 0;
+        const to = end < row.cells.length ? row.cells[end] : row.width;
+        if (to > from)
+            out.push({ line, from, to });
+        at = haystack.indexOf(needle, at + Math.max(1, needle.length));
+    }
+}
+export function createTranscriptSearchModel(source) {
+    let query = '';
+    let selected = 0;
+    let cached = [];
+    let cachedByLine = new Map();
+    let cacheKey;
+    /** Where to re-anchor the selection after the next recompute. */
+    let pendingNear;
+    function ensure(width) {
+        const key = `${width}:${source.revision()}:${query}`;
+        if (cacheKey === key)
+            return cached;
+        const found = [];
+        if (query !== '') {
+            const sensitive = caseSensitive(query);
+            const count = source.blockCount();
+            for (let block = 0; block < count; block++) {
+                const start = source.blockStart(block, width);
+                const lines = source.blockLines(block, width);
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    // Cheap reject before the cell walk: most rows never contain the
+                    // query, and plainRow() is the expensive part of this scan.
+                    if (!line.toLowerCase().includes(query.toLowerCase()))
+                        continue;
+                    rowMatches(plainRow(line), query, sensitive, start + i, found);
+                }
+            }
+        }
+        const byLine = new Map();
+        for (const match of found) {
+            const bucket = byLine.get(match.line);
+            if (bucket)
+                bucket.push(match);
+            else
+                byLine.set(match.line, [match]);
+        }
+        cached = found;
+        cachedByLine = byLine;
+        cacheKey = key;
+        if (pendingNear !== undefined) {
+            const near = pendingNear;
+            pendingNear = undefined;
+            const at = found.findIndex((match) => match.line >= near);
+            selected = at === -1 ? Math.max(0, found.length - 1) : at;
+        }
+        else if (selected >= found.length) {
+            selected = Math.max(0, found.length - 1);
+        }
+        return cached;
+    }
+    return {
+        setQuery(next, near) {
+            if (next === query)
+                return;
+            query = next;
+            pendingNear = near;
+            cacheKey = undefined;
+        },
+        query() {
+            return query;
+        },
+        matches(width) {
+            return ensure(width);
+        },
+        current(width) {
+            const found = ensure(width);
+            return found[selected];
+        },
+        status(width) {
+            const found = ensure(width);
+            return { index: found.length === 0 ? 0 : selected + 1, total: found.length };
+        },
+        step(width, direction) {
+            const found = ensure(width);
+            if (found.length === 0)
+                return undefined;
+            selected = (selected + direction + found.length) % found.length;
+            return found[selected];
+        },
+        selectNear(width, line) {
+            const found = ensure(width);
+            if (found.length === 0)
+                return undefined;
+            const at = found.findIndex((match) => match.line >= line);
+            selected = at === -1 ? found.length - 1 : at;
+            return found[selected];
+        },
+        decorate(line, rendered, width) {
+            if (query === '')
+                return rendered;
+            const found = ensure(width);
+            const bucket = cachedByLine.get(line);
+            if (bucket === undefined)
+                return rendered;
+            const selectedMatch = found[selected];
+            let painted = rendered;
+            for (const match of bucket) {
+                painted = styleCells(painted, match.from, match.to, width, match === selectedMatch ? SELECTED_HIT_STYLE : HIT_STYLE);
+            }
+            return painted;
+        },
+    };
+}

package/dist/clients/attach/render/viewport.d.ts

@@ -0,0 +1,38 @@
+import type { ViewportSource } from './measured-container.js';
+/** The flat block range occupied by the most recently rendered viewport. */
+type VisibleBlocks = {
+    first: number;
+    last: number;
+    lastFullyVisible: number;
+};
+/**
+ * A virtualized, identity-anchored transcript viewport. It owns only scroll
+ * state; all measurement and line caching remain with its ViewportSource.
+ */
+export interface TranscriptViewport {
+    /** Exactly `rows` lines, bottom-aligned and top-padded with empty rows. */
+    renderSlice(width: number, rows: number): string[];
+    /** Scroll by `lines` (negative = toward older content). */
+    scrollBy(lines: number): boolean;
+    /** Lines in one page jump — the viewport height less one overlap row. */
+    pageRows(): number;
+    /** Pin back to the live bottom. */
+    goLive(): void;
+    /** Bring absolute content `line` into view, seated a third of the way down
+     *  so the context around it reads. */
+    scrollToLine(line: number): void;
+    /** Absolute content line at the viewport's top row, or undefined before the
+     *  first render. */
+    topLine(): number | undefined;
+    /** True while the viewport is pinned to the bottom. */
+    isLive(): boolean;
+    /** Flat blocks intersecting the visible slice and its last whole block. */
+    visibleBlocks(): VisibleBlocks;
+    /** Forward frame invalidation without exposing the source to the frame. */
+    invalidate(): void;
+}
+/** Restyle one rendered transcript row, addressed by its absolute content
+ *  line — how transcript search paints its hits. */
+export type RowDecorator = (line: number, rendered: string, width: number) => string;
+export declare function createTranscriptViewport(source: ViewportSource, decorate?: RowDecorator): TranscriptViewport;
+export {};