remorses/gpuix

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "@gpuix/react",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}

import { useState } from 'react'
import { render } from '@gpuix/react'
function App() {
  const [count, setCount] = useState(0)
  return (
    

      
 setCount((c) => c + 1)}
        style={{
          padding: 12,
          borderRadius: 8,
          cursor: 'pointer',
          backgroundColor: '#232323',
          hover: { backgroundColor: '#2c2c2c' },
        }}
      >
        Count: {count}
      
    
  )
}

render(, { title: 'My App', width: 800, height: 600 })

bun --hot app.tsx

bun build --compile app.tsx --outfile dist/app
./dist/app

cargo install cargo-packager --locked

mkdir AppIcon.iconset
sips -z 16 16 icon-1024.png --out AppIcon.iconset/icon_16x16.png
sips -z 32 32 icon-1024.png --out AppIcon.iconset/[email protected]
sips -z 32 32 icon-1024.png --out AppIcon.iconset/icon_32x32.png
sips -z 64 64 icon-1024.png --out AppIcon.iconset/[email protected]
sips -z 128 128 icon-1024.png --out AppIcon.iconset/icon_128x128.png
sips -z 256 256 icon-1024.png --out AppIcon.iconset/[email protected]
sips -z 256 256 icon-1024.png --out AppIcon.iconset/icon_256x256.png
sips -z 512 512 icon-1024.png --out AppIcon.iconset/[email protected]
sips -z 512 512 icon-1024.png --out AppIcon.iconset/icon_512x512.png
sips -z 1024 1024 icon-1024.png --out AppIcon.iconset/[email protected]
iconutil -c icns AppIcon.iconset -o AppIcon.icns

{
  "productName": "My App",
  "version": "0.1.0",
  "identifier": "dev.example.app",
  "binariesDir": "dist",
  "outDir": "bundle",
  "binaries": [{ "path": "app", "main": true }],
  "icons": ["AppIcon.icns"],
  "formats": ["app"]
}

cargo packager --release --config packager.json
open "bundle/My App.app"

{
  "binaries": [
    { "path": "gpuix-hermes", "main": true },
    { "path": "gpuix-native.darwin-arm64.node", "main": false }
  ]
}

cargo packager signer generate

import { checkUpdate } from '@gpuix/native'
import { render } from '@gpuix/react'
import { App } from './app'
async function maybeUpdate() {
  const update = await checkUpdate('0.1.0', {
    endpoints: ['https://github.com/OWNER/REPO/releases/latest'],
    pubkey: '',
  })
  if (update) await update.downloadAndInstall()
}
maybeUpdate()
render()

# macOS
bun build --compile app.tsx --outfile dist/app
cargo packager --release --config packager.json
gh release upload v0.1.0 \
  "bundle/My App.app.tar.gz" \
  "bundle/My App.app.tar.gz.sig" \
  --clobber
Linux
bun build --compile app.tsx --outfile dist/app
cargo packager --release --config packager.json
gh release upload v0.1.0 \
  bundle/app_0.1.0_x86_64.AppImage \
  bundle/app_0.1.0_x86_64.AppImage.sig \
  --clobber
Windows
bun build --compile app.tsx --outfile dist/app.exe
cargo packager --release --config packager.json
gh release upload v0.1.0 \
  bundle/app_0.1.0_x64-setup.exe \
  bundle/app_0.1.0_x64-setup.exe.sig \
  --clobber

bun add -g @gpuix/cli
gpuix completions install

and `` in JS, for comparison | | web | bun run web from the repository root | The ChatGPT example rendered in a browser canvas with WebGPU |

The todo app lives in example-app/ and is meant to be copied with bunx @gpuix/cli new. The rest live in examples/. Those bun --hot commands need a clone of this repo and a local native build. They will not run against the published packages alone.

Or download a standalone chat build from the GitHub release. No Bun or Rust install is required.

tar -xzf example-chat-aarch64-apple-darwin.tar.gz
./example-chat-aarch64-apple-darwin

The archive keeps the executable bit, so there is no chmod step. macOS may still block the unsigned binary the first time. Right-click the file, choose Open, and confirm.

On Windows, download example-chat-x86_64-pc-windows-msvc.exe and double-click it. On Linux, the file is example-chat-x86_64-unknown-linux-gnu.tar.gz.

The web example bundles the same React app and reconciler as the desktop chat example. wasm-bindgen exposes mutations and event callbacks to the existing retained tree and GpuixView, which run through GPUI's browser platform.

