@xincli/opentui-core 0.4.6 → 0.4.7

package/plugins/registry.d.ts

@@ -0,0 +1,42 @@
+import type { CliRenderer } from "../renderer.js";
+import type { Plugin, PluginContext, PluginErrorEvent, PluginErrorReport, ResolvedSlotRenderer, SlotRenderer } from "./types.js";
+export interface SlotRegistryOptions {
+    onPluginError?: (event: PluginErrorEvent) => void;
+    debugPluginErrors?: boolean;
+    maxPluginErrors?: number;
+}
+export declare class SlotRegistry<TNode, TSlots extends object, TContext extends PluginContext = PluginContext> {
+    private plugins;
+    private sortedPluginsCache;
+    private listeners;
+    private errorListeners;
+    private pluginErrors;
+    private registrationOrder;
+    private batchDepth;
+    private batchedNotify;
+    private rendererInstance;
+    private hostContext;
+    private options;
+    constructor(renderer: CliRenderer, context: TContext, options?: SlotRegistryOptions);
+    get renderer(): CliRenderer;
+    get context(): Readonly<TContext>;
+    configure(options: SlotRegistryOptions): void;
+    register(plugin: Plugin<TNode, TSlots, TContext>): () => void;
+    unregister(id: string): boolean;
+    updateOrder(id: string, order: number): boolean;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    onPluginError(listener: (event: PluginErrorEvent) => void): () => void;
+    batch<T>(run: () => T): T;
+    getPluginErrors(): readonly PluginErrorEvent[];
+    clearPluginErrors(): void;
+    reportPluginError(report: PluginErrorReport): PluginErrorEvent;
+    resolve<K extends keyof TSlots>(slot: K): Array<SlotRenderer<TNode, TSlots[K], TContext>>;
+    resolveEntries<K extends keyof TSlots>(slot: K): Array<ResolvedSlotRenderer<TNode, TSlots[K], TContext>>;
+    private getSortedPlugins;
+    private syncPluginSortMetadata;
+    private invalidateSortedPluginsCache;
+    private notifyListeners;
+    private flushListeners;
+}
+export declare function createSlotRegistry<TNode, TSlots extends object, TContext extends PluginContext = PluginContext>(renderer: CliRenderer, key: string, context: TContext, options?: SlotRegistryOptions): SlotRegistry<TNode, TSlots, TContext>;

package/plugins/types.d.ts

@@ -0,0 +1,34 @@
+import type { CliRenderer } from "../renderer.js";
+export type PluginContext = object;
+export type SlotMode = "append" | "replace" | "single_winner";
+export type PluginErrorPhase = "setup" | "render" | "dispose" | "error_placeholder";
+export type PluginErrorSource = "registry" | "core" | (string & {});
+export interface PluginErrorEvent {
+    pluginId: string;
+    slot?: string;
+    phase: PluginErrorPhase;
+    source: PluginErrorSource;
+    error: Error;
+    timestamp: number;
+}
+export interface PluginErrorReport {
+    pluginId: string;
+    slot?: string;
+    phase: PluginErrorPhase;
+    source?: PluginErrorSource;
+    error: unknown;
+}
+export type SlotRenderer<TNode, TProps, TContext extends PluginContext = PluginContext> = (ctx: Readonly<TContext>, props: TProps) => TNode;
+export interface Plugin<TNode, TSlots extends object, TContext extends PluginContext = PluginContext> {
+    id: string;
+    order?: number;
+    setup?: (ctx: Readonly<TContext>, renderer: CliRenderer) => void;
+    dispose?: () => void;
+    slots: {
+        [K in keyof TSlots]?: SlotRenderer<TNode, TSlots[K], TContext>;
+    };
+}
+export interface ResolvedSlotRenderer<TNode, TProps, TContext extends PluginContext = PluginContext> {
+    id: string;
+    renderer: SlotRenderer<TNode, TProps, TContext>;
+}

package/post/effects.d.ts

