klyro 0.1.50 → 0.1.51

package/dist/tui/app.d.ts

@@ -7,6 +7,7 @@ import type { StatusSnapshot } from './status.js';
 import type { TranscriptItem } from './transcript.js';
 import { TuiApprovalBridge } from './approval.js';
 import type { PlanStep } from '../agent/runtime.js';
+import { type TranscriptScrollHandle } from './transcript-commands.js';
 export interface AppProps {
     initialModel: string;
     maxSteps: number;
@@ -26,6 +27,7 @@ export interface AppProps {
         scrollToBottom: () => void;
         scrollHalfPage: (dir: -1 | 1) => void;
         scrollToTop: () => void;
+        transcript: TranscriptScrollHandle;
     }) => void;
     version?: string;
     isFullscreen?: boolean;

package/dist/tui/app.js

@@ -12,6 +12,7 @@ import { tokens, g } from './tokens.js';
 import { initialScroll, scrollReducer, resolveTopRow, maxTopFor, } from './scroll-model.js';
 import { buildIndex, itemAtRow, MeasureCache } from './measure.js';
 import { renderMarkdownLines } from './markdown.js';
+import { getTranscriptCommand, } from './transcript-commands.js';
 let _id = 0;
 function nextId(p) { _id++; return `${p}-${_id}`; }
 function Header({ cwd, model, version, width }) {
@@ -184,13 +185,21 @@ export function App(props) {
         if (status.status !== 'running')
             ctrlCArmed.current = false;
     }, [status.status]);
-    // design.md §13: submit snaps to bottom — immediate + microtask + timeout
-    // so React/Ink layout settles before the final pin.
-    const snapToBottomSettled = useCallback(() => {
-        scrollCmdsRef.current.bottom();
-        queueMicrotask(() => scrollCmdsRef.current.bottom());
-        setTimeout(() => scrollCmdsRef.current.bottom(), 0);
-    }, []);
+    // scroll.md §7: submit bumps a version key; the settle effect below pins
+    // to bottom immediate + microtask + timeout so layout settles first.
+    // (Decoupled from render: never scroll directly inside the submit handler.)
+    const [submitKey, setSubmitKey] = useState(0);
+    useEffect(() => {
+        if (!submitKey)
+            return;
+        const toBottom = () => {
+            scrollCmdsRef.current.bottom();
+        };
+        toBottom();
+        queueMicrotask(toBottom);
+        const t = setTimeout(toBottom, 0);
+        return () => clearTimeout(t);
+    }, [submitKey]);
     // Shift+Enter intent: explicit shift+return, kitty/CSI-u sequence, legacy
     // ESC+CR pair, or Esc immediately followed by Return (75ms, non-empty input).
     const escReturnAt = useRef(0);
