agent-sh 0.6.0 → 0.7.0

package/dist/utils/floating-panel.d.ts

@@ -0,0 +1,198 @@
+import { TerminalBuffer } from "./terminal-buffer.js";
+import { HandlerRegistry } from "./handler-registry.js";
+import type { EventBus } from "../event-bus.js";
+import type { BorderStyle } from "./box-frame.js";
+export interface FloatingPanelConfig {
+    /** Key sequence that toggles the panel (e.g. "\x1c" for Ctrl+\). */
+    trigger: string;
+    /** Panel width. Number = columns, string with % = percentage. Default: "80%". */
+    width?: number | string;
+    /** Max width in columns. Default: 100. */
+    maxWidth?: number;
+    /** Panel height. Number = rows, string with % = percentage. Default: "60%". */
+    height?: number | string;
+    /** Min content rows inside the panel. Default: 6. */
+    minHeight?: number;
+    /** Border style. Default: "rounded". */
+    borderStyle?: BorderStyle;
+    /**
+     * Show dimmed terminal content behind the panel. Default: true.
+     * Requires @xterm/headless — falls back to blank background if unavailable.
+     */
+    dimBackground?: boolean;
+    /** Auto-dismiss delay in ms when done (0 = disabled). Default: 0. */
+    autoDismissMs?: number;
+    /** Icon shown before the input cursor. Default: "\u276f". */
+    promptIcon?: string;
+    /**
+     * Pre-existing TerminalBuffer to reuse. If provided, the panel will
+     * not create its own headless terminal. Useful when sharing a buffer
+     * with other features (e.g. context injection, terminal_read tool).
+     */
+    terminalBuffer?: TerminalBuffer;
+    /**
+     * Handler namespace prefix. Default: "panel".
+     * All handlers are registered as `{prefix}:render-content`,
+     * `{prefix}:submit`, etc. Use different prefixes for multiple panels.
+     */
+    handlerPrefix?: string;
+}
+/**
+ * Context passed to the render-content handler.
+ */
+export interface RenderContext {
+    /** Available width for content (inside box, excluding borders and padding). */
+    width: number;
+    /** Available height for content (rows inside box). */
+    height: number;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current input buffer text (during input phase). */
+    inputBuffer: string;
+    /** Current input cursor position (during input phase). */
+    inputCursor: number;
+    /** Current scroll offset. */
+    scrollOffset: number;
+    /** Built-in content lines (from appendText/appendLine). */
+    contentLines: readonly string[];
+    /** Current partial line being streamed. */
+    partialLine: string;
+}
+/**
+ * Result from render-content handler.
+ */
+export interface RenderResult {
+    lines: string[];
+    /** Optional cursor position within the content area. */
+    cursor?: {
+        row: number;
+        col: number;
+    };
+}
+/**
+ * Box geometry computed from config + terminal size.
+ */
+export interface BoxGeometry {
+    /** Terminal columns. */
+    cols: number;
+    /** Terminal rows. */
+    rows: number;
+    /** Box width in columns (including borders). */
+    boxW: number;
+    /** Box height in rows (including borders). */
+    boxH: number;
+    /** Box top offset (0-indexed row). */
+    boxTop: number;
+    /** Box left offset (0-indexed column). */
+    boxLeft: number;
+    /** Usable content width inside box. */
+    contentW: number;
+    /** Usable content height inside box. */
+    contentH: number;
+}
+/**
+ * Context passed to the render-frame handler.
+ */
+export interface FrameContext {
+    /** Box geometry. */
+    geo: BoxGeometry;
+    /** Content render result (from render-content handler). */
+    content: RenderResult;
+    /** Background lines from the terminal buffer (null if no dimming). */
+    bgLines: string[] | null;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current title text. */
+    title: string;
+    /** Current footer text. */
+    footer: string;
+    /** Border characters for the configured border style. */
+    border: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+}
+/**
+ * Result from render-frame handler.
+ */
+export interface FrameResult {
+    /** One string per terminal row. */
+    rows: string[];
+    /** ANSI sequence to position the cursor (empty string if no cursor). */
+    cursorSeq: string;
+}
+export type Phase = "idle" | "input" | "active" | "done";
+export declare class FloatingPanel {
+    private readonly config;
+    private readonly bus;
+    private readonly border;
+    private readonly externalBuffer;
+    private readonly prefix;
+    /**
+     * Handler registry for this panel. Extensions use `handlers.advise()`
+     * to customize rendering and behavior.
+     *
+     * Registered handlers:
+     *   - `{prefix}:render-content(ctx: RenderContext) -> RenderResult`
+     *   - `{prefix}:render-frame(ctx: FrameContext) -> FrameResult`
+     *   - `{prefix}:render-border-top(ctx: FrameContext) -> string`
+     *   - `{prefix}:render-border-bottom(ctx: FrameContext) -> string`
+     *   - `{prefix}:composite-row(content: string, bgLine: string|null, boxLeft: number, boxW: number, cols: number) -> string`
+     *   - `{prefix}:submit(query: string) -> void`
+     *   - `{prefix}:dismiss() -> void`
+     *   - `{prefix}:input(data: string) -> boolean`
+     *   - `{prefix}:build-row(content: string, width: number) -> string`
+     */
+    readonly handlers: HandlerRegistry;
+    private buffer;
+    private bufferInitialized;
+    /** All byte sequences that should be recognized as the trigger key. */
+    private readonly triggerSeqs;
+    private phase;
+    private editor;
+    private contentLines;
+    private currentPartialLine;
+    private scrollOffset;
+    private title;
+    private footer;
+    private renderTimer;
+    private autoDismissTimer;
+    private resizeHandler;
+    private prevFrame;
+    private suppressNextRedraw;
+    private ptyBuffer;
+    private usedAltScreen;
+    constructor(bus: EventBus, config: FloatingPanelConfig, handlers?: HandlerRegistry);
+    private registerDefaultHandlers;
+    private wireEvents;
+    /** Check whether data matches any encoding of the trigger key. */
+    private isTrigger;
+    private ensureBuffer;
+    get active(): boolean;
+    get terminalBuffer(): TerminalBuffer | null;
+    open(): void;
+    dismiss(): void;
+    appendText(text: string): void;
+    appendLine(line: string): void;
+    updateLastLine(fn: (line: string) => string): void;
+    clearContent(): void;
+    setTitle(title: string): void;
+    setFooter(footer: string): void;
+    setActive(): void;
+    setDone(): void;
+    getInput(): string;
+    requestRender(): void;
+    private handleIntercept;
+    private handleInputKey;
+    /** Compute box geometry from config + current terminal size. */
+    computeGeometry(): BoxGeometry;
+    private buildFrame;
+    private scheduleRender;
+    private render;
+    private restoreScreen;
+    private resolveSize;
+}