@simon_he/vue-tui 0.0.8 → 1.0.0

package/dist/core/ansi/capability.d.ts

@@ -0,0 +1,20 @@
+import type { TerminalColorLevel, TerminalColorMode } from "./colors.js";
+export type TerminalColorCapability = Readonly<{
+    mode: TerminalColorMode;
+    level: TerminalColorLevel;
+}>;
+/**
+ * Detect terminal output color capability.
+ *
+ * - `mode` is the best-effort actual output mode.
+ * - `level` is the CLI theme tier (256/16/8). `truecolor` folds into `256`.
+ * - Pass `platform` (e.g. `process.platform`) to improve Windows detection.
+ *
+ * Env overrides:
+ * - `VUE_TUI_COLOR_MODE` / legacy `DIMCODE_COLOR_MODE`
+ */
+export declare function detectTerminalColorCapability(opts?: Readonly<{
+    env?: Record<string, unknown>;
+    isTTY?: boolean;
+    platform?: string;
+}>): TerminalColorCapability;

package/dist/core/ansi/colors.d.ts

@@ -0,0 +1,41 @@
+import type { AnsiColorName } from "../types.js";
+export type TerminalColorMode = "ansi8" | "ansi16" | "ansi256" | "truecolor";
+export type TerminalColorLevel = 8 | 16 | 256;
+export type AnsiRgb = Readonly<{
+    r: number;
+    g: number;
+    b: number;
+}>;
+export type Ansi8ColorName = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white";
+export declare const ANSI8_COLOR_NAMES: readonly Ansi8ColorName[];
+export declare const ANSI16_COLOR_NAMES: readonly AnsiColorName[];
+export type AnsiColorEntry = Readonly<{
+    level: TerminalColorLevel;
+    /** 0..(level-1) for ansi8/16; 0..255 for ansi256 */
+    index: number;
+    name?: AnsiColorName;
+    rgb: AnsiRgb;
+    fgOpen: string;
+    bgOpen: string;
+}>;
+export declare const SGR_RESET = "\u001B[0m";
+export declare const SGR_BOLD = "\u001B[1m";
+export declare const SGR_DIM = "\u001B[2m";
+export declare const SGR_ITALIC = "\u001B[3m";
+export declare const SGR_UNDERLINE = "\u001B[4m";
+export declare const SGR_INVERSE = "\u001B[7m";
+export declare function toAnsi8ColorName(name: AnsiColorName): Ansi8ColorName;
+export declare function ansi8FgOpen(name: AnsiColorName): string;
+export declare function ansi8BgOpen(name: AnsiColorName): string;
+export declare function ansi16FgOpen(name: AnsiColorName): string;
+export declare function ansi16BgOpen(name: AnsiColorName): string;
+export declare function ansi256FgOpen(index: number): string;
+export declare function ansi256BgOpen(index: number): string;
+export declare function truecolorFgOpen(rgb: AnsiRgb): string;
+export declare function truecolorBgOpen(rgb: AnsiRgb): string;
+export declare function ansi256ToRgb(index: number): AnsiRgb;
+export declare function rgbToAnsi256(rgb: AnsiRgb): number;
+export declare function rgbToAnsi16(rgb: AnsiRgb): AnsiColorName;
+export declare function ansi8Palette(): readonly AnsiColorEntry[];
+export declare function ansi16Palette(): readonly AnsiColorEntry[];
+export declare function ansi256Palette(): readonly AnsiColorEntry[];

package/dist/core/ansi/sgr.d.ts

@@ -0,0 +1,7 @@
+import type { Style } from "../types.js";
+export declare function applyAnsiSgrStyle(current: Style, codes: number[]): Style;
+export interface AnsiSegment {
+    text: string;
+    style: Style;
+}
+export declare function parseAnsiSgr(input: string, baseStyle?: Style): AnsiSegment[];

package/dist/core/ansi/theme.d.ts

@@ -0,0 +1,6 @@
+export declare function rgbToHex(r: number, g: number, b: number): string;
+export declare function ansi16ToCss(code: number): {
+    fg?: string;
+    bg?: string;
+};
+export declare function ansi256ToCss(index: number): string;

package/dist/core/ansi-palette.d.ts

@@ -0,0 +1,14 @@
+import type { AnsiColorName } from "./types.js";
+export type AnsiRgb = Readonly<{
+    r: number;
+    g: number;
+    b: number;
+}>;
+export type ThemePalette = Partial<Record<AnsiColorName, string>>;
+export declare const ANSI_PALETTE_HEX: Readonly<Record<AnsiColorName, string>>;
+export declare function ansiHexToRgb(hex: string): AnsiRgb | undefined;
+export declare function isAnsiColorName(name: string | undefined): name is AnsiColorName;
+export declare function ansiColorHex(name?: string, palette?: ThemePalette | null): string | undefined;
+export declare function ansiColorRgb(name?: string, palette?: ThemePalette | null): AnsiRgb | undefined;
+export declare function ansiCssVar(name: AnsiColorName): string;
+export declare function installAnsiPaletteCssVars(container: HTMLElement, palette?: ThemePalette | null): void;

