@valyrianjs/terminal 0.2.2 → 0.2.4

package/src/session.ts

@@ -7,18 +7,19 @@ import { mergeVertical } from "./layout.js";
 import { cursorFromHitbox, parseTerminalInput, parseTerminalMousePrefix, resolvePointerTarget } from "./mouse.js";
 import { createOutputWriter } from "./output-writer.js";
 import { parseBracketedPaste } from "./paste.js";
-import { renderTerminalFrame } from "./render.js";
+import { renderTerminalFrame } from "./render-internal.js";
 import { createRenderScheduler } from "./scheduler.js";
 import { plainText, stripTerminalControls } from "./text.js";
 import { collectActiveFocusScopeFocusableNodes, collectDirectOverlayFocusableNodes, collectFocusableNodes, findFocusableById, findFocused } from "./tree.js";
 import { createValyrianTerminalRuntime } from "./runtime.js";
 
-import type { TerminalRenderContext } from "./render.js";
+import type { TerminalRenderContext } from "./render-internal.js";
 
 import type { EditorState } from "./editor-state.js";
 
 import type {
   InputInteractionState,
+  TerminalButtonPressEventPayload,
   TerminalCommand,
   TerminalCommandContext,
   TerminalCaptureEventPayload,
@@ -40,13 +41,18 @@ import type {
 
 type TerminalInputStream = NonNullable<TerminalMountOptions["stdin"]>;
 
+type InternalTerminalHitbox = TerminalHitbox & {
+  __listItemIndex?: number;
+  __pressHandler?: (event: TerminalButtonPressEventPayload) => void;
+};
+
 interface ResolvedRuntimeOptions {
   runtime: "app" | "headless";
   stdin?: TerminalInputStream;
   stdout?: TerminalOutputStream;
   alternateScreen: boolean;
   hideCursor: boolean;
-  mouseReporting: boolean;
+  mouseInput: boolean;
   writesAnsi: boolean;
 }
 
@@ -82,6 +88,7 @@ const KNOWN_TERMINAL_KEY_SEQUENCES = [
 const ESCAPE = "\u001b";
 const CSI_PREFIX = "\u001b[";
 const DOUBLE_PRESS_INTERVAL_MS = 500;
+const MODAL_OVERLAY_HITBOX_ID = "\u0000valyrian-overlay-modal-shield";
 
 function isBracketedPasteStartPrefix(value: string) {
   return value.length > 0 && value.length < BRACKETED_PASTE_START.length && BRACKETED_PASTE_START.startsWith(value);
@@ -95,6 +102,38 @@ function isKnownTerminalKeySequencePrefix(value: string) {
   return KNOWN_TERMINAL_KEY_SEQUENCES.some((sequence) => value.length > 0 && value.length < sequence.length && sequence.startsWith(value));
 }
 
+function isSgrMouseSequencePrefix(value: string) {
+  return /^\u001b\[<(?:\d+)?(?:;(?:\d+)?)?(?:;(?:\d+)?)?$/.test(value);
+}
+
+function isDigit(value: string) {
+  return value >= "0" && value <= "9";
+}
+
+function restAfterInvalidSgrMouseSequence(value: string) {
+  if (!value.startsWith("\u001b[<")) {
+    return null;
+  }
+
+  let separators = 0;
+  for (let index = "\u001b[<".length; index < value.length; index += 1) {
+    const char = value[index];
+    if (isDigit(char)) {
+      continue;
+    }
+    if (char === ";" && separators < 2) {
+      separators += 1;
+      continue;
+    }
+    if (char === "M" || char === "m") {
+      return value.slice(index + 1);
+    }
+    return value.slice(index);
+  }
+
+  return null;
+}
+
 function canContinueEscapeSequence(value: string) {
   return value.startsWith("[") || value.startsWith("b") || value.startsWith("f");
 }
@@ -110,6 +149,20 @@ function isValidTerminalDimension(value: number | undefined): value is number {
   return Number.isInteger(value) && Number(value) >= 1;
 }
 
+function isModalOverlayShieldHitbox(hitbox: TerminalHitbox | null | undefined) {
+  return hitbox?.id === MODAL_OVERLAY_HITBOX_ID;
+}
+
+function hitboxIsAboveModalShield(hitboxes: TerminalHitbox[], id: string) {
+  const shieldIndex = hitboxes.findIndex((box) => isModalOverlayShieldHitbox(box));
+  if (shieldIndex < 0) {
+    return true;
+  }
+
+  const hitboxIndex = hitboxes.findIndex((box) => box.id === id);
+  return hitboxIndex >= 0 && hitboxIndex < shieldIndex;
+}
+
 
 function getProcessStdin(): TerminalInputStream | undefined {
   const candidate = globalThis.process?.stdin as TerminalInputStream | undefined;
@@ -140,7 +193,7 @@ function resolveRuntimeOptions(options: TerminalMountOptions): ResolvedRuntimeOp
     stdout,
     alternateScreen: options.alternateScreen ?? ownsInteractiveTTY,
     hideCursor: options.hideCursor ?? ownsInteractiveTTY,
-    mouseReporting: ownsInteractiveTTY,
+    mouseInput: ownsInteractiveTTY,
     writesAnsi: runtime === "app" && Boolean(stdout)
   };
 }
@@ -254,7 +307,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
   applyInteractiveState(currentTree, focusedId, inputStateById, editorStateById, listIndexById, listSelectedIndexById, listViewportOffsetById, scrollOffsetById, listHoverById, scrollHoverRowById);
   let currentFrame = renderTreeFrame(currentTree);
   let currentOutput = formatPlainFrame(currentFrame, { theme: options.theme }).trimEnd();
-  let currentHitboxes = currentFrame.hitboxes;
+  let currentHitboxes = currentFrame.hitboxes as InternalTerminalHitbox[];
 
   const outputWriter = createOutputWriter(runtimeOptions.stdout);
   const toAnsiDiff = createAnsiDiffWriter({ showCursor: !runtimeOptions.hideCursor, showCursorWhenFrameHasCursor: true, theme: options.theme });
@@ -272,6 +325,28 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     return mergeVertical(nodes.map((node) => renderTerminalFrame(node, context)));
   }
 
+  function publicTerminalNodes(nodes: TerminalNode[]): TerminalNode[] {
+    return nodes.map((node) => {
+      if (node.type === "text") {
+        return { ...node };
+      }
+
+      const publicProps: Record<string, any> = {};
+      for (const [key, value] of Object.entries(node.props)) {
+        if (!key.startsWith("__")) {
+          publicProps[key] = value;
+        }
+      }
+
+      return {
+        type: node.type,
+        tag: node.tag,
+        props: publicProps,
+        children: publicTerminalNodes(node.children)
+      };
+    });
+  }
+
   function emitLifecycleSetup() {
     const writes: string[] = [];
     if (runtimeOptions.alternateScreen) {
@@ -280,7 +355,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     if (runtimeOptions.hideCursor) {
       writes.push(ANSI_HIDE_CURSOR);
     }
-    if (runtimeOptions.mouseReporting) {
+    if (runtimeOptions.mouseInput) {
       writes.push(ANSI_ENABLE_MOUSE_REPORTING);
     }
     if (writes.length > 0) {
@@ -293,7 +368,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
       return;
     }
     const writes: string[] = [];
-    if (runtimeOptions.mouseReporting) {
+    if (runtimeOptions.mouseInput) {
       writes.push(ANSI_DISABLE_MOUSE_REPORTING);
     }
     if (runtimeOptions.hideCursor) {
@@ -308,9 +383,10 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
   }
 
   function emitOutput() {
-    if (!destroyed) {
-      outputWriter.write(runtimeOptions.writesAnsi ? toAnsiDiff(currentFrame.lines, currentFrame.cursor, currentFrame.spans) : currentOutput);
+    if (destroyed) {
+      return;
     }
+    outputWriter.write(runtimeOptions.writesAnsi ? toAnsiDiff(currentFrame.lines, currentFrame.cursor, currentFrame.spans) : currentOutput);
   }
 
   function renderNow() {
@@ -329,7 +405,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     applyInteractiveState(currentTree, focusedId, inputStateById, editorStateById, listIndexById, listSelectedIndexById, listViewportOffsetById, scrollOffsetById, listHoverById, scrollHoverRowById);
     currentFrame = renderTreeFrame(currentTree);
     currentOutput = formatPlainFrame(currentFrame, { theme: options.theme }).trimEnd();
-    currentHitboxes = currentFrame.hitboxes;
+    currentHitboxes = currentFrame.hitboxes as InternalTerminalHitbox[];
     emitOutput();
     return currentOutput;
   }
@@ -480,7 +556,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     return 1;
   }
 
-  function sourceRowFromHitbox(node: TerminalFocusNode, hitbox: { itemOffset?: number; itemIndexes?: number[]; y1: number; y2: number; contentY?: number; __listItemIndex?: number }, y: number) {
+  function sourceRowFromHitbox(node: TerminalFocusNode, hitbox: InternalTerminalHitbox, y: number) {
     if (node.tag === "terminal-list" && typeof hitbox.__listItemIndex === "number" && y >= hitbox.y1 && y <= hitbox.y2) {
       return Math.max(1, Math.min(rowCountForNode(node), hitbox.__listItemIndex + 1));
     }
@@ -541,7 +617,6 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     }
   }
 
-
   function listItemKey(node: TerminalFocusNode, index: number) {
     const items = Array.isArray(node.props.items) ? node.props.items : [];
     const item = items[index];
@@ -670,7 +745,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     return dispatchNodeEvent(node, type, { type, id });
   }
 
-  function dispatchHitboxButtonPressEvent(hitbox: TerminalHitbox, type: "press" | "doublepress" | "contextpress") {
+  function dispatchHitboxButtonPressEvent(hitbox: InternalTerminalHitbox, type: "press" | "doublepress" | "contextpress") {
     if (type !== "press" || typeof hitbox.__pressHandler !== "function") {
       return false;
     }
@@ -804,11 +879,19 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
 
   function hoverAt(x: number, y: number) {
     const hitbox = resolvePointerTarget(currentHitboxes, x, y);
-    if (!hitbox) {
-      if (pointerCaptureId) {
+    if (!hitbox || isModalOverlayShieldHitbox(hitbox)) {
+      if (pointerCaptureId && (!hitbox || hitboxIsAboveModalShield(currentHitboxes, pointerCaptureId))) {
         setSemanticHoverFromHitbox(pointerCaptureId, x, y);
         return rerender();
       }
+      if (pointerCaptureId) {
+        const capturedHitbox = currentHitboxes.find((box) => box.id === pointerCaptureId);
+        const capturedNode = findFocusableById(currentTree, pointerCaptureId);
+        const capturedRow = capturedHitbox && capturedNode
+          ? sourceRowFromHitbox(capturedNode, capturedHitbox, y)
+          : hoveredRowForNode(capturedNode);
+        setPointerCapture(null, "drag", capturedRow, x, y);
+      }
       clearSemanticHover(undefined, x, y);
       return rerender();
     }
@@ -910,7 +993,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
 
   function wheelAt(x: number, y: number, direction: -1 | 1) {
     const hitbox = resolvePointerTarget(currentHitboxes, x, y);
-    if (!hitbox) {
+    if (!hitbox || isModalOverlayShieldHitbox(hitbox)) {
       return currentOutput;
     }
 
@@ -1165,7 +1248,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
       return toAnsiFrame(currentFrame.lines, currentFrame.cursor, currentFrame.spans, { showCursor: !options.hideCursor, showCursorWhenFrameHasCursor: true, theme: options.theme });
     },
     tree() {
-      return currentTree;
+      return publicTerminalNodes(currentTree);
     },
     focus(id: string) {
       const node = findFocusableById(currentTree, id);
@@ -1178,7 +1261,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     },
     focusAt(x: number, y: number) {
       const hitbox = resolvePointerTarget(currentHitboxes, x, y);
-      if (!hitbox) {
+      if (!hitbox || isModalOverlayShieldHitbox(hitbox)) {
         clearSemanticHover(undefined, x, y);
         return false;
       }
@@ -1238,7 +1321,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     },
     clickAt(x: number, y: number) {
       const hitbox = resolvePointerTarget(currentHitboxes, x, y);
-      if (!hitbox) {
+      if (!hitbox || isModalOverlayShieldHitbox(hitbox)) {
         clearSemanticHover(undefined, x, y);
         return currentOutput;
       }
@@ -1343,6 +1426,18 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
       return;
     }
 
+    const parsedMouse = parseTerminalMousePrefix(value);
+    if (parsedMouse) {
+      processParsedMouseInput(parsedMouse.input);
+      processInputStream(parsedMouse.rest);
+      return;
+    }
+
+    if (isSgrMouseSequencePrefix(value)) {
+      pendingKeyChunk = value;
+      return;
+    }
+
     for (const sequence of KNOWN_TERMINAL_KEY_SEQUENCES) {
       if (value.startsWith(sequence)) {
         session.dispatchKey(parseTerminalKey(sequence));
@@ -1400,7 +1495,6 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     }
   }
 
-
   function isPrimaryMouseButton(button: number) {
     return button < 64 && (button & 3) === 0;
   }
@@ -1442,7 +1536,7 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
 
   function contextPressAt(x: number, y: number) {
     const hitbox = resolvePointerTarget(currentHitboxes, x, y);
-    if (!hitbox) {
+    if (!hitbox || isModalOverlayShieldHitbox(hitbox)) {
       clearSemanticHover(undefined, x, y);
       return currentOutput;
     }
@@ -1514,7 +1608,12 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
         }
       } else if (parsed.action === "drag") {
         if (mouseSelectionId) {
-          setCursorFromHitbox(mouseSelectionId, parsed.x, true);
+          if (!hitboxIsAboveModalShield(currentHitboxes, mouseSelectionId)) {
+            mouseSelectionId = null;
+            hoverAt(parsed.x, parsed.y);
+          } else {
+            setCursorFromHitbox(mouseSelectionId, parsed.x, true);
+          }
         } else {
           hoverAt(parsed.x, parsed.y);
         }
@@ -1574,6 +1673,21 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
       const buffered = pendingKeyChunk + value;
       cancelPendingEscapeFlush();
       pendingKeyChunk = "";
+      if (isSgrMouseSequencePrefix(buffered)) {
+        pendingKeyChunk = buffered;
+        return;
+      }
+      const parsedBufferedMouse = parseTerminalMousePrefix(buffered);
+      if (parsedBufferedMouse) {
+        processParsedMouseInput(parsedBufferedMouse.input);
+        processInputStream(parsedBufferedMouse.rest);
+        return;
+      }
+      const restAfterInvalidSgrMouse = restAfterInvalidSgrMouseSequence(buffered);
+      if (typeof restAfterInvalidSgrMouse === "string") {
+        processInputStream(restAfterInvalidSgrMouse);
+        return;
+      }
       processKeyStream(buffered);
       return;
     }

package/src/text.ts

@@ -5,6 +5,8 @@ const C1_CSI_TERMINAL_CONTROL = /\u009b[0-?]*[ -/]*[@-~]/g;
 const ESC_TERMINAL_CONTROL = /\u001b[ -/]*[0-~]/g;
 const C1_TERMINAL_CONTROL = /[\u0080-\u009f]/g;
 const C0_TERMINAL_CONTROL = /[\u0000-\u0009\u000b-\u001f\u007f]/g;
+const CELL_WIDTH_CACHE_LIMIT = 4096;
+const cellWidthCache = new Map<string, number>();
 const COMBINING_MARK = /\p{Mark}/u;
 const EMOJI_PRESENTATION = /\p{Extended_Pictographic}/u;
 
@@ -92,7 +94,17 @@ function graphemeCellWidth(grapheme: string) {
 
 export function terminalCellWidth(value: unknown) {
   const text = stripTerminalControls(value);
-  return terminalGraphemes(text).reduce((width, grapheme) => width + graphemeCellWidth(grapheme), 0);
+  const cached = cellWidthCache.get(text);
+  if (typeof cached === "number") {
+    return cached;
+  }
+
+  const width = terminalGraphemes(text).reduce((total, grapheme) => total + graphemeCellWidth(grapheme), 0);
+  if (cellWidthCache.size >= CELL_WIDTH_CACHE_LIMIT) {
+    cellWidthCache.clear();
+  }
+  cellWidthCache.set(text, width);
+  return width;
 }
 
 export function sliceTerminalCells(value: string, maxCells: number) {

package/src/theme.ts

@@ -80,7 +80,7 @@ export const defaultTerminalTheme: TerminalTheme = {
     list: { base: { color: "#d8dee9" }, selected: { color: "#ffffff", background: "#2e3440" }, current: { color: "#ffffff", background: "#3b4252" }, hover: { color: "#ffffff", background: "#2b3137" }, empty: { color: "#777777" }, expanded: { color: "#b48ead" }, collapsed: { color: "#81a1c1" } },
     scroll: { base: { color: "#d8dee9" }, hover: { color: "#dddddd" } },
     log: { base: { color: "#d8dee9" }, empty: { color: "#777777" }, error: { color: "#bf616a" }, warning: { color: "#ebcb8b" }, success: { color: "#a3be8c" }, muted: { color: "#777777" } },
-    overlay: { base: { background: "#111111" }, dragging: { color: "#b48ead" }, dropTarget: { background: "#243b53" }, capturing: { color: "#d08770" } },
+    overlay: { base: { background: "#111111" }, backdrop: { background: "#000000" }, dragging: { color: "#b48ead" }, dropTarget: { background: "#243b53" }, capturing: { color: "#d08770" } },
     pane: {
       header: { background: "#3a3a3a", color: "#ffffff" },
       transcript: { background: "#303030", color: "#dddddd" },
@@ -107,6 +107,9 @@ export const defaultTerminalTheme: TerminalTheme = {
     focus: {
       background: "#1f2328"
     },
+    "editor.focus": {
+      background: "#161b22"
+    },
     "current-row": reverseVideoToken,
     hover: {
       ansiOpen: "\u001b[4m",
@@ -183,6 +186,26 @@ export function mergeTerminalTheme(theme?: TerminalTheme): TerminalTheme {
   };
 }
 
+const DEFAULT_MERGED_THEME = mergeTerminalTheme();
+// Maintainer note: theme objects are treated as immutable for the CLI lifetime.
+// Restart the CLI to apply theme changes instead of mutating a cached source theme.
+const MERGED_THEME_BY_SOURCE = new WeakMap<TerminalTheme, TerminalTheme>();
+
+function resolveMergedTerminalTheme(theme?: TerminalTheme): TerminalTheme {
+  if (typeof theme === "undefined") {
+    return DEFAULT_MERGED_THEME;
+  }
+
+  const cached = MERGED_THEME_BY_SOURCE.get(theme);
+  if (cached) {
+    return cached;
+  }
+
+  const merged = mergeTerminalTheme(theme);
+  MERGED_THEME_BY_SOURCE.set(theme, merged);
+  return merged;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -239,7 +262,7 @@ export function resolveTerminalStyle(value: TerminalStyleValue | undefined, them
   if (typeof value !== "string") {
     return { ...value, border: isPlainObject(value.border) ? { ...value.border } : value.border, padding: isPlainObject(value.padding) ? { ...value.padding } : value.padding };
   }
-  const merged = mergeTerminalTheme(theme);
+  const merged = resolveMergedTerminalTheme(theme);
   const parts = value.split(".").filter(Boolean);
   let node: unknown = merged.styles;
   for (const part of parts) {
@@ -262,5 +285,5 @@ export function resolveTerminalStyleToken(
   kind: TerminalSemanticStyleKind | (string & {}),
   theme?: TerminalTheme
 ): TerminalStyleToken | undefined {
-  return mergeTerminalTheme(theme).spans?.[kind];
+  return resolveMergedTerminalTheme(theme).spans?.[kind];
 }

package/src/types.ts

@@ -134,8 +134,6 @@ export interface TerminalHitbox {
   itemIndexes?: number[];
   contentY?: number;
   pointerLayer?: number;
-  __listItemIndex?: number;
-  __pressHandler?: (event: TerminalButtonPressEventPayload) => void;
 }
 
 export interface CursorPosition {
@@ -507,6 +505,7 @@ export interface TerminalOverlayMarginAxes {
 export interface TerminalOverlayProps extends TerminalFocusableProps, TerminalStyleProps {
   margin: TerminalOverlayMarginValue | TerminalOverlayMarginAxes;
   trapFocus?: boolean;
+  backdrop?: boolean | TerminalStyleValue;
 }
 
 export interface TerminalFocusScopeProps {