@valyrianjs/terminal 0.2.1 → 0.2.3

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,6 +41,11 @@ import type {
 
 type TerminalInputStream = NonNullable<TerminalMountOptions["stdin"]>;
 
+type InternalTerminalHitbox = TerminalHitbox & {
+  __listItemIndex?: number;
+  __pressHandler?: (event: TerminalButtonPressEventPayload) => void;
+};
+
 interface ResolvedRuntimeOptions {
   runtime: "app" | "headless";
   stdin?: TerminalInputStream;
@@ -58,6 +64,8 @@ const KNOWN_TERMINAL_KEY_SEQUENCES = [
   "\u001b[13;129u",
   "\u001b[27;2;13~",
   "\u001b[13;2~",
+  "\u001b[1;2A",
+  "\u001b[1;2B",
   "\u001b[1;2C",
   "\u001b[1;2D",
   "\u001b[1;3C",
@@ -93,6 +101,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");
 }
@@ -108,7 +148,6 @@ function isValidTerminalDimension(value: number | undefined): value is number {
   return Number.isInteger(value) && Number(value) >= 1;
 }
 
-
 function getProcessStdin(): TerminalInputStream | undefined {
   const candidate = globalThis.process?.stdin as TerminalInputStream | undefined;
   return candidate && typeof candidate.on === "function" ? candidate : undefined;
@@ -252,7 +291,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 });
@@ -270,6 +309,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) {
@@ -306,9 +367,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() {
@@ -327,7 +389,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;
   }
@@ -478,7 +540,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));
     }
@@ -539,7 +601,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];
@@ -668,7 +729,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;
     }
@@ -1163,7 +1224,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);
@@ -1341,6 +1402,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));
@@ -1398,7 +1471,6 @@ export function mountTerminal(input: any, options: TerminalMountOptions = {}): T
     }
   }
 
-
   function isPrimaryMouseButton(button: number) {
     return button < 64 && (button & 3) === 0;
   }