package/dist/core/buffer/buffer.d.ts

@@ -0,0 +1,54 @@
+import type { Cell, Style } from "../types.js";
+import type { WidthProvider } from "./width.js";
+export declare function normalizeStyle(style?: Style): Style;
+export declare function createCell(ch: string, style?: Style, widthProvider?: WidthProvider): Cell;
+export declare function createBlankCell(style?: Style): Cell;
+export declare function createContinuationCell(style?: Style): Cell;
+export type CellFingerprintFn = (ch: string, style: Style) => number;
+export interface GridBuffer {
+    cols: number;
+    rows: number;
+    grid: Cell[][];
+    gridStart: number;
+    dirtyBits: Uint8Array;
+    dirtyCount: number;
+    dirtyMin: number;
+    dirtyMax: number;
+    dirtyAll: boolean;
+    cursorX: number;
+    cursorY: number;
+    cursorVisible: boolean;
+    cursorStyle: Style;
+    scrollback: Cell[][];
+    scrollbackLimit: number;
+    rowPool: Cell[][];
+    soaFingerprints: Uint32Array | null;
+    fingerprintFn: CellFingerprintFn | null;
+    widthProvider: WidthProvider;
+}
+export declare function createGridBuffer(cols: number, rows: number, options?: Readonly<{
+    widthProvider?: WidthProvider;
+}>): GridBuffer;
+export declare function clamp(n: number, min: number, max: number): number;
+/**
+ * Register a fingerprint function on the buffer. This enables SoA fingerprint
+ * pre-computation: cell writes will update fingerprints inline, and the renderer
+ * can read them via getRowFingerprints() instead of per-cell hash computation.
+ */
+export declare function setFingerprintFn(buffer: GridBuffer, fn: CellFingerprintFn): void;
+/**
+ * Get pre-computed fingerprints for a logical row as a TypedArray slice.
+ * Returns null if fingerprinting is not enabled on this buffer.
+ */
+export declare function getRowFingerprints(buffer: GridBuffer, y: number): Uint32Array | null;
+export declare function getBufferRow(buffer: GridBuffer, y: number): Cell[];
+export declare function getBufferCell(buffer: GridBuffer, x: number, y: number): Cell;
+export declare function markAllDirty(buffer: GridBuffer): void;
+export declare function markDirty(buffer: GridBuffer, y: number): void;
+export declare function putCell(buffer: GridBuffer, x: number, y: number, ch: string, style?: Style): void;
+export declare function fillRect(buffer: GridBuffer, x: number, y: number, w: number, h: number, ch?: string, style?: Style): void;
+export declare function clearRect(buffer: GridBuffer, x?: number, y?: number, w?: number, h?: number): void;
+export declare function scrollBuffer(buffer: GridBuffer, lines: number): void;
+export declare function scrollBufferRegion(buffer: GridBuffer, startY: number, endY: number, lines: number): readonly number[];
+export declare function resizeBuffer(buffer: GridBuffer, cols: number, rows: number): void;
+export declare function snapshotText(buffer: GridBuffer): string[];

package/dist/core/buffer/width.d.ts

@@ -0,0 +1,4 @@
+export type CellWidth = 1 | 2;
+export type BuiltinWidthProvider = "default" | "cjk" | "narrow-ambiguous";
+export type WidthProvider = BuiltinWidthProvider | ((text: string) => CellWidth);
+export declare function charCellWidth(text: string, provider?: WidthProvider): CellWidth;

package/dist/core/debug-logger.d.ts

@@ -0,0 +1,18 @@
+type DebugFileWriter = Readonly<{
+    appendFileSync?: (path: string, data: string) => void;
+    writeFileSync?: (path: string, data: string) => void;
+}>;
+export declare function setDebugFileWriter(writer: DebugFileWriter | null): void;
+export declare function resolveDebugLogPath(env: Record<string, unknown> | undefined, fallback?: string): string;
+export declare function setDebugLogDefaultPath(path: string | null): void;
+export interface DebugLogger {
+    render: (message: string) => void;
+    stream: (message: string) => void;
+    error: (message: string, ...args: any[]) => void;
+}
+export declare function createDebugLogger(enable?: boolean): DebugLogger;
+/**
+ * Check if debug logging is enabled via environment variable
+ */
+export declare function isDebugEnabled(): boolean;
+export {};