@@ -383,9 +392,28 @@ export function App(props) {
     const scrollToBottom = useCallback(() => { scrollCmdsRef.current.bottom(); }, []);
     const scrollHalfPage = useCallback((dir) => { scrollCmdsRef.current.halfPage(dir); }, []);
     const scrollToTop = useCallback(() => { scrollCmdsRef.current.top(); }, []);
+    // scroll.md §2/§10: the four-command TranscriptScrollHandle.
+    const transcriptHandle = useMemo(() => ({
+        runTranscriptCommand: (command) => {
+            switch (command) {
+                case 'messages_half_page_up':
+                    scrollCmdsRef.current.halfPage(-1);
+                    return;
+                case 'messages_half_page_down':
+                    scrollCmdsRef.current.halfPage(1);
+                    return;
+                case 'messages_first':
+                    scrollCmdsRef.current.top();
+                    return;
+                case 'messages_last':
+                    scrollCmdsRef.current.bottom();
+                    return;
+            }
+        },
+    }), []);
     const onMountedRef = useRef(props.onMounted);
     useEffect(() => { onMountedRef.current = props.onMounted; }, [props.onMounted]);
-    useEffect(() => { onMountedRef.current?.({ append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom, scrollHalfPage, scrollToTop }); globalThis.__klyroAppAppend = append; globalThis.__klyroAppendDelta = appendDelta; globalThis.__klyroAppStatus = updateStatus; globalThis.__klyroAppPlan = updatePlan; return () => { delete globalThis.__klyroAppAppend; delete globalThis.__klyroAppendDelta; delete globalThis.__klyroAppStatus; delete globalThis.__klyroAppPlan; }; }, [append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom, scrollHalfPage, scrollToTop]);
+    useEffect(() => { onMountedRef.current?.({ append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom, scrollHalfPage, scrollToTop, transcript: transcriptHandle }); globalThis.__klyroAppAppend = append; globalThis.__klyroAppendDelta = appendDelta; globalThis.__klyroAppStatus = updateStatus; globalThis.__klyroAppPlan = updatePlan; return () => { delete globalThis.__klyroAppAppend; delete globalThis.__klyroAppendDelta; delete globalThis.__klyroAppStatus; delete globalThis.__klyroAppPlan; }; }, [append, appendDelta, updateStatus, updatePlan, clearTranscript, scrollLines, scrollToBottom, scrollHalfPage, scrollToTop, transcriptHandle]);
     const toggleGroup = (id) => setExpandedGroups((prev) => { const n = new Set(prev); if (n.has(id))
         n.delete(id);
     else
@@ -406,26 +434,32 @@ export function App(props) {
             return;
         }
         // Scroll keys (work in any mode, including while running).
+        // scroll.md §6 flow: Keyboard → getTranscriptCommand → handle.
         // design.md §11: PageUp/Ctrl+U half-up, PageDown/Ctrl+D half-down,
-        // Ctrl+Home/Ctrl+End first/last. (Ctrl+B/F kept as pager aliases.)
+        // Ctrl+Home/Ctrl+End first/last. (Plain Home/End + Ctrl+B/F/G kept.)
         if (isFullscreen && maxTop > 0) {
+            const tcmd = getTranscriptCommand(inputStr, key);
+            if (tcmd) {
+                transcriptHandle.runTranscriptCommand(tcmd);
+                return;
+            }
             if (key.home) {
                 commands.jumpTop();
                 return;
-            } // Home / Ctrl+Home → first
+            }
             if (key.end) {
                 commands.jumpBottom();
                 return;
-            } // End / Ctrl+End → last
+            }
             if (key.ctrl && inputStr === 'g') {
                 commands.jumpBottom();
                 return;
             } // Ctrl+G → bottom
-            if (key.pageUp || (key.ctrl && inputStr === 'u') || (key.ctrl && inputStr === 'b')) {
+            if ((key.ctrl && inputStr === 'b')) {
                 commands.pageUp();
                 return;
             }
-            if (key.pageDown || (key.ctrl && inputStr === 'd') || (key.ctrl && inputStr === 'f')) {
+            if ((key.ctrl && inputStr === 'f')) {
                 commands.pageDown();
                 return;
             }
@@ -490,7 +524,7 @@ export function App(props) {
                 setQueuedInputs((prev) => [...prev, v]);
                 setInput('');
                 pushHistory(v);
-                snapToBottomSettled();
+                setSubmitKey((k) => k + 1);
                 return;
             }
             if (key.backspace || key.delete) {
@@ -555,7 +589,7 @@ export function App(props) {
             pushHistory(v);
             setTranscript((prev) => [...prev, { id: nextId('user'), kind: 'text', text: v, role: 'user' }]);
             streamingIdRef.current = null;
-            snapToBottomSettled();
+            setSubmitKey((k) => k + 1);
             const cmd = parseSlash(v);
             if (cmd.kind === 'prompt')
                 void props.onPrompt(cmd.text);
@@ -654,5 +688,5 @@ export function App(props) {
                                 if (it.kind === 'diff')
                                     return (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, marginBottom: 1, children: [_jsx(Text, { bold: true, color: tokens.colors.soft, children: it.summary ?? 'Diff' }), it.hunks.map((h, i) => (_jsxs(Box, { flexDirection: "column", marginTop: 0, children: [_jsx(Text, { color: tokens.colors.soft, children: h.path }), h.lines.map((l, j) => (_jsxs(Text, { wrap: "wrap", color: l.kind === 'add' ? tokens.colors.ok : l.kind === 'remove' ? tokens.colors.err : tokens.colors.dim, children: [l.kind === 'add' ? '+ ' : l.kind === 'remove' ? '- ' : '  ', l.text] }, j)))] }, i)))] }, it.id));
                                 return null;
-                            }) : null, showThinking && status.status === 'running' && !streamingIdRef.current ? (_jsxs(Box, { paddingLeft: 2, marginBottom: 1, children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsx(Text, { color: tokens.colors.dim, children: "Thinking..." }), _jsxs(Text, { color: tokens.colors.dim, children: ["  ", (elapsed / 1000).toFixed(1), "s"] })] })) : null, showPlan && plan.length > 0 ? (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, marginTop: 0, marginBottom: 1, children: [_jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsxs(Text, { bold: true, children: [g('todoPlan'), " Plan  ", plan.filter((p) => p.status === 'done').length, "/", plan.length] })] }), plan.slice(0, 8).map((p, i) => (_jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsxs(Text, { color: p.status === 'done' ? tokens.colors.ok : p.status === 'in_progress' ? tokens.colors.accent : tokens.colors.dim, children: [p.status === 'done' ? g('todoDone') : p.status === 'in_progress' ? g('todoActive') : g('todoPending'), " ", i + 1, ". ", p.title] })] }, p.id)))] })) : null, showQueued && queuedInputs.length > 0 ? (_jsx(Box, { flexDirection: "column", paddingLeft: 2, marginBottom: 1, children: queuedInputs.map((q, i) => (_jsxs(Text, { color: tokens.colors.dim, children: ["queued: ", q.slice(0, 60), i === 0 ? '  esc to drop' : ''] }, i))) })) : null] }), isFullscreen ? (_jsx(Box, { flexDirection: "column", width: 1, marginLeft: 1, children: Array.from({ length: trackH }).map((_, i) => (_jsx(Text, { color: i === thumbPos ? tokens.colors.accent : tokens.colors.guide, children: i === thumbPos ? '●' : '│' }, i))) })) : null] }), pinned && pendingNew > 0 ? (_jsx(Box, { justifyContent: "flex-end", paddingX: 1, marginTop: -1, children: _jsxs(Text, { backgroundColor: tokens.colors.accentSoft, color: tokens.colors.accent, bold: true, children: [' ↓ ', pendingNew >= 1000 ? '999+ new' : `${pendingNew} new`, ' '] }) })) : null, slashSuggest.length > 0 ? (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [slashSuggest.map((s, i) => (_jsxs(Text, { color: i === 0 ? tokens.colors.accent : tokens.colors.dim, children: [i === 0 ? '▸' : ' ', " /", s.name, "  \u2014 ", s.hint] }, s.name))), _jsx(Text, { color: tokens.colors.dim, children: "  tab to complete" })] })) : null, _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tokens.colors.guide, children: g('rule').repeat(Math.max(10, width - 2)) }), _jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.accent, bold: true, children: [g('prompt'), " "] }), _jsxs(Text, { wrap: "wrap", children: [input || _jsx(Text, { color: tokens.colors.dim, children: "Message Klyro..." }), "|"] })] }), _jsx(Text, { color: tokens.colors.guide, children: g('rule').repeat(Math.max(10, width - 2)) })] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: tokens.colors.dim, children: [baseHints, maxTop > 0 && isFullscreen ? '  ·  PgUp/Dn scroll' : ''] }), _jsxs(Text, { color: tokens.colors.dim, children: [cost > 0 ? `$${cost.toFixed(2)} · ` : '', ctxPct, "% ctx \u00B7 ", status.model, status.status === 'running' ? ' ●' : ''] })] })] }));
+                            }) : null, showThinking && status.status === 'running' && !streamingIdRef.current ? (_jsxs(Box, { paddingLeft: 2, marginBottom: 1, children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsx(Text, { color: tokens.colors.dim, children: "Thinking... (esc to cancel)" }), _jsxs(Text, { color: tokens.colors.dim, children: ["  ", (elapsed / 1000).toFixed(1), "s"] })] })) : null, showPlan && plan.length > 0 ? (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, marginTop: 0, marginBottom: 1, children: [_jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsxs(Text, { bold: true, children: [g('todoPlan'), " Plan  ", plan.filter((p) => p.status === 'done').length, "/", plan.length] })] }), plan.slice(0, 8).map((p, i) => (_jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.guide, children: ["  ", g('guide'), "   "] }), _jsxs(Text, { color: p.status === 'done' ? tokens.colors.ok : p.status === 'in_progress' ? tokens.colors.accent : tokens.colors.dim, children: [p.status === 'done' ? g('todoDone') : p.status === 'in_progress' ? g('todoActive') : g('todoPending'), " ", i + 1, ". ", p.title] })] }, p.id)))] })) : null, showQueued && queuedInputs.length > 0 ? (_jsx(Box, { flexDirection: "column", paddingLeft: 2, marginBottom: 1, children: queuedInputs.map((q, i) => (_jsxs(Text, { color: tokens.colors.dim, children: ["queued: ", q.slice(0, 60), i === 0 ? '  esc to drop' : ''] }, i))) })) : null] }), isFullscreen ? (_jsx(Box, { flexDirection: "column", width: 1, marginLeft: 1, children: Array.from({ length: trackH }).map((_, i) => (_jsx(Text, { color: i === thumbPos ? tokens.colors.accent : tokens.colors.guide, children: i === thumbPos ? '●' : '│' }, i))) })) : null] }), pinned && pendingNew > 0 ? (_jsx(Box, { justifyContent: "flex-end", paddingX: 1, marginTop: -1, children: _jsxs(Text, { backgroundColor: tokens.colors.accentSoft, color: tokens.colors.accent, bold: true, children: [' ↓ ', pendingNew >= 1000 ? '999+ new' : `${pendingNew} new`, ' '] }) })) : null, slashSuggest.length > 0 ? (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [slashSuggest.map((s, i) => (_jsxs(Text, { color: i === 0 ? tokens.colors.accent : tokens.colors.dim, children: [i === 0 ? '▸' : ' ', " /", s.name, "  \u2014 ", s.hint] }, s.name))), _jsx(Text, { color: tokens.colors.dim, children: "  tab to complete" })] })) : null, _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tokens.colors.guide, children: g('rule').repeat(Math.max(10, width - 2)) }), _jsxs(Box, { children: [_jsxs(Text, { color: tokens.colors.accent, bold: true, children: [g('prompt'), " "] }), _jsxs(Text, { wrap: "wrap", children: [input || _jsx(Text, { color: tokens.colors.dim, children: "Message Klyro..." }), "|"] })] }), _jsx(Text, { color: tokens.colors.guide, children: g('rule').repeat(Math.max(10, width - 2)) })] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { color: tokens.colors.dim, children: [baseHints, maxTop > 0 && isFullscreen ? '  ·  PgUp/Dn scroll' : ''] }), _jsxs(Text, { color: tokens.colors.dim, children: [cost > 0 ? `$${cost.toFixed(2)} · ` : '', ctxPct, "% ctx \u00B7 ", status.model, status.status === 'running' ? ' ●' : ''] })] })] }));
 }

