@vincemakes/kiso-tui 0.2.0 → 0.5.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 };
@@ -50,11 +55,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
@@ -137,15 +159,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 +287,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
@@ -321,6 +415,7 @@ export class Editor {
                     this.#chars = [];
                     this.#cursor = 0;
                     this.#scroll = 0;
+                    this.#verticalGoalCol = null;
                     this.#refreshMenu();
                     i += 1;
                 }
@@ -350,13 +445,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 +492,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 +532,15 @@ 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;
+        }
         if (final === "~") {
             const n = Number(params);
             if (n === 3)
@@ -450,6 +568,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 +596,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 +641,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 +655,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 +670,7 @@ export class Editor {
             this.#chars = [];
             this.#cursor = 0;
             this.#scroll = 0;
+            this.#verticalGoalCol = null;
             this.#onRender();
             return;
         }
@@ -610,18 +756,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)
@@ -653,6 +804,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: a submit ends the pop-walk — the next esc at rest interrupts again
@@ -716,10 +868,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 +886,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui",
-  "version": "0.2.0",
+  "version": "0.5.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.5.0"
   }
 }