@cel-tui/core 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cel-tui/core",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
   "type": "module",
   "module": "src/index.ts",
@@ -34,7 +34,7 @@
     "layout"
   ],
   "dependencies": {
-    "@cel-tui/types": "0.4.1",
+    "@cel-tui/types": "0.6.0",
     "get-east-asian-width": "^1.5.0"
   },
   "peerDependencies": {

package/src/cel.ts

@@ -191,8 +191,19 @@ function findFocusedTIInTree(ln: LayoutNode): LayoutNode | null {
 
 // --- Input handling ---
 
-// Regex for a single SGR mouse event (non-anchored, for scanning batched input)
-const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g;
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+
+// Regex for a single SGR mouse event, anchored to the current parse position.
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+
+// Trailing keyboard data that ended with an incomplete CSI sequence.
+let pendingKeyData = "";
+
+// Bracketed paste state across stdin chunks.
+let inBracketedPaste = false;
+let bracketedPasteData = "";
+let bracketedPasteSuffix = "";
 
 // Tracks accumulated scroll offsets during a batch of mouse events.
 // Controlled scroll reads scrollOffset from props, which doesn't update until
@@ -206,32 +217,61 @@ let batchScrollOffsets: Map<object, number> | null = null;
 let batchTextInputEdits: Map<TextInputProps, EditState> | null = null;
 
 function handleInput(data: string): void {
-  SGR_MOUSE_RE.lastIndex = 0;
   batchTextInputEdits = new Map();
 
-  let lastIndex = 0;
-
   try {
-    let match = SGR_MOUSE_RE.exec(data);
-    while (match) {
-      if (match.index > lastIndex) {
-        handleKeyChunk(data.slice(lastIndex, match.index));
-      }
+    let remaining = data;
+
+    if (inBracketedPaste) {
+      remaining = consumeBracketedPasteData(remaining);
+      if (remaining.length === 0) return;
+    }
+
+    let chunk = pendingKeyData + remaining;
+    pendingKeyData = "";
+
+    let keyChunkStart = 0;
+    let index = 0;
+
+    while (index < chunk.length) {
+      if (chunk.startsWith(BRACKETED_PASTE_START, index)) {
+        handleKeyChunk(chunk.slice(keyChunkStart, index));
+
+        index += BRACKETED_PASTE_START.length;
+        keyChunkStart = index;
+        inBracketedPaste = true;
+
+        const afterPaste = consumeBracketedPasteData(chunk.slice(index));
+        if (afterPaste.length === 0) return;
 
-      if (batchScrollOffsets === null) {
-        batchScrollOffsets = new Map();
+        chunk = afterPaste;
+        index = 0;
+        keyChunkStart = 0;
+        continue;
       }
 
-      const mouse = parseSgrMatch(match);
-      if (mouse) handleMouseEvent(mouse);
+      const mouse = readSgrMouseEvent(chunk, index);
+      if (mouse) {
+        handleKeyChunk(chunk.slice(keyChunkStart, index));
 
-      lastIndex = match.index + match[0].length;
-      match = SGR_MOUSE_RE.exec(data);
-    }
+        if (batchScrollOffsets === null) {
+          batchScrollOffsets = new Map();
+        }
+        if (mouse.event) handleMouseEvent(mouse.event);
+
+        index = mouse.nextIndex;
+        keyChunkStart = index;
+        continue;
+      }
 
-    if (lastIndex < data.length) {
-      handleKeyChunk(data.slice(lastIndex));
+      index++;
     }
+
+    const { complete, pending } = splitIncompleteCsiSuffix(
+      chunk.slice(keyChunkStart),
+    );
+    handleKeyChunk(complete);
+    pendingKeyData = pending;
   } finally {
     batchScrollOffsets = null;
     batchTextInputEdits = null;
@@ -245,12 +285,84 @@ function handleKeyChunk(data: string): void {
   }
 }
 
+function consumeBracketedPasteData(data: string): string {
+  const chunk = bracketedPasteSuffix + data;
+  bracketedPasteSuffix = "";
+
+  const endIndex = chunk.indexOf(BRACKETED_PASTE_END);
+  if (endIndex === -1) {
+    const { complete, pending } = splitTrailingMarkerPrefix(
+      chunk,
+      BRACKETED_PASTE_END,
+    );
+    bracketedPasteData += complete;
+    bracketedPasteSuffix = pending;
+    return "";
+  }
+
+  bracketedPasteData += chunk.slice(0, endIndex);
+  const pastedText = bracketedPasteData;
+
+  inBracketedPaste = false;
+  bracketedPasteData = "";
+  bracketedPasteSuffix = "";
+  handleBracketedPaste(pastedText);
+
+  return chunk.slice(endIndex + BRACKETED_PASTE_END.length);
+}
+
+function splitTrailingMarkerPrefix(
+  data: string,
+  marker: string,
+): { complete: string; pending: string } {
+  const maxPrefixLength = Math.min(data.length, marker.length - 1);
+  for (let length = maxPrefixLength; length > 0; length--) {
+    if (data.endsWith(marker.slice(0, length))) {
+      return {
+        complete: data.slice(0, data.length - length),
+        pending: data.slice(data.length - length),
+      };
+    }
+  }
+  return { complete: data, pending: "" };
+}
+
+function splitIncompleteCsiSuffix(data: string): {
+  complete: string;
+  pending: string;
+} {
+  const csiStart = data.lastIndexOf("\x1b[");
+  if (csiStart === -1) return { complete: data, pending: "" };
+
+  const suffix = data.slice(csiStart);
+  for (let i = 2; i < suffix.length; i++) {
+    const code = suffix.charCodeAt(i);
+    if (code >= 0x40 && code <= 0x7e) {
+      return { complete: data, pending: "" };
+    }
+  }
+
+  return { complete: data.slice(0, csiStart), pending: suffix };
+}
+
 interface MouseEvent {
   type: "click" | "scroll-up" | "scroll-down";
   x: number;
   y: number;
 }
 
+function readSgrMouseEvent(
+  data: string,
+  index: number,
+): { event: MouseEvent | null; nextIndex: number } | null {
+  const match = SGR_MOUSE_RE.exec(data.slice(index));
+  if (!match) return null;
+  return {
+    event: parseSgrMatch(match),
+    nextIndex: index + match[0].length,
+  };
+}
+
 /**
  * Parse a single SGR mouse event from a RegExp match.
  * Returns a MouseEvent for scroll and click events, null for unhandled buttons.
@@ -610,6 +722,31 @@ function getTextInputEditState(props: TextInputProps): EditState {
   };
 }
 
+function commitTextInputEdit(
+  props: TextInputProps,
+  previousState: EditState,
+  nextState: EditState,
+): void {
+  batchTextInputEdits?.set(props, nextState);
+  setTextInputCursor(props, nextState.cursor);
+  if (nextState.value !== previousState.value) {
+    props.onChange(nextState.value);
+  }
+  cel.render();
+}
+
+function handleBracketedPaste(text: string): void {
+  if (text.length === 0) return;
+
+  const focusedInput = findFocusedTextInput();
+  if (!focusedInput) return;
+
+  const props = focusedInput.node.props as TextInputProps;
+  const editState = getTextInputEditState(props);
+  const nextState = insertChar(editState, text);
+  commitTextInputEdit(props, editState, nextState);
+}
+
 function handleKeyEvent(event: KeyInput): void {
   const { key, text } = event;
 
@@ -750,12 +887,7 @@ function handleKeyEvent(event: KeyInput): void {
     }
 
     if (newState && newState !== editState) {
-      batchTextInputEdits?.set(props, newState);
-      setTextInputCursor(props, newState.cursor);
-      if (newState.value !== editState.value) {
-        props.onChange(newState.value);
-      }
-      cel.render();
+      commitTextInputEdit(props, editState, newState);
       return;
     }
   }
@@ -874,8 +1006,8 @@ export const cel = {
    * Initialize the framework with a terminal implementation.
    * Must be called before {@link cel.viewport}.
    *
-   * Enables the Kitty keyboard protocol (level 1) via the terminal,
-   * enters raw mode, and starts mouse tracking.
+   * Enables the Kitty keyboard protocol (level 1) and bracketed paste mode via
+   * the terminal, enters raw mode, and starts mouse tracking.
    *
    * @param term - Terminal to render to (ProcessTerminal or MockTerminal).
    * @param options - Optional configuration.
@@ -914,8 +1046,8 @@ export const cel = {
   /**
    * Stop the framework and restore terminal state.
    *
-   * Pops the Kitty keyboard protocol mode, disables mouse tracking,
-   * and restores the terminal to its previous state.
+   * Pops the Kitty keyboard protocol mode, disables bracketed paste and mouse
+   * tracking, and restores the terminal to its previous state.
    */
   stop(): void {
     terminal?.stop();
@@ -930,6 +1062,10 @@ export const cel = {
     stampedNode = null;
     uncontrolledScrollOffsets.clear();
     stampedScrollNodes = [];
+    pendingKeyData = "";
+    inBracketedPaste = false;
+    bracketedPasteData = "";
+    bracketedPasteSuffix = "";
     lastTerminalCursor = { visible: false };
     activeTheme = defaultTheme;
   },

package/src/index.ts

@@ -2,8 +2,9 @@
  * @module @cel-tui/core
  *
  * Core framework package. Provides the four primitives ({@link VStack},
- * {@link HStack}, {@link Text}, {@link TextInput}) and the framework
- * entrypoint ({@link cel}).
+ * {@link HStack}, {@link Text}, {@link TextInput}), the framework
+ * entrypoint ({@link cel}), and measurement helpers such as
+ * {@link measureContentHeight}.
  *
  * All types are re-exported from `@cel-tui/types`.
  *
@@ -45,6 +46,7 @@ export { VStack, HStack } from "./primitives/stacks.js";
 export { Text } from "./primitives/text.js";
 export { TextInput } from "./primitives/text-input.js";
 export { cel } from "./cel.js";
+export { measureContentHeight } from "./layout.js";
 export { CellBuffer, EMPTY_CELL, type Cell } from "./cell-buffer.js";
 export { emitBuffer, defaultTheme } from "./emitter.js";
 export { visibleWidth, extractAnsiCode } from "./width.js";

package/src/layout.ts

@@ -121,6 +121,15 @@ function intrinsicMainSize(
           resolveSizeValue(cProps?.width, 0) ??
           intrinsicMainSize(child, false, innerCross);
       }
+      if (cProps) {
+        const minMain = isVertical
+          ? (cProps.minHeight ?? 0)
+          : (cProps.minWidth ?? 0);
+        const maxMain = isVertical
+          ? (cProps.maxHeight ?? Infinity)
+          : (cProps.maxWidth ?? Infinity);
+        childMain = clamp(childMain, minMain, maxMain);
+      }
       total += childMain;
       if (i < node.children.length - 1) total += gap;
     }
@@ -150,9 +159,12 @@ function intrinsicMainSize(
         }
       }
       wrapWidths.push(w);
-      const h =
+      let h =
         resolveSizeValue(cProps?.height, 0) ??
         intrinsicMainSize(child, true, innerCross);
+      if (cProps) {
+        h = clamp(h, cProps.minHeight ?? 0, cProps.maxHeight ?? Infinity);
+      }
       wrapHeights.push(h);
     }
     const wrapRows = assignWrapRows(wrapWidths, innerCross, gap);
@@ -259,6 +271,37 @@ function largestRemainder(fractions: number[], total: number): number[] {
 
 // --- Main layout ---
 
+/**
+ * Measure a node tree's intrinsic content height at the provided width.
+ *
+ * This is a content-measurement helper, not a viewport/clipping helper.
+ * The caller-provided `width` is the authoritative wrapping width for the
+ * measured subtree. Measurement starts at the given node, ignores that
+ * node's own main-axis height constraints, and walks downward through its
+ * descendants. Descendant sizing rules still apply normally.
+ *
+ * Use this for intrinsically sized content such as scrollback/message
+ * history chunks. If a wrapper's visible height is controlled by `height`,
+ * `flex`, or percentage sizing, measure the content subtree inside that
+ * wrapper instead.
+ *
+ * @example
+ * ```ts
+ * const addedHeight = measureContentHeight(
+ *   VStack({}, olderMessages.map(renderMessage)),
+ *   { width: historyContentWidth },
+ * );
+ *
+ * scrollOffset += addedHeight;
+ * ```
+ */
+export function measureContentHeight(
+  node: Node,
+  options: { width: number },
+): number {
+  return intrinsicMainSize(node, true, options.width);
+}
+
 /**
  * Compute the layout for a UI tree.
  *

package/src/terminal.ts

@@ -12,8 +12,8 @@ export interface Terminal {
   /** Terminal height in rows. */
   get rows(): number;
   /**
-   * Enter raw mode, enable Kitty level 1 keyboard reporting, enable mouse
-   * tracking, and hide the cursor.
+   * Enter raw mode, enable Kitty level 1 keyboard reporting, enable bracketed
+   * paste mode, enable mouse tracking, and hide the cursor.
    *
    * The framework prefers Kitty semantics but its parser also accepts mixed
    * tmux/legacy keyboard encodings that may still arrive on stdin.
@@ -30,10 +30,11 @@ export interface Terminal {
 /**
  * Real terminal using process.stdin/stdout.
  *
- * Enables Kitty keyboard protocol level 1, SGR mouse tracking, and raw mode.
- * The runtime prefers Kitty semantics for full modifier fidelity, while the
- * parser remains compatible with mixed tmux/legacy keyboard encodings that
- * may still arrive on stdin. All modes are restored on stop/crash.
+ * Enables Kitty keyboard protocol level 1, bracketed paste mode, SGR mouse
+ * tracking, and raw mode. The runtime prefers Kitty semantics for full
+ * modifier fidelity, while the parser remains compatible with mixed
+ * tmux/legacy keyboard encodings that may still arrive on stdin. All modes are
+ * restored on stop/crash.
  */
 export class ProcessTerminal implements Terminal {
   private wasRaw = false;
@@ -76,6 +77,8 @@ export class ProcessTerminal implements Terminal {
     this.write("\x1b[?1049h");
     // Enable Kitty keyboard protocol level 1 (disambiguate) with push flag
     this.write("\x1b[>1u");
+    // Enable bracketed paste mode
+    this.write("\x1b[?2004h");
     // Enable mouse tracking (normal mode) + SGR encoding
     this.write("\x1b[?1000h\x1b[?1006h");
     this.hideCursor();
@@ -110,6 +113,8 @@ export class ProcessTerminal implements Terminal {
 
     // Disable mouse tracking + SGR encoding
     this.write("\x1b[?1006l\x1b[?1000l");
+    // Disable bracketed paste mode
+    this.write("\x1b[?2004l");
     // Pop Kitty keyboard protocol mode
     this.write("\x1b[<u");
     this.showCursor();