@termuijs/core 0.1.4 → 0.1.6

package/dist/index.js

@@ -214,15 +214,15 @@ function contrastRatio(fg, bg) {
   const darker = Math.min(l1, l2);
   return (lighter + 0.05) / (darker + 0.05);
 }
-function wcagLevel(ratio2, large = false) {
+function wcagLevel(ratio, large = false) {
   if (large) {
-    if (ratio2 >= 4.5) return "AAA";
-    if (ratio2 >= 3) return "AA";
+    if (ratio >= 4.5) return "AAA";
+    if (ratio >= 3) return "AA";
     return "fail";
   }
-  if (ratio2 >= 7) return "AAA";
-  if (ratio2 >= 4.5) return "AA";
-  if (ratio2 >= 3) return "A";
+  if (ratio >= 7) return "AAA";
+  if (ratio >= 4.5) return "AA";
+  if (ratio >= 3) return "A";
   return "fail";
 }
 function validateThemeContrast(theme) {
@@ -241,10 +241,10 @@ function validateThemeContrast(theme) {
   for (const [label, hex] of pairs) {
     if (!hex) continue;
     const fgColor = parseColor(hex);
-    const ratio2 = contrastRatio(fgColor, bgColor);
-    const level = wcagLevel(ratio2);
+    const ratio = contrastRatio(fgColor, bgColor);
+    const level = wcagLevel(ratio);
     if (level !== "AAA" && level !== "AA") {
-      failures.push({ pair: label, ratio: Math.round(ratio2 * 100) / 100, level, required: "AA" });
+      failures.push({ pair: label, ratio: Math.round(ratio * 100) / 100, level, required: "AA" });
     }
   }
   return failures;
@@ -257,6 +257,7 @@ __export(ansi_exports, {
   ESC: () => ESC,
   OSC: () => OSC,
   beginSyncUpdate: () => beginSyncUpdate,
+  bell: () => bell,
   blink: () => blink,
   bold: () => bold,
   clearDown: () => clearDown,
@@ -265,15 +266,21 @@ __export(ansi_exports, {
   clearLineToStart: () => clearLineToStart,
   clearScreen: () => clearScreen,
   clearUp: () => clearUp,
+  clipboard: () => clipboard,
+  cursorShape: () => cursorShape,
   dim: () => dim,
   disableBracketedPaste: () => disableBracketedPaste,
+  disableFocusTracking: () => disableFocusTracking,
   disableMouse: () => disableMouse,
   enableBracketedPaste: () => enableBracketedPaste,
+  enableFocusTracking: () => enableFocusTracking,
   enableMouse: () => enableMouse,
   endSyncUpdate: () => endSyncUpdate,
   enterAltScreen: () => enterAltScreen,
   exitAltScreen: () => exitAltScreen,
   hideCursor: () => hideCursor,
+  hyperlinkClose: () => hyperlinkClose,
+  hyperlinkOpen: () => hyperlinkOpen,
   inverse: () => inverse,
   italic: () => italic,
   moveDown: () => moveDown,
@@ -281,6 +288,9 @@ __export(ansi_exports, {
   moveRight: () => moveRight,
   moveTo: () => moveTo,
   moveUp: () => moveUp,
+  notify: () => notify,
+  readClipboard: () => readClipboard,
+  requestCursorPosition: () => requestCursorPosition,
   reset: () => reset,
   resetBlink: () => resetBlink,
   resetBold: () => resetBold,
@@ -296,6 +306,7 @@ __export(ansi_exports, {
   setTitle: () => setTitle,
   showCursor: () => showCursor,
   strikethrough: () => strikethrough,
+  stripAnsiControl: () => stripAnsiControl,
   underline: () => underline,
   writeClipboard: () => writeClipboard
 });
@@ -306,6 +317,15 @@ var hideCursor = `${CSI}?25l`;
 var showCursor = `${CSI}?25h`;
 var saveCursorPosition = `${CSI}s`;
 var restoreCursorPosition = `${CSI}u`;
+function cursorShape(shape, blink2 = true) {
+  const codes = {
+    block: 1,
+    underline: 3,
+    bar: 5
+  };
+  const code = codes[shape] + (blink2 ? 0 : 1);
+  return `${CSI}${code} q`;
+}
 function moveTo(col, row) {
   return `${CSI}${row + 1};${col + 1}H`;
 }
@@ -321,6 +341,7 @@ function moveRight(n = 1) {
 function moveLeft(n = 1) {
   return `${CSI}${n}D`;
 }
+var requestCursorPosition = `${CSI}6n`;
 var clearScreen = `${CSI}2J`;
 var clearLine = `${CSI}2K`;
 var clearLineToEnd = `${CSI}0K`;
@@ -335,6 +356,8 @@ var enableMouse = `${CSI}?1000h${CSI}?1002h${CSI}?1006h`;
 var disableMouse = `${CSI}?1000l${CSI}?1002l${CSI}?1006l`;
 var enableBracketedPaste = `${CSI}?2004h`;
 var disableBracketedPaste = `${CSI}?2004l`;
+var enableFocusTracking = `${CSI}?1004h`;
+var disableFocusTracking = `${CSI}?1004l`;
 var reset = `${CSI}0m`;
 var bold = `${CSI}1m`;
 var dim = `${CSI}2m`;
@@ -357,10 +380,52 @@ var resetScrollRegion = `${CSI}r`;
 function setTitle(title) {
   return `${OSC}0;${title}\x07`;
 }
+function hyperlinkOpen(url) {
+  if (!/^(https?|file):\/\//i.test(url)) return "";
+  const safeUrl = url.replace(/[\u0000-\u001F\u007F-\u009F\u001B]/g, "");
+  return `\x1B]8;;${safeUrl}\x1B\\`;
+}
+var hyperlinkClose = "\x1B]8;;\x1B\\";
+var bell = "\x07";
+function notify(text) {
+  const safeText = text.replace(/[\u0000-\u001F\u007F-\u009F\u001B]/g, "");
+  return `${OSC}9;${safeText}${bell}`;
+}
+function stripAnsiControl(str) {
+  let out = str.replace(
+    /\x1b(?:[@-Z\\-_]|\[[0-9;]*[a-zA-Z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[PX^_][^\x1b]*\x1b\\|.)/g,
+    ""
+  );
+  out = out.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, "");
+  return out;
+}
 function writeClipboard(text, stdout = process.stdout) {
   const encoded = Buffer.from(text, "utf8").toString("base64");
   stdout.write(`${OSC}52;c;${encoded}\x07`);
 }
+function readClipboard(stdin = process.stdin, stdout = process.stdout) {
+  return new Promise((resolve, reject) => {
+    const handler = (data) => {
+      const str = data.toString("utf8");
+      const match = str.match(/\x1b\]52;c;([^\x07]+)\x07/);
+      if (!match) return;
+      stdin.off("data", handler);
+      try {
+        resolve(
+          Buffer.from(match[1], "base64").toString("utf8")
+        );
+      } catch (err) {
+        reject(err);
+      }
+    };
+    stdin.on("data", handler);
+    stdout.write(`${OSC}52;c;?\x07`);
+  });
+}
+var clipboard = {
+  write: writeClipboard,
+  read: readClipboard
+};
 
 // src/terminal/Terminal.ts
 var Terminal = class {
@@ -372,32 +437,55 @@ var Terminal = class {
   _isRawMode = false;
   _isAltScreen = false;
   _isMouseEnabled = false;
+  _isBracketedPasteEnabled = false;
   _resizeHandlers = [];
   _cleanupHandlers = [];
   _originalRawMode;
+  // Debounce state properties
+  _resizeDebounceMs;
+  _resizeTimer = null;
+  _lastDispatchedCols;
+  _lastDispatchedRows;
   // Stored handler references for proper cleanup
   _resizeHandler = null;
   _exitHandler = null;
-  _sigintHandler = null;
-  _sigtermHandler = null;
-  _uncaughtExceptionHandler = null;
-  _unhandledRejectionHandler = null;
   _restored = false;
+  _restoring = false;
+  // Stream write queue state to prevent interleaving backpressure fragmentation
+  _writeQueue = [];
+  _isWriting = false;
   constructor(options = {}) {
     this.stdout = options.stdout ?? process.stdout;
     this.stdin = options.stdin ?? process.stdin;
     this.colorDepth = options.colorDepth ?? detectColorDepth();
     this._cols = this.stdout.columns ?? 80;
     this._rows = this.stdout.rows ?? 24;
+    this._resizeDebounceMs = options.resizeDebounceMs ?? 16;
+    this._lastDispatchedCols = this._cols;
+    this._lastDispatchedRows = this._rows;
     this._resizeHandler = () => {
       this._cols = this.stdout.columns ?? 80;
       this._rows = this.stdout.rows ?? 24;
-      for (const handler of this._resizeHandlers) {
-        handler(this._cols, this._rows);
+      if (this._resizeTimer) {
+        clearTimeout(this._resizeTimer);
       }
+      this._resizeTimer = setTimeout(() => {
+        this._resizeTimer = null;
+        if (this._cols !== this._lastDispatchedCols || this._rows !== this._lastDispatchedRows) {
+          this._lastDispatchedCols = this._cols;
+          this._lastDispatchedRows = this._rows;
+          const handlers = [...this._resizeHandlers];
+          for (const handler of handlers) {
+            handler(this._cols, this._rows);
+          }
+        }
+      }, this._resizeDebounceMs);
     };
     this.stdout.on("resize", this._resizeHandler);
     this._setupCleanup();
+    if (options.bracketedPaste) {
+      this.enableBracketedPaste();
+    }
   }
   /** Current terminal width in columns */
   get cols() {
@@ -451,6 +539,18 @@ var Terminal = class {
     this.write(disableMouse);
     this._isMouseEnabled = false;
   }
+  /** Emit the enable sequence (CSI ?2004h). Idempotent. */
+  enableBracketedPaste() {
+    if (this._isBracketedPasteEnabled) return;
+    this.write(enableBracketedPaste);
+    this._isBracketedPasteEnabled = true;
+  }
+  /** Emit the disable sequence (CSI ?2004l). Idempotent. */
+  disableBracketedPaste() {
+    if (!this._isBracketedPasteEnabled) return;
+    this.write(disableBracketedPaste);
+    this._isBracketedPasteEnabled = false;
+  }
   // ── Cursor ──────────────────────────────────────────
   hideCursor() {
     this.write(hideCursor);
@@ -458,10 +558,71 @@ var Terminal = class {
   showCursor() {
     this.write(showCursor);
   }
+  /** Set the cursor shape via DECSCUSR. Default blink = true. */
+  setCursorShape(shape, blink2) {
+    this.write(cursorShape(shape, blink2));
+  }
+  /** Ring the terminal bell (BEL). */
+  bell() {
+    this.write(bell);
+  }
+  /** Send an OSC 9 desktop notification. Body is appended after a separator. */
+  notify(title, body) {
+    const payload = body === void 0 ? title : `${title}: ${body}`;
+    this.write(notify(payload));
+  }
   // ── Output ──────────────────────────────────────────
+  /**
+   * Writes chunked string data to stdout.
+   * Enforces queue serialization to ensure atomic ANSI escape execution.
+   */
   write(data) {
+    if (!data) return;
+    this._writeQueue.push(data);
+    if (this._isWriting) return;
+    this._processWriteQueue();
+  }
+  /**
+   * Writes data to stdout synchronously, bypassing the write queue.
+   * Used by the renderer during frame flush to avoid races with the
+   * async queue lifecycle. Only use for render-path output.
+   */
+  writeSync(data) {
+    if (!data) return;
     this.stdout.write(data);
   }
+  /**
+   * Sequentially unshifts and drains string frames to stdout safely.
+   */
+  _processWriteQueue() {
+    if (this._writeQueue.length === 0) {
+      this._isWriting = false;
+      return;
+    }
+    this._isWriting = true;
+    const chunk = this._writeQueue.shift();
+    const canContinue = this.stdout.write(chunk);
+    if (!canContinue) {
+      this.stdout.once("drain", () => {
+        this._processWriteQueue();
+      });
+    } else {
+      this._processWriteQueue();
+    }
+  }
+  // ── Clipboard ───────────────────────────────────────
+  /**
+   * Read text from the system clipboard via OSC 52.
+   */
+  readClipboard() {
+    return readClipboard(this.stdin, this.stdout);
+  }
+  /**
+   * Write text to the system clipboard via OSC 52.
+   */
+  writeClipboard(text) {
+    writeClipboard(text, this.stdout);
+  }
   // ── Resize ──────────────────────────────────────────
   onResize(handler) {
     this._resizeHandlers.push(handler);
@@ -477,27 +638,35 @@ var Terminal = class {
    * Called automatically on SIGINT, SIGTERM, process exit.
    */
   restore() {
-    if (this._restored) return;
-    this._restored = true;
-    if (this._exitHandler) process.off("exit", this._exitHandler);
-    if (this._sigintHandler) process.off("SIGINT", this._sigintHandler);
-    if (this._sigtermHandler) process.off("SIGTERM", this._sigtermHandler);
-    if (this._uncaughtExceptionHandler) {
-      process.off("uncaughtException", this._uncaughtExceptionHandler);
-      this._uncaughtExceptionHandler = null;
-    }
-    if (this._unhandledRejectionHandler) {
-      process.off("unhandledRejection", this._unhandledRejectionHandler);
-      this._unhandledRejectionHandler = null;
+    if (this._restored || this._restoring) return;
+    this._restoring = true;
+    if (this._resizeTimer) {
+      clearTimeout(this._resizeTimer);
+      this._resizeTimer = null;
     }
+    this._writeQueue = [];
+    this._isWriting = false;
+    if (this._exitHandler) process.off("exit", this._exitHandler);
     if (this._resizeHandler) {
       this.stdout.off("resize", this._resizeHandler);
     }
-    this.disableMouse();
-    this.exitAltScreen();
-    this.exitRawMode();
-    this.showCursor();
-    this.write(reset);
+    const directWrite = this.stdout.write.bind(this.stdout);
+    const savedWrite = this.write;
+    this.write = (s) => {
+      directWrite(s);
+    };
+    try {
+      this.disableBracketedPaste();
+      this.disableMouse();
+      this.exitAltScreen();
+      this.exitRawMode();
+      this.showCursor();
+      this.write(reset);
+      this._restored = true;
+    } finally {
+      this.write = savedWrite;
+      this._restoring = false;
+    }
   }
   /**
    * Register a custom cleanup handler that runs on terminal restore.
@@ -507,7 +676,8 @@ var Terminal = class {
   }
   _setupCleanup() {
     const runCleanupHandlers = () => {
-      for (const handler of this._cleanupHandlers) {
+      const handlers = [...this._cleanupHandlers];
+      for (const handler of handlers) {
         try {
           handler();
         } catch {
@@ -516,30 +686,209 @@ var Terminal = class {
       this.restore();
     };
     this._exitHandler = runCleanupHandlers;
-    this._sigintHandler = () => {
-      runCleanupHandlers();
-      process.exit(130);
-    };
-    this._sigtermHandler = () => {
-      runCleanupHandlers();
-      process.exit(143);
-    };
     process.on("exit", this._exitHandler);
-    process.on("SIGINT", this._sigintHandler);
-    process.on("SIGTERM", this._sigtermHandler);
-    this._uncaughtExceptionHandler = (err) => {
-      this.restore();
-      process.exit(1);
-    };
-    this._unhandledRejectionHandler = () => {
-      this.restore();
-      process.exit(1);
-    };
-    process.on("uncaughtException", this._uncaughtExceptionHandler);
-    process.on("unhandledRejection", this._unhandledRejectionHandler);
   }
 };
 
+// src/utils/unicode.ts
+function isWideChar(codePoint) {
+  return (
+    // CJK Unified Ideographs (common Chinese/Japanese/Korean)
+    codePoint >= 19968 && codePoint <= 40959 || // CJK Unified Ideographs Extension A
+    codePoint >= 13312 && codePoint <= 19903 || // CJK Compatibility Ideographs
+    codePoint >= 63744 && codePoint <= 64255 || // Hangul Syllables
+    codePoint >= 44032 && codePoint <= 55215 || // Katakana
+    codePoint >= 12448 && codePoint <= 12543 || // CJK Symbols and Punctuation
+    codePoint >= 12288 && codePoint <= 12351 || // Hiragana
+    codePoint >= 12352 && codePoint <= 12447 || // Fullwidth Forms
+    codePoint >= 65281 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || // CJK Unified Ideographs Extension B
+    codePoint >= 131072 && codePoint <= 173791 || // CJK Unified Ideographs Extension C,D,E,F
+    codePoint >= 173824 && codePoint <= 191471 || // CJK Compatibility Ideographs Supplement
+    codePoint >= 194560 && codePoint <= 195103
+  );
+}
+function isCombining(codePoint) {
+  return (
+    // Combining Diacritical Marks
+    codePoint >= 768 && codePoint <= 879 || // Combining Diacritical Marks Extended
+    codePoint >= 6832 && codePoint <= 6911 || // Combining Diacritical Marks Supplement
+    codePoint >= 7616 && codePoint <= 7679 || // Combining Diacritical Marks for Symbols
+    codePoint >= 8400 && codePoint <= 8447 || // Combining Half Marks
+    codePoint >= 65056 && codePoint <= 65071 || // Variation selectors
+    codePoint >= 65024 && codePoint <= 65039 || // Zero-width joiner / non-joiner
+    codePoint === 8203 || codePoint === 8204 || codePoint === 8205 || codePoint === 65279
+  );
+}
+function isEmoji(codePoint) {
+  return (
+    // Emoticons
+    codePoint >= 128512 && codePoint <= 128591 || // Misc Symbols and Pictographs
+    codePoint >= 127744 && codePoint <= 128511 || // Transport and Map
+    codePoint >= 128640 && codePoint <= 128767 || // Supplemental Symbols
+    codePoint >= 129280 && codePoint <= 129535 || // Misc symbols
+    codePoint >= 9728 && codePoint <= 9983 || // Dingbats
+    codePoint >= 9984 && codePoint <= 10175 || // Flags
+    codePoint >= 127456 && codePoint <= 127487
+  );
+}
+var segmenter = new Intl.Segmenter();
+function segmentWidth(segment) {
+  const cp = segment.codePointAt(0);
+  if (cp < 32 || cp >= 127 && cp < 160) {
+    return 0;
+  }
+  if (isCombining(cp)) {
+    return 0;
+  }
+  const charCount = [...segment].length;
+  let isMultiCpWide = false;
+  if (charCount > 1) {
+    const cps = [...segment].map((c) => c.codePointAt(0));
+    isMultiCpWide = cps.slice(1).some((c) => !isCombining(c));
+  }
+  if (isWideChar(cp) || isEmoji(cp) || isMultiCpWide) {
+    return 2;
+  }
+  return 1;
+}
+function stringWidth(str) {
+  let width = 0;
+  let inEscape = false;
+  const segments = segmenter.segment(str);
+  for (const { segment } of segments) {
+    const cp = segment.codePointAt(0);
+    if (cp === 27) {
+      inEscape = true;
+      continue;
+    }
+    if (inEscape) {
+      if (cp >= 64 && cp <= 126 && cp !== 91) {
+        inEscape = false;
+      }
+      continue;
+    }
+    width += segmentWidth(segment);
+  }
+  return width;
+}
+function truncate(str, maxWidth, ellipsis = "\u2026") {
+  if (maxWidth <= 0) return "";
+  const strW = stringWidth(str);
+  if (strW <= maxWidth) return str;
+  const ellipsisW = stringWidth(ellipsis);
+  const targetW = maxWidth - ellipsisW;
+  if (targetW <= 0) return ellipsis.slice(0, maxWidth);
+  let width = 0;
+  let result = "";
+  let inEscape = false;
+  let escapeBuffer = "";
+  const segments = segmenter.segment(str);
+  for (const { segment } of segments) {
+    const cp = segment.codePointAt(0);
+    if (cp === 27) {
+      inEscape = true;
+      escapeBuffer += segment;
+      continue;
+    }
+    if (inEscape) {
+      escapeBuffer += segment;
+      if (cp >= 64 && cp <= 126 && cp !== 91) {
+        inEscape = false;
+        result += escapeBuffer;
+        escapeBuffer = "";
+      }
+      continue;
+    }
+    let charW = segmentWidth(segment);
+    if (width + charW > targetW) break;
+    width += charW;
+    result += segment;
+  }
+  return result + ellipsis;
+}
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+function wordWrap(str, width) {
+  if (width <= 0) return str;
+  const lines = str.split("\n");
+  const result = [];
+  for (const line of lines) {
+    if (stringWidth(line) <= width) {
+      result.push(line);
+      continue;
+    }
+    let currentLine = "";
+    let currentWidth = 0;
+    const words = line.split(/(\s+)/);
+    for (const word of words) {
+      const wordW = stringWidth(word);
+      if (currentWidth + wordW <= width) {
+        currentLine += word;
+        currentWidth += wordW;
+      } else if (wordW > width) {
+        if (currentLine) {
+          result.push(currentLine);
+          currentLine = "";
+          currentWidth = 0;
+        }
+        const wordSegments = segmenter.segment(word);
+        for (const { segment } of wordSegments) {
+          const charW = segmentWidth(segment);
+          if (currentWidth + charW > width) {
+            result.push(currentLine);
+            currentLine = "";
+            currentWidth = 0;
+          }
+          currentLine += segment;
+          currentWidth += charW;
+        }
+      } else {
+        result.push(currentLine);
+        currentLine = word.trimStart();
+        currentWidth = stringWidth(currentLine);
+      }
+    }
+    if (currentLine) {
+      result.push(currentLine);
+    }
+  }
+  return result.join("\n");
+}
+
+// src/terminal/env-caps.ts
+var caps = {
+  color: !process.env.NO_COLOR && process.env.TERM !== "dumb",
+  unicode: !process.env.NO_UNICODE && process.env.TERM !== "dumb",
+  motion: !process.env.NO_MOTION && !process.env.CI,
+  ci: !!process.env.CI,
+  get background() {
+    if (process.env.TERM_BACKGROUND === "light") return "light";
+    if (process.env.TERM_BACKGROUND === "dark") return "dark";
+    const colorfgbg = process.env.COLORFGBG;
+    if (colorfgbg) {
+      const parts = colorfgbg.split(";");
+      const bg = parseInt(parts[parts.length - 1], 10);
+      if (!Number.isNaN(bg)) return bg < 8 ? "dark" : "light";
+    }
+    return "dark";
+  },
+  get keybindingMode() {
+    const mode = process.env.TERMUI_KEYBINDINGS;
+    if (mode === "vim" || mode === "emacs") return mode;
+    return "default";
+  }
+};
+function prefersReducedMotion() {
+  return !caps.motion;
+}
+function shouldUseColor() {
+  return caps.color;
+}
+function prefersHighContrast() {
+  return process.env.HIGH_CONTRAST === "1";
+}
+
 // src/terminal/Screen.ts
 var EMPTY_COLOR = Object.freeze({ type: "none" });
 function emptyCell() {
@@ -553,7 +902,8 @@ function emptyCell() {
     dim: false,
     strikethrough: false,
     inverse: false,
-    width: 1
+    width: 1,
+    link: void 0
   };
 }
 function resetCell(cell) {
@@ -567,9 +917,10 @@ function resetCell(cell) {
   cell.strikethrough = false;
   cell.inverse = false;
   cell.width = 1;
+  cell.link = void 0;
 }
 function cellsEqual(a, b) {
-  return a.char === b.char && a.bold === b.bold && a.italic === b.italic && a.underline === b.underline && a.dim === b.dim && a.strikethrough === b.strikethrough && a.inverse === b.inverse && a.width === b.width && colorsEqual(a.fg, b.fg) && colorsEqual(a.bg, b.bg);
+  return a.char === b.char && a.bold === b.bold && a.italic === b.italic && a.underline === b.underline && a.dim === b.dim && a.strikethrough === b.strikethrough && a.inverse === b.inverse && a.width === b.width && a.link === b.link && colorsEqual(a.fg, b.fg) && colorsEqual(a.bg, b.bg);
 }
 function colorsEqual(a, b) {
   if (a.type !== b.type) return false;
@@ -583,25 +934,98 @@ function colorsEqual(a, b) {
     case "rgb":
       return a.r === b.r && a.g === b.g && a.b === b.b;
     case "hex":
-      return a.hex === b.hex;
+      return a.hex.toLowerCase() === b.hex.toLowerCase();
   }
 }
 var Screen = class {
   _cols;
   _rows;
+  _previousLines = [];
+  _lastRenderedHeight = 0;
+  get lastRenderedHeight() {
+    return this._lastRenderedHeight;
+  }
+  set lastRenderedHeight(value) {
+    this._lastRenderedHeight = value;
+  }
+  _previousStyleLines = [];
   front;
   back;
+  /**
+   * Render epoch counter. Incremented on every swap so downstream consumers
+   * (e.g. Renderer._flush) can detect and skip stale frames from a previous
+   * epoch, preventing double-swap corruption.
+   */
+  _epoch = 0;
+  /** True while swap() is executing to prevent re-entrant double-swap corruption. */
+  _swapping = false;
+  /** The epoch captured at the start of the current flush cycle. */
+  _flushEpoch = -1;
   /**
    * Stack of clipping regions. When non-empty, setCell/writeString
    * only write to cells within the topmost clip rectangle.
    */
   _clipStack = [];
+  _translateYStack = [];
+  _translateY = 0;
   constructor(cols, rows) {
     this._cols = cols;
     this._rows = rows;
     this.front = this._createGrid(cols, rows);
     this.back = this._createGrid(cols, rows);
   }
+  /** Retrieve a read-only copy of the cell at (x, y) from the back buffer. */
+  getCell(x, y) {
+    x = Math.floor(x);
+    y = Math.floor(y);
+    if (!(x >= 0 && x < this._cols && y >= 0 && y < this._rows)) return void 0;
+    return this.back[y][x];
+  }
+  /** Serialize a back-buffer row to a plain string (skips continuation cells). */
+  getLine(row) {
+    if (row < 0 || row >= this._rows) return "";
+    return this.back[row].filter((cell) => cell.width !== 0).map((cell) => cell.char || " ").join("");
+  }
+  /**
+   * Serialize the style attributes of a back-buffer row into a
+   * fingerprint string. When the characters are identical but the
+   * styles differ (color, bold, italic, etc.), this fingerprint
+   * changes, allowing the diff renderer to detect style-only updates.
+   */
+  getStyleLine(row) {
+    if (row < 0 || row >= this._rows) return "";
+    let hash = 0;
+    for (const cell of this.back[row]) {
+      if (cell.width === 0) continue;
+      const fg = cell.fg.type;
+      const bg = cell.bg.type;
+      const bits = (cell.bold ? 1 : 0) | (cell.italic ? 2 : 0) | (cell.underline ? 4 : 0) | (cell.dim ? 8 : 0) | (cell.strikethrough ? 16 : 0) | (cell.inverse ? 32 : 0);
+      const seed = fg.charCodeAt(0) * 65536 + bg.charCodeAt(0) * 4096 + bits;
+      hash = (hash << 7) - hash + seed | 0;
+      if (cell.link) {
+        for (let i = 0; i < cell.link.length; i++)
+          hash = (hash << 5) - hash + cell.link.charCodeAt(i) | 0;
+      }
+    }
+    return String(hash);
+  }
+  /** Return the saved line string for the given row (empty before first saveLines call). */
+  getPreviousLine(row) {
+    return this._previousLines[row] ?? "";
+  }
+  /** Return the saved style fingerprint for the given row. */
+  getPreviousStyleLine(row) {
+    return this._previousStyleLines[row] ?? "";
+  }
+  /** Snapshot the current back-buffer line strings for use by diffRenderer. */
+  saveLines() {
+    this._previousLines = [];
+    this._previousStyleLines = [];
+    for (let r = 0; r < this._rows; r++) {
+      this._previousLines.push(this.getLine(r));
+      this._previousStyleLines.push(this.getStyleLine(r));
+    }
+  }
   get cols() {
     return this._cols;
   }
@@ -642,12 +1066,21 @@ var Screen = class {
   get activeClip() {
     return this._clipStack.length > 0 ? this._clipStack[this._clipStack.length - 1] : null;
   }
+  pushTranslateY(offset) {
+    this._translateYStack.push(offset);
+    this._translateY += offset;
+  }
+  popTranslateY() {
+    const offset = this._translateYStack.pop() ?? 0;
+    this._translateY -= offset;
+  }
   /**
    * Write a cell to the back buffer at position (col, row).
    */
   setCell(col, row, cell) {
     col = Math.floor(col);
     row = Math.floor(row);
+    row += this._translateY;
     if (!(col >= 0 && col < this._cols && row >= 0 && row < this._rows)) return;
     if (this._clipStack.length > 0) {
       const clip = this._clipStack[this._clipStack.length - 1];
@@ -656,6 +1089,9 @@ var Screen = class {
       }
     }
     const existing = this.back[row][col];
+    if (cell.char !== void 0) {
+      cell = { ...cell, char: stripAnsiControl(cell.char) };
+    }
     Object.assign(existing, cell);
   }
   /**
@@ -666,31 +1102,37 @@ var Screen = class {
     row = Math.floor(row);
     col = Math.floor(col);
     if (!(row >= 0 && row < this._rows)) return;
+    const safeStr = stripAnsiControl(str);
     let x = col;
-    for (const char of str) {
+    const segments = segmenter.segment(safeStr);
+    for (const { segment } of segments) {
       if (x >= this._cols) break;
+      let finalChar = segment;
+      let width = stringWidth(segment);
       if (x < 0) {
-        x++;
+        x += width;
         continue;
       }
-      const cp = char.codePointAt(0);
-      const isWide = this._isWideCodePoint(cp);
-      const width = isWide ? 2 : 1;
+      if (width > 1 && !caps.unicode) {
+        finalChar = "*";
+        width = 1;
+      }
+      if (width === 0) continue;
       this.setCell(x, row, {
-        char,
+        char: finalChar,
         width,
         ...style
       });
-      if (isWide && x + 1 < this._cols) {
-        this.setCell(x + 1, row, {
-          char: "",
-          width: 0,
-          ...style
-        });
-        x += 2;
-      } else {
-        x += 1;
+      for (let i = 1; i < width; i++) {
+        if (x + i < this._cols) {
+          this.setCell(x + i, row, {
+            char: "",
+            width: 0,
+            ...style
+          });
+        }
       }
+      x += width;
     }
   }
   /**
@@ -704,13 +1146,34 @@ var Screen = class {
       }
     }
   }
+  /** Current render epoch — incremented after each swap. */
+  get epoch() {
+    return this._epoch;
+  }
+  /** The epoch captured at the start of the current flush cycle. */
+  get flushEpoch() {
+    return this._flushEpoch;
+  }
+  set flushEpoch(value) {
+    this._flushEpoch = value;
+  }
   /**
    * Swap front and back buffers. Called after rendering diffs.
+   * Uses mutual exclusion to prevent double-swap corruption when
+   * _flush() is called concurrently (e.g. from duplicate setImmediate
+   * callbacks).
    */
   swap() {
-    const temp = this.front;
-    this.front = this.back;
-    this.back = temp;
+    if (this._swapping) return;
+    this._swapping = true;
+    try {
+      const temp = this.front;
+      this.front = this.back;
+      this.back = temp;
+      this._epoch++;
+    } finally {
+      this._swapping = false;
+    }
   }
   /**
    * Resize the screen. Clears both buffers.
@@ -720,17 +1183,43 @@ var Screen = class {
     this._rows = rows;
     this.front = this._createGrid(cols, rows);
     this.back = this._createGrid(cols, rows);
+    this._previousLines = [];
   }
   /**
    * Clear the front buffer (marks everything as "needs redraw").
+   * Mutates cells in-place to avoid GC pressure from object allocation.
    */
   invalidate() {
     for (let r = 0; r < this._rows; r++) {
       for (let c = 0; c < this._cols; c++) {
-        this.front[r][c] = { ...emptyCell(), char: "\0" };
+        resetCell(this.front[r][c]);
+        this.front[r][c].char = "\0";
       }
     }
   }
+  /**
+   * Export current screen as ANSI snapshot text.
+   */
+  exportANSI() {
+    const lines = [];
+    for (let r = 0; r < this._rows; r++) {
+      lines.push(this.getLine(r));
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Export current screen as SVG.
+   */
+  exportSVG() {
+    return `
+<svg xmlns="http://www.w3.org/2000/svg"
+     width="${this._cols * 8}"
+     height="${this._rows * 16}">
+    <text x="10" y="20">
+        Terminal Export
+    </text>
+</svg>`;
+  }
   _createGrid(cols, rows) {
     const grid = [];
     for (let r = 0; r < rows; r++) {
@@ -742,25 +1231,74 @@ var Screen = class {
     }
     return grid;
   }
-  _isWideCodePoint(cp) {
-    return cp >= 19968 && cp <= 40959 || cp >= 13312 && cp <= 19903 || cp >= 63744 && cp <= 64255 || cp >= 44032 && cp <= 55215 || cp >= 12448 && cp <= 12543 || cp >= 12288 && cp <= 12351 || cp >= 12352 && cp <= 12447 || cp >= 65281 && cp <= 65376 || cp >= 65504 && cp <= 65510 || cp >= 128512 && cp <= 128591 || cp >= 127744 && cp <= 128511 || cp >= 128640 && cp <= 128767 || cp >= 129280 && cp <= 129535 || cp >= 131072 && cp <= 173791;
+};
+
+// src/renderer/render-hook.ts
+var RenderHook = class {
+  _buffer = [];
+  _isActive = false;
+  _originalConsole = {};
+  // any[]: console methods accept arbitrary argument shapes
+  /** Check if the hook is currently intercepting console output */
+  get isActive() {
+    return this._isActive;
+  }
+  /** Wrap console.log/warn/error to buffer external logs instead of writing to stdout */
+  start() {
+    if (this._isActive) return;
+    this._isActive = true;
+    const methods = ["log", "warn", "error"];
+    for (const method of methods) {
+      this._originalConsole[method] = console[method];
+      const hook = this;
+      console[method] = function(...args) {
+        const text = args.map((a) => typeof a === "string" ? a : String(a)).join(" ");
+        hook._buffer.push(text + "\n");
+      };
+    }
+  }
+  /** Restore original console methods */
+  stop() {
+    if (!this._isActive) return;
+    this._isActive = false;
+    for (const [method, original] of Object.entries(this._originalConsole)) {
+      console[method] = original;
+    }
+    this._originalConsole = {};
+  }
+  /** Retrieve and clear the buffered logs */
+  flush() {
+    if (this._buffer.length === 0) return "";
+    const out = this._buffer.join("");
+    this._buffer = [];
+    return out;
+  }
+  /** Write directly to process.stdout, bypassing any buffering */
+  writeRaw(text) {
+    process.stdout.write(text);
   }
 };
 
 // src/terminal/Renderer.ts
-var Renderer = class {
+var Renderer = class _Renderer {
   _terminal;
   _screen;
   _fps;
   _frameTimer = null;
   _renderRequested = false;
   _colorDepth;
+  _diffRenderer;
   _onTick = null;
-  constructor(terminal, screen, fps = 30) {
+  _callbacks = /* @__PURE__ */ new Set();
+  /** The stdout interceptor hook for buffering external logs */
+  hook;
+  constructor(terminal, screen, fps = 30, diffRenderer = true) {
     this._terminal = terminal;
     this._screen = screen;
     this._fps = fps;
     this._colorDepth = terminal.colorDepth;
+    this._diffRenderer = diffRenderer;
+    this.hook = new RenderHook();
   }
   /** Change the rendering frame rate cap */
   setFPS(fps) {
@@ -777,10 +1315,6 @@ var Renderer = class {
     const interval = Math.floor(1e3 / this._fps);
     this._frameTimer = setInterval(() => {
       this._onTick?.();
-      if (this._renderRequested) {
-        this._renderRequested = false;
-        this._flush();
-      }
     }, interval);
   }
   /** Stop the render loop */
@@ -798,6 +1332,13 @@ var Renderer = class {
   renderNow() {
     this._flush();
   }
+  /** Register a per-frame profiling callback. Returns an unsubscribe function. */
+  onFrame(cb) {
+    this._callbacks.add(cb);
+    return () => {
+      this._callbacks.delete(cb);
+    };
+  }
   /**
    * Full-screen clear and redraw (first render or after resize).
    */
@@ -805,51 +1346,210 @@ var Renderer = class {
     this._screen.invalidate();
     this._flush();
   }
+  /** ANSI sequence to save cursor position */
+  static _CURSOR_SAVE = "\x1B[s";
+  /** ANSI sequence to restore cursor position */
+  static _CURSOR_RESTORE = "\x1B[u";
   /**
    * Core diff and flush: compare front vs back buffer,
    * emit only changed cells.
    */
   _flush() {
-    const { front, back, cols, rows } = this._screen;
-    let output = beginSyncUpdate;
-    let lastRow = -1;
-    let lastCol = -1;
-    for (let r = 0; r < rows; r++) {
-      for (let c = 0; c < cols; c++) {
-        const frontCell = front[r][c];
-        const backCell = back[r][c];
-        if (cellsEqual(frontCell, backCell)) continue;
-        if (backCell.width === 0) continue;
-        if (r !== lastRow || c !== lastCol) {
-          output += moveTo(c, r);
+    const epoch = this._screen.epoch;
+    if (this._screen.flushEpoch === epoch) return;
+    this._screen.flushEpoch = epoch;
+    const start = this._callbacks.size > 0 ? performance.now() : 0;
+    const bufferedLogs = this.hook.flush();
+    if (bufferedLogs) {
+      this._screen.invalidate();
+    }
+    try {
+      const { front, back, cols, rows } = this._screen;
+      let output = beginSyncUpdate;
+      if (this._diffRenderer) {
+        this._lastStyleFingerprint = null;
+        for (let r = 0; r < rows; r++) {
+          output += this._renderDiffLine(r, front, back, cols);
+        }
+        output += reset;
+        output += endSyncUpdate;
+        if (bufferedLogs) {
+          this._terminal.writeSync(_Renderer._CURSOR_SAVE + bufferedLogs + _Renderer._CURSOR_RESTORE);
         }
-        output += this._renderCell(backCell);
-        lastRow = r;
-        lastCol = c + (backCell.width === 2 ? 2 : 1);
+        this._terminal.writeSync(output);
+        this._screen.saveLines();
+        this._emitStats(start, bufferedLogs, output);
+        this._screen.swap();
+        return;
+      }
+      for (let r = 0; r < rows; r++) {
+        if (this._screen.getLine(r) === this._screen.getPreviousLine(r) && this._screen.getStyleLine(r) === this._screen.getPreviousStyleLine(r)) continue;
+        output += moveTo(0, r);
+        output += this._renderLine(r);
       }
+      output += reset;
+      output += endSyncUpdate;
+      if (bufferedLogs) {
+        this._terminal.writeSync(_Renderer._CURSOR_SAVE + bufferedLogs + _Renderer._CURSOR_RESTORE);
+      }
+      this._terminal.writeSync(output);
+      this._emitStats(start, bufferedLogs, output);
+      this._screen.saveLines();
+      this._screen.swap();
+    } catch (_err) {
+      this._renderRequested = true;
+      this._lastStyleFingerprint = null;
+    }
+  }
+  /** Style fingerprint of the last rendered cell (to suppress redundant ANSI reset/apply). */
+  _lastStyleFingerprint = null;
+  /** Build a stable style fingerprint string for a cell (avoids allocation-heavy object comparison). */
+  _styleFingerprint(cell) {
+    const fg = cell.fg;
+    const bg = cell.bg;
+    let fgKey;
+    switch (fg.type) {
+      case "none":
+        fgKey = "n";
+        break;
+      case "named":
+        fgKey = `N:${fg.name}`;
+        break;
+      case "ansi256":
+        fgKey = `A:${fg.code}`;
+        break;
+      case "rgb":
+        fgKey = `R:${fg.r},${fg.g},${fg.b}`;
+        break;
+      case "hex":
+        fgKey = `H:${fg.hex.toLowerCase()}`;
+        break;
+      default:
+        fgKey = "n";
+    }
+    let bgKey;
+    switch (bg.type) {
+      case "none":
+        bgKey = "n";
+        break;
+      case "named":
+        bgKey = `N:${bg.name}`;
+        break;
+      case "ansi256":
+        bgKey = `A:${bg.code}`;
+        break;
+      case "rgb":
+        bgKey = `R:${bg.r},${bg.g},${bg.b}`;
+        break;
+      case "hex":
+        bgKey = `H:${bg.hex.toLowerCase()}`;
+        break;
+      default:
+        bgKey = "n";
     }
-    output += reset;
-    output += endSyncUpdate;
-    this._terminal.write(output);
-    this._screen.swap();
+    return `${cell.bold ? "B" : ""}${cell.dim ? "D" : ""}${cell.italic ? "I" : ""}${cell.underline ? "U" : ""}${cell.strikethrough ? "S" : ""}${cell.inverse ? "V" : ""}|${fgKey}|${bgKey}`;
   }
   /**
    * Generate the ANSI escape sequence to render a single cell.
+   * Skips ansiReset + re-apply when the adjacent cell has identical style.
    */
   _renderCell(cell) {
     let seq = "";
-    seq += reset;
-    if (cell.bold) seq += "\x1B[1m";
-    if (cell.dim) seq += "\x1B[2m";
-    if (cell.italic) seq += "\x1B[3m";
-    if (cell.underline) seq += "\x1B[4m";
-    if (cell.strikethrough) seq += "\x1B[9m";
-    if (cell.inverse) seq += "\x1B[7m";
-    seq += colorToAnsiFg(cell.fg, this._colorDepth);
-    seq += colorToAnsiBg(cell.bg, this._colorDepth);
-    seq += cell.char || " ";
+    const fp = this._styleFingerprint(cell);
+    if (fp !== this._lastStyleFingerprint) {
+      seq += reset;
+      if (cell.bold) seq += "\x1B[1m";
+      if (cell.dim) seq += "\x1B[2m";
+      if (cell.italic) seq += "\x1B[3m";
+      if (cell.underline) seq += "\x1B[4m";
+      if (cell.strikethrough) seq += "\x1B[9m";
+      if (cell.inverse) seq += "\x1B[7m";
+      seq += colorToAnsiFg(cell.fg, this._colorDepth);
+      seq += colorToAnsiBg(cell.bg, this._colorDepth);
+      this._lastStyleFingerprint = fp;
+    }
+    seq += stripAnsiControl(cell.char) || " ";
     return seq;
   }
+  /**
+   * If a span starts at a width-0 continuation cell (the second half of a
+   * wide character), adjust backward to the preceding cell so the cursor
+   * is placed at a valid column boundary.
+   */
+  static _adjustSpanStart(col, row) {
+    while (col > 0 && row[col].width === 0) {
+      col--;
+    }
+    return col;
+  }
+  /**
+   * Render only the changed spans within a single row (cell-level granularity).
+   * Uses moveTo to position the cursor at the start of each changed span.
+   */
+  _renderDiffLine(row, front, back, cols) {
+    let output = "";
+    let spanStart = -1;
+    for (let c = 0; c < cols; c++) {
+      if (back[row][c].width === 0) continue;
+      const changed = !cellsEqual(front[row][c], back[row][c]);
+      if (changed && spanStart === -1) {
+        spanStart = c;
+      } else if (!changed && spanStart !== -1) {
+        const adjustedStart = _Renderer._adjustSpanStart(spanStart, back[row]);
+        output += moveTo(adjustedStart, row);
+        for (let sc = spanStart; sc < c; sc++) {
+          const cell = back[row][sc];
+          if (cell.width === 0) continue;
+          output += this._renderCell(cell);
+        }
+        spanStart = -1;
+      }
+    }
+    if (spanStart !== -1) {
+      const adjustedStart = _Renderer._adjustSpanStart(spanStart, back[row]);
+      output += moveTo(adjustedStart, row);
+      for (let sc = spanStart; sc < cols; sc++) {
+        const cell = back[row][sc];
+        if (cell.width === 0) continue;
+        output += this._renderCell(cell);
+      }
+    }
+    return output;
+  }
+  _renderLine(row) {
+    let output = "";
+    for (let c = 0; c < this._screen.cols; c++) {
+      const cell = this._screen.back[row][c];
+      if (cell.width === 0) continue;
+      output += this._renderCell(cell);
+    }
+    return output;
+  }
+  _emitStats(start, bufferedLogs, output) {
+    if (this._callbacks.size === 0) return;
+    const durationMs = performance.now() - start;
+    const { front, back, cols, rows } = this._screen;
+    let cellsChanged = 0;
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        if (!cellsEqual(front[r][c], back[r][c])) {
+          cellsChanged++;
+        }
+      }
+    }
+    const bytesWritten = (bufferedLogs ? Buffer.byteLength(bufferedLogs) : 0) + Buffer.byteLength(output);
+    const stats = {
+      cellsChanged,
+      bytesWritten,
+      durationMs: Math.max(0, durationMs)
+    };
+    for (const cb of this._callbacks) {
+      try {
+        cb(stats);
+      } catch {
+      }
+    }
+  }
 };
 
 // src/terminal/LayerManager.ts
@@ -860,9 +1560,12 @@ var LayerManager = class {
   _layers = /* @__PURE__ */ new Map();
   _cols;
   _rows;
+  _hitWidgetGrid;
+  _hitZGrid;
   constructor(cols, rows) {
     this._cols = cols;
     this._rows = rows;
+    this._allocateHitGrids();
   }
   get cols() {
     return this._cols;
@@ -936,15 +1639,30 @@ var LayerManager = class {
     col = Math.floor(col);
     if (!(row >= 0 && row < this._rows)) return;
     let x = col;
-    for (const char of str) {
+    for (const { segment: char } of segmenter.segment(str)) {
       if (x >= this._cols) break;
+      const charWidth = segmentWidth(char);
       if (x < 0) {
-        x++;
+        x += charWidth;
         continue;
       }
-      this.setCell(layerId, x, row, { char, width: 1, ...style });
-      x++;
+      this.setCell(layerId, x, row, { char, width: charWidth, ...style });
+      if (charWidth === 2 && x + 1 < this._cols) {
+        this.setCell(layerId, x + 1, row, { char: " ", width: 1, ...style });
+      }
+      x += charWidth;
+    }
+  }
+  /**
+   * Check whether any visible layer has pending dirty changes.
+   */
+  hasDirtyLayers() {
+    for (const layer of this._layers.values()) {
+      if (layer.visible && layer.dirtyRegion) {
+        return true;
+      }
     }
+    return false;
   }
   /**
    * Clear all cells in a specific layer.
@@ -957,7 +1675,7 @@ var LayerManager = class {
         layer.cells[r][c] = emptyCell();
       }
     }
-    layer.dirtyRegion = null;
+    layer.dirtyRegion = { x: 0, y: 0, width: this._cols, height: this._rows };
   }
   /**
    * Clear all overlay layers.
@@ -971,28 +1689,29 @@ var LayerManager = class {
    * Composite all overlay layers onto the Screen's back buffer.
    * Layers are applied in z-index order (lowest first).
    * Transparent cells (empty with no colors) are skipped.
+   * Writes directly to screen.back to avoid setCell overhead
+   * (bounds/clip checks are already satisfied by dirtyRegion).
    */
   composite(screen) {
     const sorted = this.getSortedLayers();
     for (const layer of sorted) {
       if (!layer.dirtyRegion) continue;
       const { x: dx, y: dy, width: dw, height: dh } = layer.dirtyRegion;
-      for (let r = dy; r < dy + dh && r < this._rows; r++) {
-        for (let c = dx; c < dx + dw && c < this._cols; c++) {
-          const cell = layer.cells[r][c];
-          if (isCellTransparent(cell)) continue;
-          screen.setCell(c, r, {
-            char: cell.char,
-            fg: cell.fg,
-            bg: cell.bg,
-            bold: cell.bold,
-            italic: cell.italic,
-            underline: cell.underline,
-            dim: cell.dim,
-            strikethrough: cell.strikethrough,
-            inverse: cell.inverse,
-            width: cell.width
-          });
+      const maxRow = Math.min(dy + dh, this._rows);
+      const maxCol = Math.min(dx + dw, this._cols);
+      for (let r = dy; r < maxRow; r++) {
+        const backRow = screen.back[r];
+        const layerRow = layer.cells[r];
+        if (!backRow || !layerRow) continue;
+        let c = dx;
+        while (c < maxCol) {
+          const cell = layerRow[c];
+          if (isCellTransparent(cell)) {
+            c++;
+            continue;
+          }
+          Object.assign(backRow[c], cell);
+          c++;
         }
       }
     }
@@ -1007,6 +1726,41 @@ var LayerManager = class {
       layer.cells = this._createGrid();
       layer.dirtyRegion = null;
     }
+    this._allocateHitGrids();
+  }
+  /** Reset the hit grid. Call once at the start of each frame. */
+  clearHitGrid() {
+    this._allocateHitGrids();
+  }
+  /**
+   * Mark a rectangular region as owned by a widget at a given z-index.
+   * Higher z wins when regions overlap.
+   */
+  setHitRegion(widgetId, x, y, w, h, z) {
+    const zVal = z ?? 0;
+    const startX = Math.floor(x);
+    const startY = Math.floor(y);
+    const width = Math.floor(w);
+    const height = Math.floor(h);
+    for (let r = startY; r < startY + height; r++) {
+      if (r < 0 || r >= this._rows) continue;
+      for (let c = startX; c < startX + width; c++) {
+        if (c < 0 || c >= this._cols) continue;
+        if (zVal >= this._hitZGrid[r][c]) {
+          this._hitWidgetGrid[r][c] = widgetId;
+          this._hitZGrid[r][c] = zVal;
+        }
+      }
+    }
+  }
+  /** Return the topmost widget id at a cell, or null. */
+  hitTest(col, row) {
+    const c = Math.floor(col);
+    const r = Math.floor(row);
+    if (c < 0 || c >= this._cols || r < 0 || r >= this._rows) {
+      return null;
+    }
+    return this._hitWidgetGrid[r][c];
   }
   /**
    * Create an empty cell grid.
@@ -1022,6 +1776,23 @@ var LayerManager = class {
     }
     return grid;
   }
+  /**
+   * Allocate parallel hit grid and z-index grid.
+   */
+  _allocateHitGrids() {
+    this._hitWidgetGrid = [];
+    this._hitZGrid = [];
+    for (let r = 0; r < this._rows; r++) {
+      const widgetRow = [];
+      const zRow = [];
+      for (let c = 0; c < this._cols; c++) {
+        widgetRow.push(null);
+        zRow.push(-Infinity);
+      }
+      this._hitWidgetGrid.push(widgetRow);
+      this._hitZGrid.push(zRow);
+    }
+  }
   /**
    * Expand the dirty region of a layer to include the given cell.
    */
@@ -1042,14 +1813,6 @@ var LayerManager = class {
   }
 };
 
-// src/terminal/env-caps.ts
-var caps = {
-  color: !process.env.NO_COLOR && process.env.TERM !== "dumb",
-  unicode: !process.env.NO_UNICODE && process.env.TERM !== "dumb",
-  motion: !process.env.NO_MOTION && !process.env.CI,
-  ci: !!process.env.CI
-};
-
 // src/terminal/ascii-map.ts
 var BOX = {
   "\u250C": "+",
@@ -1078,6 +1841,93 @@ var BOX = {
 var BRAILLE_SPIN = ["|", "/", "-", "\\"];
 var BLOCK = { full: "#", empty: " ", partial: "-" };
 
+// src/terminal/bell.ts
+function bell2() {
+  if (typeof process !== "undefined" && process.stdout && process.stdout.write) {
+    process.stdout.write("\x07");
+  }
+}
+
+// src/renderer/border-merge.ts
+var VERTICAL = /* @__PURE__ */ new Set(["\u2502", "|"]);
+var HORIZONTAL = /* @__PURE__ */ new Set(["\u2500", "-"]);
+function isVertical(char) {
+  return VERTICAL.has(char);
+}
+function isHorizontal(char) {
+  return HORIZONTAL.has(char);
+}
+var UNICODE_JUNCTIONS = {
+  LRTB: "\u253C",
+  RTB: "\u251C",
+  LTB: "\u2524",
+  LRB: "\u252C",
+  LRT: "\u2534",
+  RB: "\u250C",
+  LB: "\u2510",
+  RT: "\u2514",
+  LT: "\u2518",
+  TB: "\u2502",
+  LR: "\u2500",
+  R: "\u2500",
+  L: "\u2500",
+  T: "\u2502",
+  B: "\u2502"
+};
+var ASCII_JUNCTIONS = {
+  LRTB: "+",
+  RTB: "+",
+  LTB: "+",
+  LRB: "+",
+  LRT: "+",
+  RB: "+",
+  LB: "+",
+  RT: "+",
+  LT: "+",
+  TB: "|",
+  LR: "-",
+  R: "-",
+  L: "-",
+  T: "|",
+  B: "|"
+};
+function getJunctions() {
+  return caps.unicode ? UNICODE_JUNCTIONS : ASCII_JUNCTIONS;
+}
+function mergeBorders(screen) {
+  const grid = screen.back;
+  const junctions = getJunctions();
+  const updates = [];
+  for (let row = 0; row < screen.rows; row++) {
+    for (let col = 0; col < screen.cols; col++) {
+      const cell = grid[row][col];
+      const top = row > 0 ? grid[row - 1][col].char : "";
+      const bottom = row < screen.rows - 1 ? grid[row + 1][col].char : "";
+      const left = col > 0 ? grid[row][col - 1].char : "";
+      const right = col < screen.cols - 1 ? grid[row][col + 1].char : "";
+      const hasTop = isVertical(top);
+      const hasBottom = isVertical(bottom);
+      const hasLeft = isHorizontal(left);
+      const hasRight = isHorizontal(right);
+      const key = (hasLeft ? "L" : "") + (hasRight ? "R" : "") + (hasTop ? "T" : "") + (hasBottom ? "B" : "");
+      const merged = junctions[key];
+      if (merged) {
+        updates.push({
+          row,
+          col,
+          char: merged
+        });
+      }
+    }
+  }
+  for (const update of updates) {
+    grid[update.row][update.col].char = update.char;
+  }
+}
+
+// src/input/InputParser.ts
+import { Buffer as Buffer2 } from "buffer";
+
 // src/events/types.ts
 function createKeyEvent(base) {
   const event = {
@@ -1180,6 +2030,19 @@ var SPECIAL_KEYS = {
   10: "enter",
   32: "space"
 };
+function normalizeNavigationKey(keyName) {
+  const mode = caps.keybindingMode;
+  if (mode === "vim") {
+    if (keyName === "k") return "up";
+    if (keyName === "j") return "down";
+    if (keyName === "h") return "left";
+    if (keyName === "l") return "right";
+  } else if (mode === "emacs") {
+    if (keyName === "ctrl+p") return "up";
+    if (keyName === "ctrl+n") return "down";
+  }
+  return keyName;
+}
 
 // src/input/MouseParser.ts
 function parseMouseEvent(data) {
@@ -1192,13 +2055,28 @@ function parseMouseEvent(data) {
   let button;
   let type;
   let scrollDelta;
+  let scrollDeltaX;
+  let scrollAxis;
   const buttonBits = cb & 3;
   const motion = (cb & 32) !== 0;
   const isScroll = (cb & 64) !== 0;
+  const shift = (cb & 4) !== 0;
+  const alt = (cb & 8) !== 0;
+  const ctrl = (cb & 16) !== 0;
   if (isScroll) {
     button = "none";
     type = "scroll";
-    scrollDelta = buttonBits === 0 ? -1 : 1;
+    const lowBits = cb & 7;
+    if (lowBits === 6) {
+      scrollAxis = "horizontal";
+      scrollDeltaX = -1;
+    } else if (lowBits === 7) {
+      scrollAxis = "horizontal";
+      scrollDeltaX = 1;
+    } else {
+      scrollAxis = "vertical";
+      scrollDelta = buttonBits === 0 ? -1 : 1;
+    }
   } else if (motion) {
     type = "mousemove";
     button = decodeButton(buttonBits);
@@ -1214,7 +2092,12 @@ function parseMouseEvent(data) {
     y: cy,
     button,
     type,
-    scrollDelta
+    ...scrollDelta !== void 0 && { scrollDelta },
+    ...scrollDeltaX !== void 0 && { scrollDeltaX },
+    ...scrollAxis !== void 0 && { scrollAxis },
+    shift,
+    alt,
+    ctrl
   };
 }
 function decodeButton(bits) {
@@ -1236,7 +2119,9 @@ function isMouseSequence(data) {
 // src/events/EventEmitter.ts
 var EventEmitter = class {
   _handlers = /* @__PURE__ */ new Map();
+  // any: handler type erased here; callers constrain via generics
   _onceHandlers = /* @__PURE__ */ new Map();
+  // any: handler type erased here; callers constrain via generics
   /**
    * Subscribe to an event.
    * @returns Unsubscribe function.
@@ -1276,7 +2161,7 @@ var EventEmitter = class {
       for (const handler of handlers) {
         try {
           handler(data);
-        } catch {
+        } catch (_err) {
         }
       }
     }
@@ -1285,7 +2170,7 @@ var EventEmitter = class {
       for (const handler of onceHandlers) {
         try {
           handler(data);
-        } catch {
+        } catch (_err) {
         }
       }
       onceHandlers.clear();
@@ -1317,7 +2202,10 @@ var InputParser = class {
   _stdin;
   _handler = null;
   _escapeTimeout = null;
-  _escapeBuffer = "";
+  _escapeBuffer = Buffer2.alloc(0);
+  _isPasting = false;
+  _pasteBuffer = "";
+  _cursorRequests = [];
   constructor(stdin) {
     this._stdin = stdin;
   }
@@ -1329,6 +2217,25 @@ var InputParser = class {
   onMouse(handler) {
     return this._events.on("mouse", handler);
   }
+  /** Subscribe to terminal focus-in (true) / focus-out (false) reports. */
+  onFocusChange(handler) {
+    return this._events.on("focuschange", handler);
+  }
+  onPaste(handler) {
+    return this._events.on("paste", handler);
+  }
+  requestCursorPosition(timeoutMs = 200) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const idx = this._cursorRequests.findIndex((item) => item.reject === reject);
+        if (idx !== -1) {
+          this._cursorRequests.splice(idx, 1);
+        }
+        reject(new Error("Cursor position request timed out"));
+      }, timeoutMs);
+      this._cursorRequests.push({ resolve, reject, timeout });
+    });
+  }
   /** Start listening for input */
   start() {
     if (this._handler) return;
@@ -1347,46 +2254,57 @@ var InputParser = class {
       clearTimeout(this._escapeTimeout);
       this._escapeTimeout = null;
     }
-    this._escapeBuffer = "";
+    this._escapeBuffer = Buffer2.alloc(0);
+    for (const req of this._cursorRequests) {
+      clearTimeout(req.timeout);
+      req.reject(new Error("InputParser stopped"));
+    }
+    this._cursorRequests = [];
   }
   /**
    * Process a chunk of raw input bytes.
    */
   _processInput(data) {
     const str = data.toString("utf8");
-    if (this._escapeBuffer) {
-      this._escapeBuffer += str;
+    const PASTE_START = "\x1B[200~";
+    const PASTE_END = "\x1B[201~";
+    if (str.includes(PASTE_START) && str.includes(PASTE_END)) {
+      const pastedText = str.replace(PASTE_START, "").replace(PASTE_END, "");
+      this._events.emit("paste", pastedText);
+      return;
+    }
+    if (this._escapeBuffer.length > 0) {
+      this._escapeBuffer = Buffer2.concat([this._escapeBuffer, data]);
       if (this._escapeTimeout) {
         clearTimeout(this._escapeTimeout);
         this._escapeTimeout = null;
       }
-      this._tryParseEscape(data);
+      this._tryParseEscape();
       return;
     }
     if (str.startsWith("\x1B") && str.length === 1) {
-      this._escapeBuffer = str;
+      this._escapeBuffer = data;
       this._escapeTimeout = setTimeout(() => {
         this._events.emit("key", createKeyEvent({
           key: "escape",
-          raw: Buffer.from(this._escapeBuffer),
+          raw: this._escapeBuffer,
           ctrl: false,
           alt: false,
           shift: false
         }));
-        this._escapeBuffer = "";
+        this._escapeBuffer = Buffer2.alloc(0);
         this._escapeTimeout = null;
       }, 50);
       return;
     }
     if (str.startsWith("\x1B")) {
-      this._escapeBuffer = str;
-      this._tryParseEscape(data);
+      this._escapeBuffer = data;
+      this._tryParseEscape();
       return;
     }
-    for (let i = 0; i < str.length; i++) {
-      const ch = str[i];
-      const code = str.charCodeAt(i);
-      const raw = Buffer.from(ch, "utf8");
+    for (const ch of str) {
+      const code = ch.codePointAt(0);
+      const raw = Buffer2.from(ch, "utf8");
       if (code >= 1 && code <= 26) {
         const keyName = CTRL_KEYS[code];
         const isCtrl = code !== 9 && code !== 13 && code !== 10;
@@ -1423,13 +2341,13 @@ var InputParser = class {
   /**
    * Try to parse buffered escape sequence.
    */
-  _tryParseEscape(rawData) {
-    const seq = this._escapeBuffer;
+  _tryParseEscape() {
+    const seq = this._escapeBuffer.toString("utf8");
     if (isMouseSequence(seq)) {
       const mouseEvt = parseMouseEvent(seq);
       if (mouseEvt) {
         this._events.emit("mouse", mouseEvt);
-        this._escapeBuffer = "";
+        this._escapeBuffer = Buffer2.alloc(0);
         return;
       }
       if (seq.length < 20) {
@@ -1438,12 +2356,35 @@ var InputParser = class {
           this._escapeTimeout = null;
         }
         this._escapeTimeout = setTimeout(() => {
-          this._escapeBuffer = "";
+          this._escapeBuffer = Buffer2.alloc(0);
           this._escapeTimeout = null;
         }, 100);
         return;
       }
     }
+    const cursorMatch = seq.match(/^\x1b\[(\d+);(\d+)R$/);
+    if (cursorMatch) {
+      const row = parseInt(cursorMatch[1], 10);
+      const col = parseInt(cursorMatch[2], 10);
+      const position = { row, col };
+      for (const request of this._cursorRequests) {
+        clearTimeout(request.timeout);
+        request.resolve(position);
+      }
+      this._cursorRequests = [];
+      this._escapeBuffer = Buffer2.alloc(0);
+      return;
+    }
+    if (seq === "\x1B[I") {
+      this._events.emit("focuschange", true);
+      this._escapeBuffer = Buffer2.alloc(0);
+      return;
+    }
+    if (seq === "\x1B[O") {
+      this._events.emit("focuschange", false);
+      this._escapeBuffer = Buffer2.alloc(0);
+      return;
+    }
     if (seq in ESCAPE_SEQUENCES) {
       const keyName = ESCAPE_SEQUENCES[seq];
       const isShift = keyName.startsWith("shift+");
@@ -1452,28 +2393,28 @@ var InputParser = class {
       const cleanKey = keyName.replace(/^(shift|ctrl|alt)\+/, "");
       this._events.emit("key", createKeyEvent({
         key: cleanKey,
-        raw: rawData,
+        raw: this._escapeBuffer,
         ctrl: isCtrl,
         alt: isAlt,
         shift: isShift
       }));
-      this._escapeBuffer = "";
+      this._escapeBuffer = Buffer2.alloc(0);
       return;
     }
-    if (seq.length === 2 && seq[0] === "\x1B") {
+    if (seq.length === 2 && seq[0] === "\x1B" && seq[1] !== "[" && seq[1] !== "O") {
       const ch = seq[1];
       this._events.emit("key", createKeyEvent({
         key: ch,
-        raw: rawData,
+        raw: this._escapeBuffer,
         ctrl: false,
         alt: true,
         shift: ch !== ch.toLowerCase() && ch === ch.toUpperCase()
       }));
-      this._escapeBuffer = "";
+      this._escapeBuffer = Buffer2.alloc(0);
       return;
     }
     if (seq.length > 20) {
-      this._escapeBuffer = "";
+      this._escapeBuffer = Buffer2.alloc(0);
       return;
     }
     if (this._escapeTimeout) {
@@ -1481,12 +2422,184 @@ var InputParser = class {
       this._escapeTimeout = null;
     }
     this._escapeTimeout = setTimeout(() => {
-      this._escapeBuffer = "";
+      this._escapeBuffer = Buffer2.alloc(0);
       this._escapeTimeout = null;
     }, 100);
   }
 };
 
+// src/input/MouseGestures.ts
+var MouseGestures = class {
+  doubleClickMs;
+  lastMouseDown = null;
+  activeDragButton = null;
+  wasDragging = false;
+  constructor(opts) {
+    this.doubleClickMs = opts?.doubleClickMs ?? 300;
+  }
+  /**
+   * Feed a raw MouseEvent. Returns synthesized events to emit
+   * (may be empty). Does not mutate the input event.
+   */
+  feed(event) {
+    const synthesized = [];
+    if (event.type === "mousedown") {
+      const now = Date.now();
+      if (this.lastMouseDown && this.lastMouseDown.x === event.x && this.lastMouseDown.y === event.y && this.lastMouseDown.button === event.button && now - this.lastMouseDown.time <= this.doubleClickMs) {
+        synthesized.push({
+          x: event.x,
+          y: event.y,
+          button: event.button,
+          type: "dblclick"
+        });
+        this.lastMouseDown = null;
+      } else {
+        this.lastMouseDown = {
+          x: event.x,
+          y: event.y,
+          button: event.button,
+          time: now
+        };
+      }
+      this.activeDragButton = event.button;
+      this.wasDragging = false;
+    } else if (event.type === "mousemove") {
+      if (this.activeDragButton !== null) {
+        this.wasDragging = true;
+        synthesized.push({
+          x: event.x,
+          y: event.y,
+          button: this.activeDragButton,
+          type: "drag"
+        });
+      }
+    } else if (event.type === "mouseup") {
+      if (this.activeDragButton !== null) {
+        if (this.wasDragging) {
+          synthesized.push({
+            x: event.x,
+            y: event.y,
+            button: event.button,
+            type: "dragend"
+          });
+        }
+        this.activeDragButton = null;
+        this.wasDragging = false;
+      }
+    }
+    return synthesized;
+  }
+};
+
+// src/input/ChordMatcher.ts
+function getKeyEventToken(event) {
+  let token = "";
+  if (event.ctrl) token += "ctrl+";
+  if (event.alt) token += "alt+";
+  if (event.shift) token += "shift+";
+  token += event.key.toLowerCase();
+  return token;
+}
+var ChordMatcher = class {
+  _bindings = [];
+  _nextId = 0;
+  _buffer = [];
+  _timeoutMs;
+  _timer = null;
+  constructor(opts) {
+    this._timeoutMs = opts?.timeoutMs ?? 800;
+  }
+  bind(keys, handler) {
+    const id = this._nextId++;
+    this._bindings.push({ keys, handler, id });
+    return () => {
+      this._bindings = this._bindings.filter((b) => b.id !== id);
+    };
+  }
+  feed(event) {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    const token = getKeyEventToken(event);
+    let candidate = [...this._buffer, token];
+    let matchingBindings = this._getMatchingBindings(candidate);
+    if (matchingBindings.length === 0) {
+      this._buffer = [];
+      candidate = [token];
+      matchingBindings = this._getMatchingBindings(candidate);
+      if (matchingBindings.length === 0) {
+        return false;
+      }
+    }
+    this._buffer = candidate;
+    const completedBindings = matchingBindings.filter(
+      (binding) => binding.keys.length === candidate.length
+    );
+    if (completedBindings.length > 0) {
+      for (const binding of completedBindings) {
+        binding.handler();
+      }
+      this._buffer = [];
+      return true;
+    }
+    this._timer = setTimeout(() => {
+      this._buffer = [];
+      this._timer = null;
+    }, this._timeoutMs);
+    return true;
+  }
+  _getMatchingBindings(candidate) {
+    return this._bindings.filter((binding) => {
+      if (binding.keys.length < candidate.length) return false;
+      for (let i = 0; i < candidate.length; i++) {
+        if (binding.keys[i] !== candidate[i]) return false;
+      }
+      return true;
+    });
+  }
+};
+
+// src/renderer/live-render.ts
+var LiveRender = class {
+  constructor(terminal, screen) {
+    this.terminal = terminal;
+    this.screen = screen;
+  }
+  terminal;
+  screen;
+  getHeight(frame) {
+    if (frame.length === 0) {
+      return 0;
+    }
+    return frame.split("\n").length;
+  }
+  /**
+   * Renders a serialized screen buffer.
+   *
+   * Widgets render into a Screen object first.
+   * Callers should serialize the Screen contents into a string
+   * before passing it to LiveRender.render().
+   */
+  render(frame) {
+    let output = "";
+    const previousHeight = this.screen.lastRenderedHeight;
+    if (previousHeight > 0) {
+      output += moveUp(previousHeight);
+      for (let i = 0; i < previousHeight; i++) {
+        output += clearLine;
+        if (i < previousHeight - 1) {
+          output += "\n";
+        }
+      }
+      output += "\r";
+    }
+    output += frame;
+    this.terminal.write(output);
+    this.screen.lastRenderedHeight = this.getHeight(frame);
+  }
+};
+
 // src/style/Style.ts
 function normalizeEdges(value) {
   if (value === void 0) return { top: 0, right: 0, bottom: 0, left: 0 };
@@ -1523,6 +2636,32 @@ function defaultStyle() {
     gap: 0
   };
 }
+var LAYOUT_PROPS = /* @__PURE__ */ new Set([
+  "width",
+  "height",
+  "minWidth",
+  "minHeight",
+  "maxWidth",
+  "maxHeight",
+  "padding",
+  "margin",
+  "border",
+  "flexDirection",
+  "justifyContent",
+  "alignItems",
+  "flexGrow",
+  "flexShrink",
+  "flexWrap",
+  "gap",
+  "overflow",
+  "visible"
+]);
+function hasLayoutChanges(oldStyle, newStyle) {
+  for (const key of LAYOUT_PROPS) {
+    if (oldStyle[key] !== newStyle[key]) return true;
+  }
+  return false;
+}
 function styleToCellAttrs(style) {
   return {
     fg: style.fg ?? { type: "none" },
@@ -1589,8 +2728,19 @@ var BORDER_CHARS = {
     left: "\u2506"
   }
 };
-function getBorderChars(style, customChars) {
+var ASCII_BORDER_CHARS = {
+  topLeft: "+",
+  top: "-",
+  topRight: "+",
+  right: "|",
+  bottomRight: "+",
+  bottom: "-",
+  bottomLeft: "+",
+  left: "|"
+};
+function getBorderChars(style, customChars, asciiOnly = false) {
   if (style === "none") return null;
+  if (asciiOnly) return ASCII_BORDER_CHARS;
   if (style === "custom") {
     const base = BORDER_CHARS.single;
     return { ...base, ...customChars };
@@ -1602,6 +2752,333 @@ function borderSize(style) {
   return { horizontal: 2, vertical: 2 };
 }
 
+// src/layout/pos.ts
+var Pos = class {
+  /** Center the element within its parent */
+  static center() {
+    return new PosCenter();
+  }
+  /** Anchor the element `margin` units away from the end (right/bottom) */
+  static anchorEnd(margin = 0) {
+    return new PosAnchorEnd(margin);
+  }
+  /** Align multiple siblings as a group */
+  static align(alignment, groupId) {
+    return new PosAlign(alignment, groupId);
+  }
+};
+var PosCenter = class extends Pos {
+  dependencies() {
+    return ["parentSize", "elementSize"];
+  }
+  evaluate(ctx) {
+    const pSize = ctx.axis === "horizontal" ? ctx.parentWidth : ctx.parentHeight;
+    const eSize = ctx.axis === "horizontal" ? ctx.elementWidth : ctx.elementHeight;
+    return Math.floor((pSize - eSize) / 2);
+  }
+};
+var PosAnchorEnd = class extends Pos {
+  constructor(margin) {
+    super();
+    this.margin = margin;
+  }
+  margin;
+  dependencies() {
+    return ["parentSize", "elementSize"];
+  }
+  evaluate(ctx) {
+    const pSize = ctx.axis === "horizontal" ? ctx.parentWidth : ctx.parentHeight;
+    const eSize = ctx.axis === "horizontal" ? ctx.elementWidth : ctx.elementHeight;
+    return pSize - eSize - this.margin;
+  }
+};
+var PosAlign = class extends Pos {
+  constructor(alignment, groupId) {
+    super();
+    this.alignment = alignment;
+    this.groupId = groupId;
+  }
+  alignment;
+  groupId;
+  dependencies() {
+    return ["group:" + this.groupId, "elementSize"];
+  }
+  evaluate(ctx) {
+    const groupSize = ctx.getGroupSize(this.groupId);
+    if (groupSize === 0) return 0;
+    const pSize = ctx.axis === "horizontal" ? ctx.parentWidth : ctx.parentHeight;
+    const eSize = ctx.axis === "horizontal" ? ctx.elementWidth : ctx.elementHeight;
+    let groupOffset = 0;
+    if (this.alignment === "center") {
+      groupOffset = Math.floor((pSize - groupSize) / 2);
+    } else if (this.alignment === "end") {
+      groupOffset = pSize - groupSize;
+    }
+    const localOffset = Math.floor((groupSize - eSize) / 2);
+    return groupOffset + localOffset;
+  }
+};
+
+// src/layout/dim.ts
+var Dim = class {
+  /** Size to the intrinsic content of the element */
+  static auto() {
+    return new DimAuto();
+  }
+  /** Fill remaining space in the parent, minus an optional margin */
+  static fill(margin = 0) {
+    return new DimFill(margin);
+  }
+  /** Custom function to determine size */
+  static func(fn) {
+    return new DimFunc(fn);
+  }
+};
+var DimAuto = class extends Dim {
+  dependencies() {
+    return ["contentSize"];
+  }
+  evaluate(ctx) {
+    return ctx.axis === "horizontal" ? ctx.contentWidth : ctx.contentHeight;
+  }
+};
+var DimFill = class extends Dim {
+  constructor(margin) {
+    super();
+    this.margin = margin;
+  }
+  margin;
+  dependencies() {
+    return ["parentSize"];
+  }
+  evaluate(ctx) {
+    const avail = ctx.axis === "horizontal" ? ctx.parentWidth : ctx.parentHeight;
+    return Math.max(0, avail - this.margin);
+  }
+};
+var DimFunc = class extends Dim {
+  constructor(fn) {
+    super();
+    this.fn = fn;
+  }
+  fn;
+  dependencies() {
+    return [];
+  }
+  evaluate(ctx) {
+    return this.fn(ctx);
+  }
+};
+
+// src/layout/constraint.ts
+var Flex = /* @__PURE__ */ ((Flex2) => {
+  Flex2["Start"] = "start";
+  Flex2["Center"] = "center";
+  Flex2["End"] = "end";
+  Flex2["SpaceBetween"] = "space-between";
+  Flex2["SpaceAround"] = "space-around";
+  return Flex2;
+})(Flex || {});
+var Constraint = class {
+  /** Fixed length in columns/rows */
+  static Length(n) {
+    return new LengthConstraint(n);
+  }
+  /** Percentage of available space (0-100) */
+  static Percentage(n) {
+    return new PercentageConstraint(n);
+  }
+  /** Minimum length */
+  static Min(n) {
+    return new MinConstraint(n);
+  }
+  /** Maximum length */
+  static Max(n) {
+    return new MaxConstraint(n);
+  }
+  /** Fills remaining space, with a flex weight */
+  static Fill(weight = 1) {
+    return new FillConstraint(weight);
+  }
+};
+var LengthConstraint = class extends Constraint {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+  value;
+};
+var PercentageConstraint = class extends Constraint {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+  value;
+};
+var MinConstraint = class extends Constraint {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+  value;
+};
+var MaxConstraint = class extends Constraint {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+  value;
+};
+var FillConstraint = class extends Constraint {
+  constructor(weight) {
+    super();
+    this.weight = weight;
+  }
+  weight;
+};
+function resolveConstraints(available, constraints, flex = "start" /* Start */, gap = 0) {
+  const n = constraints.length;
+  if (n === 0) return [];
+  const sizes = new Array(n).fill(0);
+  const minSizes = new Array(n).fill(0);
+  const maxSizes = new Array(n).fill(Infinity);
+  let totalFixed = 0;
+  let fillWeightSum = 0;
+  for (let i = 0; i < n; i++) {
+    const c = constraints[i];
+    if (c instanceof LengthConstraint) {
+      sizes[i] = c.value;
+      totalFixed += c.value;
+    } else if (c instanceof PercentageConstraint) {
+      sizes[i] = Math.floor(available * c.value / 100);
+      totalFixed += sizes[i];
+    } else if (c instanceof MinConstraint) {
+      minSizes[i] = c.value;
+    } else if (c instanceof MaxConstraint) {
+      maxSizes[i] = c.value;
+    } else if (c instanceof FillConstraint) {
+      fillWeightSum += c.weight;
+    }
+  }
+  for (let i = 0; i < n; i++) {
+    if (constraints[i] instanceof MinConstraint) {
+      sizes[i] = minSizes[i];
+      totalFixed += sizes[i];
+    }
+  }
+  const totalGaps = gap * (n - 1);
+  let remaining = Math.max(0, available - totalFixed - totalGaps);
+  if (fillWeightSum > 0) {
+    let distributed = 0;
+    for (let i = 0; i < n; i++) {
+      const c = constraints[i];
+      if (c instanceof FillConstraint) {
+        const share = Math.floor(remaining * c.weight / fillWeightSum);
+        sizes[i] = share;
+        distributed += share;
+      }
+    }
+    let leftover = remaining - distributed;
+    if (leftover > 0) {
+      for (let i = n - 1; i >= 0; i--) {
+        if (constraints[i] instanceof FillConstraint) {
+          sizes[i] += leftover;
+          break;
+        }
+      }
+    }
+  }
+  const totalUsed = sizes.reduce((a, b) => a + b, 0) + totalGaps;
+  const freeSpace = Math.max(0, available - totalUsed);
+  const results = [];
+  let offset = 0;
+  let spaceBetween = 0;
+  switch (flex) {
+    case "start" /* Start */:
+      break;
+    case "end" /* End */:
+      offset = freeSpace;
+      break;
+    case "center" /* Center */:
+      offset = freeSpace / 2;
+      break;
+    case "space-between" /* SpaceBetween */:
+      if (n > 1) spaceBetween = freeSpace / (n - 1);
+      break;
+    case "space-around" /* SpaceAround */:
+      if (n > 0) {
+        spaceBetween = freeSpace / n;
+        offset = spaceBetween / 2;
+      }
+      break;
+  }
+  for (let i = 0; i < n; i++) {
+    results.push({ offset: Math.floor(offset), size: sizes[i] });
+    offset += sizes[i] + gap + spaceBetween;
+  }
+  return results;
+}
+function resolveLayoutVariables(nodes, parentWidth, parentHeight) {
+  const state = /* @__PURE__ */ new Map();
+  function evaluateVariable(node, varName) {
+    const key = `${node.id}:${varName}`;
+    const existing = state.get(key);
+    if (existing === "computing") {
+      throw new Error(`Cycle detected resolving ${key}`);
+    }
+    if (typeof existing === "number") {
+      return existing;
+    }
+    state.set(key, "computing");
+    let result = 0;
+    const val = node[varName];
+    const ctx = {
+      parentWidth,
+      parentHeight,
+      axis: varName === "x" || varName === "width" ? "horizontal" : "vertical",
+      contentWidth: node.contentWidth,
+      contentHeight: node.contentHeight,
+      get elementWidth() {
+        return evaluateVariable(node, "width");
+      },
+      get elementHeight() {
+        return evaluateVariable(node, "height");
+      },
+      get elementX() {
+        return evaluateVariable(node, "x");
+      },
+      get elementY() {
+        return evaluateVariable(node, "y");
+      },
+      getGroupSize(groupId) {
+        const groupNodes = nodes.filter((n) => n.groupId === groupId);
+        let maxSize = 0;
+        for (const gNode of groupNodes) {
+          const size = evaluateVariable(gNode, this.axis === "horizontal" ? "width" : "height");
+          maxSize = Math.max(maxSize, size);
+        }
+        return maxSize;
+      }
+    };
+    if (val instanceof Pos) {
+      result = val.evaluate(ctx);
+    } else if (val instanceof Dim) {
+      result = val.evaluate(ctx);
+    } else if (typeof val === "number") {
+      result = val;
+    }
+    state.set(key, result);
+    node.computed[varName] = result;
+    return result;
+  }
+  for (const node of nodes) {
+    evaluateVariable(node, "width");
+    evaluateVariable(node, "height");
+    evaluateVariable(node, "x");
+    evaluateVariable(node, "y");
+  }
+}
+
 // src/layout/LayoutEngine.ts
 function createLayoutNode(id, style, children = []) {
   return {
@@ -1609,14 +3086,44 @@ function createLayoutNode(id, style, children = []) {
     style,
     children,
     computed: { x: 0, y: 0, width: 0, height: 0 },
-    _dirty: true
+    _dirty: true,
+    _lastContainerWidth: 0,
+    _lastContainerHeight: 0,
+    _lastComputedWidth: 0,
+    _lastComputedHeight: 0,
+    _draggable: false,
+    _dragging: false
   };
 }
 function computeLayout(root, containerWidth, containerHeight) {
+  const sizeChanged = root._lastContainerWidth !== containerWidth || root._lastContainerHeight !== containerHeight;
+  if (!sizeChanged && !root._dirty && !hasDirtyChild(root)) {
+    return;
+  }
+  root._lastContainerWidth = containerWidth;
+  root._lastContainerHeight = containerHeight;
   root.computed = { x: 0, y: 0, width: containerWidth, height: containerHeight };
   layoutNode(root, containerWidth, containerHeight);
+  root.computed.width = containerWidth;
+  root.computed.height = containerHeight;
+}
+function invalidateLayout(node) {
+  node._dirty = true;
+  for (const child of node.children) {
+    invalidateLayout(child);
+  }
+}
+function hasDirtyChild(node) {
+  if (node._dirty) return true;
+  for (const child of node.children) {
+    if (hasDirtyChild(child)) return true;
+  }
+  return false;
 }
 function layoutNode(node, availWidth, availHeight, precomputed = false) {
+  if (!node._dirty && node._lastComputedWidth === node.computed.width && node._lastComputedHeight === node.computed.height) {
+    return;
+  }
   const style = node.style;
   const padding = normalizeEdges(style.padding);
   const margin = normalizeEdges(style.margin);
@@ -1626,6 +3133,8 @@ function layoutNode(node, availWidth, availHeight, precomputed = false) {
     let nodeHeight2 = resolveSize(style.height, availHeight);
     if (nodeWidth2 === void 0) nodeWidth2 = availWidth - margin.left - margin.right;
     if (nodeHeight2 === void 0) nodeHeight2 = availHeight - margin.top - margin.bottom;
+    if (!Number.isFinite(nodeWidth2)) nodeWidth2 = 0;
+    if (!Number.isFinite(nodeHeight2)) nodeHeight2 = 0;
     nodeWidth2 = clampSize(nodeWidth2, style.minWidth, style.maxWidth);
     nodeHeight2 = clampSize(nodeHeight2, style.minHeight, style.maxHeight);
     node.computed.width = nodeWidth2;
@@ -1633,23 +3142,105 @@ function layoutNode(node, availWidth, availHeight, precomputed = false) {
   }
   if (node.children.length === 0) {
     node._dirty = false;
+    node._lastComputedWidth = node.computed.width;
+    node._lastComputedHeight = node.computed.height;
     return;
   }
   const nodeWidth = node.computed.width;
   const nodeHeight = node.computed.height;
-  const innerX = padding.left + border.horizontal / 2;
-  const innerY = padding.top + border.vertical / 2;
+  const innerX = padding.left + (border.horizontal > 0 ? 1 : 0);
+  const innerY = padding.top + (border.vertical > 0 ? 1 : 0);
   const innerWidth = Math.max(0, nodeWidth - padding.left - padding.right - border.horizontal);
   const innerHeight = Math.max(0, nodeHeight - padding.top - padding.bottom - border.vertical);
   const direction = style.flexDirection ?? "column";
   const isRow = direction === "row";
   const gap = style.gap ?? 0;
+  if (style.constraints && style.constraints.length > 0) {
+    const mainAvail2 = isRow ? innerWidth : innerHeight;
+    let flexJustify = "start" /* Start */;
+    if (style.justifyContent === "space-between") flexJustify = "space-between" /* SpaceBetween */;
+    else if (style.justifyContent === "space-around") flexJustify = "space-around" /* SpaceAround */;
+    else if (style.justifyContent === "center") flexJustify = "center" /* Center */;
+    else if (style.justifyContent === "flex-end") flexJustify = "end" /* End */;
+    const results = resolveConstraints(mainAvail2, style.constraints, flexJustify);
+    let visibleIndex = 0;
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[i];
+      if (visibleIndex >= results.length) break;
+      if (child.style.visible === false) continue;
+      const res = results[visibleIndex];
+      const childMargin = normalizeEdges(child.style.margin);
+      if (isRow) {
+        child.computed = {
+          x: Math.floor(node.computed.x + innerX + res.offset + childMargin.left),
+          y: Math.floor(node.computed.y + innerY + childMargin.top),
+          width: Math.round(Math.max(0, res.size - childMargin.left - childMargin.right)),
+          height: Math.round(Math.max(0, innerHeight - childMargin.top - childMargin.bottom))
+        };
+      } else {
+        child.computed = {
+          x: Math.floor(node.computed.x + innerX + childMargin.left),
+          y: Math.floor(node.computed.y + innerY + res.offset + childMargin.top),
+          width: Math.round(Math.max(0, innerWidth - childMargin.left - childMargin.right)),
+          height: Math.round(Math.max(0, res.size - childMargin.top - childMargin.bottom))
+        };
+      }
+      layoutNode(child, child.computed.width, child.computed.height, true);
+      visibleIndex++;
+    }
+    node._dirty = false;
+    node._lastComputedWidth = node.computed.width;
+    node._lastComputedHeight = node.computed.height;
+    return;
+  }
+  const topologicalChildren = [];
+  const flexChildren = [];
+  for (const child of node.children) {
+    if (child.style.visible === false) continue;
+    const s = child.style;
+    if (s.x instanceof Pos || s.y instanceof Pos || s.width instanceof Dim || s.height instanceof Dim || s.groupId != null) {
+      topologicalChildren.push(child);
+    } else {
+      flexChildren.push(child);
+    }
+  }
+  if (topologicalChildren.length > 0) {
+    const resolvableNodes = topologicalChildren.map((child) => {
+      const s = child.style;
+      let cw = 0, ch = 0;
+      if (typeof s.width === "number") cw = s.width;
+      if (typeof s.height === "number") ch = s.height;
+      return {
+        id: child.id,
+        x: s.x,
+        y: s.y,
+        width: typeof s.width === "string" ? void 0 : s.width,
+        height: typeof s.height === "string" ? void 0 : s.height,
+        contentWidth: cw,
+        contentHeight: ch,
+        groupId: s.groupId,
+        computed: { x: 0, y: 0, width: 0, height: 0 },
+        _originalNode: child
+        // keep reference
+      };
+    });
+    resolveLayoutVariables(resolvableNodes, innerWidth, innerHeight);
+    for (const rNode of resolvableNodes) {
+      const child = rNode._originalNode;
+      child.computed = {
+        x: Math.floor(node.computed.x + innerX + rNode.computed.x),
+        y: Math.floor(node.computed.y + innerY + rNode.computed.y),
+        width: Math.round(Math.max(0, rNode.computed.width)),
+        height: Math.round(Math.max(0, rNode.computed.height))
+      };
+      layoutNode(child, child.computed.width, child.computed.height, true);
+    }
+  }
   const childInfos = [];
   let totalFixed = 0;
   let totalGrow = 0;
   let totalShrink = 0;
-  for (const child of node.children) {
-    if (child.style.visible === false) continue;
+  for (const child of flexChildren) {
     const childMargin = normalizeEdges(child.style.margin);
     const childBorder = borderSize(child.style.border ?? "none");
     const grow = child.style.flexGrow ?? 0;
@@ -1756,20 +3347,26 @@ function layoutNode(node, availWidth, availHeight, precomputed = false) {
     layoutNode(info.node, info.node.computed.width, info.node.computed.height, true);
   }
   node._dirty = false;
+  node._lastComputedWidth = node.computed.width;
+  node._lastComputedHeight = node.computed.height;
 }
 function resolveSize(value, available) {
   if (value === void 0) return void 0;
-  if (typeof value === "number") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) return 0;
+    return value;
+  }
   if (typeof value === "string" && value.endsWith("%")) {
     const pct = parseFloat(value) / 100;
+    if (!Number.isFinite(pct)) return 0;
     return Math.floor(available * pct);
   }
   return void 0;
 }
-function clampSize(value, min2, max2) {
+function clampSize(value, min, max) {
   let result = value;
-  if (min2 !== void 0) result = Math.max(result, min2);
-  if (max2 !== void 0) result = Math.min(result, max2);
+  if (min !== void 0) result = Math.max(result, min);
+  if (max !== void 0) result = Math.min(result, max);
   return result;
 }
 
@@ -1804,94 +3401,6 @@ function unionRect(a, b) {
   return { x, y, width: r - x, height: bot - y };
 }
 
-// src/layout/ConstraintLayout.ts
-var length = (n) => ({ type: "length", value: n });
-var percentage = (n) => ({ type: "percentage", value: n });
-var ratio = (num, den) => ({ type: "ratio", num, den });
-var min = (n) => ({ type: "min", value: n });
-var max = (n) => ({ type: "max", value: n });
-var fill = (weight = 1) => ({ type: "fill", weight });
-function resolveSize2(constraint, available) {
-  switch (constraint.type) {
-    case "length":
-      return Math.min(constraint.value, available);
-    case "percentage":
-      return Math.min(Math.floor(available * constraint.value / 100), available);
-    case "ratio":
-      return constraint.den === 0 ? 0 : Math.min(
-        Math.floor(available * constraint.num / constraint.den),
-        available
-      );
-    case "min":
-      return constraint.value;
-    case "max":
-      return Math.min(constraint.value, available);
-    case "fill":
-      return 0;
-  }
-}
-function splitRect(rect, constraints, direction = "vertical", gap = 0) {
-  if (constraints.length === 0) return [];
-  const totalAvailable = direction === "horizontal" ? rect.width : rect.height;
-  const count = constraints.length;
-  const totalGaps = count > 1 ? gap * (count - 1) : 0;
-  const availableForConstraints = Math.max(0, totalAvailable - totalGaps);
-  const sizes = [];
-  let usedSpace = 0;
-  let fillWeightSum = 0;
-  for (const constraint of constraints) {
-    if (constraint.type === "fill") {
-      sizes.push(0);
-      fillWeightSum += Math.max(1, constraint.weight);
-    } else {
-      const size = resolveSize2(constraint, availableForConstraints);
-      sizes.push(size);
-      usedSpace += size;
-    }
-  }
-  if (fillWeightSum > 0) {
-    const remaining = Math.max(0, availableForConstraints - usedSpace);
-    let distributed = 0;
-    for (let i = 0; i < count; i++) {
-      const constraint = constraints[i];
-      if (!constraint || constraint.type !== "fill") continue;
-      const weight = Math.max(1, constraint.weight);
-      const share = Math.floor(remaining * weight / fillWeightSum);
-      sizes[i] = share;
-      distributed += share;
-    }
-    const leftover = remaining - distributed;
-    if (leftover > 0) {
-      for (let i = count - 1; i >= 0; i--) {
-        const constraint = constraints[i];
-        if (constraint && constraint.type === "fill") {
-          sizes[i] = (sizes[i] ?? 0) + leftover;
-          break;
-        }
-      }
-    }
-  }
-  let totalUsed = 0;
-  for (let i = 0; i < count; i++) {
-    const size = sizes[i] ?? 0;
-    const clamped = Math.max(0, Math.min(size, availableForConstraints - totalUsed));
-    sizes[i] = clamped;
-    totalUsed += clamped;
-  }
-  const results = [];
-  let offset = 0;
-  for (let i = 0; i < count; i++) {
-    const size = sizes[i] ?? 0;
-    if (direction === "horizontal") {
-      results.push({ x: rect.x + offset, y: rect.y, width: size, height: rect.height });
-    } else {
-      results.push({ x: rect.x, y: rect.y + offset, width: rect.width, height: size });
-    }
-    offset += size + gap;
-  }
-  return results;
-}
-
 // src/events/FocusManager.ts
 var FocusManager = class {
   _focusables = [];
@@ -1912,6 +3421,16 @@ var FocusManager = class {
    * Maps groupId → ordered list of widget IDs.
    */
   _groups = /* @__PURE__ */ new Map();
+  /**
+   * Record of on-screen rects for widgets, used for spatial navigation.
+   */
+  _rects = /* @__PURE__ */ new Map();
+  /** Monotonically increasing epoch for ordered event sequencing */
+  _epoch = 0;
+  /** Queue of focus state changes accumulated before start() is called */
+  _pendingQueue = [];
+  /** True once start() has been called — enables event emission */
+  _started = false;
   /** Currently focused widget ID, or null if none */
   get currentId() {
     if (this._currentIndex < 0 || this._currentIndex >= this._focusables.length) {
@@ -1923,16 +3442,35 @@ var FocusManager = class {
   on(event, handler) {
     return this._events.on(event, handler);
   }
+  /**
+   * Enable event emission and replay any queued focus events.
+   * Call this from App.mount() after _subscribeFocusEvents().
+   */
+  start() {
+    if (this._started) return;
+    this._started = true;
+    for (const evt of this._pendingQueue) {
+      this._events.emit(evt.type, evt);
+    }
+    this._pendingQueue = [];
+  }
   /**
    * Register a focusable widget.
    * Widgets are ordered by tabIndex (ascending), then insertion order.
+   * Before start() is called, events are queued rather than emitted so
+   * they are not lost when App has not yet subscribed to them.
    */
   register(focusable) {
     this._focusables.push(focusable);
     this._focusables.sort((a, b) => a.tabIndex - b.tabIndex);
     if (this._currentIndex < 0 && focusable.focusable) {
       this._currentIndex = this._focusables.indexOf(focusable);
-      this._events.emit("focus", { targetId: focusable.id, type: "focus" });
+      const event = { targetId: focusable.id, type: "focus", epoch: this._epoch++ };
+      if (this._started) {
+        this._events.emit("focus", event);
+      } else {
+        this._pendingQueue.push(event);
+      }
     }
   }
   /**
@@ -1941,21 +3479,31 @@ var FocusManager = class {
   unregister(id) {
     const idx = this._focusables.findIndex((f) => f.id === id);
     if (idx < 0) return;
+    this._rects.delete(id);
     const wasFocused = idx === this._currentIndex;
     this._focusables.splice(idx, 1);
     if (wasFocused) {
-      this._events.emit("blur", { targetId: id, type: "blur" });
+      this._events.emit("blur", { targetId: id, type: "blur", epoch: this._epoch++ });
       if (this._focusables.length > 0) {
         this._currentIndex = Math.min(this._currentIndex, this._focusables.length - 1);
         this._events.emit("focus", {
           targetId: this._focusables[this._currentIndex].id,
-          type: "focus"
+          type: "focus",
+          epoch: this._epoch++
         });
       } else {
         this._currentIndex = -1;
       }
     } else if (idx < this._currentIndex) {
       this._currentIndex--;
+      this._events.emit("blur", { targetId: id, type: "blur", epoch: this._epoch++ });
+      if (this._currentIndex >= 0 && this._currentIndex < this._focusables.length) {
+        this._events.emit("focus", {
+          targetId: this._focusables[this._currentIndex].id,
+          type: "focus",
+          epoch: this._epoch++
+        });
+      }
     }
   }
   /**
@@ -2099,6 +3647,69 @@ var FocusManager = class {
     }
     return false;
   }
+  // ── Spatial Navigation ──────────────────────────────
+  /** Record the on-screen rect for a widget, used for spatial navigation. */
+  setRect(id, rect) {
+    this._rects.set(id, rect);
+  }
+  _spatialFocus(isValid, calcDistance) {
+    const currentId = this.currentId;
+    if (!currentId) return false;
+    const currentRect = this._rects.get(currentId);
+    if (!currentRect) return false;
+    const cx = currentRect.x + currentRect.width / 2;
+    const cy = currentRect.y + currentRect.height / 2;
+    let bestId = null;
+    let minDistance = Infinity;
+    const candidates = this._getActiveFocusables();
+    for (const node of candidates) {
+      if (!node.focusable || node.id === currentId) continue;
+      const targetRect = this._rects.get(node.id);
+      if (!targetRect) continue;
+      const tx = targetRect.x + targetRect.width / 2;
+      const ty = targetRect.y + targetRect.height / 2;
+      if (isValid(cx, cy, tx, ty)) {
+        const dist = calcDistance(cx, cy, tx, ty);
+        if (dist < minDistance) {
+          minDistance = dist;
+          bestId = node.id;
+        }
+      }
+    }
+    if (bestId) {
+      this.focusWidget(bestId);
+      return true;
+    }
+    return false;
+  }
+  /** Move focus to the nearest focusable widget above the current one. */
+  focusUp() {
+    return this._spatialFocus(
+      (cx, cy, tx, ty) => ty < cy,
+      (cx, cy, tx, ty) => cy - ty + Math.abs(tx - cx)
+    );
+  }
+  /** Move focus to the nearest focusable widget below the current one. */
+  focusDown() {
+    return this._spatialFocus(
+      (cx, cy, tx, ty) => ty > cy,
+      (cx, cy, tx, ty) => ty - cy + Math.abs(tx - cx)
+    );
+  }
+  /** Move focus to the nearest focusable widget to the left of the current one. */
+  focusLeft() {
+    return this._spatialFocus(
+      (cx, cy, tx, ty) => tx < cx,
+      (cx, cy, tx, ty) => cx - tx + Math.abs(ty - cy)
+    );
+  }
+  /** Move focus to the nearest focusable widget to the right of the current one. */
+  focusRight() {
+    return this._spatialFocus(
+      (cx, cy, tx, ty) => tx > cx,
+      (cx, cy, tx, ty) => tx - cx + Math.abs(ty - cy)
+    );
+  }
   // ── Private ──────────────────────────────────────────
   /**
    * Get the active focusables, filtered by the current trap if any.
@@ -2113,12 +3724,13 @@ var FocusManager = class {
   _changeFocus(newIndex) {
     const oldId = this.currentId;
     if (oldId) {
-      this._events.emit("blur", { targetId: oldId, type: "blur" });
+      this._events.emit("blur", { targetId: oldId, type: "blur", epoch: this._epoch++ });
     }
     this._currentIndex = newIndex;
     this._events.emit("focus", {
       targetId: this._focusables[newIndex].id,
-      type: "focus"
+      type: "focus",
+      epoch: this._epoch++
     });
   }
 };
@@ -2353,6 +3965,23 @@ function renderFallback(screen) {
   return lines.join("\n");
 }
 
+// src/inline-viewport.ts
+function renderInlineToTerminal(terminal, screen, rows) {
+  const totalRows = screen.rows;
+  const start = Math.max(0, totalRows - rows);
+  const lines = [];
+  for (let r = start; r < totalRows; r++) {
+    const row = screen.back[r];
+    if (!row) continue;
+    lines.push(row.map((c) => c.char || " ").join(""));
+  }
+  if (lines.length === 0) return;
+  terminal.write(lines.join("\n") + "\n");
+}
+function createInlineViewport(opts) {
+  return { rows: opts.rows };
+}
+
 // src/app/App.ts
 var App = class {
   terminal;
@@ -2368,18 +3997,38 @@ var App = class {
   _exitResolve = null;
   _unsubKey = null;
   _unsubMouse = null;
+  _unsubPaste = null;
+  _unsubFocus = null;
+  _unsubBlur = null;
+  _unsubSigInt = null;
+  _unsubSigTerm = null;
+  _unsubUncaughtException = null;
+  _unsubUnhandledRejection = null;
   _widgetById = /* @__PURE__ */ new Map();
+  // any: Widget shape varies; narrowed at retrieval
+  _pendingFocusState = /* @__PURE__ */ new Map();
+  _consecutiveRenderFailures = 0;
+  static MAX_RENDER_FAILURES = 5;
+  // Lines to insert before inline viewport output. Each entry: { id: symbol, text: string }
+  _insertBefore = [];
+  // Core fix patch: Track if a paint task has been queued for the next event loop tick
+  _isRenderPending = false;
   constructor(rootWidget, options = {}) {
     this._rootWidget = rootWidget;
     this._options = {
       fullscreen: true,
       mouse: false,
       fps: 30,
+      dockBorders: false,
+      diffRenderer: true,
+      // Default screenMode: if fullscreen explicitly disabled, treat as 'main', otherwise 'alternate'
+      screenMode: options.fullscreen === false ? "main" : "alternate",
+      inlineRows: 0,
       ...options
     };
     this.terminal = new Terminal(options);
     this.screen = new Screen(this.terminal.cols, this.terminal.rows);
-    this.renderer = new Renderer(this.terminal, this.screen, this._options.fps);
+    this.renderer = new Renderer(this.terminal, this.screen, this._options.fps, this._options.diffRenderer);
     this.input = new InputParser(this.terminal.stdin);
     this.focus = new FocusManager();
     this.events = new EventEmitter();
@@ -2387,8 +4036,6 @@ var App = class {
   }
   /**
    * Start the application.
-   * Sets up the terminal, starts the render loop, and mounts the root widget.
-   * Returns a promise that resolves when exit() is called.
    */
   async mount() {
     if (this._mounted) return 0;
@@ -2397,8 +4044,15 @@ var App = class {
       return 0;
     }
     this._mounted = true;
+    this._subscribeFocusEvents();
+    this.focus.start();
+    const focusedId = this.focus.currentId;
+    if (focusedId) {
+      this._pendingFocusState.set(focusedId, true);
+    }
+    this.renderer.hook.start();
     this.terminal.enterRawMode();
-    if (this._options.fullscreen) {
+    if (this._options.screenMode === "alternate") {
       this.terminal.enterAltScreen();
     }
     this.terminal.hideCursor();
@@ -2422,9 +4076,9 @@ var App = class {
         ...rawEvent,
         targetId: this.focus.currentId ?? void 0
       });
-      const focusedId = this.focus.currentId;
-      if (focusedId) {
-        const chain = this._buildBubbleChain(focusedId);
+      const focusedId2 = this.focus.currentId;
+      if (focusedId2) {
+        const chain = this._buildBubbleChain(focusedId2);
         for (const widget of chain) {
           widget.events.emit("key", event);
           if (event._propagationStopped) break;
@@ -2446,6 +4100,43 @@ var App = class {
     this._unsubMouse = this.input.onMouse((event) => {
       this.events.emit("mouse", event);
     });
+    this._unsubPaste = this.input.onPaste((text) => {
+      this.events.emit("paste", text);
+    });
+    const onSigInt = () => {
+      this.exit(130);
+    };
+    const onSigTerm = () => {
+      this.exit(143);
+    };
+    process.on("SIGINT", onSigInt);
+    process.on("SIGTERM", onSigTerm);
+    this._unsubSigInt = () => process.off("SIGINT", onSigInt);
+    this._unsubSigTerm = () => process.off("SIGTERM", onSigTerm);
+    this.terminal.onCleanup(() => {
+      this.renderer.hook.stop();
+    });
+    const onUncaughtException = (err) => {
+      this.renderer.hook.stop();
+      this.renderer.hook.writeRaw(this.renderer.hook.flush());
+      this.renderer.hook.writeRaw(`Uncaught exception: ${err.message}
+${err.stack}
+`);
+      this.terminal.restore();
+      process.exit(1);
+    };
+    process.on("uncaughtException", onUncaughtException);
+    this._unsubUncaughtException = () => process.off("uncaughtException", onUncaughtException);
+    const onUnhandledRejection = (reason) => {
+      this.renderer.hook.stop();
+      this.renderer.hook.writeRaw(this.renderer.hook.flush());
+      this.renderer.hook.writeRaw(`Unhandled rejection: ${reason}
+`);
+      this.terminal.restore();
+      process.exit(1);
+    };
+    process.on("unhandledRejection", onUnhandledRejection);
+    this._unsubUnhandledRejection = () => process.off("unhandledRejection", onUnhandledRejection);
     this.renderer.start(() => this.requestRender());
     this._rootWidget.mount?.();
     this.events.emit("mount", void 0);
@@ -2458,24 +4149,41 @@ var App = class {
   /**
    * Stop the application and restore terminal state.
    */
-  unmount() {
+  unmount(exitCode = 0) {
     if (!this._mounted) return;
     this._mounted = false;
     this._rootWidget.unmount?.();
     this.events.emit("unmount", void 0);
+    this._unsubSigInt?.();
+    this._unsubSigInt = null;
+    this._unsubSigTerm?.();
+    this._unsubSigTerm = null;
     this._unsubKey?.();
     this._unsubKey = null;
     this._unsubMouse?.();
     this._unsubMouse = null;
+    this._unsubFocus?.();
+    this._unsubFocus = null;
+    this._unsubBlur?.();
+    this._unsubBlur = null;
+    this._unsubPaste?.();
+    this._unsubPaste = null;
+    this._unsubUncaughtException?.();
+    this._unsubUncaughtException = null;
+    this._unsubUnhandledRejection?.();
+    this._unsubUnhandledRejection = null;
+    this.renderer.hook.stop();
     this.renderer.stop();
     this.input.stop();
     this.terminal.restore();
     this.events.removeAll();
+    if (this._exitResolve) {
+      this._exitResolve(exitCode);
+      this._exitResolve = null;
+    }
   }
   /**
    * Create an overlay layer for rendering above normal widgets.
-   * @param id     Unique layer identifier (e.g. 'modal', 'select-dropdown', 'toast')
-   * @param zIndex Stacking order (higher = rendered on top). Default: 100
    */
   addOverlay(id, zIndex = 100) {
     this.layers.createLayer(id, zIndex);
@@ -2488,33 +4196,84 @@ var App = class {
   }
   /**
    * Request a re-render on the next frame.
-   * Skips layout + render pass when the root widget reports no dirty state.
+   * Batches rapid structural updates via setImmediate scheduling so that
+   * multiple synchronous state mutations collapse into a single render frame.
    */
   requestRender() {
     if (!this._mounted) return;
-    if (this._rootWidget.isDirty === false) {
-      return;
-    }
-    const layoutRoot = this._rootWidget.getLayoutNode();
-    computeLayout(layoutRoot, this.terminal.cols, this.terminal.rows);
-    this._rootWidget.syncLayout?.();
-    this._buildWidgetMap(this._rootWidget);
-    this.screen.clear();
-    this._rootWidget.render(this.screen);
-    this._rootWidget.clearDirty?.();
-    this.layers.composite(this.screen);
-    this.renderer.requestFrame();
+    if (this._isRenderPending) return;
+    this._isRenderPending = true;
+    setImmediate(() => {
+      if (!this._mounted) {
+        this._isRenderPending = false;
+        return;
+      }
+      try {
+        if (this._rootWidget.isDirty === false && !this.layers.hasDirtyLayers()) {
+          return;
+        }
+        if (this._rootWidget.isDirty !== false) {
+          const layoutRoot = this._rootWidget.getLayoutNode();
+          computeLayout(layoutRoot, this.terminal.cols, this.terminal.rows);
+          this._rootWidget.syncLayout?.();
+          this._buildWidgetMap(this._rootWidget);
+          this.screen.clear();
+          this._rootWidget.render(this.screen);
+          if (this._options.dockBorders) {
+            mergeBorders(this.screen);
+          }
+          this._rootWidget.clearDirty?.();
+        }
+        this.layers.composite(this.screen);
+        if (this._options.screenMode === "inline") {
+          for (const item of this._insertBefore) {
+            this.terminal.write(item.text + "\n");
+          }
+          renderInlineToTerminal(this.terminal, this.screen, this._options.inlineRows ?? 0);
+        } else {
+          this.renderer.requestFrame();
+        }
+      } finally {
+        this._isRenderPending = false;
+        if (this._rootWidget.isDirty === true) {
+          this.requestRender();
+        }
+      }
+    });
   }
   /**
    * Exit the app (convenience method).
    */
   exit(code = 0) {
-    this.unmount();
+    this.unmount(code);
     if (this._exitResolve) {
       this._exitResolve(code);
       this._exitResolve = null;
     }
   }
+  /**
+   * Read from the system clipboard.
+   */
+  readClipboard() {
+    return this.terminal.readClipboard();
+  }
+  /**
+   * Write to the system clipboard.
+   */
+  writeClipboard(text) {
+    this.terminal.writeClipboard(text);
+  }
+  /**
+   * Register a persistent line to be written above inline viewport output.
+   */
+  insertBefore(line) {
+    const id = /* @__PURE__ */ Symbol();
+    this._insertBefore.push({ id, text: line });
+    return () => {
+      const idx = this._insertBefore.findIndex((x) => x.id === id);
+      if (idx >= 0) this._insertBefore.splice(idx, 1);
+    };
+  }
   /**
    * Render in fallback (static) mode for non-interactive environments.
    */
@@ -2529,8 +4288,6 @@ var App = class {
   }
   /**
    * Build the bubble chain for keyboard events.
-   * Returns an array: [focused widget, parent, grandparent, ..., root]
-   * Uses the cached _widgetById map for O(1) lookup instead of DFS.
    */
   _buildBubbleChain(widgetId) {
     const chain = [];
@@ -2547,15 +4304,17 @@ var App = class {
   }
   /**
    * Rebuild the widget ID cache by walking the entire widget tree.
-   * Called after syncLayout() so the map stays current.
    */
   _buildWidgetMap(root) {
     this._widgetById.clear();
     this._walkWidget(root);
+    this._applyPendingFocusState();
   }
   _walkWidget(widget) {
     if (!widget) return;
-    if (widget.id) this._widgetById.set(widget.id, widget);
+    if (widget.id) {
+      this._widgetById.set(widget.id, widget);
+    }
     const children = widget._children ?? widget.children ?? [];
     if (Array.isArray(children)) {
       for (const child of children) {
@@ -2563,167 +4322,116 @@ var App = class {
       }
     }
   }
-};
-
-// src/utils/unicode.ts
-function isWideChar(codePoint) {
-  return (
-    // CJK Unified Ideographs (common Chinese/Japanese/Korean)
-    codePoint >= 19968 && codePoint <= 40959 || // CJK Unified Ideographs Extension A
-    codePoint >= 13312 && codePoint <= 19903 || // CJK Compatibility Ideographs
-    codePoint >= 63744 && codePoint <= 64255 || // Hangul Syllables
-    codePoint >= 44032 && codePoint <= 55215 || // Katakana
-    codePoint >= 12448 && codePoint <= 12543 || // CJK Symbols and Punctuation
-    codePoint >= 12288 && codePoint <= 12351 || // Hiragana
-    codePoint >= 12352 && codePoint <= 12447 || // Fullwidth Forms
-    codePoint >= 65281 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || // CJK Unified Ideographs Extension B
-    codePoint >= 131072 && codePoint <= 173791 || // CJK Unified Ideographs Extension C,D,E,F
-    codePoint >= 173824 && codePoint <= 191471 || // CJK Compatibility Ideographs Supplement
-    codePoint >= 194560 && codePoint <= 195103
-  );
-}
-function isCombining(codePoint) {
-  return (
-    // Combining Diacritical Marks
-    codePoint >= 768 && codePoint <= 879 || // Combining Diacritical Marks Extended
-    codePoint >= 6832 && codePoint <= 6911 || // Combining Diacritical Marks Supplement
-    codePoint >= 7616 && codePoint <= 7679 || // Combining Diacritical Marks for Symbols
-    codePoint >= 8400 && codePoint <= 8447 || // Combining Half Marks
-    codePoint >= 65056 && codePoint <= 65071 || // Variation selectors
-    codePoint >= 65024 && codePoint <= 65039 || // Zero-width joiner / non-joiner
-    codePoint === 8203 || codePoint === 8204 || codePoint === 8205 || codePoint === 65279
-  );
-}
-function isEmoji(codePoint) {
-  return (
-    // Emoticons
-    codePoint >= 128512 && codePoint <= 128591 || // Misc Symbols and Pictographs
-    codePoint >= 127744 && codePoint <= 128511 || // Transport and Map
-    codePoint >= 128640 && codePoint <= 128767 || // Supplemental Symbols
-    codePoint >= 129280 && codePoint <= 129535 || // Misc symbols
-    codePoint >= 9728 && codePoint <= 9983 || // Dingbats
-    codePoint >= 9984 && codePoint <= 10175 || // Flags
-    codePoint >= 127456 && codePoint <= 127487
-  );
-}
-function stringWidth(str) {
-  let width = 0;
-  let inEscape = false;
-  for (const char of str) {
-    const cp = char.codePointAt(0);
-    if (cp === 27) {
-      inEscape = true;
-      continue;
-    }
-    if (inEscape) {
-      if (cp >= 64 && cp <= 126 && cp !== 91) {
-        inEscape = false;
-      }
-      continue;
+  _handleFocusEvent(event) {
+    const focused = event.type === "focus";
+    const changed = this._setWidgetFocused(event.targetId, focused);
+    if (changed === null) {
+      this._pendingFocusState.set(event.targetId, focused);
+      return;
     }
-    if (cp < 32 || cp >= 127 && cp < 160) {
-      continue;
+    if (changed) {
+      this.requestRender();
     }
-    if (isCombining(cp)) {
-      continue;
+  }
+  _setWidgetFocused(id, focused) {
+    const widget = this._widgetById.get(id);
+    if (!widget) {
+      return null;
     }
-    if (isWideChar(cp) || isEmoji(cp)) {
-      width += 2;
-      continue;
+    if (!this._isFocusAwareWidget(widget) || widget.isFocused === focused) {
+      return false;
     }
-    width += 1;
+    widget.isFocused = focused;
+    widget.markDirty?.();
+    return true;
   }
-  return width;
-}
-function truncate(str, maxWidth, ellipsis = "\u2026") {
-  if (maxWidth <= 0) return "";
-  const strW = stringWidth(str);
-  if (strW <= maxWidth) return str;
-  const ellipsisW = stringWidth(ellipsis);
-  const targetW = maxWidth - ellipsisW;
-  if (targetW <= 0) return ellipsis.slice(0, maxWidth);
-  let width = 0;
-  let result = "";
-  let inEscape = false;
-  let escapeBuffer = "";
-  for (const char of str) {
-    const cp = char.codePointAt(0);
-    if (cp === 27) {
-      inEscape = true;
-      escapeBuffer += char;
-      continue;
+  _subscribeFocusEvents() {
+    if (!this._unsubFocus) {
+      this._unsubFocus = this.focus.on("focus", (event) => this._handleFocusEvent(event));
     }
-    if (inEscape) {
-      escapeBuffer += char;
-      if (cp >= 64 && cp <= 126 && cp !== 91) {
-        inEscape = false;
-        result += escapeBuffer;
-        escapeBuffer = "";
+    if (!this._unsubBlur) {
+      this._unsubBlur = this.focus.on("blur", (event) => this._handleFocusEvent(event));
+    }
+  }
+  _applyPendingFocusState() {
+    for (const [id, focused] of this._pendingFocusState) {
+      const stateChanged = this._setWidgetFocused(id, focused);
+      if (stateChanged !== null) {
+        this._pendingFocusState.delete(id);
       }
-      continue;
     }
-    let charW = 1;
-    if (isCombining(cp)) {
-      charW = 0;
-    } else if (isWideChar(cp) || isEmoji(cp)) {
-      charW = 2;
-    } else if (cp < 32 || cp >= 127 && cp < 160) {
-      charW = 0;
+  }
+  _isFocusAwareWidget(widget) {
+    return typeof widget === "object" && widget !== null && "id" in widget && typeof widget.id === "string" && "isFocused" in widget && typeof widget.isFocused === "boolean";
+  }
+};
+
+// src/utils/debounce.ts
+function debounce(func, wait, options = {}) {
+  const { leading = false, trailing = true } = options;
+  let timeoutId = null;
+  let lastArgs = null;
+  let lastCallTime = null;
+  let lastInvokeTime = 0;
+  function invokeFunc(time) {
+    const args = lastArgs;
+    lastArgs = null;
+    lastInvokeTime = time;
+    return func(...args);
+  }
+  function shouldInvoke(time) {
+    const timeSinceLastCall = time - (lastCallTime ?? 0);
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    return lastCallTime === null || timeSinceLastCall >= wait || timeSinceLastCall < 0 || timeSinceLastInvoke >= wait;
+  }
+  function trailingEdge() {
+    timeoutId = null;
+    if (trailing && lastArgs) {
+      return invokeFunc(Date.now());
     }
-    if (width + charW > targetW) break;
-    width += charW;
-    result += char;
+    lastArgs = null;
+    return void 0;
   }
-  return result + ellipsis;
-}
-function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
-}
-function wordWrap(str, width) {
-  if (width <= 0) return str;
-  const lines = str.split("\n");
-  const result = [];
-  for (const line of lines) {
-    if (stringWidth(line) <= width) {
-      result.push(line);
-      continue;
+  function timerExpired() {
+    const time = Date.now();
+    if (shouldInvoke(time)) {
+      trailingEdge();
+    } else {
+      const timeSinceLastCall = time - (lastCallTime ?? 0);
+      const timeWaiting = wait - timeSinceLastCall;
+      timeoutId = setTimeout(timerExpired, timeWaiting);
     }
-    let currentLine = "";
-    let currentWidth = 0;
-    const words = line.split(/(\s+)/);
-    for (const word of words) {
-      const wordW = stringWidth(word);
-      if (currentWidth + wordW <= width) {
-        currentLine += word;
-        currentWidth += wordW;
-      } else if (wordW > width) {
-        if (currentLine) {
-          result.push(currentLine);
-          currentLine = "";
-          currentWidth = 0;
-        }
-        for (const char of word) {
-          const cp = char.codePointAt(0);
-          const charW = isWideChar(cp) || isEmoji(cp) ? 2 : isCombining(cp) ? 0 : 1;
-          if (currentWidth + charW > width) {
-            result.push(currentLine);
-            currentLine = "";
-            currentWidth = 0;
-          }
-          currentLine += char;
-          currentWidth += charW;
+  }
+  const debounced = function(...args) {
+    const time = Date.now();
+    const isInvoking = shouldInvoke(time);
+    lastArgs = args;
+    lastCallTime = time;
+    if (isInvoking) {
+      if (timeoutId === null) {
+        if (leading) {
+          return invokeFunc(time);
         }
+        timeoutId = setTimeout(timerExpired, wait);
       } else {
-        result.push(currentLine);
-        currentLine = word.trimStart();
-        currentWidth = stringWidth(currentLine);
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(timerExpired, wait);
       }
+    } else if (timeoutId === null && trailing) {
+      timeoutId = setTimeout(timerExpired, wait);
     }
-    if (currentLine) {
-      result.push(currentLine);
+    return void 0;
+  };
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
     }
-  }
-  return result.join("\n");
+    lastInvokeTime = 0;
+    lastArgs = null;
+    lastCallTime = null;
+    timeoutId = null;
+  };
+  return debounced;
 }
 export {
   App,
@@ -2736,14 +4444,27 @@ export {
   BarSets,
   BorderSets,
   CTRL_KEYS,
+  ChordMatcher,
   ColorDepth,
+  Constraint,
+  Dim,
   ESCAPE_SEQUENCES,
   EventEmitter,
+  FillConstraint,
+  Flex,
   FocusManager,
   HORIZONTAL_BAR_SYMBOLS,
   InputParser,
   LayerManager,
+  LengthConstraint,
   LineSets,
+  LiveRender,
+  MaxConstraint,
+  MinConstraint,
+  MouseGestures,
+  PercentageConstraint,
+  Pos,
+  RenderHook,
   Renderer,
   SPECIAL_KEYS,
   Screen,
@@ -2752,40 +4473,48 @@ export {
   Terminal,
   VERTICAL_BAR_SYMBOLS,
   ansi_exports as ansi,
+  bell2 as bell,
   borderSize,
   caps,
   cellsEqual,
+  clipboard,
   colorToAnsiBg,
   colorToAnsiFg,
   colorToRgb,
   computeLayout,
   containsPoint,
   contrastRatio,
+  createInlineViewport,
   createKeyEvent,
   createLayoutNode,
   createTestScreen,
+  debounce,
   defaultStyle,
   detectColorDepth,
   emptyCell,
   emptyRect,
-  fill,
   getBorderChars,
+  hasLayoutChanges,
   intersectRect,
+  invalidateLayout,
   isMouseSequence,
-  length,
-  max,
+  mergeBorders,
   mergeStyles,
-  min,
   normalizeEdges,
+  normalizeNavigationKey,
   parseColor,
   parseMouseEvent,
-  percentage,
-  ratio,
+  prefersHighContrast,
+  prefersReducedMotion,
+  readClipboard,
   relativeLuminance,
   renderFallback,
+  renderInlineToTerminal,
+  resolveConstraints,
+  resolveLayoutVariables,
+  shouldUseColor,
   shouldUseFallback,
   shrinkRect,
-  splitRect,
   stringWidth,
   stripAnsi,
   styleToCellAttrs,