@@ -0,0 +1,147 @@
+import type { OptimizedBuffer } from "../buffer.js";
+export declare class DistortionEffect {
+    glitchChancePerSecond: number;
+    maxGlitchLines: number;
+    minGlitchDuration: number;
+    maxGlitchDuration: number;
+    maxShiftAmount: number;
+    shiftFlipRatio: number;
+    colorGlitchChance: number;
+    private lastGlitchTime;
+    private glitchDuration;
+    private activeGlitches;
+    constructor(options?: Partial<DistortionEffect>);
+    /**
+     * Applies the animated distortion/glitch effect to the buffer.
+     */
+    apply(buffer: OptimizedBuffer, deltaTime: number): void;
+}
+/**
+ * Applies a vignette effect by darkening the corners, optimized with precomputation.
+ * Uses native colorMatrix with a zero matrix for attenuation.
+ */
+export declare class VignetteEffect {
+    private _strength;
+    private precomputedAttenuationCellMask;
+    private cachedWidth;
+    private cachedHeight;
+    private static zeroMatrix;
+    constructor(strength?: number);
+    set strength(newStrength: number);
+    get strength(): number;
+    private _computeFactors;
+    /**
+     * Applies the vignette effect using native colorMatrix with a zero matrix.
+     * The zero matrix maps all colors to black, and the attenuation cell masks
+     * control how much of the effect is applied (strength-based blending).
+     */
+    apply(buffer: OptimizedBuffer): void;
+}
+/**
+ * Applies animated cloud shadows using Perlin noise.
+ * Darkens the background buffer based on procedural cloud density.
+ */
+export declare class CloudsEffect {
+    private noise;
+    private _scale;
+    private _speed;
+    private _density;
+    private _darkness;
+    private time;
+    constructor(scale?: number, speed?: number, density?: number, darkness?: number);
+    set scale(newScale: number);
+    get scale(): number;
+    set speed(newSpeed: number);
+    get speed(): number;
+    set density(newDensity: number);
+    get density(): number;
+    set darkness(newDarkness: number);
+    get darkness(): number;
+    /**
+     * Applies cloud shadow effect using Perlin noise mask with native colorMatrix.
+     * Uses FBM (Fractal Brownian Motion) for detailed clouds, offloaded to native code.
+     */
+    apply(buffer: OptimizedBuffer, deltaTime: number): void;
+}
+/**
+ * Applies animated flames rising from the bottom using Perlin noise.
+ * Creates warm fire effect that fades as it rises.
+ */
+export declare class FlamesEffect {
+    private noise;
+    private _scale;
+    private _speed;
+    private _intensity;
+    private time;
+    constructor(scale?: number, speed?: number, intensity?: number);
+    set scale(newScale: number);
+    get scale(): number;
+    set speed(newSpeed: number);
+    get speed(): number;
+    set intensity(newIntensity: number);
+    get intensity(): number;
+    /**
+     * Applies flame effect rising from bottom using Perlin noise.
+     * Flames get cooler (redder) and fade as they rise.
+     */
+    apply(buffer: OptimizedBuffer, deltaTime: number): void;
+}
+/**
+ * Applies a CRT rolling bar effect - a horizontal bar that slowly scans down the screen.
+ * Simulates the classic CRT monitor rolling bar artifact.
+ */
+export declare class CRTRollingBarEffect {
+    private _speed;
+    private _height;
+    private _intensity;
+    private _fadeDistance;
+    private position;
+    constructor(speed?: number, height?: number, intensity?: number, fadeDistance?: number);
+    set speed(newSpeed: number);
+    get speed(): number;
+    set height(newHeight: number);
+    get height(): number;
+    set intensity(newIntensity: number);
+    get intensity(): number;
+    set fadeDistance(newFadeDistance: number);
+    get fadeDistance(): number;
+    /**
+     * Applies the rolling bar effect to the buffer.
+     * Creates a smooth horizontal bar that scans down the screen with a bell-curve gradient.
+     * The bar has a bright center that smoothly fades to the edges.
+     */
+    apply(buffer: OptimizedBuffer, deltaTime: number): void;
+}
+/**
+ * Applies animated rainbow colors to cells with white foreground.
+ * Cycles through HSV hue spectrum over time.
+ */
+export declare class RainbowTextEffect {
+    private _speed;
+    private _saturation;
+    private _value;
+    private _repeats;
+    private time;
+    constructor(speed?: number, saturation?: number, value?: number, repeats?: number);
+    set speed(newSpeed: number);
+    get speed(): number;
+    set saturation(newSaturation: number);
+    get saturation(): number;
+    set value(newValue: number);
+    get value(): number;
+    set repeats(newRepeats: number);
+    get repeats(): number;
+    /**
+     * Converts HSV color to RGB
+     * @param h - Hue [0, 1]
+     * @param s - Saturation [0, 1]
+     * @param v - Value [0, 1]
+     * @returns [r, g, b] each in [0, 1]
+     */
+    private hsvToRgb;
+    /**
+     * Applies rainbow colors to cells with white foreground.
+     * White is defined as R, G, B all >= 0.9
+     */
+    apply(buffer: OptimizedBuffer, deltaTime: number): void;
+}