The web build needs nightly Rust and the matching wasm-bindgen CLI:

rustup toolchain install nightly --component rust-src --target wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.127 --locked
bun run web

The generated Wasm uses shared memory, so the page must be cross-origin isolated. Production servers must send these headers on the top-level document:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

require-corp then constrains cross-origin subresources, which must supply their own CORS or Cross-Origin-Resource-Policy. Serve the JavaScript and the Wasm from the same origin as the document and nothing else is needed.

bun run web rebuilds the Wasm only when packages/native/wasm is missing. After a Rust change, force it:

bun scripts/web.ts --rebuild

Hot reload in the browser

bun run web serves the example through Bun's frontend dev server, so an edit to examples/chat.tsx arrives as a React Fast Refresh update. Components swap in place and useState survives, which means the composer text, the sidebar selection, and the scroll position all stay where they were. The GPUI canvas is never re-created and the ~19 MB Wasm module is never re-fetched.

Fast Refresh only applies to a module whose exports are all components. Edit anything else, such as the entry file, and Bun reloads the page instead. Both paths are correct; the reload is only slower.

The Wasm half is a singleton and must never re-evaluate. WebGpuixRenderer::init fails with GPUIX web is already running once its thread-local app exists, and GPUI's browser platform appends its own canvas to `. What protects it is not that it lives in node_modules`; Bun bundles it into the same client registry as your app. It is that Bun re-runs only the changed module and then walks upward through its importers, so an unchanged dependency stays evaluated and cached. Two rules follow:

• do not call import.meta.hot.accept("./your-app", ...) in the entry file.

Bun runs an importer's dependency-accept callback even when the imported module already self-accepted, so that callback would remount the tree on top of a successful refresh and throw away every useState

• keep the @gpuix/native import in a module that can never become a Refresh

boundary and is never explicitly accepted

The chat example puts a virtualized `` and a GFM table inside an assistant turn, inside a scrolling transcript:

Markdown, code and a virtualized diff in one frame:

Architecture

GPUIX bridges React and Solid to GPUI using a shared mutation-based runtime. Desktop apps use napi-rs; browser apps load the same Rust renderer through wasm-bindgen. Each framework adapter collects changed elements into one atomic mutation batch. Rust applies that batch to a retained element tree that GPUI reads each frame.

┌─────────────────────────────────────────────────────────────────┐
│  React or Solid (JavaScript)                                    │
│                                                                 │
│  function App() {                                               │
│    const [count, setCount] = useState(0)                        │
│    return (                                                     │
│      
                  │
│        
 setCount(c => c + 1)}>               │
│          Count: {count}                                         │
│        
                                                   │
│      
                                                     │
│    )                                                            │
│  }                                                              │
└─────────────────────────────────────────────────────────────────┘
                    │ napi desktop / wasm-bindgen browser
                    │ applyBatch([
                    │   ["createElement", 1, "div"],
                    │   ["setStyle", 1, {...}],
                    │   ["setRoot", 1]
                    │ ])
                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  Rust host bridge                                               │
│                                                                 │
│  RetainedTree ── stores elements, styles, event flags           │
│       │                                                         │
│       ▼  each GPUI frame                                        │
│  GpuixView::render() → build_element() → GPUI elements          │
└─────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  GPUI                                                           │
│                                                                 │
│  Metal, DirectX, Vulkan, or browser WebGPU / WebGL2             │
│  Flexbox layout via Taffy                                       │
└─────────────────────────────────────────────────────────────────┘

Why This Works

GPUI is an immediate-mode UI framework — it rebuilds the entire element tree every frame. Instead of fighting this, GPUIX embraces it:

1. The React or Solid adapter detects a state change and queues host mutations (createElement, setStyle, appendChild, etc.) 2. applyBatch() validates and applies the complete commit to the Rust RetainedTree 3. On each GPUI frame, GpuixView::render() walks the RetainedTree and calls build_element() to produce ephemeral GPUI elements 4. GPUI lays them out (Taffy flexbox) and renders to the GPU 5. Only changed elements cross the FFI boundary. The framework adapter sends minimal mutations

React and Solid use the same IDs, mutation queue, event routing, testing API, automation client, observers, and text-search matcher. Their framework-specific schedulers and component contexts stay in the adapter packages.

Mutation API

The mutation surface between JS and Rust is one atomic method. Desktop uses napi and the browser uses wasm-bindgen:

