klyro 0.1.45 → 0.1.47

package/dist/tui/app.test.js

@@ -201,6 +201,73 @@ describe('App', () => {
         const frame = lastFrame() ?? '';
         expect(frame).toMatch(/LATE-1-tag/);
     });
+    it('↑ recalls the previous prompt (input history, §8.3)', async () => {
+        const onPrompt = vi.fn(async () => { });
+        const { stdin, lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: onPrompt, onSlash: async () => { } }));
+        stdin.write('first recallable prompt');
+        await new Promise((r) => setTimeout(r, 20));
+        stdin.write('\x0d');
+        await new Promise((r) => setTimeout(r, 50));
+        expect(onPrompt).toHaveBeenCalledWith('first recallable prompt');
+        // Input cleared after submit; ↑ should restore it from history.
+        stdin.write('\x1b[A');
+        await new Promise((r) => setTimeout(r, 30));
+        expect(lastFrame() ?? '').toContain('first recallable prompt');
+    });
+    it('↑ on empty input scrolls one line instead of history', 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));
+        stdin.write(KEY_HOME);
+        await new Promise((r) => setTimeout(r, 30));
+        // Empty input + plain ↑ → line up (stays near top, MSG-00 visible).
+        stdin.write('\x1b[A');
+        await new Promise((r) => setTimeout(r, 30));
+        expect(lastFrame() ?? '').toMatch(/MSG-00-tag/);
+    });
+    it('/c shows top-6 suggestions and Tab completes', async () => {
+        const { stdin, lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { } }));
+        stdin.write('/c');
+        await new Promise((r) => setTimeout(r, 30));
+        const withSuggest = lastFrame() ?? '';
+        expect(withSuggest).toMatch(/\/clear/);
+        expect(withSuggest).toMatch(/tab to complete/i);
+        stdin.write('\t');
+        await new Promise((r) => setTimeout(r, 30));
+        expect(lastFrame() ?? '').toContain('/clear ');
+    });
+    it('Enter on empty input while pinned jumps back to bottom (§7.2)', 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, 100));
+        stdin.write(KEY_HOME);
+        await new Promise((r) => setTimeout(r, 100));
+        const g = globalThis;
+        g.__klyroAppAppend({ id: 'late-1', kind: 'text', text: 'LATE-1-tag', role: 'assistant' });
+        await new Promise((r) => setTimeout(r, 200));
+        expect(lastFrame() ?? '').not.toMatch(/LATE-1-tag/);
+        // Empty input + Enter → dismiss badge, follow tail.
+        stdin.write('\x0d');
+        await new Promise((r) => setTimeout(r, 100));
+        expect(lastFrame() ?? '').toMatch(/LATE-1-tag/);
+    });
+    it('onMounted scrollLines/scrollToBottom drive the viewport (wheel path)', async () => {
+        let captured = null;
+        const { lastFrame } = render(_jsx(App, { initialModel: "m", maxSteps: 10, cwd: "/test", onPrompt: async () => { }, onSlash: async () => { }, isFullscreen: true, initialTranscript: makeInitialTranscript(25), onMounted: (h) => {
+                captured = { scrollLines: h.scrollLines, scrollToBottom: h.scrollToBottom };
+            } }));
+        await new Promise((r) => setTimeout(r, 50));
+        expect(captured).not.toBeNull();
+        // Wheel up ×12 (3 lines each = 36 > maxTop 32) → pinned at top.
+        for (let i = 0; i < 12; i++)
+            captured.scrollLines(-3);
+        await new Promise((r) => setTimeout(r, 50));
+        const top = lastFrame() ?? '';
+        expect(top).toMatch(/MSG-00-tag/);
+        expect(top).not.toMatch(/MSG-24-tag/);
+        // scrollToBottom → tail visible again.
+        captured.scrollToBottom();
+        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/measure.d.ts

@@ -0,0 +1,85 @@
+/**
+ * scroll.md §4 — Measurement layer (item → display lines).
+ *
+ * Pure functions only: no hooks, no side effects. The App measures each
+ * transcript block into wrapped display-line heights, caches by
+ * (key, width, content-signature), and builds a cumulative line index so
+ * scrolling is O(1) per frame and only the streaming tail is re-measured.
+ *
+ * Heights mirror the render structure in app.tsx:
+ *   user text      = wrapped lines + 1 (marginBottom)
+ *   assistant text = 1 (guide+Klyro header) + wrapped + 1
+ *   group collapsed= 1 + 1 margin; expanded = 1 + min(n,12) + overflow?1 + 1
+ *   error          = wrapped + 1 margin
+ *   policy         = 0 (renders null)
+ *   file_changed   = 1 + 1 margin
+ *   diff           = 1 summary + Σ(1 path + wrapped hunk lines) + 1 margin
+ *   plan block     = 1 + min(8, steps) + 1 margin
+ *   thinking/queue = content lines + 1 margin
+ */
+/** Display width per scroll.md §12: never `.length` (CJK=2, emoji=2, combining=0). */
+export declare function displayWidth(s: string): number;
+/** Wrapped display-line count for already-newline-split text at `width`. */
+export declare function wrapCount(text: string, width: number): number;
+/** Content width inside the transcript column (guide prefix + padding). */
+export declare function contentWidth(termWidth: number): number;
+export type BlockDesc = {
+    kind: 'user';
+    text: string;
+} | {
+    kind: 'assistant';
+    text: string;
+} | {
+    kind: 'group';
+    count: number;
+    expanded: boolean;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'policy';
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'diff';
+    hunks: Array<{
+        path: string;
+        lines: string[];
+    }>;
+} | {
+    kind: 'plan';
+    done: number;
+    total: number;
+} | {
+    kind: 'thinking';
+} | {
+    kind: 'queued';
+    count: number;
+};
+export declare const EXPANDED_DETAIL_CAP = 12;
+export declare function blockHeight(b: BlockDesc, termWidth: number): number;
+/** Content fingerprint: changes whenever the block's rendered lines could change. */
+export declare function blockSig(b: BlockDesc): string;
+/** Cache: key → height. Only the streaming tail changes sig per tick (I6 → O(1)). */
+export declare class MeasureCache {
+    private map;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    heightFor(key: string, block: BlockDesc, termWidth: number): number;
+    /** Resize (width change) invalidates everything — scroll.md §12. */
+    invalidateWidth(): void;
+    get size(): number;
+}
+export interface LineIndex {
+    offsets: number[];
+    total: number;
+}
+/** Cumulative first-row offsets; dirtyFrom allows incremental rebuild (only tail dirtied). */
+export declare function buildIndex(heights: number[], prev?: {
+    offsets: number[];
+    dirtyFrom: number;
+}): LineIndex;
+/** Binary search: display row → block index (upperBound(offsets, row) - 1). */
+export declare function itemAtRow(offsets: number[], row: number): number;
+export declare function clamp(n: number, lo: number, hi: number): number;

package/dist/tui/measure.js

@@ -0,0 +1,186 @@
+/**
+ * scroll.md §4 — Measurement layer (item → display lines).
+ *
+ * Pure functions only: no hooks, no side effects. The App measures each
+ * transcript block into wrapped display-line heights, caches by
+ * (key, width, content-signature), and builds a cumulative line index so
+ * scrolling is O(1) per frame and only the streaming tail is re-measured.
+ *
+ * Heights mirror the render structure in app.tsx:
+ *   user text      = wrapped lines + 1 (marginBottom)
+ *   assistant text = 1 (guide+Klyro header) + wrapped + 1
+ *   group collapsed= 1 + 1 margin; expanded = 1 + min(n,12) + overflow?1 + 1
+ *   error          = wrapped + 1 margin
+ *   policy         = 0 (renders null)
+ *   file_changed   = 1 + 1 margin
+ *   diff           = 1 summary + Σ(1 path + wrapped hunk lines) + 1 margin
+ *   plan block     = 1 + min(8, steps) + 1 margin
+ *   thinking/queue = content lines + 1 margin
+ */
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+function isWide(cp) {
+    return ((cp >= 0x1100 && cp <= 0x115f) ||
+        (cp >= 0x2e80 && cp <= 0xa4cf) ||
+        (cp >= 0xac00 && cp <= 0xd7a3) ||
+        (cp >= 0xf900 && cp <= 0xfaff) ||
+        (cp >= 0xfe30 && cp <= 0xfe4f) ||
+        (cp >= 0xff00 && cp <= 0xff60) ||
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1faff) ||
+        (cp >= 0x2600 && cp <= 0x27bf) ||
+        (cp >= 0x2b00 && cp <= 0x2bff));
+}
+function isZeroWidth(cp) {
+    return ((cp >= 0x0300 && cp <= 0x036f) ||
+        (cp >= 0x200b && cp <= 0x200f) ||
+        (cp >= 0xfe00 && cp <= 0xfe0f) ||
+        cp === 0x00ad);
+}
+/** Display width per scroll.md §12: never `.length` (CJK=2, emoji=2, combining=0). */
+export function displayWidth(s) {
+    const clean = s.replace(ANSI_RE, '').replace(/\t/g, '        ');
+    let w = 0;
+    for (const ch of clean) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (isZeroWidth(cp))
+            continue;
+        w += isWide(cp) ? 2 : 1;
+    }
+    return w;
+}
+/** Wrapped display-line count for already-newline-split text at `width`. */
+export function wrapCount(text, width) {
+    const w = Math.max(1, width);
+    let n = 0;
+    for (const line of text.split('\n')) {
+        const dw = displayWidth(line);
+        n += dw === 0 ? 1 : Math.max(1, Math.ceil(dw / w));
+    }
+    return Math.max(1, n);
+}
+/** Content width inside the transcript column (guide prefix + padding). */
+export function contentWidth(termWidth) {
+    return Math.max(20, termWidth - 10);
+}
+export const EXPANDED_DETAIL_CAP = 12; // scroll.md §9.3
+export function blockHeight(b, termWidth) {
+    const cw = contentWidth(termWidth);
+    switch (b.kind) {
+        case 'user':
+            return wrapCount(b.text, termWidth) + 1;
+        case 'assistant':
+            return 1 + wrapCount(b.text, cw) + 1;
+        case 'group':
+            if (!b.expanded)
+                return 1 + 1;
+            return 1 + Math.min(b.count, EXPANDED_DETAIL_CAP) + (b.count > EXPANDED_DETAIL_CAP ? 1 : 0) + 1;
+        case 'error':
+            return wrapCount(b.message, termWidth) + 1;
+        case 'policy':
+            return 0;
+        case 'file':
+            return 1 + 1;
+        case 'diff': {
+            let n = 1; // summary
+            for (const h of b.hunks)
+                n += 1 + h.lines.reduce((s, l) => s + wrapCount(l, cw), 0);
+            return n + 1;
+        }
+        case 'plan':
+            return 1 + Math.min(8, b.total) + 1;
+        case 'thinking':
+            return 1 + 1;
+        case 'queued':
+            return b.count + 1;
+    }
+}
+/** Content fingerprint: changes whenever the block's rendered lines could change. */
+export function blockSig(b) {
+    switch (b.kind) {
+        case 'user':
+            return `u:${b.text.length}:${b.text.slice(0, 16)}:${b.text.slice(-16)}`;
+        case 'assistant':
+            return `a:${b.text.length}:${b.text.slice(0, 16)}:${b.text.slice(-16)}`;
+        case 'group':
+            return `g:${b.count}:${b.expanded ? 1 : 0}`;
+        case 'error':
+            return `e:${b.message.length}:${b.message.slice(-32)}`;
+        case 'policy':
+            return 'p';
+        case 'file':
+            return `f:${b.path}`;
+        case 'diff':
+            return `d:${b.hunks.length}:${b.hunks.reduce((s, h) => s + h.lines.length, 0)}`;
+        case 'plan':
+            return `pl:${b.done}/${b.total}`;
+        case 'thinking':
+            return 't';
+        case 'queued':
+            return `q:${b.count}`;
+    }
+}
+/** Cache: key → height. Only the streaming tail changes sig per tick (I6 → O(1)). */
+export class MeasureCache {
+    map = new Map();
+    maxEntries;
+    constructor(maxEntries = 2000) {
+        this.maxEntries = maxEntries;
+    }
+    heightFor(key, block, termWidth) {
+        const sig = blockSig(block);
+        const hit = this.map.get(key);
+        if (hit && hit.width === termWidth && hit.sig === sig)
+            return hit.height;
+        const height = blockHeight(block, termWidth);
+        if (this.map.size >= this.maxEntries) {
+            const oldest = this.map.keys().next();
+            if (!oldest.done)
+                this.map.delete(oldest.value);
+        }
+        this.map.set(key, { width: termWidth, sig, height });
+        return height;
+    }
+    /** Resize (width change) invalidates everything — scroll.md §12. */
+    invalidateWidth() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+/** Cumulative first-row offsets; dirtyFrom allows incremental rebuild (only tail dirtied). */
+export function buildIndex(heights, prev) {
+    const offsets = prev ? [...prev.offsets] : [];
+    const from = prev ? Math.min(prev.dirtyFrom, heights.length) : 0;
+    for (let i = Math.max(0, from); i < heights.length; i++) {
+        offsets[i] = i === 0 ? 0 : offsets[i - 1] + heights[i - 1];
+    }
+    offsets.length = heights.length;
+    const last = heights.length - 1;
+    const total = last < 0 ? 0 : offsets[last] + heights[last];
+    return { offsets, total };
+}
+/** Binary search: display row → block index (upperBound(offsets, row) - 1). */
+export function itemAtRow(offsets, row) {
+    if (offsets.length === 0)
+        return -1;
+    if (row <= 0)
+        return 0;
+    let lo = 0;
+    let hi = offsets.length - 1;
+    let ans = 0;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (offsets[mid] <= row) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans;
+}
+export function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}