package/post/filters.d.ts

@@ -0,0 +1,65 @@
+import type { OptimizedBuffer } from "../buffer.js";
+/**
+ * Applies a scanline effect by darkening every nth row using native color matrix.
+ * Only affects the background buffer to maintain text readability.
+ */
+export declare function applyScanlines(buffer: OptimizedBuffer, strength?: number, step?: number): void;
+/**
+ * Inverts the colors in the buffer using native color matrix.
+ * Uses negative matrix with alpha offset: output = 1.0 - input for each RGB channel.
+ */
+export declare function applyInvert(buffer: OptimizedBuffer, strength?: number): void;
+/**
+ * Adds random noise to the buffer colors using colorMatrix with brightness matrix.
+ * Uses per-pixel random strength values to dim/brighten each cell.
+ */
+export declare function applyNoise(buffer: OptimizedBuffer, strength?: number): void;
+/**
+ * Applies a simplified chromatic aberration effect.
+ */
+export declare function applyChromaticAberration(buffer: OptimizedBuffer, strength?: number): void;
+/**
+ * Converts the buffer to ASCII art based on background brightness.
+ * Uses native colorMatrix for efficient color corrections.
+ */
+export declare function applyAsciiArt(buffer: OptimizedBuffer, ramp?: string, fgColor?: {
+    r: number;
+    g: number;
+    b: number;
+}, bgColor?: {
+    r: number;
+    g: number;
+    b: number;
+}): void;
+/**
+ * Adjusts the brightness of the buffer using color matrix transformation.
+ * Brightness adds the brightness value to all RGB channels (additive brightness).
+ *                   If not provided, applies uniform brightness to entire buffer.
+ */
+export declare function applyBrightness(buffer: OptimizedBuffer, brightness?: number, cellMask?: Float32Array): void;
+/**
+ * Adjusts the gain of the buffer using color matrix transformation.
+ * Gain multiplies all RGB channels by the gain factor (no clamping).
+ *                   If not provided, applies uniform gain to entire buffer.
+ */
+export declare function applyGain(buffer: OptimizedBuffer, gain?: number, cellMask?: Float32Array): void;
+/**
+ * Applies a saturation adjustment to the buffer.
+ */
+export declare function applySaturation(buffer: OptimizedBuffer, cellMask?: Float32Array, strength?: number): void;
+/**
+ * Applies a bloom effect based on bright areas (Simplified).
+ */
+export declare class BloomEffect {
+    private _threshold;
+    private _strength;
+    private _radius;
+    constructor(threshold?: number, strength?: number, radius?: number);
+    set threshold(newThreshold: number);
+    get threshold(): number;
+    set strength(newStrength: number);
+    get strength(): number;
+    set radius(newRadius: number);
+    get radius(): number;
+    apply(buffer: OptimizedBuffer): void;
+}

package/post/matrices.d.ts

