@tuidom/headless-backend 0.1.0

package/dist/headlessCaptureBackend.d.ts

@@ -0,0 +1,72 @@
+import type { ITerminalBackend } from "@tuidom/core/backend/iTerminalBackend";
+import { Point, Size } from "@tuidom/core/common/geometryPromitives";
+import type { KeyPressEvent } from "@tuidom/core/input/keyEvent";
+import type { MouseToken } from "@tuidom/core/input/rawTerminalToken";
+import { type SerializeMouseInit } from "@tuidom/core/input/serializeMouse";
+import type { Grid } from "@tuidom/core/rendering/grid";
+import { type GridSnapshot } from "@tuidom/core/rendering/gridSnapshot";
+/**
+ * Terminal backend that runs the real application without a real terminal.
+ *
+ * Unlike {@link import("@tuidom/terminal-backend/nodeTerminalBackend").NodeTerminalBackend} it never
+ * touches stdin/stdout: `setup`/`teardown` are no-ops and rendered frames are
+ * captured into a {@link GridSnapshot} instead of being written as ANSI. Input is
+ * injected the same way {@link import("@tuidom/testing/mockTerminalBackend").MockTerminalBackend}
+ * does it — through the real {@link KeyInputParser} and {@link serializeKey} DSL —
+ * so the app sees byte-for-byte the same `KeyPressEvent`s a terminal would produce.
+ *
+ * Drives the `--headless` mode: the inspector exposes {@link sendKey} /
+ * {@link captureFrame} over WebSocket so a client can script the editor and read
+ * back the screen for image rendering.
+ */
+export declare class HeadlessCaptureBackend implements ITerminalBackend {
+    private readonly inputCallbacks;
+    private readonly mouseCallbacks;
+    private readonly pasteCallbacks;
+    private readonly resizeCallbacks;
+    private readonly oscResponseCallbacks;
+    private readonly inputParser;
+    private size;
+    private lastFrame;
+    constructor(size?: Size);
+    onInput(callback: (event: KeyPressEvent) => void): void;
+    onMouse(callback: (event: MouseToken) => void): void;
+    onPaste(callback: (text: string) => void): void;
+    onResize(callback: (size: Size) => void): void;
+    onOscResponse(callback: (code: number, data: string) => void): void;
+    /**
+     * There is no terminal to probe. We never resolve the callback: leaving the
+     * probe pending is harmless (it is fire-and-forget) and keeps capabilities at
+     * their deterministic env-derived baseline, which matters for reproducible
+     * screenshots.
+     */
+    probeKeyboardProtocol(_onResult: (supported: boolean) => void): void;
+    renderFrame(grid: Grid, cursorPosition: Point | null): void;
+    getSize(): Size;
+    setup(): void;
+    teardown(): void;
+    /** OSC output (e.g. clipboard writes) has nowhere to go in headless mode. */
+    writeOscSequence(_sequence: string): void;
+    /**
+     * Inject a key using the human-readable DSL (`"a"`, `"Enter"`, `"Ctrl+P"`).
+     * Goes through the same parser as real terminal input.
+     */
+    sendKey(name: string): void;
+    /** Inject a bracketed paste: `text` is delivered to paste subscribers as one block. */
+    sendPaste(text: string): void;
+    /** Inject raw terminal bytes (escape sequences etc.) for edge cases. */
+    sendRaw(data: string): void;
+    /** Inject a ready-made mouse token straight to subscribers, bypassing the parser. */
+    simulateMouse(token: MouseToken): void;
+    /**
+     * Inject a mouse event through the real parser: it is encoded as an SGR (1006)
+     * sequence and tokenized back, exactly like input from a terminal. Coordinates
+     * are 1-based, as {@link MouseToken} carries them.
+     */
+    sendMouse(init: SerializeMouseInit): void;
+    /** Resize the virtual terminal and notify the application. */
+    resize(size: Size): void;
+    /** The most recently rendered frame as plain data. */
+    captureFrame(): GridSnapshot;
+    private emitStreams;
+}

package/dist/headlessCaptureBackend.js

