gpui-bridge 0.2.0__py3-none-win_amd64.whl

gpui_bridge/__init__.py

@@ -0,0 +1,695 @@
+"""gpui-bridge Python client: drives the gpui-bridge host over JSON Lines (stdlib only).
+
+Same model as the Node client: build nodes, queue operations, `commit()` sends
+them in one batch. `run()` blocks and calls event handlers on the calling thread
+until the host exits.
+"""
+
+import json
+import os
+import queue
+import subprocess
+import sys
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PROTOCOL_VERSION = 1
+HANDSHAKE_TIMEOUT = 10.0
+STDERR_TAIL_LINES = 20
+# Window events a client can subscribe to (PROTOCOL.md section 3).
+WINDOW_EVENTS = ("focus", "blur", "resize", "move", "visibility")
+
+
+@dataclass
+class HostExit:
+    code: int | None
+    # Last lines the host wrote to stderr, for crash reports.
+    stderr_tail: list[str]
+
+
+@dataclass
+class HostError:
+    """An `error` message from the host: the operation was rejected, the host keeps running."""
+
+    code: str
+    message: str
+    op: str | None = None
+
+
+class HostExitedError(Exception):
+    def __init__(self, message: str, exit: HostExit):
+        super().__init__(message)
+        self.exit = exit
+
+
+@dataclass
+class _Record:
+    type: str
+    parent: int | None = None
+    children: set[int] = field(default_factory=set)
+    handlers: dict = field(default_factory=dict)
+
+
+def default_host_path() -> str:
+    """`$GPUI_BRIDGE_HOST`, then the host bundled in this package, then a Cargo build in this repository."""
+    if env := os.environ.get("GPUI_BRIDGE_HOST"):
+        return env
+    exe = "gpui-bridge-host.exe" if sys.platform == "win32" else "gpui-bridge-host"
+    package = Path(__file__).resolve().parent
+    # build_wheel.py puts the optimized host in bin/; a checkout of this repository has none.
+    bundled = package / "bin" / exe
+    if bundled.exists():
+        return str(bundled)
+    # Walk up for the workspace `target/`: how many folders separate this client from the
+    # repository root is not part of the contract, so a move must not break the lookup.
+    for parent in package.parents:
+        for profile in ("debug", "release"):
+            candidate = parent / "target" / profile / exe
+            if candidate.exists():
+                return str(candidate)
+    return str(package.parents[2] / "target" / "debug" / exe)
+
+
+def _props(kwargs: dict) -> dict:
+    # `class` is a Python keyword, so callers write `class_`.
+    return {key.rstrip("_"): value for key, value in kwargs.items()}
+
+
+def _describe_exit(exit: HostExit) -> str:
+    tail = "\nLast host output:\n  " + "\n  ".join(exit.stderr_tail) if exit.stderr_tail else ""
+    return f"gpui-bridge host exited (code {exit.code}).{tail}"
+
+
+class Node:
+    def __init__(self, app: "App", id: int, type: str):
+        self._app = app
+        self.id = id
+        self.type = type
+
+    def append(self, *children: "Node") -> "Node":
+        for child in children:
+            self._app._pending.append({"op": "append", "parent": self.id, "child": child.id})
+            self._app._attach(self.id, child.id)
+        return self
+
+    def insert_before(self, child: "Node", before: "Node") -> "Node":
+        self._app._pending.append({"op": "insertBefore", "parent": self.id, "child": child.id, "before": before.id})
+        self._app._attach(self.id, child.id)
+        return self
+
+    def set(self, **props) -> "Node":
+        """Merges props; `None` removes one."""
+        self._app._pending.append({"op": "setProps", "id": self.id, "props": _props(props)})
+        return self
+
+    def on(self, event: str, handler) -> "Node":
+        """Subscribes to an event. Handlers get the Input text, the Checkbox state, or nothing (click)."""
+        self._app._set_handler(self.id, event, handler)
+        return self
+
+    def off(self, event: str) -> "Node":
+        self._app._set_handler(self.id, event, None)
+        return self
+
+    def focus(self) -> "Node":
+        """Gives the node the keyboard focus on the next commit (an Input, a Textarea or a div with keyDown)."""
+        self._app._pending.append({"op": "focus", "id": self.id})
+        return self
+
+    def remove(self) -> None:
+        """Removes the node and all its descendants."""
+        self._app._remove(self.id)
+
+
+class Window:
+    """A window other than the main one (`App.create_window`)."""
+
+    def __init__(self, app: "App", window_id: int):
+        self._app = app
+        self.id = window_id
+        self.on_closed = None  # () -> None; the user closed the window
+        self._handlers: dict = {}  # window event -> handler
+        self._events_sent: list[str] = []
+
+    def set(self, *, root: Node | None = None, **options) -> "Window":
+        """Updates the window; like `App.window`, it opens on the first commit that sets `root`."""
+        self._app._queue_window(self.id, root, options)
+        return self
+
+    def close(self) -> None:
+        """Closes the window on the next commit. `on_closed` is not called: it is for the user closing it."""
+        self._app._pending.append({"op": "closeWindow", "id": self.id})
+        self._app._open_windows.discard(self.id)
+
+    def on(self, event: str, handler) -> "Window":
+        """Subscribes to a window event (`focus`, `blur`, `resize`, `move`, `visibility`) or to
+        `closed`. Handlers get the message: bounds for `move`/`resize`, `visible` for `visibility`."""
+        if event == "closed":
+            self.on_closed = handler
+            return self
+        if event not in WINDOW_EVENTS:
+            expected = ", ".join(("closed", *WINDOW_EVENTS))
+            raise ValueError(f"unknown window event '{event}' (expected one of {expected})")
+        self._handlers[event] = handler
+        self._sync_events()
+        return self
+
+    def off(self, event: str) -> "Window":
+        """Unsubscribes; the last one removes the window's event subscription (no messages follow)."""
+        if event == "closed":
+            self.on_closed = None
+            return self
+        self._handlers.pop(event, None)
+        self._sync_events()
+        return self
+
+    def _sync_events(self) -> None:
+        """Sends the subscription list only when the set of subscribed events changes."""
+        events = list(self._handlers)
+        if events != self._events_sent:
+            self._events_sent = events
+            self._app._queue_window(self.id, None, {"events": events})
+
+    def _dispatch_window_event(self, message: dict) -> None:
+        handler = self._handlers.get(message.get("event"))
+        if handler:
+            handler(message)
+
+
+class App:
+    """Starts the host and completes the handshake. Raises with a clear message if the host cannot start."""
+
+    def __init__(self, host_path: str | None = None, *, debug: bool = False, headless: bool = False):
+        self.on_error = None  # (HostError) -> None; without it errors are printed to stderr
+        self.on_window_closed = None  # (window_id) -> None; the user closed a window
+        self.on_window_event = None  # (message) -> None; a window event the app subscribed to
+        self.on_tray = None  # (event, item) -> None; tray "click" (item None) or "menu" (item id)
+        self.on_shortcut = None  # (keys, window_id) -> None; a key registered with shortcuts()
+        self.on_notification = None  # (id, window_id) -> None; the user clicked a toast that has an id
+        self._has_tray = False  # a tray keeps the host running after the last window closes
+        self._next_request = 1
+        self._results: dict[int, dict] = {}  # answers that arrived while waiting for another one
+        self._next_id = 1
+        self._nodes: dict[int, _Record] = {}
+        self._pending: list[dict] = []
+        self._inbox: queue.Queue = queue.Queue()
+        self._stderr_tail: deque[str] = deque(maxlen=STDERR_TAIL_LINES)
+        self._exit: HostExit | None = None
+        self._closing = False
+        self._next_window_id = 2
+        self._windows: dict[int, Window] = {}
+        # Windows given a root and not closed: the host exits when the user closes the last one.
+        self._open_windows: set[int] = set()
+
+        path = host_path or default_host_path()
+        args = [path, "--no-window"] if headless else [path]
+        try:
+            self._proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        except FileNotFoundError:
+            raise HostExitedError(
+                f"gpui-bridge host not found at {path}. Build it with `cargo build` in host/ or pass host_path.",
+                HostExit(None, []),
+            ) from None
+
+        self._stderr_thread = threading.Thread(target=self._read_stderr, args=(debug,), daemon=True)
+        self._stderr_thread.start()
+        threading.Thread(target=self._read_stdout, daemon=True).start()
+        self._write([{"op": "hello", "protocol": PROTOCOL_VERSION}])
+        self._handshake()
+
+    def div(self, **props) -> Node:
+        return self._create("div", props)
+
+    def text(self, **props) -> Node:
+        return self._create("text", props)
+
+    def button(self, **props) -> Node:
+        return self._create("Button", props)
+
+    def input(self, **props) -> Node:
+        return self._create("Input", props)
+
+    def checkbox(self, **props) -> Node:
+        return self._create("Checkbox", props)
+
+    def icon(self, **props) -> Node:
+        return self._create("Icon", props)
+
+    def image(self, **props) -> Node:
+        """An image from `src` (a local file) or `data` (standard base64 of the bytes,
+        for images the app downloads itself). `fit` is the CSS `object-fit`."""
+        return self._create("Image", props)
+
+    def switch(self, **props) -> Node:
+        return self._create("Switch", props)
+
+    def radio_group(self, **props) -> Node:
+        """`options=[{"value": ..., "label": ...}]`, `value`, `direction`."""
+        return self._create("RadioGroup", props)
+
+    def select(self, **props) -> Node:
+        """`options=[{"value": ..., "label": ...}]`, `value`, `placeholder`, `searchable`."""
+        return self._create("Select", props)
+
+    def slider(self, **props) -> Node:
+        """`value`, `min` (0), `max` (100), `step` (1); `change` passes a number."""
+        return self._create("Slider", props)
+
+    def textarea(self, **props) -> Node:
+        return self._create("Textarea", props)
+
+    def dialog(self, **props) -> Node:
+        """A modal dialog shown while `open=True`; append its body as children. Events `ok`, `cancel`."""
+        return self._create("Dialog", props)
+
+    def virtual_list(self, **props) -> Node:
+        """A list that draws only the rows in view (PROTOCOL.md section 15): append one child per
+        row; `rowHeight` (32). Give it a height (`class_="flex-1"`)."""
+        return self._create("VirtualList", props)
+
+    def table(self, **props) -> Node:
+        """A data table with text cells: `columns=[{"key": ..., "name": ...}]`, `rows=[{key: cell}]`,
+        `selected`, `stripe`, `bordered`. `change` passes a row index (None when cleared),
+        `doubleClick` a row index, `sort` a dict `{"column": ..., "direction": "asc" | "desc" | "none"}`."""
+        return self._create("Table", props)
+
+    def tabs(self, **props) -> Node:
+        """A tab bar: `tabs=[{"value": ..., "label": ...}]`, `value`, `variant`. Show the content yourself."""
+        return self._create("Tabs", props)
+
+    def tab(self, **props) -> Node:
+        """One tab of a `tabs` bar: `value` (required, not empty), `label` (its text, before the
+        children), `disabled` and `class` (of the chip). Append the nodes of its chip (an `icon`, a
+        `text`, a `tag`; a last `button` is drawn after them); a `Tabs` with `tab` children uses
+        them and ignores `tabs`."""
+        return self._create("Tab", props)
+
+    def menu_bar(self, **props) -> Node:
+        """A menu bar (PROTOCOL.md section 10): `menus=[{"label": ..., "items": [...]}]`."""
+        return self._create("MenuBar", props)
+
+    # gpui-kit's Basic, Form, Layout and Advanced groups (PROTOCOL.md section 17).
+
+    def alert(self, **props) -> Node:
+        """An inline message: `message`, `title`, `variant`, `banner`, `closable`. Event `close`."""
+        return self._create("Alert", props)
+
+    def badge(self, **props) -> Node:
+        """A count (`count`, `max`), a `dot` or an `icon`, over its children."""
+        return self._create("Badge", props)
+
+    def tag(self, **props) -> Node:
+        """`label`, `variant` (primary, secondary, danger, success, warning, info), `outline`, `icon`."""
+        return self._create("Tag", props)
+
+    def kbd(self, **props) -> Node:
+        """A key or shortcut, such as `keys="ctrl-s"`; `outline`."""
+        return self._create("Kbd", props)
+
+    def progress(self, **props) -> Node:
+        """A bar: `value` from 0 to 100, `loading`."""
+        return self._create("Progress", props)
+
+    def spinner(self, **props) -> Node:
+        """A spinner; size it with `class_` (`size-4`)."""
+        return self._create("Spinner", props)
+
+    def skeleton(self, **props) -> Node:
+        """A loading placeholder; size it with `class_`."""
+        return self._create("Skeleton", props)
+
+    def rating(self, **props) -> Node:
+        """Stars: `value`, `max` (5), `controlled`. `change` passes the chosen count."""
+        return self._create("Rating", props)
+
+    def pagination(self, **props) -> Node:
+        """Pages: `page` (1-based), `total`, `compact`, `controlled`. `change` passes the page."""
+        return self._create("Pagination", props)
+
+    def collapsible(self, **props) -> Node:
+        """Content shown while `open`; append it as children."""
+        return self._create("Collapsible", props)
+
+    def accordion(self, **props) -> Node:
+        """Sections as `items=[{"id", "title", "content", "open", "disabled"}]`, `multiple`,
+        `bordered`, `controlled`. `change` passes the id of the section toggled."""
+        return self._create("Accordion", props)
+
+    def avatar(self, **props) -> Node:
+        """A picture from `src`, or the initial of `name`."""
+        return self._create("Avatar", props)
+
+    def stepper(self, **props) -> Node:
+        """Steps as `items=[{"value", "label"}]`, `value`, `vertical`, `controlled`.
+        `change` passes the chosen step's value."""
+        return self._create("Stepper", props)
+
+    def number_input(self, **props) -> Node:
+        """A text field with increment and decrement buttons: `value`, `placeholder`, `controlled`."""
+        return self._create("NumberInput", props)
+
+    def otp_input(self, **props) -> Node:
+        """A one-time code: `length` (6), `value`, `masked`, `controlled`."""
+        return self._create("OtpInput", props)
+
+    def form(self, **props) -> Node:
+        """A form: `direction` ("vertical" or "horizontal"); append `field` nodes."""
+        return self._create("Form", props)
+
+    def field(self, **props) -> Node:
+        """A label, an optional `description`, and its children as the control."""
+        return self._create("Field", props)
+
+    def group_box(self, **props) -> Node:
+        """A titled box: `title`, `variant` (normal, fill, outline); append its content."""
+        return self._create("GroupBox", props)
+
+    def description_list(self, **props) -> Node:
+        """Key-value rows: `items=[{"label", "value", "span"}]`, `columns`, `bordered`, `horizontal`."""
+        return self._create("DescriptionList", props)
+
+    def status_bar(self, **props) -> Node:
+        """A status bar: `left` and `right` text."""
+        return self._create("StatusBar", props)
+
+    def toolbar(self, **props) -> Node:
+        """A toolbar; append its content."""
+        return self._create("Toolbar", props)
+
+    def resizable(self, **props) -> Node:
+        """Panels the user can resize: `axis` (horizontal or vertical), `sizes` in pixels. Append
+        one child per panel."""
+        return self._create("Resizable", props)
+
+    def calendar(self, **props) -> Node:
+        """A month view: `value` ("YYYY-MM-DD"), `months`, `weekStartsOn`, `controlled`.
+        `change` passes the chosen day."""
+        return self._create("Calendar", props)
+
+    def tree(self, **props) -> Node:
+        """Items in props: `items=[{"id", "label", "children", "expanded", "disabled"}]`, `value`
+        (the selected item id), `controlled`. `change` passes the chosen id; `expand` and
+        `collapse` pass a folder's id."""
+        return self._create("Tree", props)
+
+    def diff(self, **props) -> Node:
+        """A patch: `patch` (a unified or Git diff), `mode` (unified or split), `lineNumbers`,
+        `softWrap`, `header`. `change` passes the selected lines ({path, side, start, end,
+        endSide}) or None."""
+        return self._create("Diff", props)
+
+    def carousel(self, **props) -> Node:
+        """A carousel: `value` (the selected slide index), `axis`, `looping`, `controls`,
+        `pagination`, `controlled`. Append one child per slide; `change` passes the index."""
+        return self._create("Carousel", props)
+
+    def sidebar(self, **props) -> Node:
+        """A sidebar: `items` (sections: {"label", "items": [{"id", "label", "icon",
+        "disabled", "open", "children"}]}), `value` (the active entry id), `collapsed`,
+        `collapsible` (icon, offcanvas, none), `side` (left, right), `controlled`. `change`
+        passes the clicked entry's id."""
+        return self._create("Sidebar", props)
+
+    def chart(self, **props) -> Node:
+        """A chart: `chart` (line, bar, pie), `data` ([{"label", "value"}]), `color`, `name`,
+        plus the options of each plot (`curve`, `dot`, `horizontal`, `xAxis`, `xTicks`, `yAxis`, `yTicks`, `grid`,
+        `yMin`, `yMax`, `innerRadius`, `padAngle`, `interactive`). It has no events."""
+        return self._create("Chart", props)
+
+    def window(self, *, root: Node | None = None, **options) -> "App":
+        """Creates or updates the main window (window 1). It opens on the first commit that sets `root`."""
+        self._queue_window(None, root, options)
+        return self
+
+    def create_window(self, *, root: Node | None = None, **options) -> Window:
+        """Another window, with its own root; it opens on the first commit that sets `root`."""
+        window = Window(self, self._next_window_id)
+        self._next_window_id += 1
+        self._windows[window.id] = window
+        return window.set(root=root, **options)
+
+    def _queue_window(self, window_id: int | None, root: Node | None, options: dict) -> None:
+        message = {"op": "window", **({"id": window_id} if window_id is not None else {}), **options}
+        if root:
+            message["root"] = root.id
+            self._open_windows.add(window_id or 1)
+        self._pending.append(message)
+
+    def open_dialog(self, *, files: bool = True, directories: bool = False, multiple: bool = False, prompt: str | None = None):
+        """Native "open" dialog: the chosen paths, or None if cancelled. Handlers keep running meanwhile."""
+        options = {"files": files, "directories": directories, "multiple": multiple, **({"prompt": prompt} if prompt else {})}
+        return self._request({"op": "openDialog", **options}, "paths")
+
+    def save_dialog(self, *, directory: str | None = None, name: str | None = None):
+        """Native "save" dialog: the chosen path, or None if cancelled."""
+        options = {key: value for key, value in (("directory", directory), ("name", name)) if value is not None}
+        return self._request({"op": "saveDialog", **options}, "path")
+
+    def read_clipboard(self):
+        """The clipboard's text, or None if it holds none."""
+        return self._request({"op": "readClipboard"}, "text")
+
+    def notify(self, message: str, **options) -> None:
+        """Shows a toast now: `title`, `type`, `window`, `id`, `autohide`, `system`."""
+        self._write([{"op": "notify", "message": message, **options}])
+
+    def write_clipboard(self, text: str) -> None:
+        self._write([{"op": "writeClipboard", "text": text}])
+
+    def open_url(self, url: str) -> None:
+        """Opens a URL with the system's handler (the browser for http)."""
+        self._write([{"op": "openUrl", "url": url}])
+
+    def open_path(self, path: str) -> None:
+        """Opens a file or folder with its default app."""
+        self._write([{"op": "openPath", "path": path}])
+
+    def _request(self, message: dict, key: str):
+        """Sends a system action and waits for its result, dispatching other messages meanwhile."""
+        if self._exit:
+            raise HostExitedError(_describe_exit(self._exit), self._exit)
+        request = self._next_request
+        self._next_request += 1
+        self._write([{**message, "request": request}])
+        while request not in self._results:
+            try:
+                message = self._inbox.get(timeout=0.5)
+            except queue.Empty:
+                continue
+            if isinstance(message, HostExit):
+                self._inbox.put(message)  # left for run()
+                raise HostExitedError(_describe_exit(message), message)
+            if message.get("type") in ("result", "error") and message.get("request") is not None:
+                self._results[message.get("request")] = message
+            else:
+                self._dispatch(message)
+        answer = self._results.pop(request)
+        if answer.get("type") == "error":
+            raise RuntimeError(f"gpui-bridge: host rejected '{answer.get('op')}': {answer.get('message')}")
+        return answer.get(key)
+
+    def shortcuts(self, keys: list[str]) -> "App":
+        """App-wide keyboard shortcuts ("ctrl-s", "f5"...), applied on the next commit; replaces the list."""
+        self._pending.append({"op": "shortcuts", "keys": list(keys)})
+        return self
+
+    def tray(self, **options) -> "App":
+        """Shows or updates the system tray icon (PROTOCOL.md section 11): `icon`, `tooltip`, `menu`."""
+        self._pending.append({"op": "tray", **options})
+        self._has_tray = True
+        return self
+
+    def remove_tray(self) -> "App":
+        """Removes the tray icon on the next commit; with no window open, the host then exits."""
+        self._pending.append({"op": "removeTray"})
+        self._has_tray = False
+        if not self._open_windows:
+            self._closing = True
+        return self
+
+    def commit(self) -> None:
+        """Sends every pending operation; the host renders once per commit."""
+        if self._exit:
+            raise HostExitedError(_describe_exit(self._exit), self._exit)
+        self._write([*self._pending, {"op": "commit"}])
+        self._pending.clear()
+
+    def run(self) -> HostExit:
+        """Calls event handlers until the host exits (window closed, `close()` or crash)."""
+        try:
+            while self._exit is None:
+                try:
+                    # A timeout keeps Ctrl+C responsive on Windows.
+                    message = self._inbox.get(timeout=0.5)
+                except queue.Empty:
+                    continue
+                if isinstance(message, HostExit):
+                    self._exit = message
+                    try:
+                        self._proc.stdin.close()
+                    except OSError:
+                        pass  # unflushed data to a dead host
+                    # An exit after close() or windowClosed is expected; anything else is a crash.
+                    if not self._closing:
+                        print(_describe_exit(message), file=sys.stderr)
+                else:
+                    self._dispatch(message)
+        except BaseException:
+            self._proc.kill()
+            raise
+        return self._exit
+
+    def close(self) -> HostExit:
+        """Closes stdin (the host exits on EOF), handles remaining messages and waits for the exit."""
+        self._closing = True
+        try:
+            self._proc.stdin.close()
+        except OSError:
+            pass
+        return self.run()
+
+    def _create(self, type: str, props: dict) -> Node:
+        # Ids are positive, unique for the whole session and never reused.
+        id = self._next_id
+        self._next_id += 1
+        self._nodes[id] = _Record(type)
+        self._pending.append({"op": "create", "id": id, "type": type, "props": _props(props)})
+        return Node(self, id, type)
+
+    def _attach(self, parent: int, child: int) -> None:
+        # Mirrors the host's move semantics so `remove` can drop descendant handlers.
+        record = self._nodes.get(child)
+        if not record:
+            return
+        if record.parent is not None and record.parent in self._nodes:
+            self._nodes[record.parent].children.discard(child)
+        record.parent = parent
+        if parent in self._nodes:
+            self._nodes[parent].children.add(child)
+
+    def _remove(self, id: int) -> None:
+        record = self._nodes.get(id)
+        if not record:
+            return
+        if record.parent is not None and record.parent in self._nodes:
+            self._nodes[record.parent].children.discard(id)
+        stack = [id]
+        while stack:
+            node = self._nodes.pop(stack.pop(), None)
+            if node:
+                stack.extend(node.children)
+        self._pending.append({"op": "remove", "id": id})
+
+    def _set_handler(self, id: int, event: str, handler) -> None:
+        # Queues `setEvents` only when the subscription set changes.
+        record = self._nodes.get(id)
+        if not record:
+            return
+        had = event in record.handlers
+        if handler:
+            record.handlers[event] = handler
+        else:
+            record.handlers.pop(event, None)
+        if had != (event in record.handlers):
+            self._pending.append({"op": "setEvents", "id": id, "events": list(record.handlers)})
+
+    def _dispatch(self, message: dict) -> None:
+        match message.get("type"):
+            case "event":
+                record = self._nodes.get(message.get("id"))
+                handler = record and record.handlers.get(message.get("event"))
+                if not handler:
+                    return
+                # A menu choice passes the item id; a Slider, a number.
+                if record.type in ("Checkbox", "Switch"):
+                    handler(message.get("checked", False))
+                elif "paths" in message:
+                    handler(message["paths"])
+                elif "value" in message or record.type in ("Input", "Textarea"):
+                    handler(message.get("value", ""))
+                else:
+                    handler()
+            case "error":
+                error = HostError(message.get("code"), message.get("message"), message.get("op"))
+                if self.on_error:
+                    self.on_error(error)
+                else:
+                    print(f"gpui-bridge: host rejected '{error.op}': {error.message}", file=sys.stderr)
+            case "windowClosed":
+                window_id = message.get("id", 1)
+                self._open_windows.discard(window_id)
+                # The host exits after the last window, unless there is a tray.
+                if not self._open_windows and not self._has_tray:
+                    self._closing = True
+                window = self._windows.get(window_id)
+                if window and window.on_closed:
+                    window.on_closed()
+                if self.on_window_closed:
+                    self.on_window_closed(window_id)
+            case "windowEvent":
+                window = self._windows.get(message.get("id", 1))
+                if window:
+                    window._dispatch_window_event(message)
+                if self.on_window_event:
+                    self.on_window_event(message)
+            case "notification":
+                if self.on_notification:
+                    self.on_notification(message.get("id"), message.get("window"))
+            case "shortcut":
+                if self.on_shortcut:
+                    self.on_shortcut(message.get("keys"), message.get("window"))
+            case "tray":
+                if self.on_tray:
+                    self.on_tray(message.get("event"), message.get("value"))
+
+    def _handshake(self) -> None:
+        deadline = time.monotonic() + HANDSHAKE_TIMEOUT
+        while True:
+            try:
+                message = self._inbox.get(timeout=max(0.0, deadline - time.monotonic()))
+            except queue.Empty:
+                self._proc.kill()
+                raise TimeoutError(f"gpui-bridge host did not answer the handshake within {HANDSHAKE_TIMEOUT:g} s") from None
+            if isinstance(message, HostExit):
+                raise HostExitedError(_describe_exit(message), message)
+            if message.get("type") == "ready":
+                return
+            if message.get("type") == "error":
+                raise RuntimeError(f"gpui-bridge handshake failed ({message.get('code')}): {message.get('message')}")
+
+    def _write(self, messages: list[dict]) -> None:
+        if self._proc.stdin.closed:
+            return
+        try:
+            for message in messages:
+                self._proc.stdin.write(json.dumps(message, separators=(",", ":")).encode() + b"\n")
+            self._proc.stdin.flush()
+        except OSError:
+            pass  # Writes racing a dying host fail; run() reports the real cause.
+
+    def _read_stdout(self) -> None:
+        for raw in self._proc.stdout:
+            line = raw.decode("utf-8", "replace").rstrip("\r\n")
+            try:
+                message = json.loads(line)
+            except ValueError:
+                message = None
+            if isinstance(message, dict):
+                self._inbox.put(message)
+            else:
+                print(f"gpui-bridge: host wrote a non-protocol line to stdout: {line}", file=sys.stderr)
+        self._proc.stdout.close()
+        # Wait for stderr too, so the exit carries the complete tail.
+        self._stderr_thread.join()
+        self._inbox.put(HostExit(self._proc.wait(), list(self._stderr_tail)))
+
+    def _read_stderr(self, debug: bool) -> None:
+        for raw in self._proc.stderr:
+            line = raw.decode("utf-8", "replace").rstrip("\r\n")
+            self._stderr_tail.append(line)
+            if debug:
+                print(f"[host] {line}", file=sys.stderr)
+        self._proc.stderr.close()