@@ -0,0 +1,20 @@
+export declare const SEPIA_MATRIX: Float32Array<ArrayBuffer>;
+/**
+ * Colorblindness simulation and compensation filters using color matrix transformations.
+ */
+export declare const PROTANOPIA_SIM_MATRIX: Float32Array<ArrayBuffer>;
+export declare const DEUTERANOPIA_SIM_MATRIX: Float32Array<ArrayBuffer>;
+export declare const TRITANOPIA_SIM_MATRIX: Float32Array<ArrayBuffer>;
+export declare const ACHROMATOPSIA_MATRIX: Float32Array<ArrayBuffer>;
+export declare const PROTANOPIA_COMP_MATRIX: Float32Array<ArrayBuffer>;
+export declare const DEUTERANOPIA_COMP_MATRIX: Float32Array<ArrayBuffer>;
+export declare const TRITANOPIA_COMP_MATRIX: Float32Array<ArrayBuffer>;
+/**
+ * Creative color effect matrices.
+ */
+export declare const TECHNICOLOR_MATRIX: Float32Array<ArrayBuffer>;
+export declare const SOLARIZATION_MATRIX: Float32Array<ArrayBuffer>;
+export declare const SYNTHWAVE_MATRIX: Float32Array<ArrayBuffer>;
+export declare const GREENSCALE_MATRIX: Float32Array<ArrayBuffer>;
+export declare const GRAYSCALE_MATRIX: Float32Array<ArrayBuffer>;
+export declare const INVERT_MATRIX: Float32Array<ArrayBuffer>;

package/renderables/ASCIIFont.d.ts

@@ -0,0 +1,52 @@
+import { type ASCIIFontName, type fonts } from "../lib/ascii.font.js";
+import { type ColorInput } from "../lib/RGBA.js";
+import { Selection, type LocalSelectionBounds } from "../lib/selection.js";
+import type { RenderableOptions } from "../Renderable.js";
+import type { RenderContext } from "../types.js";
+import { FrameBufferRenderable } from "./FrameBuffer.js";
+export interface ASCIIFontOptions extends Omit<RenderableOptions<ASCIIFontRenderable>, "width" | "height"> {
+    text?: string;
+    font?: ASCIIFontName;
+    color?: ColorInput | ColorInput[];
+    backgroundColor?: ColorInput;
+    selectionBg?: ColorInput;
+    selectionFg?: ColorInput;
+    selectable?: boolean;
+}
+export declare class ASCIIFontRenderable extends FrameBufferRenderable {
+    selectable: boolean;
+    protected static readonly _defaultOptions: {
+        text: string;
+        font: "tiny";
+        color: string;
+        backgroundColor: string;
+        selectionBg: undefined;
+        selectionFg: undefined;
+        selectable: true;
+    };
+    protected _text: string;
+    protected _font: keyof typeof fonts;
+    protected _color: ColorInput | ColorInput[];
+    protected _backgroundColor: ColorInput;
+    protected _selectionBg: ColorInput | undefined;
+    protected _selectionFg: ColorInput | undefined;
+    protected lastLocalSelection: LocalSelectionBounds | null;
+    private selectionHelper;
+    constructor(ctx: RenderContext, options: ASCIIFontOptions);
+    get text(): string;
+    set text(value: string);
+    get font(): keyof typeof fonts;
+    set font(value: keyof typeof fonts);
+    get color(): ColorInput | ColorInput[];
+    set color(value: ColorInput | ColorInput[]);
+    get backgroundColor(): ColorInput;
+    set backgroundColor(value: ColorInput);
+    private updateDimensions;
+    shouldStartSelection(x: number, y: number): boolean;
+    onSelectionChanged(selection: Selection | null): boolean;
+    getSelectedText(): string;
+    hasSelection(): boolean;
+    protected onResize(width: number, height: number): void;
+    private renderFontToBuffer;
+    private renderSelectionHighlight;
+}

package/renderables/Box.d.ts

