@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/overlays/PromptTextArea.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The one editable multi-line field in this feature (quick-prompt-library D-11).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * RENDER AND CARET COME FROM THE SAME FUNCTION. `layoutComposer` wraps the buffer and
+ * reports the caret's row and column from ONE `buildEditorVisualMap` pass, and the
+ * drawing below splits that same row at that same column. Every second authority
+ * here - a prose wrapper, a second width table, a "count the characters instead" -
+ * puts the caret on a cell that does not hold the character it points at, and the
+ * only symptom is that the user's edits land one column off in Chinese text.
+ *
+ * WHY `layout/wrap-rows.ts::wrapToRows` IS BANNED HERE (it is used one directory
+ * away, for the list's read-only preview): it splits on whitespace and rejoins with
+ * single spaces, so it eats indentation and destroys the character-index-to-cell
+ * mapping. `composer-rows.ts:16-20` says so in as many words, and that is the module
+ * this one borrows from.
+ *
+ * NO PASTE-COLLAPSE TOKENS, deliberately. The token machinery exists so a 218-line
+ * paste does not have to live in a one-line input; this IS a multi-line field, and a
+ * token inside a saved prompt body would be data corruption the user could not undo.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+export interface PromptTextAreaState {
+    buffer: string;
+    cursor: number;
+    /** Kept across vertical moves, cleared by any horizontal one (composer parity). */
+    preferredVisualColumn?: number;
+}
+export declare const EMPTY_TEXT_AREA: PromptTextAreaState;
+export type PromptTextAreaAction = {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'newline';
+} | {
+    type: 'backspace';
+} | {
+    type: 'delete';
+} | {
+    type: 'left';
+} | {
+    type: 'right';
+} | {
+    type: 'home';
+} | {
+    type: 'end';
+}
+/** Vertical moves need the wrap width; it is part of the ACTION, not of the state. */
+ | {
+    type: 'up';
+    cols: number;
+} | {
+    type: 'down';
+    cols: number;
+} | {
+    type: 'replace';
+    buffer: string;
+    cursor: number;
+};
+/**
+ * Pure. No React, no Ink, no filesystem - so the twelve editing cases are a table
+ * test rather than a rendered frame assertion.
+ */
+export declare function promptTextAreaReducer(state: PromptTextAreaState, action: PromptTextAreaAction): PromptTextAreaState;
+export interface PromptTextAreaProps {
+    state: PromptTextAreaState;
+    /** Wrap width, in cells, already net of the field's own chrome. */
+    cols: number;
+    /** Rows the field may occupy. `1` is the single-line case for title/description. */
+    rows: number;
+    focused: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+    reducedMotion?: boolean;
+}
+/**
+ * One field's worth of rows.
+ *
+ * The overflow chip is a plain `+N` on the LAST row rather than a row of its own:
+ * an extra row would make this component draw one more line than the caller budgeted
+ * for, and the frame it lives in has no way to find out.
+ */
+export declare function PromptTextArea(props: PromptTextAreaProps): React.ReactElement;

package/dist/ui/overlays/PromptTextArea.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The one editable multi-line field in this feature (quick-prompt-library D-11).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * RENDER AND CARET COME FROM THE SAME FUNCTION. `layoutComposer` wraps the buffer and
+ * reports the caret's row and column from ONE `buildEditorVisualMap` pass, and the
+ * drawing below splits that same row at that same column. Every second authority
+ * here - a prose wrapper, a second width table, a "count the characters instead" -
+ * puts the caret on a cell that does not hold the character it points at, and the
+ * only symptom is that the user's edits land one column off in Chinese text.
+ *
+ * WHY `layout/wrap-rows.ts::wrapToRows` IS BANNED HERE (it is used one directory
+ * away, for the list's read-only preview): it splits on whitespace and rejoins with
+ * single spaces, so it eats indentation and destroys the character-index-to-cell
+ * mapping. `composer-rows.ts:16-20` says so in as many words, and that is the module
+ * this one borrows from.
+ *
+ * NO PASTE-COLLAPSE TOKENS, deliberately. The token machinery exists so a 218-line
+ * paste does not have to live in a one-line input; this IS a multi-line field, and a
+ * token inside a saved prompt body would be data corruption the user could not undo.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { layoutComposer, splitRowAtColumn } from '../composer-rows.js';
+import { moveVisualCursor, snapGrapheme, stepGrapheme } from '../editor-navigation.js';
+import { PromptCaret } from '../PromptCaret.js';
+export const EMPTY_TEXT_AREA = { buffer: '', cursor: 0 };
+function withCursor(state, buffer, cursor) {
+    return { buffer, cursor: snapGrapheme(buffer, cursor, true) };
+}
+/**
+ * Pure. No React, no Ink, no filesystem - so the twelve editing cases are a table
+ * test rather than a rendered frame assertion.
+ */
+export function promptTextAreaReducer(state, action) {
+    switch (action.type) {
+        case 'insert': {
+            const cursor = snapGrapheme(state.buffer, state.cursor);
+            const buffer = state.buffer.slice(0, cursor) + action.text + state.buffer.slice(cursor);
+            return {
+                buffer,
+                cursor: snapGrapheme(buffer, cursor + action.text.length, true),
+            };
+        }
+        case 'newline': {
+            const cursor = snapGrapheme(state.buffer, state.cursor);
+            const buffer = `${state.buffer.slice(0, cursor)}\n${state.buffer.slice(cursor)}`;
+            return { buffer, cursor: cursor + 1 };
+        }
+        case 'backspace':
+        case 'delete': {
+            const cursor = snapGrapheme(state.buffer, state.cursor);
+            if (action.type === 'backspace') {
+                if (cursor <= 0)
+                    return state;
+                const from = stepGrapheme(state.buffer, cursor, 'left');
+                return withCursor(state, state.buffer.slice(0, from) + state.buffer.slice(cursor), from);
+            }
+            if (cursor >= state.buffer.length)
+                return state;
+            const to = stepGrapheme(state.buffer, cursor, 'right');
+            return withCursor(state, state.buffer.slice(0, cursor) + state.buffer.slice(to), cursor);
+        }
+        case 'left':
+            return {
+                buffer: state.buffer,
+                cursor: stepGrapheme(state.buffer, state.cursor, 'left'),
+            };
+        case 'right':
+            return {
+                buffer: state.buffer,
+                cursor: stepGrapheme(state.buffer, state.cursor, 'right'),
+            };
+        case 'home':
+            return { buffer: state.buffer, cursor: 0 };
+        case 'end':
+            return { buffer: state.buffer, cursor: snapGrapheme(state.buffer, state.buffer.length) };
+        case 'up':
+        case 'down': {
+            const moved = moveVisualCursor({
+                buffer: state.buffer,
+                cursor: state.cursor,
+                cols: action.cols,
+                direction: action.type,
+                ...(state.preferredVisualColumn === undefined
+                    ? {}
+                    : { preferredVisualColumn: state.preferredVisualColumn }),
+            });
+            // A vertical move at the first or last visual row stays put rather than
+            // jumping to the buffer's edge: the composer behaves the same way, and a jump
+            // here would silently relocate the caret in a field the user is editing.
+            return moved === null
+                ? state
+                : {
+                    buffer: state.buffer,
+                    cursor: moved.cursor,
+                    preferredVisualColumn: moved.preferredVisualColumn,
+                };
+        }
+        case 'replace':
+            return withCursor(state, action.buffer, action.cursor);
+    }
+}
+function renderSegments(segments, keyPrefix) {
+    return segments.map((segment, at) => (_jsx(Text, { children: segment.text }, `${keyPrefix}${at}`)));
+}
+/**
+ * One field's worth of rows.
+ *
+ * The overflow chip is a plain `+N` on the LAST row rather than a row of its own:
+ * an extra row would make this component draw one more line than the caller budgeted
+ * for, and the frame it lives in has no way to find out.
+ */
+export function PromptTextArea(props) {
+    const { state, cols, rows, focused } = props;
+    const glyphs = pickGlyphs(props.caps);
+    const layout = layoutComposer({
+        buffer: state.buffer,
+        cursor: state.cursor,
+        cols: Math.max(4, cols),
+        maxRows: Math.max(1, rows),
+        active: focused,
+    });
+    const hidden = layout.hiddenAbove + layout.hiddenBelow;
+    const resetKey = React.useMemo(() => ({}), [state.buffer, state.cursor, focused, props.cols, rows]);
+    if (state.buffer.length === 0) {
+        return (_jsxs(Text, { wrap: "truncate", color: props.theme.muted, children: [_jsx(PromptCaret, { text: " ", active: focused, reducedMotion: props.reducedMotion ?? false, colorLevel: props.caps.colorLevel, color: props.theme.muted, resetKey: resetKey }), glyphs.ellipsis] }));
+    }
+    return (_jsx(Box, { flexDirection: "column", children: layout.rows.map((row, at) => {
+            if (at !== layout.cursorRow) {
+                return _jsx(Text, { wrap: "truncate", children: renderSegments(row.segments, `r${at}.`) }, at);
+            }
+            const split = splitRowAtColumn(row, layout.cursorCol);
+            return (_jsxs(Text, { wrap: "truncate", children: [renderSegments(split.before, `b${at}.`), _jsx(PromptCaret, { text: split.at ? split.at.text : ' ', active: focused, reducedMotion: props.reducedMotion ?? false, colorLevel: props.caps.colorLevel, resetKey: resetKey }), renderSegments(split.after, `a${at}.`), at === layout.rows.length - 1 && hidden > 0
+                        ? _jsx(Text, { color: props.theme.muted, children: ` +${hidden}` })
+                        : null] }, at));
+        }) }));
+}

package/dist/ui/overlays/QuestionOverlay.d.ts

@@ -0,0 +1,39 @@
+/**
+ * QuestionOverlay — the keyboard-driven multiple-choice wizard `ask_user`
+ * renders (plan-mode §6.5).
+ *
+ * `OverlayFrame` MODE B (self-managed): the content is a small state machine,
+ * not a list of rows, and slicing it by element would be meaningless.
+ *
+ * THE SINGLE HIGHEST-VALUE DECISION HERE is that the recommended option is the
+ * initial highlight for every question, so `Enter Enter Enter` is a correct,
+ * deliberate "use your judgement" path rather than an accident.
+ *
+ * `Esc` IS NOT HANDLED HERE. `App` owns it, and the bridge's `settle()` is the
+ * only place a human request is ever answered. `ConfirmDialog` does the
+ * opposite — both it and `App` call `resolve` — which is harmless there only by
+ * accident of promise semantics, and is not a pattern to copy (R-P12).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { Answer, NormalizedQuestion } from '../../model/tools/human-input.js';
+interface QuestionOverlayProps {
+    isActive?: boolean;
+    questions: NormalizedQuestion[];
+    maxRows: number;
+    cols: number;
+    theme: Theme;
+    caps: TermCapabilities;
+    onSubmit: (answers: Answer[]) => void;
+    /**
+     * PLAN+GOVERN interview progress (governance-mode 9 / 10.6). Present only in that
+     * posture; absent leaves the title byte-identical to the pre-governance overlay.
+     */
+    interview?: {
+        round: number;
+        required: number;
+    };
+}
+export declare function QuestionOverlay({ isActive, questions, maxRows, cols, theme, caps, onSubmit, interview, }: QuestionOverlayProps): React.ReactElement;
+export {};

package/dist/ui/overlays/QuestionOverlay.js

@@ -0,0 +1,258 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * QuestionOverlay — the keyboard-driven multiple-choice wizard `ask_user`
+ * renders (plan-mode §6.5).
+ *
+ * `OverlayFrame` MODE B (self-managed): the content is a small state machine,
+ * not a list of rows, and slicing it by element would be meaningless.
+ *
+ * THE SINGLE HIGHEST-VALUE DECISION HERE is that the recommended option is the
+ * initial highlight for every question, so `Enter Enter Enter` is a correct,
+ * deliberate "use your judgement" path rather than an accident.
+ *
+ * `Esc` IS NOT HANDLED HERE. `App` owns it, and the bridge's `settle()` is the
+ * only place a human request is ever answered. `ConfirmDialog` does the
+ * opposite — both it and `App` call `resolve` — which is harmless there only by
+ * accident of promise semantics, and is not a pattern to copy (R-P12).
+ */
+import { useState, useLayoutEffect } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { wrapToRows } from '../layout/wrap-rows.js';
+import { OverlayFrame, overlayBodyRows } from '../layout/OverlayFrame.js';
+import { stripPasteFrames } from '../paste-frames.js';
+import { stripEnterFrames } from '../enter-frames.js';
+import { interviewChipText } from '../governance-status.js';
+/** Which option index each question starts on: the recommended one. */
+function initialCursors(questions) {
+    return questions.map((q) => Math.max(0, q.options.findIndex((o) => o.recommended)));
+}
+function initialSelections(questions) {
+    return questions.map((q) => {
+        const recommended = q.options.findIndex((o) => o.recommended);
+        return new Set(recommended >= 0 ? [recommended] : [0]);
+    });
+}
+export function QuestionOverlay({ isActive = true, questions, maxRows, cols, theme, caps, onSubmit, interview, }) {
+    const glyphs = pickGlyphs(caps);
+    const [step, setStep] = useState(0);
+    const [phase, setPhase] = useState('choosing');
+    const [cursors, setCursors] = useState(() => initialCursors(questions));
+    const [selections, setSelections] = useState(() => initialSelections(questions));
+    /**
+     * THE PER-QUESTION EXPLICIT-MARK BIT (V-1 / D-8).
+     *
+     * `initialSelections` PRE-SELECTS the recommended option on EVERY question
+     * (or the first option when there is none), so "the selection set is empty"
+     * is unreachable and can never be the test for "did the user choose?". The
+     * only reliable discriminator is the fact itself: the user pressed SPACE on
+     * this question. Without it, a user who only MOVES the cursor and presses
+     * Enter would submit the RECOMMENDED option instead of the highlighted one -
+     * a silent regression of the wizard's most common path. The bit survives
+     * Left/Right navigation exactly like `selections` and `cursors` do, and a
+     * single-choice mark is idempotent (no un-mark; Enter always has at least
+     * the marked item to submit).
+     */
+    const [markedSteps, setMarkedSteps] = useState(() => questions.map(() => false));
+    const [customs, setCustoms] = useState(() => questions.map(() => ''));
+    const [draft, setDraft] = useState('');
+    const [offset, setOffset] = useState(0);
+    const question = questions[Math.min(step, questions.length - 1)];
+    const cursor = cursors[step] ?? 0;
+    const setCursorAt = (index, value) => setCursors((prev) => prev.map((c, i) => (i === index ? value : c)));
+    const setCustomAt = (index, value) => setCustoms((prev) => prev.map((c, i) => (i === index ? value : c)));
+    const toggleAt = (index, option) => setSelections((prev) => prev.map((set, i) => {
+        if (i !== index)
+            return set;
+        const next = new Set(set);
+        if (next.has(option))
+            next.delete(option);
+        else
+            next.add(option);
+        return next;
+    }));
+    const chooseAt = (index, option) => setSelections((prev) => prev.map((set, i) => (i === index ? new Set([option]) : set)));
+    const markAt = (index) => setMarkedSteps((prev) => prev.map((marked, i) => (i === index ? true : marked)));
+    const buildAnswers = () => questions.map((q, i) => {
+        const chosen = [...(selections[i] ?? new Set())].sort((a, b) => a - b);
+        const labels = chosen.map((index) => q.options[index]?.label ?? '').filter((l) => l.length > 0);
+        const pickedOther = chosen.some((index) => q.options[index]?.isOther);
+        return {
+            id: q.id,
+            question: q.question,
+            selected: labels,
+            custom: pickedOther && (customs[i] ?? '').length > 0 ? customs[i] : null,
+        };
+    });
+    const advance = () => {
+        if (step + 1 >= questions.length)
+            setPhase('review');
+        else {
+            setStep(step + 1);
+            setPhase('choosing');
+        }
+    };
+    const goBack = () => {
+        if (step === 0)
+            return; // No-op on the first question, by design.
+        setStep(step - 1);
+        setPhase('choosing');
+    };
+    useInput((input, key) => {
+        if (!isActive)
+            return;
+        if (key.pageUp) {
+            setOffset(n => Math.max(0, n - 1));
+            return;
+        }
+        if (key.pageDown) {
+            setOffset(n => n + 1);
+            return;
+        }
+        // App owns Esc for both new overlays (R-P12). Swallow it here so the
+        // free-text editor below cannot eat the raw escape byte as a character.
+        if (key.escape)
+            return;
+        if (phase === 'review') {
+            if (key.return) {
+                onSubmit(buildAnswers());
+                return;
+            }
+            if (key.leftArrow) {
+                setStep(questions.length - 1);
+                setPhase('choosing');
+            }
+            return;
+        }
+        if (phase === 'typingOther') {
+            if (key.return) {
+                // An empty commit falls back to the recommended option rather than
+                // recording a blank answer: the user pressed Enter, which everywhere
+                // else in this wizard means "accept the sensible default".
+                if (draft.trim().length === 0) {
+                    const recommended = Math.max(0, question.options.findIndex((o) => o.recommended));
+                    chooseAt(step, recommended);
+                    setCursorAt(step, recommended);
+                    setCustomAt(step, '');
+                }
+                else {
+                    setCustomAt(step, draft.trim());
+                }
+                setDraft('');
+                setPhase('choosing');
+                advance();
+                return;
+            }
+            if (key.leftArrow) {
+                setDraft('');
+                setPhase('choosing');
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setDraft(draft.slice(0, -1));
+                return;
+            }
+            // `stripPasteFrames`, NOT `input` (I-12 / P0-2) -- the same broadcast
+            // hazard `SettingsScreen` documents at length: a framed paste appended
+            // verbatim stores NULs that render as nothing.
+            // `stripEnterFrames` rides inside it for the newline frame a
+            // Shift+Enter broadcasts (tui-shift-enter-copy-queue 3.5): same hazard,
+            // same fix, and this order is the one that leaves no NUL in the draft.
+            if (input && !key.ctrl && !key.meta && !key.tab) {
+                setDraft(draft + stripPasteFrames(stripEnterFrames(input)));
+            }
+            return;
+        }
+        // phase === 'choosing'
+        if (key.upArrow) {
+            setCursorAt(step, (cursor - 1 + question.options.length) % question.options.length);
+            return;
+        }
+        if (key.downArrow) {
+            setCursorAt(step, (cursor + 1) % question.options.length);
+            return;
+        }
+        if (key.leftArrow) {
+            goBack();
+            return;
+        }
+        // SPACE, BY QUESTION SHAPE (D-8). The strict `input === ' '` keeps a
+        // multi-character paste frame from ever matching (R-8); the Other row is
+        // a no-op in both shapes because it needs TEXT, and Enter is its key.
+        if (input === ' ' && !question.options[cursor]?.isOther) {
+            if (question.allowMultiple) {
+                toggleAt(step, cursor);
+                return;
+            }
+            // SINGLE CHOICE: mark the highlighted item and STAY - the terminal
+            // convention of "space selects, enter confirms". The mark is recorded
+            // both in the selection set (so `[x]` renders) and in the explicit
+            // mark bit (so a later Enter submits THIS item even after the cursor
+            // has moved on).
+            chooseAt(step, cursor);
+            markAt(step);
+            return;
+        }
+        if (key.return) {
+            if (question.options[cursor]?.isOther) {
+                chooseAt(step, cursor);
+                setDraft(customs[step] ?? '');
+                setPhase('typingOther');
+                return;
+            }
+            // A single-choice Enter submits the CURSOR item unless the user has
+            // explicitly space-marked this question, in which case the marked item
+            // wins even if the cursor has since moved (V-1's regression guard:
+            // cursor + Enter alone keeps today's behavior, recommended preselect
+            // and all).
+            if (!question.allowMultiple) {
+                if (!markedSteps[step])
+                    chooseAt(step, cursor);
+            }
+            else if (!(selections[step] ?? new Set()).has(cursor))
+                toggleAt(step, cursor);
+            advance();
+        }
+    });
+    const title = phase === 'review' ? 'Review your answers' : 'Clarify the request';
+    const position = phase === 'review' ? '' : `  ${step + 1}/${questions.length}`;
+    const interviewChip = interview ? `  ${interviewChipText(interview.round, interview.required)}` : '';
+    const hint = phase === 'typingOther'
+        ? `type your answer ${glyphs.midDot} ${glyphs.enterKey} commit ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`
+        : phase === 'review'
+            ? `${glyphs.enterKey} submit ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`
+            : question.options[cursor]?.isOther
+                ? `${glyphs.arrowUp}${glyphs.arrowDown} choose ${glyphs.midDot} ${glyphs.enterKey} to type ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`
+                : `${glyphs.arrowUp}${glyphs.arrowDown} choose ${glyphs.midDot} space select ${glyphs.midDot} ${glyphs.enterKey} next ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc cancel`;
+    const rowTexts = [];
+    const optionStarts = [];
+    const push = (text) => { rowTexts.push(...wrapToRows(text, Math.max(1, cols - 4))); };
+    if (phase === 'review') {
+        buildAnswers().forEach((answer, index) => push(`${questions[index].header}: ${answer.custom ?? answer.selected.join(', ')}`));
+    }
+    else {
+        push(question.header);
+        push(question.question);
+        question.options.forEach((option, index) => {
+            optionStarts.push(rowTexts.length);
+            const mark = (selections[step] ?? new Set()).has(index) ? '[x]' : '[ ]';
+            push(`${index === cursor ? glyphs.caret : ' '} ${mark} ${option.label}${option.recommended ? ' RECOMMENDED' : ''} ${option.description}`);
+        });
+        if (phase === 'typingOther')
+            push(`${glyphs.caret} ${draft || 'type your own answer'} `);
+    }
+    const focus = phase === 'review' ? 0 : phase === 'typingOther'
+        ? Math.max(0, rowTexts.length - 1) : optionStarts[cursor] ?? 0;
+    useLayoutEffect(() => {
+        const height = overlayBodyRows(maxRows, cols);
+        setOffset(previous => focus < previous ? focus : focus >= previous + height
+            ? focus - height + 1 : previous);
+    }, [focus, maxRows, cols, step, phase]);
+    // `space select` shows for BOTH shapes (AC-10) - 42 characters on the
+    // single-choice shape without `cancel`, a deliberate 5-column growth inside
+    // the `cols <= 48` budget this hint exists for (V-12).
+    const shortHint = phase === 'typingOther' ? 'Enter commit | Left back | Esc cancel'
+        : phase === 'review' ? 'Enter submit | Left back | Esc cancel'
+            : '^v choose Space select Enter next Esc';
+    return _jsx(OverlayFrame, { title: `${title}${position}${interviewChip}`, hint: cols <= 48 ? shortHint : hint, maxRows: maxRows, cols: cols, theme: theme, caps: caps, rows: rowTexts.map((line, index) => _jsx(Text, { wrap: "truncate", children: line || ' ' }, index)), scrollOffset: offset, onScrollClamp: setOffset });
+}

package/dist/ui/overlays/QueueOverlay.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { PendingSteering } from '../../model/agent/queued-messages.js';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+export interface QueueTextRow {
+    queueId: string;
+    offset: number;
+    text: string;
+}
+/** Preserve visible whitespace and display terminal controls as harmless escapes. */
+export declare function projectQueueRows(pending: readonly PendingSteering[], columns: number): QueueTextRow[];
+/** Anchor by stable message ID and source offset, including long soft-wrapped lines. */
+export declare function restoreQueueAnchor(before: readonly QueueTextRow[], after: readonly QueueTextRow[], scroll: number): number;
+export declare function QueueOverlay(props: {
+    pending: readonly PendingSteering[];
+    cols: number;
+    maxRows: number;
+    scrollOffset: number;
+    onScrollClamp: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+}): React.ReactElement;

package/dist/ui/overlays/QueueOverlay.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from 'react';
+import { Text } from 'ink';
+import stringWidth from 'string-width';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { graphemes } from '../editor-navigation.js';
+/** Preserve visible whitespace and display terminal controls as harmless escapes. */
+export function projectQueueRows(pending, columns) {
+    const width = Math.max(1, columns);
+    const rows = [];
+    for (const [index, item] of pending.entries()) {
+        rows.push({ queueId: item.queueId, offset: -1, text: `Queue ${index + 1}` });
+        let text = '';
+        let cells = 0;
+        let offset = 0;
+        const flush = () => {
+            rows.push({ queueId: item.queueId, offset, text });
+            text = '';
+            cells = 0;
+        };
+        for (const part of graphemes(item.text)) {
+            if (part.text === '\n' || part.text === '\r\n') {
+                flush();
+                offset = part.end;
+                continue;
+            }
+            const safe = part.text === '\t' ? ' '.repeat(4 - cells % 4)
+                : part.text.replace(/[\x00-\x1f\x7f-\x9f]/g, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+            const units = safe === part.text ? [safe] : Array.from(safe);
+            for (const unit of units) {
+                const size = stringWidth(unit);
+                if (cells + size > width && text) {
+                    flush();
+                    offset = part.index;
+                }
+                text += unit;
+                cells += size;
+            }
+        }
+        flush();
+    }
+    return rows;
+}
+/** Anchor by stable message ID and source offset, including long soft-wrapped lines. */
+export function restoreQueueAnchor(before, after, scroll) {
+    const anchor = before[Math.min(scroll, before.length - 1)];
+    if (!anchor || !after.length)
+        return 0;
+    let target = -1;
+    for (let i = 0; i < after.length; i++) {
+        if (after[i].queueId === anchor.queueId && after[i].offset <= anchor.offset)
+            target = i;
+    }
+    if (target >= 0)
+        return target;
+    const next = before.slice(scroll).find((row) => after.some((item) => item.queueId === row.queueId));
+    if (next)
+        return after.findIndex((row) => row.queueId === next.queueId);
+    const previous = [...before.slice(0, scroll)].reverse()
+        .find((row) => after.some((item) => item.queueId === row.queueId));
+    return previous ? after.findIndex((row) => row.queueId === previous.queueId) : 0;
+}
+export function QueueOverlay(props) {
+    const { pending, cols, scrollOffset, onScrollClamp, theme } = props;
+    const projected = useMemo(() => projectQueueRows(pending, cols - (cols >= 48 ? 4 : 2)), [pending, cols]);
+    const previous = useRef({ rows: projected, scroll: scrollOffset });
+    const anchored = previous.current.rows === projected ? scrollOffset
+        : restoreQueueAnchor(previous.current.rows, projected, previous.current.scroll);
+    const bodyRows = Math.max(1, Math.floor(props.maxRows) - (cols >= 48 ? 5 : 3));
+    const offset = Math.max(0, Math.min(anchored, projected.length - bodyRows));
+    useEffect(() => {
+        previous.current = { rows: projected, scroll: offset };
+        if (offset !== scrollOffset)
+            onScrollClamp(offset);
+    }, [projected, offset, scrollOffset, onScrollClamp]);
+    const rows = useMemo(() => projected.length ? projected.map((row, index) => _jsx(Text, { wrap: "truncate", color: theme.primary, children: row.text || ' ' }, `${row.queueId}:${index}`))
+        : [_jsx(Text, { children: "Queue is empty" }, "empty")], [projected, theme]);
+    return _jsx(OverlayFrame, { ...props, title: `Queue: ${pending.length} pending`, hint: "PgUp/PgDn | Up/Down | Esc", rows: rows, scrollOffset: offset });
+}