@@ -1572,6 +1644,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,22 @@ 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;
+
+type GraphemeSegmenter = {
+  segment(value: string): Iterable<{ segment: string }>;
+};
+
+const Segmenter = (Intl as unknown as {
+  Segmenter?: new (locale?: string, options?: { granularity: "grapheme" }) => GraphemeSegmenter;
+}).Segmenter;
+
+const GRAPHEME_SEGMENTER = typeof Segmenter === "function"
+  ? new Segmenter(undefined, { granularity: "grapheme" })
+  : null;
 
 export function stripTerminalControls(value: unknown) {
   return String(value)
@@ -18,3 +34,147 @@ export function stripTerminalControls(value: unknown) {
 }
 
 export const plainText = stripTerminalControls;
+
+export function terminalGraphemes(value: string): string[] {
+  if (GRAPHEME_SEGMENTER !== null) {
+    return Array.from(GRAPHEME_SEGMENTER.segment(value), (part) => part.segment);
+  }
+
+  return Array.from(value);
+}
+
+function isWideCodePoint(codePoint: number) {
+  return (
+    codePoint >= 0x1100 && (
+      codePoint <= 0x115f
+      || codePoint === 0x2329
+      || codePoint === 0x232a
+      || (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+      || (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+      || (codePoint >= 0xf900 && codePoint <= 0xfaff)
+      || (codePoint >= 0xfe10 && codePoint <= 0xfe19)
+      || (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+      || (codePoint >= 0xff00 && codePoint <= 0xff60)
+      || (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+      || (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+    )
+  );
+}
+
+function isZeroWidthCodePoint(codePoint: number, char: string) {
+  return codePoint === 0x200d
+    || (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+    || (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+    || COMBINING_MARK.test(char);
+}
+
+function graphemeCellWidth(grapheme: string) {
+  if (grapheme.length === 0) {
+    return 0;
+  }
+
+  if (grapheme.includes("\u200d") || EMOJI_PRESENTATION.test(grapheme)) {
+    return 2;
+  }
+
+  let width = 0;
+  for (const char of Array.from(grapheme)) {
+    const codePoint = char.codePointAt(0);
+    if (typeof codePoint !== "number") {
+      continue;
+    }
+    if (isZeroWidthCodePoint(codePoint, char)) {
+      continue;
+    }
+    width = Math.max(width, isWideCodePoint(codePoint) ? 2 : 1);
+  }
+
+  return width;
+}
+
+export function terminalCellWidth(value: unknown) {
+  const text = stripTerminalControls(value);
+  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) {
+  const limit = Math.max(0, Math.trunc(Number(maxCells) || 0));
+  let width = 0;
+  let output = "";
+
+  for (const grapheme of terminalGraphemes(value)) {
+    const graphemeWidth = graphemeCellWidth(grapheme);
+    if (graphemeWidth > 0 && width + graphemeWidth > limit) {
+      break;
+    }
+    output += grapheme;
+    width += graphemeWidth;
+  }
+
+  return output;
+}
+
+export function dropTerminalCells(value: string, cells: number) {
+  const limit = Math.max(0, Math.trunc(Number(cells) || 0));
+  let width = 0;
+  let output = "";
+  let dropping = true;
+
+  for (const grapheme of terminalGraphemes(value)) {
+    if (dropping) {
+      const graphemeWidth = graphemeCellWidth(grapheme);
+      if (width < limit || (graphemeWidth === 0 && width <= limit)) {
+        width += graphemeWidth;
+        continue;
+      }
+      dropping = false;
+    }
+    output += grapheme;
+  }
+
+  return output;
+}
+
+export function padEndTerminalCells(value: string, width: number) {
+  const size = Math.max(0, Math.trunc(Number(width) || 0));
+  const visibleWidth = terminalCellWidth(value);
+  return visibleWidth >= size ? value : `${value}${" ".repeat(size - visibleWidth)}`;
+}
+
+export function terminalCellToStringIndex(value: string) {
+  const indexes: number[] = [0];
+  let cellOffset = 0;
+  let stringIndex = 0;
+
+  for (const grapheme of terminalGraphemes(value)) {
+    const graphemeWidth = graphemeCellWidth(grapheme);
+    const nextStringIndex = stringIndex + grapheme.length;
+
+    if (graphemeWidth > 0) {
+      for (let cell = 1; cell < graphemeWidth; cell += 1) {
+        indexes[cellOffset + cell] = nextStringIndex;
+      }
+      cellOffset += graphemeWidth;
+      indexes[cellOffset] = nextStringIndex;
+    }
+
+    stringIndex = nextStringIndex;
+  }
+
+  indexes[cellOffset] = stringIndex;
+  return indexes;
+}
+
+export function cursorCellOffset(value: string, cursor: number) {
+  return terminalCellWidth(value.slice(0, Math.max(0, Math.trunc(Number(cursor) || 0))));
+}

package/src/theme.ts

@@ -183,6 +183,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 +259,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 +282,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

@@ -129,12 +129,11 @@ export interface TerminalHitbox {
   y2: number;
   textStartX?: number;
   textLength?: number;
+  textCellToStringIndex?: number[];
   itemOffset?: number;
   itemIndexes?: number[];
   contentY?: number;
   pointerLayer?: number;
-  __listItemIndex?: number;
-  __pressHandler?: (event: TerminalButtonPressEventPayload) => void;
 }
 
 export interface CursorPosition {
@@ -387,7 +386,9 @@ export interface TerminalInputProps extends TerminalFocusableProps, TerminalStyl
 export interface TerminalEditorProps extends TerminalFocusableProps, TerminalStyleProps {
   value?: string;
   placeholder?: string;
+  width?: number;
   height?: number;
+  fill?: boolean;
   onchange?(event: TerminalEditorChangeEventPayload): void;
   oninput?(event: TerminalEditorChangeEventPayload): void;
   onsubmit?(event: TerminalEditorSubmitEventPayload): void;