@vincemakes/kiso-tui 0.2.0 → 0.6.0

package/dist/compositor.d.ts

@@ -49,6 +49,22 @@ import { type ResumeMeta } from "./render.js";
  *  embeds at the edit position; the compositor strips it and moves
  *  relatively (it never reaches the terminal). */
 export declare const CURSOR_MARKER = "\u001B_[kiso-cur]\u001B\\";
+/** KC1 §5 — the input row's bound state. The legacy pair stays
+ *  REQUIRED and keeps its exact meaning (the cursor line's visible
+ *  slice and its display column), so a one-row provider — the old
+ *  `{line, cursor}` shape — keeps working unchanged; the composer's
+ *  rows ride as OPTIONAL fields, which is what makes the CLI's binding
+ *  signature-neutral (zero cli source growth). */
+export interface InputState {
+    readonly line: string;
+    readonly cursor: number;
+    /** the visible rows (≤ N_visible), dim "…" markers included */
+    readonly lines?: readonly string[];
+    /** the cursor's row within `lines` */
+    readonly cursorRow?: number;
+    /** the cursor's display column within that row */
+    readonly cursorCol?: number;
+}
 export interface BodyOptions {
     /** Is the cell renderer live? A color TTY with a real size — checked
      *  per mutation (the TIOCSWINSZ can land after main constructs us). */
@@ -182,10 +198,7 @@ export declare class Body {
      *  up; the old ApprovalPrompt's question slot retires with it). */
     bindApproval(state: () => PanelState | null): void;
     /** Bind the CURRENT input line's state — the focus component reads it. */
-    bindInput(state: () => {
-        line: string;
-        cursor: number;
-    }, prompt: string): void;
+    bindInput(state: () => InputState, prompt: string): void;
     /** Bind the editor's slash-command menu state — the MenuSelect slot
      *  occupant (the menu replaces the editor's view while open). */
     bindMenu(state: () => {
@@ -228,10 +241,7 @@ export declare class Dock {
      *  occupant (the panel replaces the live region + the input lead
      *  while up; the old ApprovalPrompt's question slot retires). */
     bindApproval(state: () => PanelState | null): void;
-    bindInput(state: () => {
-        line: string;
-        cursor: number;
-    }, prompt: string): void;
+    bindInput(state: () => InputState, prompt: string): void;
     bindMenu(state: () => {
         items: readonly MenuItem[];
         selected: number;

package/dist/compositor.js

@@ -77,6 +77,12 @@ export class Body {
     #lastLiveRows = 0; // the recorded live row count (incl. the chrome)
     #lastSkip = 0; // the last frame's window top in model rows — the A8b scroll's leaving-count base
     #lastH = 0;
+    // KC1 §6: the composer's recorded extent — the row count the last
+    // frame drew (exit's clear walks it) and the row its CHA parked the
+    // cursor on (the steady frame's relative anchor). N = 1 reproduces
+    // the retired constants exactly (one input row, the anchor at H−2).
+    #lastInputRows = 1;
+    #lastAnchorRow = 0;
     #frameTimer = null;
     #spinnerTimer = null;
     #spinnerI = 0;
@@ -599,8 +605,10 @@ export class Body {
         const H = this.#lastH > 0 ? this.#lastH : process.stdout.rows ?? 24;
         const out = [];
         out.push("\x1b[r");
-        for (let row = H - 3; row <= H; row += 1) { // V6-3: the four chrome rows
-            out.push(`\x1b[${row};1H\x1b[0K`); // clear the three chrome rows
+        // V6-3 + KC1: the chrome rows — the RECORDED composer extent rides
+        // the same mechanism the resize clear already uses (N = 1 ⇒ H−3..H)
+        for (let row = H - 2 - this.#lastInputRows; row <= H; row += 1) {
+            out.push(`\x1b[${row};1H\x1b[0K`); // clear the chrome rows
         }
         out.push(`\x1b[${Math.max(1, H - 1)};1H`);
         this.#write(out.join(""));
@@ -751,11 +759,17 @@ export class Body {
     liveCount() {
         const panel = this.#panelState?.() ?? null;
         const queueRows = this.#queueRows(this.#opts.width(), this.#opts.height());
+        // KC1 §6: the composer's extra rows are chrome too — the scalar
+        // counts them exactly like the menu/queue bands (N = 1 ⇒ +0)
+        const inputExtra = this.#inputRows(this.#opts.width(), this.#opts.height(), this.#menuRows(this.#opts.width()).length, queueRows.length).rows.length - 1;
         if (panel !== null) {
             // W21: the panel's own rows (the cap is exact — the scalar
             // reflects the screen). W22: the queue chips occupy their
             // own band — the panel's cap shrinks by their rows.
-            return panelBlockRows(panel.view, panel.phase, panel.sel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - queueRows.length)).length + CHROME_ROWS + queueRows.length;
+            return (panelBlockRows(panel.view, panel.phase, panel.sel, this.#opts.width(), Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
+                CHROME_ROWS +
+                inputExtra +
+                queueRows.length);
         }
         const live = this.#cells.slice(this.#committed);
         const ctx = { spinnerI: this.#spinnerI, now: Date.now(), height: this.#opts.height() };
@@ -767,7 +781,7 @@ export class Body {
             lines += bodySpacing(prev, rows).length;
             prev = rows;
         }
-        return lines + CHROME_ROWS + this.#menuRows(W).length + queueRows.length;
+        return lines + CHROME_ROWS + inputExtra + this.#menuRows(W).length + queueRows.length;
     }
     /** The lines committed THIS frame — the writes land in the frame's
      *  committed section (the rows just above the live region). */
@@ -825,7 +839,12 @@ export class Body {
         // (the band above the box top) — the chrome rows and the live
         // caps account for both.
         const queueRows = this.#queueRows(W, H);
-        const chromeRows = CHROME_ROWS + menuRows.length + queueRows.length;
+        // KC1 §6: the input is N rows now (N = 1 ⇒ today's chrome exactly)
+        // — chromeRows = 3 + N + menu + queue, and the content cap loses
+        // the composer's EXTRA rows the same way it loses the bands.
+        const editor = this.#inputRows(W, H, menuRows.length, queueRows.length);
+        const inputExtra = editor.rows.length - 1;
+        const chromeRows = CHROME_ROWS + inputExtra + menuRows.length + queueRows.length;
         let liveLines = [];
         const panel = this.#panelState?.() ?? null;
         if (panel !== null) {
@@ -834,7 +853,7 @@ export class Body {
             // the W11 blank would separate it from the frozen content).
             // The cap is exact, so the force-commit loop never fires. W22:
             // the queue band sits below the panel — the cap shrinks by it.
-            liveLines = panelBlockRows(panel.view, panel.phase, panel.sel, W, Math.max(1, H - 4 - queueRows.length));
+            liveLines = panelBlockRows(panel.view, panel.phase, panel.sel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
         }
         else {
             let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
@@ -848,7 +867,7 @@ export class Body {
         //    commits the oldest live cell UNCONDITIONALLY (the one sharp
         //    edge — the cap scalar is asserted by the gates). W22: the
         //    queue band shrinks the cap by its rows (empty queue → H−4).
-        while (liveLines.length > H - 4 - queueRows.length && this.#committed < this.#cells.length) { // V6-3: the content cap H−4
+        while (liveLines.length > H - 4 - inputExtra - queueRows.length && this.#committed < this.#cells.length) { // V6-3: the content cap H−4 (KC1: −N's extra rows)
             this.#commitCell(this.#committed, W, ctx);
             liveLines = [];
             {
@@ -882,16 +901,21 @@ export class Body {
         // path: the window re-paints at the model's positions, every row
         // covered (the V6-1 every-row rule).
         if (this.#fullRedraw || liveTop > this.#lastLiveTop + this.#committedLinesThisFrame.length || liveRowsTotal < this.#lastLiveRows) {
-            this.#drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, ctx);
+            this.#drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, editor);
             this.#fullRedraw = false;
         }
         else {
-            this.#drawSteady(out, W, H, liveTop, liveLines, queueRows, menuRows, ctx);
+            this.#drawSteady(out, W, H, liveTop, liveLines, queueRows, menuRows, editor);
         }
         out.push("\x1b[?2026l");
         this.#write(out.join(""));
         this.#lastLiveTop = liveTop;
         this.#lastLiveRows = liveRowsTotal;
+        this.#lastInputRows = editor.rows.length;
+        // KC1 §6: the next steady frame's relative moves start where THIS
+        // frame's CHA parked the cursor — the marker's row inside the
+        // composer (N = 1 ⇒ H−2, the retired hard-coded anchor).
+        this.#lastAnchorRow = H - 1 - editor.rows.length + editor.markerRow;
     }
     /** Commit the cell at index i: render + cache its lines (immutable —
      *  the force-committed form freezes at the current render), advance
@@ -1044,9 +1068,20 @@ export class Body {
      *  occupant (the queue is dense, like the menu; each line is its
      *  own chip with the □ gutter). */
     #queueRows(W, H) {
-        const lines = this.#queueState?.() ?? [];
-        if (lines.length === 0)
+        const queued = this.#queueState?.() ?? [];
+        if (queued.length === 0)
             return [];
+        // KC1 (adjudication A4): a MULTI-LINE queued message's chip shows
+        // its FIRST line + a ⏎×k suffix — k = the additional lines, counted
+        // after the SAME §3 normalization the editor applies (a CRLF pair
+        // is ONE break), so the chip stays one row per queued turn. The
+        // suffix rides INSIDE the chip as plain text: the chip renderer
+        // escapes control bytes, so an SGR span would be stripped there —
+        // and the cells package stays untouched this round.
+        const lines = queued.map((line) => {
+            const parts = line.replace(/\r\n?/g, "\n").split("\n");
+            return parts.length > 1 ? `${parts[0]} ⏎×${parts.length - 1}` : line;
+        });
         // A8b: the band CAPS so the content keeps its rows — an unbounded
         // band (the batch flood pastes the whole queue at once) overflowed
         // the screen: the content cap H−4−queue went negative, the march
@@ -1078,14 +1113,14 @@ export class Body {
         }
         return rows;
     }
-    /** The focus component's input row — the marker embedded at the
-     *  cursor's display column WITHIN THE ROW (the brick/question lead
-     *  included), the question/editor/menu variants. The compositor
-     *  strips the marker and returns the frame-derived COLUMN — the
-     *  cursor move lands AT the marker (a CHA — the column is absolute,
-     *  so the move's base is irrelevant; the retired afterW CUB's base
-     *  was the LAST write's end column, which the steady frame's
-     *  gap/stale ELs leave at col 1 — the A3 finding).
+    /** ONE input row's bytes — the marker embedded at `embedAt` (the
+     *  cursor's display column within the row) when this row owns the
+     *  cursor, `null` on the composer's other rows. The compositor
+     *  strips the marker and returns the frame-derived CELL — the cursor
+     *  move lands AT the marker (a CHA — the column is absolute, so the
+     *  move's base is irrelevant; the retired afterW CUB's base was the
+     *  LAST write's end column, which the steady frame's gap/stale ELs
+     *  leave at col 1 — the A3 finding).
      *
      *  W6: the row lives INSIDE the box — the walls are a prefix/suffix
      *  width only, composed AFTER the marker embed (the marker math is
@@ -1094,67 +1129,101 @@ export class Body {
      *  pad completes the row to EXACTLY W — invariant ① throws on
      *  overflow, so the box row is built full-width, never truncated.
      *  W23: the lead width is the ONE authority — leadWidth (width.ts),
-     *  shared with the editor's selfRender/#reflow and editCol. */
-    #inputRow(W, _ctx) {
-        const st = this.#inputState();
-        const panel = this.#panelState?.() ?? null;
-        // the lead — the panel's phase lead when the panel owns the row
-        // (1-3> / the rule input's "2 Yes, don't ask again for " / the
-        // amend "feedback (deny): "), the bound prompt otherwise
-        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
-        const leadW = leadWidth(lead);
-        const row = `${lead}${st.line}`;
-        // embed the marker at the cursor's display column
+     *  shared with the editor's selfRender/#reflow and editCol.
+     *  KC1 §6: the walk is UNCHANGED — a one-row composer emits exactly
+     *  today's bytes (the T-C1 identity anchor). */
+    #inputRowBytes(row, W, embedAt) {
         let markerLine = "";
         let markerCell = 0; // the marker's 0-based cell — the walk's w at the embed
         let w = 0;
-        {
-            let inserted = false;
-            let i = 0;
-            while (i < row.length) {
-                if (row[i] === "\x1b") {
-                    const m = /^\x1b\[[0-9;]*m/.exec(row.slice(i));
-                    if (m !== null) {
-                        markerLine += m[0];
-                        i += m[0].length;
-                        continue;
-                    }
-                }
-                if (!inserted && w >= leadW + st.cursor) {
-                    markerLine += CURSOR_MARKER;
-                    markerCell = w;
-                    inserted = true;
+        let inserted = embedAt === null; // a row without the cursor never embeds
+        let i = 0;
+        while (i < row.length) {
+            if (row[i] === "\x1b") {
+                const m = /^\x1b\[[0-9;]*m/.exec(row.slice(i));
+                if (m !== null) {
+                    markerLine += m[0];
+                    i += m[0].length;
+                    continue;
                 }
-                const cw = displayWidth(row[i]);
-                if (w + cw > W - 4)
-                    break; // the cap — the two walls' columns
-                markerLine += row[i];
-                w += cw;
-                i += 1;
             }
-            if (!inserted) {
-                // the walk ended before the cursor cell (the box edge) —
-                // the marker rests at the row's end; the move still lands
-                // AT it (the min() of the contract)
+            if (!inserted && w >= embedAt) {
                 markerLine += CURSOR_MARKER;
                 markerCell = w;
+                inserted = true;
             }
+            const cw = displayWidth(row[i]);
+            if (w + cw > W - 4)
+                break; // the cap — the two walls' columns
+            markerLine += row[i];
+            w += cw;
+            i += 1;
+        }
+        if (!inserted) {
+            // the walk ended before the cursor cell (the box edge) — the
+            // marker rests at the row's end; the move still lands AT it
+            // (the min() of the contract)
+            markerLine += CURSOR_MARKER;
+            markerCell = w;
         }
         const stripped0 = markerLine.replace(CURSOR_MARKER, "");
         if (W < 4) {
             // the degenerate screen: the box cannot hold its walls — the
             // bare row (the pre-W6 bytes; the fold probe's pass-through
             // line still crashes invariant ① downstream, as before)
-            return { stripped: stripped0, markerCol: 3 + markerCell };
+            return { stripped: stripped0, markerCell };
         }
         // the pad completes the row to W — the content stopped at W−4,
         // so the pad is ≥ 1
         const padW = W - 3 - w;
-        const stripped = `\x1b[2m│ \x1b[0m${stripped0}\x1b[2m${" ".repeat(padW)}│\x1b[0m`;
-        // W23: the frame-derived column — wallL (2) + the marker's cell
-        // + 1 — the CHA lands the cursor AT the marker from ANY base
-        const markerCol = 3 + markerCell;
-        return { stripped, markerCol };
+        return { stripped: `\x1b[2m│ \x1b[0m${stripped0}\x1b[2m${" ".repeat(padW)}│\x1b[0m`, markerCell };
+    }
+    /** KC1 §6 — the focus component's input ROWS (N = 1 today's single
+     *  row, byte for byte). The lead rides the FIRST row and the
+     *  continuations indent by its width, so the cursor's column formula
+     *  is the same on every row; the CURSOR'S row carries the marker and
+     *  the frame derives the cursor from it — row AND column — with no
+     *  editPos side channel.
+     *
+     *  The rows arrive already windowed by the editor's §5 estimate; the
+     *  frame re-applies the SAME clamp against the REAL folded menu and
+     *  queue bands (N_visible's height term), keeping the cursor's row
+     *  in view — so the geometry is legal at every terminal size. */
+    #inputRows(W, H, menuRows, queueRows) {
+        const st = this.#inputState();
+        const panel = this.#panelState?.() ?? null;
+        // the lead — the panel's phase lead when the panel owns the row
+        // (1-3> / the rule input's "2 Yes, don't ask again for " / the
+        // amend "feedback (deny): "), the bound prompt otherwise
+        const lead = panel !== null ? panelLead(panel.view, panel.phase, panel.sel) : this.#inputPrompt;
+        const leadW = leadWidth(lead);
+        // a LEGACY one-row provider (the old {line, cursor} shape) keeps
+        // working: its single line is the composer's single row
+        let rows = st.lines !== undefined && st.lines.length > 0 ? [...st.lines] : [st.line];
+        let cursorRow = Math.min(st.cursorRow ?? 0, rows.length - 1);
+        const cursorCol = st.cursorCol ?? st.cursor;
+        // KC1 §5's N_visible, re-applied against the frame's REAL bands:
+        // the editor could only estimate the menu/queue heights (they
+        // fold at width), so the frame is the authority. The window keeps
+        // the CURSOR'S row, so a clamp never hides it.
+        const n = Math.max(1, Math.min(rows.length, H - 3 - menuRows - queueRows));
+        if (rows.length > n) {
+            const first = Math.max(0, Math.min(cursorRow - n + 1, rows.length - n));
+            rows = rows.slice(first, first + n);
+            cursorRow -= first;
+        }
+        const out = [];
+        let markerCol = 3;
+        for (let r = 0; r < rows.length; r += 1) {
+            const text = `${r === 0 ? lead : " ".repeat(leadW)}${rows[r]}`;
+            const bytes = this.#inputRowBytes(text, W, r === cursorRow ? leadW + cursorCol : null);
+            out.push(bytes.stripped);
+            // W23: the frame-derived column — wallL (2) + the marker's
+            // cell + 1 — the CHA lands the cursor AT the marker from ANY base
+            if (r === cursorRow)
+                markerCol = 3 + bytes.markerCell;
+        }
+        return { rows: out, markerRow: cursorRow, markerCol };
     }
     /** The full-redraw path (the first frame, the resize repaint) — CUP
      *  allowed here; zero LF; zero \x1b[3J; zero replay. The committed
@@ -1167,7 +1236,8 @@ export class Body {
      *  survive anywhere the draw does not touch; a draw that covers
      *  EVERY row is idempotent: N consecutive resizes end with the same
      *  screen as a single jump to the same size. */
-    #drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, ctx) {
+    #drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, editor) {
+        const inputExtra = editor.rows.length - 1; // KC1: the composer's rows above the retired single input row
         const committed = this.#committedLinesThisFrame;
         // 0. the FROZEN rows — the re-folded committed content (re-flowed
         //    at the new width by the terminal): re-painted at [1..frozen],
@@ -1194,7 +1264,7 @@ export class Body {
         // window (the committed share + the live + the chrome), r
         // monotone, every row 1..H re-painted (the V6-1 every-row rule).
         const all = [...frozen, ...committed, ...liveLines];
-        const skip = Math.max(0, all.length + CHROME_ROWS + queueRows.length + menuRows.length - H);
+        const skip = Math.max(0, all.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
         // A8b (the shrink-trigger's completion): the rows that LEAVE the
         // window scroll into the terminal's scrollback — the LF mechanism
         // (the steady path's own). Only the rows the paint re-covers (the
@@ -1237,41 +1307,44 @@ export class Body {
             r += 1;
         }
         // 3. the GAP rows (between the live content and the chrome) — EL.
-        for (let rr = r; rr <= H - 4; rr += 1) {
+        for (let rr = r; rr <= H - 4 - inputExtra; rr += 1) {
             out.push(`\x1b[${rr};1H\x1b[0K`);
         }
         // W22: the queue chips sit directly above the box top (the
         // "pre-render ABOVE the input row"), the menu above the queue.
-        const queueTop = H - 3 - queueRows.length;
-        const menuTop = H - 3 - queueRows.length - menuRows.length;
+        const queueTop = H - 3 - inputExtra - queueRows.length;
+        const menuTop = queueTop - menuRows.length;
         for (let i = 0; i < queueRows.length; i += 1) {
             out.push(`\x1b[${queueTop + i};1H\x1b[0K${this.#checked(queueRows[i], W)}`);
         }
         for (let i = 0; i < menuRows.length; i += 1) {
             out.push(`\x1b[${menuTop + i};1H\x1b[0K${this.#checked(menuRows[i], W)}`);
         }
-        // V6-3 + W6: the design §03 chrome — box top (H−3), input
-        // (H−2), box bottom (H−1), status (H) — the box's four rows.
-        out.push(`\x1b[${H - 3};1H\x1b[0K${boxTop(W)}`);
-        const editor = this.#inputRow(W, ctx);
-        out.push(`\x1b[${H - 2};1H\x1b[0K${this.#checked(editor.stripped, W)}`);
+        // V6-3 + W6 + KC1 §6: the design §03 chrome — box top (H−2−N),
+        // the composer's N input rows (H−1−N .. H−2), box bottom (H−1),
+        // status (H). N = 1 is the retired four-row chrome exactly.
+        out.push(`\x1b[${H - 3 - inputExtra};1H\x1b[0K${boxTop(W)}`);
+        for (let i = 0; i < editor.rows.length; i += 1) {
+            out.push(`\x1b[${H - 2 - inputExtra + i};1H\x1b[0K${this.#checked(editor.rows[i], W)}`);
+        }
         out.push(`\x1b[${H - 1};1H\x1b[0K${boxBottom(W)}`);
         const statusRow = this.#statusSource();
         out.push(`\x1b[${H};1H\x1b[0K${this.#checked(statusLine(statusRow.status, this.#tail, W, statusRow.hint), W)}`);
-        // the cursor: up two (the input row at H−2) + the CHA to the
-        // marker's frame-derived column — W23: the afterW CUB retired
-        // (the CHA is absolute — the base is irrelevant; the CUB's base
-        // was the LAST write's end column, which the steady frame's ELs
-        // leave at col 1 — the A3 finding)
-        out.push("\x1b[2A");
+        // the cursor: up from the status row to the MARKER'S row inside
+        // the composer (N = 1, markerRow 0 ⇒ the retired \x1b[2A) + the
+        // CHA to the marker's frame-derived column — W23: the afterW CUB
+        // retired (the CHA is absolute — the base is irrelevant; the
+        // CUB's base was the LAST write's end column, which the steady
+        // frame's ELs leave at col 1 — the A3 finding)
+        out.push(`\x1b[${1 + editor.rows.length - editor.markerRow}A`);
         out.push(`\x1b[${editor.markerCol}G`);
     }
     /** The steady-state frame — RELATIVE moves only (invariant ②); the
      *  commits scroll via the CUP-free real LF at the last row, and the
      *  committed lines write in the march's top section (rows
      *  [liveTop−N .. liveTop−1] — the frozen area's bottom). */
-    #drawSteady(out, W, H, liveTop, liveLines, queueRows, menuRows, ctx) {
-        const editor = this.#inputRow(W, ctx); // derived from the frame — the marker
+    #drawSteady(out, W, H, liveTop, liveLines, queueRows, menuRows, editor) {
+        const inputExtra = editor.rows.length - 1; // KC1: the composer's rows above the retired single input row
         const committed = this.#committedLinesThisFrame;
         // A8b: the steady path's window geometry — the same skip as the full
         // path's (#lastSkip's formula): the model rows above the window
@@ -1280,7 +1353,7 @@ export class Body {
         // frozenCount, so the lines at [frozenCount..skip−1] are the fresh
         // leaving share (their old-screen copies are stale).
         const frozenCount = this.#committedLines - committed.length;
-        const skip = Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + queueRows.length + menuRows.length - H);
+        const skip = Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
         const leaving = Math.max(0, skip - this.#lastSkip);
         // the jump to the bottom row H, then N real LFs scroll the screen
         // exactly N rows — ONE per committed line (the bookkeeping; the
@@ -1329,18 +1402,25 @@ export class Body {
             out.push(`\x1b[${H};1H`); // CUP to the bottom — the absolute scroll base (the ELs moved the cursor)
         }
         else {
-            out.push("\x1b[2B"); // the anchor (H−2) to the bottom — no scroll
+            // KC1 §6: the anchor is where the LAST frame's CHA parked the
+            // cursor — the marker's row inside the composer (N = 1 ⇒ H−2,
+            // the retired \x1b[2B)
+            const anchorRow = this.#lastAnchorRow > 0 ? this.#lastAnchorRow : H - 2;
+            if (H > anchorRow)
+                out.push(`\x1b[${H - anchorRow}B`);
         }
         for (let i = 0; i < committed.length; i += 1)
             out.push("\n");
-        // the bottom-up repaint, from the last row up — V6-3 + W6: the
-        // design §03 chrome: status (H), box bottom (H−1), input (H−2),
-        // box top (H−3)
+        // the bottom-up repaint, from the last row up — V6-3 + W6 + KC1:
+        // the design §03 chrome: status (H), box bottom (H−1), the
+        // composer's N input rows (H−2 up to H−1−N), box top (H−2−N)
         const statusRow = this.#statusSource();
         out.push(`\x1b[1G\x1b[0K${this.#checked(statusLine(statusRow.status, this.#tail, W, statusRow.hint), W)}`); // H — the status
         out.push(`\x1b[1A\x1b[1G\x1b[0K${boxBottom(W)}`); // H−1 — the box bottom
-        out.push(`\x1b[1A\x1b[1G\x1b[0K${this.#checked(editor.stripped, W)}`); // H−2 — the input
-        out.push(`\x1b[1A\x1b[1G\x1b[0K${boxTop(W)}`); // H−3 — the box top
+        for (let i = editor.rows.length - 1; i >= 0; i -= 1) {
+            out.push(`\x1b[1A\x1b[1G\x1b[0K${this.#checked(editor.rows[i], W)}`); // the input rows, bottom-up
+        }
+        out.push(`\x1b[1A\x1b[1G\x1b[0K${boxTop(W)}`); // H−2−N — the box top
         // W22: the queue chips sit directly above the box top (the
         // "pre-render ABOVE the input row"), the menu above the queue —
         // the bottom-up order mirrors the row order.
@@ -1370,7 +1450,7 @@ export class Body {
         //    the queue + menu bands (their rows at [H−3−queue−menu..H−4]
         //    are marched and must survive — the unclamped geometry erased
         //    them).
-        for (let r = liveTop + liveLines.length; r <= H - 4 - queueRows.length - menuRows.length; r += 1) {
+        for (let r = liveTop + liveLines.length; r <= H - 4 - inputExtra - queueRows.length - menuRows.length; r += 1) {
             out.push(`\x1b[${r};1H\x1b[0K`);
         }
         // 2. the STALE rows above the committed section — the scrolled old
@@ -1402,14 +1482,16 @@ export class Body {
             ? Math.max(1, liveTop - 1)
             : staleFrom < liveTop
                 ? liveTop - 1
-                : liveTop + liveLines.length <= H - 4 - queueRows.length - menuRows.length
-                    ? H - 4 - queueRows.length - menuRows.length
+                : liveTop + liveLines.length <= H - 4 - inputExtra - queueRows.length - menuRows.length
+                    ? H - 4 - inputExtra - queueRows.length - menuRows.length
                     : liveLines.length > 0
                         ? liveTop + liveLines.length - 1
                         : menuRows.length > 0
-                            ? H - 3 - menuRows.length - queueRows.length
-                            : H - 3;
-        const down = H - 2 - lastRow; // the anchor: the input row (H−2)
+                            ? H - 3 - inputExtra - menuRows.length - queueRows.length
+                            : H - 3 - inputExtra;
+        // the anchor: the MARKER'S row inside the composer (N = 1,
+        // markerRow 0 ⇒ the retired H−2)
+        const down = H - 2 - inputExtra + editor.markerRow - lastRow;
         if (down > 0)
             out.push(`\x1b[${down}B`);
         // W23: the CHA to the frame-derived column — the cursor rests AT

package/dist/editor.d.ts

@@ -13,8 +13,13 @@
  * clusters (family emoji etc.) are not guaranteed perfect — each code
  * point counts as its width.
  *
- * The editor is a SINGLE line: bracketed paste (?2004h) unwraps and
- * inserts, internal newlines become spaces.
+ * KC1 (the multi-line composer): the buffer is FLAT — 0x0A is a stored
+ * code point in #chars, and the lines, the cursor's row/column and the
+ * visible window are all DERIVED per read (never a second mutable
+ * model, so every existing op — insert, kills, history stash, queue-pop
+ * replace, panel stash/restore — works unchanged). Bracketed paste
+ * (?2004h) unwraps and inserts its newlines LITERALLY; every newline
+ * source funnels through the ONE normalizer in feed() (§3).
  */
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
@@ -43,6 +48,11 @@ export declare class Editor {
     onEot(cb: () => void): void;
     onEscape(cb: () => void): void;
     onExpand(cb: () => void): void;
+    /** KC2 §2: the redirect chain — the gesture hands the buffer's text
+     *  over while the run is told to stop. Mirrors onEscape (a list, so
+     *  listeners can coexist); the line arrives already gone from the
+     *  composer, exactly as a submit's does. */
+    onRedirect(cb: (line: string) => void): void;
     /** W22: bind the pending-turn queue — the CLI's live slots. The ↑
      *  pop walks them (each pop leaves the queue, cancelling the turn);
      *  esc ends the walk after one more pop. */
@@ -50,11 +60,23 @@ export declare class Editor {
     /** The whole buffer as text (the CLI's line()/clearLine()). */
     line(): string;
     clearLine(): void;
-    /** The visible slice (dim "…" prefix when scrolled) + the cursor's
-     *  display column within it — the dock's input-row state. */
+    /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
+     *  their legacy meaning (the CURSOR LINE's visible slice and the
+     *  cursor's display column in it — a single-line buffer yields
+     *  today's exact values, and a legacy one-row consumer keeps
+     *  working), and the composer's own view rides beside them.
+     *
+     *  The window is DERIVED per read — no persistent #vscroll:
+     *  visibleStart = clamp(cursorLine − N_visible + 1, 0, lineCount −
+     *  N_visible), so it trails the cursor, can never hide it, and no
+     *  stash / restore / clear / submit path has new state to carry. A
+     *  dim "…" marks whichever edge hides rows. */
     dockState(): {
         line: string;
         cursor: number;
+        lines: string[];
+        cursorRow: number;
+        cursorCol: number;
     };
     /** v3 §04: the menu's visible state for the dock — null when closed. */
     menuState(): {

package/dist/editor.js

@@ -13,8 +13,13 @@
  * clusters (family emoji etc.) are not guaranteed perfect — each code
  * point counts as its width.
  *
- * The editor is a SINGLE line: bracketed paste (?2004h) unwraps and
- * inserts, internal newlines become spaces.
+ * KC1 (the multi-line composer): the buffer is FLAT — 0x0A is a stored
+ * code point in #chars, and the lines, the cursor's row/column and the
+ * visible window are all DERIVED per read (never a second mutable
+ * model, so every existing op — insert, kills, history stash, queue-pop
+ * replace, panel stash/restore — works unchanged). Bracketed paste
+ * (?2004h) unwraps and inserts its newlines LITERALLY; every newline
+ * source funnels through the ONE normalizer in feed() (§3).
  */
 import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 // the width primitives moved to width.ts (W1, the single width
@@ -36,6 +41,17 @@ export const MENU_ITEMS = [
     { name: "/status", desc: "show session id, event count, and context estimate" },
     { name: "/help", desc: "print this list of commands" },
 ];
+/** KC1 §3 — the newline code point. Every source (paste, Ctrl+J, the
+ *  Shift+Enter encodings, a CRLF pair) normalizes to exactly ONE. */
+const NEWLINE = 0x0a;
+/** KC1 §5 — the composer's CEILING (adjudication A1): at most 6 visible
+ *  rows. A ceiling only — N_visible clamps by the terminal's height so
+ *  the geometry stays legal down to the compositor's enter gate (H = 4
+ *  ⇒ one row, exactly today's minimum). */
+const N_MAX = 6;
+/** The dim "…" — the ONE truncation mark: the horizontal scroll's
+ *  prefix (unchanged) and the viewport's hidden-rows markers. */
+const ELLIPSIS = "\x1b[2m…\x1b[0m";
 /**
  * The editor. Raw mode + bracketed paste (?2004h) on enter, restored on
  * exit. The input row is rendered by `onRender` (the CLI wires it to the
@@ -46,7 +62,13 @@ export const MENU_ITEMS = [
 export class Editor {
     #chars = [];
     #cursor = 0;
-    #scroll = 0; // chars scrolled off the left (width-based reflow)
+    #scroll = 0; // chars scrolled off the left of the CURSOR'S LINE (width-based reflow; KC1: line-local, so a single-line buffer is unchanged)
+    // KC1 §2 — the ONE new ephemeral field: the desired column for the
+    // ↑/↓ walk (a long line's column 20 → a short line clamps to 5 → the
+    // next long line RETURNS to 20). Set on the first vertical move,
+    // kept across consecutive ones, reset by any horizontal move, insert
+    // or delete. Never stashed — it is a walk's state, not the buffer's.
+    #verticalGoalCol = null;
     #questionCb = null;
     // W21: the panel state machine — the approval/trust panel owns the
     // interaction while up: the digit/y/n/esc/tab routing, the rule
@@ -65,6 +87,12 @@ export class Editor {
     // (dispatch) coexist; a listener removes itself via an unarmed guard
     // (the compact's handler no-ops after its abort has fired).
     #escapeCbs = [];
+    // KC2 §2: the redirect LIST — mirrors #escapeCbs. The editor FORWARDS
+    // the gesture with the buffer's text; it never interprets it. What a
+    // redirect MEANS (abort the run, then run THIS ahead of the queue) is
+    // the CLI's — here it is only "these two keys, pressed together, hand
+    // the line over by a different door than Enter's".
+    #redirectCbs = [];
     // W15: the expand-key list (ctrl+r) — the CLI's dispatch decides the
     // target (a live cell toggles in place; a committed cell appends the
     // expanded block). Mirrors the escape list: multiple listeners can
@@ -122,6 +150,13 @@ export class Editor {
     onExpand(cb) {
         this.#expandCbs.push(cb);
     }
+    /** KC2 §2: the redirect chain — the gesture hands the buffer's text
+     *  over while the run is told to stop. Mirrors onEscape (a list, so
+     *  listeners can coexist); the line arrives already gone from the
+     *  composer, exactly as a submit's does. */
+    onRedirect(cb) {
+        this.#redirectCbs.push(cb);
+    }
     /** W22: bind the pending-turn queue — the CLI's live slots. The ↑
      *  pop walks them (each pop leaves the queue, cancelling the turn);
      *  esc ends the walk after one more pop. */
@@ -137,15 +172,86 @@ export class Editor {
         this.#chars = [];
         this.#cursor = 0;
         this.#scroll = 0;
+        this.#verticalGoalCol = null;
         this.#onRender();
     }
-    /** The visible slice (dim "…" prefix when scrolled) + the cursor's
-     *  display column within it — the dock's input-row state. */
+    // ---- KC1 §5: the DERIVED line model (the buffer stays FLAT) ----
+    /** The lines as [start, end) index pairs — the 0x0A itself EXCLUDED.
+     *  A buffer without a newline is exactly ONE line spanning the whole
+     *  buffer: today's shape, derived. */
+    #lineBounds() {
+        const out = [];
+        let start = 0;
+        for (let i = 0; i < this.#chars.length; i += 1) {
+            if (this.#chars[i] === NEWLINE) {
+                out.push({ start, end: i });
+                start = i + 1;
+            }
+        }
+        out.push({ start, end: this.#chars.length });
+        return out;
+    }
+    /** The cursor's line index — the first line whose end it has not
+     *  passed (a cursor resting ON a newline belongs to the line that
+     *  newline closes, never to the next one). */
+    #cursorLine(bounds) {
+        for (let i = 0; i < bounds.length; i += 1) {
+            if (this.#cursor <= bounds[i].end)
+                return i;
+        }
+        return bounds.length - 1;
+    }
+    /** The cursor's OWN line — the unit of the horizontal scroll and of
+     *  the line-local A/E/U/K (A3). */
+    #cursorBounds() {
+        const bounds = this.#lineBounds();
+        return bounds[this.#cursorLine(bounds)];
+    }
+    /** KC1 §5 — N_visible = min(lineCount, N_MAX, max(1, H − 3 − the
+     *  menu/queue bands)). The height clamp guarantees legal geometry
+     *  down to the compositor's enter gate; the compositor re-applies the
+     *  SAME formula against the frame's real bands (it alone knows their
+     *  folded row counts), so this is the editor's honest estimate and
+     *  the frame's clamp is the authority. */
+    #visibleRows(lineCount) {
+        const H = process.stdout.rows ?? 24;
+        const bands = (this.#menuOpen ? this.#menuFiltered().length : 0) + this.#queueState().length;
+        return Math.max(1, Math.min(lineCount, N_MAX, Math.max(1, H - 3 - bands)));
+    }
+    /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
+     *  their legacy meaning (the CURSOR LINE's visible slice and the
+     *  cursor's display column in it — a single-line buffer yields
+     *  today's exact values, and a legacy one-row consumer keeps
+     *  working), and the composer's own view rides beside them.
+     *
+     *  The window is DERIVED per read — no persistent #vscroll:
+     *  visibleStart = clamp(cursorLine − N_visible + 1, 0, lineCount −
+     *  N_visible), so it trails the cursor, can never hide it, and no
+     *  stash / restore / clear / submit path has new state to carry. A
+     *  dim "…" marks whichever edge hides rows. */
     dockState() {
-        const visible = String.fromCodePoint(...this.#chars.slice(this.#scroll));
-        const prefix = this.#scroll > 0 ? "\x1b[2m…\x1b[0m" : "";
-        const col = (this.#scroll > 0 ? 1 : 0) + widthOf(this.#chars.slice(this.#scroll, this.#cursor));
-        return { line: `${prefix}${visible}`, cursor: col };
+        const bounds = this.#lineBounds();
+        const cursorLine = this.#cursorLine(bounds);
+        const n = this.#visibleRows(bounds.length);
+        const first = Math.max(0, Math.min(cursorLine - n + 1, bounds.length - n));
+        const lines = [];
+        for (let i = first; i < first + n; i += 1) {
+            const b = bounds[i];
+            // the cursor's own row carries the horizontal scroll (and its
+            // "…"); the other rows render whole and cap at the frame's wall
+            const from = i === cursorLine ? b.start + this.#scroll : b.start;
+            const scrolled = i === cursorLine && this.#scroll > 0 ? ELLIPSIS : "";
+            const above = i === first && first > 0 ? ELLIPSIS : "";
+            const below = i === first + n - 1 && first + n < bounds.length ? ELLIPSIS : "";
+            lines.push(`${above}${scrolled}${String.fromCodePoint(...this.#chars.slice(from, b.end))}${below}`);
+        }
+        const cursorRow = cursorLine - first;
+        // the window trails the cursor, so the hidden-above marker can only
+        // share the cursor's row in the degenerate one-row window (a tiny
+        // terminal) — where it shifts the column like the scroll's does
+        const marks = (cursorRow === 0 && first > 0 ? 1 : 0) + (this.#scroll > 0 ? 1 : 0);
+        const cursorCol = marks + widthOf(this.#chars.slice(bounds[cursorLine].start + this.#scroll, this.#cursor));
+        return { line: lines[cursorRow], cursor: cursorCol, lines, cursorRow, cursorCol };
     }
     /** v3 §04: the menu's visible state for the dock — null when closed. */
     menuState() {
@@ -194,6 +300,7 @@ export class Editor {
         this.#chars = [];
         this.#cursor = 0;
         this.#scroll = 0;
+        this.#verticalGoalCol = null;
         this.#menuOpen = false;
         this.#menuSel = 0;
         this.#queuePopMode = false; // W22: the panel owns the keys while up
@@ -314,6 +421,17 @@ export class Editor {
                 else if (rest.startsWith("O")) {
                     i += 3; // SS3 (function keys) — ignored
                 }
+                else if (rest.startsWith("\x0d") && this.#composerIdle()) {
+                    // KC2 §2 — Alt+Enter. A terminal sends Alt+X as ESC and X in
+                    // ONE write, so SAME-CHUNK is the whole test: no timer, no
+                    // hold, nothing parked. The identical two bytes arriving in
+                    // SEPARATE chunks are NOT combined — they fall to the branch
+                    // below, where the bare Esc fires at once (its immediacy is
+                    // exactly what a hold would spend) and the next chunk's CR
+                    // submits: today's two gestures, untouched.
+                    this.#redirect();
+                    i += 2; // both bytes belong to the one gesture
+                }
                 else if (this.#menuOpen) {
                     // v3 §04: Esc closes the menu and clears the buffer.
                     // CA-4: the closing esc consumes its burst (the `i += 1`
@@ -321,6 +439,7 @@ export class Editor {
                     this.#chars = [];
                     this.#cursor = 0;
                     this.#scroll = 0;
+                    this.#verticalGoalCol = null;
                     this.#refreshMenu();
                     i += 1;
                 }
@@ -350,13 +469,27 @@ export class Editor {
                 }
             }
             else if (c === "\x0d" || c === "\x0a") {
-                if (this.#pasting) {
-                    this.#insert(0x20); // single-line editor: newlines become spaces
+                // KC1 §3 — the ONE newline normalizer. Inside a paste every
+                // boundary (LF, CR, CRLF) becomes EXACTLY one 0x0A; a paste's
+                // trailing CR at a CHUNK boundary parks in #pending (the
+                // existing CSI-resume mechanism) and resolves against the next
+                // chunk's leading LF, so a CR|LF pair split by the stdin read
+                // is still ONE newline. Outside a paste: Ctrl+J (LF) inserts,
+                // Enter (CR) submits — and a typed CRLF pair submits ONCE (the
+                // LF is consumed with it, never landing in the fresh buffer).
+                // A lone interactive CR never parks: the submit is immediate.
+                if (c === "\x0d" && i + 1 === text.length && this.#pasting) {
+                    this.#pending = text.slice(i);
+                    break;
+                }
+                const consumed = c === "\x0d" && text[i + 1] === "\x0a" ? 2 : 1;
+                if (this.#pasting || c === "\x0a") {
+                    this.#insert(NEWLINE);
                 }
                 else {
                     this.#submit();
                 }
-                i += 1;
+                i += consumed;
             }
             else if (c === "\x7f" || c === "\x08") {
                 this.#backspace();
@@ -383,13 +516,13 @@ export class Editor {
                 i += 1;
             }
             else if (c === "\x01") {
-                this.#cursor = 0;
+                this.#cursor = this.#cursorBounds().start; // A3: line-local (a single line starts at 0 — unchanged)
                 this.#reflow();
                 this.#onRender();
                 i += 1;
             }
             else if (c === "\x05") {
-                this.#cursor = this.#chars.length;
+                this.#cursor = this.#cursorBounds().end; // A3: line-local (a single line ends at the buffer's end)
                 this.#reflow();
                 this.#onRender();
                 i += 1;
@@ -423,6 +556,27 @@ export class Editor {
         }
     }
     #csi(params, final) {
+        // KC1 §4 — Shift+Enter WHERE THE TERMINAL ENCODES IT: kitty's
+        // CSI-u (ESC [ 13;2 u) and xterm's modifyOtherKeys (ESC [ 27;2;13 ~).
+        // Never claimed universal — Ctrl+J is the everywhere baseline; a
+        // terminal that sends neither simply never reaches this row. The
+        // chunk-split safety is the existing #pending CSI resume.
+        if ((final === "u" && params === "13;2") || (final === "~" && params === "27;2;13")) {
+            this.#insert(NEWLINE);
+            return;
+        }
+        // KC2 §2 — Ctrl+Enter, the SAME two encodings with modifier 5
+        // (1 + ctrl): kitty's CSI-u and xterm's modifyOtherKeys. Never
+        // claimed universal — a terminal that encodes neither sends a plain
+        // CR, which is an ordinary submit/queue (the safe degrade). The
+        // chunk-split safety is the existing #pending CSI resume, shared
+        // with Shift+Enter above. Outside the normal composer state the
+        // sequence is simply unknown, exactly like any other stray CSI.
+        if ((final === "u" && params === "13;5") || (final === "~" && params === "27;5;13")) {
+            if (this.#composerIdle())
+                this.#redirect();
+            return;
+        }
         if (final === "~") {
             const n = Number(params);
             if (n === 3)
@@ -450,6 +604,13 @@ export class Editor {
                 else
                     this.#menuSel = Math.min(this.#menuFiltered().length - 1, this.#menuSel + 1);
             }
+            else if (this.#chars.includes(NEWLINE)) {
+                // KC1 §4: a MULTI-LINE buffer's ↑↓ walk its lines. The
+                // history and the queue-pop below stay gated on an EMPTY
+                // buffer — a multi-line buffer is never empty, so the
+                // precedence can only ever add, never take.
+                this.#verticalMove(final === "A" ? -1 : 1);
+            }
             else if (final === "A" && this.#queuePop !== null && (this.#queuePopMode || this.line() === "") && this.#queueState().length > 0) {
                 // W22: ↑ pops the LAST queued message into the buffer — the
                 // walk: repeated presses pop older ones (each replaces the
@@ -471,14 +632,32 @@ export class Editor {
             this.#move(1);
         }
         else if (final === "H") {
-            this.#cursor = 0;
+            this.#cursor = this.#cursorBounds().start; // A3: Home follows Ctrl+A — line-local
             this.#reflow();
         }
         else if (final === "F") {
-            this.#cursor = this.#chars.length;
+            this.#cursor = this.#cursorBounds().end; // A3: End follows Ctrl+E — line-local
             this.#reflow();
         }
     }
+    /** KC1 §4 — the ↑/↓ walk. The cursor keeps its DESIRED column across
+     *  a short line: the goal is captured at the FIRST vertical move and
+     *  survives consecutive ones (#reflow clears it, so any horizontal
+     *  move / insert / delete ends the walk); a step past either end
+     *  stays put. */
+    #verticalMove(delta) {
+        const bounds = this.#lineBounds();
+        const cur = this.#cursorLine(bounds);
+        const next = cur + delta;
+        if (next < 0 || next >= bounds.length)
+            return;
+        const from = bounds[cur];
+        const goal = this.#verticalGoalCol ?? widthOf(this.#chars.slice(from.start, this.#cursor));
+        const to = bounds[next];
+        this.#cursor = this.#indexAtWidth(to.start, to.end, goal);
+        this.#reflow();
+        this.#verticalGoalCol = goal; // the walk re-arms it (the reflow's reset is for every OTHER key)
+    }
     // ---- W21: the panel state machine ----
     #panelSelect(sel) {
         const panel = this.#panel;
@@ -498,6 +677,7 @@ export class Editor {
         this.#chars = [...panel.view.name].map((ch) => ch.codePointAt(0));
         this.#cursor = this.#chars.length;
         this.#scroll = 0;
+        this.#verticalGoalCol = null;
         this.#onRender();
     }
     /** tab — the amend phase on the selected option (yes/deny); the
@@ -511,6 +691,7 @@ export class Editor {
         this.#chars = [];
         this.#cursor = 0;
         this.#scroll = 0;
+        this.#verticalGoalCol = null;
         this.#onRender();
     }
     /** esc — back out of the rule/amend to the options (the buffer
@@ -525,6 +706,7 @@ export class Editor {
             this.#chars = [];
             this.#cursor = 0;
             this.#scroll = 0;
+            this.#verticalGoalCol = null;
             this.#onRender();
             return;
         }
@@ -610,18 +792,23 @@ export class Editor {
             this.#onRender();
     }
     #killToStart() {
-        this.#chars.splice(0, this.#cursor);
-        this.#cursor = 0;
+        const { start } = this.#cursorBounds(); // A3: line-local (0 on a single line — unchanged)
+        this.#chars.splice(start, this.#cursor - start);
+        this.#cursor = start;
         this.#reflow();
         if (!this.#pasting)
             this.#onRender();
     }
     #killToEnd() {
-        this.#chars.length = this.#cursor;
+        const { end } = this.#cursorBounds(); // A3: line-local (the buffer's end on a single line — unchanged)
+        this.#chars.splice(this.#cursor, end - this.#cursor);
         this.#reflow();
         if (!this.#pasting)
             this.#onRender();
     }
+    /** Ctrl+W — the word kill. The newline rides as a non-space code
+     *  point (a kill at a line's start joins it to the one above, the
+     *  readline behavior); A3 scopes A/E/U/K, not W. */
     #killWord() {
         let i = this.#cursor;
         while (i > 0 && this.#chars[i - 1] === 0x20)
@@ -632,8 +819,76 @@ export class Editor {
         this.#cursor = i;
         this.#reflow();
     }
+    /** KC1/KC2 — the buffer LEAVES: the flat chars, the cursor, the
+     *  horizontal scroll, the ↑/↓ goal, the menu and the pop-walk all
+     *  reset together (W22: a departing line ends the pop-walk, so the
+     *  next esc at rest interrupts again). Shared by the submit and the
+     *  redirect — the two doors a line can leave by. */
+    #takeLine() {
+        const line = String.fromCodePoint(...this.#chars);
+        this.#chars = [];
+        this.#cursor = 0;
+        this.#scroll = 0;
+        this.#verticalGoalCol = null;
+        this.#menuOpen = false;
+        this.#menuSel = 0;
+        this.#queuePopMode = false;
+        return line;
+    }
+    /** A2: the history remembers submitted TURN lines — never question
+     *  answers, never empties; adjacent duplicates collapse, the tail
+     *  caps at 100. A redirect is a turn, so it is remembered too. */
+    #remember(line) {
+        if (this.#history[this.#history.length - 1] !== line)
+            this.#history.push(line);
+        if (this.#history.length > 100)
+            this.#history.shift();
+    }
+    /** KC2 §2 — the NORMAL composer state: the redirect gesture is live
+     *  ONLY here. The approval panel, the slash menu, the history browse
+     *  and the queue-pop walk each OWN their keys first (the W21 "the
+     *  panel owns the keys" design, restated as a gate); a pending
+     *  question is the panel's dock-less twin (askPanel routes to
+     *  question() when the dock cannot render, so the ask owns the keys
+     *  there too); and a bracketed paste is literal TEXT, where an ESC CR
+     *  is the pasted content's own bytes and never a keypress. In every
+     *  one of those states the two bytes fall through to today's
+     *  handling — two gestures, unchanged. */
+    #composerIdle() {
+        return (this.#panel === null &&
+            !this.#menuOpen &&
+            this.#historyIdx === null &&
+            !this.#queuePopMode &&
+            !this.#pasting &&
+            this.#questionCb === null);
+    }
+    /**
+     * KC2 §2 — the gesture's meaning, kept as small as it can honestly be.
+     *
+     * An EMPTY buffer carries no correction, so the gesture degenerates to
+     * the bare Esc: the abort alone, nothing submitted. With text, the
+     * line leaves exactly as a submit's does and the listeners decide (the
+     * CLI aborts a live run and front-jumps the correction; idle, it is
+     * simply an Enter). UNWIRED — the recovery flow never binds it — the
+     * gesture IS a submit: a line is never lost to a missing binding.
+     */
+    #redirect() {
+        if (this.#chars.length === 0) {
+            for (const cb of [...this.#escapeCbs])
+                cb();
+            return;
+        }
+        if (this.#redirectCbs.length === 0) {
+            this.#submit();
+            return;
+        }
+        const line = this.#takeLine();
+        this.#remember(line);
+        for (const cb of [...this.#redirectCbs])
+            cb(line);
+        this.#onRender();
+    }
     #submit() {
-        let line = String.fromCodePoint(...this.#chars);
         if (this.#menuOpen) {
             // A1 (the feel): Enter submits the EXACT selection directly; a
             // PARTIAL selection COMPLETES the buffer (the Tab semantics)
@@ -641,7 +896,7 @@ export class Editor {
             // again. The old behavior executed the completed command on
             // the first Enter, before the user had seen the completion.
             const m = this.#menuFiltered()[this.#menuSel];
-            if (m !== undefined && m.name !== line) {
+            if (m !== undefined && m.name !== this.line()) {
                 this.#chars = [...m.name].map((ch) => ch.codePointAt(0));
                 this.#cursor = this.#chars.length;
                 this.#reflow();
@@ -650,12 +905,7 @@ export class Editor {
                 return; // completed, not executed
             }
         }
-        this.#chars = [];
-        this.#cursor = 0;
-        this.#scroll = 0;
-        this.#menuOpen = false;
-        this.#menuSel = 0;
-        this.#queuePopMode = false; // W22: a submit ends the pop-walk — the next esc at rest interrupts again
+        const line = this.#takeLine();
         const cb = this.#questionCb;
         this.#questionCb = null;
         if (cb !== null) {
@@ -667,14 +917,8 @@ export class Editor {
         else {
             this.#pendingLines.push(line); // nobody wired yet — hold it
         }
-        // A2: the history remembers submitted TURN lines — never question
-        // answers, never empties; adjacent duplicates collapse.
-        if (cb === null && line !== "") {
-            if (this.#history[this.#history.length - 1] !== line)
-                this.#history.push(line);
-            if (this.#history.length > 100)
-                this.#history.shift();
-        }
+        if (cb === null && line !== "")
+            this.#remember(line);
         this.#onRender();
     }
     /** A2: step the history browse; a delta past the newest exits back to
@@ -716,10 +960,14 @@ export class Editor {
         this.#chars = [...line].map((ch) => ch.codePointAt(0));
         this.#cursor = this.#chars.length;
         this.#scroll = 0;
+        this.#verticalGoalCol = null;
         this.#onRender();
     }
     // ---- width-based horizontal scroll ----
     #reflow() {
+        // KC1: any key that reaches the reflow ended a ↑/↓ walk (the walk
+        // itself re-arms the goal right after its own reflow call).
+        this.#verticalGoalCol = null;
         const W = (process.stdout.columns ?? 0) || 80; // degenerate 0 falls back to 80
         // W21: the panel's phase lead owns the input row while up — the
         // line's max width follows the lead (the rule/amend leads are
@@ -730,22 +978,30 @@ export class Editor {
         const lead = this.#panel !== null ? panelLead(this.#panel.view, this.#panel.phase, this.#panel.sel) : PROMPT;
         const leadW = leadWidth(lead);
         const maxW = Math.max(1, W - leadW - 4); // W6: the box's walls (2+2) — the visible line fits the box's inner width; the "…" rides inside
-        const curCol = widthOf(this.#chars.slice(0, this.#cursor));
-        const scrolledW = widthOf(this.#chars.slice(0, this.#scroll));
+        // KC1: the scroll is the CURSOR LINE's own offset — a single-line
+        // buffer's line starts at 0, so the math is today's exactly. The
+        // clamp catches a walk onto a line SHORTER than the old offset.
+        const { start, end } = this.#cursorBounds();
+        this.#scroll = Math.min(this.#scroll, end - start);
+        const curCol = widthOf(this.#chars.slice(start, this.#cursor));
+        const scrolledW = widthOf(this.#chars.slice(start, start + this.#scroll));
         if (curCol < scrolledW) {
-            this.#scroll = this.#indexAtWidth(curCol);
+            this.#scroll = this.#indexAtWidth(start, end, curCol) - start;
         }
         else if (curCol >= scrolledW + maxW) {
-            this.#scroll = this.#indexAtWidth(Math.max(0, curCol - maxW + 1));
+            this.#scroll = this.#indexAtWidth(start, end, Math.max(0, curCol - maxW + 1)) - start;
         }
     }
-    #indexAtWidth(target) {
+    /** The first index in [start, end] whose display width from `start`
+     *  reaches `target` — the width-based column walk (a wide char never
+     *  splits: the index lands BEFORE it). */
+    #indexAtWidth(start, end, target) {
         let w = 0;
-        for (let i = 0; i < this.#chars.length; i += 1) {
+        for (let i = start; i < end; i += 1) {
             if (w >= target)
                 return i;
             w += charWidth(this.#chars[i]);
         }
-        return this.#chars.length;
+        return end;
     }
 }

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export { Container, foldLine, visibleWidth, SPINNER, type Component, type FrameC
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type PathResolver, type RecapStats, type ResumeMeta, type RenderInput, type RenderResult, type RunUsage, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
+export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";

package/dist/index.js

@@ -14,3 +14,6 @@ export { Container, foldLine, visibleWidth, SPINNER } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
+// KC2 §5: the status rows' formatters — the CLI keeps the state and the
+// repaint, the terminal layer owns what the row says.
+export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";

package/dist/status.d.ts

@@ -0,0 +1,38 @@
+/**
+ * KC2 §5 — the status line's FORMATTERS, extracted from the CLI (the
+ * ADR-0041 escape hatch: extraction, never a fifth raise). The split is
+ * the one the ADR names: the CLI keeps the STATE (the rotating glyph,
+ * the run's start instant, the live usage, whether the dock is up) and
+ * the REPAINT; what a status row SAYS is presentation, and presentation
+ * belongs to the terminal layer.
+ *
+ * Two callers built these rows independently before the move — chat's
+ * REPL and the recovery flow — with the running row duplicated verbatim
+ * in both. One definition now serves both, and the tier stays a
+ * PARAMETER precisely because the two callers disagree on it (chat
+ * spells plan's read-only posture out per W19, the recovery flow prints
+ * the bare mode): the extraction must not silently unify a difference it
+ * was not asked to settle.
+ *
+ * The rows are byte-for-byte what the CLI built before the move — the
+ * v2b/v3 §03 shapes the e2e transcripts pin by substring — with ONE
+ * deliberate exception: the running row's interrupt hint, which KC2 §2
+ * widens to name the new gesture.
+ */
+/** v3 §03/§05 — the working glyph family; the CLI's 200ms spinner walks
+ *  it and hands each glyph back to `runningStatus`. */
+export declare const STATUS_GLYPHS: readonly ["▖", "▘", "▝", "▗"];
+/**
+ * The RUNNING row: the rotating glyph, the wall seconds since `since`
+ * (never below 1 — a run that just started still reads "1s", so the row
+ * never claims a turn took no time), the streamed output tokens once the
+ * count is known, the interrupt hints, and the live ctx estimate.
+ *
+ * KC2 §2: the hint names BOTH gestures. Esc still stops; alt+⏎ redirects
+ * — stop, and do THIS instead. The row is where the gesture is taught,
+ * because it is on screen exactly when the gesture is useful.
+ */
+export declare function runningStatus(glyph: string, since: number, outTokens: number | null, ctxRatio: number): string;
+/** The IDLE row: the approval tier as the CALLER names it, the /mode
+ *  hint, the model driving the session, and the ctx estimate. */
+export declare function idleStatus(tier: string, model: string, ctxRatio: number): string;

package/dist/status.js

@@ -0,0 +1,52 @@
+/**
+ * KC2 §5 — the status line's FORMATTERS, extracted from the CLI (the
+ * ADR-0041 escape hatch: extraction, never a fifth raise). The split is
+ * the one the ADR names: the CLI keeps the STATE (the rotating glyph,
+ * the run's start instant, the live usage, whether the dock is up) and
+ * the REPAINT; what a status row SAYS is presentation, and presentation
+ * belongs to the terminal layer.
+ *
+ * Two callers built these rows independently before the move — chat's
+ * REPL and the recovery flow — with the running row duplicated verbatim
+ * in both. One definition now serves both, and the tier stays a
+ * PARAMETER precisely because the two callers disagree on it (chat
+ * spells plan's read-only posture out per W19, the recovery flow prints
+ * the bare mode): the extraction must not silently unify a difference it
+ * was not asked to settle.
+ *
+ * The rows are byte-for-byte what the CLI built before the move — the
+ * v2b/v3 §03 shapes the e2e transcripts pin by substring — with ONE
+ * deliberate exception: the running row's interrupt hint, which KC2 §2
+ * widens to name the new gesture.
+ */
+import { kUnit } from "./render.js";
+/** v3 §03/§05 — the working glyph family; the CLI's 200ms spinner walks
+ *  it and hands each glyph back to `runningStatus`. */
+export const STATUS_GLYPHS = ["▖", "▘", "▝", "▗"];
+/** The ~ctx estimate as the whole-percent LEFT. A non-finite ratio (no
+ *  window, no estimate) yields null and the row prints "~null%" — the
+ *  long-standing shape, kept on purpose: an honest null beats an
+ *  invented percentage. */
+function ctxLeft(ratio) {
+    return Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
+}
+/**
+ * The RUNNING row: the rotating glyph, the wall seconds since `since`
+ * (never below 1 — a run that just started still reads "1s", so the row
+ * never claims a turn took no time), the streamed output tokens once the
+ * count is known, the interrupt hints, and the live ctx estimate.
+ *
+ * KC2 §2: the hint names BOTH gestures. Esc still stops; alt+⏎ redirects
+ * — stop, and do THIS instead. The row is where the gesture is taught,
+ * because it is on screen exactly when the gesture is useful.
+ */
+export function runningStatus(glyph, since, outTokens, ctxRatio) {
+    const out = outTokens !== null ? ` ↓ ${kUnit(outTokens)} tokens` : "";
+    const seconds = Math.max(1, Math.round((Date.now() - since) / 1000));
+    return `${glyph} working ${seconds}s${out} · esc stop · alt+⏎ redirect · ctx left ~${ctxLeft(ctxRatio)}%`;
+}
+/** The IDLE row: the approval tier as the CALLER names it, the /mode
+ *  hint, the model driving the session, and the ctx estimate. */
+export function idleStatus(tier, model, ctxRatio) {
+    return `▸ ${tier} · /mode to switch · ${model} · ctx left ~${ctxLeft(ctxRatio)}%`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "kiso tui — the pure terminal layer (cell renderer, dock, raw editor, diff, palette). Zero runtime dependencies: input is data, output is bytes.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,6 @@
   },
   "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/tui#readme",
   "dependencies": {
-    "@vincemakes/kiso-tui-cells": "0.2.0"
+    "@vincemakes/kiso-tui-cells": "0.6.0"
   }
 }