@@ -0,0 +1,132 @@
+import { Point, Size } from "@tuidom/core/common/geometryPromitives";
+import { KeyInputParser } from "@tuidom/core/input/keyInputParser";
+import { serializeKey } from "@tuidom/core/input/serializeKey";
+import { serializeMouse } from "@tuidom/core/input/serializeMouse";
+import { emptyGridSnapshot, snapshotGrid } from "@tuidom/core/rendering/gridSnapshot";
+/**
+ * Terminal backend that runs the real application without a real terminal.
+ *
+ * Unlike {@link import("@tuidom/terminal-backend/nodeTerminalBackend").NodeTerminalBackend} it never
+ * touches stdin/stdout: `setup`/`teardown` are no-ops and rendered frames are
+ * captured into a {@link GridSnapshot} instead of being written as ANSI. Input is
+ * injected the same way {@link import("@tuidom/testing/mockTerminalBackend").MockTerminalBackend}
+ * does it — through the real {@link KeyInputParser} and {@link serializeKey} DSL —
+ * so the app sees byte-for-byte the same `KeyPressEvent`s a terminal would produce.
+ *
+ * Drives the `--headless` mode: the inspector exposes {@link sendKey} /
+ * {@link captureFrame} over WebSocket so a client can script the editor and read
+ * back the screen for image rendering.
+ */
+export class HeadlessCaptureBackend {
+    inputCallbacks = [];
+    mouseCallbacks = [];
+    pasteCallbacks = [];
+    resizeCallbacks = [];
+    oscResponseCallbacks = [];
+    inputParser = new KeyInputParser();
+    size;
+    lastFrame;
+    constructor(size = new Size(120, 32)) {
+        this.size = size;
+        this.lastFrame = emptyGridSnapshot(size.width, size.height);
+    }
+    // ─── ITerminalBackend ───
+    onInput(callback) {
+        this.inputCallbacks.push(callback);
+    }
+    onMouse(callback) {
+        this.mouseCallbacks.push(callback);
+    }
+    onPaste(callback) {
+        this.pasteCallbacks.push(callback);
+    }
+    onResize(callback) {
+        this.resizeCallbacks.push(callback);
+    }
+    onOscResponse(callback) {
+        this.oscResponseCallbacks.push(callback);
+    }
+    /**
+     * There is no terminal to probe. We never resolve the callback: leaving the
+     * probe pending is harmless (it is fire-and-forget) and keeps capabilities at
+     * their deterministic env-derived baseline, which matters for reproducible
+     * screenshots.
+     */
+    probeKeyboardProtocol(_onResult) {
+        // intentionally never resolved — see doc comment
+    }
+    renderFrame(grid, cursorPosition) {
+        this.lastFrame = snapshotGrid(grid, cursorPosition);
+    }
+    getSize() {
+        return this.size;
+    }
+    setup() {
+        // No terminal to initialize.
+    }
+    teardown() {
+        // No terminal to restore.
+    }
+    /** OSC output (e.g. clipboard writes) has nowhere to go in headless mode. */
+    writeOscSequence(_sequence) {
+        // No-op: no terminal to receive the sequence.
+    }
+    // ─── Driver surface (used by the inspector in headless mode) ───
+    /**
+     * Inject a key using the human-readable DSL (`"a"`, `"Enter"`, `"Ctrl+P"`).
+     * Goes through the same parser as real terminal input.
+     */
+    sendKey(name) {
+        this.sendRaw(serializeKey(name));
+        // serializeKey always yields a complete sequence, so drain any tail a lone
+        // ESC ("Escape") would otherwise leave buffered awaiting a continuation.
+        if (this.inputParser.hasPending()) {
+            this.emitStreams(this.inputParser.flush());
+        }
+    }
+    /** Inject a bracketed paste: `text` is delivered to paste subscribers as one block. */
+    sendPaste(text) {
+        this.sendRaw(`\x1b[200~${text}\x1b[201~`);
+    }
+    /** Inject raw terminal bytes (escape sequences etc.) for edge cases. */
+    sendRaw(data) {
+        this.emitStreams(this.inputParser.parseWithMouse(data));
+    }
+    /** Inject a ready-made mouse token straight to subscribers, bypassing the parser. */
+    simulateMouse(token) {
+        for (const cb of this.mouseCallbacks)
+            cb(token);
+    }
+    /**
+     * Inject a mouse event through the real parser: it is encoded as an SGR (1006)
+     * sequence and tokenized back, exactly like input from a terminal. Coordinates
+     * are 1-based, as {@link MouseToken} carries them.
+     */
+    sendMouse(init) {
+        this.sendRaw(serializeMouse(init));
+    }
+    /** Resize the virtual terminal and notify the application. */
+    resize(size) {
+        this.size = size;
+        for (const cb of this.resizeCallbacks)
+            cb(size);
+    }
+    /** The most recently rendered frame as plain data. */
+    captureFrame() {
+        return this.lastFrame;
+    }
+    emitStreams(streams) {
+        for (const event of streams.keys) {
+            for (const cb of this.inputCallbacks)
+                cb(event);
+        }
+        for (const token of streams.mouse) {
+            for (const cb of this.mouseCallbacks)
+                cb(token);
+        }
+        for (const text of streams.paste) {
+            for (const cb of this.pasteCallbacks)
+                cb(text);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@tuidom/headless-backend",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Experimental terminal UI DOM — headless capture backend (in-memory frames for screenshots/e2e). API is unstable.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tuidom/tuidom.git",
+        "directory": "packages/headless-backend"
+    },
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "keywords": [
+        "tui",
+        "terminal",
+        "ui",
+        "dom",
+        "headless"
+    ],
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        "./package.json": "./package.json",
+        "./*.js": "./dist/*.js",
+        "./*": "./dist/*.js"
+    },
+    "dependencies": {
+        "@tuidom/core": "0.1.0"
+    }
+}