@opentui/core 0.0.0-20250923-da12fb15 → 0.0.0-20250924-9d06e8e4

package/3d.js

@@ -5,7 +5,7 @@ import {
   __export,
   __require,
   __toESM
-} from "./index-ce0mn4wa.js";
+} from "./index-bq6h36ne.js";
 
 // ../../node_modules/omggif/omggif.js
 var require_omggif = __commonJS((exports) => {

package/Renderable.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from "events";
 import { type Node as YogaNode } from "yoga-layout";
 import { OptimizedBuffer } from "./buffer";
-import type { ParsedKey } from "./lib/parse.keypress";
+import type { KeyEvent, PasteEvent } from "./lib/KeyHandler";
 import type { Selection } from "./lib/selection";
 import { type AlignString, type FlexDirectionString, type JustifyString, type OverflowString, type PositionTypeString, type WrapString } from "./lib/yoga.options";
 import { type VNode } from "./renderables/composition/vnode";
@@ -78,7 +78,7 @@ export interface RenderableOptions<T extends BaseRenderable = BaseRenderable> ex
     onMouseOut?: (this: T, event: MouseEvent) => void;
     onMouseScroll?: (this: T, event: MouseEvent) => void;
     onPaste?: (this: T, text: string) => void;
-    onKeyDown?: (key: ParsedKey) => void;
+    onKeyDown?: (key: KeyEvent) => void;
     onSizeChange?: (this: T) => void;
 }
 export declare function isRenderable(obj: any): obj is Renderable;
@@ -126,8 +126,8 @@ export declare abstract class Renderable extends BaseRenderable {
     protected frameBuffer: OptimizedBuffer | null;
     protected _focusable: boolean;
     protected _focused: boolean;
-    protected keypressHandler: ((key: ParsedKey) => void) | null;
-    protected pasteHandler: ((text: string) => void) | null;
+    protected keypressHandler: ((key: KeyEvent) => void) | null;
+    protected pasteHandler: ((event: PasteEvent) => void) | null;
     private _live;
     protected _liveCount: number;
     private _sizeChangeListener;
@@ -169,7 +169,7 @@ export declare abstract class Renderable extends BaseRenderable {
     get liveCount(): number;
     set live(value: boolean);
     protected propagateLiveCount(delta: number): void;
-    handleKeyPress?(key: ParsedKey | string): boolean;
+    handleKeyPress?(key: KeyEvent | string): boolean;
     handlePaste?(text: string): void;
     findDescendantById(id: string): Renderable | undefined;
     requestRender(): void;
@@ -276,8 +276,8 @@ export declare abstract class Renderable extends BaseRenderable {
     set onMouseScroll(handler: ((event: MouseEvent) => void) | undefined);
     set onPaste(handler: ((text: string) => void) | undefined);
     get onPaste(): ((text: string) => void) | undefined;
-    set onKeyDown(handler: ((key: ParsedKey) => void) | undefined);
-    get onKeyDown(): ((key: ParsedKey) => void) | undefined;
+    set onKeyDown(handler: ((key: KeyEvent) => void) | undefined);
+    get onKeyDown(): ((key: KeyEvent) => void) | undefined;
     set onSizeChange(handler: (() => void) | undefined);
     get onSizeChange(): (() => void) | undefined;
     private applyEventOptions;

package/animation/Timeline.d.ts

@@ -1,3 +1,4 @@
+import type { CliRenderer } from "../renderer";
 export interface TimelineOptions {
     duration?: number;
     loop?: boolean;
@@ -111,7 +112,7 @@ declare class TimelineEngine {
     defaults: {
         frameRate: number;
     };
-    attach(renderer: any): void;
+    attach(renderer: CliRenderer): void;
     detach(): void;
     private updateLiveState;
     private onTimelineStateChange;

package/{index-ce0mn4wa.js → index-bq6h36ne.js}

@@ -2191,6 +2191,62 @@ var ANSI = {
 };
 
 // src/lib/KeyHandler.ts
+class KeyEvent {
+  name;
+  ctrl;
+  meta;
+  shift;
+  option;
+  sequence;
+  number;
+  raw;
+  eventType;
+  code;
+  super;
+  hyper;
+  capsLock;
+  numLock;
+  baseCode;
+  _defaultPrevented = false;
+  constructor(key) {
+    this.name = key.name;
+    this.ctrl = key.ctrl;
+    this.meta = key.meta;
+    this.shift = key.shift;
+    this.option = key.option;
+    this.sequence = key.sequence;
+    this.number = key.number;
+    this.raw = key.raw;
+    this.eventType = key.eventType;
+    this.code = key.code;
+    this.super = key.super;
+    this.hyper = key.hyper;
+    this.capsLock = key.capsLock;
+    this.numLock = key.numLock;
+    this.baseCode = key.baseCode;
+  }
+  get defaultPrevented() {
+    return this._defaultPrevented;
+  }
+  preventDefault() {
+    this._defaultPrevented = true;
+  }
+}
+
+class PasteEvent {
+  text;
+  _defaultPrevented = false;
+  constructor(text) {
+    this.text = text;
+  }
+  get defaultPrevented() {
+    return this._defaultPrevented;
+  }
+  preventDefault() {
+    this._defaultPrevented = true;
+  }
+}
+
 class KeyHandler extends EventEmitter {
   stdin;
   useKittyKeyboard;
@@ -2210,7 +2266,7 @@ class KeyHandler extends EventEmitter {
         this.pasteBuffer.push(Bun.stripANSI(data));
         if (data.endsWith(ANSI.bracketedPasteEnd)) {
           this.pasteMode = false;
-          this.emit("paste", this.pasteBuffer.join(""));
+          this.emit("paste", new PasteEvent(this.pasteBuffer.join("")));
           this.pasteBuffer = [];
         }
         return;
@@ -2218,16 +2274,16 @@ class KeyHandler extends EventEmitter {
       const parsedKey = parseKeypress(key, { useKittyKeyboard: this.useKittyKeyboard });
       switch (parsedKey.eventType) {
         case "press":
-          this.emit("keypress", parsedKey);
+          this.emit("keypress", new KeyEvent(parsedKey));
           break;
         case "repeat":
-          this.emit("keyrepeat", parsedKey);
+          this.emit("keyrepeat", new KeyEvent(parsedKey));
           break;
         case "release":
-          this.emit("keyrelease", parsedKey);
+          this.emit("keyrelease", new KeyEvent(parsedKey));
           break;
         default:
-          this.emit("keypress", parsedKey);
+          this.emit("keypress", new KeyEvent(parsedKey));
           break;
       }
     };
@@ -2238,6 +2294,45 @@ class KeyHandler extends EventEmitter {
   }
 }
 
+class InternalKeyHandler extends KeyHandler {
+  renderableHandlers = new Map;
+  constructor(stdin, useKittyKeyboard = false) {
+    super(stdin, useKittyKeyboard);
+  }
+  emit(event, ...args) {
+    return this.emitWithPriority(event, ...args);
+  }
+  emitWithPriority(event, ...args) {
+    const hasGlobalListeners = super.emit(event, ...args);
+    const renderableSet = this.renderableHandlers.get(event);
+    let hasRenderableListeners = false;
+    if (renderableSet && renderableSet.size > 0) {
+      hasRenderableListeners = true;
+      if (event === "keypress" || event === "keyrepeat" || event === "keyrelease" || event === "paste") {
+        const keyEvent = args[0];
+        if (keyEvent.defaultPrevented)
+          return hasGlobalListeners || hasRenderableListeners;
+      }
+      for (const handler of renderableSet) {
+        handler(...args);
+      }
+    }
+    return hasGlobalListeners || hasRenderableListeners;
+  }
+  onInternal(event, handler) {
+    if (!this.renderableHandlers.has(event)) {
+      this.renderableHandlers.set(event, new Set);
+    }
+    this.renderableHandlers.get(event).add(handler);
+  }
+  offInternal(event, handler) {
+    const handlers = this.renderableHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+  }
+}
+
 // src/lib/RGBA.ts
 class RGBA {
   buffer;
@@ -4814,6 +4909,166 @@ class ASCIIFontSelectionHelper {
     return previousSelection?.start !== this.localSelection?.start || previousSelection?.end !== this.localSelection?.end;
   }
 }
+
+// src/lib/singleton.ts
+var singletonCacheSymbol = Symbol.for("@opentui/core/singleton");
+function singleton(key, factory) {
+  const bag = globalThis[singletonCacheSymbol] ??= {};
+  if (!(key in bag)) {
+    bag[key] = factory();
+  }
+  return bag[key];
+}
+
+// src/lib/env.ts
+var envRegistry = {};
+function registerEnvVar(config) {
+  const existing = envRegistry[config.name];
+  if (existing) {
+    if (existing.description !== config.description || existing.type !== config.type || existing.default !== config.default) {
+      throw new Error(`Environment variable "${config.name}" is already registered with different configuration. ` + `Existing: ${JSON.stringify(existing)}, New: ${JSON.stringify(config)}`);
+    }
+    return;
+  }
+  envRegistry[config.name] = config;
+}
+function normalizeBoolean(value) {
+  const lowerValue = value.toLowerCase();
+  return ["true", "1", "on", "yes"].includes(lowerValue);
+}
+function parseEnvValue(config) {
+  const envValue = process.env[config.name];
+  if (envValue === undefined && config.default !== undefined) {
+    return config.default;
+  }
+  if (envValue === undefined) {
+    throw new Error(`Required environment variable ${config.name} is not set. ${config.description}`);
+  }
+  switch (config.type) {
+    case "boolean":
+      return typeof envValue === "boolean" ? envValue : normalizeBoolean(envValue);
+    case "number":
+      const numValue = Number(envValue);
+      if (isNaN(numValue)) {
+        throw new Error(`Environment variable ${config.name} must be a valid number, got: ${envValue}`);
+      }
+      return numValue;
+    case "string":
+    default:
+      return envValue;
+  }
+}
+
+class EnvStore {
+  parsedValues = new Map;
+  get(key) {
+    if (this.parsedValues.has(key)) {
+      return this.parsedValues.get(key);
+    }
+    if (!(key in envRegistry)) {
+      throw new Error(`Environment variable ${key} is not registered.`);
+    }
+    try {
+      const value = parseEnvValue(envRegistry[key]);
+      this.parsedValues.set(key, value);
+      return value;
+    } catch (error) {
+      throw new Error(`Failed to parse env var ${key}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  has(key) {
+    return key in envRegistry;
+  }
+}
+var envStore = singleton("env-store", () => new EnvStore);
+function generateEnvMarkdown() {
+  const configs = Object.values(envRegistry);
+  if (configs.length === 0) {
+    return `# Environment Variables
+
+No environment variables registered.
+`;
+  }
+  let markdown = `# Environment Variables
+
+`;
+  for (const config of configs) {
+    markdown += `## ${config.name}
+
+`;
+    markdown += `${config.description}
+
+`;
+    markdown += `**Type:** \`${config.type || "string"}\`  
+`;
+    if (config.default !== undefined) {
+      const defaultValue = typeof config.default === "string" ? `"${config.default}"` : String(config.default);
+      markdown += `**Default:** \`${defaultValue}\`  
+`;
+    } else {
+      markdown += `**Default:** *Required*  
+`;
+    }
+    markdown += `
+`;
+  }
+  return markdown;
+}
+function generateEnvColored() {
+  const configs = Object.values(envRegistry);
+  if (configs.length === 0) {
+    return `\x1B[1;36mEnvironment Variables\x1B[0m
+
+No environment variables registered.
+`;
+  }
+  let output = `\x1B[1;36mEnvironment Variables\x1B[0m
+
+`;
+  for (const config of configs) {
+    output += `\x1B[1;33m${config.name}\x1B[0m
+`;
+    output += `${config.description}
+`;
+    output += `\x1B[32mType:\x1B[0m \x1B[36m${config.type || "string"}\x1B[0m
+`;
+    if (config.default !== undefined) {
+      const defaultValue = typeof config.default === "string" ? `"${config.default}"` : String(config.default);
+      output += `\x1B[32mDefault:\x1B[0m \x1B[35m${defaultValue}\x1B[0m
+`;
+    } else {
+      output += `\x1B[32mDefault:\x1B[0m \x1B[31mRequired\x1B[0m
+`;
+    }
+    output += `
+`;
+  }
+  return output;
+}
+var env = new Proxy({}, {
+  get(target, prop) {
+    if (typeof prop !== "string") {
+      return;
+    }
+    return envStore.get(prop);
+  },
+  has(target, prop) {
+    return envStore.has(prop);
+  },
+  ownKeys() {
+    return Object.keys(envRegistry);
+  },
+  getOwnPropertyDescriptor(target, prop) {
+    if (envStore.has(prop)) {
+      return {
+        enumerable: true,
+        configurable: true,
+        get: () => envStore.get(prop)
+      };
+    }
+    return;
+  }
+});
 // src/zig.ts
 import { dlopen, toArrayBuffer as toArrayBuffer2, JSCallback, ptr } from "bun:ffi";
 import { existsSync } from "fs";
@@ -5020,6 +5275,18 @@ var targetLibPath = module.default;
 if (!existsSync(targetLibPath)) {
   throw new Error(`opentui is not supported on the current platform: ${process.platform}-${process.arch}`);
 }
+registerEnvVar({
+  name: "OTUI_DEBUG_FFI",
+  description: "Enable debug logging for the FFI bindings.",
+  type: "boolean",
+  default: false
+});
+registerEnvVar({
+  name: "OTUI_TRACE_FFI",
+  description: "Enable tracing for the FFI bindings.",
+  type: "boolean",
+  default: false
+});
 function getOpenTUILib(libPath) {
   const resolvedLibPath = libPath || targetLibPath;
   const rawSymbols = dlopen(resolvedLibPath, {
@@ -5360,7 +5627,7 @@ function getOpenTUILib(libPath) {
       returns: "void"
     }
   });
-  if (process.env.DEBUG_FFI === "true" || process.env.TRACE_FFI === "true") {
+  if (env.OTUI_DEBUG_FFI || env.OTUI_TRACE_FFI) {
     return {
       symbols: convertToDebugSymbols(rawSymbols.symbols)
     };
@@ -5374,7 +5641,7 @@ function convertToDebugSymbols(symbols) {
   Object.entries(symbols).forEach(([key, value]) => {
     debugSymbols[key] = value;
   });
-  if (process.env.DEBUG_FFI === "true") {
+  if (env.OTUI_DEBUG_FFI) {
     Object.entries(symbols).forEach(([key, value]) => {
       if (typeof value === "function") {
         debugSymbols[key] = (...args) => {
@@ -5386,7 +5653,7 @@ function convertToDebugSymbols(symbols) {
       }
     });
   }
-  if (process.env.TRACE_FFI === "true") {
+  if (env.OTUI_TRACE_FFI) {
     hasTracing = true;
     Object.entries(symbols).forEach(([key, value]) => {
       if (typeof value === "function") {
@@ -6378,14 +6645,14 @@ class Renderable extends BaseRenderable {
         this.handleKeyPress(key);
       }
     };
-    this.pasteHandler = (text) => {
-      this._pasteListener?.call(this, text);
+    this.pasteHandler = (event) => {
+      this._pasteListener?.call(this, event.text);
       if (this.handlePaste) {
-        this.handlePaste(text);
+        this.handlePaste(event.text);
       }
     };
-    this.ctx.keyInput.on("keypress", this.keypressHandler);
-    this.ctx.keyInput.on("paste", this.pasteHandler);
+    this.ctx._internalKeyInput.onInternal("keypress", this.keypressHandler);
+    this.ctx._internalKeyInput.onInternal("paste", this.pasteHandler);
     this.emit("focused" /* FOCUSED */);
   }
   blur() {
@@ -6394,11 +6661,11 @@ class Renderable extends BaseRenderable {
     this._focused = false;
     this.requestRender();
     if (this.keypressHandler) {
-      this.ctx.keyInput.off("keypress", this.keypressHandler);
+      this.ctx._internalKeyInput.offInternal("keypress", this.keypressHandler);
       this.keypressHandler = null;
     }
     if (this.pasteHandler) {
-      this.ctx.keyInput.off("paste", this.pasteHandler);
+      this.ctx._internalKeyInput.offInternal("paste", this.pasteHandler);
       this.pasteHandler = null;
     }
     this.emit("blurred" /* BLURRED */);
@@ -7547,16 +7814,6 @@ class CapturedWritableStream extends Writable {
   }
 }
 
-// src/singleton.ts
-var singletonCacheSymbol = Symbol.for("@opentui/core/singleton");
-function singleton(key, factory) {
-  const bag = globalThis[singletonCacheSymbol] ??= {};
-  if (!(key in bag)) {
-    bag[key] = factory();
-  }
-  return bag[key];
-}
-
 // src/console.ts
 function getCallerInfo() {
   const err = new Error;
@@ -7577,6 +7834,18 @@ function getCallerInfo() {
   return { functionName, fullPath, fileName, lineNumber, columnNumber };
 }
 var capture = singleton("ConsoleCapture", () => new Capture);
+registerEnvVar({
+  name: "OTUI_USE_CONSOLE",
+  description: "Whether to use the console. Will not capture console output if set to false.",
+  type: "boolean",
+  default: true
+});
+registerEnvVar({
+  name: "SHOW_CONSOLE",
+  description: "Show the console at startup if set to true.",
+  type: "boolean",
+  default: false
+});
 
 class TerminalConsoleCache extends EventEmitter4 {
   _cachedLogs = [];
@@ -7594,7 +7863,7 @@ class TerminalConsoleCache extends EventEmitter4 {
     this.overrideConsoleMethods();
   }
   setupConsoleCapture() {
-    if (process.env.OTUI_USE_CONSOLE === "false")
+    if (!env.OTUI_USE_CONSOLE)
       return;
     const mockStdout = new CapturedWritableStream("stdout", capture);
     const mockStderr = new CapturedWritableStream("stderr", capture);
@@ -7759,7 +8028,7 @@ class TerminalConsole extends EventEmitter4 {
     terminalConsoleCache.on("entry", (logEntry) => {
       this._handleNewLog(logEntry);
     });
-    if (process.env.SHOW_CONSOLE === "true") {
+    if (env.SHOW_CONSOLE) {
       this.show();
     }
   }
@@ -8237,6 +8506,19 @@ function getObjectsInViewport(viewport, objects, direction = "column", padding =
 }
 
 // src/renderer.ts
+registerEnvVar({
+  name: "OTUI_DUMP_CAPTURES",
+  description: "Dump captured output when the renderer exits.",
+  type: "boolean",
+  default: false
+});
+registerEnvVar({
+  name: "OTUI_NO_NATIVE_RENDER",
+  description: "Disable native rendering. This will not actually output ansi and is useful for debugging.",
+  type: "boolean",
+  default: false
+});
+
 class MouseEvent {
   type;
   button;
@@ -8468,8 +8750,8 @@ Captured output:
   }
   exitHandler = (() => {
     this.destroy();
-    if (true) {
-      this.dumpOutputCache(`=== UNHANDLED OUTPUT (this is only printed in non-production environments) ===
+    if (env.OTUI_DUMP_CAPTURES) {
+      this.dumpOutputCache(`=== CAPTURED OUTPUT ===
 `);
     }
   }).bind(this);
@@ -8520,7 +8802,7 @@ Captured output:
     process.on("exit", this.exitHandler);
     this._console = new TerminalConsole(this, config.consoleOptions);
     this.useConsole = config.useConsole ?? true;
-    this._keyHandler = new KeyHandler(this.stdin, config.useKittyKeyboard ?? false);
+    this._keyHandler = new InternalKeyHandler(this.stdin, config.useKittyKeyboard ?? false);
     global.requestAnimationFrame = (callback) => {
       const id = CliRenderer.animationFrameId++;
       this.animationRequest.set(id, callback);
@@ -8535,7 +8817,7 @@ Captured output:
       global.window = {};
     }
     global.window.requestAnimationFrame = requestAnimationFrame;
-    if (process.env.OTUI_NO_NATIVE_RENDER === "true") {
+    if (env.OTUI_NO_NATIVE_RENDER) {
       this.renderNative = () => {
         if (this._splitHeight > 0) {
           this.flushStdoutCache(this._splitHeight);
@@ -8608,6 +8890,9 @@ Captured output:
   get keyInput() {
     return this._keyHandler;
   }
+  get _internalKeyInput() {
+    return this._keyHandler;
+  }
   get terminalWidth() {
     return this._terminalWidth;
   }
@@ -9385,7 +9670,7 @@ Captured output:
   }
 }
 
-export { __toESM, __commonJS, __export, __require, Edge, Gutter, exports_src, BorderChars, getBorderFromSides, getBorderSides, borderCharsToArray, BorderCharArrays, nonAlphanumericKeys, parseKeypress, ANSI, KeyHandler, RGBA, hexToRgb, rgbToHex, hsvToRgb, parseColor, fonts, measureText, getCharacterPositions, coordinateToCharacterIndex, renderFontToFrameBuffer, TextAttributes, DebugOverlayCorner, createTextAttributes, visualizeRenderableTree, isStyledText, StyledText, stringToStyledText, black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite, bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, bold, italic, underline, strikethrough, dim, reverse, blink, fg, bg, t, SyntaxStyle, hastToStyledText, parseAlign, parseBoxSizing, parseDimension, parseDirection, parseDisplay, parseEdge, parseFlexDirection, parseGutter, parseJustify, parseLogLevel, parseMeasureMode, parseOverflow, parsePositionType, parseUnit, parseWrap, MouseParser, Selection, convertGlobalToLocalSelection, ASCIIFontSelectionHelper, TextBuffer, LogLevel2 as LogLevel, setRenderLibPath, resolveRenderLib, OptimizedBuffer, h, isVNode, maybeMakeRenderable, wrapWithDelegates, instantiate, delegate, isValidPercentage, LayoutEvents, RenderableEvents, isRenderable, BaseRenderable, Renderable, RootRenderable, capture, ConsolePosition, TerminalConsole, getObjectsInViewport, MouseEvent, MouseButton, createCliRenderer, CliRenderEvents, CliRenderer };
+export { __toESM, __commonJS, __export, __require, Edge, Gutter, exports_src, BorderChars, getBorderFromSides, getBorderSides, borderCharsToArray, BorderCharArrays, nonAlphanumericKeys, parseKeypress, ANSI, KeyEvent, PasteEvent, KeyHandler, InternalKeyHandler, RGBA, hexToRgb, rgbToHex, hsvToRgb, parseColor, fonts, measureText, getCharacterPositions, coordinateToCharacterIndex, renderFontToFrameBuffer, TextAttributes, DebugOverlayCorner, createTextAttributes, visualizeRenderableTree, isStyledText, StyledText, stringToStyledText, black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite, bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, bold, italic, underline, strikethrough, dim, reverse, blink, fg, bg, t, SyntaxStyle, hastToStyledText, parseAlign, parseBoxSizing, parseDimension, parseDirection, parseDisplay, parseEdge, parseFlexDirection, parseGutter, parseJustify, parseLogLevel, parseMeasureMode, parseOverflow, parsePositionType, parseUnit, parseWrap, MouseParser, Selection, convertGlobalToLocalSelection, ASCIIFontSelectionHelper, envRegistry, registerEnvVar, generateEnvMarkdown, generateEnvColored, env, TextBuffer, LogLevel2 as LogLevel, setRenderLibPath, resolveRenderLib, OptimizedBuffer, h, isVNode, maybeMakeRenderable, wrapWithDelegates, instantiate, delegate, isValidPercentage, LayoutEvents, RenderableEvents, isRenderable, BaseRenderable, Renderable, RootRenderable, capture, ConsolePosition, TerminalConsole, getObjectsInViewport, MouseEvent, MouseButton, createCliRenderer, CliRenderEvents, CliRenderer };
 
-//# debugId=E1BF4DFE4379457164756E2164756E21
-//# sourceMappingURL=index-ce0mn4wa.js.map
+//# debugId=16DF4272CB23A07264756E2164756E21
+//# sourceMappingURL=index-bq6h36ne.js.map