package/dist/core/hyperlink.d.ts

@@ -0,0 +1,9 @@
+export type SanitizeTerminalHrefOptions = Readonly<{
+    allowFileUrls?: boolean;
+}>;
+export type SanitizeDomHrefOptions = Readonly<{
+    allowRelative?: boolean;
+}>;
+export declare function isSafeRelativeHref(value: string): boolean;
+export declare function sanitizeTerminalHref(value: unknown, options?: SanitizeTerminalHrefOptions): string | null;
+export declare function sanitizeDomHref(value: unknown, options?: SanitizeDomHrefOptions): string | null;

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { TERMINAL_RENDER_PLANES, type TerminalRenderPlane, type TerminalRenderPlanes, } from "./render-plane.js";
+export { createTerminal } from "./terminal/create-terminal.js";
+export type { AnsiColorName, BufferSnapshot, Cell, Style, Terminal, TerminalCommitEvent, TerminalEventMap, TerminalOptions, TerminalResizeEvent, TerminalScrollOperation, ThemeModeId, } from "./types.js";
+export type { BuiltinWidthProvider, CellWidth, WidthProvider } from "./buffer/width.js";

package/dist/core/path-provider-types.d.ts

@@ -0,0 +1,24 @@
+import type { PathPickMode, SuggestPathsResult } from "./path-suggest.js";
+export type FsEntryKind = "file" | "directory" | "other";
+export type FsDirEntry = Readonly<{
+    name: string;
+    kind: FsEntryKind;
+}>;
+export type FsStat = Readonly<{
+    exists: boolean;
+    kind: FsEntryKind;
+}>;
+export type PathPickerProvider = Readonly<{
+    listDir: (absDir: string) => Promise<FsDirEntry[]>;
+    stat: (absPath: string) => Promise<FsStat>;
+    suggest?: (info: Readonly<{
+        workspaceAbs: string;
+        input: string;
+        mode: PathPickMode;
+        max: number;
+        showHidden?: boolean;
+        maxDepth?: number;
+        gitignore?: "blocking" | "nonBlocking";
+    }>) => Promise<SuggestPathsResult>;
+    resolvePath?: (workspaceAbs: string, input: string) => string | Promise<string>;
+}>;

package/dist/core/path-suggest.d.ts

@@ -0,0 +1,35 @@
+import type { FsDirEntry } from "./path-provider-types.js";
+export type PathPickMode = "directory" | "file" | "any";
+export type PathSuggestion = Readonly<{
+    kind: "directory" | "file";
+    display: string;
+    completion: string;
+    absPath: string;
+}>;
+export type SuggestPathsResult = Readonly<{
+    baseDirAbs: string;
+    dirPrefix: string;
+    query: string;
+    suggestions: PathSuggestion[];
+}>;
+export declare function parsePathQuery(rawInput: string): {
+    dirPrefix: string;
+    query: string;
+};
+export declare function suggestPaths(options: Readonly<{
+    workspaceAbs: string;
+    input: string;
+    mode: PathPickMode;
+    max: number;
+    showHidden?: boolean;
+    listDir: (absDir: string) => Promise<FsDirEntry[]>;
+    maxDepth?: number;
+    shouldIgnore?: (info: Readonly<{
+        normalizedRelPath: string;
+        isDir: boolean;
+    }>) => boolean;
+}>): Promise<SuggestPathsResult>;
+export declare function resolveUserPath(workspaceAbs: string, input: string, options?: Readonly<{
+    homeDir?: string;
+}>): string;
+export declare function suggestParentHint(path: string): string;

package/dist/core/render-plane.d.ts

@@ -0,0 +1,3 @@
+export declare const TERMINAL_RENDER_PLANES: readonly ["default", "transcript", "chrome", "overlay"];
+export type TerminalRenderPlane = (typeof TERMINAL_RENDER_PLANES)[number];
+export type TerminalRenderPlanes = readonly TerminalRenderPlane[];

package/dist/core/terminal/create-terminal.d.ts

@@ -0,0 +1,8 @@
+import type { TerminalRenderPlane, TerminalRenderPlanes } from "../render-plane.js";
+import type { Cell, Terminal, TerminalOptions } from "../types.js";
+export declare function getPlaneTerminal(terminal: Terminal, plane: TerminalRenderPlane): Terminal;
+export declare function readTerminalRowForPlanes(terminal: Terminal, y: number, planes?: TerminalRenderPlanes | null): readonly Cell[];
+export declare function resetPlaneRowsForRender(terminal: Terminal, plane: TerminalRenderPlane, dirtyRows: readonly number[] | null): void;
+export declare function getPlaneRowCoverageKind(terminal: Terminal, plane: TerminalRenderPlane, y: number): 0 | 1 | 2;
+export declare function scrollPlaneRows(terminal: Terminal, plane: TerminalRenderPlane, startY: number, endY: number, lines: number): void;
+export declare function createTerminal(opts: TerminalOptions): Terminal;

