gpui-bridge 0.0.0-stage → 0.2.0

package/dist/app.js

@@ -0,0 +1,587 @@
+// Runtime-agnostic client core: the App/UINode API and the handshake. It only
+// needs a transport to the host process, so any JavaScript runtime can use it
+// (Node: index.ts, txiki.js: txiki.ts).
+import { PROTOCOL_VERSION, } from "./protocol.js";
+import { Tree } from "./tree.js";
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+export class HostExitedError extends Error {
+    exit;
+    constructor(message, exit) {
+        super(message);
+        this.exit = exit;
+        this.name = "HostExitedError";
+    }
+}
+function describeExit(exit, hostPath) {
+    if (exit.spawnError) {
+        const code = exit.spawnError.code;
+        return code === "ENOENT"
+            ? `gpui-bridge host not found at ${hostPath}. Build it with \`cargo build\` in host/ or pass hostPath.`
+            : `gpui-bridge host failed to start: ${exit.spawnError.message}`;
+    }
+    const how = exit.signal ? `signal ${exit.signal}` : `code ${exit.code}`;
+    const tail = exit.stderrTail.length ? `\nLast host output:\n  ${exit.stderrTail.join("\n  ")}` : "";
+    return `gpui-bridge host exited (${how}).${tail}`;
+}
+export class UINode {
+    app;
+    id;
+    type;
+    /** @internal */
+    constructor(app, id, type) {
+        this.app = app;
+        this.id = id;
+        this.type = type;
+    }
+    append(...children) {
+        for (const child of children) {
+            this.app.wire.queue({ op: "append", parent: this.id, child: child.id });
+            this.app.wire.attach(this.id, child.id);
+        }
+        return this;
+    }
+    insertBefore(child, before) {
+        this.app.wire.queue({ op: "insertBefore", parent: this.id, child: child.id, before: before.id });
+        this.app.wire.attach(this.id, child.id);
+        return this;
+    }
+    /** Merges props; `null` removes one. */
+    set(props) {
+        this.app.wire.queue({ op: "setProps", id: this.id, props });
+        return this;
+    }
+    /** Subscribes to an event; the host only emits subscribed events. */
+    on(event, handler) {
+        this.app.wire.setHandler(this.id, event, handler);
+        return this;
+    }
+    off(event) {
+        this.app.wire.setHandler(this.id, event, undefined);
+        return this;
+    }
+    /** Gives the node the keyboard focus on the next commit (an Input, a Textarea or a div with `keyDown`). */
+    focus() {
+        this.app.wire.queue({ op: "focus", id: this.id });
+        return this;
+    }
+    /** Removes the node and all its descendants. */
+    remove() {
+        this.app.wire.remove(this.id);
+    }
+}
+/** A window other than the main one (`App.createWindow`). */
+export class AppWindow {
+    app;
+    id;
+    closedListeners = new Set();
+    eventListeners = new Map();
+    /** The subscription list last sent, to avoid one message per listener. */
+    eventNames = "";
+    /** @internal */
+    constructor(app, id) {
+        this.app = app;
+        this.id = id;
+    }
+    /** Updates the window; like `App.window`, it opens on the first commit that sets `root`. */
+    set(options) {
+        this.app.queueWindow(this.id, options);
+        return this;
+    }
+    /** Closes the window on the next commit. No `closed` event follows: that is only for the user closing it. */
+    close() {
+        this.app.queueCloseWindow(this.id);
+    }
+    on(event, listener) {
+        if (event === "closed") {
+            this.closedListeners.add(listener);
+            return this;
+        }
+        const listeners = this.eventListeners.get(event) ?? new Set();
+        listeners.add(listener);
+        this.eventListeners.set(event, listeners);
+        this.syncEvents();
+        return this;
+    }
+    off(event, listener) {
+        if (event === "closed") {
+            this.closedListeners.delete(listener);
+            return this;
+        }
+        const listeners = this.eventListeners.get(event);
+        listeners?.delete(listener);
+        if (listeners?.size === 0)
+            this.eventListeners.delete(event);
+        this.syncEvents();
+        return this;
+    }
+    /** @internal */
+    handleClosed() {
+        for (const listener of this.closedListeners)
+            listener();
+    }
+    /** @internal */
+    handleWindowEvent(payload) {
+        for (const listener of this.eventListeners.get(payload.event) ?? [])
+            listener(payload);
+    }
+    /** Sends the subscription list only when the set of subscribed events changes. */
+    syncEvents() {
+        const events = [...this.eventListeners.keys()];
+        const names = events.join(",");
+        if (names === this.eventNames)
+            return;
+        this.eventNames = names;
+        this.app.queueWindow(this.id, { events });
+    }
+}
+export class App {
+    host;
+    hostPath;
+    /** @internal Protocol operations queued until `commit`. */
+    wire = new Tree();
+    listeners = {
+        error: new Set(),
+        windowClosed: new Set(),
+        windowEvent: new Set(),
+        shortcut: new Set(),
+        notification: new Set(),
+        tray: new Set(),
+        exit: new Set(),
+    };
+    exitInfo;
+    closing = false;
+    nextWindowId = 2;
+    windows = new Map();
+    /** Windows given a root and not closed: the host exits when the user closes the last one. */
+    openWindows = new Set();
+    nextRequest = 1;
+    /** System actions waiting for their `result`. */
+    requests = new Map();
+    /** A tray keeps the host running after the last window closes. */
+    hasTray = false;
+    exitWaiters = [];
+    /** @internal */
+    constructor(host, hostPath) {
+        this.host = host;
+        this.hostPath = hostPath;
+    }
+    div(props = {}) {
+        return this.create("div", props);
+    }
+    text(props = {}) {
+        return this.create("text", props);
+    }
+    button(props = {}) {
+        return this.create("Button", props);
+    }
+    input(props = {}) {
+        return this.create("Input", props);
+    }
+    checkbox(props = {}) {
+        return this.create("Checkbox", props);
+    }
+    icon(props = {}) {
+        return this.create("Icon", props);
+    }
+    image(props = {}) {
+        return this.create("Image", props);
+    }
+    switch(props = {}) {
+        return this.create("Switch", props);
+    }
+    radioGroup(props = {}) {
+        return this.create("RadioGroup", props);
+    }
+    select(props = {}) {
+        return this.create("Select", props);
+    }
+    slider(props = {}) {
+        return this.create("Slider", props);
+    }
+    textarea(props = {}) {
+        return this.create("Textarea", props);
+    }
+    /** A modal dialog shown while `open`; append its body as children. */
+    dialog(props = {}) {
+        return this.create("Dialog", props);
+    }
+    /** A list that builds only the rows in view; append one child per row (PROTOCOL.md section 15). */
+    virtualList(props = {}) {
+        return this.create("VirtualList", props);
+    }
+    /** A data table with text cells; it virtualizes its rows. */
+    table(props = {}) {
+        return this.create("Table", props);
+    }
+    /** A tab bar; show the chosen tab's content yourself. */
+    tabs(props = {}) {
+        return this.create("Tabs", props);
+    }
+    /** One tab of a `Tabs`; append the nodes of its chip (an `Icon`, a `text`, a `Tag`…; a last `Button` is drawn after them). */
+    tab(props = {}) {
+        return this.create("Tab", props);
+    }
+    /** A menu bar: one button per menu (PROTOCOL.md section 10). */
+    menuBar(props = {}) {
+        return this.create("MenuBar", props);
+    }
+    /** An inline message; `close` when it is `closable` (PROTOCOL.md section 17). */
+    alert(props = {}) {
+        return this.create("Alert", props);
+    }
+    /** A count, a dot or an icon over its children. */
+    badge(props = {}) {
+        return this.create("Badge", props);
+    }
+    tag(props = {}) {
+        return this.create("Tag", props);
+    }
+    /** A key or shortcut, such as `ctrl-s`. */
+    kbd(props = {}) {
+        return this.create("Kbd", props);
+    }
+    /** A progress bar: `value` from 0 to 100. */
+    progress(props = {}) {
+        return this.create("Progress", props);
+    }
+    /** A spinner; give it a size with `class` (`size-4`). */
+    spinner(props = {}) {
+        return this.create("Spinner", props);
+    }
+    /** A loading placeholder. */
+    skeleton(props = {}) {
+        return this.create("Skeleton", props);
+    }
+    /** Stars: `change` with the chosen count. */
+    rating(props = {}) {
+        return this.create("Rating", props);
+    }
+    /** Page navigation: `change` with the chosen page (1-based). */
+    pagination(props = {}) {
+        return this.create("Pagination", props);
+    }
+    /** Content shown while `open`; toggle it with anything that takes a click. */
+    collapsible(props = {}) {
+        return this.create("Collapsible", props);
+    }
+    /** Sections as `items`; `change` with the id of the one toggled. */
+    accordion(props = {}) {
+        return this.create("Accordion", props);
+    }
+    /** A user picture, or their initial. */
+    avatar(props = {}) {
+        return this.create("Avatar", props);
+    }
+    /** A step indicator: `change` with the chosen step's `value`. */
+    stepper(props = {}) {
+        return this.create("Stepper", props);
+    }
+    /** A text field with increment and decrement buttons. */
+    numberInput(props = {}) {
+        return this.create("NumberInput", props);
+    }
+    /** A one-time code, one cell per digit. */
+    otpInput(props = {}) {
+        return this.create("OtpInput", props);
+    }
+    /** A form; append `Field`s to it. */
+    form(props = {}) {
+        return this.create("Form", props);
+    }
+    /** A label, an optional description and its children as the control. */
+    field(props = {}) {
+        return this.create("Field", props);
+    }
+    /** A titled box; append its content. */
+    groupBox(props = {}) {
+        return this.create("GroupBox", props);
+    }
+    /** Key-value rows. */
+    descriptionList(props = {}) {
+        return this.create("DescriptionList", props);
+    }
+    /** A status bar with text on the left and on the right. */
+    statusBar(props = {}) {
+        return this.create("StatusBar", props);
+    }
+    /** A toolbar; append its content. */
+    toolbar(props = {}) {
+        return this.create("Toolbar", props);
+    }
+    /** Panels the user can resize; append one child per panel. */
+    resizable(props = {}) {
+        return this.create("Resizable", props);
+    }
+    /** A month view: `change` with the chosen day (`YYYY-MM-DD`). */
+    calendar(props = {}) {
+        return this.create("Calendar", props);
+    }
+    /** Items in props; `change` with the chosen item's id, `expand`/`collapse` with a folder's id. */
+    tree(props = {}) {
+        return this.create("Tree", props);
+    }
+    /** A parsed patch; `change` with the selected lines. */
+    diff(props = {}) {
+        return this.create("Diff", props);
+    }
+    /** Slides as children; `change` with the selected index. */
+    carousel(props = {}) {
+        return this.create("Carousel", props);
+    }
+    /** Sections of entries in props; `change` with the clicked entry's id. */
+    sidebar(props = {}) {
+        return this.create("Sidebar", props);
+    }
+    /** A line, bar or pie chart of the points in `data`. */
+    chart(props = {}) {
+        return this.create("Chart", props);
+    }
+    /** A node of any type; the specific methods below only add typing. */
+    create(type, props = {}) {
+        return new UINode(this, this.wire.create(type, { ...props }), type);
+    }
+    /** Creates or updates the main window (window 1). It opens on the first commit that sets `root`. */
+    window(options) {
+        this.queueWindow(undefined, options);
+        return this;
+    }
+    /** Another window, with its own root; it opens on the first commit that sets `root`. */
+    createWindow(options = {}) {
+        const window = new AppWindow(this, this.nextWindowId++);
+        this.windows.set(window.id, window);
+        return window.set(options);
+    }
+    /** @internal */
+    queueWindow(id, options) {
+        const { root, ...rest } = options;
+        this.wire.queue({ op: "window", ...(id !== undefined && { id }), ...rest, ...(root && { root: root.id }) });
+        if (root)
+            this.openWindows.add(id ?? 1);
+    }
+    /** @internal */
+    queueCloseWindow(id) {
+        this.wire.queue({ op: "closeWindow", id });
+        this.openWindows.delete(id);
+    }
+    /** Native "open" dialog; resolves with the chosen paths, or `null` if cancelled. */
+    async openDialog(options = {}) {
+        return (await this.request({ op: "openDialog", request: 0, ...options })).paths ?? null;
+    }
+    /** Native "save" dialog; resolves with the chosen path, or `null` if cancelled. */
+    async saveDialog(options = {}) {
+        return (await this.request({ op: "saveDialog", request: 0, ...options })).path ?? null;
+    }
+    /** The clipboard's text, or `null` if it holds none. */
+    async readClipboard() {
+        return (await this.request({ op: "readClipboard", request: 0 })).text ?? null;
+    }
+    /** Shows a toast now (not on commit). */
+    notify(options) {
+        this.action({ op: "notify", ...options });
+    }
+    writeClipboard(text) {
+        this.action({ op: "writeClipboard", text });
+    }
+    /** Opens a URL with the system's handler (the browser for http). */
+    openUrl(url) {
+        this.action({ op: "openUrl", url });
+    }
+    /** Opens a file or folder with its default app. */
+    openPath(path) {
+        this.action({ op: "openPath", path });
+    }
+    /** Actions run when the host gets them, not on commit. */
+    action(message) {
+        if (this.exitInfo)
+            throw new HostExitedError(describeExit(this.exitInfo, this.hostPath), this.exitInfo);
+        this.host.send(message);
+    }
+    request(message) {
+        const request = this.nextRequest++;
+        return new Promise((resolve, reject) => {
+            this.action({ ...message, request });
+            this.requests.set(request, { resolve, reject });
+        });
+    }
+    /** App-wide keyboard shortcuts (`ctrl-s`, `f5`…), applied on the next commit; replaces the list. */
+    shortcuts(keys) {
+        this.wire.queue({ op: "shortcuts", keys });
+        return this;
+    }
+    /** Shows or updates the system tray icon on the next commit. */
+    tray(options) {
+        this.wire.queue({ op: "tray", ...options });
+        this.hasTray = true;
+        return this;
+    }
+    /** Removes the tray icon on the next commit; with no window open, the host then exits. */
+    removeTray() {
+        this.wire.queue({ op: "removeTray" });
+        this.hasTray = false;
+        if (this.openWindows.size === 0)
+            this.closing = true;
+        return this;
+    }
+    /** Sends every pending operation; the host renders once per commit. */
+    commit() {
+        if (this.exitInfo)
+            throw new HostExitedError(describeExit(this.exitInfo, this.hostPath), this.exitInfo);
+        this.wire.commit((message) => this.host.send(message));
+    }
+    on(event, listener) {
+        this.listeners[event].add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.listeners[event].delete(listener);
+        return this;
+    }
+    /** Closes the connection; resolves when the host has exited. */
+    close() {
+        this.closing = true;
+        this.host.close();
+        return this.exited();
+    }
+    /** Resolves when the host process has exited, for any reason. */
+    exited() {
+        if (this.exitInfo)
+            return Promise.resolve(this.exitInfo);
+        return new Promise((resolve) => this.exitWaiters.push(resolve));
+    }
+    /** @internal */
+    handleMessage(message) {
+        switch (message.type) {
+            case "event": {
+                const handler = this.wire.handler(message.id, message.event);
+                if (!handler)
+                    return;
+                const type = this.wire.type(message.id);
+                const payload = message.event === "menu"
+                    ? { item: message.value ?? "" }
+                    : message.event === "keyDown"
+                        ? { key: message.value ?? "" }
+                        : message.event === "drop"
+                            ? { paths: message.paths ?? [] }
+                            : message.event === "sort"
+                                ? message.value
+                                : type === "Checkbox" || type === "Switch"
+                                    ? { checked: message.checked ?? false }
+                                    : message.value !== undefined
+                                        ? { value: message.value }
+                                        : type === "Input" || type === "Textarea"
+                                            ? { value: "" }
+                                            : {};
+                handler(payload);
+                return;
+            }
+            case "error": {
+                const error = { code: message.code, message: message.message, op: message.op };
+                // A rejected system action: its promise fails instead of waiting for a result.
+                const pending = message.request !== undefined ? this.requests.get(message.request) : undefined;
+                if (pending) {
+                    this.requests.delete(message.request);
+                    pending.reject(Object.assign(new Error(`gpui-bridge: host rejected '${error.op}': ${error.message}`), { host: error }));
+                    return;
+                }
+                if (!this.emit("error", error))
+                    console.warn(`gpui-bridge: host rejected '${error.op}': ${error.message}`);
+                return;
+            }
+            case "windowClosed":
+                this.openWindows.delete(message.id);
+                // The host exits after the last window, unless there is a tray.
+                if (this.openWindows.size === 0 && !this.hasTray)
+                    this.closing = true;
+                this.windows.get(message.id)?.handleClosed();
+                this.emit("windowClosed", { id: message.id });
+                return;
+            case "windowEvent": {
+                const payload = {
+                    id: message.id,
+                    event: message.event,
+                    x: message.x,
+                    y: message.y,
+                    width: message.width,
+                    height: message.height,
+                    visible: message.visible,
+                };
+                this.windows.get(message.id)?.handleWindowEvent(payload);
+                this.emit("windowEvent", payload);
+                return;
+            }
+            case "result":
+                this.requests.get(message.request)?.resolve(message);
+                this.requests.delete(message.request);
+                return;
+            case "notification":
+                this.emit("notification", { id: message.id, window: message.window });
+                return;
+            case "shortcut":
+                this.emit("shortcut", { keys: message.keys, window: message.window });
+                return;
+            case "tray":
+                this.emit("tray", message.event === "menu" ? { event: "menu", item: message.value ?? "" } : { event: "click" });
+                return;
+            case "ready":
+                return;
+        }
+    }
+    /** @internal */
+    handleExit(exit) {
+        this.exitInfo = exit;
+        // An exit after close() or windowClosed is expected; anything else is a crash.
+        const unexpected = !this.closing;
+        if (!this.emit("exit", exit) && unexpected)
+            console.error(describeExit(exit, this.hostPath));
+        for (const resolve of this.exitWaiters.splice(0))
+            resolve(exit);
+        for (const { reject } of this.requests.values())
+            reject(new HostExitedError(describeExit(exit, this.hostPath), exit));
+        this.requests.clear();
+    }
+    emit(event, payload) {
+        for (const listener of this.listeners[event])
+            listener(payload);
+        return this.listeners[event].size > 0;
+    }
+}
+/**
+ * Starts the host through `start` and completes the handshake. Rejects with a
+ * clear message if the host cannot start.
+ */
+export function connect(hostPath, start) {
+    return new Promise((resolve, reject) => {
+        let app;
+        let ready = false;
+        const timer = setTimeout(() => {
+            host.kill();
+            reject(new Error(`gpui-bridge host did not answer the handshake within ${HANDSHAKE_TIMEOUT_MS} ms`));
+        }, HANDSHAKE_TIMEOUT_MS);
+        const host = start({
+            onMessage(message) {
+                if (ready)
+                    return app.handleMessage(message);
+                if (message.type === "ready") {
+                    ready = true;
+                    clearTimeout(timer);
+                    resolve(app);
+                }
+                else if (message.type === "error") {
+                    clearTimeout(timer);
+                    reject(new Error(`gpui-bridge handshake failed (${message.code}): ${message.message}`));
+                }
+            },
+            onCorruptLine(line) {
+                console.error(`gpui-bridge: host wrote a non-protocol line to stdout: ${line}`);
+            },
+            onExit(exit) {
+                if (ready)
+                    return app.handleExit(exit);
+                clearTimeout(timer);
+                reject(new HostExitedError(describeExit(exit, hostPath), exit));
+            },
+        });
+        app = new App(host, hostPath);
+        host.send({ op: "hello", protocol: PROTOCOL_VERSION });
+    });
+}

