Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI
svelte docs
Preetham Pemmasaniaaa19d681938
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2e59418..1cc0eed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,45 @@ All notable changes to **blenderui** (BUI). The format follows## [Unreleased]+### Added+- **Svelte** (new npm package `@blender-ui/svelte` 0.1.0, Svelte 5.57): Svelte 5 components in+ native windows, with feature parity with `@blender-ui/react`: `render(Component, options)`,+ `createRoot(window)`, `act(fn)`, Blender's ten widgets as components, BUI's signals (each a+ Svelte store, `$count`), headless tests and screenshots, Node.js (`--import+ @blender-ui/svelte/register`), Bun (`--preload`) and `bui build` / `bui run`. Runes, snippets,+ bindings, keyed `{#each}`, `{#await}`, `{#key}`, context, lifecycle and scoped `<style>`+ blocks work; transitions run their start and end without animating in between. Svelte has+ no custom-renderer API, so its compiled components run on `@blender-ui/native`'s DOM.+- **`@blender-ui/native`, a fuller DOM:** a window-less `document` whose nodes are detached until+ inserted into a window's tree (then created natively with their subtree), `DocumentFragment`,+ `Comment` (an anchor that takes no space), `cloneNode`, `before` / `after` / `append` /+ `prepend` / `replaceWith`, `contains`, `isConnected`, `el.style` with `cssText` /+ `setProperty` / `removeProperty`, `el.classList`, DOM properties that reflect attributes+ (`disabled`, `hidden`, `value`, `checked`, `type` ...) on `HTMLElement`, `dispatchEvent`,+ `event.composedPath()` and `cancelBubble`. Nodes made by `document` are freed natively once+ removed and dropped.+- **A shared layer for framework bindings:** `@blender-ui/native/host` (`open`, `blenderWidgets`,+ `applyProps`: what React's binding did on its own), `@blender-ui/native/globals` (the browser+ globals DOM frameworks read), and `bui build` bundling with the Bun plugin of every+ `@blender-ui/*` package that declares one (`"bui": { "bunPlugin" }`). A binding for another+ framework is a thin adapter over these.+- **Benchmarks:** `bench/cells.js --svelte [--signals]` and `bench/startup.js --svelte`.++### Changed+- **`@blender-ui/native`:** siblings are a linked list (insert, remove and `nextSibling` are+ O(1); `childNodes` returns a new array), and listener maps are made on the first listener.+ Re-rendering 3,000 cells per frame from React costs a little less CPU.+- **`@blender-ui/native`:** reading `el.style` returns the inline style object (its `cssText`+ is the old string); setting it still takes a string, an object or a signal.+ `addEventListener` accepts any event type (those BUI doesn't report only fire through+ `dispatchEvent`) instead of throwing.+- **`@blender-ui/react`** uses `@blender-ui/native/host` for its props, events, widgets and+ window options; its API and behaviour are unchanged.+- **`bui build`** bundles with `Bun.build` (and the framework plugins it finds) instead of the+ `bun build` command line.+- **`bench/startup.js`** counts launches that fail at exit (after their first frame, a+ sporadic crash on Bun at quit) instead of aborting.+## [0.3.0] - 2026-11-06### Addeddiff --git a/README.md b/README.mdindex 4e9200c..1fa1e3f 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@BUI</h1>-**Blender's user interface, as a library you can use from Python, Rust, JavaScript/React, C, C++ and Dear ImGui.**+**Blender's user interface, as a library you can use from Python, Rust, JavaScript (React, Svelte), C, C++ and Dear ImGui.**People spent decades building and optimizing Blender's GUI. It's battery and memory efficient, and super duper fast. We decoupled it, to give everyone a chance to build their own products with it. It supports multiple languages and frameworks, so you won't miss a beat!@@ -164,7 +164,7 @@ all get the same widgets and interactions:| **Qt-style** Python (`QWidget`, layouts, `clicked.connect`) | The common subset of Qt widgets | Partial || **Blender components** (`Panel`, `NumberSlider`, `PieMenu`, the node editor ...) | 45 native Blender widgets and editors, from Python; ten of them also from Rust and JavaScript | Complete || **Rust**: HTML + CSS + Tailwind, HTML-like markup (`rsx!` / `view!`), hooks, or [gpui](https://www.gpui.rs) / [zopra](https://zopra.preetham.top) syntax | A web-like framework: HTML that looks like a browser's, Blender's look with `styled`, and Blender components (`<NumberSlider>`, `<Button>` ...) | Working |-| **JavaScript / React** on Node.js or Bun: a DOM-like API or JSX | The same engine and components in native windows, over napi-rs; React's hooks backed by signals | Working |+| **JavaScript / React / Svelte** on Node.js or Bun: a DOM-like API, JSX or Svelte components | The same engine and components in native windows, over napi-rs; React's hooks backed by signals; Svelte 5 components | Working || **Dear ImGui** from C++, C, Python or Rust | The real Dear ImGui on BUI windows in Blender's theme, or a build where ImGui's widgets _are_ Blender's widgets | Working || **C** (`BUI_kit.h`) | The kit itself: nodes, widgets, windows | Working || **MyGo** | MyGo | Not yet (coming soon) |@@ -215,7 +215,8 @@ If you're starting fresh in Python, the Blender components are the friendliest.- **React 19.3** renders to BUI: HTML host components, CSS and Tailwind, events, Suspense, transitions, actions, and Blender components (`<NumberSlider>`, `<Button>` ...). BUI draws them, on the CPU or the GPU; there's no browser and no webview.- **React's hooks, by React's names**, holding signals: pass one into JSX (`{count}`) and a change updates that one node without re-rendering; read it while rendering (`count.value`) and the component re-renders, as with React. A conformance suite checks each hook against React's own.-- **`@blender-ui/native`**: a DOM-like API (`createElement`, `appendChild`, `addEventListener`) with the same signals, for apps without React.+- **Svelte 5** (`@blender-ui/svelte`): components with runes, snippets, bindings and scoped styles, mounted into native windows; Svelte's compiled code runs on BUI's DOM, so a `$state` change updates the one node that shows it.+- **`@blender-ui/native`**: a DOM-like API (`createElement`, `appendChild`, `addEventListener`) with the same signals, for apps without a framework, and the shared layer the React and Svelte bindings are thin adapters over.- **Node.js and Bun**, through a napi-rs addon, with headless mode for tests.### Small standalone apps@@ -359,6 +360,7 @@ default MSVC target), and on Linux the X11 headers (`libx11-dev` or```shnpm install @blender-ui/react react # or: bun add @blender-ui/react react+npm install @blender-ui/svelte svelte # Svelte 5npm install @blender-ui/native # the DOM-like API, without React```@@ -1254,6 +1256,10 @@ transforms, OpenType features, multi-column layout. Guide:Hooks keep React's names but hold signals: pass one into JSX and a changeupdates that node without re-rendering. README:[bindings/react](bindings/react/README.md).+- **`@blender-ui/svelte`**: Svelte 5 components (runes, snippets, bindings,+ keyed blocks, context, scoped `<style>`) and the Blender components, on+ Node.js (`--import @blender-ui/svelte/register`), Bun and `bui build`.+ README: [bindings/svelte](bindings/svelte/README.md).- **`@blender-ui/native`**: a DOM-like API (`createElement`, `appendChild`,`addEventListener`, `className` with Tailwind, `style`) with signals,`memo`, `effect` and `batch`. README: [bindings/node](bindings/node/README.md).@@ -1322,7 +1328,7 @@ SVG recorder use it. Guide: [INTEGRATION.md](INTEGRATION.md).| [Qt syntax](docs/qt.md) | Classes, signals, layouts, painting, coverage || [Components](docs/components.md) | The `bui.components` reference || [Rust](docs/rust.md) | `rsx!`, hooks, HTML, CSS and Tailwind coverage, effects, animations, events, headless tests |-| [JavaScript and React](docs/javascript.md) | `@blender-ui/native`, `@blender-ui/react`, how changes cross to the UI thread, performance |+| [JavaScript, React and Svelte](docs/javascript.md) | `@blender-ui/native`, `@blender-ui/react`, `@blender-ui/svelte`, adding a framework, how changes cross to the UI thread, performance || [Dear ImGui](docs/imgui.md) | Dear ImGui on BUI from C++, C, Python and Rust; the Blender-widgets build; coverage || [C API](docs/c-api.md) | The C kit (`BUI_kit.h`) || [Integration](INTEGRATION.md) | Embedding BUI drawing in C, C++, Qt or PySide hosts |@@ -1494,6 +1500,38 @@ What this means:has no JIT, so re-rendering a 3,000-element list every frame drops it to20 FPS. Keep big lists on signals, or build with `--bun`.+**React and Svelte, side by side** (one session, runs interleaved, medians of+3; `--svelte` in the commands below):++| 3,000 cells, one session | FPS | CPU per frame | RAM |+| ------------------------------------------- | ----------: | ----------------: | -------------: |+| Node 26: React with state / with signals | 27.6 / 27.6 | 42.5 / 36.9 ms | 150 / 98 MB |+| Node 26: Svelte (runes) / with signals | 24.8 / 26.6 | 41.5 / 38.6 ms | 119 / 118 MB |+| Bun 1.4: React with state / with signals | 24.0 / 25.0 | 55.8 / 40.8 ms | 111 / 86 MB |+| Bun 1.4: Svelte (runes) / with signals | 26.4 / 27.0 | 39.3 / 38.2 ms | 100 / 100 MB |+| QuickJS: React with state / with signals | 8.5 / 27.0 | 117 / 37.3 ms | 67 / 62 MB |+| QuickJS: Svelte (runes) / with signals | 26.9 / 25.9 | 37.5 / 38.7 ms | 76 / 76 MB |++| First frame, median of 12 (React / Svelte) | First frame | RAM at first frame |+| ------------------------------------------- | ------------: | -----------------: |+| QuickJS executable (`bui build`, 6.9 MB) | 94 / 89 ms | 20.5 / 19.8 MB |+| Bun executable (`bui build --bun`) | 111 / 107 ms | 37.8 / 38.3 MB |+| Bun (`--preload …/register` for Svelte) | 130 / 243 ms | 36.4 / 46.6 MB |+| Node.js (`--import …/register` for Svelte) | 147 / 440 ms | 46.8 / 64.1 MB |++- **Svelte needs no signals to stay cheap:** runes update the one cell that+ changes, so Svelte costs what React with signals does on every runtime, and+ holds 27 FPS on QuickJS where React re-rendering the grid falls to 8.5.+- **Memory:** Svelte keeps 14–21 MB more than React with signals at 3,000+ cells (its effects and each-block items).+- **Startup:** built with `bui build`, both reach the first frame in about+ 90 ms. On Node.js and Bun, Svelte's runtime loads from about 90 source files+ first (components come from the compile cache).+- **This session ran at about 27 FPS** for every variant (the machine, not the+ code), so compare these rows with each other, not with the tables above.+ React with state cost 45.8 ms and 190 MB on Node in the same session before+ this release's DOM changes (linked siblings, lazy listener maps).+Method, the memory breakdown and how to rerun:[docs/javascript.md](docs/javascript.md#performance).@@ -1546,10 +1584,12 @@ cd bindings/nodenode bench/cells.js 3000 # DOM-like API, one cell changing per framenode bench/cells.js 3000 --react # React re-rendering the gridnode bench/cells.js 3000 --react --signals # React with signals: no re-render+node --import ../svelte/register.js bench/cells.js 3000 --svelte # Svelte, runesnode bench/cells.js 3000 --gpu # on the GPU rendererbun bench/cells.js 3000 # on Bunnode cli.js run bench/cells.js -- 3000 # on the 5 MB QuickJS runtimenode bench/startup.js # launch to first frame: Node, Bun and both executables+node bench/startup.js --svelte # the same for the Svelte app```**tkinter: canvas frame cost** (headless, any platform):@@ -1605,7 +1645,7 @@ and on an NVIDIA GPU.| ------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- || `blenderui` on PyPI | Windows x86_64, Linux x86_64 (manylinux), macOS arm64 and x86_64 | CPython 3.11 to 3.14. No musllinux or 32-bit wheels. || `blenderui` on crates.io | Any platform with CMake and a C compiler | Rust 1.88+. `blenderui-imgui` (Dear ImGui) is on crates.io too. |-| `@blender-ui/native`, `@blender-ui/react` on npm | Windows x64 | Node.js 18+ or Bun. Elsewhere, build the addon from source. |+| `@blender-ui/native`, `@blender-ui/react`, `@blender-ui/svelte` on npm | Windows x64 | Node.js 18+ (22.15+ for Svelte) or Bun. Elsewhere, build the addon from source. || C and C++ (CMake) | Windows, Linux, macOS | CMake 3.20+, a C11 and C++20 compiler. |## 35. Environment variables@@ -1703,7 +1743,7 @@ How each was counted: [Coverage](https://bui.preetham.top/docs/reference/coverag| `api/` | Stable C ABI for render-sink hosts || `bindings/python/` | The `buipy` extension and the `bui` / `blenderui` packages (tkinter, Qt, components, ImGui) || `bindings/rust/` | `blenderui`, `blenderui-sys`, `blenderui-macros`, `blenderui-tailwind`, `blenderui-imgui`, `blenderui-jsview`, `blenderui-node`, `blenderui-qjs`, and the benchmark |-| `bindings/node/`, `bindings/react/` | `@blender-ui/native` and `@blender-ui/react` |+| `bindings/node/`, `bindings/react/`, `bindings/svelte/` | `@blender-ui/native`, `@blender-ui/react` and `@blender-ui/svelte` || `bindings/imgui/` | Dear ImGui (vendored), the BUI backend, Blender style, the C API and its generator, the Blender-widgets build || `backends/qt/` | C++ Qt/QPainter render-sink backend || `bench/` | The start time and battery benchmark |@@ -1722,7 +1762,7 @@ How each was counted: [Coverage](https://bui.preetham.top/docs/reference/coverag| [`examples/imgui_demo.cpp`](examples/imgui_demo.cpp) | Dear ImGui's demo window on BUI, from C++ || [`examples/imgui_demo_c.c`](examples/imgui_demo_c.c) | The same from C (`cimgui.h`) || [`examples/imgui_blender_compare.cpp`](examples/imgui_blender_compare.cpp) | ImGui widgets next to BUI's native Blender widgets |-| [`examples/site/`](examples/site/) | The website's screenshot programs: a Render Properties editor and a node editor (Python components), tkinter and ttk dialogs, a Qt material editor, an ImGui inspector (C++ and Python), a C modifier stack, and a JavaScript task list (DOM and React) |+| [`examples/site/`](examples/site/) | The website's screenshot programs: a Render Properties editor and a node editor (Python components), tkinter and ttk dialogs, a Qt material editor, an ImGui inspector (C++ and Python), a C modifier stack, and a JavaScript task list (DOM, React and Svelte) || [`hello.rs`](bindings/rust/blenderui/examples/hello.rs) | Rust: a component, hooks, Tailwind attributes and a Blender slider || [`showcase.rs`](bindings/rust/blenderui/examples/showcase.rs) | Rust: HTML, a stylesheet, flex/grid, tables, Blender form widgets || [`forms.rs`](bindings/rust/blenderui/examples/forms.rs) | Rust: form controls as plain HTML, inside `styled`, and as Blender components |@@ -1732,6 +1772,7 @@ How each was counted: [Coverage](https://bui.preetham.top/docs/reference/coverag| [`blenderui-imgui` demo](bindings/rust/blenderui-imgui/examples/demo.rs) | Dear ImGui from Rust (`cargo run -p blenderui-imgui --example demo`) || [`bindings/node/examples/counter.js`](bindings/node/examples/counter.js) | JavaScript: the DOM-like API || [`bindings/react/examples/counter.jsx`](bindings/react/examples/counter.jsx) | React in JSX (`bun examples/counter.jsx`) |+| [`bindings/svelte/examples/Counter.svelte`](bindings/svelte/examples/Counter.svelte) | Svelte 5 (`node --import ./bindings/svelte/register.js bindings/svelte/examples/counter.js`) |---diff --git a/bindings/node/README.md b/bindings/node/README.mdindex 662f52c..4dd2aff 100644--- a/bindings/node/README.md+++ b/bindings/node/README.md@@ -10,8 +10,9 @@ classes, Blender components (`NumberSlider`, `Button` ...), and signals. It runsBun through a napi-rs addon, and `bui build` turns an app into a singleexecutable of about 5 MB. There's no browser and no webview.-For React, use [`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react),-which is built on this package.+For React, use [`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react);+for Svelte, [`@blender-ui/svelte`](https://www.npmjs.com/package/@blender-ui/svelte).+Both are built on this package.```shnpm install @blender-ui/native # or: bun add @blender-ui/native@@ -39,11 +40,25 @@ win.body.appendChild(button)- **A DOM-like tree:** `createElement`, `createTextNode`, `appendChild`,`insertBefore`, `removeChild`, `setAttribute`, `className` (Tailwindclasses included), `style` (a string or an object), `textContent`.- - Moving nodes and the error cases behave as in the DOM.+ - Moving nodes and the error cases behave as in the DOM; siblings are a+ linked list.+ - `before` / `after` / `append` / `replaceWith`, `cloneNode`,+ `dispatchEvent`, `el.style.setProperty`, `el.classList`, and DOM+ properties that reflect attributes (`disabled`, `value`, `checked` ...).- `destroy()` frees a removed subtree natively.+- **`document`:** a window-less document whose nodes are detached until+ inserted into a window's tree; fragments, and comments as anchors. A removed+ node made by `document` is freed natively at the end of the tick unless it+ was reinserted.+- **For framework bindings:** `@blender-ui/native/host` (`open`,+ `blenderWidgets`, `applyProps`: what React's and Svelte's bindings share),+ `@blender-ui/native/globals` (`document`, `window` and the node classes as+ globals, for DOM-based frameworks), and `bui build` bundling with the Bun+ plugin a `@blender-ui/*` package declares (`"bui": { "bunPlugin" }`).- **Events:** `addEventListener` for `click`, `mousedown`, `mouseup`,`mousemove`, `mouseenter`, `mouseleave`, `wheel`, `keydown`, `keyup`, `input`- and `change`.+ and `change` arrive from the UI thread; other types fire through+ `dispatchEvent`.- They bubble through the tree, and `stopPropagation()` works.- They arrive after BUI has handled them, so `preventDefault()` only marksthe event.@@ -78,7 +93,7 @@ Options:- `-o <file>`: the output file.- `--console`: keep a console window for logs (Windows builds open none).-- `--dev`: React's development build.+- `--dev`: development builds (React's, Svelte's dev mode).Bundling uses [Bun](https://bun.sh), so it must be installed.diff --git a/bindings/react/README.md b/bindings/react/README.mdindex c9c29da..b2e983f 100644--- a/bindings/react/README.md+++ b/bindings/react/README.md@@ -7,6 +7,8 @@ React 19 for the desktop, drawn by [BUI](https://github.com/ppmpreetham/BUI),Blender's UI toolkit. You write JSX with HTML elements, CSS and Tailwindclasses, and BUI renders it in native windows on the CPU or the GPU. There'sno browser, no webview and no Electron.+Prefer Svelte? [`@blender-ui/svelte`](https://www.npmjs.com/package/@blender-ui/svelte)+is the same engine for Svelte 5.- **React's hooks, by React's names, holding signals.** A change updates theone node that shows it, without re-rendering the component.diff --git a/bindings/svelte/README.md b/bindings/svelte/README.mdnew file mode 100644index 0000000..f06b2ce--- /dev/null+++ b/bindings/svelte/README.md@@ -0,0 +1,91 @@+# @blender-ui/svelte++[](https://www.npmjs.com/package/@blender-ui/svelte)+[](https://github.com/ppmpreetham/BUI/blob/main/LICENSE)++Svelte 5 for the desktop, drawn by [BUI](https://github.com/ppmpreetham/BUI),+Blender's UI toolkit. You write components with runes, snippets, HTML+elements, CSS and Tailwind classes, and BUI renders them in native windows on+the CPU or the GPU. There's no browser, no webview and no Electron.++- **Plain Svelte.** Runes, snippets, bindings, `{#each}` / `{#if}` /+ `{#await}` / `{#key}`, context, lifecycle and scoped `<style>` blocks work+ as on the web; a `$state` change updates the one node that shows it.+- **Blender's widgets** as components: `Button`, `NumberSlider` and eight more.+- **Node.js and Bun**, and `bui build` makes one small executable.++```sh+npm install @blender-ui/svelte svelte # or: bun add @blender-ui/svelte svelte+```++```svelte+<!-- Counter.svelte -->+<script>+ import { Button } from '@blender-ui/svelte'+ let count = $state(0)+</script>++<main class="p-6 flex flex-col gap-3 bg-[#2b2b2b] text-[#e6e6e6]">+ <span>Clicks: {count}</span>+ <Button onclick={() => count++}>Add one</Button>+</main>+```++```js+// app.js+import { render } from '@blender-ui/svelte'+import Counter from './Counter.svelte'++render(Counter, { title: 'Counter', width: 360, height: 200, gpu: true })+```++```sh+node --import @blender-ui/svelte/register app.js # Node.js 22.15++bun --preload @blender-ui/svelte/register app.js # Bun+npx bui build app.js # ship it: one small executable+```++`register` compiles `.svelte` (and `.svelte.js`) files on import, caching the+output in `node_modules/.cache/@blender-ui/svelte`, and resolves `svelte` to+its browser build. `bui build` finds this package's bundler plugin by itself.++## API++| Export | What it does |+|---|---|+| `render(Component, options)` | Opens a window and mounts `Component`; returns `{ app, window, root, component }` |+| `createRoot(window)` | `{ render(Component, { props, context }), unmount() }` for a window you opened with [`@blender-ui/native`](https://www.npmjs.com/package/@blender-ui/native); closing the window unmounts it |+| `act(fn)` | Runs `fn` and applies Svelte's pending updates now (tests) |+| `Button`, `Checkbox`, `Radio`, `NumberField`, `NumberSlider`, `TextField`, `TextArea`, `ColorSwatch`, `Dropdown`, `ProgressBar` | Blender's widgets, always drawn and handled like Blender |+| `signal`, `computed`, `effect`, `batch`, `untrack`, `createSignal`, `ref`, `startTransition` | BUI's signals, for state outside components; each is a Svelte store (`$count`) |++Options: `props`, `context`, and the window's `title`, `width`, `height`,+`resizable`, `gpu`, `slug`, `headless`, `theme` (`'dark'` or `'light'`) and+`app` (an `App` to open the window in).++## How it works++Svelte has no custom-renderer API: compiled components call the DOM.+[`@blender-ui/native`](https://www.npmjs.com/package/@blender-ui/native)+provides that DOM: `document` makes detached nodes that join a window's+retained tree when inserted, comments are anchors that take no space, and only+the changes of each tick cross to BUI's UI thread. Components compile with+`fragments: 'tree'` (templates built with `createElement`, no HTML parser).+Svelte's event delegation works: an element with an `onclick` listens+natively, so BUI sends it its clicks.++Not there yet: transitions run their start and end without animating in+between; `{@html}` (no HTML parser); `bind:clientWidth` and other size+bindings (no `ResizeObserver`).++## Requirements++- **Windows x64** prebuilt. On **Linux**, build the `@blender-ui/native`+ addon from source; on **macOS** it's headless for now.+- **Node.js 22.15** or newer (`module.registerHooks`), or Bun.+- **Svelte 5.57** or newer.++Guide: [docs/javascript.md](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md) ·+Website: [bui.preetham.top](https://bui.preetham.top) ·+Source: [github.com/ppmpreetham/BUI](https://github.com/ppmpreetham/BUI) ·+License: GPL-2.0-or-laterdiff --git a/bindings/svelte/index.d.ts b/bindings/svelte/index.d.tsindex aa60589..d437e74 100644--- a/bindings/svelte/index.d.ts+++ b/bindings/svelte/index.d.ts@@ -22,6 +22,10 @@ export function createRoot (window: Window): Rootexport function render<P extends Record<string, any>> (Component: Component<P>, options?: RenderOptions & MountOptions<P>):{ app: App, window: Window, root: Root, component: Record<string, any> }+/** @internal Compiled components with a `<style>` block call it: the stylesheet+ * is added to each window once. */+export function addStyle (key: string, css: string): void+/** Run `fn` and apply Svelte's pending updates now (tests). */export function act<R> (fn?: () => R): Rdiff --git a/docs/javascript.md b/docs/javascript.mdindex 67edaa3..deeda8e 100644--- a/docs/javascript.md+++ b/docs/javascript.md@@ -1,4 +1,4 @@-# JavaScript and React+# JavaScript, React and SvelteBUI runs from JavaScript through a native addon built with napi-rs, much as[GPUIX](https://www.npmjs.com/package/@gpuix/react) drives GPUI. You get native@@ -12,6 +12,7 @@ engine ([Standalone apps](#standalone-apps)).|---|---|| [`@blender-ui/native`](https://www.npmjs.com/package/@blender-ui/native) (`bindings/node`) | A DOM-like API (`createElement`, `setAttribute`, `appendChild`, `addEventListener`, `requestAnimationFrame`) and signals || [`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react) (`bindings/react`) | A React 19.3 renderer; React's hooks by React's names, backed by signals |+| [`@blender-ui/svelte`](https://www.npmjs.com/package/@blender-ui/svelte) (`bindings/svelte`) | Svelte 5 components (runes, snippets, scoped styles) on the DOM-like API |**Platforms:** prebuilt for Windows x64. On Linux, build the addon fromsource (see [Building](#building)); windows are native X11 windows, on the CPU or@@ -72,6 +73,14 @@ The tree behaves like the DOM:- **Errors:** inserting a node into itself, or before a node that isn't achild, throws.- **Freeing nodes:** `destroy()` frees a removed subtree natively.+- **DOM methods:** `before`, `after`, `append`, `prepend`, `replaceWith`,+ `cloneNode`, `contains`, `dispatchEvent`, `el.style.setProperty`,+ `el.classList`, and DOM properties that reflect attributes (`disabled`,+ `hidden`, `value`, `checked`, `type` ...). Siblings are a linked list.+- **`document`** makes detached nodes, which are created natively (with their+ subtree) when inserted into a window's tree; fragments and comments work as+ in the DOM, and a removed node made by `document` that isn't reinserted by+ the end of the tick is freed for you.## React@@ -112,6 +121,71 @@ Host components are HTML elements, as in React DOM:view transitions commit without animating. `createRoot(window)` renders into awindow you opened yourself, and closing the window unmounts its root.+## Svelte++```svelte+<!-- Counter.svelte -->+<script>+ import { Button } from '@blender-ui/svelte'+ let count = $state(0)+</script>++<main class="p-6 flex flex-col gap-3">+ <span>Clicks: {count}</span>+ <Button onclick={() => count++}>Add one</Button>+</main>+```++```js+// app.js: node --import @blender-ui/svelte/register app.js+// (or bun --preload @blender-ui/svelte/register app.js, or npx bui build app.js)+import { render } from '@blender-ui/svelte'+import Counter from './Counter.svelte'++render(Counter, { title: 'BUI + Svelte', width: 420, height: 220, gpu: true })+```++`@blender-ui/svelte` mirrors `@blender-ui/react`: `render(Component, { props,+context, ...windowOptions })`, `createRoot(window)`, `act(fn)` (Svelte's+`flushSync`), Blender's widgets as components and BUI's signals, each of which+is a Svelte store (`$count`). Svelte 5.57 or newer; Node.js 22.15 or newer.++- **How it renders.** Svelte has no custom-renderer API: compiled components+ call the DOM. `@blender-ui/native/globals` provides it (`document`,+ `window`, the node classes), on the same retained tree React uses, so only+ each tick's changes cross to the UI thread. Components compile with+ `fragments: 'tree'` (templates from `createElement`, no HTML parser).+- **`register`** compiles `.svelte` and `.svelte.js` files on import (cached in+ `node_modules/.cache/@blender-ui/svelte`) and resolves `svelte` to its+ browser build; `bui build` finds the same plugin by itself.+- **Events:** Svelte delegates `onclick` and friends to the window's body; an+ element with a delegated handler listens natively, so BUI sends it its+ events, and Svelte bubbles them through `event.composedPath()`.+- **Styles:** a component's scoped `<style>` is added to each window once.+- **Not yet:** transitions run their start and end without animating in+ between; `{@html}` and size bindings (`bind:clientWidth`) aren't there.++## Bindings for other frameworks++React and Svelte are thin adapters over one shared layer, and a new binding+(Vue, Solid, Lit ...) plugs in the same way:++| Shared piece | What it gives a binding |+|---|---|+| `@blender-ui/native` (`dom.js`) | The tree: elements, text, comments, fragments, events, `document` |+| `@blender-ui/native/host` | `open(options)`: the App and window behind `render(..., options)`; `blenderWidgets(wrap)`: Blender's widgets as the framework's components; `applyProps(el, prev, next)`: JSX-style props (`className`, `style` objects, `onClick`, signals) |+| `@blender-ui/native/globals` | `document`, `window`, the node classes and `requestAnimationFrame` as globals, for frameworks whose compiled code calls the DOM |+| `bui build` | Bundles with the Bun plugin of every `@blender-ui/*` package whose `package.json` has `"bui": { "bunPlugin": "./plugin.js" }` |++- **A prop-based renderer** (React's reconciler, Vue's `createRenderer`,+ Solid's `universal` renderer) maps its node operations to+ `window.createElement` / `insertBefore` / `removeChild` and its props to+ `applyProps`.+- **A DOM-based framework** (Svelte, Solid's DOM output, Lit) imports+ `@blender-ui/native/globals` and mounts into `window.body`.+- **A compiler** (Svelte's, Vue's single-file components) ships a Bun plugin and+ declares it in `package.json`, and `bui build` picks it up.+## Hooks and signals`@blender-ui/react` exports React's hooks by React's names. The ones that hold@@ -236,7 +310,10 @@ Options:- `-o <file>`: the output file.- `--console`: keep a console window for logs. By default, Windows builds openno console.-- `--dev`: use React's development build.+- `--dev`: development builds (React's, Svelte's dev mode).++Framework packages add their bundler plugins: with `@blender-ui/svelte`+installed, `.svelte` files bundle as they are.**The default build** is `bui-runtime`, BUI with an embedded[QuickJS](https://github.com/quickjs-ng/quickjs) engine (4.9 MB), with your@@ -297,8 +374,10 @@ builds `bui-runtime` from source.JavaScript makes in its callback join that frame, so there is one rebuildper frame.- **Freeing.** Nodes that React removes, or creates in a render it throws away- (an interrupted or suspended concurrent render), are freed natively. So is- a closed window's tree: its bindings and listeners are released.+ (an interrupted or suspended concurrent render), are freed natively. Nodes+ Svelte drops (removed from a window and not reinserted by the end of the+ tick) are freed too. So is a closed window's tree: its bindings and+ listeners are released.## Performance@@ -398,15 +477,53 @@ Where the memory goes, for plain JS on Node at 3,000 cells:its own copy of the tree.- **JavaScript objects:** a few MB live.+### React and Svelte++The same scenes from `@blender-ui/react` and `@blender-ui/svelte`+(`bench/cells.js 3000 --gpu --react|--svelte [--signals]`, `bench/startup.js+[--svelte]`), on the Ryzen 7 5800U laptop, Windows 11, Node.js 26.13, Bun+1.4.4, in one session (2026-11-06): cells runs interleaved, medians of 3.+"Svelte with signals" passes BUI signals as stores (`{$label}`).++| 3,000 cells, one session | FPS | CPU per frame | RAM |+| ------------------------------------------- | ----------: | ----------------: | -------------: |+| Node 26: React with state / with signals | 27.6 / 27.6 | 42.5 / 36.9 ms | 150 / 98 MB |+| Node 26: Svelte (runes) / with signals | 24.8 / 26.6 | 41.5 / 38.6 ms | 119 / 118 MB |+| Bun 1.4: React with state / with signals | 24.0 / 25.0 | 55.8 / 40.8 ms | 111 / 86 MB |+| Bun 1.4: Svelte (runes) / with signals | 26.4 / 27.0 | 39.3 / 38.2 ms | 100 / 100 MB |+| QuickJS: React with state / with signals | 8.5 / 27.0 | 117 / 37.3 ms | 67 / 62 MB |+| QuickJS: Svelte (runes) / with signals | 26.9 / 25.9 | 37.5 / 38.7 ms | 76 / 76 MB |++| First frame, median of 12 (React / Svelte) | First frame | RAM at first frame |+| ------------------------------------------- | ------------: | -----------------: |+| QuickJS executable (`bui build`, 6.9 MB) | 94 / 89 ms | 20.5 / 19.8 MB |+| Bun executable (`bui build --bun`) | 111 / 107 ms | 37.8 / 38.3 MB |+| Bun (`--preload …/register` for Svelte) | 130 / 243 ms | 36.4 / 46.6 MB |+| Node.js (`--import …/register` for Svelte) | 147 / 440 ms | 46.8 / 64.1 MB |++- **Svelte needs no signals to stay cheap:** runes update the one cell that+ changes, so Svelte costs what React with signals does on every runtime, and+ holds 27 FPS on QuickJS where React re-rendering the grid falls to 8.5.+- **Memory:** Svelte keeps 14–21 MB more than React with signals at 3,000+ cells (its effects and each-block items).+- **Startup:** built with `bui build`, both reach the first frame in about+ 90 ms. On Node.js and Bun, Svelte's runtime loads from about 90 source files+ first (components come from the compile cache).+- **This session ran at about 27 FPS** for every variant (the machine, not the+ code), so compare these rows with each other, not with the tables above.+ React with state cost 45.8 ms and 190 MB on Node in the same session before+ this release's DOM changes (linked siblings, lazy listener maps).+## Building```shcd bindingsnpm install # links the two packages (npm workspaces)npm run build # cargo build -p blenderui-node --release, copies the .node file-npm test # both packages' tests (headless)+npm test # every package's tests (headless)node node/examples/counter.jsnode react/examples/counter.js+node --import ./svelte/register.js svelte/examples/counter.jsbun node/bench/cells.js 3000 --gpu --react --signals # Bun works too```@@ -416,8 +533,9 @@ MinGW, put its `bin` folder on `PATH`.## PublishingThe packages are published under the [`@blender-ui`](https://www.npmjs.com/org/blender-ui)-npm organization. `@blender-ui/react` depends on `@blender-ui/native`-(`^0.2.0`), so publish the native package first, whenever it has changed.+npm organization. `@blender-ui/react` and `@blender-ui/svelte` depend on+`@blender-ui/native`, so publish the native package first, whenever it has+changed.```shnpm login # an account in the blender-ui org@@ -425,6 +543,7 @@ cd bindingsnpm install # link the workspacecd node && npm publish --access public # @blender-ui/native (builds the addon and runtime, runs the tests)cd ../react && npm publish --access public # @blender-ui/react (runs the tests)+cd ../svelte && npm publish --access public # @blender-ui/svelte (runs the tests)```- **`prepublishOnly`** runs the tests before uploading. For the nativediff --git a/examples/site/js/TodoSvelte.svelte b/examples/site/js/TodoSvelte.sveltenew file mode 100644index 0000000..6d8cbcd--- /dev/null+++ b/examples/site/js/TodoSvelte.svelte@@ -0,0 +1,43 @@+<!-- The task list of todo_dom.js and todo_react.js in Svelte 5 (@blender-ui/svelte). -->+<script>+ import { Button, Checkbox, ProgressBar, TextField } from '../../../bindings/svelte/index.js'+ import style from './todo_style.js'+ const { TASKS, TAG_COLORS, CSS } = style++ let tasks = $state(TASKS.map((t) => ({ ...t })))+ let filter = $state('All')+ let draft = $state('')+ const done = $derived(tasks.filter((t) => t.done).length)+ const pct = $derived(Math.round(100 * done / tasks.length))+ const shown = $derived(tasks.filter((t) => filter === 'All' || (filter === 'Done') === t.done))+</script>++<div>+ <svelte:element this={'style'}>{CSS}</svelte:element>+ <div class="head">+ <h1>Robot Arm · Sprint 4</h1>+ <span class="muted">{tasks.length - done} open · {done} done</span>+ </div>+ <div class="add">+ <TextField placeholder="Add a task…" value={draft} oninput={(e) => (draft = e.target.value)} />+ <Button onclick={() => draft && tasks.push({ text: draft, tag: 'Modeling', done: false })}>Add</Button>+ </div>+ <div class="filters">+ {#each ['All', 'Active', 'Done'] as f (f)}+ <span class={filter === f ? 'filter on' : 'filter'} onclick={() => (filter = f)}>{f}</span>+ {/each}+ </div>+ <div class="list">+ {#each shown as task (task.text)}+ <div class={task.done ? 'item done' : 'item'}>+ <Checkbox checked={task.done} onchange={() => (task.done = !task.done)} />+ <span class="text">{task.text}</span>+ <span class="tag" style:background-color={TAG_COLORS[task.tag]}>{task.tag}</span>+ </div>+ {/each}+ </div>+ <div class="foot">+ <ProgressBar class="bar" max="100" value={String(pct)} />+ <span class="muted">{pct}% complete</span>+ </div>+</div>diff --git a/examples/site/js/shoot.mjs b/examples/site/js/shoot.mjsindex d4ed3b6..21a4549 100644--- a/examples/site/js/shoot.mjs+++ b/examples/site/js/shoot.mjs@@ -58,4 +58,7 @@ await save(dom.build(app), 'js-dom-tasks')const react = require('./todo_react.js')const r = react.build({ app })await save(r.window, 'js-react-tasks')+await import('../../../bindings/svelte/register.js') // .svelte files import as components+const svelte = await import('./todo_svelte.mjs')+await save(svelte.build({ app }).window, 'js-svelte-tasks')app.quit()diff --git a/examples/site/js/todo_svelte.mjs b/examples/site/js/todo_svelte.mjsnew file mode 100644index 0000000..c98c505--- /dev/null+++ b/examples/site/js/todo_svelte.mjs@@ -0,0 +1,14 @@+// The task list of todo_dom.js written in Svelte 5 (@blender-ui/svelte):+// TodoSvelte.svelte, state in runes.+// node --import ./bindings/svelte/register.js examples/site/js/todo_svelte.mjs+// bun --preload ./bindings/svelte/register.js examples/site/js/todo_svelte.mjs+import { render } from '../../../bindings/svelte/index.js'+import Tasks from './TodoSvelte.svelte'++export function build (options = {}) {+ const r = render(Tasks, { title: 'Tasks (Svelte)', width: 440, height: 370, ...options })+ r.window.body.setAttribute('styled', '')+ return r+}++if (import.meta.main ?? process.argv[1]?.endsWith('todo_svelte.mjs')) build({ theme: process.env.BUI_THEME })diff --git a/website/WRITING.md b/website/WRITING.mdindex 2538a28..81e3d28 100644--- a/website/WRITING.md+++ b/website/WRITING.md@@ -566,6 +566,7 @@ Already written: `start/introduction`, `start/installation`,| --- | --- | --- || `native-api.mdx` | 10 | `@blender-ui/native`: `App`, windows, `createElement`, attributes, events, `requestAnimationFrame`, headless mode. Source: `docs/javascript.md#plain-javascript` || `react.mdx` | 20 | `@blender-ui/react`: `render`, JSX setup (`jsxImportSource`), host components, Blender components, Suspense and transitions. Source: `docs/javascript.md#react` |+| `svelte.mdx` | 25 | `@blender-ui/svelte`: `render`, `register` (Node.js, Bun), elements and events, Blender components, scoped styles, signals as stores, `bui build`. Source: `docs/javascript.md#svelte` || `signals.mdx` | 30 | Hooks that hold signals: pass `{count}` to update one node, read `count.value` to re-render; the conformance suite. Source: `docs/javascript.md#hooks-and-signals` || `standalone-executables.mdx` | 40 | `bui build` (QuickJS, ~5 MB), `--bun`, `--console`, `--dev`, `bui run`. Source: `docs/javascript.md#standalone-apps` |diff --git a/website/public/images/shots/INDEX.md b/website/public/images/shots/INDEX.mdindex 3c99c32..abb8608 100644--- a/website/public/images/shots/INDEX.md+++ b/website/public/images/shots/INDEX.md@@ -41,6 +41,7 @@ bindings/node).| --- | --- | --- || `js-dom-tasks-{dark,light}.png` | A task list with the native DOM-like API (createElement, appendChild, addEventListener), Blender TextField / Button / Checkbox / ProgressBar | `examples/site/js/todo_dom.js` (+ `todo_style.js`; shot by `shoot.mjs`) || `js-react-tasks-{dark,light}.png` | The same task list in React (@blender-ui/react, hooks) | `examples/site/js/todo_react.js` |+| `js-svelte-tasks-{dark,light}.png` | The same task list in Svelte 5 (@blender-ui/svelte, runes); pixel-identical to the React shot | `examples/site/js/TodoSvelte.svelte` (+ `todo_svelte.mjs`) |## C / C++diff --git a/website/public/images/shots/js-svelte-tasks-dark.png b/website/public/images/shots/js-svelte-tasks-dark.pngnew file mode 100644index 0000000..3d2b22eBinary files /dev/null and b/website/public/images/shots/js-svelte-tasks-dark.png differdiff --git a/website/public/images/shots/js-svelte-tasks-light.png b/website/public/images/shots/js-svelte-tasks-light.pngnew file mode 100644index 0000000..90e833eBinary files /dev/null and b/website/public/images/shots/js-svelte-tasks-light.png differdiff --git a/website/src/components/landing/InstallTabs.astro b/website/src/components/landing/InstallTabs.astroindex 456dc81..ff8aaa5 100644--- a/website/src/components/landing/InstallTabs.astro+++ b/website/src/components/landing/InstallTabs.astro@@ -3,6 +3,7 @@ const commands = [{ id: "pip", label: "pip", cmd: "pip install blenderui", note: "Python 3.11+: tkinter, Qt syntax, components, Dear ImGui" },{ id: "npm", label: "npm", cmd: "npm install @blender-ui/react react", note: "Node.js 18+ or Bun · prebuilt for Windows x64" },{ id: "bun", label: "bun", cmd: "bun add @blender-ui/react react", note: "Bun reads JSX directly: bun app.jsx" },+ { id: "svelte", label: "svelte", cmd: "npm install @blender-ui/svelte svelte", note: "Svelte 5 · Node.js 22.15+ or Bun · prebuilt for Windows x64" },{id: "cargo",label: "cargo",diff --git a/website/src/components/landing/snippets.ts b/website/src/components/landing/snippets.tsindex 514ac61..20c3d1a 100644--- a/website/src/components/landing/snippets.ts+++ b/website/src/components/landing/snippets.ts@@ -235,6 +235,35 @@ render(<Counter />, { title: "Counter", width: 360, height: 200, gpu: true })`,source: "README.md",};+const svelte: Syntax = {+ id: "svelte",+ label: "Svelte",+ title: "Svelte 5, in a native window",+ blurb:+ "Runes, snippets, bindings and scoped styles, unchanged. Svelte's compiled components run on BUI's DOM, so a $state change updates the one node that shows it.",+ lang: "svelte",+ file: "Counter.svelte",+ code: `<script>+ import { Button, NumberSlider } from "@blender-ui/svelte"+ let count = $state(0)+</script>++<main styled class="p-6 flex flex-col gap-3">+ <span>Clicks: {count}</span>+ <Button onclick={() => count++}>Add one</Button>+ <NumberSlider min={0} max={10} />+</main>++<!-- app.js: render(Counter, { title: "Counter", gpu: true }) -->`,+ install: "npm install @blender-ui/svelte svelte",+ shot: "js-svelte-tasks",+ fallback: "images/shots/js-svelte-tasks-dark.png",+ alt: "A task list in Svelte on BUI: a Blender text field and button, checkboxes and a progress bar",+ caption: "examples/site/js/TodoSvelte.svelte, Svelte on BUI",+ docs: "docs/javascript/svelte/",+ source: "bindings/svelte/README.md",+};+const dom: Syntax = {id: "dom",label: "DOM-like API",@@ -431,7 +460,7 @@ int main(void)export const languages: Language[] = [{ id: "python", tab: "Python", icon: "file-py", syntaxes: [tkinter, qt] },{ id: "rust", tab: "Rust", icon: "file-rs", syntaxes: [rsx, gpui, htmlBuilder] },- { id: "javascript", tab: "JavaScript", icon: "file-js", syntaxes: [react, dom] },+ { id: "javascript", tab: "JavaScript", icon: "file-js", syntaxes: [react, svelte, dom] },{ id: "imgui", tab: "Dear ImGui", icon: "squares-four", syntaxes: [imguiCpp, imguiC, imguiPy, imguiRust] },{ id: "c", tab: "C", icon: "file-c", syntaxes: [c] },];diff --git a/website/src/components/site/Footer.astro b/website/src/components/site/Footer.astroindex 32eb09e..1e622fb 100644--- a/website/src/components/site/Footer.astro+++ b/website/src/components/site/Footer.astro@@ -20,6 +20,7 @@ const groups = [["blenderui on crates.io", site.crates],["@blender-ui/react", site.npm],["@blender-ui/native", "https://www.npmjs.com/package/@blender-ui/native"],+ ["@blender-ui/svelte", "https://www.npmjs.com/package/@blender-ui/svelte"],],},{diff --git a/website/src/config/nav.ts b/website/src/config/nav.tsindex 6c94d43..39ae92a 100644--- a/website/src/config/nav.ts+++ b/website/src/config/nav.ts@@ -10,7 +10,7 @@ export const sections = [{ label: "Tutorials", blurb: "Build a first app, one language at a time", icon: "graduation-cap" },{ label: "Python", blurb: "tkinter, Qt syntax and Blender components", icon: "file-py" },{ label: "Rust", blurb: "HTML, CSS, Tailwind, rsx! and hooks, natively", icon: "file-rs" },- { label: "JavaScript & React", blurb: "Node.js, Bun, React and standalone apps", icon: "file-js" },+ { label: "JavaScript & React", blurb: "Node.js, Bun, React, Svelte and standalone apps", icon: "file-js" },{ label: "Dear ImGui", blurb: "The real Dear ImGui, in Blender's theme", icon: "squares-four" },{ label: "C & C++", blurb: "The C kit and embedding BUI in your host", icon: "file-c" },{ label: "Concepts", blurb: "How BUI works under the hood", icon: "lightbulb-filament" },diff --git a/website/src/content/docs/javascript/native-api.mdx b/website/src/content/docs/javascript/native-api.mdxindex 346da1c..ad13404 100644--- a/website/src/content/docs/javascript/native-api.mdx+++ b/website/src/content/docs/javascript/native-api.mdx@@ -6,12 +6,12 @@ section: JavaScript & Reactorder: 10languages: ["javascript"]badges: ["Node.js", "Bun"]-sources: ["docs/javascript.md", "bindings/node/README.md", "bindings/node/index.js", "bindings/node/index.d.ts", "bindings/node/examples/counter.js", "bindings/node/package.json"]+sources: ["docs/javascript.md", "bindings/node/README.md", "bindings/node/index.js", "bindings/node/dom.js", "bindings/node/host.js", "bindings/node/globals.js", "bindings/node/index.d.ts", "bindings/node/examples/counter.js", "bindings/node/package.json"]---If you've ever written `document.createElement`, you already know this API. **`@blender-ui/native` gives you the DOM's shape, Tailwind classes and signals, and draws the result in a native window** with BUI's engine. There's no browser underneath and no webview: just your script, Node.js or Bun, and a small native addon.-It's also the layer the [React renderer](../react/) is built on, so everything here works there too.+It's also the layer the [React renderer](../react/) and the [Svelte binding](../svelte/) are built on, so everything here works there too.<Callout type="note" title="Before you start">You need Node.js 18 or newer, or Bun. Install with `npm install @blender-ui/native` (or `bun add @blender-ui/native`). The addon is prebuilt for Windows x64; on Linux, build it from source. The [installation page](../../start/installation/) has the details.@@ -67,7 +67,7 @@ A window gives you `body`, `createElement(tag)`, `createTextNode(text)`, `reques## Elements and attributes-The tree behaves like the DOM: `appendChild`, `insertBefore`, `removeChild`, `remove()`, `parentNode`, `childNodes`, `firstChild`, `nextSibling` and friends.+The tree behaves like the DOM: `appendChild`, `insertBefore`, `removeChild`, `remove()`, `before`, `after`, `append`, `replaceWith`, `cloneNode`, `parentNode`, `childNodes`, `firstChild`, `nextSibling` and friends. Siblings are a linked list, so inserting, removing and walking siblings cost the same however long the list is.- **Moving a node:** `appendChild` or `insertBefore` on a node that already has a parent moves it.- **Mistakes throw:** inserting a node into itself, or before a node that isn't a child, throws an error, as in a browser.@@ -76,8 +76,8 @@ The tree behaves like the DOM: `appendChild`, `insertBefore`, `removeChild`, `reElements are HTML elements (`div`, `span`, `button`, `input`, `h1` …), laid out with CSS and drawn natively by BUI. They take the usual attributes:- **`class` / `className`**, including Tailwind classes: `'p-4 flex gap-2 bg-[#4772b3]'`.-- **`style`**, as a CSS string (`'color: red'`) or an object (`{ backgroundColor: 'red', width: 40 }`).-- **`id`, `href`, `value`, `src`** and the rest, through `setAttribute`.+- **`style`**, as a CSS string (`'color: red'`) or an object (`{ backgroundColor: 'red', width: 40 }`). Reading `el.style` gives the inline style, with `cssText`, `setProperty` and `removeProperty`; `el.classList` edits `class`.+- **`id`, `href`, `value`, `src`** and the rest, through `setAttribute`. DOM properties such as `disabled`, `hidden`, `checked`, `value` and `type` reflect their attribute. (`el.id` is the node's native id, so set the `id` attribute with `setAttribute`.)Any attribute, `style` and `textContent` can be a **signal**: the node then follows it. Setting a plain value later unbinds the signal.@@ -116,6 +116,23 @@ The events are `click`, `mousedown`, `mouseup`, `mousemove`, `mouseenter`, `mous- **`preventDefault()` only marks the event.** Events reach JavaScript after BUI has already handled them, so it can't cancel what BUI did.- **Form controls** keep their latest value: read `el.value` or `el.checked` after an `input` or `change` event.+## Detached nodes and `document`++`document` (`require('@blender-ui/native').document`) is a window-less document, as DOM frameworks expect one. Its `createElement`, `createTextNode`, `createComment` and `createDocumentFragment` make **detached** nodes: they live in JavaScript until you insert them into a window's tree, which then creates them and their subtree natively in one go. So one template can be cloned (`cloneNode(true)`) into any window.++- **Fragments** insert their children, as in the DOM.+- **Comments** are anchors: natively an empty text node, which takes no space in layout.+- **Freeing:** a node made by `document` that you remove and don't reinsert by the end of the tick is freed natively for you. Nodes made by `win.createElement` keep the explicit `destroy()`.+- **`dispatchEvent(event)`** runs an element's listeners (and its ancestors', if the event bubbles); `event.composedPath()` lists the target and its ancestors. Listeners for event types BUI doesn't report are accepted, and only fire through `dispatchEvent`.++## Framework bindings++The React and Svelte packages are thin adapters over this API, and a binding for another framework plugs in the same way:++- **`@blender-ui/native/host`** holds what every binding shares: `open(options)` (the `App` and window behind a `render(..., options)`), `blenderWidgets(wrap)` (Blender's widgets as the framework's components) and `applyProps(el, prev, next)` (JSX-style props such as `className`, `style` objects, `onClick` and signals, onto an element). A renderer that works with props (React's reconciler; Vue's or Solid's custom renderers) calls these.+- **`@blender-ui/native/globals`** installs `document`, `window`, the node classes and `requestAnimationFrame` as globals, for frameworks whose compiled code calls the DOM (Svelte; Solid's or Lit's DOM output too).+- **`bui build`** bundles with the Bun plugin of every `@blender-ui/*` package that declares one in its `package.json` (`"bui": { "bunPlugin": "./plugin.js" }`). That's how `.svelte` files compile into a standalone app.+## Frames and measuring```js@@ -173,6 +190,9 @@ The numbers, with their context, are on the [standalone executables](../standalo<Card title="React" href="docs/javascript/react/" icon="layers" kicker="JavaScript">The same engine, written as JSX components with React's hooks.</Card>+ <Card title="Svelte" href="docs/javascript/svelte/" icon="layers" kicker="JavaScript">+ Svelte 5 components, runes and snippets on the same engine.+ </Card><Card title="Signals" href="docs/javascript/signals/" icon="zap" kicker="JavaScript">How a signal updates one node without re-rendering anything.</Card>diff --git a/website/src/content/docs/javascript/svelte.mdx b/website/src/content/docs/javascript/svelte.mdxnew file mode 100644index 0000000..8a02fec--- /dev/null+++ b/website/src/content/docs/javascript/svelte.mdx@@ -0,0 +1,172 @@+---+title: Svelte on the desktop+sidebarLabel: Svelte+description: Mount Svelte 5 components into native BUI windows with runes, snippets, Tailwind classes and Blender's widgets, on Node.js or Bun.+section: JavaScript & React+order: 25+languages: ["javascript"]+badges: ["Svelte 5.57"]+sources: ["docs/javascript.md", "bindings/svelte/README.md", "bindings/svelte/index.js", "bindings/svelte/events.js", "bindings/svelte/compile.js", "bindings/svelte/index.d.ts", "bindings/svelte/package.json", "bindings/svelte/examples/Counter.svelte", "bindings/svelte/examples/counter.js", "bindings/node/globals.js", "bindings/node/dom.js"]+---++Write Svelte components as you would for the browser, and get a native desktop window instead. **`@blender-ui/svelte` mounts Svelte 5 components into BUI**: runes, snippets, bindings, transitions and `{#each}` blocks work as they do on the web, BUI draws the result on the CPU or the GPU, and Blender's widgets are one import away. No Electron, no webview.++Svelte is already fine-grained: a `$state` change updates the one node that shows it, and that's what BUI sends to its UI thread. Your component code is plain Svelte.++## Install++```sh+npm install @blender-ui/svelte svelte+# or+bun add @blender-ui/svelte svelte+```++It brings `@blender-ui/native` with it. Svelte 5.57 or newer is a peer dependency, and Node.js needs to be 22.15 or newer (Bun works too). The native addon is prebuilt for Windows x64; on Linux, [build it from source](../../start/installation/).++## Your first component++```svelte title="Counter.svelte"+<script>+ import { Button } from '@blender-ui/svelte'+ let count = $state(0)+</script>++<main class="p-6 flex flex-col gap-3 bg-[#2b2b2b] text-[#e6e6e6]">+ <span>Clicks: {count}</span>+ <Button onclick={() => count++}>Add one</Button>+</main>+```++```js title="app.js"+import { render } from '@blender-ui/svelte'+import Counter from './Counter.svelte'++render(Counter, { title: 'Counter', width: 360, height: 200, gpu: true })+```++Run it:++```sh+node --import @blender-ui/svelte/register app.js+# or+bun --preload @blender-ui/svelte/register app.js+```++`register` teaches the runtime two things: `.svelte` files (and `.svelte.js` rune modules) import as compiled components, and `svelte` resolves to its browser build. Compiled components are cached in `node_modules/.cache/@blender-ui/svelte`, so later starts skip Svelte's compiler. With Bun you can put the preload in `bunfig.toml` instead: `preload = ["@blender-ui/svelte/register"]`.++## `render` and `createRoot`++`render(Component, options)` opens a window and mounts the component into it. It returns `{ app, window, root, component }`, where `component` holds the component's exports.++| Option | What it does |+| --- | --- |+| `props` | The component's props |+| `context` | A `Map` of context for the component tree, as in Svelte's `mount` |+| `title`, `width`, `height`, `resizable` | The window |+| `gpu` | Draw on the GPU (Direct3D 11 on Windows, OpenGL on Linux) |+| `slug` | GPU text from glyph outlines (default) or an atlas |+| `headless` | Render off-screen: tests and CI |+| `theme` | Blender's `'dark'` (default) or `'light'` theme |+| `app` | Reuse an `App` you already made, to open several windows |++`window` is a [`@blender-ui/native` window](../native-api/), so you can style its body directly:++```js+const { window } = render(Counter, { title: 'BUI + Svelte', width: 420, height: 260 })+window.body.setAttribute('styled', '') // Blender's look for every element+window.body.className = 'm-0 bg-[#2b2b2b] text-[#e6e6e6]'+```++To mount into a window you opened yourself, use `createRoot(window)`, then `root.render(Component, { props })` and `root.unmount()`. Closing the window unmounts its root (`onDestroy` runs). For tests, `act(fn)` runs `fn` and applies Svelte's pending updates at once (`flushSync`).++## Elements, events and bindings++Elements are HTML elements, as in the browser:++- **`class`** takes Tailwind classes, and `class={{ on: active }}` objects and arrays work. **`style`** takes a string; `style:color={c}` directives work.+- **Mouse, keyboard and form events** work: `onclick`, `onmousedown`, `onmouseup`, `onmousemove`, `onmouseenter`, `onmouseleave`, `onwheel`, `onkeydown`, `onkeyup`, `oninput` and `onchange`. They bubble, and `stopPropagation` works. Svelte delegates most of them to the window's body, as on the web.+- **Bindings:** `bind:value`, `bind:checked`, `bind:group` and `bind:this` work.+- **Blocks:** `{#if}`, `{#each}` (keyed too), `{#await}`, `{#key}` and snippets with `{@render}` work, and so do context, `onMount` and `onDestroy`.+- **Transitions** (`transition:`, `in:`, `out:`) run their start and end, without animating in between, for now: an outro removes its element at once.++## Blender's widgets++Import Blender's widgets as components. They're always drawn and handled the Blender way: drag a number to change it, <Kbd>Ctrl</Kbd> to snap, and click to type a value or a sum such as `2*pi`.++```svelte title="Panel.svelte"+<script>+ import { NumberSlider, Button } from '@blender-ui/svelte'+ let size = $state(2.5)+</script>++<main class="p-4 flex flex-col gap-2">+ <NumberSlider min={0} max={10} value={size} oninput={(e) => (size = Number(e.target.value))} />+ <Button onclick={() => console.log('apply', size)}>Apply</Button>+</main>+```++<Figure+ shot="js-svelte-tasks"+ alt="A task list in Svelte on BUI: a Blender text field and Add button, a list of tasks with Blender checkboxes, and a progress bar"+ caption="Blender components in a Svelte app: <code>TextField</code>, <code>Button</code>, <code>Checkbox</code> and <code>ProgressBar</code> (<code>examples/site/js/TodoSvelte.svelte</code>)."+/>++The ten components are `Button`, `Checkbox`, `Radio`, `NumberField`, `NumberSlider`, `TextField`, `TextArea`, `ColorSwatch`, `Dropdown` and `ProgressBar`. Each is an HTML element underneath (`NumberSlider` is an `<input type="range">`), so it takes the same attributes and events. Their lowercase twins (`<button>`, `<input>`) look like a browser's controls, except inside a `styled` element.++## Styles++A component's `<style>` block works: Svelte scopes it to the component, and BUI adds each component's stylesheet to a window once, however many instances it shows. Tailwind classes and `style` attributes work everywhere, as in the other bindings.++## Signals++Runes are the way to hold state in Svelte, and they're already fine-grained. For state that lives outside components, `@blender-ui/svelte` exports BUI's signals (`signal`, `computed`, `effect`, `batch`, `untrack`, `createSignal`, `ref`). Each one is a Svelte store, so `$count` follows it inside a component:++```svelte+<script>+ import { selection } from './store.js' // export const selection = signal([])+</script>++<p>{$selection.length} selected</p>+```++## Standalone apps++`bui build` bundles `.svelte` files too: the Svelte package registers its bundler plugin with `bui`, so there's nothing to configure.++```sh+npx bui build app.js # app.exe: BUI + QuickJS, one small file+npx bui build app.js --bun # app.exe: a Bun executable+npx bui run app.js # run on the QuickJS runtime, no build+```++See [standalone executables](../standalone-executables/) for the options.++## Performance++The same scenes from Svelte and from the React binding, measured in one session:++<BenchChart id="js-frameworks-cpu-3000" />++<BenchTable id="jsFrameworksStartup" />++Svelte's runes update only what changed, so a 3,000-cell grid with one cell changing per frame costs what React with signals does, on Node.js, Bun and QuickJS alike. Built with `bui build`, a Svelte app reaches its first frame as fast as a React one; on Node.js and Bun, Svelte's runtime loads from its source files first. The [benchmarks page](../../performance/benchmarks/) has the method.++## How it works++Svelte has no custom-renderer API: a compiled component calls the DOM directly (`createElement`, `cloneNode`, `insertBefore`, `addEventListener` ...). `@blender-ui/native` provides that DOM. `document` makes detached nodes that join a window's retained tree when they're inserted into it, comments and empty text nodes act as anchors without taking any space, and only the changes of each tick cross to BUI's UI thread. Nodes Svelte drops are freed natively at the end of the tick.++Components are compiled with `fragments: 'tree'`, so templates are built with `createElement` rather than an HTML parser.++## Next steps++<CardGrid>+ <Card title="React" href="docs/javascript/react/" icon="atom" kicker="JavaScript">+ The same windows and widgets from React 19.3, with signal-backed hooks.+ </Card>+ <Card title="Standalone executables" href="docs/javascript/standalone-executables/" icon="terminal" kicker="JavaScript">+ Turn app.js into one small executable.+ </Card>+ <Card title="The DOM-like API" href="docs/javascript/native-api/" icon="book" kicker="JavaScript">+ The layer underneath: windows, elements, events, headless tests, and how a framework plugs in.+ </Card>+</CardGrid>diff --git a/website/src/content/docs/performance/benchmarks.mdx b/website/src/content/docs/performance/benchmarks.mdxindex 7d007ce..e872a48 100644--- a/website/src/content/docs/performance/benchmarks.mdx+++ b/website/src/content/docs/performance/benchmarks.mdx@@ -101,6 +101,18 @@ More results, at 100 and 1,000 cells:- **Signals make React as cheap as the plain API:** the component doesn't re-render.- **QuickJS** starts fastest and uses the least memory, from a 5 MB file. It has no JIT, so re-rendering a 3,000-element list every frame drops it to 20 FPS. Keep big lists on signals, or build with `--bun`.+### React and Svelte, side by side++**What was measured:** the same scenes from `@blender-ui/react` and `@blender-ui/svelte`, in one session, runs interleaved (`bench/cells.js --react | --svelte [--signals]`, `bench/startup.js [--svelte]`). This session's machine ran every variant at about 27 FPS, so compare these rows with each other, not with the tables above.++<BenchChart id="js-frameworks-cpu-3000" />++<BenchTable id="jsFrameworksStartup" />++- **Svelte needs no signals to stay cheap:** its runes update the one cell that changes, so it costs what React with signals does, on every runtime. React with state re-renders the grid and falls to 8.5 FPS on QuickJS; Svelte holds 27.+- **Memory:** Svelte keeps more per element than React with signals (its effects and each-block items), 14–21 MB more at 3,000 cells.+- **Startup:** built into an executable, both start in about 90 ms. On Node.js and Bun, Svelte's runtime loads from about 90 source files, which costs 0.1–0.3 s; `bui build` bundles it.+<Callout type="joke">Unlike a Cycles render, these numbers don't get any less noisy if you leave them running overnight. Run each benchmark a few times instead.</Callout>diff --git a/website/src/content/docs/start/installation.mdx b/website/src/content/docs/start/installation.mdxindex e38b8d5..8a81be9 100644--- a/website/src/content/docs/start/installation.mdx+++ b/website/src/content/docs/start/installation.mdx@@ -75,7 +75,15 @@ npm install @blender-ui/react reactbun add @blender-ui/react react```-For the DOM-like API without React:+For Svelte 5 (Node.js 22.15 or newer, or Bun):++```sh+npm install @blender-ui/svelte svelte+# or+bun add @blender-ui/svelte svelte+```++For the DOM-like API without a framework:```shnpm install @blender-ui/nativediff --git a/website/src/content/docs/start/introduction.mdx b/website/src/content/docs/start/introduction.mdxindex 5c14634..febcceb 100644--- a/website/src/content/docs/start/introduction.mdx+++ b/website/src/content/docs/start/introduction.mdx@@ -44,7 +44,7 @@ Every row below drives the same C kit, so they all get the same widgets and inte["<strong>Qt-style Python</strong> (<code>QWidget</code>, layouts, <code>clicked.connect</code>)", "partial", "The common subset of Qt widgets"],["<strong>Blender components</strong> (<code>Panel</code>, <code>NumberSlider</code>, <code>PieMenu</code> …)", "done", "45 native Blender widgets and editors from Python"],["<strong>Rust</strong> with HTML, CSS, Tailwind, <code>rsx!</code> or gpui-style builders, and hooks", "done", "A web-like framework, drawn natively"],- ["<strong>JavaScript or React</strong> on Node.js or Bun", "done", "The same engine, with React's hooks backed by signals"],+ ["<strong>JavaScript, React or Svelte</strong> on Node.js or Bun", "done", "The same engine, with React's hooks backed by signals, or Svelte 5 components"],["<strong>Dear ImGui</strong> from C++, C, Python or Rust", "done", "The real Dear ImGui, in Blender's theme or with Blender's widgets"],["<strong>C</strong> (<code>BUI_kit.h</code>)", "done", "The kit itself"],]} />diff --git a/website/src/data/bench.ts b/website/src/data/bench.tsindex d23f84c..5d33c94 100644--- a/website/src/data/bench.ts+++ b/website/src/data/bench.ts@@ -193,6 +193,34 @@ const tablesBase = {],note: "Plain JS uses @blender-ui/native; React with signals renders the grid once; React with state re-renders it every frame. React's production build throughout.",},+ jsFrameworksStartup: {+ caption:+ "React vs Svelte, startup: the same small counter app (bench/first-frame.js, bench/first-frame-svelte.js) quits after its first frame; median of 12 launches after a warm-up, one session (2026-11-06)",+ columns: ["First frame (React / Svelte)", "React", "Svelte", "RAM at first frame (React / Svelte)"],+ numeric: [1, 2, 3],+ rows: [+ ["<strong>QuickJS executable</strong> (bui build, 6.9 MB either way)", "94 ms", "<strong>89 ms</strong>", "20.5 / <strong>19.8 MB</strong>"],+ ["Bun executable (bui build --bun)", "111 ms", "107 ms", "37.8 / 38.3 MB"],+ ["Bun (bun --preload …/register app.js)", "<strong>130 ms</strong>", "243 ms", "<strong>36.4</strong> / 46.6 MB"],+ ["Node.js (node --import …/register app.js)", "<strong>147 ms</strong>", "440 ms", "<strong>46.8</strong> / 64.1 MB"],+ ],+ note: "On Node.js and Bun, Svelte's runtime loads from its source files (about 90 modules) and components come from the compile cache; bui build bundles both frameworks ahead of time.",+ },+ jsFrameworks3000: {+ caption:+ "React vs Svelte, 3,000 animated cells (bench/cells.js): one cell changes per frame, GPU renderer, medians of 3 interleaved runs, one session (2026-11-06)",+ columns: ["3,000 cells", "FPS", "CPU per frame", "RAM"],+ numeric: [1, 2, 3],+ rows: [+ ["Node 26: React with state / React with signals", "27.6 / 27.6", "42.5 / 36.9 ms", "150 / <strong>98 MB</strong>"],+ ["Node 26: Svelte (runes) / Svelte with signals", "24.8 / 26.6", "41.5 / 38.6 ms", "119 / 118 MB"],+ ["Bun 1.4: React with state / React with signals", "24.0 / 25.0", "55.8 / 40.8 ms", "111 / <strong>86 MB</strong>"],+ ["Bun 1.4: Svelte (runes) / Svelte with signals", "26.4 / 27.0", "39.3 / <strong>38.2 ms</strong>", "100 / 100 MB"],+ ["QuickJS: React with state / React with signals", "8.5 / 27.0", "117 / <strong>37.3 ms</strong>", "67 / <strong>62 MB</strong>"],+ ["QuickJS: Svelte (runes) / Svelte with signals", "26.9 / 25.9", "37.5 / 38.7 ms", "76 / 76 MB"],+ ],+ note: "This session ran at about 27 FPS for every variant, so the absolute numbers aren't comparable with the tables above; compare the rows with each other. Svelte with runes needs no signals: only the cell that changes updates. Svelte with signals passes BUI signals as stores ($style). The same session's React with state cost 45.8 ms and 190 MB on Node before this release's DOM changes.",+ },jsAnim1000: {caption: "JavaScript animation, 1,000 cells",columns: ["1,000 cells", "FPS", "CPU per frame", "RAM"],@@ -640,6 +668,21 @@ export const charts = {table: "jsStartup",source: sources.readme,},+ "js-frameworks-cpu-3000": {+ kind: "groups",+ title: "React vs Svelte: CPU per frame, 3,000 cells",+ subtitle: "One cell changes per frame; GPU renderer; one session, interleaved runs",+ unit: "ms",+ better: "lower",+ series: [{ name: "React + signals", ours: true }, { name: "React + state" }, { name: "Svelte (runes)", ours: true }, { name: "Svelte + signals", ours: true }],+ groups: [+ { label: "QuickJS", values: [37.3, 117, 37.5, 38.7] },+ { label: "Bun 1.4", values: [40.8, 55.8, 39.3, 38.2] },+ { label: "Node 26", values: [36.9, 42.5, 41.5, 38.6] },+ ],+ table: "jsFrameworks3000",+ source: sources.js,+ },"js-cpu-3000": {kind: "groups",title: "JavaScript: CPU per frame, 3,000 cells",