package/dist/tui/mouse.d.ts

@@ -0,0 +1,36 @@
+/**
+ * scroll.md §8.5 (S8) — mouse wheel capture for OpenCode-style scrolling.
+ *
+ * Ink owns stdin via useInput and cannot see mouse events, so the REPL wraps
+ * `process.stdin.emit` with this stateful splitter: SGR/X10 mouse sequences
+ * are swallowed (wheel → scroll deltas, clicks/motion → dropped), everything
+ * else passes through to Ink untouched.
+ *
+ * Only the wheel is acted on. Clicks are swallowed (not forwarded) because a
+ * mouse-reporting terminal would otherwise deliver them to readline as typed
+ * garbage; Shift+drag still selects natively in most terminals.
+ *
+ * Sequences handled:
+ *   SGR: `\x1b[<Cb;x;yM` / `...m`  (1006, requested via `CSI ? 1006 h`)
+ *   X10: `\x1b[M Cb Cx Cy`         (fallback for terminals ignoring 1006)
+ * Wheel bit is 64 in both; direction bit is 1 (down) — modifiers OR into Cb.
+ */
+export declare const WHEEL_LINES = 3;
+export interface MouseSplit {
+    /** bytes Ink is still allowed to see */
+    kept: Buffer;
+    /** wheel deltas: negative = up (older), positive = down (newer) */
+    wheels: number[];
+}
+export declare class MouseFilter {
+    private pending;
+    /**
+     * Split one stdin chunk. Holds an unambiguous trailing partial mouse
+     * sequence for the next chunk; a lone trailing ESC passes through
+     * immediately so the Esc key (queued-drop) never lags.
+     */
+    push(chunk: Buffer): MouseSplit;
+    reset(): void;
+}
+export declare const MOUSE_ENABLE = "\u001B[?1000h\u001B[?1006h";
+export declare const MOUSE_DISABLE = "\u001B[?1000l\u001B[?1006l";

