@linxiraos/pi-tui 1.1.0 → 1.1.2

package/dist/types/tui.d.ts

@@ -0,0 +1,332 @@
+import { ImageBudget } from "./components/image.js";
+import { type Terminal } from "./terminal.js";
+import { visibleWidth } from "./utils.js";
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+type StartListener = () => void;
+export interface RenderTimer {
+    cancel(): void;
+}
+export interface RenderScheduler {
+    now(): number;
+    scheduleImmediate(callback: () => void): void;
+    scheduleRender(callback: () => void, delayMs: number): RenderTimer;
+}
+export interface TUIOptions {
+    renderScheduler?: RenderScheduler;
+}
+/** Physical terminal dimensions supplied to a frame provider. */
+export interface ViewportSize {
+    readonly columns: number;
+    readonly rows: number;
+}
+/** Immutable finalized rows offered until the terminal accepts this identifier. */
+export interface HistoryBatch {
+    readonly id: number;
+    readonly rows: readonly string[];
+}
+/** One history append and the complete mutable viewport for a terminal frame. */
+export interface TerminalFramePlan {
+    readonly history?: HistoryBatch;
+    readonly viewport: readonly string[];
+}
+/** Produces bounded terminal frames and retires acknowledged history batches. */
+export interface TerminalFrameProvider {
+    renderFrame(viewport: ViewportSize): TerminalFramePlan;
+    acknowledgeHistory(id: number): void;
+    /** Full semantic viewport used only on the transient resize buffer. */
+    renderResizeFrame?(viewport: ViewportSize): readonly string[];
+    /** Re-offer finalized history after a display reset or resize replay. */
+    resetHistory?(): void;
+}
+export interface TUIStartOptions {
+    /** Clear saved native scrollback before the first paint. */
+    clearScrollback?: boolean;
+    /**
+     * Paint without owning stdin: the terminal stays in cooked mode (kernel
+     * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
+     * switches to raw input and replays the kernel-buffered keystrokes.
+     */
+    deferInput?: boolean;
+}
+/**
+ * Component interface - all components must implement this
+ *
+ * Render contract: the returned array (and its rows) belongs to the component.
+ * Callers MUST NOT mutate it — components are allowed to return a cached array
+ * and will return the exact same reference for as long as their rendered
+ * content is unchanged. Conversely, a component MUST return a fresh array
+ * reference whenever its content changed; reference equality across two
+ * render() calls is the engine's proof that the rows are byte-identical
+ * (containers memoize their concatenation on it, and the TUI derives the
+ * frame's stable prefix from it). A component that mutates a previously
+ * returned array in place must implement {@link RenderStablePrefix} to declare
+ * which leading rows survived.
+ */
+export interface Component {
+    /**
+     * Render the component to an array of physical rows at the given width.
+     * The result is component-owned and `readonly` to the caller; an unchanged
+     * component may (and should) return the same array reference it returned
+     * last time.
+     */
+    render(width: number): readonly string[];
+    /**
+     * Optional handler for keyboard input when component has focus
+     */
+    handleInput?(data: string): void;
+    /**
+     * If true, component receives key release events (Kitty protocol).
+     * Default is false - release events are filtered out.
+     */
+    wantsKeyRelease?: boolean;
+    /**
+     * Optional hook to invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate?(): void;
+    /**
+     * Optional hook to set whether this component ignores tight layout mode.
+     */
+    setIgnoreTight?(ignore: boolean): any;
+    /**
+     * Optional teardown. Called when the component is permanently removed from
+     * the live tree (e.g. a transcript reset). Release timers, intervals, and
+     * subscriptions here. Must be idempotent. Containers propagate dispose to
+     * their children; leaf components without resources may omit it.
+     */
+    dispose?(): void;
+}
+/** Lets an overlay root delegate keyboard focus to components it owns. */
+export interface OverlayFocusOwner {
+    /** Returns true when `component` is a focus target inside this overlay. */
+    ownsOverlayFocusTarget(component: Component): boolean;
+}
+/**
+ * Interface for components that can receive focus and display a cursor.
+ * When focused, the component should emit CURSOR_MARKER at the cursor position
+ * in its render output. TUI will find this marker and position the hardware
+ * cursor there for proper IME candidate window positioning.
+ *
+ * Components that can switch between terminal-cursor and software-cursor
+ * rendering expose `setUseTerminalCursor`; TUI keeps that mode in sync with
+ * its resolved hardware-cursor preference whenever focus or the preference
+ * changes.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+    /** Set by TUI when hardware cursor rendering is enabled or disabled. */
+    setUseTerminalCursor?(useTerminalCursor: boolean): void;
+}
+/** Options for scheduling a TUI render. */
+export interface RenderRequestOptions {
+    /** Clear terminal scrollback for intentional transcript replacement. */
+    clearScrollback?: boolean;
+}
+/**
+ * Controls how a settled terminal resize refreshes native history.
+ *
+ * `append` replays the current transcript below retained history, `rebuild`
+ * clears history before replaying it, and `preserve` repaints only the viewport.
+ */
+export type ResizeScrollbackMode = "append" | "rebuild" | "preserve";
+/** Type guard to check if a component implements Focusable */
+export declare function isFocusable(component: Component | null): component is Component & Focusable;
+/**
+ * Cursor position marker - APC (Application Program Command) sequence.
+ * This is a zero-width escape sequence that terminals ignore.
+ * Components emit this at the cursor position when focused.
+ * TUI finds and strips this marker, then positions the hardware cursor there.
+ */
+export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+export { visibleWidth };
+/**
+ * Anchor position for overlays
+ */
+export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Margin configuration for overlays
+ */
+export interface OverlayMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Value that can be absolute (number) or percentage (string like "50%") */
+export type SizeValue = number | `${number}%`;
+/**
+ * Options for overlay positioning and sizing.
+ * Values can be absolute numbers or percentage strings (e.g., "50%").
+ */
+export interface OverlayOptions {
+    /** Width in columns, or percentage of terminal width (e.g., "50%") */
+    width?: SizeValue;
+    /** Minimum width in columns */
+    minWidth?: number;
+    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
+    maxHeight?: SizeValue;
+    /** Anchor point for positioning (default: 'center') */
+    anchor?: OverlayAnchor;
+    /** Horizontal offset from anchor position (positive = right) */
+    offsetX?: number;
+    /** Vertical offset from anchor position (positive = down) */
+    offsetY?: number;
+    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
+    row?: SizeValue;
+    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
+    col?: SizeValue;
+    /** Margin from terminal edges. Number applies to all sides. */
+    margin?: OverlayMargin | number;
+    /**
+     * Control overlay visibility based on terminal dimensions.
+     * If provided, overlay is only rendered when this returns true.
+     * Called each render cycle with current terminal dimensions.
+     */
+    visible?: (termWidth: number, termHeight: number) => boolean;
+    /**
+     * Borrow the terminal's alternate screen buffer for this overlay's lifetime
+     * (vim/less idiom). While the topmost visible overlay sets this, the engine
+     * paints only the modal on the alt screen and emits no ED3 / scrollback
+     * bytes, so the transcript on the normal screen stays untouched and is not
+     * scrollable behind the modal. Defaults off — all other overlays are
+     * unchanged and still draw over the transcript on the normal screen.
+     */
+    fullscreen?: boolean;
+    /**
+     * Enable terminal mouse reporting while fullscreen. Defaults on; disable it
+     * when native terminal text selection takes precedence over pointer events.
+     */
+    mouseTracking?: boolean;
+}
+/**
+ * Handle returned by showOverlay for controlling the overlay
+ */
+export interface OverlayHandle {
+    /** Permanently remove the overlay (cannot be shown again) */
+    hide(): void;
+    /** Temporarily hide or show the overlay */
+    setHidden(hidden: boolean): void;
+    /** Check if overlay is temporarily hidden */
+    isHidden(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    #private;
+    children: Component[];
+    setIgnoreTight(ignore: boolean): this;
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    /** Dispose every child, then detach it from this container. */
+    disposeChildren(): void;
+    invalidate(): void;
+    /**
+     * Propagate teardown to children. Call when the container's children are
+     * being permanently discarded (not when they are detached for reuse — use
+     * {@link clear} for that). Idempotent per child via each child's own dispose.
+     */
+    dispose(): void;
+    render(width: number): readonly string[];
+}
+/**
+ * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
+ * CSI-SGR sequences are touched; text, cursor moves, OSC, hyperlinks and image
+ * payloads pass through verbatim. Returns the original reference when nothing
+ * merges, so SGR-light lines incur only a single `indexOf` scan.
+ */
+export declare function coalesceAdjacentSgr(line: string): string;
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    #private;
+    terminal: Terminal;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    overlayStack: {
+        component: Component;
+        options?: OverlayOptions;
+        preFocus: Component | null;
+        hidden: boolean;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
+    /** Install the product-owned bounded frame provider. */
+    setFrameProvider(provider: TerminalFrameProvider | undefined): void;
+    get fullRedraws(): number;
+    /** Shared budget that caps how many inline images render as live graphics. */
+    get imageBudget(): ImageBudget;
+    /**
+     * Set how many inline images stay live graphics before older ones fall back
+     * to text (`0` disables the cap). Older images are hidden via a graphics purge
+     * plus a full redraw on the frame after a new image exceeds the cap.
+     */
+    setMaxInlineImages(cap: number): void;
+    /** Return how settled resizes refresh native scrollback. */
+    getResizeScrollback(): ResizeScrollbackMode;
+    /** Set how settled resizes refresh native scrollback. */
+    setResizeScrollback(mode: ResizeScrollbackMode): void;
+    /** Delete every tracked Kitty image from the terminal graphics store. */
+    clearInlineImages(): void;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    /**
+     * Whether DEC 2026 synchronized-output wrappers are currently emitted around
+     * paints. Starts from conservative terminal/env detection and is reconciled at
+     * runtime against the terminal's DECRQM mode-2026 report — enabled on a
+     * positive report, disabled on a negative one.
+     */
+    get synchronizedOutput(): boolean;
+    setFocus(component: Component | null): void;
+    /** Component currently receiving keyboard input, if any. */
+    getFocused(): Component | null;
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay(): void;
+    /** Check if there are any visible overlays */
+    hasOverlay(): boolean;
+    invalidate(): void;
+    start(options?: TUIStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: raw mode, input
+     * handlers, and the response-eliciting capability probes start() skipped.
+     * Keystrokes typed in cooked mode meanwhile arrive through the normal input
+     * path. Idempotent; no-op when input was never deferred.
+     */
+    enableInput(): void;
+    addStartListener(listener: StartListener): () => void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    stop(): void;
+    /**
+     * Destructive user-gesture reset: invalidate every component, erase native
+     * history, then repaint from row zero. Reachable only from explicit gestures (session
+     * replace, /tree, an explicit clear) — never from ordinary rendering,
+     * animation, resize, or finalization.
+     */
+    resetDisplay(): void;
+    requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /**
+     * Paint a forced frame synchronously when startup must hand off an already
+     * visible component tree before further async initialization. Same as
+     * {@link requestRender} minus the `setImmediate` hop.
+     */
+    renderNow(options?: RenderRequestOptions): void;
+    /**
+     * Schedule a render on behalf of `component` after a self-contained change
+     * (spinner frame, blink). Frames always compose the bounded viewport from
+     * scratch — retired blocks no longer render — so a scoped request is simply
+     * an ordinary render.
+     */
+    requestComponentRender(_component: Component): void;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,112 @@
+import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@linxiraos/pi-natives";
+export { Ellipsis } from "@linxiraos/pi-natives";
+export { DEFAULT_TAB_WIDTH } from "@linxiraos/pi-utils";
+export type HangulCompatibilityJamoWidth = "platform" | "unicode" | 1 | 2;
+export declare function getHangulCompatibilityJamoWidth(): HangulCompatibilityJamoWidth;
+export declare function getWidthConfigEpoch(): number;
+/** Publish exact per-line visible widths for a rendered lines array. */
+export declare function publishLineWidths(lines: readonly string[], widths: readonly number[]): void;
+/** Exact per-line visible widths for an unchanged `lines` array under the current width config. */
+export declare function getPublishedLineWidths(lines: readonly string[]): readonly number[] | undefined;
+export declare function setHangulCompatibilityJamoWidth(width: HangulCompatibilityJamoWidth): boolean;
+export declare function resetHangulCompatibilityJamoWidthForTests(): void;
+export type TextSizingScale = 1 | 2 | 3;
+export type TextSizingVerticalAlign = "top" | "bottom" | "center";
+export type TextSizingHorizontalAlign = "left" | "right" | "center";
+export interface TextSizingOptions {
+    scale?: TextSizingScale;
+    widthCells?: number;
+    verticalAlign?: TextSizingVerticalAlign;
+    horizontalAlign?: TextSizingHorizontalAlign;
+}
+/**
+ * Encode a plain-text span using Kitty's OSC 66 text-sizing protocol. The TUI
+ * emits only safe UTF-8 payloads and ST terminators so its ANSI parser and the
+ * terminal agree on span boundaries.
+ */
+export declare function encodeTextSized(text: string, options?: TextSizingOptions): string;
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null | "", pad?: boolean | null): string;
+export declare function wrapTextWithAnsi(text: string, width: number): string[];
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;
+export declare function replaceTabs(text: string): string;
+/**
+ * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
+ */
+export declare function padding(n: number): string;
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getSegmenter(): Intl.Segmenter;
+/**
+ * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
+ *
+ * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
+ * stripping); this adds the corrections it omits — tabs (expanded to
+ * `tabWidth` cells), OSC 66 text-sizing payloads (scaled by `s=`), and APC
+ * sequences (counted as printable by Bun, actually zero cells).
+ */
+export declare function visibleWidth(str: string): number;
+/**
+ * Scaled spans must bypass wrapping/padding and, when scaled up, reserve the
+ * terminal rows their multicell glyphs flow into.
+ */
+export declare function isOsc66Line(line: string): boolean;
+/**
+ * Largest `s=` scale among the OSC 66 spans in a line (1 when none is scaled).
+ * A scale-`s` heading occupies `s` terminal rows, so the `s - 1` blank rows
+ * beneath it are the glyph's lower half and must never be erased or overdrawn.
+ */
+export declare function osc66MaxScale(line: string): number;
+/**
+ * Normalize text for terminal output without changing logical editor content.
+ * Some terminals render precomposed Thai/Lao AM vowels inconsistently during
+ * differential repaint. Their compatibility decompositions have the same cell
+ * width but avoid stale-cell artifacts in terminal renderers.
+ */
+export declare function normalizeTerminalOutput(str: string): string;
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Check if a character is punctuation.
+ */
+export declare function isPunctuationChar(char: string): boolean;
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export declare function getWordNavKind(grapheme: string): WordNavKind;
+export declare function isWordNavJoiner(grapheme: string): boolean;
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordLeft(text: string, cursor: number): number;
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordRight(text: string, cursor: number): number;
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;
+export declare function setTuiTight(tight: boolean): void;
+export declare function isTuiTight(): boolean;
+export declare function getPaddingX(basePadding: number): number;

package/package.json

@@ -1,69 +1,72 @@
 {
-  "type": "module",
-  "name": "@linxiraos/pi-tui",
-  "version": "1.1.0",
-  "description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-  "homepage": "https://omp.sh",
-  "author": "Stencil Labs, Inc.",
-  "contributors": [
-    "Mario Zechner"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/can1357/oh-my-pi.git",
-    "directory": "packages/tui"
-  },
-  "bugs": {
-    "url": "https://github.com/can1357/oh-my-pi/issues"
-  },
-  "keywords": [
-    "tui",
-    "terminal",
-    "ui",
-    "text-editor",
-    "differential-rendering",
-    "typescript",
-    "cli"
-  ],
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "scripts": {
-    "check": "biome check . && bun run check:types",
-    "check:types": "tsgo -p tsconfig.json --noEmit",
-    "lint": "biome lint .",
-    "test": "bun test --parallel test/*.test.ts",
-    "fix": "biome check --write --unsafe .",
-    "fmt": "biome format --write ."
-  },
-  "dependencies": {
-    "@linxiraos/pi-natives": "catalog:",
-    "@linxiraos/pi-utils": "catalog:"
-  },
-  "devDependencies": {
-    "kitty-vt-wasm": "catalog:"
-  },
-  "engines": {
-    "bun": ">=1.3.14"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
-    },
-    "./*": {
-      "types": "./src/*.ts",
-      "import": "./src/*.ts"
-    },
-    "./components/*": {
-      "types": "./src/components/*.ts",
-      "import": "./src/components/*.ts"
-    },
-    "./*.js": "./src/*.ts"
-  }
-}
+	"type": "module",
+	"name": "@linxiraos/pi-tui",
+	"version": "1.1.2",
+	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
+	"homepage": "https://linxira-os.github.io/zeta/",
+	"author": "Stencil Labs, Inc.",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"directory": "packages/tui"
+	},
+	"bugs": {
+		"url": "https://github.com/Linxira-OS/linxira-zeta/issues"
+	},
+	"keywords": [
+		"tui",
+		"terminal",
+		"ui",
+		"text-editor",
+		"differential-rendering",
+		"typescript",
+		"cli"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel test/*.test.ts",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@linxiraos/pi-natives": "1.1.2",
+		"@linxiraos/pi-utils": "1.1.2"
+	},
+	"devDependencies": {
+		"kitty-vt-wasm": "^0.2.0"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD-PARTY-NOTICES.txt",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./components/*": {
+			"types": "./dist/types/components/*.d.ts",
+			"import": "./src/components/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}