@skaft/hamr 0.4.1

package/node_modules/@hamr/tui/dist/tui.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Minimal TUI implementation with differential rendering
+ */
+import type { Terminal } from "./terminal.ts";
+import { type RgbColor } from "./terminal-colors.ts";
+import { visibleWidth } from "./utils.ts";
+/**
+ * Component interface - all components must implement this
+ */
+export interface Component {
+    /**
+     * Render the component to lines for the given viewport width
+     * @param width - Current viewport width
+     * @returns Array of strings, each representing a line
+     */
+    render(width: number): 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;
+    /**
+     * Invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate(): void;
+}
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+/**
+ * Interface for components that can receive focus and display a hardware 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.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+}
+/** 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;
+    /** If true, don't capture keyboard focus when shown */
+    nonCapturing?: boolean;
+}
+/** Options for {@link OverlayHandle.unfocus}. */
+export interface OverlayUnfocusOptions {
+    /** Explicit target to focus after releasing this overlay. */
+    target: Component | null;
+}
+/**
+ * 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;
+    /** Focus this overlay and bring it to the visual front */
+    focus(): void;
+    /** Release focus to the next visible capturing overlay or previous target, or to an explicit target when provided */
+    unfocus(options?: OverlayUnfocusOptions): void;
+    /** Check if this overlay currently has focus */
+    isFocused(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    children: Component[];
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    terminal: Terminal;
+    private previousLines;
+    private previousKittyImageIds;
+    private previousWidth;
+    private previousHeight;
+    private focusedComponent;
+    private inputListeners;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    private renderRequested;
+    private renderTimer;
+    private lastRenderAt;
+    private static readonly MIN_RENDER_INTERVAL_MS;
+    private cursorRow;
+    private hardwareCursorRow;
+    private showHardwareCursor;
+    private clearOnShrink;
+    private maxLinesRendered;
+    private previousViewportTop;
+    private fullRedrawCount;
+    private stopped;
+    private pendingOsc11BackgroundReplies;
+    private pendingOsc11BackgroundQueries;
+    private focusOrderCounter;
+    private overlayStack;
+    private overlayFocusRestore;
+    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    get fullRedraws(): number;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    /**
+     * Set whether to trigger full re-render when content shrinks.
+     * When true (default), empty rows are cleared when content shrinks.
+     * When false, empty rows remain (reduces redraws on slower terminals).
+     */
+    setClearOnShrink(enabled: boolean): void;
+    setFocus(component: Component | null): void;
+    private setFocusInternal;
+    private clearOverlayFocusRestore;
+    private clearOverlayFocusRestoreFor;
+    private resolveBlockedOverlayFocusResume;
+    private getVisibleOverlayFocusRestore;
+    private isOverlayFocusAncestor;
+    private retargetOverlayPreFocus;
+    private isComponentMounted;
+    private containsComponent;
+    /**
+     * 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;
+    /** Check if an overlay entry is currently visible */
+    private isOverlayVisible;
+    /** Find the visual-frontmost visible capturing overlay, if any */
+    private getTopmostVisibleOverlay;
+    invalidate(): void;
+    start(): void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    private queryCellSize;
+    stop(): void;
+    requestRender(force?: boolean): void;
+    private scheduleRender;
+    private handleInput;
+    private consumeOsc11BackgroundResponse;
+    private consumeCellSizeResponse;
+    /**
+     * Resolve overlay layout from options.
+     * Returns { width, row, col, maxHeight } for rendering.
+     */
+    private resolveOverlayLayout;
+    private resolveAnchorRow;
+    private resolveAnchorCol;
+    /** Composite all overlays into content lines (sorted by focusOrder, higher = on top). */
+    private compositeOverlays;
+    private static readonly SEGMENT_RESET;
+    private applyLineResets;
+    private collectKittyImageIds;
+    private deleteKittyImages;
+    private getKittyImageReservedRows;
+    private expandChangedRangeForKittyImages;
+    private deleteChangedKittyImages;
+    /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
+    private compositeLineAt;
+    /**
+     * Find and extract cursor position from rendered lines.
+     * Searches for CURSOR_MARKER, calculates its position, and strips it from the output.
+     * Only scans the bottom terminal height lines (visible viewport).
+     * @param lines - Rendered lines to search
+     * @param height - Terminal height (visible viewport size)
+     * @returns Cursor position { row, col } or null if no marker found
+     */
+    private extractCursorPosition;
+    private doRender;
+    /**
+     * Position the hardware cursor for IME candidate window.
+     * @param cursorPos The cursor position extracted from rendered output, or null
+     * @param totalLines Total number of rendered lines
+     */
+    private positionHardwareCursor;
+    /**
+     * Query the terminal's default background color with OSC 11 (`ESC ] 11 ; ? BEL`).
+     * @param timeoutMs Query timeout in milliseconds.
+     * @returns Promise containing the parsed RGB color, or undefined if it times out or fails to parse.
+     */
+    queryTerminalBackgroundColor({ timeoutMs }: {
+        timeoutMs: number;
+    }): Promise<RgbColor | undefined>;
+}
+//# sourceMappingURL=tui.d.ts.map

package/node_modules/@hamr/tui/dist/tui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui.d.ts","sourceRoot":"","sources":["../src/tui.ts"],"names":[],"mappings":"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"}