gpui_bridge/bin/host.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.2.0",
+  "protocol": 1,
+  "target": "win32-x64",
+  "sha256": "fd45752626302a5bd2b71817f01dc6e1c2af6448aa606820d71d04959a94c2db"
+}

gpui_bridge-0.2.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: gpui-bridge
+Version: 0.2.0
+Summary: Python client for the gpui-bridge native UI host
+Author: gpui-bridge contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/InDIOS/gpui-bridge#readme
+Project-URL: Repository, https://github.com/InDIOS/gpui-bridge
+Project-URL: Issues, https://github.com/InDIOS/gpui-bridge/issues
+Project-URL: Protocol, https://github.com/InDIOS/gpui-bridge/blob/main/docs/PROTOCOL.md
+Keywords: gpui,gpui-component,native,desktop,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gpui-bridge (Python)
+
+Native desktop UIs with [GPUI](https://www.gpui.rs/) and
+[gpui-kit](https://gpui-kit.com/), driven from Python. A Rust host
+owns the window, the event loop and the component tree; this client describes the UI as
+operations on that tree and receives events. Standard library only.
+
+```python
+from gpui_bridge import App
+
+app = App()
+count = 0
+
+root = app.div(class_="flex flex-col items-center gap-4 p-6 size-full")
+label = app.text(content="0", class_="text-xl font-bold")
+
+def add(_event=None):
+    global count
+    count += 1
+    label.set(content=str(count))
+    app.commit()
+
+root.append(label, app.button(label="Add", variant="primary").on("click", add))
+app.window(title="Counter", width=320, height=200, root=root)
+app.commit()
+app.run()
+```
+
+## Install
+
+```sh
+pip install gpui-bridge
+```
+
+Requires Python 3.10+. The wheel is built per platform and carries an optimized
+`gpui-bridge-host` binary, so its tag names that platform (`py3-none-win_amd64`,
+`py3-none-macosx_11_0_arm64`, `py3-none-manylinux_2_35_x86_64`) and no Rust toolchain is
+needed at runtime. Those three are the platforms with a wheel; the host has been drawn in a real
+window only on Windows so far.
+
+`class` is a Python keyword: write `class_="..."`, and the client strips the trailing underscore.
+Props and events are keyword arguments, and every node has `append`, `insert_before`, `set`,
+`remove`, `on` and `off`.
+
+## Host lookup
+
+1. `$GPUI_BRIDGE_HOST`
+2. `gpui_bridge/bin/gpui-bridge-host[.exe]` inside the installed package
+3. A Cargo build in `target/debug` or `target/release`, searched upwards (a checkout)
+
+## Links
+
+- [Protocol specification](https://github.com/InDIOS/gpui-bridge/blob/main/docs/PROTOCOL.md)
+  and the [conformance transcripts](https://github.com/InDIOS/gpui-bridge/tree/main/conformance):
+  everything a client in another language needs.
+- [Examples](https://github.com/InDIOS/gpui-bridge/tree/main/examples).
+- Node.js and React clients: `gpui-bridge` and `gpui-bridge-react` on npm.
+
+Protocol version 1. MIT licensed.

gpui_bridge-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+gpui_bridge/__init__.py,sha256=9eS9ED0N7gNDsVmbzNURAzDw7169ui6RyMmthFg5_KM,30211
+gpui_bridge/bin/gpui-bridge-host.exe,sha256=_UV1JiYwKlvStxgX8B3G4cKvZEiqYGgg1x0ElZqUwts,19076608
+gpui_bridge/bin/host.json,sha256=uxmHKJOO9mpxc5KtfZIkil9AYxWYSxRHXICdVcl_Nes,147
+gpui_bridge-0.2.0.dist-info/licenses/LICENSE,sha256=u_pqOxKY12j1fgcsnE3ADgQi5BE_wgGzBb2kalkJc1k,1081
+gpui_bridge-0.2.0.dist-info/METADATA,sha256=FkNYmL9lF9TBY76i7s6BlZ3Ai6nEdk9nD7-2t4LBQcM,3380
+gpui_bridge-0.2.0.dist-info/WHEEL,sha256=bhMFZwp6VMtrbl2Ck6PlXryKaCggO1NzYn_HcFbBF1I,97
+gpui_bridge-0.2.0.dist-info/top_level.txt,sha256=FO3OApNVj-wGLrFJYiY5MU8ubLUGlCvLgm6PBoOaIdU,12
+gpui_bridge-0.2.0.dist-info/RECORD,,

gpui_bridge-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

gpui_bridge-0.2.0.dist-info/licenses/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.

gpui_bridge-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gpui_bridge