package/dist/tui/mouse.js

@@ -0,0 +1,94 @@
+/**
+ * scroll.md §8.5 (S8) — mouse wheel capture for OpenCode-style scrolling.
+ *
+ * Ink owns stdin via useInput and cannot see mouse events, so the REPL wraps
+ * `process.stdin.emit` with this stateful splitter: SGR/X10 mouse sequences
+ * are swallowed (wheel → scroll deltas, clicks/motion → dropped), everything
+ * else passes through to Ink untouched.
+ *
+ * Only the wheel is acted on. Clicks are swallowed (not forwarded) because a
+ * mouse-reporting terminal would otherwise deliver them to readline as typed
+ * garbage; Shift+drag still selects natively in most terminals.
+ *
+ * Sequences handled:
+ *   SGR: `\x1b[<Cb;x;yM` / `...m`  (1006, requested via `CSI ? 1006 h`)
+ *   X10: `\x1b[M Cb Cx Cy`         (fallback for terminals ignoring 1006)
+ * Wheel bit is 64 in both; direction bit is 1 (down) — modifiers OR into Cb.
+ */
+export const WHEEL_LINES = 3; // scroll.md §8.4: wheel = ±3 lines
+function isDigit(b) {
+    return b >= 0x30 && b <= 0x39;
+}
+export class MouseFilter {
+    pending = Buffer.alloc(0);
+    /**
+     * Split one stdin chunk. Holds an unambiguous trailing partial mouse
+     * sequence for the next chunk; a lone trailing ESC passes through
+     * immediately so the Esc key (queued-drop) never lags.
+     */
+    push(chunk) {
+        const buf = Buffer.concat([this.pending, chunk]);
+        this.pending = Buffer.alloc(0);
+        const kept = [];
+        const wheels = [];
+        let i = 0;
+        const n = buf.length;
+        while (i < n) {
+            // SGR mouse: ESC [ < Cb ; x ; y (M|m)
+            if (buf[i] === 0x1b && i + 2 < n && buf[i + 1] === 0x5b && buf[i + 2] === 0x3c) {
+                let j = i + 3;
+                while (j < n && (isDigit(buf[j]) || buf[j] === 0x3b))
+                    j++;
+                if (j >= n) {
+                    // split across chunks — hold for more data
+                    this.pending = buf.subarray(i);
+                    break;
+                }
+                const term = buf[j];
+                if (term === 0x4d || term === 0x6d) {
+                    const cb = parseInt(buf.subarray(i + 3, j).toString().split(';')[0] ?? 'NaN', 10);
+                    if (!Number.isNaN(cb) && (cb & 64) !== 0) {
+                        wheels.push((cb & 1) === 0 ? -WHEEL_LINES : WHEEL_LINES);
+                    }
+                    i = j + 1; // swallow (wheel or click/motion)
+                    continue;
+                }
+                // ESC [ < not followed by digits→M/m: not a mouse seq, pass ESC through
+                kept.push(buf.subarray(i, i + 1));
+                i++;
+                continue;
+            }
+            // X10 mouse: ESC [ M Cb Cx Cy
+            if (buf[i] === 0x1b && i + 2 < n && buf[i + 1] === 0x5b && buf[i + 2] === 0x4d) {
+                if (i + 5 >= n) {
+                    this.pending = buf.subarray(i); // split across chunks
+                    break;
+                }
+                const cb = buf[i + 3] - 32;
+                if ((cb & 64) !== 0) {
+                    wheels.push((cb & 1) === 0 ? -WHEEL_LINES : WHEEL_LINES);
+                }
+                i += 6; // swallow
+                continue;
+            }
+            // Trailing partial that could ONLY be a split SGR/X10 start: hold it.
+            // A lone trailing ESC passes through (Esc key must not lag).
+            const tail = n - i;
+            if (tail <= 5) {
+                const rest = buf.subarray(i).toString('latin1');
+                if (/^\x1b\[<$/.test(rest) || /^\x1b\[<[\d;]+$/.test(rest) || /^\x1b\[M.{0,2}$/.test(rest)) {
+                    this.pending = buf.subarray(i);
+                    break;
+                }
+            }
+            kept.push(buf.subarray(i, i + 1));
+            i++;
+        }
+        return { kept: Buffer.concat(kept), wheels };
+    }
+    reset() {
+        this.pending = Buffer.alloc(0);
+    }
+}
+export const MOUSE_ENABLE = '\x1b[?1000h\x1b[?1006h'; // button events + SGR coords
+export const MOUSE_DISABLE = '\x1b[?1000l\x1b[?1006l';

package/dist/tui/scroll-flow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tui/scroll-flow.test.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * scroll.md diagnostic: realistic session flow — seed history, stream a long
+ * answer in chunks (like provider deltas), scroll mid-stream, stream more.
+ * Asserts the chat-flow invariants the user actually sees:
+ *   - follow-tail: latest streamed text visible while at bottom
+ *   - freeze: pinned viewport doesn't move while streaming
+ *   - badge counts new lines
+ *   - frame never exceeds terminal rows (I1)
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from 'ink-testing-library';
+import { App } from './app.js';
+const PROPS = {
+    initialModel: 'm',
+    maxSteps: 10,
+    cwd: '/test',
+    onPrompt: async () => { },
+    onSlash: async () => { },
+};
+const g = globalThis;
+const tick = (ms = 30) => new Promise((r) => setTimeout(r, ms));
+const rowsOf = (frame) => frame.split('\n').length;
+function seed(n) {
+    return Array.from({ length: n }, (_, i) => ({
+        id: `seed-${i}`,
+        kind: 'text',
+        text: `MSG-${i.toString().padStart(2, '0')}-tag`,
+        role: 'user',
+    }));
+}
+describe('scroll flow diagnostics', () => {
+    it('reports terminal geometry (debug aid)', async () => {
+        const { lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true }));
+        await tick(50);
+        const frame = lastFrame() ?? '';
+        // eslint-disable-next-line no-console
+        console.log(`[diag] frame rows=${rowsOf(frame)} cols~${(frame.split('\n')[0] ?? '').length}`);
+        expect(rowsOf(frame)).toBeLessThanOrEqual(32);
+    });
+    it('follow-tail: streamed long answer stays visible, frame stays bounded', async () => {
+        const { lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: seed(5) }));
+        await tick(50);
+        g.__klyroAppStatus({ status: 'running' });
+        const chunk = 'STREAMCHUNK lorem ipsum dolor sit amet. ';
+        for (let i = 0; i < 12; i++) {
+            g.__klyroAppendDelta(`${chunk}#${i} `);
+            await tick(40);
+            const frame = lastFrame() ?? '';
+            expect(rowsOf(frame)).toBeLessThanOrEqual(32);
+            // latest streamed chunk must be visible (follow-tail)
+            expect(frame).toContain(`#${i}`);
+        }
+    });
+    it('freeze: pinned top survives streaming, badge counts, End restores', async () => {
+        const { stdin, lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: seed(40) }));
+        await tick(100);
+        stdin.write('\x1b[H'); // Home → top
+        await tick(50);
+        const top = lastFrame() ?? '';
+        expect(top).toContain('MSG-00-tag');
+        g.__klyroAppStatus({ status: 'running' });
+        for (let i = 0; i < 5; i++) {
+            g.__klyroAppendDelta(`late chunk number ${i} with filler words here. `);
+            await tick(40);
+        }
+        const frozen = lastFrame() ?? '';
+        expect(frozen).toContain('MSG-00-tag'); // viewport did not yank down
+        expect(frozen).toMatch(/↓ \d+ new/); // badge visible
+        expect(rowsOf(frozen)).toBeLessThanOrEqual(32);
+        stdin.write('\x1b[F'); // End → follow
+        await tick(50);
+        expect(lastFrame() ?? '').toContain('number 4');
+    });
+    it('wrapped long item: pin mid-item, stream, same first line stays', async () => {
+        const long = Array.from({ length: 10 }, (_, i) => `WRAPLINE-${i} ` + 'x'.repeat(180)).join('\n');
+        const items = [
+            { id: 'w1', kind: 'text', text: long, role: 'assistant' },
+            ...seed(30),
+        ];
+        const { stdin, lastFrame } = render(_jsx(App, { ...PROPS, isFullscreen: true, initialTranscript: items }));
+        await tick(100);
+        stdin.write('\x1b[H');
+        await tick(50);
+        const before = (lastFrame() ?? '').split('\n').slice(0, 3).join('\n');
+        g.__klyroAppStatus({ status: 'running' });
+        for (let i = 0; i < 5; i++) {
+            g.__klyroAppendDelta(`more streamed text ${i} ` + 'y'.repeat(120));
+            await tick(40);
+        }
+        const after = (lastFrame() ?? '').split('\n').slice(0, 3).join('\n');
+        expect(after).toBe(before); // anchor stability at line granularity
+    });
+});

