@zakmandhro/bunti 0.1.5 → 0.2.0

package/dist/render.js

@@ -1,7 +1,102 @@
 /**
  * Bunti Functional Rendering & Diffing
  */
+import { hintKeyboardStdinNotTTY } from './diagnostics';
+import { createKeyEvent, HeldKeyTracker, InputTokenizer, } from './input';
 import { ANSI, resizeScreen } from './state';
+/**
+ * Crash safety: every screen with an active render loop is tracked here so
+ * that process-level failure handlers can restore the terminal no matter how
+ * the process goes down (throw, unhandled rejection, exit, SIGHUP).
+ */
+const activeScreens = new Set();
+/**
+ * Emits the restorative ANSI sequence for a screen (mouse/focus tracking off,
+ * reset, clear, back to main buffer, cursor visible) and disables raw mode.
+ * Idempotent: safe to call any number of times per loop session.
+ */
+export function restoreTerminal(state) {
+    if (state.isRestored)
+        return;
+    state.isRestored = true;
+    const options = state.options;
+    let cmd = '';
+    if (state.pointerShape === 'pointer') {
+        cmd += OSC_POINTER_DEFAULT;
+        state.pointerShape = 'default';
+    }
+    if (options.mouse)
+        cmd += ANSI.mouseDisable;
+    if (options.focus)
+        cmd += ANSI.focusDisable;
+    cmd += ANSI.reset + ANSI.clear + ANSI.home;
+    if (options.alternateBuffer)
+        cmd += ANSI.mainBuffer;
+    cmd += ANSI.showCursor;
+    cmd += ANSI.reset;
+    try {
+        process.stdout.write(cmd);
+    }
+    catch {
+        // stdout may already be gone (e.g. terminal closed on SIGHUP)
+    }
+    if (process.stdin.isTTY) {
+        try {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+        }
+        catch {
+            // stdin may already be destroyed
+        }
+    }
+}
+function restoreAllScreens() {
+    for (const screen of activeScreens)
+        restoreTerminal(screen);
+}
+function formatError(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
+/** Restore first, then report on the main screen, then die like the runtime would. */
+const onUncaughtException = (err) => {
+    restoreAllScreens();
+    process.stderr.write(`${formatError(err)}\n`);
+    process.exit(1);
+};
+const onUnhandledRejection = (reason) => {
+    restoreAllScreens();
+    process.stderr.write(`${formatError(reason)}\n`);
+    process.exit(1);
+};
+/** 'exit' must stay synchronous: restore only, never exit() or async work. */
+const onProcessExit = () => {
+    restoreAllScreens();
+};
+const onSighup = () => {
+    restoreAllScreens();
+    process.exit(129); // 128 + SIGHUP(1), matching default signal death
+};
+let crashHandlersInstalled = false;
+function installCrashHandlers() {
+    if (crashHandlersInstalled)
+        return;
+    crashHandlersInstalled = true;
+    process.on('uncaughtException', onUncaughtException);
+    process.on('unhandledRejection', onUnhandledRejection);
+    process.on('exit', onProcessExit);
+    process.on('SIGHUP', onSighup);
+}
+function removeCrashHandlers() {
+    if (!crashHandlersInstalled)
+        return;
+    crashHandlersInstalled = false;
+    process.removeListener('uncaughtException', onUncaughtException);
+    process.removeListener('unhandledRejection', onUnhandledRejection);
+    process.removeListener('exit', onProcessExit);
+    process.removeListener('SIGHUP', onSighup);
+}
 export function syncScreenSize(state) {
     const width = process.stdout.columns || 80;
     const height = process.stdout.rows || 24;
@@ -15,18 +110,77 @@ export function isResizeSettled(state, now = Date.now()) {
     return !state.isResizing || now >= (state.resizeSettlesAt ?? 0);
 }
 export function clearTerminalForResize(state) {
-    process.stdout.write(ANSI.syncStart + ANSI.clear + ANSI.home + ANSI.syncEnd);
+    const sync = state.syncOutput !== false;
+    process.stdout.write((sync ? ANSI.syncStart : '') +
+        ANSI.clear +
+        ANSI.home +
+        (sync ? ANSI.syncEnd : ''));
     state.needsFullRedraw = true;
 }
+/** Copies a back-buffer cell's fields onto its front-buffer counterpart. */
+function syncFrontCell(front, cell) {
+    front.char = cell.char;
+    front.fg = cell.fg;
+    front.bg = cell.bg;
+    front.fgCode = cell.fgCode;
+    front.bgCode = cell.bgCode;
+    front.bold = cell.bold;
+    front.italic = cell.italic;
+    front.underline = cell.underline;
+    front.dim = cell.dim;
+    front.strike = cell.strike;
+    front.skip = cell.skip;
+}
+/** OSC 22 mouse-cursor shapes (xterm pointer-shape protocol). */
+const OSC_POINTER = '\x1b]22;pointer\x1b\\';
+const OSC_POINTER_DEFAULT = '\x1b]22;default\x1b\\';
 /**
- * Diffs back and front buffers surgically.
+ * OSC 22 pointer cursor: emits the 'pointer' shape when any hitbox
+ * registered this frame is under the mouse, and resets to 'default' on the
+ * hover-off edge. Emission is edge-triggered (once per state change, never
+ * per frame). Gated off for Apple Terminal, which does not understand
+ * OSC 22; everywhere else an unsupported sequence is harmlessly ignored.
  */
-export function flush(state) {
-    const writer = Bun.stdout.writer();
+export function updatePointerShape(state) {
+    if (!state.options.mouse)
+        return;
+    if (state.terminal?.app === 'apple-terminal')
+        return;
+    let hovered = false;
+    for (const box of state.hitboxes.values()) {
+        if (state.mouseX >= box.x &&
+            state.mouseX < box.x + box.width &&
+            state.mouseY >= box.y &&
+            state.mouseY < box.y + box.height) {
+            hovered = true;
+            break;
+        }
+    }
+    const shape = hovered ? 'pointer' : 'default';
+    if (shape === (state.pointerShape ?? 'default'))
+        return;
+    state.pointerShape = shape;
+    try {
+        process.stdout.write(hovered ? OSC_POINTER : OSC_POINTER_DEFAULT);
+    }
+    catch {
+        // stdout may already be gone during teardown
+    }
+}
+/**
+ * Diffs back and front buffers and assembles the ANSI update string.
+ * Mutates the front buffer and the state's SGR trackers exactly like a real
+ * flush, but performs no I/O — flush() writes the result, tests assert on it.
+ */
+export function renderFrame(state) {
     let renderString = state.needsFullRedraw ? ANSI.clear + ANSI.home : '';
     let lastFg = state.lastFg;
     let lastBg = state.lastBg;
     let lastBold = state.lastBold ?? false;
+    let lastItalic = state.lastItalic ?? false;
+    let lastUnderline = state.lastUnderline ?? false;
+    let lastDim = state.lastDim ?? false;
+    let lastStrike = state.lastStrike ?? false;
     const width = state.width;
     const height = state.height;
     for (let y = 0; y < height; y++) {
@@ -41,6 +195,10 @@ export function flush(state) {
                 b.fg !== f.fg ||
                 b.bg !== f.bg ||
                 !!b.bold !== !!f.bold ||
+                !!b.italic !== !!f.italic ||
+                !!b.underline !== !!f.underline ||
+                !!b.dim !== !!f.dim ||
+                !!b.strike !== !!f.strike ||
                 !!b.skip !== !!f.skip) {
                 if (firstDirty === -1)
                     firstDirty = x;
@@ -53,39 +211,62 @@ export function flush(state) {
                 const idx = rowOffset + x;
                 const cell = state.backBuffer[idx];
                 const front = state.frontBuffer[idx];
-                if (cell.skip) {
-                    front.char = cell.char;
-                    front.fg = cell.fg;
-                    front.bg = cell.bg;
-                    front.fgCode = cell.fgCode;
-                    front.bgCode = cell.bgCode;
-                    front.bold = cell.bold;
-                    front.skip = cell.skip;
-                    continue;
-                }
-                if (cell.char === '') {
-                    front.char = '';
-                    front.fg = cell.fg;
-                    front.bg = cell.bg;
-                    front.fgCode = cell.fgCode;
-                    front.bgCode = cell.bgCode;
-                    front.bold = cell.bold;
-                    front.skip = cell.skip;
+                if (cell.skip || cell.char === '') {
+                    syncFrontCell(front, cell);
                     continue;
                 }
                 const fg = cell.fgCode;
                 const bg = cell.bgCode;
                 const bold = !!cell.bold;
-                if (bold !== lastBold) {
-                    renderString += bold ? '\x1b[1m' : '\x1b[22m';
+                const dim = !!cell.dim;
+                const italic = !!cell.italic;
+                const underline = !!cell.underline;
+                const strike = !!cell.strike;
+                if (bold !== lastBold || dim !== lastDim) {
+                    // SGR 22 clears BOTH bold and dim, so they are emitted jointly:
+                    // if either must turn off, emit 22 and re-assert the survivor.
+                    if ((lastBold && !bold) || (lastDim && !dim)) {
+                        renderString += '\x1b[22m';
+                        if (bold)
+                            renderString += '\x1b[1m';
+                        if (dim)
+                            renderString += '\x1b[2m';
+                    }
+                    else {
+                        if (bold && !lastBold)
+                            renderString += '\x1b[1m';
+                        if (dim && !lastDim)
+                            renderString += '\x1b[2m';
+                    }
                     lastBold = bold;
+                    lastDim = dim;
+                }
+                if (italic !== lastItalic) {
+                    renderString += italic ? '\x1b[3m' : '\x1b[23m';
+                    lastItalic = italic;
+                }
+                if (underline !== lastUnderline) {
+                    renderString += underline ? '\x1b[4m' : '\x1b[24m';
+                    lastUnderline = underline;
+                }
+                if (strike !== lastStrike) {
+                    renderString += strike ? '\x1b[9m' : '\x1b[29m';
+                    lastStrike = strike;
                 }
                 if (fg !== lastFg || bg !== lastBg) {
                     if (fg === undefined && bg === undefined) {
                         renderString += '\x1b[0m';
-                        if (lastBold) {
+                        // SGR 0 wipes every attribute; re-assert the active ones.
+                        if (lastBold)
                             renderString += '\x1b[1m';
-                        }
+                        if (lastDim)
+                            renderString += '\x1b[2m';
+                        if (lastItalic)
+                            renderString += '\x1b[3m';
+                        if (lastUnderline)
+                            renderString += '\x1b[4m';
+                        if (lastStrike)
+                            renderString += '\x1b[9m';
                     }
                     else {
                         // Foreground
@@ -123,38 +304,57 @@ export function flush(state) {
                     lastBg = bg;
                 }
                 renderString += cell.char;
-                front.char = cell.char;
-                front.fg = cell.fg;
-                front.bg = cell.bg;
-                front.fgCode = cell.fgCode;
-                front.bgCode = cell.bgCode;
-                front.bold = cell.bold;
-                front.skip = cell.skip;
+                syncFrontCell(front, cell);
             }
         }
     }
+    state.needsFullRedraw = false;
+    state.lastFg = lastFg;
+    state.lastBg = lastBg;
+    state.lastBold = lastBold;
+    state.lastItalic = lastItalic;
+    state.lastUnderline = lastUnderline;
+    state.lastDim = lastDim;
+    state.lastStrike = lastStrike;
+    return renderString;
+}
+/**
+ * Diffs back and front buffers surgically and writes the update to stdout.
+ */
+export function flush(state) {
+    const renderString = renderFrame(state);
     if (renderString) {
-        writer.write(ANSI.syncStart +
+        const writer = Bun.stdout.writer();
+        // Synchronized-output wrap (mode 2026) is gated on the detected profile:
+        // emitted unless the terminal was positively identified as lacking it
+        // (state.syncOutput === false). Absent/unknown profiles keep the wrap.
+        const sync = state.syncOutput !== false;
+        writer.write((sync ? ANSI.syncStart : '') +
             (state.options.hideCursor ? ANSI.hideCursor : '') +
             renderString +
-            ANSI.syncEnd);
+            (sync ? ANSI.syncEnd : ''));
         writer.flush();
     }
-    state.needsFullRedraw = false;
-    state.lastFg = lastFg;
-    state.lastBg = lastBg;
-    state.lastBold = lastBold;
 }
 /**
  * Starts the render loop for a given screen state.
  */
 export function loop(state, renderCallback) {
+    if (activeScreens.size > 0) {
+        throw new Error('A Bunti render loop is already active in this process. ' +
+            'Stop it first (requestStop or Ctrl+C) before calling render() again.');
+    }
     const options = state.options;
+    // Dev hint: keyboard input silently does nothing on piped stdin.
+    hintKeyboardStdinNotTTY(options.keyboard === true, process.stdin.isTTY === true);
+    state.isRestored = false;
+    activeScreens.add(state);
+    installCrashHandlers();
     if (options.alternateBuffer)
         process.stdout.write(ANSI.alternateBuffer);
     if (options.hideCursor)
         process.stdout.write(ANSI.hideCursor);
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         let stopped = false;
         let interval = null;
         const setupInput = () => {
@@ -172,37 +372,37 @@ export function loop(state, renderCallback) {
             }
         };
         const inputHandler = (data) => applyInputToState(state, data, stop);
-        const stop = () => {
+        /**
+         * Tears the loop down exactly once: clears the interval, removes every
+         * listener this loop registered, restores the terminal, then settles the
+         * promise (rejecting with `failure.error` when a frame crashed).
+         */
+        const finish = (failure) => {
             if (stopped)
                 return;
             stopped = true;
             state.isStopped = true;
             if (interval)
                 clearInterval(interval);
-            // 1. Restore Terminal Modes
-            if (process.stdin.isTTY) {
-                process.stdin.setRawMode(false);
-                process.stdin.pause();
-            }
-            // 2. Remove Listeners
+            // 1. Remove Listeners
+            state.inputTokenizer?.dispose();
             process.stdin.removeListener('data', inputHandler);
             process.removeListener('SIGWINCH', resizeHandler);
             process.removeListener('SIGINT', stop);
             process.removeListener('SIGTERM', stop);
-            // 3. Emit Restorative ANSI Sequence
-            let cmd = '';
-            if (options.mouse)
-                cmd += ANSI.mouseDisable;
-            if (options.focus)
-                cmd += ANSI.focusDisable;
-            cmd += ANSI.reset + ANSI.clear + ANSI.home;
-            if (options.alternateBuffer)
-                cmd += ANSI.mainBuffer;
-            cmd += ANSI.showCursor;
-            cmd += ANSI.reset;
-            process.stdout.write(cmd);
-            resolve();
+            activeScreens.delete(state);
+            if (activeScreens.size === 0)
+                removeCrashHandlers();
+            // 2. Restore Terminal Modes + Emit Restorative ANSI Sequence
+            restoreTerminal(state);
+            if (failure) {
+                reject(failure.error);
+            }
+            else {
+                resolve();
+            }
         };
+        const stop = () => finish(null);
         const resizeHandler = () => {
             resizeScreen(state);
             clearTerminalForResize(state);
@@ -229,15 +429,41 @@ export function loop(state, renderCallback) {
                     state.isResizing = false;
                     if (stopped || state.isStopped)
                         return;
+                    drainFrameInput(state);
+                    // Frame timing: loop() owns the clock. dt is clamped so a
+                    // suspended process doesn't produce a giant catch-up step.
+                    const now = Date.now();
+                    state.dt =
+                        state.lastFrameAt === undefined
+                            ? 0
+                            : Math.min(100, now - state.lastFrameAt);
+                    state.lastFrameAt = now;
+                    state.frameCount = (state.frameCount ?? 0) + 1;
                     renderCallback(state);
                     if (stopped || state.isStopped)
                         return;
                     flush(state);
-                    state.lastKey = undefined;
+                    // OSC 22 mouse-cursor shape reacts to this frame's hitboxes.
+                    updatePointerShape(state);
                 } while (tickAgain);
             }
             catch (err) {
-                console.error(err);
+                // Never write errors into the alt screen and never keep looping over
+                // a broken frame. Either the app opts into continuing via onError,
+                // or we tear down (restoring the terminal) and reject the loop
+                // promise so the error surfaces once, on the main screen.
+                let shouldContinue = false;
+                if (options.onError) {
+                    try {
+                        shouldContinue = options.onError(err) === 'continue';
+                    }
+                    catch {
+                        shouldContinue = false; // a broken error handler never saves the loop
+                    }
+                }
+                if (!shouldContinue) {
+                    finish({ error: err });
+                }
             }
             finally {
                 ticking = false;
@@ -269,67 +495,156 @@ export function loop(state, renderCallback) {
         restartLoop();
     });
 }
-export function applyInputToState(state, data, stop) {
-    const input = data instanceof Buffer ? data.toString() : String(data);
-    // 1. Focus Tracking
-    if (input === '\x1b[I') {
-        state.hasFocus = true;
-        if (state.restartLoop)
-            state.restartLoop();
+function requestTick(state) {
+    state.requestTick?.();
+}
+function heldTracker(state) {
+    state.heldKeys ??= new HeldKeyTracker({
+        holdWindowMs: state.options.holdWindowMs,
+    });
+    return state.heldKeys;
+}
+/**
+ * Classifies a key event (press vs repeat), enqueues it, and mirrors the
+ * legacy `state.lastKey` slot. Ctrl+C keeps its stop/SIGINT behavior and
+ * never enters the queue.
+ */
+function enqueueKeyEvent(state, event, stop) {
+    if (event.ctrl && event.key === 'c') {
+        stop?.(); // Ctrl+C
         return;
     }
-    if (input === '\x1b[O') {
-        state.hasFocus = false;
-        if (state.restartLoop)
-            state.restartLoop();
-        return;
+    const classified = heldTracker(state).record(event);
+    state.keyQueue.push(classified);
+    // Back-compat: lastKey only ever carries unmodified key names, so ctrl
+    // bytes no longer leak into text consumers like Input.
+    if (!classified.ctrl && !classified.alt && classified.kind !== 'release') {
+        state.lastKey = classified.key;
+    }
+}
+/**
+ * SGR mouse semantics:
+ * - wheel (bit 64): wheel_up / wheel_down key events, no press state
+ * - motion (bit 32): coordinates only (drags keep the pressed button)
+ * - press 'M': records the press origin; no click yet
+ * - release 'm': emits 'click' ONCE at the press-origin coordinates
+ */
+function dispatchMouse(state, token, stop) {
+    const button = token.button;
+    state.mouseX = token.x - 1;
+    state.mouseY = token.y - 1;
+    if (button & 64) {
+        // Wheel
+        state.mouseButton = button;
+        if (token.action === 'press') {
+            if (button === 64) {
+                enqueueKeyEvent(state, createKeyEvent('wheel_up', token.raw), stop);
+            }
+            else if (button === 65) {
+                enqueueKeyEvent(state, createKeyEvent('wheel_down', token.raw), stop);
+            }
+        }
+    }
+    else if (button & 32) {
+        // Motion. Base 3 = no buttons held (pure move): keep press state as-is.
+        const base = button & 3;
+        if (base !== 3)
+            state.mouseButton = base;
     }
-    // 2. Mouse Tracking (SGR protocol)
-    const match = input.match(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/);
-    if (match) {
-        state.mouseButton = parseInt(match[1], 10);
-        state.mouseX = parseInt(match[2], 10) - 1;
-        state.mouseY = parseInt(match[3], 10) - 1;
-        state.isMouseDown = match[4] === 'M';
-        if (state.requestTick) {
-            state.requestTick();
+    else if (token.action === 'press') {
+        state.mouseButton = button;
+        state.isMouseDown = true;
+        if ((button & 3) === 0) {
+            state.mouseDownX = state.mouseX;
+            state.mouseDownY = state.mouseY;
         }
-        if (match[4] === 'M') {
-            if (state.mouseButton === 64)
-                state.lastKey = 'wheel_up';
-            else if (state.mouseButton === 65)
-                state.lastKey = 'wheel_down';
-            else if (state.mouseButton === 0)
-                state.lastKey = 'click';
+    }
+    else {
+        state.mouseButton = button;
+        state.isMouseDown = false;
+        if ((button & 3) === 0 &&
+            state.mouseDownX !== undefined &&
+            state.mouseDownY !== undefined) {
+            state.clickX = state.mouseDownX;
+            state.clickY = state.mouseDownY;
+            enqueueKeyEvent(state, createKeyEvent('click', token.raw), stop);
         }
-        return;
+        state.mouseDownX = undefined;
+        state.mouseDownY = undefined;
     }
-    // 3. Signal Interception
-    if (input === '\u0003') {
-        stop?.(); // Ctrl+C
-        return;
+}
+function dispatchInputTokens(state, tokens, stop) {
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'focus': {
+                state.hasFocus = token.focused;
+                state.restartLoop?.();
+                continue; // restartLoop already forces a tick
+            }
+            case 'response': {
+                state.terminalResponses.push(token.response);
+                // Bounded: consumers drain; a probe-less app must not leak.
+                if (state.terminalResponses.length > 64) {
+                    state.terminalResponses.shift();
+                }
+                break;
+            }
+            case 'mouse': {
+                dispatchMouse(state, token, stop);
+                break;
+            }
+            case 'key': {
+                enqueueKeyEvent(state, token.event, stop);
+                break;
+            }
+        }
+        requestTick(state);
+    }
+}
+/**
+ * Feeds a raw stdin chunk through the screen's stateful tokenizer and
+ * dispatches the resulting tokens. Partial escape sequences are carried
+ * across calls; a bare ESC flushes as 'escape' via the tokenizer timer.
+ */
+export function applyInputToState(state, data, stop) {
+    const input = data instanceof Buffer ? data.toString() : String(data);
+    state.inputTokenizer ??= new InputTokenizer({
+        escTimeoutMs: state.options.escTimeoutMs,
+    });
+    const tokenizer = state.inputTokenizer;
+    // Rebind each call so timer flushes see the latest stop handler.
+    tokenizer.onFlush = (tokens) => dispatchInputTokens(state, tokens, stop);
+    dispatchInputTokens(state, tokenizer.push(input), stop);
+}
+/**
+ * Moves queued KeyEvents into this frame's `state.keys`, appends synthetic
+ * held-key releases, and recomputes the legacy `state.lastKey` slot (first
+ * unmodified press/repeat of the frame). Runs once per render tick, before
+ * the render callback.
+ */
+export function drainFrameInput(state) {
+    const frame = state.keyQueue.length > 0 ? state.keyQueue.splice(0) : [];
+    if (state.heldKeys) {
+        const releases = state.heldKeys.collectReleases();
+        if (releases.length > 0)
+            frame.push(...releases);
+    }
+    state.keys = frame;
+    let lastKey;
+    let hasClick = false;
+    for (const event of frame) {
+        if (event.kind === 'release')
+            continue;
+        if (event.key === 'click')
+            hasClick = true;
+        if (lastKey === undefined && !event.ctrl && !event.alt) {
+            lastKey = event.key;
+        }
     }
-    // 4. Key Normalization
-    let key = input;
-    if (input === '\x7f' || input === '\x08')
-        key = 'backspace';
-    else if (input === '\r' || input === '\n')
-        key = 'enter';
-    else if (input === '\t')
-        key = 'tab';
-    else if (input === '\x1b[A')
-        key = 'up';
-    else if (input === '\x1b[B')
-        key = 'down';
-    else if (input === '\x1b[C')
-        key = 'right';
-    else if (input === '\x1b[D')
-        key = 'left';
-    else if (input === '\x1b')
-        key = 'escape';
-    state.lastKey = key;
-    if (state.requestTick) {
-        state.requestTick();
+    state.lastKey = lastKey;
+    if (!hasClick) {
+        state.clickX = undefined;
+        state.clickY = undefined;
     }
 }
 //# sourceMappingURL=render.js.map