@zenbu-labs/pixel 0.0.0 → 0.0.12

package/dist/terminal/detect.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detect = detect;
+exports.checkTerminal = checkTerminal;
+exports.cannotOpenPanes = cannotOpenPanes;
+const graphics_1 = require("./graphics");
+const run_1 = require("./run");
+const terminals_1 = require("./terminals");
+function detect(env = process.env, run) {
+    const runIn = run ?? (0, run_1.shellIn)(env);
+    for (const recognise of terminals_1.TERMINALS) {
+        const terminal = recognise(env, runIn);
+        if (terminal)
+            return terminal;
+    }
+    return null;
+}
+async function checkTerminal(terminal, env = process.env) {
+    await terminal?.prepare?.();
+    if (env[graphics_1.SKIP_ENV])
+        return { terminal, graphics: "supported" };
+    const probed = await (0, graphics_1.probeGraphics)(terminal);
+    const graphics = probed === "unknown" ? (terminal ? "supported" : "unsupported") : probed;
+    return { terminal, graphics };
+}
+function cannotOpenPanes(terminal) {
+    const who = terminal
+        ? `${terminal.name} cannot open panes from a command`
+        : "unrecogonized terminal";
+    const recommendation = process.platform === "darwin"
+        ? "We recommend Ghostty (https://ghostty.org/download)."
+        : "We recommend Kitty (https://sw.kovidgoyal.net/kitty/binary)";
+    return `${who}. ${recommendation}`;
+}

package/dist/terminal/graphics.d.ts

@@ -0,0 +1,9 @@
+import type { Terminal } from "./terminal";
+export type GraphicsSupport = "supported" | "unsupported" | "unknown";
+export declare const SKIP_ENV = "PIXEL_SKIP_GRAPHICS_CHECK";
+export declare function probeGraphics(terminal: Terminal | null): Promise<GraphicsSupport>;
+export declare function panePixels(): Promise<{
+    width: number;
+    height: number;
+} | null>;
+export declare function unsupportedGraphicsMessage(color?: boolean): string;