@@ -0,0 +1,85 @@
+import { type RenderableOptions, Renderable } from "../Renderable.js";
+import type { OptimizedBuffer } from "../buffer.js";
+import { type BorderCharacters, type BorderSides, type BorderSidesConfig, type BorderStyle } from "../lib/index.js";
+import { type ColorInput, RGBA } from "../lib/RGBA.js";
+import type { RenderContext } from "../types.js";
+export interface BoxOptions<TRenderable extends Renderable = BoxRenderable> extends RenderableOptions<TRenderable> {
+    backgroundColor?: string | RGBA;
+    borderStyle?: BorderStyle;
+    border?: boolean | BorderSides[];
+    borderColor?: string | RGBA;
+    customBorderChars?: BorderCharacters;
+    shouldFill?: boolean;
+    title?: string;
+    titleColor?: string | RGBA;
+    titleAlignment?: "left" | "center" | "right";
+    bottomTitle?: string;
+    bottomTitleAlignment?: "left" | "center" | "right";
+    focusedBorderColor?: ColorInput;
+    focusable?: boolean;
+    gap?: number | `${number}%`;
+    rowGap?: number | `${number}%`;
+    columnGap?: number | `${number}%`;
+}
+export declare class BoxRenderable extends Renderable {
+    protected _backgroundColor: RGBA;
+    protected _border: boolean | BorderSides[];
+    protected _borderStyle: BorderStyle;
+    protected _borderColor: RGBA;
+    protected _focusedBorderColor: RGBA;
+    private _customBorderCharsObj;
+    protected _customBorderChars?: Uint32Array;
+    protected borderSides: BorderSidesConfig;
+    shouldFill: boolean;
+    protected _title?: string;
+    protected _titleColor?: RGBA;
+    protected _titleAlignment: "left" | "center" | "right";
+    protected _bottomTitle?: string;
+    protected _bottomTitleAlignment: "left" | "center" | "right";
+    protected _defaultOptions: {
+        backgroundColor: string;
+        borderStyle: "single";
+        border: false;
+        borderColor: string;
+        shouldFill: true;
+        titleAlignment: "left";
+        bottomTitleAlignment: "left";
+        focusedBorderColor: string;
+    };
+    constructor(ctx: RenderContext, options: BoxOptions);
+    private initializeBorder;
+    get customBorderChars(): BorderCharacters | undefined;
+    set customBorderChars(value: BorderCharacters | undefined);
+    get backgroundColor(): RGBA;
+    set backgroundColor(value: RGBA | string | undefined);
+    get border(): boolean | BorderSides[];
+    set border(value: boolean | BorderSides[]);
+    get borderStyle(): BorderStyle;
+    set borderStyle(value: BorderStyle);
+    get borderColor(): RGBA;
+    set borderColor(value: RGBA | string);
+    get focusedBorderColor(): RGBA;
+    set focusedBorderColor(value: RGBA | string);
+    get title(): string | undefined;
+    set title(value: string | undefined);
+    get titleColor(): RGBA | undefined;
+    set titleColor(value: string | RGBA | undefined);
+    get titleAlignment(): "left" | "center" | "right";
+    set titleAlignment(value: "left" | "center" | "right");
+    get bottomTitle(): string | undefined;
+    set bottomTitle(value: string | undefined);
+    get bottomTitleAlignment(): "left" | "center" | "right";
+    set bottomTitleAlignment(value: "left" | "center" | "right");
+    protected renderSelf(buffer: OptimizedBuffer): void;
+    protected getScissorRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    private applyYogaBorders;
+    private applyYogaGap;
+    set gap(gap: number | `${number}%` | undefined);
+    set rowGap(rowGap: number | `${number}%` | undefined);
+    set columnGap(columnGap: number | `${number}%` | undefined);
+}

package/renderables/Code.d.ts

