mindweave 0.0.1 → 2.1.2

package/dist/cli/framebuffer/parse.js

@@ -0,0 +1,266 @@
+/**
+ * parse.ts — Ink's frame string into a cell grid.
+ *
+ * Ink hands the terminal one string per frame: lines separated by `\n`, with SGR
+ * escape sequences (`\x1b[...m`) inline wherever the style changes. To diff frames
+ * cell by cell we first have to know what each frame ACTUALLY PUTS in each cell,
+ * which means interpreting those sequences the way a terminal would.
+ *
+ * So this is a very small terminal emulator: it walks the string carrying the
+ * current pen (foreground, background, attributes), and every printable character
+ * it meets is stamped into the grid at the cursor, which then advances.
+ *
+ * ## Scope, deliberately
+ *
+ * It handles what Ink emits and nothing else. Ink's frame content is styled text
+ * and newlines — it does not move the cursor around inside a frame, because it
+ * builds the whole frame as a string first (see `ink/build/ink.js`, which writes
+ * `eraseLines(previousHeight) + wrappedOutput`). Any other CSI sequence is SKIPPED
+ * rather than guessed at: skipping leaves the grid exactly as it was, which is the
+ * safe direction to be wrong in, where guessing would corrupt every cell after it.
+ *
+ * The one non-SGR sequence that matters is the `eraseLines` prefix, and the caller
+ * strips that before we ever see it — see `writer.ts`.
+ */
+import { ATTR, DEFAULT_COLOR, WIDE_CONTINUATION, paletteColor, rgbColor, } from "./screen.js";
+import { eastAsianWidth } from "get-east-asian-width";
+/** A fresh pen: the terminal's own colours, no attributes. */
+function resetPen(pen) {
+    pen.fg = DEFAULT_COLOR;
+    pen.bg = DEFAULT_COLOR;
+    pen.attrs = 0;
+}
+/**
+ * Apply one SGR sequence's parameters to the pen.
+ *
+ * Returns nothing; mutates `pen`. Written as a loop with an index rather than a
+ * `for..of` because the extended colour forms (`38;5;n` and `38;2;r;g;b`) consume
+ * following parameters, so the cursor into the list has to move by more than one.
+ */
+function applySgr(pen, params) {
+    if (params.length === 0) {
+        // A bare `\x1b[m` is `\x1b[0m` — a full reset.
+        resetPen(pen);
+        return;
+    }
+    for (let i = 0; i < params.length; i++) {
+        const p = params[i];
+        switch (p) {
+            case 0:
+                resetPen(pen);
+                break;
+            case 1:
+                pen.attrs |= ATTR.bold;
+                break;
+            case 2:
+                pen.attrs |= ATTR.dim;
+                break;
+            case 3:
+                pen.attrs |= ATTR.italic;
+                break;
+            case 4:
+                pen.attrs |= ATTR.underline;
+                break;
+            case 7:
+                pen.attrs |= ATTR.inverse;
+                break;
+            case 8:
+                pen.attrs |= ATTR.hidden;
+                break;
+            case 9:
+                pen.attrs |= ATTR.strikethrough;
+                break;
+            // 21/22 both end bold. 22 also ends dim, and clearing both for either is
+            // deliberate: chalk emits 22 to close a bold span, and leaving dim set would
+            // tint every cell after it.
+            case 21:
+            case 22:
+                pen.attrs &= ~(ATTR.bold | ATTR.dim);
+                break;
+            case 23:
+                pen.attrs &= ~ATTR.italic;
+                break;
+            case 24:
+                pen.attrs &= ~ATTR.underline;
+                break;
+            case 27:
+                pen.attrs &= ~ATTR.inverse;
+                break;
+            case 28:
+                pen.attrs &= ~ATTR.hidden;
+                break;
+            case 29:
+                pen.attrs &= ~ATTR.strikethrough;
+                break;
+            case 39:
+                pen.fg = DEFAULT_COLOR;
+                break;
+            case 49:
+                pen.bg = DEFAULT_COLOR;
+                break;
+            case 38:
+            case 48: {
+                // Extended colour: `38;5;n` (palette) or `38;2;r;g;b` (truecolour).
+                const isFg = p === 38;
+                const mode = params[i + 1];
+                if (mode === 5 && params.length > i + 2) {
+                    const c = paletteColor(params[i + 2]);
+                    if (isFg)
+                        pen.fg = c;
+                    else
+                        pen.bg = c;
+                    i += 2;
+                }
+                else if (mode === 2 && params.length > i + 4) {
+                    const c = rgbColor(params[i + 2], params[i + 3], params[i + 4]);
+                    if (isFg)
+                        pen.fg = c;
+                    else
+                        pen.bg = c;
+                    i += 4;
+                }
+                else {
+                    // Malformed — consume the mode byte and carry on rather than
+                    // misreading the remaining parameters as colours.
+                    i += 1;
+                }
+                break;
+            }
+            default:
+                if (p >= 30 && p <= 37)
+                    pen.fg = paletteColor(p - 30);
+                else if (p >= 90 && p <= 97)
+                    pen.fg = paletteColor(p - 90 + 8);
+                else if (p >= 40 && p <= 47)
+                    pen.bg = paletteColor(p - 40);
+                else if (p >= 100 && p <= 107)
+                    pen.bg = paletteColor(p - 100 + 8);
+                // Anything else is a code we do not model. Ignored, not guessed.
+                break;
+        }
+    }
+}
+/** Reset a run of cells to default-styled blanks, the way an erase sequence does. */
+function blank(screen, from, to) {
+    const lo = Math.max(0, Math.min(from, screen.chars.length));
+    const hi = Math.max(lo, Math.min(to, screen.chars.length));
+    screen.chars.fill(32, lo, hi);
+    screen.fg.fill(DEFAULT_COLOR, lo, hi);
+    screen.bg.fill(DEFAULT_COLOR, lo, hi);
+    screen.attrs.fill(0, lo, hi);
+}
+/**
+ * Draw `frame` into `screen`, starting at row `top`.
+ *
+ * The screen is NOT cleared first — the caller decides that, because a resize
+ * wants a clean grid while an ordinary frame is a complete repaint of the rows it
+ * covers and clearing would be redundant work. Rows the frame does not reach are
+ * left alone.
+ */
+export function parseFrame(screen, frame, top = 0) {
+    const pen = { fg: DEFAULT_COLOR, bg: DEFAULT_COLOR, attrs: 0 };
+    let x = 0;
+    let y = top;
+    for (let i = 0; i < frame.length;) {
+        const ch = frame[i];
+        if (ch === "") {
+            // CSI: ESC [ params... final-byte
+            if (frame[i + 1] === "[") {
+                let j = i + 2;
+                while (j < frame.length) {
+                    const c = frame.charCodeAt(j);
+                    // Parameter bytes are 0x30-0x3F, intermediates 0x20-0x2F; the final byte
+                    // is 0x40-0x7E and ends the sequence.
+                    if (c >= 0x40 && c <= 0x7e)
+                        break;
+                    j++;
+                }
+                const final = frame[j];
+                const body = frame.slice(i + 2, j);
+                const params = body === "" ? [] : body.split(";").map((s) => (s === "" ? 0 : Number.parseInt(s, 10) || 0));
+                if (final === "m") {
+                    applySgr(pen, params);
+                }
+                else if (final === "H" || final === "f") {
+                    // Absolute cursor position, 1-based on the real screen. `top` is where
+                    // row 0 of this grid sits, so it comes back off to get a grid row.
+                    y = (params[0] ?? 1) - 1 + top;
+                    x = (params[1] ?? 1) - 1;
+                }
+                else if (final === "C") {
+                    x += Math.max(1, params[0] ?? 1);
+                }
+                else if (final === "D") {
+                    x = Math.max(0, x - Math.max(1, params[0] ?? 1));
+                }
+                else if (final === "J") {
+                    // Erase display. A real terminal blanks the cells; skipping it left this
+                    // parser believing text was still there that the terminal had already wiped,
+                    // which is a difference that only shows up on a resize (the one time the
+                    // writer sends one). 2 = whole screen, 1 = up to the cursor, 0 = from it on.
+                    const mode = params[0] ?? 0;
+                    const from = mode === 2 ? 0 : mode === 1 ? 0 : y * screen.width + x;
+                    const to = mode === 2 ? screen.chars.length : mode === 1 ? y * screen.width + x : screen.chars.length;
+                    blank(screen, from, to);
+                }
+                else if (final === "K") {
+                    // Erase in line, same three modes but bounded to the current row.
+                    const mode = params[0] ?? 0;
+                    const rowStart = y * screen.width;
+                    const from = mode === 0 ? rowStart + x : rowStart;
+                    const to = mode === 1 ? rowStart + x + 1 : rowStart + screen.width;
+                    blank(screen, from, to);
+                }
+                // Every other CSI is skipped whole — see the file header.
+                i = j + 1;
+                continue;
+            }
+            // A non-CSI escape (OSC, single-character escapes). Skip the ESC and let the
+            // following bytes be read normally; Ink does not emit these inside a frame,
+            // and dropping one byte is far less damaging than misparsing a run.
+            i += 1;
+            continue;
+        }
+        if (ch === "\n") {
+            y++;
+            x = 0;
+            i += 1;
+            continue;
+        }
+        if (ch === "\r") {
+            x = 0;
+            i += 1;
+            continue;
+        }
+        // A printable character. Read a full codepoint, because a surrogate pair is one
+        // character occupying (usually) two columns, and splitting it would write two
+        // meaningless halves.
+        const code = frame.codePointAt(i);
+        const size = code > 0xffff ? 2 : 1;
+        i += size;
+        if (y >= screen.height || y < 0) {
+            // Past the bottom of the grid: keep scanning so the pen stays correct if the
+            // frame comes back into range, but write nothing.
+            continue;
+        }
+        const w = eastAsianWidth(code);
+        if (x < screen.width) {
+            const at = screen.index(x, y);
+            screen.chars[at] = code;
+            screen.fg[at] = pen.fg;
+            screen.bg[at] = pen.bg;
+            screen.attrs[at] = pen.attrs;
+            // A wide character claims the next column too. Marking it is what keeps every
+            // later column on the row aligned with what the terminal will actually do.
+            if (w === 2 && x + 1 < screen.width) {
+                const next = screen.index(x + 1, y);
+                screen.chars[next] = WIDE_CONTINUATION;
+                screen.fg[next] = pen.fg;
+                screen.bg[next] = pen.bg;
+                screen.attrs[next] = pen.attrs;
+            }
+        }
+        x += w;
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/cli/framebuffer/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/cli/framebuffer/parse.ts"],"names":[],"mappings":"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"}

package/dist/cli/framebuffer/screen.js

@@ -0,0 +1,196 @@
+/**
+ * screen.ts — the cell grid, and the colour model that packs into it.
+ *
+ * This is the memory the whole framebuffer renderer is built on: one entry per
+ * character cell on the terminal, held as a STRUCTURE OF ARRAYS rather than an
+ * array of cell objects.
+ *
+ * Why SoA, concretely: a 200x50 terminal is 10,000 cells. As objects that is
+ * 10,000 allocations per frame for the garbage collector to walk, and the fields
+ * of one cell land wherever the allocator put them. As four flat typed arrays it
+ * is four allocations TOTAL, reused for the life of the process, laid out
+ * contiguously so the diff loop reads straight down memory. The diff runs over
+ * every cell on every frame, so this is the loop whose cache behaviour decides
+ * whether the renderer can hit a frame budget. Same layout OpenTUI's Zig core and
+ * ratatui's Buffer use, for the same reason.
+ *
+ * Everything a cell needs is an integer, so comparing two cells is four integer
+ * comparisons and no allocation, no string compare, no property lookup.
+ *
+ * ## The colour encoding
+ *
+ * A terminal colour is one of four things, and they must round-trip exactly — a
+ * cell that was written as 256-palette colour 33 has to be re-emitted as palette
+ * 33, not as its RGB approximation, or the diff would rewrite cells that never
+ * actually changed. So the encoding is a tagged integer:
+ *
+ *   0                          default (terminal's own foreground/background)
+ *   PALETTE | n                256-colour palette index n (0-255)
+ *   RGB     | (r<<16|g<<8|b)   24-bit truecolour
+ *
+ * The tag lives above the 24 bits of payload, so an entire colour is one Uint32
+ * and equality is `===`.
+ */
+/** Tag marking a packed colour as a 256-colour palette index. */
+export const PALETTE = 1 << 25;
+/** Tag marking a packed colour as 24-bit RGB. */
+export const RGB = 1 << 26;
+/** The terminal's own default colour — what a cell has when nothing set it. */
+export const DEFAULT_COLOR = 0;
+/** Text attributes, as bit flags in one integer. */
+export const ATTR = {
+    bold: 1 << 0,
+    dim: 1 << 1,
+    italic: 1 << 2,
+    underline: 1 << 3,
+    inverse: 1 << 4,
+    hidden: 1 << 5,
+    strikethrough: 1 << 6,
+};
+/**
+ * A cell holding the RIGHT half of a double-width character.
+ *
+ * Wide characters (CJK, most emoji) occupy two terminal columns but are a single
+ * character. The left cell carries the codepoint; the right carries this marker so
+ * that the diff knows the column is spoken for and the painter knows never to emit
+ * anything for it — the terminal advances the cursor two columns by itself when it
+ * prints the wide character.
+ *
+ * It is a distinct value rather than a blank because the difference matters: a
+ * blank would be legitimately printable and would desynchronise every column after
+ * it on that row.
+ */
+export const WIDE_CONTINUATION = 0xffff_ffff;
+/** A grid of terminal cells. */
+export class Screen {
+    width;
+    height;
+    /** Unicode codepoint per cell. 32 (space) is empty; WIDE_CONTINUATION is the
+     *  right half of a wide character. */
+    chars;
+    /** Packed foreground colour per cell. */
+    fg;
+    /** Packed background colour per cell. */
+    bg;
+    /** Packed attribute flags per cell. */
+    attrs;
+    constructor(width, height) {
+        this.width = Math.max(0, width);
+        this.height = Math.max(0, height);
+        const n = this.width * this.height;
+        this.chars = new Uint32Array(n);
+        this.fg = new Uint32Array(n);
+        this.bg = new Uint32Array(n);
+        this.attrs = new Uint32Array(n);
+        this.clear();
+    }
+    /** Row-major index of a cell. Callers are expected to be in bounds; this is the
+     *  hot path and a check here would run millions of times a second. */
+    index(x, y) {
+        return y * this.width + x;
+    }
+    /** Reset every cell to a default-styled blank. */
+    clear() {
+        this.chars.fill(32);
+        this.fg.fill(DEFAULT_COLOR);
+        this.bg.fill(DEFAULT_COLOR);
+        this.attrs.fill(0);
+    }
+    /**
+     * Resize, discarding contents.
+     *
+     * Deliberately does NOT preserve the old grid. A resize re-wraps every line, so
+     * the previous contents are not a valid picture of the new screen at any size —
+     * keeping them would mean diffing against a frame that never existed and leaving
+     * stale text on screen. The caller repaints in full instead.
+     *
+     * Reuses the existing buffers when the cell count is unchanged (a pure rotation,
+     * e.g. 80x50 to 50x80), which is the one case where reallocating would be waste.
+     */
+    resize(width, height) {
+        const w = Math.max(0, width);
+        const h = Math.max(0, height);
+        const n = w * h;
+        if (n !== this.chars.length) {
+            this.chars = new Uint32Array(n);
+            this.fg = new Uint32Array(n);
+            this.bg = new Uint32Array(n);
+            this.attrs = new Uint32Array(n);
+        }
+        this.width = w;
+        this.height = h;
+        this.clear();
+    }
+    /** Copy `other` into this screen. Both must be the same size; the caller resizes
+     *  first. `set` on a typed array is a memcpy, which is the point. */
+    copyFrom(other) {
+        if (other.width !== this.width || other.height !== this.height) {
+            this.resize(other.width, other.height);
+        }
+        this.chars.set(other.chars);
+        this.fg.set(other.fg);
+        this.bg.set(other.bg);
+        this.attrs.set(other.attrs);
+    }
+    /** Whether two cells are identical in every respect — the diff's inner test. */
+    sameAs(other, i) {
+        return (this.chars[i] === other.chars[i] &&
+            this.fg[i] === other.fg[i] &&
+            this.bg[i] === other.bg[i] &&
+            this.attrs[i] === other.attrs[i]);
+    }
+}
+/** Pack a 256-colour palette index. */
+export function paletteColor(index) {
+    return PALETTE | (index & 0xff);
+}
+/** Pack a 24-bit RGB colour. */
+export function rgbColor(r, g, b) {
+    return RGB | ((r & 0xff) << 16) | ((g & 0xff) << 8) | (b & 0xff);
+}
+/**
+ * The SGR parameters that produce `color` as a foreground (`fg`) or background.
+ *
+ * Returns the numeric parameters rather than a finished escape string so the
+ * painter can join a whole cell's worth — colour, background and attributes — into
+ * ONE `\x1b[...m` instead of three. Fewer, longer sequences is measurably less to
+ * write than more, shorter ones.
+ */
+export function colorParams(color, fg) {
+    if (color === DEFAULT_COLOR)
+        return [fg ? 39 : 49];
+    if (color & RGB) {
+        const v = color & 0xff_ffff;
+        return [fg ? 38 : 48, 2, (v >> 16) & 0xff, (v >> 8) & 0xff, v & 0xff];
+    }
+    const index = color & 0xff;
+    // The first 16 palette entries have short, universally supported forms. Worth the
+    // branch: they are by far the most common colours a TUI actually uses, and the
+    // short form is 3-4 bytes against 11 for the indexed form, on every cell that
+    // changes colour.
+    if (index < 8)
+        return [(fg ? 30 : 40) + index];
+    if (index < 16)
+        return [(fg ? 90 : 100) + (index - 8)];
+    return [fg ? 38 : 48, 5, index];
+}
+/** The SGR parameters that turn `attrs` on, assuming a reset state. */
+export function attrParams(attrs) {
+    const out = [];
+    if (attrs & ATTR.bold)
+        out.push(1);
+    if (attrs & ATTR.dim)
+        out.push(2);
+    if (attrs & ATTR.italic)
+        out.push(3);
+    if (attrs & ATTR.underline)
+        out.push(4);
+    if (attrs & ATTR.inverse)
+        out.push(7);
+    if (attrs & ATTR.hidden)
+        out.push(8);
+    if (attrs & ATTR.strikethrough)
+        out.push(9);
+    return out;
+}
+//# sourceMappingURL=screen.js.map

package/dist/cli/framebuffer/screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../../../src/cli/framebuffer/screen.ts"],"names":[],"mappings":"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"}

package/dist/cli/framebuffer/writer.js

@@ -0,0 +1,139 @@
+/**
+ * writer.ts — sits between Ink and the terminal, and writes only what changed.
+ *
+ * Ink's contract with the terminal is "erase everything I drew last time, then draw
+ * all of it again", on every render. That is tens of kilobytes per frame on a large
+ * terminal, pushed through a write that blocks the event loop on Windows — which is
+ * why typing and scrolling lag in proportion to how much is on screen rather than
+ * how much actually changed.
+ *
+ * This replaces that contract with a framebuffer:
+ *
+ *     Ink renders a frame  ->  parse it into a cell grid  ->  diff against the grid
+ *     already on screen  ->  emit only the cells that differ  ->  keep the new grid
+ *
+ * Ink is untouched, and so is every component. The interception is a PROXY STDOUT
+ * handed to `render()`, not a patch of `process.stdout`: everything arriving here is
+ * therefore known to be Ink's renderer output, where a global patch would also catch
+ * unrelated writes and have to guess which was which.
+ *
+ * ## What is passed through untouched
+ *
+ * Only frame CONTENT can be diffed. Control sequences that are not a frame — entering
+ * the alternate screen, hiding the cursor, the synchronized-update markers Ink wraps
+ * frames in — carry no cells and are forwarded exactly as sent. The test is whether a
+ * write contains anything printable once its escape sequences are removed.
+ */
+import { Screen } from "./screen.js";
+import { parseFrame } from "./parse.js";
+import { paint } from "./paint.js";
+/**
+ * The prefix Ink puts before a frame to remove the previous one:
+ * `\x1b[2K` (erase line) and `\x1b[1A` (cursor up) repeated, then `\x1b[G`.
+ *
+ * We drop it. The whole point of the framebuffer is that the previous frame is NOT
+ * erased — the parts of it that are still correct stay on screen untouched, which is
+ * exactly the work being saved.
+ */
+const ERASE_PREFIX = /^(?:\x1b\[2K(?:\x1b\[1A)?)+\x1b\[G/;
+/** Any escape sequence, for deciding whether a write carries visible content. */
+const ANY_ESCAPE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[[\]()#;?]*[0-9;]*[A-Za-z]|\x1b./g;
+/**
+ * Wrap `real` so Ink's frames are diffed before they reach it.
+ *
+ * `onFrame` is called after each frame with what it cost, so the perf log can report
+ * the saving without this module knowing anything about logging.
+ */
+export function framebufferStdout(real, onFrame) {
+    // The grid currently on the terminal, and the one being built for this frame. Two
+    // long-lived buffers, swapped — never reallocated per frame, which is the whole
+    // reason the cell data is in typed arrays.
+    let onScreen = new Screen(real.columns ?? 80, real.rows ?? 24);
+    let pending = new Screen(onScreen.width, onScreen.height);
+    /**
+     * Match the grids to the terminal. Returns true when the size changed, which the
+     * caller must answer by erasing the real screen before it paints.
+     *
+     * The erase is the whole point and it used to be missing. Resizing reset `onScreen`
+     * to blanks, on the reasoning that a blank model would make every cell differ and
+     * force a full repaint. It does the opposite: the new frame's blank regions are also
+     * blanks, so the diff finds them identical and writes nothing for them, while the real
+     * terminal still holds whatever was in those cells before. That is what fused an old
+     * line onto a new one, leaving rows like `Tools(session)s, ask_user, create_skill,`.
+     *
+     * Erasing for real is also the cheap fix rather than the expensive one. Filling the
+     * model with a sentinel no cell can equal would work too, and would then write every
+     * space on screen as an explicit character. One escape sequence costs four bytes and
+     * leaves the diff free to stay minimal for the frame itself.
+     */
+    function syncSize() {
+        const w = real.columns ?? onScreen.width;
+        const h = real.rows ?? onScreen.height;
+        if (w === onScreen.width && h === onScreen.height)
+            return false;
+        onScreen.resize(w, h);
+        pending.resize(w, h);
+        // Now TRUE rather than assumed: the model says blank, and the caller is about to
+        // make the terminal blank to match.
+        onScreen.clear();
+        return true;
+    }
+    /**
+     * Replaces `write` and nothing else.
+     *
+     * A hand-written object listing the members Ink "needs" was tried first and BROKE
+     * THE APP: Ink reads `stdout.isTTY` in five places to decide whether it is driving
+     * a terminal at all, the substitute did not have it, and Ink quietly took its
+     * non-interactive path — a blank screen, no error. The tests did not catch it
+     * because they pass a fake stdout that has no `isTTY` either, so both sides agreed
+     * on the wrong thing.
+     *
+     * A Proxy is the fix that cannot have that class of bug again: every property, every
+     * method, the prototype and `instanceof` all still resolve to the real stream, and
+     * only `write` is ours. Nothing has to be enumerated, so nothing can be forgotten.
+     */
+    const fbWrite = (data, callback) => {
+        const body = data.replace(ERASE_PREFIX, "");
+        // No printable content: a control sequence, not a frame. Forward verbatim —
+        // these are how the alternate screen is entered, the cursor hidden, and frames
+        // wrapped in synchronized-update markers, none of which we may swallow.
+        if (body.replace(ANY_ESCAPE, "").trim() === "") {
+            return real.write(data, callback);
+        }
+        const resized = syncSize();
+        // Build the new frame. Cleared first because a frame is a complete statement
+        // about the rows it covers: a line that got shorter must leave blanks behind,
+        // not the tail of what used to be there.
+        pending.clear();
+        parseFrame(pending, body);
+        // `` erases the display, `` homes the cursor. Sent only on a resize,
+        // to bring the real screen into line with the freshly blanked model above.
+        const escape = (resized ? "" : "") + paint(onScreen, pending, 1);
+        // Swap rather than copy. Both grids are the same shape and `pending` is fully
+        // rewritten at the start of every frame, so the old on-screen grid is free to
+        // become the next scratch buffer — no allocation, no memcpy.
+        const previous = onScreen;
+        onScreen = pending;
+        pending = previous;
+        onFrame?.({ inBytes: data.length, outBytes: escape.length });
+        if (escape === "") {
+            // Nothing changed. Writing zero bytes is the correct output, but the caller
+            // may be waiting on the callback, so it still has to be settled.
+            callback?.(null);
+            return true;
+        }
+        return real.write(escape, callback);
+    };
+    return new Proxy(real, {
+        get(target, prop, receiver) {
+            if (prop === "write")
+                return fbWrite;
+            const value = Reflect.get(target, prop, target);
+            // Methods are bound to the REAL stream, not to the proxy. A stream's own
+            // methods reach into its internal state, and calling them with the proxy as
+            // `this` would have them look for that state on the wrong object.
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+//# sourceMappingURL=writer.js.map

package/dist/cli/framebuffer/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/cli/framebuffer/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,YAAY,GAAG,oCAAoC,CAAC;AAE1D,iFAAiF;AACjF,MAAM,UAAU,GAAG,yEAAyE,CAAC;AAoB7F;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAyB,IAAO,EAAE,OAAqC;IACtG,kFAAkF;IAClF,gFAAgF;IAChF,2CAA2C;IAC3C,IAAI,QAAQ,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC/D,IAAI,OAAO,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;OAeG;IACH,SAAS,QAAQ;QACf,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC;QACzC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC;QACvC,IAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,IAAI,CAAC,KAAK,QAAQ,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAChE,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrB,iFAAiF;QACjF,oCAAoC;QACpC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,QAAuC,EAAW,EAAE;QAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAE5C,4EAA4E;QAC5E,+EAA+E;QAC/E,wEAAwE;QACxE,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC;QAE3B,6EAA6E;QAC7E,8EAA8E;QAC9E,yCAAyC;QACzC,OAAO,CAAC,KAAK,EAAE,CAAC;QAChB,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAE1B,4EAA4E;QAC5E,2EAA2E;QAC3E,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAExE,8EAA8E;QAC9E,8EAA8E;QAC9E,6DAA6D;QAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC;QAC1B,QAAQ,GAAG,OAAO,CAAC;QACnB,OAAO,GAAG,QAAQ,CAAC;QAEnB,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAE7D,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAClB,4EAA4E;YAC5E,iEAAiE;YACjE,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC;IAEF,OAAO,IAAI,KAAK,CAAC,IAAI,EAAE;QACrB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACxB,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,OAAO,CAAC;YACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAChD,yEAAyE;YACzE,4EAA4E;YAC5E,kEAAkE;YAClE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAClE,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}