package/dist/host-process.d.ts

@@ -0,0 +1,18 @@
+import type { HostEvents, HostTransport } from "./app.js";
+import type { ClientMessage } from "./protocol.js";
+export interface HostProcessOptions extends HostEvents {
+    path: string;
+    args: string[];
+    debug: boolean;
+}
+export declare class HostProcess implements HostTransport {
+    private readonly child;
+    private readonly stderrTail;
+    private exited;
+    constructor(options: HostProcessOptions);
+    get running(): boolean;
+    send(message: ClientMessage): void;
+    /** Closes stdin; the host exits on EOF. */
+    close(): void;
+    kill(): void;
+}

package/dist/host-process.js

@@ -0,0 +1,56 @@
+// Spawns the host binary and speaks JSON Lines over its stdin/stdout.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const STDERR_TAIL_LINES = 20;
+export class HostProcess {
+    child;
+    stderrTail = [];
+    exited = false;
+    constructor(options) {
+        this.child = spawn(options.path, options.args, { stdio: ["pipe", "pipe", "pipe"] });
+        createInterface({ input: this.child.stdout }).on("line", (line) => {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                options.onCorruptLine(line);
+                return;
+            }
+            options.onMessage(message);
+        });
+        createInterface({ input: this.child.stderr }).on("line", (line) => {
+            this.stderrTail.push(line);
+            if (this.stderrTail.length > STDERR_TAIL_LINES)
+                this.stderrTail.shift();
+            if (options.debug)
+                console.error(`[host] ${line}`);
+        });
+        // Writes racing a dying host fail with EPIPE; the exit handler reports the real cause.
+        this.child.stdin.on("error", () => { });
+        const finish = (exit) => {
+            if (this.exited)
+                return;
+            this.exited = true;
+            options.onExit({ ...exit, stderrTail: [...this.stderrTail] });
+        };
+        this.child.on("error", (spawnError) => finish({ code: null, signal: null, spawnError }));
+        // "close" (not "exit") so all stdout/stderr lines are delivered first.
+        this.child.on("close", (code, signal) => finish({ code, signal }));
+    }
+    get running() {
+        return !this.exited;
+    }
+    send(message) {
+        if (this.exited)
+            return;
+        this.child.stdin.write(JSON.stringify(message) + "\n");
+    }
+    /** Closes stdin; the host exits on EOF. */
+    close() {
+        this.child.stdin.end();
+    }
+    kill() {
+        this.child.kill();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { type App } from "./app.js";
+export * from "./app.js";
+export * from "./protocol.js";
+export interface AppOptions {
+    /** Host binary. Defaults to `$GPUI_BRIDGE_HOST`, then the platform package installed with this one, then the debug build in this repository. */
+    hostPath?: string;
+    /** Forward host logs (stderr) to the console. */
+    debug?: boolean;
+    /** Run the host without a window (`--no-window`), e.g. for tests. */
+    headless?: boolean;
+}
+/** The host to run: `$GPUI_BRIDGE_HOST`, then the packaged one, then a build in this repository. */
+export declare function defaultHostPath(): string;
+/** Starts the host and completes the handshake. Rejects with a clear message if the host cannot start. */
+export declare function createApp(options?: AppOptions): Promise<App>;