@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/overlays/PromptEditorPage.js

@@ -0,0 +1,227 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The prompt editor page (quick-prompt-library §4.4 / D-11).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`. Labels and the footer
+ * are English like every other overlay; every sentence that explains a REFUSAL comes
+ * from `prompts/copy.ts`.
+ *
+ * SELF-MANAGED `OverlayFrame`, not the controlled one. The two modes are a
+ * discriminated union (`children?: undefined`), and this page lays out a multi-row
+ * body field that owns its own scrolling: handing it over as `rows` would mean the
+ * frame counts a body's lines as rows and windows them again (P2-2).
+ *
+ * TWO WAYS TO SAVE, AND THE SECOND ONE IS NOT DECORATION. `Ctrl+S` is the fast path,
+ * and it is a byte a terminal can eat (XON/XOFF) - so `Tab` to the `Save` row and
+ * `Enter` must do exactly the same thing. That is what keeps "I cannot save" from
+ * being a bug a whole class of terminals can reproduce.
+ */
+import { useEffect, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { stripPasteFrames } from '../paste-frames.js';
+import { stripEnterFrames } from '../enter-frames.js';
+import { stepGrapheme } from '../editor-navigation.js';
+import { OverlayFrame, overlayBodyRows } from '../layout/OverlayFrame.js';
+import { promptErrorCopy } from '../../model/prompts/copy.js';
+import { PROMPT_EDITOR_FIELDS, fieldIndex, } from './prompt-library-state.js';
+import { EMPTY_TEXT_AREA, PromptTextArea, promptTextAreaReducer, } from './PromptTextArea.js';
+/** Columns the field labels occupy. Fixed, so the values line up. */
+const LABEL_CELLS = 10;
+/** Body rows the page reserves for chrome when the frame is generous. */
+const MIN_BODY_ROWS = 3;
+/** Text fields of the page, in the order Tab visits them. */
+function nextField(at, delta) {
+    const count = PROMPT_EDITOR_FIELDS.length;
+    return (at + delta + count) % count;
+}
+/**
+ * Which deletion key was pressed, if any.
+ *
+ * `key.delete` IS TREATED AS BACKSPACE, and the reason is measured rather than assumed:
+ * ink's parser reports the `0x7f` byte - which is what the BACKSPACE KEY sends on every
+ * terminal this product runs on - as `name: 'delete'`, and it hands the component an
+ * EMPTY `input` for both it and `ESC [ 3 ~`. The two are therefore indistinguishable at
+ * this layer, and the safe reading is the one the keyboard actually produces: backward.
+ * A forward-delete binding that fired on Backspace would delete the character the user
+ * was not looking at, and there is no undo in this field.
+ */
+function deletionKind(_input, key) {
+    return key.backspace === true || key.delete === true ? 'backspace' : null;
+}
+/**
+ * The page.
+ *
+ * The draft lives in the parent (the reducer owns it, so `Save` and `Esc` can see the
+ * same text); this component owns only what no other surface needs: which row has
+ * focus, and where each single-line field's caret sits.
+ */
+export function PromptEditorPage(props) {
+    const { state, cols, maxRows, theme, caps } = props;
+    const draft = state.draft;
+    const glyphs = pickGlyphs(caps);
+    const [focus, setFocus] = useState(0);
+    // THE CARET STARTS AT THE END OF EACH FIELD, which is where a user expects to append:
+    // starting at 0 would put every typed character in FRONT of the prefilled text, so an
+    // edit to `Clean code review` would read `FixClean code review`.
+    const [cursors, setCursors] = useState(() => ({
+        title: draft.title.length,
+        description: draft.description.length,
+        tags: draft.tags.length,
+    }));
+    const [content, setContent] = useState({
+        ...EMPTY_TEXT_AREA,
+        buffer: draft.content,
+        cursor: draft.content.length,
+    });
+    const field = PROMPT_EDITOR_FIELDS[Math.min(focus, PROMPT_EDITOR_FIELDS.length - 1)];
+    const bodyRows = Math.max(MIN_BODY_ROWS, overlayBodyRows(maxRows, cols) - 5);
+    const fieldCols = Math.max(8, cols - LABEL_CELLS - 6);
+    // A REFUSAL OWNS THE FOCUS (D-12): the store already names the row that failed, so the
+    // caret is moved there instead of leaving the user to read an error in a footer and
+    // work out which of four fields it is about. Keyed on `state.error`, so it fires once
+    // per distinct refusal rather than on every render.
+    useEffect(() => {
+        if (state.error === null)
+            return;
+        setFocus(fieldIndex(state.errorField));
+    }, [state.error, state.errorField]);
+    const editSingle = (name, text, key, deletion) => {
+        const value = draft[name];
+        const cursor = Math.min(cursors[name], value.length);
+        if (key.leftArrow || key.rightArrow) {
+            setCursors({
+                ...cursors,
+                [name]: stepGrapheme(value, cursor, key.leftArrow ? 'left' : 'right'),
+            });
+            return;
+        }
+        if (deletion === 'backspace') {
+            if (cursor <= 0)
+                return;
+            const from = stepGrapheme(value, cursor, 'left');
+            props.onDraft({ [name]: value.slice(0, from) + value.slice(cursor) });
+            setCursors({ ...cursors, [name]: from });
+            return;
+        }
+        if (text.length === 0)
+            return;
+        const next = value.slice(0, cursor) + text + value.slice(cursor);
+        props.onDraft({ [name]: next });
+        setCursors({ ...cursors, [name]: cursor + text.length });
+    };
+    const applyContent = (action) => {
+        const current = { ...content, buffer: draft.content };
+        const next = promptTextAreaReducer(current, action);
+        // COMPARED ON THE FIELDS, not on object identity: the reducer echoes its input object
+        // back for a no-op move, and that object is rebuilt on every keystroke - so an
+        // identity check would both hide the no-op and trigger a render for it.
+        if (next.buffer !== current.buffer || next.cursor !== current.cursor)
+            setContent(next);
+        if (next.buffer !== draft.content)
+            props.onDraft({ content: next.buffer });
+    };
+    useInput((input, key) => {
+        if (props.isActive === false)
+            return;
+        // BEFORE EVERYTHING: a refused save and a dirty Esc are both two-step states, and
+        // the accelerator that resolves them must not be swallowed by the text handling
+        // below. `Ctrl+S` is the same precedent `SettingsScreen.tsx` set.
+        if (key.ctrl && (input === 's' || input === 'S')) {
+            props.onSave();
+            return;
+        }
+        if (key.escape) {
+            props.onEsc();
+            return;
+        }
+        if (key.tab) {
+            setFocus(nextField(focus, key.shift ? -1 : 1));
+            return;
+        }
+        const clean = stripPasteFrames(stripEnterFrames(input));
+        if (field === 'save') {
+            if (key.return)
+                props.onSave();
+            return;
+        }
+        if (field === 'cancel') {
+            if (key.return)
+                props.onCancel();
+            return;
+        }
+        if (field === 'content') {
+            if (key.upArrow) {
+                applyContent({ type: 'up', cols: fieldCols });
+                return;
+            }
+            if (key.downArrow) {
+                applyContent({ type: 'down', cols: fieldCols });
+                return;
+            }
+            if (key.return || clean.includes('\n')) {
+                applyContent({ type: 'newline' });
+                return;
+            }
+            const contentDeletion = deletionKind(input, key);
+            if (contentDeletion !== null) {
+                applyContent({ type: contentDeletion });
+                return;
+            }
+            if (key.leftArrow) {
+                applyContent({ type: 'left' });
+                return;
+            }
+            if (key.rightArrow) {
+                applyContent({ type: 'right' });
+                return;
+            }
+            if (key.ctrl || key.meta)
+                return;
+            if (clean.length > 0)
+                applyContent({ type: 'insert', text: clean });
+            return;
+        }
+        // Single-line fields: Enter advances rather than saving, because there is nothing
+        // for a newline to mean in a one-line field.
+        if (key.return) {
+            setFocus(nextField(focus, 1));
+            return;
+        }
+        if (key.upArrow) {
+            setFocus(nextField(focus, -1));
+            return;
+        }
+        if (key.downArrow) {
+            setFocus(nextField(focus, 1));
+            return;
+        }
+        if (key.ctrl || key.meta)
+            return;
+        editSingle(field, clean, key, deletionKind(input, key));
+    });
+    /** One text field, or an action row. The caret marks the focused one. */
+    const row = (name) => {
+        const focused = field === name;
+        const caret = focused ? glyphs.caret : ' ';
+        if (name === 'save' || name === 'cancel') {
+            const label = name === 'save' ? 'Save' : 'Cancel';
+            return (_jsx(Text, { wrap: "truncate", color: focused ? theme.accent : theme.muted, children: `${caret} [ ${label} ]` }, name));
+        }
+        const label = name === 'title' ? 'Title' : name === 'content' ? 'Body'
+            : name === 'description' ? 'Note' : 'Tags';
+        const value = draft[name];
+        if (name === 'content') {
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { wrap: "truncate", color: focused ? theme.accent : theme.muted, children: `${caret} ${label.padEnd(LABEL_CELLS)}` }), _jsx(Box, { flexDirection: "column", paddingLeft: 2, children: _jsx(PromptTextArea, { state: { ...content, buffer: draft.content }, cols: fieldCols, rows: bodyRows, focused: focused, theme: theme, caps: caps, ...(props.reducedMotion === undefined ? {} : { reducedMotion: props.reducedMotion }) }) })] }, name));
+        }
+        const shown = value.length === 0 ? '(empty)' : value;
+        return (_jsx(Text, { wrap: "truncate", color: focused ? theme.accent : theme.muted, children: `${caret} ${label.padEnd(LABEL_CELLS)}${shown}` }, name));
+    };
+    const title = state.error === null
+        ? (draft.id === null ? 'New prompt' : 'Edit prompt')
+        : promptErrorCopy(state.error);
+    const hint = state.escArmed
+        ? 'Esc again discards the draft | Tab next field'
+        : 'Tab next field | Enter next line | Ctrl+S save | Esc close';
+    return (_jsxs(OverlayFrame, { title: title, hint: hint, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: [_jsxs(Text, { wrap: "truncate", color: theme.muted, children: [_jsx(Text, { color: draft.favorite ? theme.toolDone : theme.muted, children: draft.favorite ? '[fav] ' : '      ' }), `${[...draft.content].length} chars`] }), _jsx(Box, { flexDirection: "column", children: PROMPT_EDITOR_FIELDS.map((name) => row(name)) })] }));
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The prompt manager: `Ctrl+P` (quick-prompt-library §4.4 / §6.4).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * A LIST PLUS A DETAIL BLOCK, the `KitPicker` idiom (F-17): three columns of prompt
+ * metadata never fit on a 72-column terminal, and the detail block is how this
+ * package already shows everything that does not fit in a row.
+ *
+ * THE OVERLAY OWNS NO DATA. Every mutation goes out through `onMutate`, and the new
+ * snapshot comes back through `library`. An overlay that patched its own copy would
+ * show a prompt the disk does not have (I-6), and the first time that happened the
+ * user would find out at the next launch.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { PromptLibrary, PromptLibraryIntent, PromptLibraryMutation, PromptMutationResult } from '../../model/prompts/types.js';
+export interface PromptLibraryOverlayProps {
+    isActive: boolean;
+    library: PromptLibrary;
+    /** D-21's one-shot hand-off; consumed at most once (I-8). */
+    intent?: PromptLibraryIntent;
+    cols: number;
+    maxRows: number;
+    scrollOffset: number;
+    onScrollClamp?: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    reducedMotion?: boolean;
+    /** The store, reached through `App` so this component stays a view. */
+    onMutate: (action: PromptLibraryMutation) => PromptMutationResult;
+    /** One-shot feedback (save, delete, write failure) for `App`'s toast channel. */
+    onNotice?: (level: 'info' | 'warn' | 'error', text: string) => void;
+    onClose: () => void;
+}
+export declare function PromptLibraryOverlay(props: PromptLibraryOverlayProps): React.ReactElement;

package/dist/ui/overlays/PromptLibraryOverlay.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The prompt manager: `Ctrl+P` (quick-prompt-library §4.4 / §6.4).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * A LIST PLUS A DETAIL BLOCK, the `KitPicker` idiom (F-17): three columns of prompt
+ * metadata never fit on a 72-column terminal, and the detail block is how this
+ * package already shows everything that does not fit in a row.
+ *
+ * THE OVERLAY OWNS NO DATA. Every mutation goes out through `onMutate`, and the new
+ * snapshot comes back through `library`. An overlay that patched its own copy would
+ * show a prompt the disk does not have (I-6), and the first time that happened the
+ * user would find out at the next launch.
+ */
+import { useEffect, useReducer, useRef } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { clipProfileText, useProfileScroll } from './ModelProfilePicker.js';
+import { promptDeletedCopy, promptErrorCopy, promptSavedCopy, PROMPT_EMPTY_BODY_COPY, PROMPT_EMPTY_TITLE_COPY } from '../../model/prompts/copy.js';
+import { INITIAL_PROMPT_LIBRARY_STATE, deleteDetail, finishPromptEditor, libraryDetail, libraryHint, libraryRows, promptLibraryReducer, } from './prompt-library-state.js';
+import { PromptEditorPage } from './PromptEditorPage.js';
+/** The reducer takes the library as a third argument, so it is bound per dispatch. */
+function reduce(state, dispatched) {
+    return promptLibraryReducer(state, dispatched.action, dispatched.library);
+}
+export function PromptLibraryOverlay(props) {
+    const { library, cols, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const [state, rawDispatch] = useReducer(reduce, INITIAL_PROMPT_LIBRARY_STATE);
+    const dispatch = (action) => rawDispatch({ action, library });
+    const rows = libraryRows(library);
+    const count = rows.length;
+    const cursor = count === 0 ? 0 : Math.min(state.index, count - 1);
+    const focused = rows[cursor];
+    const offset = useProfileScroll(props, cursor);
+    /**
+     * CONSUME THE INTENT EXACTLY ONCE (I-8).
+     *
+     * A `useRef`, not state: the ref is written before the dispatch is processed, so a
+     * StrictMode double-invoke of this effect sees `nonce <= consumed` and does nothing.
+     * State would be one render behind and would open the editor twice.
+     */
+    const consumed = useRef(0);
+    const intent = props.intent;
+    useEffect(() => {
+        if (!intent || intent.nonce <= consumed.current)
+            return;
+        consumed.current = intent.nonce;
+        dispatch({ type: 'init', entry: intent.entry, library, nonce: intent.nonce });
+    }, [intent]);
+    /** One mutation, its refusal routed to the same two channels every time. */
+    const mutate = (action) => {
+        const result = props.onMutate(action);
+        if (!result.ok)
+            props.onNotice?.('warn', promptErrorCopy(result.code));
+        return result;
+    };
+    const save = () => {
+        const verdict = finishPromptEditor(state.draft);
+        if (!verdict.ok) {
+            dispatch({ type: 'failed', code: verdict.code, field: verdict.field });
+            props.onNotice?.('warn', promptErrorCopy(verdict.code));
+            return;
+        }
+        const draft = state.draft;
+        const result = draft.id === null
+            ? mutate({ kind: 'create', draft })
+            : mutate({ kind: 'update', id: draft.id, draft });
+        if (!result.ok) {
+            // THE PAGE DOES NOT CLOSE AND THE DRAFT IS NOT TOUCHED (D-12): the editor is
+            // where the user has invested the most, so a refusal must cost nothing.
+            dispatch({ type: 'failed', code: result.code });
+            return;
+        }
+        dispatch({ type: 'commit', id: result.id ?? draft.id });
+        props.onNotice?.('info', promptSavedCopy(draft.title.trim()));
+    };
+    const confirmDelete = () => {
+        const id = state.pendingDeleteId;
+        if (!id) {
+            dispatch({ type: 'cancelled' });
+            return;
+        }
+        const title = library.prompts.find((prompt) => prompt.id === id)?.title ?? '';
+        const result = mutate({ kind: 'delete', id });
+        dispatch({ type: 'cancelled' });
+        // `promptDeletedCopy`, not `promptSavedCopy`: the two sentences are one word apart
+        // and the wrong one tells the user their prompt still exists.
+        if (result.ok)
+            props.onNotice?.('info', promptDeletedCopy(title));
+    };
+    useInput((input, key) => {
+        if (props.isActive === false)
+            return;
+        // THE EDITOR PAGE OWNS EVERY KEY WHILE IT IS OPEN, Esc INCLUDED. Two `useInput`
+        // hooks are live at once (this one and the page's), so handling Esc in both would
+        // dispatch `esc` TWICE for one keypress: the first arms the discard and the second
+        // executes it, which silently throws away a drafted body on a single Esc. The page
+        // already reports Esc through `onEsc`, so this branch must stay silent.
+        if (state.page === 'editor')
+            return;
+        if (state.page === 'delete') {
+            if (key.escape || input === 'n' || input === 'N') {
+                dispatch({ type: 'cancelled' });
+                return;
+            }
+            if (key.return || input === 'y' || input === 'Y')
+                confirmDelete();
+            return;
+        }
+        // --- list page ---------------------------------------------------------
+        if (key.escape) {
+            props.onClose();
+            return;
+        }
+        // THE RAW SEQUENCE **AND** THE PARSED CHORD (D-23, corrected by measurement).
+        // Ink 5's `parse-keypress` recognises `\x1b[1;5A`, reports it as
+        // `ctrl + upArrow`, and hands the component an EMPTY `input` - so the sequence
+        // comparison alone would be a dead branch on this runtime, and the chord
+        // comparison alone would miss a host that passes the raw bytes through. Either
+        // shape reorders; `\x1b[A` (modifier lost) matches neither and only moves focus.
+        const reorderUp = input === '\x1b[1;5A' || (key.ctrl && key.upArrow);
+        const reorderDown = input === '\x1b[1;5B' || (key.ctrl && key.downArrow);
+        if (reorderUp || reorderDown) {
+            if (!focused)
+                return;
+            const result = mutate({ kind: 'move', id: focused.id, delta: reorderUp ? -1 : 1 });
+            if (result.ok)
+                dispatch({ type: 'list', focusId: focused.id });
+            return;
+        }
+        if (key.upArrow || (key.tab && key.shift)) {
+            dispatch({ type: 'focus', index: count === 0 ? 0 : (cursor - 1 + count) % count });
+            return;
+        }
+        if (key.downArrow) {
+            dispatch({ type: 'focus', index: count === 0 ? 0 : (cursor + 1) % count });
+            return;
+        }
+        if (key.return) {
+            if (focused)
+                dispatch({ type: 'edit', id: focused.id, library });
+            return;
+        }
+        if (key.ctrl || key.meta)
+            return;
+        if (input === 'a') {
+            dispatch({ type: 'create' });
+            return;
+        }
+        if (input === 'd' && focused) {
+            dispatch({ type: 'delete', id: focused.id });
+            return;
+        }
+        if (input === 'f' && focused) {
+            const prompt = library.prompts.find((entry) => entry.id === focused.id);
+            mutate({ kind: 'favorite', id: focused.id, favorite: prompt?.favorite !== true });
+            dispatch({ type: 'list', focusId: focused.id });
+        }
+    });
+    if (state.page === 'editor') {
+        return (_jsx(PromptEditorPage, { isActive: props.isActive, state: state, cols: cols, maxRows: props.maxRows, theme: theme, caps: caps, ...(props.reducedMotion === undefined ? {} : { reducedMotion: props.reducedMotion }), onDraft: (patch) => dispatch({ type: 'draft', patch }), onSave: save, onEsc: () => dispatch({ type: 'esc' }), onCancel: () => dispatch({ type: 'cancelled' }) }));
+    }
+    const body = [];
+    if (state.page === 'delete') {
+        for (const [at, line] of deleteDetail(library, state.pendingDeleteId).entries()) {
+            body.push(_jsx(Text, { wrap: "truncate", color: at === 0 ? theme.accent : theme.muted, children: clipProfileText(line, cols - 8) }, `del-${at}`));
+        }
+        return (_jsx(OverlayFrame, { title: "Delete prompt", hint: libraryHint(state, count), rows: body, scrollOffset: 0, maxRows: props.maxRows, cols: cols, theme: theme, caps: caps }));
+    }
+    for (const [at, row] of rows.entries()) {
+        const isCursor = at === cursor;
+        body.push(_jsx(Text, { wrap: "truncate", color: isCursor ? theme.accent : theme.muted, children: `${isCursor ? glyphs.caret : ' '} ${clipProfileText(row.label, cols - 8)}` }, row.id));
+    }
+    if (count === 0) {
+        // TWO ROWS, NOT AN EMPTY SCREEN (§9.7): an empty list that says nothing reads as a
+        // broken panel, and the key that fixes it (`a`) is not otherwise discoverable. The
+        // sentences come from `prompts/copy.ts` so this state and the picker's own empty
+        // state cannot drift into two wordings of the same advice.
+        body.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: clipProfileText(PROMPT_EMPTY_TITLE_COPY, cols - 8) }, "empty-title"));
+        body.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: clipProfileText(PROMPT_EMPTY_BODY_COPY, cols - 8) }, "empty-body"));
+    }
+    // THE DETAIL BLOCK DESCRIBES THE FOCUSED ROW ONLY, and it is last so a narrow
+    // terminal clips the description rather than the list.
+    for (const [at, line] of libraryDetail(focused, library, cols).entries()) {
+        body.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: clipProfileText(`  ${line}`, cols - 8) }, `detail-${at}`));
+    }
+    return (_jsx(OverlayFrame, { title: `Prompts${count > 0 ? ` (${count})` : ''}`, hint: libraryHint(state, count), rows: body, scrollOffset: offset, onScrollClamp: props.onScrollClamp, maxRows: props.maxRows, cols: cols, theme: theme, caps: caps }));
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The prompt picker: `/prompts` (quick-prompt-library §4.5).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE QUERY BOX IS THE LIST. There is no separate search field and no `/` mode: the
+ * picker exists for one keystroke-to-answer gesture, and an extra mode to enter is an
+ * extra thing that can be wrong about which component owns the next key.
+ *
+ * `Ctrl+Enter` IS RECOGNISED BY ITS BYTES, NOT BY `key.ctrl && key.return`. The stdin
+ * filter normalises every modified Enter (`\x1b[13;5u`, the win32 record, `\x1b[13;2u`)
+ * into `ENTER_NEWLINE_FRAME` before Ink sees it (enter-sequences.ts), so the parsed
+ * chord never occurs - a branch written that way is dead code that LOOKS implemented
+ * (R-11). On a terminal without keyboard enhancement the chord degrades to a plain
+ * `Enter`, which fills without sending; the footer therefore names `Enter fill` first.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { PromptLibrary, PromptLibraryEntry } from '../../model/prompts/types.js';
+export interface PromptPickerProps {
+    isActive: boolean;
+    library: PromptLibrary;
+    cols: number;
+    maxRows: number;
+    scrollOffset: number;
+    onScrollClamp?: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    /** `submit` is true only for `Ctrl+Enter` (see `SUBMIT_FRAMES`). */
+    onFill: (id: string, submit: boolean) => void;
+    /** `Tab` / `a`: hand over to the manager without leaving the overlay stack. */
+    onManage: (entry: PromptLibraryEntry) => void;
+    onClose: () => void;
+}
+export declare function PromptPicker(props: PromptPickerProps): React.ReactElement;

package/dist/ui/overlays/PromptPicker.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The prompt picker: `/prompts` (quick-prompt-library §4.5).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE QUERY BOX IS THE LIST. There is no separate search field and no `/` mode: the
+ * picker exists for one keystroke-to-answer gesture, and an extra mode to enter is an
+ * extra thing that can be wrong about which component owns the next key.
+ *
+ * `Ctrl+Enter` IS RECOGNISED BY ITS BYTES, NOT BY `key.ctrl && key.return`. The stdin
+ * filter normalises every modified Enter (`\x1b[13;5u`, the win32 record, `\x1b[13;2u`)
+ * into `ENTER_NEWLINE_FRAME` before Ink sees it (enter-sequences.ts), so the parsed
+ * chord never occurs - a branch written that way is dead code that LOOKS implemented
+ * (R-11). On a terminal without keyboard enhancement the chord degrades to a plain
+ * `Enter`, which fills without sending; the footer therefore names `Enter fill` first.
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { ENTER_NEWLINE_FRAME } from '../../input/limits.js';
+import { PROMPT_PICKER_LIMITS } from '../../model/prompts/limits.js';
+import { nextView } from '../../model/prompts/search.js';
+import { stripPasteFrames } from '../paste-frames.js';
+import { stripEnterFrames } from '../enter-frames.js';
+import { clipProfileText, useProfileScroll } from './ModelProfilePicker.js';
+import { pickerDetail, pickerDigitTarget, pickerHint, pickerRows, } from './prompt-picker-state.js';
+/** Every modified Enter the stdin filter folds into its frame, plus the raw CSI-u. */
+const SUBMIT_FRAMES = [ENTER_NEWLINE_FRAME, '\x1b[13;5u'];
+export function PromptPicker(props) {
+    const { library, cols, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const [query, setQuery] = useState('');
+    const [view, setView] = useState('manual');
+    // THE FOCUS IS AN ID, NOT AN INDEX (D-9's cost, paid here): both filtering and
+    // `Ctrl+S` can reorder the list under the cursor, and an index would silently point
+    // at a different prompt after either.
+    const [focusId, setFocusId] = useState(null);
+    const rows = pickerRows({ library, query, view });
+    const found = rows.findIndex((row) => row.id === focusId);
+    const cursor = rows.length === 0 ? 0 : Math.max(0, Math.min(found, rows.length - 1));
+    const focused = rows[cursor];
+    const offset = useProfileScroll(props, cursor);
+    const empty = library.prompts.length === 0;
+    const fill = (id, submit) => {
+        if (!id)
+            return;
+        props.onFill(id, submit);
+    };
+    useInput((input, key) => {
+        if (props.isActive === false)
+            return;
+        if (key.escape) {
+            props.onClose();
+            return;
+        }
+        // BEFORE `key.return`: the frame arrives with `return` false, so this branch must
+        // not be reachable only through the plain-Enter path.
+        if (SUBMIT_FRAMES.includes(input)) {
+            fill(focused?.id, true);
+            return;
+        }
+        if (key.return) {
+            fill(focused?.id, false);
+            return;
+        }
+        if (key.ctrl && (input === 's' || input === 'S')) {
+            setView(nextView(view));
+            return;
+        }
+        if (key.upArrow) {
+            if (rows.length === 0)
+                return;
+            setFocusId(rows[(cursor - 1 + rows.length) % rows.length].id);
+            return;
+        }
+        if (key.downArrow) {
+            if (rows.length === 0)
+                return;
+            setFocusId(rows[(cursor + 1) % rows.length].id);
+            return;
+        }
+        if (key.tab) {
+            // ONE OVERLAY STACK, NOT TWO (AC-23): the picker hands the manager an intent and
+            // closes, and an empty library lands straight in the editor because there is
+            // nothing for a list page to show.
+            props.onManage(empty ? { kind: 'create' } : { kind: 'list' });
+            return;
+        }
+        if (key.backspace || key.delete) {
+            setQuery((value) => [...value].slice(0, -1).join(''));
+            return;
+        }
+        if (key.ctrl || key.meta)
+            return;
+        const clean = stripPasteFrames(stripEnterFrames(input));
+        if (clean.length === 0)
+            return;
+        if (query.length === 0) {
+            // `1`-`9` PICK A ROW (AC-21). Only while the query is empty: otherwise the digit
+            // is the first character of what the user is searching for.
+            if (input === 'a' && empty) {
+                props.onManage({ kind: 'create' });
+                return;
+            }
+            const target = pickerDigitTarget(rows, input);
+            if (target !== null) {
+                fill(target, false);
+                return;
+            }
+        }
+        setQuery((value) => (value + clean).slice(0, PROMPT_PICKER_LIMITS.queryMaxChars));
+        setFocusId(null);
+    });
+    const body = [
+        _jsx(Text, { wrap: "truncate", color: theme.primary, children: `${glyphs.caret} ${query.length > 0 ? query : '(type to filter)'}` }, "query"),
+    ];
+    for (const [at, row] of rows.entries()) {
+        const isCursor = at === cursor;
+        const marks = `${row.favorite ? ' [fav]' : ''}${row.tags.length > 0 ? ` #${row.tags[0]}` : ''}`;
+        body.push(_jsx(Text, { wrap: "truncate", color: isCursor ? theme.accent : theme.muted, children: `${isCursor ? glyphs.caret : ' '} ${row.index}. `
+                + clipProfileText(`${row.title}${marks}`, cols - 12) }, row.id));
+    }
+    for (const [at, line] of pickerDetail(focused, library).entries()) {
+        body.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: clipProfileText(`  ${line}`, cols - 8) }, `detail-${at}`));
+    }
+    return (_jsx(OverlayFrame, { title: `Pick a prompt (${rows.length}/${library.prompts.length})`, hint: pickerHint({ count: rows.length, query, view }), rows: body, scrollOffset: offset, onScrollClamp: props.onScrollClamp, maxRows: props.maxRows, cols: cols, theme: theme, caps: caps }));
+}