@profullstack/hqtui 0.1.0

package/dist/surface.js

@@ -0,0 +1,181 @@
+import { FrameBuffer } from "./buffer.js";
+import { DEFAULT_COLOR } from "./color.js";
+import { inset, intersect, isEmpty } from "./layout.js";
+import { graphemes, stringWidth, truncate, fit } from "./unicode.js";
+export const BORDERS = {
+    rounded: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", ml: "├", mr: "┤", mt: "┬", mb: "┴", cross: "┼" },
+    single: { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│", ml: "├", mr: "┤", mt: "┬", mb: "┴", cross: "┼" },
+    double: { tl: "╔", tr: "╗", bl: "╚", br: "╝", h: "═", v: "║", ml: "╠", mr: "╣", mt: "╦", mb: "╩", cross: "╬" },
+    thick: { tl: "┏", tr: "┓", bl: "┗", br: "┛", h: "━", v: "┃", ml: "┣", mr: "┫", mt: "┳", mb: "┻", cross: "╋" },
+    dashed: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "╌", v: "╎", ml: "├", mr: "┤", mt: "┬", mb: "┴", cross: "┼" },
+    ascii: { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|", ml: "+", mr: "+", mt: "+", mb: "+", cross: "+" },
+};
+/**
+ * A clipped, translated view onto the framebuffer. Widgets only ever see a
+ * Surface, so nothing can draw outside the rectangle it was given.
+ */
+export class Surface {
+    buffer;
+    rect;
+    clip;
+    theme;
+    constructor(buffer, rect, theme, clip) {
+        this.buffer = buffer;
+        this.rect = rect;
+        this.theme = theme;
+        this.clip = clip ? intersect(rect, clip) : rect;
+    }
+    get width() {
+        return this.rect.width;
+    }
+    get height() {
+        return this.rect.height;
+    }
+    get empty() {
+        return isEmpty(this.rect);
+    }
+    /** A child surface in local coordinates, clipped to this one. */
+    sub(x, y, width, height) {
+        const abs = { x: this.rect.x + x, y: this.rect.y + y, width, height };
+        return new Surface(this.buffer, abs, this.theme, this.clip);
+    }
+    /** A child surface from an absolute rect (as produced by the layout solver). */
+    region(rect, clipToParent = true) {
+        return new Surface(this.buffer, rect, this.theme, clipToParent ? this.clip : undefined);
+    }
+    inset(padding) {
+        return this.region(inset(this.rect, padding));
+    }
+    visible(absX, absY) {
+        const c = this.clip;
+        return absX >= c.x && absY >= c.y && absX < c.x + c.width && absY < c.y + c.height;
+    }
+    char(x, y, value, style) {
+        const ax = this.rect.x + x;
+        const ay = this.rect.y + y;
+        if (!this.visible(ax, ay))
+            return;
+        const v = typeof value === "string" ? (value.codePointAt(0) ?? 32) : value;
+        this.buffer.setCell(ax, ay, v, style);
+    }
+    /** Draw text at local (x, y). Returns columns written. */
+    text(x, y, text, options = {}) {
+        const ay = this.rect.y + y;
+        const c = this.clip;
+        if (ay < c.y || ay >= c.y + c.height)
+            return 0;
+        const limit = Math.min(options.maxWidth ?? this.width - x, this.width - x);
+        if (limit <= 0)
+            return 0;
+        let content = text;
+        if (options.ellipsis !== false && stringWidth(content) > limit) {
+            content = truncate(content, limit);
+        }
+        if (options.align && options.align !== "left") {
+            content = fit(content, limit, options.align);
+        }
+        const style = { fg: options.fg, bg: options.bg, attrs: options.attrs };
+        let cx = this.rect.x + x;
+        let written = 0;
+        for (const g of graphemes(content)) {
+            if (written + g.width > limit)
+                break;
+            if (cx >= c.x && cx + g.width <= c.x + c.width) {
+                this.buffer.setCell(cx, ay, g.value, style);
+            }
+            cx += g.width;
+            written += g.width;
+        }
+        return written;
+    }
+    /** Text positioned within the full surface width. */
+    textAligned(y, text, align, options = {}) {
+        this.text(0, y, fit(truncate(text, this.width), this.width, align), { ...options, align: "left" });
+    }
+    fill(style, ch = 32) {
+        this.fillRect(0, 0, this.width, this.height, style, ch);
+    }
+    fillRect(x, y, w, h, style, ch = 32) {
+        const abs = intersect({ x: this.rect.x + x, y: this.rect.y + y, width: w, height: h }, this.clip);
+        if (isEmpty(abs))
+            return;
+        this.buffer.fillRect(abs.x, abs.y, abs.width, abs.height, ch, style);
+    }
+    styleRect(x, y, w, h, style) {
+        const abs = intersect({ x: this.rect.x + x, y: this.rect.y + y, width: w, height: h }, this.clip);
+        if (isEmpty(abs))
+            return;
+        this.buffer.styleRect(abs.x, abs.y, abs.width, abs.height, style);
+    }
+    hline(x, y, length, ch = "─", style) {
+        for (let i = 0; i < length; i++)
+            this.char(x + i, y, ch, style);
+    }
+    vline(x, y, length, ch = "│", style) {
+        for (let i = 0; i < length; i++)
+            this.char(x, y + i, ch, style);
+    }
+    /**
+     * Draw a bordered box with an optional title, and return the interior surface.
+     * This is the workhorse behind every panel in the library.
+     */
+    box(options = {}) {
+        const style = options.border ?? "rounded";
+        const fg = options.borderColor ?? this.theme.border;
+        const bg = options.bg;
+        if (options.fill !== false && bg !== undefined) {
+            this.fill({ bg });
+        }
+        if (style === "none" || this.width < 2 || this.height < 1) {
+            return this.inset(style === "none" ? 0 : 1);
+        }
+        const b = BORDERS[style];
+        const w = this.width;
+        const h = this.height;
+        const borderStyle = { fg, bg };
+        this.char(0, 0, b.tl, borderStyle);
+        this.char(w - 1, 0, b.tr, borderStyle);
+        this.hline(1, 0, w - 2, b.h, borderStyle);
+        if (h > 1) {
+            this.char(0, h - 1, b.bl, borderStyle);
+            this.char(w - 1, h - 1, b.br, borderStyle);
+            this.hline(1, h - 1, w - 2, b.h, borderStyle);
+            this.vline(0, 1, h - 2, b.v, borderStyle);
+            this.vline(w - 1, 1, h - 2, b.v, borderStyle);
+        }
+        if (options.title) {
+            const titleColor = options.titleColor ?? this.theme.title;
+            const label = ` ${options.title} `;
+            const maxLabel = Math.max(0, w - 4);
+            const shown = truncate(label, maxLabel);
+            const tw = stringWidth(shown);
+            const align = options.titleAlign ?? "left";
+            const tx = align === "left" ? 2 : align === "right" ? Math.max(2, w - 2 - tw) : Math.max(2, Math.floor((w - tw) / 2));
+            this.text(tx, 0, shown, { fg: titleColor, bg, attrs: 1 /* bold */ });
+        }
+        if (options.subtitle) {
+            const sub = ` ${options.subtitle} `;
+            const sw = stringWidth(sub);
+            if (sw + 4 < w) {
+                this.text(w - 2 - sw, 0, sub, { fg: options.subtitleColor ?? this.theme.muted, bg });
+            }
+        }
+        if (options.footer && h > 2) {
+            const foot = ` ${options.footer} `;
+            const fw = stringWidth(foot);
+            if (fw + 4 < w) {
+                this.text(2, h - 1, foot, { fg: options.footerColor ?? this.theme.muted, bg });
+            }
+        }
+        return this.sub(1, 1, Math.max(0, w - 2), Math.max(0, h - 2));
+    }
+    /** Absolute rect of this surface, for hit-testing mouse events. */
+    hitRect() {
+        return { ...this.rect };
+    }
+}
+export function createSurface(buffer, theme, rect) {
+    return new Surface(buffer, rect ?? { x: 0, y: 0, width: buffer.width, height: buffer.height }, theme);
+}
+export { DEFAULT_COLOR };
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

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

package/dist/terminal.d.ts

@@ -0,0 +1,63 @@
+import { type Capabilities, type CapabilityOverrides } from "./capabilities.ts";
+import { type InputEvent } from "./input.ts";
+export interface TerminalOptions {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WriteStream;
+    /** Use the alternate screen so the user's scrollback survives. Default true. */
+    alternateScreen?: boolean;
+    mouse?: boolean;
+    hideCursor?: boolean;
+    bracketedPaste?: boolean;
+    focusEvents?: boolean;
+    title?: string;
+    capabilities?: CapabilityOverrides;
+    /** Restore the terminal on SIGINT/SIGTERM/uncaught errors. Default true. */
+    installExitHandlers?: boolean;
+    /** How long to wait before a lone ESC counts as the Escape key. Default 30ms. */
+    escapeTimeout?: number;
+}
+export interface TerminalSize {
+    columns: number;
+    rows: number;
+}
+type Listener<T> = (value: T) => void;
+/**
+ * Owns the TTY: raw mode, alternate screen, mouse reporting, and — above all —
+ * putting everything back. A crashed app must never leave an unusable shell.
+ */
+export declare class Terminal {
+    readonly input: NodeJS.ReadStream;
+    readonly output: NodeJS.WriteStream;
+    readonly capabilities: Capabilities;
+    private options;
+    private parser;
+    private entered;
+    /** Milliseconds to wait before deciding a lone ESC was the Escape key. */
+    readonly escapeTimeout: number;
+    private rawWasSet;
+    private inputListeners;
+    private resizeListeners;
+    private cleanupHandlers;
+    private escapeTimer;
+    private onData;
+    private dispatch;
+    private onResize;
+    constructor(options?: TerminalOptions);
+    size(): TerminalSize;
+    write(data: string): void;
+    /** Enter full-screen mode. Idempotent. */
+    enter(): void;
+    /** Put the terminal back exactly as it was found. Safe to call twice. */
+    restore(): void;
+    onInput(listener: Listener<InputEvent>): () => void;
+    onResizeEvent(listener: Listener<TerminalSize>): () => void;
+    private installExitHandlers;
+}
+export declare function createTerminal(options?: TerminalOptions): Terminal;
+/**
+ * Last-resort cleanup for a process that lost its Terminal reference.
+ * Safe to call from a signal handler or a REPL after a bad crash.
+ */
+export declare function emergencyRestore(output?: NodeJS.WriteStream): void;
+export {};
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAsB,MAAM,mBAAmB,CAAC;AACpG,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,gFAAgF;IAChF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEtC;;;GAGG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,OAAO,CAAC,OAAO,CAAwH;IACvI,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAmC;IACzD,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAaZ;IAEF,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,QAAQ,CAGd;gBAEU,OAAO,GAAE,eAAoB;IAgBzC,IAAI,IAAI,YAAY;IAOpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB,0CAA0C;IAC1C,KAAK,IAAI,IAAI;IA0Bb,yEAAyE;IACzE,OAAO,IAAI,IAAI;IA0Bf,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,IAAI;IAKnD,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,MAAM,IAAI;IAK3D,OAAO,CAAC,mBAAmB;CAmC5B;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAEtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,MAAM,CAAC,WAA4B,GAAG,IAAI,CAQlF"}

package/dist/terminal.js

@@ -0,0 +1,189 @@
+import { ansi, setTitle } from "./ansi.js";
+import { detectCapabilities } from "./capabilities.js";
+import { InputParser } from "./input.js";
+/**
+ * Owns the TTY: raw mode, alternate screen, mouse reporting, and — above all —
+ * putting everything back. A crashed app must never leave an unusable shell.
+ */
+export class Terminal {
+    input;
+    output;
+    capabilities;
+    options;
+    parser = new InputParser();
+    entered = false;
+    /** Milliseconds to wait before deciding a lone ESC was the Escape key. */
+    escapeTimeout;
+    rawWasSet = false;
+    inputListeners = new Set();
+    resizeListeners = new Set();
+    cleanupHandlers = [];
+    escapeTimer = null;
+    onData = (chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        this.dispatch(this.parser.parse(text));
+        // A lone ESC is only the Escape key once nothing follows it.
+        if (this.escapeTimer)
+            clearTimeout(this.escapeTimer);
+        this.escapeTimer = null;
+        if (this.parser.hasPending) {
+            this.escapeTimer = setTimeout(() => {
+                this.escapeTimer = null;
+                this.dispatch(this.parser.flush());
+            }, this.escapeTimeout);
+            this.escapeTimer.unref?.();
+        }
+    };
+    dispatch(events) {
+        for (const event of events) {
+            for (const listener of this.inputListeners)
+                listener(event);
+        }
+    }
+    onResize = () => {
+        const size = this.size();
+        for (const listener of this.resizeListeners)
+            listener(size);
+    };
+    constructor(options = {}) {
+        this.input = options.input ?? process.stdin;
+        this.output = options.output ?? process.stdout;
+        this.capabilities = detectCapabilities(options.capabilities ?? {}, process.env, this.output);
+        this.escapeTimeout = options.escapeTimeout ?? 30;
+        this.options = {
+            alternateScreen: options.alternateScreen ?? true,
+            mouse: options.mouse ?? this.capabilities.mouse,
+            hideCursor: options.hideCursor ?? true,
+            bracketedPaste: options.bracketedPaste ?? this.capabilities.bracketedPaste,
+            focusEvents: options.focusEvents ?? this.capabilities.focusEvents,
+            installExitHandlers: options.installExitHandlers ?? true,
+            title: options.title,
+        };
+    }
+    size() {
+        return {
+            columns: this.output.columns ?? 80,
+            rows: this.output.rows ?? 24,
+        };
+    }
+    write(data) {
+        if (data.length === 0)
+            return;
+        this.output.write(data);
+    }
+    /** Enter full-screen mode. Idempotent. */
+    enter() {
+        if (this.entered)
+            return;
+        this.entered = true;
+        let setup = "";
+        if (this.options.alternateScreen)
+            setup += ansi.alternateScreenOn;
+        if (this.options.hideCursor)
+            setup += ansi.cursorHide;
+        if (this.options.mouse && this.capabilities.mouse)
+            setup += ansi.mouseOn;
+        if (this.options.bracketedPaste)
+            setup += ansi.bracketedPasteOn;
+        if (this.options.focusEvents)
+            setup += ansi.focusOn;
+        if (this.options.title)
+            setup += setTitle(this.options.title);
+        setup += ansi.clearScreen + ansi.cursorHome;
+        this.write(setup);
+        if (this.input.isTTY && typeof this.input.setRawMode === "function") {
+            this.input.setRawMode(true);
+            this.rawWasSet = true;
+        }
+        this.input.resume?.();
+        this.input.setEncoding?.("utf8");
+        this.input.on("data", this.onData);
+        this.output.on("resize", this.onResize);
+        if (this.options.installExitHandlers)
+            this.installExitHandlers();
+    }
+    /** Put the terminal back exactly as it was found. Safe to call twice. */
+    restore() {
+        if (!this.entered)
+            return;
+        this.entered = false;
+        if (this.escapeTimer)
+            clearTimeout(this.escapeTimer);
+        this.escapeTimer = null;
+        this.input.off?.("data", this.onData);
+        this.output.off?.("resize", this.onResize);
+        if (this.rawWasSet && typeof this.input.setRawMode === "function") {
+            this.input.setRawMode(false);
+            this.rawWasSet = false;
+        }
+        this.input.pause?.();
+        let teardown = ansi.reset;
+        if (this.options.focusEvents)
+            teardown += ansi.focusOff;
+        if (this.options.bracketedPaste)
+            teardown += ansi.bracketedPasteOff;
+        if (this.options.mouse)
+            teardown += ansi.mouseOff;
+        if (this.options.hideCursor)
+            teardown += ansi.cursorShow;
+        teardown += this.options.alternateScreen ? ansi.alternateScreenOff : `\n`;
+        this.write(teardown);
+        for (const off of this.cleanupHandlers)
+            off();
+        this.cleanupHandlers = [];
+    }
+    onInput(listener) {
+        this.inputListeners.add(listener);
+        return () => this.inputListeners.delete(listener);
+    }
+    onResizeEvent(listener) {
+        this.resizeListeners.add(listener);
+        return () => this.resizeListeners.delete(listener);
+    }
+    installExitHandlers() {
+        const restore = () => this.restore();
+        const onSignal = (signal) => () => {
+            restore();
+            process.exit(signal === "SIGINT" ? 130 : 143);
+        };
+        const onExit = () => restore();
+        const onError = (error) => {
+            restore();
+            // The terminal is usable again, so the stack trace is actually readable.
+            console.error(error);
+            process.exit(1);
+        };
+        const sigint = onSignal("SIGINT");
+        const sigterm = onSignal("SIGTERM");
+        const sighup = onSignal("SIGHUP");
+        process.on("SIGINT", sigint);
+        process.on("SIGTERM", sigterm);
+        process.on("SIGHUP", sighup);
+        process.on("exit", onExit);
+        process.on("uncaughtException", onError);
+        process.on("unhandledRejection", onError);
+        this.cleanupHandlers.push(() => {
+            process.off("SIGINT", sigint);
+            process.off("SIGTERM", sigterm);
+            process.off("SIGHUP", sighup);
+            process.off("exit", onExit);
+            process.off("uncaughtException", onError);
+            process.off("unhandledRejection", onError);
+        });
+    }
+}
+export function createTerminal(options = {}) {
+    return new Terminal(options);
+}
+/**
+ * Last-resort cleanup for a process that lost its Terminal reference.
+ * Safe to call from a signal handler or a REPL after a bad crash.
+ */
+export function emergencyRestore(output = process.stdout) {
+    output.write(ansi.reset + ansi.focusOff + ansi.bracketedPasteOff + ansi.mouseOff +
+        ansi.cursorShow + ansi.alternateScreenOff);
+    if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
+        process.stdin.setRawMode(false);
+    }
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,71 @@
+import { FrameBuffer } from "./buffer.ts";
+import { Container } from "./ui.ts";
+import { type Theme, type ThemeName } from "./theme.ts";
+import { type Capabilities, type CapabilityOverrides } from "./capabilities.ts";
+import { type Color } from "./color.ts";
+export interface RenderOptions {
+    width?: number;
+    height?: number;
+    theme?: Theme | ThemeName | string;
+    capabilities?: CapabilityOverrides;
+    /** Frame number reported to the view, for animation snapshots. */
+    frame?: number;
+    elapsed?: number;
+    focus?: number;
+}
+export interface CellSnapshot {
+    char: string;
+    fg: Color;
+    bg: Color;
+    attrs: number;
+}
+export interface RenderedScreen {
+    width: number;
+    height: number;
+    buffer: FrameBuffer;
+    /** Plain text, one line per row, trailing spaces trimmed. */
+    text(): string;
+    /** One row of plain text. */
+    line(y: number): string;
+    /** Everything, with ANSI colors — paste into a terminal to see it. */
+    ansi(): string;
+    cell(x: number, y: number): CellSnapshot;
+    /** Row/col of the first occurrence, or null. */
+    find(needle: string): {
+        x: number;
+        y: number;
+    } | null;
+    contains(needle: string): boolean;
+    /** Cell grid as JSON, for structural assertions. */
+    toJSON(): CellSnapshot[][];
+}
+/**
+ * Render a view to an in-memory screen. No TTY, no escape codes, no timers —
+ * which is what makes TUI code written with this library actually testable.
+ *
+ *   const screen = renderToScreen(({ ui }) => ui.text("CPU 72%"));
+ *   expect(screen.text()).toContain("CPU 72%");
+ */
+export declare function renderToScreen(view: (args: {
+    ui: Container;
+    theme: Theme;
+    width: number;
+    height: number;
+    capabilities: Capabilities;
+}) => void, options?: RenderOptions): RenderedScreen;
+/** Shorthand: render and return plain text. Ideal for snapshot tests. */
+export declare function renderToText(view: Parameters<typeof renderToScreen>[0], options?: RenderOptions): string;
+/** Render with ANSI colors, e.g. to write a demo screenshot to a file. */
+export declare function renderToAnsi(view: Parameters<typeof renderToScreen>[0], options?: RenderOptions): string;
+/**
+ * Render to standalone HTML — a real screenshot of the UI, no terminal needed.
+ * This is how the marketing site and the docs show live examples.
+ */
+export declare function renderToHtml(view: Parameters<typeof renderToScreen>[0], options?: RenderOptions & {
+    fontSize?: number;
+    padding?: number;
+    className?: string;
+}): string;
+/** Drive a view for N frames — for animation and performance assertions. */
+export declare function renderFrames(view: Parameters<typeof renderToScreen>[0], count: number, options?: RenderOptions): RenderedScreen[];
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

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