@blender-ui/native 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,19 @@
 # @blender-ui/native
 
-Blender's UI toolkit from JavaScript: native windows drawn on the CPU or with
-Direct3D 11, HTML elements, CSS and Tailwind classes, and signals. It runs on
-Node.js and Bun through a native addon (napi-rs), with no browser and no
-Electron. For React, see
-[`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react).
+[![npm](https://img.shields.io/npm/v/@blender-ui/native)](https://www.npmjs.com/package/@blender-ui/native)
+[![license](https://img.shields.io/npm/l/@blender-ui/native)](https://github.com/ppmpreetham/BUI/blob/main/LICENSE)
+
+[BUI](https://github.com/ppmpreetham/BUI), Blender's UI toolkit, from
+JavaScript. It gives you native windows drawn on the CPU or with Direct3D 11,
+HTML elements, CSS and Tailwind classes, and signals. It runs on Node.js and
+Bun through a napi-rs addon, and `bui build` turns an app into a single
+executable 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.
 
 ```sh
-npm install @blender-ui/native
+npm install @blender-ui/native        # or: bun add @blender-ui/native
 ```
 
 ```js
@@ -30,40 +36,91 @@ win.body.appendChild(button)
 ## API
 
 - **A DOM-like tree:** `createElement`, `createTextNode`, `appendChild`,
-  `insertBefore`, `removeChild`, `setAttribute`, `className` (with Tailwind
-  classes), `style` (a string or an object), `textContent`.
+  `insertBefore`, `removeChild`, `setAttribute`, `className` (Tailwind
+  classes included), `style` (a string or an object), `textContent`.
+  - Moving nodes and the error cases behave as in the DOM.
+  - `destroy()` frees a removed subtree natively.
 - **Events:** `addEventListener` for `click`, `mousedown`, `mouseup`,
   `mousemove`, `mouseenter`, `mouseleave`, `wheel`, `keydown`, `keyup`, `input`
-  and `change`. They bubble through the tree, and `stopPropagation()` works.
-  They arrive after BUI has handled them, so `preventDefault()` only marks the
-  event.
+  and `change`.
+  - They bubble through the tree, and `stopPropagation()` works.
+  - They arrive after BUI has handled them, so `preventDefault()` only marks
+    the event.
 - **Frames and measurement:** `win.requestAnimationFrame(cb)` is paced by the
   display. `el.getBoundingClientRect()` and `win.screenshot()` return
   promises.
 - **Signals:** `signal`, `memo`, `effect`, `batch`, `untrack`,
-  `startTransition`. Pass a signal to `setAttribute`, `style`, `textContent`
-  or `createTextNode`, and its changes update that node alone. The signals are
-  also available without the addon: `require('@blender-ui/native/signals')`.
+  `startTransition`.
+  - Pass a signal to `setAttribute`, `style` (or inside a style object),
+    `textContent` or `createTextNode`, and its changes update that node
+    alone.
+  - Memos and effects track what they read, are glitch-free, and need no
+    dependency arrays.
+  - Without the addon: `require('@blender-ui/native/signals')`.
 - **Tests:** `new App({ headless: true })` renders off-screen, and
   `win.click(x, y)` simulates input.
 
+## Standalone apps
+
+```sh
+npx bui build app.js           # app.exe: BUI + embedded QuickJS, ~5 MB
+npx bui build app.js --bun     # app.exe: Bun, with Node's APIs and a JIT, ~115 MB
+npx bui run app.js             # run on the QuickJS runtime, no build
+```
+
+Options:
+
+- `-o <file>`: the output file.
+- `--console`: keep a console window for logs (Windows builds open none).
+- `--dev`: React's development build.
+
+Bundling uses [Bun](https://bun.sh), so it must be installed.
+
+**How the default build works.** It appends your bundled app to `bui-runtime`,
+BUI with the QuickJS engine embedded. That takes under a second and compiles
+nothing.
+
+- **It's fast to start:** the result reaches its first frame in about 70 ms
+  and uses 19 MB of RAM there.
+- **It's limited:** no Node modules (`fs` and the like) and no JIT. Keep
+  frequent updates on signals, or use `--bun`.
+
 ## How it's fast
 
 - **Its own UI thread:** BUI renders on a thread of its own, so it never
-  blocks Node and an idle window uses no CPU.
-- **Only changes cross:** each tick, a window sends one batch of operations
-  (an `Int32Array` and a string table) to the UI thread.
+  blocks JavaScript, and an idle window uses no CPU.
+- **Only changes cross:** each tick, a window sends one batch of operations,
+  an `Int32Array` and a string table.
 - **Styles parsed once:** a `style` value is parsed when it's set, not every
   frame.
 
+## Benchmarks
+
+Ryzen 7 5800U laptop, Windows 11, GPU renderer. Method:
+[guide](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md#performance).
+
+| Startup (small app, quits at first frame) | First frame | Launch to exit | RAM | Size |
+|---|---:|---:|---:|---:|
+| **`bui build`** (QuickJS) | **68 ms** | **104 ms** | **19 MB** | **4.9 MB** |
+| `bui build --bun` | 79 ms | 147 ms | 35 MB | 114 MB |
+| `bun app.js` | 80 ms | 152 ms | 35 MB | |
+| `node app.js` | 108 ms | 187 ms | 45 MB | |
+
+| 3,000 cells, one changing per frame | FPS | CPU per frame | RAM |
+|---|---:|---:|---:|
+| Bun | 58.8 | 13.1 ms | 80 MB |
+| Node.js | 55.8 | 14.4 ms | 88 MB |
+| QuickJS (`bui build`) | 59.1 | 16.3 ms | 56 MB |
+| *Rust, for reference* | 59.6 | 12.0 ms | 43 MB |
+
 ## Requirements
 
-- **Prebuilt for Windows x64.** On other platforms, build from a clone of the
+- **Prebuilt for Windows x64.** Elsewhere, build from a clone of the
   [repository](https://github.com/ppmpreetham/BUI) with `npm run build` in
-  `bindings/node`. That needs Rust, CMake and a C compiler; native windows
-  there are not supported yet, so use `headless: true`.
+  `bindings/node`. You need Rust, CMake and a C compiler, and native windows
+  aren't supported there yet, so use `headless: true`.
 - **Runtimes:** Node.js 18 or newer, or Bun.
 
-Guide, benchmarks and internals:
-[docs/javascript.md](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md).
-License: GPL-2.0-or-later.
+Guide: [docs/javascript.md](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md) ·
+Source: [github.com/ppmpreetham/BUI](https://github.com/ppmpreetham/BUI) ·
+License: GPL-2.0-or-later

package/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// bui: build standalone apps from a JavaScript / JSX entry.
+//
+//   bui build app.jsx [-o app.exe]   a small executable: BUI + QuickJS (~5 MB)
+//   bui build app.jsx --bun          a Bun executable (full Node APIs, ~120 MB)
+//   bui run app.jsx [args]           run on the small runtime (no executable)
+//
+// Options:
+//   -o, --out <file>   output file (default: the entry's name, .exe on Windows)
+//   --bun              compile with `bun build --compile` instead of QuickJS
+//   --console          keep a console window (Windows; default: none, for apps)
+//   --dev              React's development build (default: production)
+//
+// Bundling uses Bun (https://bun.sh), which must be installed.
+// SPDX-License-Identifier: GPL-2.0-or-later
+'use strict'
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+const MAGIC = Buffer.from('BUIAPP01')
+const TAG = `${process.platform}-${process.arch}`
+const EXE = process.platform === 'win32' ? '.exe' : ''
+
+function fail (msg) {
+  console.error(`bui: ${msg}`)
+  process.exit(1)
+}
+
+function parse (argv) {
+  const o = { cmd: argv[0], entry: null, out: null, bun: false, console: false, dev: false, rest: [] }
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (o.cmd === 'run' && o.entry !== null) o.rest.push(a)
+    else if (a === '-o' || a === '--out') o.out = argv[++i]
+    else if (a === '--bun') o.bun = true
+    else if (a === '--console') o.console = true
+    else if (a === '--dev') o.dev = true
+    else if (a.startsWith('-')) fail(`unknown option ${a}`)
+    else o.entry = a
+  }
+  return o
+}
+
+/** The QuickJS runtime shipped in this package (or the workspace build). */
+function runtimePath () {
+  const shipped = path.join(__dirname, `bui-runtime.${TAG}${EXE}`)
+  if (fs.existsSync(shipped)) return shipped
+  const built = path.join(__dirname, '../rust/target/release', `bui-runtime${EXE}`)
+  if (fs.existsSync(built)) return built
+  fail(`no bui-runtime for ${TAG}: prebuilt for Windows x64; run \`npm run build\` in bindings/node to build it`)
+}
+
+/** Bun's executable: this process when running on Bun; otherwise asked once
+ *  (npm installs it behind a shell shim on Windows), then run without a shell
+ *  so arguments keep their quotes. */
+let bunPath = null
+function findBun () {
+  if (bunPath !== null) return bunPath
+  if (typeof Bun !== 'undefined') return (bunPath = process.execPath)
+  const r = spawnSync('bun', ['-e', 'process.stdout.write(process.execPath)'],
+    { encoding: 'utf8', shell: process.platform === 'win32' })
+  if (r.status !== 0 || !r.stdout) fail('bundling needs Bun: https://bun.sh')
+  return (bunPath = r.stdout.trim())
+}
+
+function bun (args, opts = {}) {
+  const r = spawnSync(findBun(), args, { stdio: opts.quiet ? 'pipe' : 'inherit', encoding: 'utf8' })
+  if (r.status !== 0) fail(`bun ${args[0]} failed${r.stderr ? `:
+${r.stderr}` : ''}`)
+  return r
+}
+
+/** One script for QuickJS: the app and its packages, React in production mode. */
+function bundle (entry, dev) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bui-'))
+  // an ES module importing the entry: Bun's IIFE output runs a CommonJS
+  // entry only when something imports it
+  const wrapper = path.join(dir, 'entry.mjs')
+  fs.writeFileSync(wrapper, `import ${JSON.stringify(path.resolve(entry).split(path.sep).join('/'))}\n`)
+  const out = path.join(dir, 'app.js')
+  bun(['build', wrapper, '--target=browser', '--format=iife', '--minify',
+    `--define=process.env.NODE_ENV="${dev ? 'development' : 'production'}"`,
+    '--external=node:*', '--external=*.node', `--outfile=${out}`], { quiet: true })
+  const js = fs.readFileSync(out)
+  fs.rmSync(dir, { recursive: true, force: true })
+  return js
+}
+
+/** Windows: mark the executable as a windowed app (no console window). */
+function setGuiSubsystem (buf) {
+  if (buf.readUInt16LE(0) !== 0x5a4d) return
+  const pe = buf.readUInt32LE(0x3c)
+  if (buf.readUInt32LE(pe) !== 0x4550) return
+  buf.writeUInt16LE(2, pe + 24 + 68) // IMAGE_SUBSYSTEM_WINDOWS_GUI
+}
+
+function build (o) {
+  const name = path.basename(o.entry).replace(/\.[^.]+$/, '')
+  const out = path.resolve(o.out ?? `${name}${EXE}`)
+  const t0 = Date.now()
+  if (o.bun) {
+    const args = ['build', '--compile', '--minify', o.entry, `--outfile=${out}`,
+      `--define=process.env.NODE_ENV="${o.dev ? 'development' : 'production'}"`]
+    if (process.platform === 'win32' && !o.console) args.push('--windows-hide-console')
+    bun(args)
+  } else {
+    const js = bundle(o.entry, o.dev)
+    const runtime = fs.readFileSync(runtimePath())
+    if (process.platform === 'win32' && !o.console) setGuiSubsystem(runtime)
+    const trailer = Buffer.alloc(16)
+    MAGIC.copy(trailer, 0)
+    trailer.writeBigUInt64LE(BigInt(js.length), 8)
+    fs.writeFileSync(out, Buffer.concat([runtime, js, trailer]))
+    if (process.platform !== 'win32') fs.chmodSync(out, 0o755)
+  }
+  const mb = (fs.statSync(out).size / 1048576).toFixed(1)
+  console.log(`bui: built ${path.relative(process.cwd(), out)} (${mb} MB, ${o.bun ? 'Bun' : 'QuickJS'}) in ${Date.now() - t0} ms`)
+}
+
+function run (o) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bui-run-'))
+  const file = path.join(dir, `${path.basename(o.entry).replace(/\.[^.]+$/, '')}.js`)
+  fs.writeFileSync(file, bundle(o.entry, o.dev))
+  const r = spawnSync(runtimePath(), [file, ...o.rest], { stdio: 'inherit' })
+  fs.rmSync(dir, { recursive: true, force: true })
+  process.exit(r.status ?? 1)
+}
+
+const o = parse(process.argv.slice(2))
+if (!['build', 'run'].includes(o.cmd) || !o.entry) {
+  console.log(fs.readFileSync(__filename, 'utf8').split('\n').slice(1, 14).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'))
+  process.exit(o.cmd ? 1 : 0)
+}
+if (!fs.existsSync(o.entry)) fail(`no such file: ${o.entry}`)
+if (o.cmd === 'build') build(o)
+else run(o)

package/index.js

@@ -10,21 +10,26 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 'use strict'
 
-const path = require('node:path')
-
-const addon = process.env.BUI_NODE_ADDON ||
-  path.join(__dirname, `blenderui.${process.platform}-${process.arch}.node`)
-let native
-try {
-  native = require(addon)
-} catch (err) {
-  throw new Error(`@blender-ui/native: no native addon for ${process.platform}-${process.arch} (${addon}). ` +
-    'Prebuilt binaries are for Windows x64; elsewhere, build it from a clone of ' +
-    'https://github.com/ppmpreetham/BUI with `npm run build` in bindings/node (needs Rust, CMake and a C compiler).',
-  { cause: err })
+// The native layer: the QuickJS runtime's built-in one (bui-runtime, apps
+// made by `bui build`), or the napi addon (Node.js, Bun).
+const native = globalThis.__BUI_NATIVE__ ?? loadAddon()
+
+function loadAddon () {
+  const env = process.env.BUI_NODE_ADDON
+  try {
+    // a literal path where a prebuilt binary exists: `bun build --compile` (and
+    // other bundlers) can then embed the addon in the executable
+    if (!env && process.platform === 'win32' && process.arch === 'x64') return require('./blenderui.win32-x64.node')
+    return require(env || require('node:path').join(__dirname, `blenderui.${process.platform}-${process.arch}.node`))
+  } catch (err) {
+    throw new Error(`@blender-ui/native: no native addon for ${process.platform}-${process.arch}. ` +
+      'Prebuilt binaries are for Windows x64; elsewhere, build it from a clone of ' +
+      'https://github.com/ppmpreetham/BUI with `npm run build` in bindings/node (needs Rust, CMake and a C compiler).',
+    { cause: err })
+  }
 }
 const signals = require('./signals')
-const { isSignal, effect, unowned } = signals
+const { isSignal, effect, unowned, memo } = signals
 
 // Keep in sync with bindings/rust/blenderui-node/src/lib.rs.
 const OP = { CREATE: 0, TEXT: 1, SET_ATTR: 2, REMOVE_ATTR: 3, APPEND: 4, INSERT: 5, REMOVE: 6, SET_TEXT: 7, LISTEN: 8, FREE: 9 }
@@ -246,7 +251,13 @@ class Element extends Node {
   set className (v) { this.setAttribute('class', v) }
   get style () { return this._attrs.get('style') ?? '' }
   /** A CSS declaration string, or an object (`{ backgroundColor: 'red', width: 40 }`). */
-  set style (v) { this.setAttribute('style', typeof v === 'string' || isSignal(v) ? v : styleText(v)) }
+  set style (v) {
+    if (v == null) return this.removeAttribute('style')
+    if (typeof v === 'string' || isSignal(v)) return this.setAttribute('style', v)
+    // an object: plain values, or some signals (`{ color: colorSignal }`), then bound
+    for (const k in v) if (isSignal(v[k])) return this.setAttribute('style', memo(() => styleText(v)))
+    this.setAttribute('style', styleText(v))
+  }
   get textContent () { return super.textContent }
   set textContent (t) {
     for (const c of [...this.childNodes]) { this.removeChild(c); c.destroy() }
@@ -310,7 +321,8 @@ const UNITLESS = new Set(['opacity', 'z-index', 'flex', 'flex-grow', 'flex-shrin
 function styleText (o) {
   let s = ''
   for (const k in o) {
-    const v = o[k]
+    const raw = o[k]
+    const v = isSignal(raw) ? raw.value : raw // read: a memo around this follows it
     if (v == null || v === false || v === '') continue
     const prop = k.startsWith('--') ? k : k.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
     s += `${prop}: ${typeof v === 'number' && v !== 0 && !UNITLESS.has(prop) ? v + 'px' : v}; `

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@blender-ui/native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Blender's UI from JavaScript: native windows (CPU or Direct3D 11), HTML elements, CSS and Tailwind classes, signals. Node.js and Bun, through napi-rs.",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "bui": "cli.js"
+  },
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -16,7 +19,9 @@
     "index.js",
     "signals.js",
     "index.d.ts",
+    "cli.js",
     "blenderui.*.node",
+    "bui-runtime.*",
     "README.md",
     "LICENSE"
   ],