package/dist/terminal/graphics.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_ENV = void 0;
+exports.probeGraphics = probeGraphics;
+exports.panePixels = panePixels;
+exports.unsupportedGraphicsMessage = unsupportedGraphicsMessage;
+const node_fs_1 = __importDefault(require("node:fs"));
+exports.SKIP_ENV = "PIXEL_SKIP_GRAPHICS_CHECK";
+const PROBE_ID = 4207;
+const PROBE_TIMEOUT_MS = 500;
+function passthrough(seq) {
+    return `\x1bPtmux;${seq.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+function probeSequence(wrap) {
+    const query = `\x1b_Gi=${PROBE_ID},a=q,t=d,f=24,s=1,v=1;AAAA\x1b\\`;
+    return `${wrap ? passthrough(query) : query}\x1b[c`;
+}
+function graphicsReply(buffer) {
+    const needle = `Gi=${PROBE_ID};`;
+    const at = buffer.indexOf(needle);
+    if (at < 0)
+        return null;
+    const rest = buffer.slice(at + needle.length);
+    if (rest.length < 2)
+        return null;
+    return rest.startsWith("OK");
+}
+function probeGraphics(terminal) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY || !process.stdout.isTTY || !stdin.setRawMode) {
+        return Promise.resolve("unknown");
+    }
+    const wasRaw = stdin.isRaw;
+    return new Promise((resolve) => {
+        let buffer = "";
+        let timer = null;
+        let done = false;
+        const finish = (graphics) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            stdin.off("data", onData);
+            try {
+                if (!wasRaw)
+                    stdin.setRawMode?.(false);
+            }
+            catch { }
+            if (!stdin.isPaused())
+                stdin.pause();
+            resolve(graphics);
+        };
+        const onData = (chunk) => {
+            buffer += chunk.toString("binary");
+            const reply = graphicsReply(buffer);
+            if (reply !== null)
+                return finish(reply ? "supported" : "unsupported");
+            if (buffer.length > 1024)
+                finish("unknown");
+        };
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            return finish("unknown");
+        }
+        stdin.resume();
+        stdin.on("data", onData);
+        timer = setTimeout(() => finish("unknown"), PROBE_TIMEOUT_MS);
+        try {
+            node_fs_1.default.writeSync(1, probeSequence(terminal?.wrapper === "tmux"));
+        }
+        catch {
+            finish("unknown");
+        }
+    });
+}
+function panePixels() {
+    const stdin = process.stdin;
+    if (!stdin.isTTY || !process.stdout.isTTY || !stdin.setRawMode)
+        return Promise.resolve(null);
+    const wasRaw = stdin.isRaw;
+    return new Promise((resolve) => {
+        let buffer = "";
+        let timer = null;
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            stdin.off("data", onData);
+            try {
+                if (!wasRaw)
+                    stdin.setRawMode?.(false);
+            }
+            catch { }
+            if (!stdin.isPaused())
+                stdin.pause();
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            buffer += chunk.toString("binary");
+            const reply = /\x1b\[4;(\d+);(\d+)t/.exec(buffer);
+            if (reply)
+                finish({ width: Number(reply[2]), height: Number(reply[1]) });
+        };
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            return finish(null);
+        }
+        stdin.resume();
+        stdin.on("data", onData);
+        timer = setTimeout(() => finish(null), PROBE_TIMEOUT_MS);
+        try {
+            node_fs_1.default.writeSync(1, "\x1b[14t");
+        }
+        catch {
+            finish(null);
+        }
+    });
+}
+function unsupportedGraphicsMessage(color = false) {
+    const sgr = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    return [
+        "",
+        `  ${sgr("1", "Unsupported terminal: this terminal cannot display graphics")}`,
+        "",
+        `  ${sgr("2", "We recommend Ghostty:")}`,
+        `  ${sgr("4", "https://ghostty.org/download")}`,
+        "",
+        `  ${sgr("2", "Note: any terminal that supports the kitty graphics protocol is supported")}`,
+        "",
+    ].join("\n");
+}

package/dist/terminal/index.d.ts

@@ -0,0 +1,12 @@
+/// <reference path="../../electron/electron.d.ts" preserve="true" />
+export type { Detect, Direction, ListPanesOptions, Pane, PaneContext, PaneDetails, SplitRequest, Terminal } from "./terminal";
+export { canSplit } from "./terminal";
+export type { Run } from "./run";
+export { shellIn } from "./run";
+export { bracketedPaste, callerTty, shellLiteral } from "./shared";
+export type { TerminalCheck } from "./detect";
+export { cannotOpenPanes, checkTerminal, detect } from "./detect";
+export type { GraphicsSupport } from "./graphics";
+export type { Instance } from "../instances";
+export { findOwner, listInstances, PROTOCOL as EMBED_PROTOCOL } from "../instances";
+export { probeGraphics, unsupportedGraphicsMessage, SKIP_ENV as GRAPHICS_SKIP_ENV } from "./graphics";

package/dist/terminal/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRAPHICS_SKIP_ENV = exports.unsupportedGraphicsMessage = exports.probeGraphics = exports.EMBED_PROTOCOL = exports.listInstances = exports.findOwner = exports.detect = exports.checkTerminal = exports.cannotOpenPanes = exports.shellLiteral = exports.callerTty = exports.bracketedPaste = exports.shellIn = exports.canSplit = void 0;
+var terminal_1 = require("./terminal");
+Object.defineProperty(exports, "canSplit", { enumerable: true, get: function () { return terminal_1.canSplit; } });
+var run_1 = require("./run");
+Object.defineProperty(exports, "shellIn", { enumerable: true, get: function () { return run_1.shellIn; } });
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "bracketedPaste", { enumerable: true, get: function () { return shared_1.bracketedPaste; } });
+Object.defineProperty(exports, "callerTty", { enumerable: true, get: function () { return shared_1.callerTty; } });
+Object.defineProperty(exports, "shellLiteral", { enumerable: true, get: function () { return shared_1.shellLiteral; } });
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "cannotOpenPanes", { enumerable: true, get: function () { return detect_1.cannotOpenPanes; } });
+Object.defineProperty(exports, "checkTerminal", { enumerable: true, get: function () { return detect_1.checkTerminal; } });
+Object.defineProperty(exports, "detect", { enumerable: true, get: function () { return detect_1.detect; } });
+var instances_1 = require("../instances");
+Object.defineProperty(exports, "findOwner", { enumerable: true, get: function () { return instances_1.findOwner; } });
+Object.defineProperty(exports, "listInstances", { enumerable: true, get: function () { return instances_1.listInstances; } });
+Object.defineProperty(exports, "EMBED_PROTOCOL", { enumerable: true, get: function () { return instances_1.PROTOCOL; } });
+var graphics_1 = require("./graphics");
+Object.defineProperty(exports, "probeGraphics", { enumerable: true, get: function () { return graphics_1.probeGraphics; } });
+Object.defineProperty(exports, "unsupportedGraphicsMessage", { enumerable: true, get: function () { return graphics_1.unsupportedGraphicsMessage; } });
+Object.defineProperty(exports, "GRAPHICS_SKIP_ENV", { enumerable: true, get: function () { return graphics_1.SKIP_ENV; } });

package/dist/terminal/run.d.ts

@@ -0,0 +1,2 @@
+export type Run = (bin: string, args: string[], input?: string) => Promise<string>;
+export declare function shellIn(env: NodeJS.ProcessEnv): Run;

package/dist/terminal/run.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellIn = shellIn;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const exec = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function shellIn(env) {
+    return async (bin, args, input) => {
+        const running = exec(bin, args, { env, maxBuffer: 4 * 1024 * 1024, timeout: 8000 });
+        if (input !== undefined)
+            running.child.stdin?.end(input);
+        const { stdout } = await running;
+        return stdout;
+    };
+}

package/dist/terminal/shared.d.ts

@@ -0,0 +1,20 @@
+import type { Pane } from "./terminal";
+export interface CallerTty {
+    path: string | null;
+    denied: boolean;
+}
+export interface PaneRect {
+    id: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export declare function adjacentPane(from: PaneRect, candidates: PaneRect[], direction: "right" | "left" | "down" | "up", gap?: number): PaneRect | null;
+export declare function callerTty(): CallerTty;
+export declare function setPaneWorkingDirectory(tty: string, directory: string): void;
+export declare function paneById(panes: () => Promise<Pane[]>, id: string | null | undefined): Promise<Pane | null>;
+export declare function shellQuote(argv: string[]): string;
+export declare const sleep: (ms: number) => Promise<unknown>;
+export declare function shellLiteral(text: string): string;
+export declare function bracketedPaste(text: string): string;

package/dist/terminal/shared.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+exports.adjacentPane = adjacentPane;
+exports.callerTty = callerTty;
+exports.setPaneWorkingDirectory = setPaneWorkingDirectory;
+exports.paneById = paneById;
+exports.shellQuote = shellQuote;
+exports.shellLiteral = shellLiteral;
+exports.bracketedPaste = bracketedPaste;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+function adjacentPane(from, candidates, direction, gap = 2) {
+    const touches = (candidate) => {
+        switch (direction) {
+            case "right":
+                return candidate.left > from.right && candidate.left <= from.right + gap;
+            case "left":
+                return candidate.right < from.left && candidate.right >= from.left - gap;
+            case "down":
+                return candidate.top > from.bottom && candidate.top <= from.bottom + gap;
+            case "up":
+                return candidate.bottom < from.top && candidate.bottom >= from.top - gap;
+        }
+    };
+    const overlap = (candidate) => direction === "right" || direction === "left"
+        ? Math.min(candidate.bottom, from.bottom) - Math.max(candidate.top, from.top)
+        : Math.min(candidate.right, from.right) - Math.max(candidate.left, from.left);
+    let best = null;
+    for (const candidate of candidates) {
+        if (candidate.id === from.id || !touches(candidate) || overlap(candidate) < 0)
+            continue;
+        if (!best || overlap(candidate) > overlap(best))
+            best = candidate;
+    }
+    return best;
+}
+function callerTty() {
+    let pid = process.pid;
+    for (let hops = 0; hops < 30 && pid > 1; hops++) {
+        let out;
+        try {
+            out = (0, node_child_process_1.execFileSync)("ps", ["-o", "ppid=,tty=", "-p", String(pid)], {
+                encoding: "utf8",
+            }).trim();
+        }
+        catch {
+            return { path: null, denied: hops === 0 };
+        }
+        if (!out)
+            return { path: null, denied: hops === 0 };
+        const [ppid, tty] = out.split(/\s+/);
+        if (tty && tty !== "??" && tty !== "?")
+            return { path: `/dev/${tty}`, denied: false };
+        pid = Number(ppid);
+        if (!Number.isFinite(pid))
+            return { path: null, denied: false };
+    }
+    return { path: null, denied: false };
+}
+function setPaneWorkingDirectory(tty, directory) {
+    const encoded = directory.split("/").map(encodeURIComponent).join("/");
+    node_fs_1.default.writeFileSync(tty, `\x1b]7;file://${node_os_1.default.hostname()}${encoded}\x07`);
+}
+async function paneById(panes, id) {
+    if (!id)
+        return null;
+    return (await panes()).find((pane) => pane.id === id) ?? null;
+}
+function shellQuote(argv) {
+    return argv
+        .map((arg) => arg !== "" && /^[\w\-./:=+@%,]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`)
+        .join(" ");
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.sleep = sleep;
+function shellLiteral(text) {
+    return `'${text.replace(/['\\]/g, (char) => (char === "'" ? "'\\''" : "'\\\\'"))}'`;
+}
+function bracketedPaste(text) {
+    if (!text.includes("\n"))
+        return text;
+    return `\x1b[200~${text.replaceAll("\x1b[201~", "")}\x1b[201~`;
+}

