@vincemakes/kiso-tui 0.15.8 → 0.15.10

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
@@ -867,7 +876,43 @@ export class Body {
         if (process.stdout.isTTY !== true || palette().bold === "" || rows < 4)
             return;
         this.#docked = true;
-        this.#guardStdout();
+        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
@@ -936,26 +988,56 @@ export class Body {
      * change, and the cursor parks on the wrong row. Three PTY gates
      * caught it.
      *
-     * The fix is not a list of writers to remember. stdout is wrapped
-     * while the dock is up: anything written that is not this frame's own
-     * bytes forgets the screen, and the next frame repaints. New callers
-     * cannot get it wrong because they are not asked to get it right.
+     * REL-0152-D17: BOTH descriptors, and the second one is the one that
+     * mattered. The first version of this guard wrapped stdout alone,
+     * while kiso's degradation notices go to stderr through
+     * `console.error` — and several of them BEGIN with `[` and contain
+     * `]`:
+     *
+     *     [extensions] …        [project .kiso] …
+     *     [KISO_FAUX_SCRIPT] …  [run failed] …
+     *
+     * Those land on the tty wherever the cursor is, and a renderer that
+     * does not know they were printed skips exactly the rows that would
+     * repair them. The residue survives on the rows whose desired content
+     * NEVER changes — the composer box's own edges — which is a stray `[`
+     * at the left and `]` at the right for the rest of the session,
+     * clearing only on a resize and returning on the next launch.
+     *
+     * The reasoning that missed it was mine, and it is worth keeping: the
+     * renderer emits no OSC and no bare `]`, so a `]` on screen CANNOT
+     * have come from its stream. I had that fact and concluded "therefore
+     * the terminal invents it" when the only sound conclusion is
+     * "therefore something else wrote it".
+     *
+     * The fix is not a list of writers to remember, and not silencing the
+     * loggers. A compositor cannot hold a belief about a terminal it does
+     * not own: any write it did not make forgets the screen, whichever
+     * descriptor carried it. New callers cannot get it wrong because they
+     * are not asked to get it right.
      */
-    #guardStdout() {
+    #guardOutput() {
         if (this.#unguard !== null || this.#opts.write !== undefined)
             return;
-        const real = process.stdout.write.bind(process.stdout);
-        const patched = ((chunk, ...rest) => {
-            if (!this.#inFrame)
-                this.#screen = [];
-            return real(chunk, ...rest);
-        });
-        process.stdout.write = patched;
+        const restores = [];
+        for (const stream of [process.stdout, process.stderr]) {
+            const real = stream.write.bind(stream);
+            const patched = ((chunk, ...rest) => {
+                if (!this.#inFrame)
+                    this.#screen = [];
+                return real(chunk, ...rest);
+            });
+            stream.write = patched;
+            restores.push(() => {
+                // only restore what we installed — another wrapper may have
+                // been layered on top since (the byte trace does exactly that)
+                if (stream.write === patched)
+                    stream.write = real;
+            });
+        }
         this.#unguard = () => {
-            // only restore what we installed — another wrapper may have
-            // been layered on top since (the byte trace does exactly that)
-            if (process.stdout.write === patched)
-                process.stdout.write = real;
+            for (const r of restores)
+                r();
             this.#unguard = null;
         };
     }
@@ -971,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);
@@ -981,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
@@ -1343,6 +1466,15 @@ 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");
+        }
         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/dist/editor.d.ts

@@ -72,6 +72,10 @@ export declare class Editor {
      *  human asks for them — ctrl+V, or an empty paste. The CLI owns the
      *  platform, the editor owns the moment. */
     onClipboardPaste(cb: () => string | null): void;
+    /** REL-0152-D16: the files this line's `[Image #N]` capsules stand
+     *  for, by their number. The CLI resolves them when it builds the
+     *  turn; a capsule the human deleted is simply never looked up. */
+    attachments(): Map<number, string>;
     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);

package/dist/editor.js

@@ -131,6 +131,24 @@ export class Editor {
      * every entry is text they chose to paste and may still submit.
      */
     #pastes = new Map();
+    /**
+     * REL-0152-D16 — which file each `[Image #N]` capsule stands for.
+     *
+     * D15 made ctrl+V fetch the clipboard and it worked; then it inserted
+     * the PATH, the path began with `/`, and the composer handed it to
+     * the slash-command dispatcher. A feature that reaches the last step
+     * and gives the result to the wrong parser has not shipped.
+     *
+     * So the buffer carries a token and this carries the file. The token
+     * is what the LINE is — the dispatcher sees `[Image #1]`, which is
+     * not a command and never could be — and the CLI reads this map when
+     * it builds the turn. Unlike the text capsule, the image is NOT
+     * expanded into the line on the way out: a path is not something the
+     * model should be sent, and a transcript full of temp-file names is
+     * not something the human should have to read.
+     */
+    #attachments = new Map();
+    #attachSeq = 0;
     #pasteSeq = 0;
     /** The buffer index where the in-flight paste began; null outside one. */
     #pasteAt = null;
@@ -311,6 +329,12 @@ export class Editor {
     onClipboardPaste(cb) {
         this.#onClipboardPaste = cb;
     }
+    /** REL-0152-D16: the files this line's `[Image #N]` capsules stand
+     *  for, by their number. The CLI resolves them when it builds the
+     *  turn; a capsule the human deleted is simply never looked up. */
+    attachments() {
+        return new Map(this.#attachments);
+    }
     onRedirect(cb) {
         this.#redirectCbs.push(cb);
     }
@@ -1205,9 +1229,13 @@ export class Editor {
                 // REL-0152-D15: ctrl+V asks for the clipboard. Inert with no
                 // hook wired, and 0x16 must NEVER reach the buffer — an
                 // unhandled control byte in a prompt is a corrupt prompt.
-                const text = this.#onClipboardPaste?.() ?? null;
-                if (text !== null && text !== "") {
-                    for (const ch of text)
+                const file = this.#onClipboardPaste?.() ?? null;
+                if (file !== null && file !== "") {
+                    // REL-0152-D16: the capsule goes in the buffer, the file
+                    // goes beside it. See #attachments.
+                    this.#attachSeq += 1;
+                    this.#attachments.set(this.#attachSeq, file);
+                    for (const ch of `[Image #${this.#attachSeq}]`)
                         this.#insert(ch.codePointAt(0));
                     this.#onRender();
                 }
@@ -1951,10 +1979,12 @@ export class Editor {
             // REL-0152-D11: an empty paste is the image case — see
             // #onEmptyPaste. Anything it returns is ordinary text from here
             // on and takes the same route as if it had been typed.
-            const substitute = this.#onClipboardPaste?.() ?? null;
-            if (substitute === null || substitute === "")
+            const file = this.#onClipboardPaste?.() ?? null;
+            if (file === null || file === "")
                 return;
-            run = [...substitute].map((ch) => ch.codePointAt(0));
+            this.#attachSeq += 1;
+            this.#attachments.set(this.#attachSeq, file);
+            run = [...`[Image #${this.#attachSeq}]`].map((ch) => ch.codePointAt(0));
         }
         if (this.#historyIdx !== null)
             this.#historyIdx = null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui",
-	"version": "0.15.8",
+	"version": "0.15.10",
 	"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.8"
+		"@vincemakes/kiso-tui-cells": "0.15.10"
 	}
 }