@opentui/core 0.1.24 → 0.1.26

package/lib/KeyHandler.d.ts

@@ -1,15 +1,57 @@
 import { EventEmitter } from "events";
-import { type ParsedKey } from "./parse.keypress";
-export type { ParsedKey };
-type KeyHandlerEventMap = {
-    keypress: [ParsedKey];
-    keyrepeat: [ParsedKey];
-    keyrelease: [ParsedKey];
+import { type KeyEventType, type ParsedKey } from "./parse.keypress";
+export declare class KeyEvent implements ParsedKey {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    option: boolean;
+    sequence: string;
+    number: boolean;
+    raw: string;
+    eventType: KeyEventType;
+    code?: string;
+    super?: boolean;
+    hyper?: boolean;
+    capsLock?: boolean;
+    numLock?: boolean;
+    baseCode?: number;
+    private _defaultPrevented;
+    constructor(key: ParsedKey);
+    get defaultPrevented(): boolean;
+    preventDefault(): void;
+}
+export declare class PasteEvent {
+    text: string;
+    private _defaultPrevented;
+    constructor(text: string);
+    get defaultPrevented(): boolean;
+    preventDefault(): void;
+}
+export type KeyHandlerEventMap = {
+    keypress: [KeyEvent];
+    keyrepeat: [KeyEvent];
+    keyrelease: [KeyEvent];
+    paste: [PasteEvent];
 };
 export declare class KeyHandler extends EventEmitter<KeyHandlerEventMap> {
-    private stdin;
-    private useKittyKeyboard;
+    protected stdin: NodeJS.ReadStream;
+    protected useKittyKeyboard: boolean;
+    protected listener: (key: Buffer) => void;
+    protected pasteMode: boolean;
+    protected pasteBuffer: string[];
     constructor(stdin?: NodeJS.ReadStream, useKittyKeyboard?: boolean);
     destroy(): void;
 }
-export declare function getKeyHandler(useKittyKeyboard?: boolean): KeyHandler;
+/**
+ * This class is used internally by the renderer to ensure global handlers
+ * can preventDefault before renderable handlers process events.
+ */
+export declare class InternalKeyHandler extends KeyHandler {
+    private renderableHandlers;
+    constructor(stdin?: NodeJS.ReadStream, useKittyKeyboard?: boolean);
+    emit<K extends keyof KeyHandlerEventMap>(event: K, ...args: KeyHandlerEventMap[K]): boolean;
+    private emitWithPriority;
+    onInternal<K extends keyof KeyHandlerEventMap>(event: K, handler: (...args: KeyHandlerEventMap[K]) => void): void;
+    offInternal<K extends keyof KeyHandlerEventMap>(event: K, handler: (...args: KeyHandlerEventMap[K]) => void): void;
+}

package/lib/data-paths.d.ts

@@ -0,0 +1,26 @@
+import { EventEmitter } from "events";
+export interface DataPaths {
+    globalConfigPath: string;
+    globalConfigFile: string;
+    localConfigFile: string;
+    globalDataPath: string;
+}
+export interface DataPathsEvents {
+    "paths:changed": [paths: DataPaths];
+}
+export declare class DataPathsManager extends EventEmitter<DataPathsEvents> {
+    private _appName;
+    private _globalConfigPath?;
+    private _globalConfigFile?;
+    private _localConfigFile?;
+    private _globalDataPath?;
+    constructor();
+    get appName(): string;
+    set appName(value: string);
+    get globalConfigPath(): string;
+    get globalConfigFile(): string;
+    get localConfigFile(): string;
+    get globalDataPath(): string;
+    toObject(): DataPaths;
+}
+export declare function getDataPaths(): DataPathsManager;

package/lib/debounce.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Debounce controller that manages debounce instances for a specific scope
+ */
+export declare class DebounceController {
+    private scopeId;
+    constructor(scopeId: string | number);
+    /**
+     * Debounces the provided function with the given ID
+     *
+     * @param id Unique identifier within this scope
+     * @param ms Milliseconds to wait before executing
+     * @param fn Function to execute
+     */
+    debounce<R>(id: string | number, ms: number, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Clear a specific debounce timer in this scope
+     *
+     * @param id The debounce ID to clear
+     */
+    clearDebounce(id: string | number): void;
+    /**
+     * Clear all debounce timers in this scope
+     */
+    clear(): void;
+}
+/**
+ * Creates a new debounce controller for a specific scope
+ *
+ * @param scopeId Unique identifier for this debounce scope
+ * @returns A DebounceController for the specified scope
+ */
+export declare function createDebounce(scopeId: string | number): DebounceController;
+/**
+ * Clears all debounce timers for a specific scope
+ *
+ * @param scopeId The scope identifier
+ */
+export declare function clearDebounceScope(scopeId: string | number): void;
+/**
+ * Clears all active debounce timers across all scopes
+ */
+export declare function clearAllDebounces(): void;

package/lib/env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Environment variable registry
+ *
+ * Usage:
+ * ```ts
+ * import { registerEnvVar, env } from "./lib/env.ts";
+ *
+ * // Register environment variables
+ * registerEnvVar({
+ *   name: "DEBUG",
+ *   description: "Enable debug logging",
+ *   type: "boolean",
+ *   default: false
+ * });
+ *
+ * registerEnvVar({
+ *   name: "PORT",
+ *   description: "Server port number",
+ *   type: "number",
+ *   default: 3000
+ * });
+ *
+ * // Access environment variables
+ * if (env.DEBUG) {
+ *   console.log("Debug mode enabled");
+ * }
+ *
+ * const port = env.PORT; // number
+ * ```
+ */
+export interface EnvVarConfig {
+    name: string;
+    description: string;
+    default?: string | boolean | number;
+    type?: "string" | "boolean" | "number";
+}
+export declare const envRegistry: Record<string, EnvVarConfig>;
+export declare function registerEnvVar(config: EnvVarConfig): void;
+export declare function clearEnvCache(): void;
+export declare function generateEnvMarkdown(): string;
+export declare function generateEnvColored(): string;
+export declare const env: Record<string, any>;

package/lib/hast-styled-text.d.ts

@@ -1,5 +1,5 @@
-import { RGBA } from "./RGBA";
 import { StyledText } from "./styled-text";
+import { SyntaxStyle } from "./syntax-style";
 export interface HASTText {
     type: "text";
     value: string;
@@ -13,26 +13,6 @@ export interface HASTElement {
     children: HASTNode[];
 }
 export type HASTNode = HASTText | HASTElement;
-export interface StyleDefinition {
-    fg?: RGBA;
-    bg?: RGBA;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    dim?: boolean;
-}
-interface MergedStyle {
-    fg?: RGBA;
-    bg?: RGBA;
-    attributes: number;
-}
-export declare class SyntaxStyle {
-    private styles;
-    private mergedStyleCache;
-    constructor(styles: Record<string, StyleDefinition>);
-    mergeStyles(...styleNames: string[]): MergedStyle;
-    clearCache(): void;
-    getCacheSize(): number;
-}
+export { SyntaxStyle } from "./syntax-style";
+export type { StyleDefinition } from "./syntax-style";
 export declare function hastToStyledText(hast: HASTNode, syntaxStyle: SyntaxStyle): StyledText;
-export {};

package/lib/index.d.ts

@@ -4,7 +4,13 @@ export * from "./ascii.font";
 export * from "./hast-styled-text";
 export * from "./RGBA";
 export * from "./parse.keypress";
+export * from "./scroll-acceleration";
 export * from "./styled-text";
 export * from "./yoga.options";
 export * from "./parse.mouse";
 export * from "./selection";
+export * from "./env";
+export * from "./tree-sitter-styled-text";
+export * from "./tree-sitter";
+export * from "./syntax-style";
+export * from "./data-paths";

package/lib/parse.keypress.d.ts

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 export declare const nonAlphanumericKeys: string[];
 export type KeyEventType = "press" | "repeat" | "release";
-export type ParsedKey = {
+export interface ParsedKey {
     name: string;
     ctrl: boolean;
     meta: boolean;
@@ -17,7 +17,7 @@ export type ParsedKey = {
     capsLock?: boolean;
     numLock?: boolean;
     baseCode?: number;
-};
+}
 export type ParseKeypressOptions = {
     useKittyKeyboard?: boolean;
 };

package/lib/queue.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generic processing queue that handles asynchronous job processing
+ */
+export declare class ProcessQueue<T> {
+    private processor;
+    private queue;
+    private processing;
+    private autoProcess;
+    constructor(processor: (item: T) => Promise<void> | void, autoProcess?: boolean);
+    enqueue(item: T): void;
+    private processQueue;
+    clear(): void;
+    isProcessing(): boolean;
+    size(): number;
+}

package/lib/scroll-acceleration.d.ts

@@ -0,0 +1,43 @@
+export interface ScrollAcceleration {
+    tick(now?: number): number;
+    reset(): void;
+}
+export declare class LinearScrollAccel implements ScrollAcceleration {
+    tick(_now?: number): number;
+    reset(): void;
+}
+/**
+ * macOS-inspired scroll acceleration.
+ *
+ * The class measures the time between consecutive scroll events and keeps a short
+ * moving window of the latest intervals. The average interval determines which
+ * multiplier to apply so that quick bursts accelerate and slower gestures stay precise.
+ *
+ * For intuition, treat the streak as a continuous timeline and compare it with the
+ * exponential distance curve from the pointer-acceleration research post:
+ *   d(t) = v₀ * ( t + A * (exp(t/τ) - 1 - t/τ) ).
+ * Small t stays near the base multiplier, medium streaks settle on multiplier1, and
+ * sustained bursts reach multiplier2, mirroring how the exponential curve bends up.
+ *
+ * Options:
+ * - threshold1: upper bound (ms) of the "medium" band. Raise to delay the ramp.
+ * - threshold2: upper bound (ms) of the "fast" band. Lower to demand tighter bursts.
+ * - multiplier1: scale for medium speed streaks.
+ * - multiplier2: scale for sustained fast streaks.
+ * - baseMultiplier: scale for relaxed scrolling; set to 1 for linear behaviour.
+ */
+export declare class MacOSScrollAccel implements ScrollAcceleration {
+    private opts;
+    private lastTickTime;
+    private velocityHistory;
+    private readonly historySize;
+    private readonly streakTimeout;
+    private readonly minTickInterval;
+    constructor(opts?: {
+        A?: number;
+        tau?: number;
+        maxMultiplier?: number;
+    });
+    tick(now?: number): number;
+    reset(): void;
+}

package/{singleton.d.ts → lib/singleton.d.ts}

@@ -3,3 +3,5 @@
  * persists across Bun hot reloads, and is type-safe.
  */
 export declare function singleton<T>(key: string, factory: () => T): T;
+export declare function destroySingleton(key: string): void;
+export declare function hasSingleton(key: string): boolean;

package/lib/styled-text.d.ts

@@ -1,4 +1,3 @@
-import type { TextRenderable } from "../renderables/Text";
 import type { TextChunk } from "../text-buffer";
 import { type ColorInput } from "./RGBA";
 declare const BrandedStyledText: unique symbol;
@@ -18,21 +17,7 @@ export declare function isStyledText(obj: any): obj is StyledText;
 export declare class StyledText {
     [BrandedStyledText]: boolean;
     chunks: TextChunk[];
-    textRenderable?: TextRenderable;
     constructor(chunks: TextChunk[]);
-    mount(textRenderable: TextRenderable): void;
-    /**
-     * @deprecated: Use textRenderable.insertChunk instead
-     */
-    insert(chunk: TextChunk, index?: number): StyledText;
-    /**
-     * @deprecated: Use textRenderable.removeChunk instead
-     */
-    remove(chunk: TextChunk): StyledText;
-    /**
-     * @deprecated: Use textRenderable.replaceChunk instead
-     */
-    replace(chunk: TextChunk, oldChunk: TextChunk): StyledText;
 }
 export declare function stringToStyledText(content: string): StyledText;
 export type StylableInput = string | number | boolean | TextChunk;

package/lib/syntax-style.d.ts

@@ -0,0 +1,36 @@
+import { RGBA, type ColorInput } from "./RGBA";
+export interface StyleDefinition {
+    fg?: RGBA;
+    bg?: RGBA;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    dim?: boolean;
+}
+export interface MergedStyle {
+    fg?: RGBA;
+    bg?: RGBA;
+    attributes: number;
+}
+export interface ThemeTokenStyle {
+    scope: string[];
+    style: {
+        foreground?: ColorInput;
+        background?: ColorInput;
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean;
+        dim?: boolean;
+    };
+}
+export declare function convertThemeToStyles(theme: ThemeTokenStyle[]): Record<string, StyleDefinition>;
+export declare class SyntaxStyle {
+    private styles;
+    private mergedStyleCache;
+    constructor(styles: Record<string, StyleDefinition>);
+    static fromTheme(theme: ThemeTokenStyle[]): SyntaxStyle;
+    mergeStyles(...styleNames: string[]): MergedStyle;
+    getStyle(name: string): StyleDefinition | undefined;
+    clearCache(): void;
+    getCacheSize(): number;
+}

package/lib/tree-sitter/assets/update.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+export interface UpdateOptions {
+    /** Path to parsers-config.json */
+    configPath: string;
+    /** Directory where .wasm and .scm files will be downloaded */
+    assetsDir: string;
+    /** Path where the generated TypeScript file will be written */
+    outputPath: string;
+}
+declare function main(options?: Partial<UpdateOptions>): Promise<void>;
+export { main as updateAssets };

package/lib/tree-sitter/client.d.ts

@@ -0,0 +1,46 @@
+import { EventEmitter } from "events";
+import type { TreeSitterClientOptions, TreeSitterClientEvents, BufferState, FiletypeParserOptions, Edit, PerformanceStats, SimpleHighlight } from "./types";
+declare global {
+    const OTUI_TREE_SITTER_WORKER_PATH: string;
+}
+export declare function addDefaultParsers(parsers: FiletypeParserOptions[]): void;
+export declare class TreeSitterClient extends EventEmitter<TreeSitterClientEvents> {
+    private initialized;
+    private worker;
+    private buffers;
+    private initializePromise;
+    private initializeResolvers;
+    private messageCallbacks;
+    private messageIdCounter;
+    private editQueues;
+    private debouncer;
+    private options;
+    constructor(options: TreeSitterClientOptions);
+    private emitError;
+    private emitWarning;
+    private startWorker;
+    private stopWorker;
+    private handleReset;
+    initialize(): Promise<void>;
+    private registerDefaultParsers;
+    private resolvePath;
+    addFiletypeParser(filetypeParser: FiletypeParserOptions): void;
+    getPerformance(): Promise<PerformanceStats>;
+    highlightOnce(content: string, filetype: string): Promise<{
+        highlights?: SimpleHighlight[];
+        warning?: string;
+        error?: string;
+    }>;
+    private handleWorkerMessage;
+    preloadParser(filetype: string): Promise<boolean>;
+    createBuffer(id: number, content: string, filetype: string, version?: number, autoInitialize?: boolean): Promise<boolean>;
+    updateBuffer(id: number, edits: Edit[], newContent: string, version: number): Promise<void>;
+    private processEdit;
+    removeBuffer(bufferId: number): Promise<void>;
+    destroy(): Promise<void>;
+    resetBuffer(bufferId: number, version: number, content: string): Promise<void>;
+    getBuffer(bufferId: number): BufferState | undefined;
+    getAllBuffers(): BufferState[];
+    isInitialized(): boolean;
+    setDataPath(dataPath: string): Promise<void>;
+}

package/lib/tree-sitter/default-parsers.d.ts

@@ -0,0 +1,2 @@
+import type { FiletypeParserOptions } from "./types";
+export declare function getParsers(): FiletypeParserOptions[];

package/lib/tree-sitter/download-utils.d.ts

@@ -0,0 +1,21 @@
+export interface DownloadResult {
+    content?: ArrayBuffer;
+    filePath?: string;
+    error?: string;
+}
+export declare class DownloadUtils {
+    private static hashUrl;
+    /**
+     * Download a file from URL or load from local path, with caching support
+     */
+    static downloadOrLoad(source: string, cacheDir: string, cacheSubdir: string, fileExtension: string, useHashForCache?: boolean, filetype?: string): Promise<DownloadResult>;
+    /**
+     * Download and save a file to a specific target path
+     */
+    static downloadToPath(source: string, targetPath: string): Promise<DownloadResult>;
+    /**
+     * Fetch multiple highlight queries and concatenate them
+     */
+    static fetchHighlightQueries(sources: string[], cacheDir: string, filetype: string): Promise<string>;
+    private static fetchHighlightQuery;
+}

package/lib/tree-sitter/index.d.ts

@@ -0,0 +1,10 @@
+import { TreeSitterClient } from "./client";
+export * from "./client";
+export * from "../tree-sitter-styled-text";
+export * from "../syntax-style";
+export * from "./types";
+export * from "../syntax-style";
+export * from "./resolve-ft";
+export type { UpdateOptions } from "./assets/update";
+export { updateAssets } from "./assets/update";
+export declare function getTreeSitterClient(): TreeSitterClient;

package/lib/tree-sitter/parser.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tree-sitter/resolve-ft.d.ts

@@ -0,0 +1,2 @@
+export declare function extToFiletype(extension: string): string | undefined;
+export declare function pathToFiletype(path: string): string | undefined;

package/lib/tree-sitter/types.d.ts

@@ -0,0 +1,64 @@
+export interface HighlightRange {
+    startCol: number;
+    endCol: number;
+    group: string;
+}
+export interface HighlightResponse {
+    line: number;
+    highlights: HighlightRange[];
+    droppedHighlights: HighlightRange[];
+}
+export type SimpleHighlight = [number, number, string];
+export interface FiletypeParserOptions {
+    filetype: string;
+    queries: {
+        highlights: string[];
+    };
+    wasm: string;
+}
+export interface BufferState {
+    id: number;
+    version: number;
+    content: string;
+    filetype: string;
+    hasParser: boolean;
+}
+export interface ParsedBuffer extends BufferState {
+    hasParser: true;
+}
+export interface TreeSitterClientEvents {
+    "highlights:response": [bufferId: number, version: number, highlights: HighlightResponse[]];
+    "buffer:initialized": [bufferId: number, hasParser: boolean];
+    "buffer:disposed": [bufferId: number];
+    "worker:log": [logType: "log" | "error", message: string];
+    error: [error: string, bufferId?: number];
+    warning: [warning: string, bufferId?: number];
+}
+export interface TreeSitterClientOptions {
+    dataPath: string;
+    workerPath?: string | URL;
+    initTimeout?: number;
+}
+export interface Edit {
+    startIndex: number;
+    oldEndIndex: number;
+    newEndIndex: number;
+    startPosition: {
+        row: number;
+        column: number;
+    };
+    oldEndPosition: {
+        row: number;
+        column: number;
+    };
+    newEndPosition: {
+        row: number;
+        column: number;
+    };
+}
+export interface PerformanceStats {
+    averageParseTime: number;
+    parseTimes: number[];
+    averageQueryTime: number;
+    queryTimes: number[];
+}

package/lib/tree-sitter-styled-text.d.ts

@@ -0,0 +1,7 @@
+import type { TextChunk } from "../text-buffer";
+import { StyledText } from "./styled-text";
+import { SyntaxStyle } from "./syntax-style";
+import { TreeSitterClient } from "./tree-sitter/client";
+import type { SimpleHighlight } from "./tree-sitter/types";
+export declare function treeSitterToTextChunks(content: string, highlights: SimpleHighlight[], syntaxStyle: SyntaxStyle): TextChunk[];
+export declare function treeSitterToStyledText(content: string, filetype: string, syntaxStyle: SyntaxStyle, client: TreeSitterClient): Promise<StyledText>;

package/lib/validate-dir-name.d.ts

@@ -0,0 +1 @@
+export declare function isValidDirectoryName(name: string): boolean;

package/package.json

@@ -4,7 +4,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "OpenTUI is a TypeScript library for building terminal user interfaces (TUIs)",
   "license": "MIT",
   "repository": {
@@ -27,24 +27,37 @@
       "import": "./testing.js",
       "require": "./testing.js",
       "types": "./testing.d.ts"
+    },
+    "./parser.worker": {
+      "import": "./lib/tree-sitter/parser.worker.js",
+      "require": "./lib/tree-sitter/parser.worker.js",
+      "types": "./lib/tree-sitter/parser.worker.d.ts"
     }
   },
+  "dependencies": {
+    "jimp": "1.6.0",
+    "yoga-layout": "3.2.1"
+  },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/three": "0.177.0",
     "commander": "^13.1.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "web-tree-sitter": "^0.26.0"
+  },
+  "peerDependencies": {
+    "web-tree-sitter": ">=0.26.0"
   },
   "optionalDependencies": {
     "@dimforge/rapier2d-simd-compat": "^0.17.3",
     "bun-webgpu": "0.1.3",
     "planck": "^1.4.2",
     "three": "0.177.0",
-    "@opentui/core-darwin-x64": "0.1.24",
-    "@opentui/core-darwin-arm64": "0.1.24",
-    "@opentui/core-linux-x64": "0.1.24",
-    "@opentui/core-linux-arm64": "0.1.24",
-    "@opentui/core-win32-x64": "0.1.24",
-    "@opentui/core-win32-arm64": "0.1.24"
+    "@opentui/core-darwin-x64": "0.1.26",
+    "@opentui/core-darwin-arm64": "0.1.26",
+    "@opentui/core-linux-x64": "0.1.26",
+    "@opentui/core-linux-arm64": "0.1.26",
+    "@opentui/core-win32-x64": "0.1.26",
+    "@opentui/core-win32-arm64": "0.1.26"
   }
 }