@vincemakes/kiso-tui 0.15.9 → 0.15.11

package/dist/compositor.d.ts

@@ -212,6 +212,32 @@ export declare class Body {
      *  live region's first row) — NEVER at the formula's committed-count
      *  top: external writes (the CLI's console.error CRLF) can shift the
      *  committed content down, and a formula-top ED0 would clear it. */
+    /**
+     * REL-0152-D18 — a window DRAG is one resize, not forty.
+     *
+     * SIGWINCH fires continuously while a drag is in progress — every few
+     * pixels is another signal — and this used to answer each one at once
+     * with an erase and a full repaint. A real terminal REFLOWS on a width
+     * change and pushes the rows it displaces into its scrollback, so
+     * every one of those repaints deposited another copy of the screen
+     * into the history. The owner's two-second drag left six identical
+     * copies of the same tool block in the transcript.
+     *
+     * Nothing clever can undo that afterwards: the scrollback is not ours
+     * to rewrite. The only fix is to not paint into the middle of a drag.
+     *
+     * The geometry is adopted IMMEDIATELY — every cap and bound is read
+     * from `#opts` at frame time, so the model is already at the new size
+     * and nothing is computed against a stale width. What waits is the
+     * PAINT. When the signals stop, one erase and one repaint.
+     *
+     * The competitor does not have this problem, for a structural reason
+     * worth naming rather than envying: it runs on the alternate screen,
+     * which has no scrollback to accumulate into. kiso is on the primary
+     * screen deliberately — the transcript IS the terminal's own
+     * scrollback, which is the product's whole claim — so it pays for
+     * that choice here, and has to pay carefully.
+     */
     onResize(): void;
     /** W18: the status row's right-aligned hint is part of the status
      *  state — the compacting row passes "esc to cancel" (the affordance

package/dist/compositor.js

@@ -64,6 +64,10 @@ const SPINNER_MS = 200; // the spinner cadence — a ONE-SHOT re-armed on demand
 /** REL-0152-R1: a held row that has never been painted, so the first
  *  frame writes every row rather than trusting an empty string. */
 const NOT_PAINTED = "\u0000never";
+/** REL-0152-D18 — how long a drag has to be quiet before it is over.
+ *  Long enough that a continuous drag never crosses it, short enough
+ *  that a single resize still feels immediate. */
+const RESIZE_SETTLE_MS = 80;
 const CHROME_ROWS = 4; // box top + input + box bottom + status — the design §03 chrome (V6-3; the box is W6)
 /** W20 — the whole-table-replace comparison: the live task block only
  *  redraws when the items actually changed (the task extension's
@@ -141,6 +145,11 @@ export class Body {
     #scrolledOff = 0;
     /** REL-0152-R1: this frame is the repaint after a SIGWINCH. */
     #resizeFrame = false;
+    /** REL-0152-D18: a drag's signals are still arriving. */
+    #resizePending = false;
+    /** REL-0152-D19: the inherited terminal has not been released yet. */
+    #needsReset = false;
+    #resizeTimer = null;
     #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
@@ -868,6 +877,42 @@ export class Body {
             return;
         this.#docked = true;
         this.#guardOutput();
+        // REL-0152-D19: RELEASE the terminal we were handed, before the
+        // first frame.
+        //
+        // The dock resets on the way OUT and reset nothing on the way IN,
+        // so every session began in whatever state the previous occupant
+        // left. For THIS product that is not an edge case: kiso's claim is
+        // that it survives kill -9, which makes "the last instance died
+        // without running its teardown" a supported and advertised way to
+        // arrive here.
+        //
+        // Both of these confine writes to a SUB-REGION of the screen,
+        // which is the only way content can survive at a column the dock
+        // paints — every chrome row is exactly W wide and written from
+        // column 1, so an erase plus a W-wide write covers the row end to
+        // end unless the write cannot reach the ends.
+        //
+        //   ESC[r     the scroll region back to the whole screen
+        //   ESC[?69l  left/right margin mode OFF (DECLRMM) — ESC[r does
+        //             NOT release margins, which is why resetting only the
+        //             region on exit was never enough
+        //
+        // And two that a KILLED kiso leaves set, which REL-0152-D14
+        // introduced and this is the first thing to defend against it: a
+        // frame turns autowrap off and the cursor invisible and restores
+        // both at its end, so a process that dies BETWEEN those two points
+        // hands the shell — and the next kiso — a terminal with wrapping
+        // off and no cursor. `kill -9` cannot be caught, so the entry is
+        // the only place this can be repaired, and a product whose claim
+        // is that it survives kill -9 has to repair it there.
+        //
+        //   ESC[?7h   autowrap back to its default
+        //   ESC[?25h  the cursor visible again
+        //
+        // Idempotent, sixteen bytes, once per session, and correct whether
+        // or not anything was actually left set.
+        this.#needsReset = true;
         this.#attachResize();
         this.#fullRedraw = true;
         this.#dirty = true;
@@ -877,6 +922,13 @@ export class Body {
      *  chrome rows cleared, the cursor home at the input line. */
     exit() {
         this.#unguard?.();
+        // REL-0152-D18: a drag in flight must not repaint into a torn-down
+        // dock — the timer outlives the compositor otherwise.
+        if (this.#resizeTimer !== null) {
+            clearTimeout(this.#resizeTimer);
+            this.#resizeTimer = null;
+        }
+        this.#resizePending = false;
         // TUI2-R3v2 ②: the mouse disable rides the SAME teardown as CSI r,
         // and rides it BEFORE the docked guard — an un-docked compositor is
         // exactly the state a superseded or half-torn-down one is in, and
@@ -1001,9 +1053,50 @@ export class Body {
      *  live region's first row) — NEVER at the formula's committed-count
      *  top: external writes (the CLI's console.error CRLF) can shift the
      *  committed content down, and a formula-top ED0 would clear it. */
+    /**
+     * REL-0152-D18 — a window DRAG is one resize, not forty.
+     *
+     * SIGWINCH fires continuously while a drag is in progress — every few
+     * pixels is another signal — and this used to answer each one at once
+     * with an erase and a full repaint. A real terminal REFLOWS on a width
+     * change and pushes the rows it displaces into its scrollback, so
+     * every one of those repaints deposited another copy of the screen
+     * into the history. The owner's two-second drag left six identical
+     * copies of the same tool block in the transcript.
+     *
+     * Nothing clever can undo that afterwards: the scrollback is not ours
+     * to rewrite. The only fix is to not paint into the middle of a drag.
+     *
+     * The geometry is adopted IMMEDIATELY — every cap and bound is read
+     * from `#opts` at frame time, so the model is already at the new size
+     * and nothing is computed against a stale width. What waits is the
+     * PAINT. When the signals stop, one erase and one repaint.
+     *
+     * The competitor does not have this problem, for a structural reason
+     * worth naming rather than envying: it runs on the alternate screen,
+     * which has no scrollback to accumulate into. kiso is on the primary
+     * screen deliberately — the transcript IS the terminal's own
+     * scrollback, which is the product's whole claim — so it pays for
+     * that choice here, and has to pay carefully.
+     */
     onResize() {
         if (!this.#isActive())
             return;
+        this.#resizePending = true;
+        if (this.#resizeTimer !== null)
+            clearTimeout(this.#resizeTimer);
+        this.#resizeTimer = setTimeout(() => {
+            this.#resizeTimer = null;
+            this.#settleResize();
+        }, RESIZE_SETTLE_MS);
+        if (this.#resizeTimer.unref !== undefined)
+            this.#resizeTimer.unref();
+    }
+    /** The one repaint a drag earns, once its signals have stopped. */
+    #settleResize() {
+        if (!this.#resizePending || !this.#isActive())
+            return;
+        this.#resizePending = false;
         const H = this.#opts.height();
         const liveRows = this.#lastLiveRows > 0 ? this.#lastLiveRows : 3;
         const from = Math.max(1, (this.#lastH > 0 ? this.#lastH : H) - liveRows + 1);
@@ -1011,7 +1104,7 @@ export class Body {
         this.#fullRedraw = true;
         this.#resizeFrame = true;
         this.#dirty = true;
-        this.render(); // the immediate redraw at the NEW geometry
+        this.render();
     }
     /** W18: the status row's right-aligned hint is part of the status
      *  state — the compacting row passes "esc to cancel" (the affordance
@@ -1373,6 +1466,32 @@ export class Body {
         // Restored at the end of every frame: prose written OUTSIDE a
         // frame (bodyLog, an error) is ordinary output and must still
         // wrap, and the shell inherits the terminal when kiso exits.
+        if (this.#needsReset) {
+            // REL-0152-D19: released as the FIRST bytes of the FIRST frame
+            // rather than as a write of its own. A separate write would be
+            // one more thing between the dock coming up and its first
+            // frame, and the PTY gates that wait on the boot stream feel
+            // it; inside the frame it is four sequences and no new event.
+            this.#needsReset = false;
+            out.push("\x1b[r\x1b[?69l\x1b[?7h\x1b[?25h");
+            // REL-0152-D20 — the mechanism is understood and the obvious fix
+            // is NOT taken here. See the finding.
+            //
+            // The first frame addresses rows 1..H absolutely and draws over
+            // whatever the terminal was showing. Scrolling a screenful away
+            // first would fix that, and it was built and measured: it pushes
+            // up to H BLANK rows into the scrollback, and TUI2-R2pre's
+            // blank-share gate went from 14/43 to 29/43 — past the "a
+            // healthy session's scrollback is mostly content" invariant that
+            // gate exists to hold. Trading a symptom with a five-second
+            // user-side setting for a broken invariant is a worse deal.
+            //
+            // The correct version scrolls only as far as the terminal's
+            // content actually reaches, which needs a cursor-position query
+            // at boot — its own round, with its own risk (this file already
+            // declined a boot-time round-trip once, for racing the editor
+            // for stdin).
+        }
         out.push("\x1b[?7l");
         out.push(this.#conservative ? "\x1b[?25l" : "\x1b[?2026h"); // D1: sync ON, or cursor-hide where 2026 is dead bytes
         // A8: the bottom-anchored window (the model's last H rows) shifts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui",
-	"version": "0.15.9",
+	"version": "0.15.11",
 	"description": "kiso tui \u2014 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.15.9"
+		"@vincemakes/kiso-tui-cells": "0.15.11"
 	}
 }