type MutationHost = Pick

createMutationQueue only needs that. Window size, focus, and selection use smaller host types (WindowSizeHost, SelectionHost). NativeRenderer is MutationHost plus those methods, so a fake can implement applyBatch alone.

Element IDs are plain numbers generated by an incrementing counter in JS. React may abandon work in concurrent render mode, so GPUIX keeps new host nodes in JS until React places the accepted subtree during commit. Only then are its mutations added to the batch. applyBatch() applies that accepted commit atomically and marks the Rust view dirty for the next frame.

Event Flow

Events travel from GPUI back to React through a ThreadsafeFunction on desktop and a wasm-bindgen callback in the browser.

User clicks element id=3
       │
       ▼
GPUI fires on_click on the element
       │
       ▼
Rust closure calls emit_event_full(callback, 3, "click", {x, y, ...})
       │
       ▼
Desktop ThreadsafeFunction / browser callback sends EventPayload
       │
       ▼
JS event registry: eventHandlers.get(3)?.get("click")?.(payload)
       │
       ▼
React handler runs: onClick={() => setCount(c => c + 1)}
       │
       ▼
State update triggers re-render → reconciler sends mutations back to Rust

Event handlers are stored in a JS-side registry keyed by (elementId, eventType). Rust only knows whether an element has a listener (via setEventListener), not the closure itself — the actual handler lives in JS.

Packages

• @gpuix/native: Rust bindings plus the framework-neutral TypeScript host runtime. It owns host types, mutation batching, renderer state, event routing, observers, native testing, and automation.
• @gpuix/native/host: host contracts, mutation helpers, renderer ownership, window observers, selection observation, and text search. Importing it does not load the .node addon.
• @gpuix/native/testing: the shared TestRenderer over the real TestGpuixRenderer.
• @gpuix/native/automation: the shared automation protocol, client, locators, and process launcher.
• @gpuix/react: the React reconciler and React components. It preserves its existing exports and re-exports shared testing, automation, search, and observer APIs.
• @gpuix/solid: the Solid 1 universal renderer, Solid primitives, motion, Select, Combobox, Tooltip, Bun preload, and build plugin.
• @gpuix/cli — gpuix new downloads example-app/, sets its published React dependency, and installs it as a standalone project.

Pin the selected adapter and @gpuix/native to the same exact version. GPUIX is still pre-1.0. Breaking changes can land before v1. Upgrade them together.

Solid quick start

Install Solid and the official Solid adapter:

bun add --exact @gpuix/solid @gpuix/native solid-js

Use Solid's preserved JSX. The preload compiles application .tsx and .jsx files for Solid's universal renderer and selects the reactive client runtime.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "jsxImportSource": "@gpuix/solid",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}

preload = ["@gpuix/solid/preload"]

import { createSignal } from 'solid-js'
import { render } from '@gpuix/solid'
function App() {
  const [count, setCount] = createSignal(0)
  return (
    

      
 setCount((value) => value + 1)}>
        Count: {count()}
      
    
  )
}

render(() => , { title: 'Solid GPUIX', width: 800, height: 600 })

Run it directly. No wrapper command or Vite configuration is required.

bun app.tsx
bun --hot app.tsx

For production Bun.build, pass the exported plugin:

import solidPlugin from '@gpuix/solid/bun-plugin'
await Bun.build({
  entrypoints: ['./app.tsx'],
  target: 'bun',
  outdir: './dist',
  plugins: [solidPlugin],
})

@gpuix/solid targets stable Solid 1.9. Its peer range is >=1.9 <2.

The full Solid adapter API is in the Solid guide.

Building

This section is for working on GPUIX itself. To build an app with it, see Quickstart instead. Installing the packages needs no Rust toolchain and no submodule.

Prerequisites

1. Rust toolchain 2. Node.js 18+ 3. Xcode with Metal Toolchain (macOS)

# Install Metal Toolchain if needed
xcodebuild -downloadComponent MetalToolchain
Install dependencies
bun install
Check out the pinned GPUI fork
git submodule update --init --recursive
Build native package
cd packages/native
bun run build
Build React package
cd ../react
bun run build
Build Solid package
cd ../solid
bun run build
Run example (use tmux for long-running sessions)
cd ../../examples
bun --hot counter.tsx

Usage

```tsx import React, { useState } from 'react' import { render } from '@gpuix/react'

function App() { const [count, setCount] = useState(0) return (