package/dist/tui/app.test.js

@@ -319,6 +319,43 @@ describe('App', () => {
         await new Promise((r) => setTimeout(r, 50));
         expect(onPrompt).toHaveBeenCalledWith('line one\nline two');
     });
+    it('submitting while pinned snaps back to bottom (scroll.md §7)', async () => {
+        const onPrompt = vi.fn(async () => { });
+        const { stdin, lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: onPrompt, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25) }));
+        await new Promise((r) => setTimeout(r, 100));
+        stdin.write(KEY_HOME);
+        await new Promise((r) => setTimeout(r, 50));
+        expect(lastFrame() ?? '').toMatch(/MSG-00-tag/);
+        stdin.write('hello again');
+        await new Promise((r) => setTimeout(r, 20));
+        stdin.write('\x0d');
+        // Settle effect: immediate + microtask + timeout(0) bottom pin.
+        await new Promise((r) => setTimeout(r, 150));
+        expect(onPrompt).toHaveBeenCalledWith('hello again');
+        expect(lastFrame() ?? '').toMatch(/MSG-24-tag/);
+    });
+    it('onMounted transcript handle runs the four commands (scroll.md §2)', async () => {
+        let handle = null;
+        const { lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25), onMounted: (h) => {
+                handle = h.transcript;
+            } }));
+        await new Promise((r) => setTimeout(r, 50));
+        expect(handle).not.toBeNull();
+        handle.runTranscriptCommand('messages_half_page_up');
+        await new Promise((r) => setTimeout(r, 50));
+        let frame = lastFrame() ?? '';
+        // Half page (10 lines) up from bottom (row 30 → 20): MSG-24 gone, MSG-14 in view.
+        expect(frame).not.toMatch(/MSG-24-tag/);
+        expect(frame).toMatch(/MSG-14-tag/);
+        handle.runTranscriptCommand('messages_first');
+        await new Promise((r) => setTimeout(r, 50));
+        frame = lastFrame() ?? '';
+        expect(frame).toMatch(/MSG-00-tag/);
+        expect(frame).not.toMatch(/MSG-24-tag/);
+        handle.runTranscriptCommand('messages_last');
+        await new Promise((r) => setTimeout(r, 50));
+        expect(lastFrame() ?? '').toMatch(/MSG-24-tag/);
+    });
     it('Shift+Up / Shift+Down scroll by one line', async () => {
         const { stdin, lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25) }));
         await new Promise((r) => setTimeout(r, 50));