package/dist/tui/scroll-model.d.ts

@@ -0,0 +1,67 @@
+/**
+ * scroll.md §5 — Anchor-based scroll model (pure, no React).
+ *
+ * Position is an Anchor ({itemId, lineInItem}), never a raw row index (I4),
+ * so resizes, group expand/collapse, and compaction never make the view jump.
+ * While anchored to 'bottom', new output follows; the instant the user scrolls
+ * up the anchor pins to an item and freezes, accumulating newSinceUnstick
+ * display lines for the `↓ N new` badge (§7).
+ */
+export type Anchor = {
+    mode: 'bottom';
+} | {
+    mode: 'pinned';
+    itemId: string;
+    lineInItem: number;
+};
+export interface ScrollState {
+    anchor: Anchor;
+    userScrolled: boolean;
+    /** display lines appended since the user unstuck (badge count, §7) */
+    newSinceUnstick: number;
+}
+export declare const FOLLOW_EPSILON = 1;
+export declare const initialScroll: ScrollState;
+export type ScrollAction = {
+    type: 'BY_LINES';
+    delta: number;
+} | {
+    type: 'BY_PAGE';
+    dir: -1 | 1;
+} | {
+    type: 'BY_HALF_PAGE';
+    dir: -1 | 1;
+} | {
+    type: 'TO_TOP';
+} | {
+    type: 'TO_BOTTOM';
+} | {
+    type: 'CONTENT_GREW';
+    lines: number;
+} | {
+    type: 'REFLOW';
+};
+/** Index abstraction over measured display lines (§4.3). */
+export interface ScrollCtx {
+    /** number of blocks */
+    count: number;
+    /** display-line offset of block i */
+    offsetOf: (i: number) => number;
+    /** key of block i (stable across regroups) */
+    keyOf: (i: number) => string;
+    /** block index containing display row */
+    indexAt: (row: number) => number;
+    /** total measured display lines */
+    total: number;
+    viewportH: number;
+}
+export declare function maxTopFor(ctx: ScrollCtx): number;
+export declare function scrollReducer(s: ScrollState, a: ScrollAction, ctx: ScrollCtx): ScrollState;
+export interface Resolved {
+    topRow: number;
+    atBottom: boolean;
+}
+/** Anchor → topRow, run once per frame after the line index rebuild (§5.3). */
+export declare function resolveTopRow(s: ScrollState, ctx: ScrollCtx): Resolved;
+/** Badge label per §7.2. Empty string = hidden. */
+export declare function badgeLabel(atBottom: boolean, newSinceUnstick: number, idle: boolean): string;