@opentui/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opentui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# OpenTUI
+
+OpenTUI is a TypeScript library for building terminal user interfaces (TUIs). It is currently in
+development and is not ready for production use. It will be the foundational TUI framework for both
+[opencode](https://opencode.ai) and [terminaldotshop](https://terminal.shop).
+
+## Install
+
+```bash
+bun install @opentui/core
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+This creates platform-specific libraries that are automatically loaded by the TypeScript layer.
+
+## Examples
+
+```bash
+bun run src/examples/index.ts
+```
+
+## CLI Renderer
+
+### Renderables
+
+Renderables are hierarchical objects that can be positioned, nested, styled and rendered to the terminal:
+
+```typescript
+import { createCliRenderer, TextRenderable } from "@opentui/core"
+
+const renderer = await createCliRenderer()
+
+const obj = new TextRenderable("my-obj", { content: "Hello, world!" })
+
+renderer.root.add(obj)
+```

package/Renderable.d.ts

@@ -0,0 +1,158 @@
+import { OptimizedBuffer, type RenderContext, type MouseEvent, type SelectionState } from ".";
+import { EventEmitter } from "events";
+import { FlexDirection, Direction, PositionType, Edge, Align, Justify } from "yoga-layout";
+import { TrackedNode } from "./lib/TrackedNode";
+import type { ParsedKey } from "./lib/parse.keypress";
+import { type KeyHandler } from "./lib/KeyHandler";
+export declare enum LayoutEvents {
+    LAYOUT_CHANGED = "layout-changed",
+    ADDED = "added",
+    REMOVED = "removed",
+    RESIZED = "resized"
+}
+export declare enum RenderableEvents {
+    FOCUSED = "focused",
+    BLURRED = "blurred"
+}
+export { Justify, Align, FlexDirection, Direction, PositionType, Edge };
+export interface Position {
+    top?: number | "auto" | `${number}%`;
+    right?: number | "auto" | `${number}%`;
+    bottom?: number | "auto" | `${number}%`;
+    left?: number | "auto" | `${number}%`;
+}
+export interface LayoutOptions {
+    flexGrow?: number;
+    flexShrink?: number;
+    flexDirection?: FlexDirection;
+    alignItems?: Align;
+    justifyContent?: Justify;
+    flexBasis?: number | "auto" | undefined;
+    positionType?: "absolute" | "relative";
+    position?: Position;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    } | number | "auto" | `${number}%`;
+    padding?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    } | number | `${number}%`;
+    enableLayout?: boolean;
+}
+export interface RenderableOptions extends Partial<LayoutOptions> {
+    width?: number | "auto" | `${number}%`;
+    height?: number | "auto" | `${number}%`;
+    zIndex?: number;
+    visible?: boolean;
+    buffered?: boolean;
+}
+export declare abstract class Renderable extends EventEmitter {
+    static renderablesByNumber: Map<number, Renderable>;
+    readonly id: string;
+    readonly num: number;
+    protected ctx: RenderContext | null;
+    private _x;
+    private _y;
+    protected _width: number | "auto" | `${number}%`;
+    protected _height: number | "auto" | `${number}%`;
+    private _widthValue;
+    private _heightValue;
+    private _zIndex;
+    protected _visible: boolean;
+    selectable: boolean;
+    protected buffered: boolean;
+    protected frameBuffer: OptimizedBuffer | null;
+    private _dirty;
+    protected focusable: boolean;
+    protected _focused: boolean;
+    protected keyHandler: KeyHandler;
+    protected keypressHandler: ((key: ParsedKey) => void) | null;
+    protected layoutNode: TrackedNode;
+    protected _positionType: "absolute" | "relative";
+    protected _position: Position;
+    private renderableMap;
+    private renderableArray;
+    private needsZIndexSort;
+    parent: Renderable | null;
+    private _yogaPerformancePositionUpdated;
+    constructor(id: string, options: RenderableOptions);
+    get visible(): boolean;
+    set visible(value: boolean);
+    hasSelection(): boolean;
+    onSelectionChanged(selection: SelectionState | null): boolean;
+    getSelectedText(): string;
+    shouldStartSelection(x: number, y: number): boolean;
+    focus(): void;
+    blur(): void;
+    get focused(): boolean;
+    handleKeyPress?(key: ParsedKey | string): boolean;
+    protected get isDirty(): boolean;
+    private markClean;
+    needsUpdate(): void;
+    get x(): number;
+    set x(value: number);
+    set top(value: number);
+    set left(value: number);
+    get y(): number;
+    set y(value: number);
+    get width(): number;
+    set width(value: number | "auto" | `${number}%`);
+    get height(): number;
+    set height(value: number | "auto" | `${number}%`);
+    get zIndex(): number;
+    set zIndex(value: number);
+    requestZIndexSort(): void;
+    private ensureZIndexSorted;
+    private setupYogaProperties;
+    setPosition(position: Position): void;
+    private updateYogaPosition;
+    set flexGrow(grow: number);
+    set flexShrink(shrink: number);
+    set flexDirection(direction: FlexDirection);
+    set alignItems(alignItems: Align);
+    set justifyContent(justifyContent: Justify);
+    set flexBasis(basis: number | "auto" | undefined);
+    set minWidth(minWidth: number | `${number}%` | undefined);
+    set maxWidth(maxWidth: number | `${number}%` | undefined);
+    set minHeight(minHeight: number | `${number}%` | undefined);
+    set maxHeight(maxHeight: number | `${number}%` | undefined);
+    getLayoutNode(): TrackedNode;
+    updateFromLayout(): void;
+    protected onLayoutResize(width: number, height: number): void;
+    protected handleFrameBufferResize(width: number, height: number): void;
+    protected createFrameBuffer(): void;
+    protected onResize(width: number, height: number): void;
+    protected requestLayout(): void;
+    add(obj: Renderable): void;
+    propagateContext(ctx: RenderContext | null): void;
+    getRenderable(id: string): Renderable | undefined;
+    remove(id: string): void;
+    getChildren(): Renderable[];
+    render(buffer: OptimizedBuffer, deltaTime: number): void;
+    protected beforeRender(): void;
+    protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void;
+    destroy(): void;
+    protected destroySelf(): void;
+    processMouseEvent(event: MouseEvent): void;
+    protected onMouseEvent(event: MouseEvent): void;
+}
+export declare class RootRenderable extends Renderable {
+    private yogaConfig;
+    constructor(width: number, height: number, ctx: RenderContext);
+    add(obj: Renderable): void;
+    remove(id: string): void;
+    requestLayout(): void;
+    calculateLayout(): void;
+    resize(width: number, height: number): void;
+    protected beforeRender(): void;
+    protected destroySelf(): void;
+}

package/animation/Timeline.d.ts

@@ -0,0 +1,114 @@
+export interface TimelineOptions {
+    duration?: number;
+    loop?: boolean;
+    autoplay?: boolean;
+    onComplete?: () => void;
+    onPause?: () => void;
+}
+export interface AnimationOptions {
+    duration: number;
+    ease?: EasingFunctions;
+    onUpdate?: (animation: JSAnimation) => void;
+    onComplete?: () => void;
+    onStart?: () => void;
+    onLoop?: () => void;
+    loop?: boolean | number;
+    loopDelay?: number;
+    alternate?: boolean;
+    once?: boolean;
+    [key: string]: any;
+}
+export interface JSAnimation {
+    targets: any[];
+    deltaTime: number;
+    progress: number;
+    currentTime: number;
+}
+interface TimelineItem {
+    type: "animation" | "callback" | "timeline";
+    startTime: number;
+}
+interface TimelineTimelineItem extends TimelineItem {
+    type: "timeline";
+    timeline: Timeline;
+    timelineStarted?: boolean;
+}
+interface TimelineCallbackItem extends TimelineItem {
+    type: "callback";
+    callback: () => void;
+    executed: boolean;
+}
+interface TimelineAnimationItem extends TimelineItem {
+    type: "animation";
+    target: any[];
+    properties?: Record<string, number>;
+    initialValues?: Record<string, number>[];
+    duration?: number;
+    ease?: keyof typeof easingFunctions;
+    loop?: boolean | number;
+    loopDelay?: number;
+    alternate?: boolean;
+    onUpdate?: (animation: JSAnimation) => void;
+    onComplete?: () => void;
+    onStart?: () => void;
+    onLoop?: () => void;
+    completed?: boolean;
+    started?: boolean;
+    currentLoop?: number;
+    once?: boolean;
+}
+export type EasingFunctions = keyof typeof easingFunctions;
+declare const easingFunctions: {
+    linear: (t: number) => number;
+    inQuad: (t: number) => number;
+    outQuad: (t: number) => number;
+    inOutQuad: (t: number) => number;
+    inExpo: (t: number) => number;
+    outExpo: (t: number) => number;
+    inOutSine: (t: number) => number;
+    outBounce: (t: number) => number;
+    outElastic: (t: number) => number;
+    inBounce: (t: number) => number;
+    inCirc: (t: number) => number;
+    outCirc: (t: number) => number;
+    inOutCirc: (t: number) => number;
+    inBack: (t: number, s?: number) => number;
+    outBack: (t: number, s?: number) => number;
+    inOutBack: (t: number, s?: number) => number;
+};
+export declare class Timeline {
+    items: (TimelineAnimationItem | TimelineCallbackItem)[];
+    subTimelines: TimelineTimelineItem[];
+    currentTime: number;
+    isPlaying: boolean;
+    isComplete: boolean;
+    duration: number;
+    loop: boolean;
+    synced: boolean;
+    private autoplay;
+    private onComplete?;
+    private onPause?;
+    constructor(options?: TimelineOptions);
+    add(target: any, properties: AnimationOptions, startTime?: number | string): this;
+    once(target: any, properties: AnimationOptions): this;
+    call(callback: () => void, startTime?: number | string): this;
+    sync(timeline: Timeline, startTime?: number): this;
+    play(): this;
+    pause(): this;
+    resetItems(): void;
+    restart(): this;
+    update(deltaTime: number): void;
+}
+declare class TimelineEngine {
+    private timelines;
+    defaults: {
+        frameRate: number;
+    };
+    register(timeline: Timeline): void;
+    unregister(timeline: Timeline): void;
+    clear(): void;
+    update(deltaTime: number): void;
+}
+export declare const engine: TimelineEngine;
+export declare function createTimeline(options?: TimelineOptions): Timeline;
+export {};

package/ansi.d.ts

@@ -0,0 +1,26 @@
+export declare const ANSI: {
+    switchToAlternateScreen: string;
+    switchToMainScreen: string;
+    reset: string;
+    hideCursor: string;
+    showCursor: string;
+    resetCursorColor: string;
+    saveCursorState: string;
+    restoreCursorState: string;
+    queryPixelSize: string;
+    scrollDown: (lines: number) => string;
+    scrollUp: (lines: number) => string;
+    moveCursor: (row: number, col: number) => string;
+    moveCursorAndClear: (row: number, col: number) => string;
+    clearFromCursor: string;
+    setRgbBackground: (r: number, g: number, b: number) => string;
+    resetBackground: string;
+    enableMouseTracking: string;
+    disableMouseTracking: string;
+    enableButtonEventTracking: string;
+    disableButtonEventTracking: string;
+    enableAnyEventTracking: string;
+    disableAnyEventTracking: string;
+    enableSGRMouseMode: string;
+    disableSGRMouseMode: string;
+};

package/buffer.d.ts

@@ -0,0 +1,88 @@
+import type { TextBuffer } from "./text-buffer";
+import { RGBA } from "./types";
+import { type RenderLib } from "./zig";
+import { type Pointer } from "bun:ffi";
+import { type BorderStyle, type BorderSides } from "./lib";
+export declare class OptimizedBuffer {
+    id: string;
+    lib: RenderLib;
+    private bufferPtr;
+    private buffer;
+    private width;
+    private height;
+    respectAlpha: boolean;
+    private useFFI;
+    get ptr(): Pointer;
+    constructor(lib: RenderLib, ptr: Pointer, buffer: {
+        char: Uint32Array;
+        fg: Float32Array;
+        bg: Float32Array;
+        attributes: Uint8Array;
+    }, width: number, height: number, options: {
+        respectAlpha?: boolean;
+    });
+    static create(width: number, height: number, options?: {
+        respectAlpha?: boolean;
+    }): OptimizedBuffer;
+    get buffers(): {
+        char: Uint32Array;
+        fg: Float32Array;
+        bg: Float32Array;
+        attributes: Uint8Array;
+    };
+    private coordsToIndex;
+    getWidth(): number;
+    getHeight(): number;
+    setRespectAlpha(respectAlpha: boolean): void;
+    clear(bg?: RGBA, clearChar?: string): void;
+    clearLocal(bg?: RGBA, clearChar?: string): void;
+    setCell(x: number, y: number, char: string, fg: RGBA, bg: RGBA, attributes?: number): void;
+    get(x: number, y: number): {
+        char: number;
+        fg: RGBA;
+        bg: RGBA;
+        attributes: number;
+    } | null;
+    setCellWithAlphaBlending(x: number, y: number, char: string, fg: RGBA, bg: RGBA, attributes?: number): void;
+    setCellWithAlphaBlendingLocal(x: number, y: number, char: string, fg: RGBA, bg: RGBA, attributes?: number): void;
+    drawText(text: string, x: number, y: number, fg: RGBA, bg?: RGBA, attributes?: number, selection?: {
+        start: number;
+        end: number;
+        bgColor?: RGBA;
+        fgColor?: RGBA;
+    } | null): void;
+    fillRect(x: number, y: number, width: number, height: number, bg: RGBA): void;
+    fillRectLocal(x: number, y: number, width: number, height: number, bg: RGBA): void;
+    drawFrameBuffer(destX: number, destY: number, frameBuffer: OptimizedBuffer, sourceX?: number, sourceY?: number, sourceWidth?: number, sourceHeight?: number): void;
+    drawFrameBufferLocal(destX: number, destY: number, frameBuffer: OptimizedBuffer, sourceX?: number, sourceY?: number, sourceWidth?: number, sourceHeight?: number): void;
+    destroy(): void;
+    drawTextBuffer(textBuffer: TextBuffer, x: number, y: number, clipRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    drawSuperSampleBuffer(x: number, y: number, pixelDataPtr: Pointer, pixelDataLength: number, format: "bgra8unorm" | "rgba8unorm", alignedBytesPerRow: number): void;
+    drawSuperSampleBufferFFI(x: number, y: number, pixelDataPtr: Pointer, pixelDataLength: number, format: "bgra8unorm" | "rgba8unorm", alignedBytesPerRow: number): void;
+    drawPackedBuffer(dataPtr: Pointer, dataLen: number, posX: number, posY: number, terminalWidthCells: number, terminalHeightCells: number): void;
+    setCellWithAlphaBlendingFFI(x: number, y: number, char: string, fg: RGBA, bg: RGBA, attributes?: number): void;
+    fillRectFFI(x: number, y: number, width: number, height: number, bg: RGBA): void;
+    resize(width: number, height: number): void;
+    clearFFI(bg?: RGBA): void;
+    drawTextFFI(text: string, x: number, y: number, fg?: RGBA, bg?: RGBA, attributes?: number): void;
+    drawFrameBufferFFI(destX: number, destY: number, frameBuffer: OptimizedBuffer, sourceX?: number, sourceY?: number, sourceWidth?: number, sourceHeight?: number): void;
+    drawBox(options: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        borderStyle?: BorderStyle;
+        customBorderChars?: Uint32Array;
+        border: boolean | BorderSides[];
+        borderColor: RGBA;
+        backgroundColor: RGBA;
+        shouldFill?: boolean;
+        title?: string;
+        titleAlignment?: "left" | "center" | "right";
+    }): void;
+}

package/console.d.ts

@@ -0,0 +1,86 @@
+import type { CliRenderer, ColorInput } from ".";
+import { EventEmitter } from "events";
+import { OptimizedBuffer } from "./buffer";
+import { Capture } from "./lib/output.capture";
+export declare const capture: Capture;
+export declare enum ConsolePosition {
+    TOP = "top",
+    BOTTOM = "bottom",
+    LEFT = "left",
+    RIGHT = "right"
+}
+export interface ConsoleOptions {
+    position?: ConsolePosition;
+    sizePercent?: number;
+    zIndex?: number;
+    colorInfo?: ColorInput;
+    colorWarn?: ColorInput;
+    colorError?: ColorInput;
+    colorDebug?: ColorInput;
+    colorDefault?: ColorInput;
+    backgroundColor?: ColorInput;
+    startInDebugMode?: boolean;
+    title?: string;
+    titleBarColor?: ColorInput;
+    titleBarTextColor?: ColorInput;
+    cursorColor?: ColorInput;
+    maxStoredLogs?: number;
+    maxDisplayLines?: number;
+}
+export declare class TerminalConsole extends EventEmitter {
+    private isVisible;
+    private isFocused;
+    private renderer;
+    private stdinHandler;
+    private options;
+    private _debugModeEnabled;
+    private frameBuffer;
+    private consoleX;
+    private consoleY;
+    private consoleWidth;
+    private consoleHeight;
+    private scrollTopIndex;
+    private isScrolledToBottom;
+    private currentLineIndex;
+    private _displayLines;
+    private _allLogEntries;
+    private _needsFrameBufferUpdate;
+    private markNeedsUpdate;
+    private _rgbaInfo;
+    private _rgbaWarn;
+    private _rgbaError;
+    private _rgbaDebug;
+    private _rgbaDefault;
+    private backgroundColor;
+    private _rgbaTitleBar;
+    private _rgbaTitleBarText;
+    private _title;
+    private _rgbaCursor;
+    private _positions;
+    constructor(renderer: CliRenderer, options?: ConsoleOptions);
+    activate(): void;
+    deactivate(): void;
+    private _handleNewLog;
+    private _updateConsoleDimensions;
+    private handleStdin;
+    private attachStdin;
+    private detachStdin;
+    private formatTimestamp;
+    private formatArguments;
+    resize(width: number, height: number): void;
+    clear(): void;
+    toggle(): void;
+    focus(): void;
+    blur(): void;
+    show(): void;
+    hide(): void;
+    getCachedLogs(): string;
+    private updateFrameBuffer;
+    renderToBuffer(buffer: OptimizedBuffer): void;
+    setDebugMode(enabled: boolean): void;
+    toggleDebugMode(): void;
+    private _scrollToBottom;
+    private _processLogEntry;
+    private _processCachedLogs;
+    private saveLogsToFile;
+}

package/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./Renderable";
+export * from "./types";
+export * from "./utils";
+export * from "./buffer";
+export * from "./text-buffer";
+export * from "./post/filters";
+export * from "./animation/Timeline";
+export * from "./lib";
+export * from "./lib/parse.keypress";
+export * from "./lib/styled-text";
+export * from "./lib/selection";
+export * from "./renderer";
+export * from "./renderables";