package/dist/tui/transcript-commands.d.ts

@@ -0,0 +1,34 @@
+/**
+ * scroll.md §§2/4/5/6 — TranscriptCommand abstraction.
+ *
+ * Only four scroll commands exist (Cline parity):
+ *   messages_half_page_up / messages_half_page_down /
+ *   messages_first / messages_last
+ *
+ * Flow (§6): Keyboard → getTranscriptCommand() → TranscriptScrollHandle →
+ * ChatMessageList. Keys are matched in ONE place (the §5 binding table);
+ * the App routes everything else (history, autocomplete, approvals).
+ *
+ * Note on the stack: the doc's `<scrollbox stickyScroll>` is OpenTUI-only
+ * and this app renders with Ink, which has no scrollbox primitive — so the
+ * handle drives the measured anchor viewport (tui/scroll-model.ts) instead.
+ * The command vocabulary and all §21 behaviors are identical.
+ */
+export type TranscriptCommand = 'messages_half_page_up' | 'messages_half_page_down' | 'messages_first' | 'messages_last';
+export interface TranscriptScrollHandle {
+    runTranscriptCommand(command: TranscriptCommand): void;
+}
+/** Minimal Ink key shape needed for the binding table. */
+export interface TranscriptKey {
+    pageUp?: boolean;
+    pageDown?: boolean;
+    home?: boolean;
+    end?: boolean;
+    ctrl?: boolean;
+}
+/**
+ * scroll.md §5 binding table (pure — unit-tested):
+ *   PageUp / Ctrl+U → up · PageDown / Ctrl+D → down ·
+ *   Ctrl+Home → first · Ctrl+End → last · anything else → undefined.
+ */
+export declare function getTranscriptCommand(input: string, key: TranscriptKey): TranscriptCommand | undefined;