package/dist/terminal/terminal.d.ts

@@ -0,0 +1,66 @@
+import type { Run } from "./run";
+export type Direction = "right" | "left" | "down" | "up";
+export interface Pane {
+    id: string;
+    tab: string;
+}
+export interface PaneDetails extends Pane {
+    tty: string | null;
+    command: string | null;
+}
+export interface PaneContext {
+    tty: string | null;
+    cwd: string;
+}
+export interface ListPanesOptions {
+    commands?: (command: string) => boolean;
+    tty?: string | null;
+}
+export interface SplitRequest {
+    from: Pane;
+    direction: Direction;
+    command: string[];
+    size: number | null;
+    tty: string | null;
+}
+export interface Terminal {
+    readonly name: string;
+    /**
+     * When terminal-browser tries to write to the TTY to render graphics using the
+     * kitty graphics protocol, tmux will by default not forward those escape
+     * codes to the outer TTY. But, tmux supports a passthrough mode if the content
+     * is wrapped in tmux specific escape codes. We implement this "wrapping" functionality
+     * internally, and allow a backend to configure what kind of wrapping should be applied (if any)
+     */
+    readonly wrapper?: "tmux";
+    /**
+     * When terminal-browser is rendered, it is scaled by the DPI of the display
+     * Terminals that report css based pixels when queried already perform that normalization, so we need an explicit flag to avoid rescaling
+     */
+    readonly reportsCssPixels?: boolean;
+    /**
+     * Allows code to be ran at startup, useful for preparing the terminal environment for terminal-browser
+     */
+    prepare?(): void | Promise<void>;
+    /**
+     * Allows terminal-browser to know which pane its being called from inside the terminal.
+     * This gives terminal-browser the ability to know if a terminal-browser instance
+     * is open inside the terminal-pane, and powers features such as:
+     * - terminal-browser ls lists the browers inside the current terminal tab
+     * - terminal-browser new-tab [url] will open in the browser inside the current terminal tab by default
+     */
+    getCurrentPane?(context: PaneContext): Promise<Pane | null>;
+    /**
+     * This powers terminal-browser's --split argument. This is useful when using terminal-browser w/ coding agents
+     * since it allows agents to open a browser next to their TUI without having to know how to
+     * script the current terminal they are running in
+     *
+     */
+    split?(request: SplitRequest): Promise<void>;
+    listPanes?(options?: ListPanesOptions): Promise<PaneDetails[]>;
+    neighbor?(from: Pane, direction: Direction): Promise<Pane | null>;
+    sendText?(pane: string, text: string): Promise<void>;
+    focusPane?(pane: string): Promise<void>;
+}
+export type Detect = (env: NodeJS.ProcessEnv, run: Run) => Terminal | null;
+export declare function canSplit(terminal: Terminal | null): boolean;

