gpui-bridge 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gpui-bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# gpui-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native desktop UIs with [GPUI](https://www.gpui.rs/) (the UI framework of the Zed editor) and
+[gpui-kit](https://gpui-kit.com/), driven from JavaScript or
+TypeScript. This package is the Node.js client; a Rust host owns the window, the event loop and
+the component tree, and they talk over stdin/stdout with JSON Lines.
+
+```ts
+import { createApp } from "gpui-bridge";
+
+const app = await createApp();
+let count = 0;
+const label = app.text({ content: "0", class: "text-xl font-bold" });
+const add = app.button({ label: "Add", variant: "primary" }).on("click", () => {
+  label.set({ content: String(++count) });
+  app.commit();
+});
+app.window({ title: "Counter", width: 320, height: 200, root: app.div({ class: "flex flex-col items-center gap-4 p-6 size-full" }).append(label, add) });
+app.commit();
+```
+
+## Install
+
+```sh
+npm install gpui-bridge
+```
+
+The package pulls in an optimized `gpui-bridge-host` binary for the machine installing it: the
+npm package `@indios/gpui-bridge-<platform>-<arch>` (`@indios/gpui-bridge-win32-x64`, `@indios/gpui-bridge-linux-x64`,
+`@indios/gpui-bridge-darwin-arm64`) is an optional dependency, so only the host this machine can run is
+downloaded. No Rust toolchain is needed at runtime — except on a platform without a package
+yet: set `GPUI_BRIDGE_HOST` to a host built from the repository. Node.js 22.6+ (or
+[txiki.js](https://github.com/saghul/txiki.js) through `gpui-bridge/dist/txiki.js`).
+
+Styles are Tailwind-like class strings that use the theme's colors, so light and dark mode and
+custom themes come for free. Props, events and every node type are typed.
+
+## Host lookup
+
+1. `createApp({ hostPath })`
+2. `$GPUI_BRIDGE_HOST`
+3. `@indios/gpui-bridge-<platform>-<arch>/bin/gpui-bridge-host[.exe]`, the platform package installed
+   with this one (`defaultHostPath()` reports the path that wins)
+4. A Cargo build in `target/debug` or `target/release`, searched upwards (a checkout)
+
+The platform package's `bin/host.json` records the host version, protocol version and target it
+was built for; include it in a bug report.
+
+## Links
+
+- [Protocol specification](https://github.com/InDIOS/gpui-bridge/blob/main/docs/PROTOCOL.md),
+  for writing a client in another language.
+- [React renderer](https://www.npmjs.com/package/gpui-bridge-react) on top of this client.
+- Examples and the rest of the repository:
+  [InDIOS/gpui-bridge](https://github.com/InDIOS/gpui-bridge).
+
+Protocol version 1. MIT licensed.

package/dist/app.d.ts

@@ -0,0 +1,329 @@
+import { type ClientMessage, type ErrorCode, type HostMessage, type MenuItem, type NodeEvents, type NodeId, type NodeProps, type NodeType, type ThemeSet, type WindowEventName, type WindowId, type WindowTheme } from "./protocol.js";
+import { Tree } from "./tree.js";
+export interface HostExit {
+    code: number | null;
+    signal: string | null;
+    /** Last lines the host wrote to stderr, for crash reports. */
+    stderrTail: string[];
+    /** Set when the process could not be started at all (e.g. binary not found). */
+    spawnError?: Error;
+}
+/** A running host process, as seen by the client core. */
+export interface HostTransport {
+    send(message: ClientMessage): void;
+    /** Closes stdin; the host exits on EOF. */
+    close(): void;
+    kill(): void;
+}
+/** What a transport reports back while the host runs. */
+export interface HostEvents {
+    onMessage(message: HostMessage): void;
+    /** stdout carried something that is not a protocol message. */
+    onCorruptLine(line: string): void;
+    onExit(exit: HostExit): void;
+}
+export interface WindowOptions {
+    title?: string;
+    width?: number;
+    height?: number;
+    /** Initial position. Only read when the window opens. */
+    x?: number;
+    y?: number;
+    /** Minimum size the user can resize to. Only read when the window opens. */
+    minWidth?: number;
+    minHeight?: number;
+    root?: UINode<NodeType>;
+    theme?: WindowTheme;
+    themeSet?: ThemeSet;
+    /** No system title bar (draw your own with `windowControl` divs). Only read when the window opens. */
+    frameless?: boolean;
+    /** Minimizes (`true`) or restores (`false`) on the next commit. An action, not a remembered state. */
+    minimized?: boolean;
+    /** Window events to receive; `AppWindow.on` sets this for you. Replaces the previous list. */
+    events?: WindowEventName[];
+}
+/** A window event (PROTOCOL.md section 3); only the ones the window subscribed to arrive. */
+export interface WindowEventPayload {
+    id: WindowId;
+    event: WindowEventName;
+    /** `move` and `resize`: the window's bounds. */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** `visibility`: whether the window is being presented. */
+    visible?: boolean;
+}
+/** A toast (PROTOCOL.md section 14). */
+export interface NotifyOptions {
+    message: string;
+    title?: string;
+    type?: "info" | "success" | "warning" | "error";
+    /** Default window 1. */
+    window?: WindowId;
+    /** Lets a click be reported (`notification` event); a new toast with the same id replaces it. */
+    id?: string;
+    /** Default true. */
+    autohide?: boolean;
+    /** Also post it to the Windows notification center. */
+    system?: boolean;
+}
+/** `openDialog` options (PROTOCOL.md section 13). Default: one file. */
+export interface OpenDialogOptions {
+    files?: boolean;
+    directories?: boolean;
+    multiple?: boolean;
+    /** The confirm button's text. */
+    prompt?: string;
+}
+/** `saveDialog` options. */
+export interface SaveDialogOptions {
+    /** Where the dialog starts; default the host's working directory. */
+    directory?: string;
+    /** Suggested file name. */
+    name?: string;
+}
+/** The system tray icon (PROTOCOL.md section 11). Each call updates only the fields it passes. */
+export interface TrayOptions {
+    /** An image file (PNG, ICO…), drawn at the tray's size. */
+    icon?: string;
+    tooltip?: string;
+    /** Opens on right-click; a native menu, so item icons are not drawn. */
+    menu?: MenuItem[];
+}
+/** An `error` message from the host: the operation was rejected, the host keeps running. */
+export interface HostError {
+    code: ErrorCode;
+    message: string;
+    op?: string;
+}
+interface AppEvents {
+    error: HostError;
+    /** The user closed a window. */
+    windowClosed: {
+        id: WindowId;
+    };
+    /** A window event the client subscribed to (`window.events`, or `AppWindow.on` for that window). */
+    windowEvent: WindowEventPayload;
+    /** The user clicked a toast that has an `id`. */
+    notification: {
+        id: string;
+        window: WindowId;
+    };
+    /** A key registered with `shortcuts()` was pressed in window `window`. */
+    shortcut: {
+        keys: string;
+        window: WindowId;
+    };
+    /** The user clicked the tray icon (`click`) or chose an item of its menu (`menu`, with the item id). */
+    tray: {
+        event: "click";
+    } | {
+        event: "menu";
+        item: string;
+    };
+    exit: HostExit;
+}
+/** `setProps` input: `null` removes a prop. */
+export type PropsUpdate<T extends NodeType> = {
+    [K in keyof NodeProps[T]]?: NodeProps[T][K] | null;
+};
+export declare class HostExitedError extends Error {
+    readonly exit: HostExit;
+    constructor(message: string, exit: HostExit);
+}
+export declare class UINode<T extends NodeType> {
+    private readonly app;
+    readonly id: NodeId;
+    readonly type: T;
+    /** @internal */
+    constructor(app: App, id: NodeId, type: T);
+    append(...children: UINode<NodeType>[]): this;
+    insertBefore(child: UINode<NodeType>, before: UINode<NodeType>): this;
+    /** Merges props; `null` removes one. */
+    set(props: PropsUpdate<T>): this;
+    /** Subscribes to an event; the host only emits subscribed events. */
+    on<E extends keyof NodeEvents[T] & string>(event: E, handler: (payload: NodeEvents[T][E]) => void): this;
+    off<E extends keyof NodeEvents[T] & string>(event: E): this;
+    /** Gives the node the keyboard focus on the next commit (an Input, a Textarea or a div with `keyDown`). */
+    focus(): this;
+    /** Removes the node and all its descendants. */
+    remove(): void;
+}
+/** A window other than the main one (`App.createWindow`). */
+export declare class AppWindow {
+    private readonly app;
+    readonly id: WindowId;
+    private readonly closedListeners;
+    private readonly eventListeners;
+    /** The subscription list last sent, to avoid one message per listener. */
+    private eventNames;
+    /** @internal */
+    constructor(app: App, id: WindowId);
+    /** Updates the window; like `App.window`, it opens on the first commit that sets `root`. */
+    set(options: WindowOptions): this;
+    /** Closes the window on the next commit. No `closed` event follows: that is only for the user closing it. */
+    close(): void;
+    /** The user closed the window, or a window event (which the window subscribes to on commit). */
+    on(event: "closed", listener: () => void): this;
+    on(event: WindowEventName, listener: (payload: WindowEventPayload) => void): this;
+    off(event: "closed", listener: () => void): this;
+    off(event: WindowEventName, listener: (payload: WindowEventPayload) => void): this;
+    /** @internal */
+    handleClosed(): void;
+    /** @internal */
+    handleWindowEvent(payload: WindowEventPayload): void;
+    /** Sends the subscription list only when the set of subscribed events changes. */
+    private syncEvents;
+}
+export declare class App {
+    private readonly host;
+    private readonly hostPath;
+    /** @internal Protocol operations queued until `commit`. */
+    readonly wire: Tree;
+    private readonly listeners;
+    private exitInfo?;
+    private closing;
+    private nextWindowId;
+    private readonly windows;
+    /** Windows given a root and not closed: the host exits when the user closes the last one. */
+    private readonly openWindows;
+    private nextRequest;
+    /** System actions waiting for their `result`. */
+    private readonly requests;
+    /** A tray keeps the host running after the last window closes. */
+    private hasTray;
+    private readonly exitWaiters;
+    /** @internal */
+    constructor(host: HostTransport, hostPath: string);
+    div(props?: NodeProps["div"]): UINode<"div">;
+    text(props?: NodeProps["text"]): UINode<"text">;
+    button(props?: NodeProps["Button"]): UINode<"Button">;
+    input(props?: NodeProps["Input"]): UINode<"Input">;
+    checkbox(props?: NodeProps["Checkbox"]): UINode<"Checkbox">;
+    icon(props?: NodeProps["Icon"]): UINode<"Icon">;
+    image(props?: NodeProps["Image"]): UINode<"Image">;
+    switch(props?: NodeProps["Switch"]): UINode<"Switch">;
+    radioGroup(props?: NodeProps["RadioGroup"]): UINode<"RadioGroup">;
+    select(props?: NodeProps["Select"]): UINode<"Select">;
+    slider(props?: NodeProps["Slider"]): UINode<"Slider">;
+    textarea(props?: NodeProps["Textarea"]): UINode<"Textarea">;
+    /** A modal dialog shown while `open`; append its body as children. */
+    dialog(props?: NodeProps["Dialog"]): UINode<"Dialog">;
+    /** A list that builds only the rows in view; append one child per row (PROTOCOL.md section 15). */
+    virtualList(props?: NodeProps["VirtualList"]): UINode<"VirtualList">;
+    /** A data table with text cells; it virtualizes its rows. */
+    table(props?: NodeProps["Table"]): UINode<"Table">;
+    /** A tab bar; show the chosen tab's content yourself. */
+    tabs(props?: NodeProps["Tabs"]): UINode<"Tabs">;
+    /** 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?: NodeProps["Tab"]): UINode<"Tab">;
+    /** A menu bar: one button per menu (PROTOCOL.md section 10). */
+    menuBar(props?: NodeProps["MenuBar"]): UINode<"MenuBar">;
+    /** An inline message; `close` when it is `closable` (PROTOCOL.md section 17). */
+    alert(props?: NodeProps["Alert"]): UINode<"Alert">;
+    /** A count, a dot or an icon over its children. */
+    badge(props?: NodeProps["Badge"]): UINode<"Badge">;
+    tag(props?: NodeProps["Tag"]): UINode<"Tag">;
+    /** A key or shortcut, such as `ctrl-s`. */
+    kbd(props?: NodeProps["Kbd"]): UINode<"Kbd">;
+    /** A progress bar: `value` from 0 to 100. */
+    progress(props?: NodeProps["Progress"]): UINode<"Progress">;
+    /** A spinner; give it a size with `class` (`size-4`). */
+    spinner(props?: NodeProps["Spinner"]): UINode<"Spinner">;
+    /** A loading placeholder. */
+    skeleton(props?: NodeProps["Skeleton"]): UINode<"Skeleton">;
+    /** Stars: `change` with the chosen count. */
+    rating(props?: NodeProps["Rating"]): UINode<"Rating">;
+    /** Page navigation: `change` with the chosen page (1-based). */
+    pagination(props?: NodeProps["Pagination"]): UINode<"Pagination">;
+    /** Content shown while `open`; toggle it with anything that takes a click. */
+    collapsible(props?: NodeProps["Collapsible"]): UINode<"Collapsible">;
+    /** Sections as `items`; `change` with the id of the one toggled. */
+    accordion(props?: NodeProps["Accordion"]): UINode<"Accordion">;
+    /** A user picture, or their initial. */
+    avatar(props?: NodeProps["Avatar"]): UINode<"Avatar">;
+    /** A step indicator: `change` with the chosen step's `value`. */
+    stepper(props?: NodeProps["Stepper"]): UINode<"Stepper">;
+    /** A text field with increment and decrement buttons. */
+    numberInput(props?: NodeProps["NumberInput"]): UINode<"NumberInput">;
+    /** A one-time code, one cell per digit. */
+    otpInput(props?: NodeProps["OtpInput"]): UINode<"OtpInput">;
+    /** A form; append `Field`s to it. */
+    form(props?: NodeProps["Form"]): UINode<"Form">;
+    /** A label, an optional description and its children as the control. */
+    field(props?: NodeProps["Field"]): UINode<"Field">;
+    /** A titled box; append its content. */
+    groupBox(props?: NodeProps["GroupBox"]): UINode<"GroupBox">;
+    /** Key-value rows. */
+    descriptionList(props?: NodeProps["DescriptionList"]): UINode<"DescriptionList">;
+    /** A status bar with text on the left and on the right. */
+    statusBar(props?: NodeProps["StatusBar"]): UINode<"StatusBar">;
+    /** A toolbar; append its content. */
+    toolbar(props?: NodeProps["Toolbar"]): UINode<"Toolbar">;
+    /** Panels the user can resize; append one child per panel. */
+    resizable(props?: NodeProps["Resizable"]): UINode<"Resizable">;
+    /** A month view: `change` with the chosen day (`YYYY-MM-DD`). */
+    calendar(props?: NodeProps["Calendar"]): UINode<"Calendar">;
+    /** Items in props; `change` with the chosen item's id, `expand`/`collapse` with a folder's id. */
+    tree(props?: NodeProps["Tree"]): UINode<"Tree">;
+    /** A parsed patch; `change` with the selected lines. */
+    diff(props?: NodeProps["Diff"]): UINode<"Diff">;
+    /** Slides as children; `change` with the selected index. */
+    carousel(props?: NodeProps["Carousel"]): UINode<"Carousel">;
+    /** Sections of entries in props; `change` with the clicked entry's id. */
+    sidebar(props?: NodeProps["Sidebar"]): UINode<"Sidebar">;
+    /** A line, bar or pie chart of the points in `data`. */
+    chart(props?: NodeProps["Chart"]): UINode<"Chart">;
+    /** A node of any type; the specific methods below only add typing. */
+    create<T extends NodeType>(type: T, props?: NodeProps[T]): UINode<T>;
+    /** Creates or updates the main window (window 1). It opens on the first commit that sets `root`. */
+    window(options: WindowOptions): this;
+    /** Another window, with its own root; it opens on the first commit that sets `root`. */
+    createWindow(options?: WindowOptions): AppWindow;
+    /** @internal */
+    queueWindow(id: WindowId | undefined, options: WindowOptions): void;
+    /** @internal */
+    queueCloseWindow(id: WindowId): void;
+    /** Native "open" dialog; resolves with the chosen paths, or `null` if cancelled. */
+    openDialog(options?: OpenDialogOptions): Promise<string[] | null>;
+    /** Native "save" dialog; resolves with the chosen path, or `null` if cancelled. */
+    saveDialog(options?: SaveDialogOptions): Promise<string | null>;
+    /** The clipboard's text, or `null` if it holds none. */
+    readClipboard(): Promise<string | null>;
+    /** Shows a toast now (not on commit). */
+    notify(options: NotifyOptions): void;
+    writeClipboard(text: string): void;
+    /** Opens a URL with the system's handler (the browser for http). */
+    openUrl(url: string): void;
+    /** Opens a file or folder with its default app. */
+    openPath(path: string): void;
+    /** Actions run when the host gets them, not on commit. */
+    private action;
+    private request;
+    /** App-wide keyboard shortcuts (`ctrl-s`, `f5`…), applied on the next commit; replaces the list. */
+    shortcuts(keys: string[]): this;
+    /** Shows or updates the system tray icon on the next commit. */
+    tray(options: TrayOptions): this;
+    /** Removes the tray icon on the next commit; with no window open, the host then exits. */
+    removeTray(): this;
+    /** Sends every pending operation; the host renders once per commit. */
+    commit(): void;
+    on<K extends keyof AppEvents>(event: K, listener: (payload: AppEvents[K]) => void): this;
+    off<K extends keyof AppEvents>(event: K, listener: (payload: AppEvents[K]) => void): this;
+    /** Closes the connection; resolves when the host has exited. */
+    close(): Promise<HostExit>;
+    /** Resolves when the host process has exited, for any reason. */
+    exited(): Promise<HostExit>;
+    /** @internal */
+    handleMessage(message: HostMessage): void;
+    /** @internal */
+    handleExit(exit: HostExit): void;
+    private emit;
+}
+/**
+ * Starts the host through `start` and completes the handshake. Rejects with a
+ * clear message if the host cannot start.
+ */
+export declare function connect(hostPath: string, start: (events: HostEvents) => HostTransport): Promise<App>;
+export {};