package/dist/tui/transcript-commands.js

@@ -0,0 +1,32 @@
+/**
+ * scroll.md §§2/4/5/6 — TranscriptCommand abstraction.
+ *
+ * Only four scroll commands exist (Cline parity):
+ *   messages_half_page_up / messages_half_page_down /
+ *   messages_first / messages_last
+ *
+ * Flow (§6): Keyboard → getTranscriptCommand() → TranscriptScrollHandle →
+ * ChatMessageList. Keys are matched in ONE place (the §5 binding table);
+ * the App routes everything else (history, autocomplete, approvals).
+ *
+ * Note on the stack: the doc's `<scrollbox stickyScroll>` is OpenTUI-only
+ * and this app renders with Ink, which has no scrollbox primitive — so the
+ * handle drives the measured anchor viewport (tui/scroll-model.ts) instead.
+ * The command vocabulary and all §21 behaviors are identical.
+ */
+/**
+ * scroll.md §5 binding table (pure — unit-tested):
+ *   PageUp / Ctrl+U → up · PageDown / Ctrl+D → down ·
+ *   Ctrl+Home → first · Ctrl+End → last · anything else → undefined.
+ */
+export function getTranscriptCommand(input, key) {
+    if (key.pageUp || (key.ctrl && input === 'u'))
+        return 'messages_half_page_up';
+    if (key.pageDown || (key.ctrl && input === 'd'))
+        return 'messages_half_page_down';
+    if (key.home && key.ctrl)
+        return 'messages_first';
+    if (key.end && key.ctrl)
+        return 'messages_last';
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klyro",
-  "version": "0.1.50",
+  "version": "0.1.51",
   "description": "Klyro \u2014 autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
   "type": "module",
   "main": "dist/index.js",