package/dist/terminal/terminal.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canSplit = canSplit;
+function canSplit(terminal) {
+    return Boolean(terminal?.split);
+}

package/dist/terminal/terminals/cmux.d.ts

@@ -0,0 +1,2 @@
+import type { Detect } from "../terminal";
+export declare const cmux: Detect;

package/dist/terminal/terminals/cmux.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmux = void 0;
+const shared_1 = require("../shared");
+const cmux = (env, run) => {
+    if (!env.CMUX_SURFACE_ID)
+        return null;
+    const binary = env.CMUX_BUNDLED_CLI_PATH ?? "cmux";
+    const cmux = (args) => run(binary, args);
+    const asked = async (args) => JSON.parse(await cmux([...args, "--json", "--id-format", "both"]));
+    async function panes() {
+        const listed = (await asked(["list-panes"])).panes ?? [];
+        const found = [];
+        for (const pane of listed) {
+            const paneId = pane.id ?? pane.ref;
+            if (!paneId)
+                continue;
+            const surfaces = (await asked(["list-pane-surfaces", "--pane", paneId]))
+                .surfaces ?? [];
+            for (const surface of surfaces) {
+                if (!surface.id)
+                    continue;
+                found.push({ id: surface.id, tab: env.CMUX_WORKSPACE_ID ?? "" });
+            }
+        }
+        return found;
+    }
+    async function listPanes() {
+        const tree = (await asked(["tree", "--all"]));
+        const found = [];
+        for (const window of tree.windows ?? []) {
+            for (const workspace of window.workspaces ?? []) {
+                for (const pane of workspace.panes ?? []) {
+                    for (const surface of pane.surfaces ?? []) {
+                        if (surface.type !== undefined && surface.type !== "terminal")
+                            continue;
+                        found.push({
+                            id: surface.id,
+                            tab: workspace.id,
+                            tty: surface.tty || null,
+                            command: null,
+                        });
+                    }
+                }
+            }
+        }
+        return found;
+    }
+    async function neighbor(from, direction) {
+        const workspace = from.tab || env.CMUX_WORKSPACE_ID;
+        const rows = (await asked(["rpc", "pane.list", JSON.stringify(workspace ? { workspace_id: workspace } : {})])).panes ?? [];
+        const rects = [];
+        const surfacesOf = new Map();
+        for (const row of rows) {
+            const id = row.id ?? row.ref;
+            const frame = row.pixel_frame ?? row.frame;
+            if (!id || !frame || frame.x == null || frame.y == null || frame.width == null || frame.height == null)
+                continue;
+            rects.push({
+                id,
+                left: Math.round(frame.x),
+                top: Math.round(frame.y),
+                right: Math.round(frame.x + frame.width) - 1,
+                bottom: Math.round(frame.y + frame.height) - 1,
+            });
+            surfacesOf.set(id, (await asked(["list-pane-surfaces", "--pane", id])).surfaces ?? []);
+        }
+        const own = rects.find((rect) => (surfacesOf.get(rect.id) ?? []).some((surface) => surface.id === from.id));
+        if (!own)
+            return null;
+        const found = (0, shared_1.adjacentPane)(own, rects, direction, 16);
+        if (!found)
+            return null;
+        const surfaces = surfacesOf.get(found.id) ?? [];
+        const shown = surfaces.find((surface) => surface.focused || surface.selected) ?? surfaces[0];
+        return shown?.id ? { id: shown.id, tab: from.tab } : null;
+    }
+    return {
+        name: "cmux",
+        getCurrentPane: () => (0, shared_1.paneById)(panes, env.CMUX_SURFACE_ID),
+        listPanes,
+        neighbor,
+        async sendText(pane, text) {
+            await cmux(["rpc", "terminal.paste", JSON.stringify({ text, surface_id: pane, submit_key: "none" })]);
+        },
+        async focusPane(pane) {
+            await cmux(["focus-panel", "--panel", pane]);
+        },
+        async split({ from, direction, command }) {
+            const created = await asked(["new-split", direction, "--surface", from.id, "--focus", "true"]);
+            const opened = created.surface_id ?? created.surface_ref;
+            if (!opened)
+                throw new Error("cmux opened a split but did not say which surface it is");
+            await cmux(["send", "--surface", opened, "--", `${(0, shared_1.shellQuote)(command)}\\n`]);
+        },
+    };
+};
+exports.cmux = cmux;

package/dist/terminal/terminals/ghostty-script.d.ts

@@ -0,0 +1 @@
+export declare const GHOSTTY_SCRIPT: string;