@@ -0,0 +1,97 @@
+import { type LineInfo, type RenderContext } from "../types.js";
+import { StyledText } from "../lib/styled-text.js";
+import { SyntaxStyle } from "../syntax-style.js";
+import { TreeSitterClient } from "../lib/tree-sitter/index.js";
+import { TextBufferRenderable, type TextBufferOptions } from "./TextBufferRenderable.js";
+import type { OptimizedBuffer } from "../buffer.js";
+import type { SimpleHighlight } from "../lib/tree-sitter/types.js";
+import type { TextChunk } from "../text-buffer.js";
+export interface HighlightContext {
+    content: string;
+    filetype: string;
+    syntaxStyle: SyntaxStyle;
+}
+export type OnHighlightCallback = (highlights: SimpleHighlight[], context: HighlightContext) => SimpleHighlight[] | undefined | Promise<SimpleHighlight[] | undefined>;
+export interface ChunkRenderContext extends HighlightContext {
+    highlights: SimpleHighlight[];
+}
+export type OnChunksCallback = (chunks: TextChunk[], context: ChunkRenderContext) => TextChunk[] | undefined | Promise<TextChunk[] | undefined>;
+export interface CodeOptions extends TextBufferOptions {
+    content?: string;
+    filetype?: string;
+    syntaxStyle: SyntaxStyle;
+    treeSitterClient?: TreeSitterClient;
+    conceal?: boolean;
+    drawUnstyledText?: boolean;
+    streaming?: boolean;
+    initialStyledText?: StyledText;
+    baseHighlight?: string;
+    onHighlight?: OnHighlightCallback;
+    onChunks?: OnChunksCallback;
+}
+export declare class CodeRenderable extends TextBufferRenderable {
+    private _content;
+    private _filetype?;
+    private _syntaxStyle;
+    private _isHighlighting;
+    private _treeSitterClient;
+    private _highlightsDirty;
+    private _highlightSnapshotId;
+    private _conceal;
+    private _drawUnstyledText;
+    private _shouldRenderTextBuffer;
+    private _streaming;
+    private _initialStyledText?;
+    private _hadInitialContent;
+    private _lastHighlights;
+    private _baseHighlight?;
+    private _onHighlight?;
+    private _onChunks?;
+    private _highlightingPromise;
+    private _renderedLineSources?;
+    private _mappedLineInfo?;
+    protected _contentDefaultOptions: {
+        content: string;
+        conceal: true;
+        drawUnstyledText: true;
+        streaming: false;
+    };
+    constructor(ctx: RenderContext, options: CodeOptions);
+    get content(): string;
+    set content(value: string);
+    get lineInfo(): LineInfo;
+    get wrapMode(): "none" | "char" | "word";
+    set wrapMode(value: "none" | "char" | "word");
+    protected onResize(width: number, height: number): void;
+    protected updateTextInfo(): void;
+    get filetype(): string | undefined;
+    set filetype(value: string | undefined);
+    get syntaxStyle(): SyntaxStyle;
+    set syntaxStyle(value: SyntaxStyle);
+    get conceal(): boolean;
+    set conceal(value: boolean);
+    get drawUnstyledText(): boolean;
+    set drawUnstyledText(value: boolean);
+    get streaming(): boolean;
+    set initialStyledText(value: StyledText | undefined);
+    set streaming(value: boolean);
+    get treeSitterClient(): TreeSitterClient;
+    set treeSitterClient(value: TreeSitterClient);
+    get onHighlight(): OnHighlightCallback | undefined;
+    get baseHighlight(): string | undefined;
+    set baseHighlight(value: string | undefined);
+    set onHighlight(value: OnHighlightCallback | undefined);
+    get onChunks(): OnChunksCallback | undefined;
+    set onChunks(value: OnChunksCallback | undefined);
+    get isHighlighting(): boolean;
+    get highlightingDone(): Promise<void>;
+    protected transformChunks(chunks: TextChunk[], context: ChunkRenderContext): Promise<TextChunk[]>;
+    private ensureVisibleTextBeforeHighlight;
+    private startHighlight;
+    private setRenderedLineSources;
+    private static isIdentityLineSources;
+    private static getMergedConcealLineRanges;
+    private getConcealLinesSourceMap;
+    getLineHighlights(lineIdx: number): import("../types.js").Highlight[];
+    protected renderSelf(buffer: OptimizedBuffer): void;
+}