package/dist/core/terminal/emitter.d.ts

@@ -0,0 +1,7 @@
+export declare class Emitter<EventMap extends Record<string, any>> {
+    constructor();
+    private getListeners;
+    on<K extends keyof EventMap>(event: K, cb: (payload: EventMap[K]) => void): () => void;
+    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
+    clear(): void;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,107 @@
+import type { TerminalRenderPlanes } from "./render-plane.js";
+import type { WidthProvider } from "./buffer/width.js";
+export type ThemeModeId = "dark" | "light";
+export type AnsiColorName = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright";
+export type Style = Readonly<{
+    /**
+     * Foreground color. Accepts:
+     * - `AnsiColorName` (e.g. `'cyanBright'`) — resolved via palette or standard ANSI codes
+     * - Hex string (e.g. `'#a9dc76'`) — converted to truecolor/ansi256 RGB
+     * - `'transparent'` — resets to terminal default (`\e[39m`)
+     */
+    fg?: string;
+    /**
+     * Background color. Same value space as `fg`.
+     * `'transparent'` resets to terminal default (`\e[49m`).
+     */
+    bg?: string;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+    /**
+     * Optional hyperlink target associated with this styled text.
+     *
+     * Renderer behavior:
+     * - stdout renderer may emit OSC 8 hyperlinks after sanitization.
+     * - DOM renderer may render <a> elements when DomRendererOptions.links is enabled.
+     *
+     * Unsafe protocols/control characters are ignored by renderers.
+     */
+    href?: string;
+}>;
+export type Cell = Readonly<{
+    ch: string;
+    width: 1 | 2;
+    continuation?: true;
+    style: Style;
+}>;
+export type BufferSnapshot = Readonly<{
+    cols: number;
+    rows: number;
+    lines: readonly string[];
+}>;
+export type TerminalSize = Readonly<{
+    cols: number;
+    rows: number;
+}>;
+export type TerminalOptions = Readonly<{
+    cols: number;
+    rows: number;
+    widthProvider?: WidthProvider;
+}>;
+export type TerminalScrollOperation = Readonly<{
+    startY: number;
+    endY: number;
+    delta: number;
+}>;
+export type TerminalCommitEvent = Readonly<{
+    dirtyRows: readonly number[] | null;
+    planes: TerminalRenderPlanes | null;
+    /** Renderer hint: try same-frame flush within backend budget; large DOM work may defer. */
+    sync?: boolean;
+    scrollOperations?: readonly TerminalScrollOperation[] | null;
+}>;
+export type TerminalResizeEvent = Readonly<{
+    cols: number;
+    rows: number;
+}>;
+export interface TerminalEventMap {
+    commit: TerminalCommitEvent;
+    resize: TerminalResizeEvent;
+}
+export interface Terminal {
+    resize: (cols: number, rows: number) => void;
+    clear: (x?: number, y?: number, w?: number, h?: number) => void;
+    write: (text: string, opts?: {
+        x?: number;
+        y?: number;
+        style?: Style;
+    }) => void;
+    writeAnsi: (text: string, opts?: {
+        x?: number;
+        y?: number;
+    }) => void;
+    put: (x: number, y: number, ch: string, style?: Style) => void;
+    fill: (x: number, y: number, w: number, h: number, ch?: string, style?: Style) => void;
+    scroll: (lines: number) => void;
+    setCursor: (x: number, y: number, visible?: boolean) => void;
+    batch: <T>(fn: () => T) => T;
+    commit: (meta?: {
+        planes?: TerminalRenderPlanes | null;
+        sync?: boolean;
+    }) => readonly number[] | null;
+    on: <K extends keyof TerminalEventMap>(event: K, cb: (payload: TerminalEventMap[K]) => void) => () => void;
+    dispose: () => void;
+    size: () => TerminalSize;
+    snapshot: () => BufferSnapshot;
+    getCell: (x: number, y: number) => Cell;
+    getRow: (y: number) => readonly Cell[];
+    setScrollbackLimit: (limit: number) => void;
+    getScrollbackLines: (count?: number) => readonly string[];
+    /** Register fingerprint function for SoA pre-computation on the composite buffer. */
+    setFingerprintFn: (fn: (ch: string, style: Style) => number) => void;
+    /** Get pre-computed fingerprints for a composite buffer row (null if not enabled). */
+    getRowFingerprints: (y: number) => Uint32Array | null;
+}