@blender-ui/native 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @blender-ui/native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![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        # or: bun add @blender-ui/native
+```
+
+```js
+const { App, signal } = require('@blender-ui/native')
+
+const app = new App({ gpu: true })
+const win = app.window({ title: 'Hello', width: 360, height: 200 })
+win.body.className = 'm-0 p-6 flex flex-col gap-3 bg-[#2b2b2b] text-[#e6e6e6]'
+
+const clicks = signal(0)
+const label = win.createElement('span')
+label.textContent = clicks            // follows the signal
+const button = win.createElement('button')
+button.textContent = 'Add one'
+button.addEventListener('click', () => clicks.value++)
+win.body.appendChild(label)
+win.body.appendChild(button)
+```
+
+## API
+
+- **A DOM-like tree:** `createElement`, `createTextNode`, `appendChild`,
+  `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.
+- **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` (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 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.** Elsewhere, build from a clone of the
+  [repository](https://github.com/ppmpreetham/BUI) with `npm run build` in
+  `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: [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.d.ts

@@ -0,0 +1,187 @@
+// Types for @blender-ui/native.
+export interface AppOptions {
+  /** Draw on the GPU (Direct3D 11). */
+  gpu?: boolean
+  /** GPU text from glyph outlines (Slug, default) or a per-glyph atlas. */
+  slug?: boolean
+  /** No native windows: tests, screenshots, CI. */
+  headless?: boolean
+  /** Quit when the last window closes (default true). */
+  quitOnLastWindowClosed?: boolean
+}
+
+export interface WindowOptions {
+  title?: string
+  width?: number
+  height?: number
+  resizable?: boolean
+  gpu?: boolean
+}
+
+export type EventType = 'click' | 'mousedown' | 'mouseup' | 'mousemove' | 'mouseenter' | 'mouseleave' |
+  'wheel' | 'keydown' | 'keyup' | 'change' | 'input'
+
+export class BuiEvent {
+  type: EventType
+  target: Element
+  currentTarget: Element
+  clientX: number
+  clientY: number
+  x: number
+  y: number
+  button: number
+  detail: number
+  deltaY: number
+  key?: string
+  char?: string
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
+  timeStamp: number
+  preventDefault (): void
+  stopPropagation (): void
+}
+
+export class Node {
+  readonly ownerWindow: Window
+  readonly id: number
+  parentNode: Element | null
+  childNodes: Node[]
+  readonly firstChild: Node | null
+  readonly lastChild: Node | null
+  readonly nextSibling: Node | null
+  textContent: string
+  appendChild<T extends Node> (child: T): T
+  insertBefore<T extends Node> (child: T, before: Node | null): T
+  removeChild<T extends Node> (child: T): T
+  remove (): void
+  /** Free the node and its subtree natively (after removing it). */
+  destroy (): void
+}
+
+export class TextNode extends Node {
+  /** A string, or a signal (the text then follows it). */
+  data: string | ReadSignal<unknown>
+  nodeValue: string
+}
+
+export class Element extends Node {
+  readonly tagName: string
+  readonly localName: string
+  className: string
+  /** CSS text, or an object such as `{ backgroundColor: 'red', width: 40 }`. */
+  style: string | Record<string, string | number | null | undefined> | ReadSignal<string | Record<string, string | number | null | undefined>>
+  /** Form controls: the latest value from input / change events. */
+  value?: string
+  checked?: boolean
+  /** A value, or a signal: the attribute then follows it (null / false removes it). */
+  setAttribute (name: string, value: unknown): void
+  getAttribute (name: string): string | null
+  hasAttribute (name: string): boolean
+  removeAttribute (name: string): void
+  addEventListener (type: EventType, listener: (event: BuiEvent) => void): void
+  removeEventListener (type: EventType, listener: (event: BuiEvent) => void): void
+  getBoundingClientRect (): Promise<{ x: number, y: number, width: number, height: number } | null>
+}
+
+export class Window {
+  readonly app: App
+  readonly id: number
+  readonly body: Element
+  closed: boolean
+  createElement (tag: string): Element
+  createTextNode (text: string | ReadSignal<unknown>): TextNode
+  /** Send pending changes now (they are otherwise sent once per tick). */
+  flush (): void
+  /** Run `cb` before the next frame, paced by the display. */
+  requestAnimationFrame (cb: (time: number) => void): number
+  cancelAnimationFrame (id: number): void
+  screenshot (): Promise<{ width: number, height: number, data: Buffer }>
+  click (x: number, y: number): void
+  close (): void
+  on (event: 'close', listener: () => void): this
+}
+
+export class App {
+  constructor (options?: AppOptions)
+  readonly headless: boolean
+  readonly windows: Map<number, Window>
+  quitOnLastWindowClosed: boolean
+  window (options?: WindowOptions): Window
+  setSlug (on: boolean): void
+  quit (): void
+}
+
+export function styleText (style: Record<string, string | number | null | undefined>): string
+
+// Signals: BUI's hooks (the Rust crate's Signal / Memo / Effect).
+// Bind one to an attribute, `style` or text and that node alone updates.
+
+export interface ReadSignal<T> {
+  /** Read, subscribing the running memo / effect. */
+  readonly value: T
+  get (): T
+  /** Read without subscribing. */
+  peek (): T
+  with<R> (fn: (value: T) => R): R
+  /** Call `fn` now and on every change; returns the unsubscribe function. */
+  subscribe (fn: (value: T) => void): () => void
+  /** `count + 1`, `count > 5` read the value (`===` and truthiness don't: use `.value`). */
+  valueOf (): T
+}
+
+export class Signal<T> implements ReadSignal<T> {
+  constructor (value: T, options?: { equals?: (a: T, b: T) => boolean })
+  value: T
+  get (): T
+  peek (): T
+  set (value: T): void
+  update (fn: (value: T) => T): void
+  with<R> (fn: (value: T) => R): R
+  subscribe (fn: (value: T) => void): () => void
+  valueOf (): T
+}
+
+export class Memo<T> implements ReadSignal<T> {
+  readonly value: T
+  get (): T
+  peek (): T
+  with<R> (fn: (value: T) => R): R
+  subscribe (fn: (value: T) => void): () => void
+  valueOf (): T
+}
+
+export function signal<T> (value: T, options?: { equals?: (a: T, b: T) => boolean }): Signal<T>
+/** A lazily derived, cached value, recomputed when the signals it read change. */
+export function memo<T> (fn: () => T, options?: { equals?: (a: T, b: T) => boolean }): Memo<T>
+export const computed: typeof memo
+/** Runs `fn` now and when what it read changes; `fn` may return a cleanup. Returns `dispose`. */
+export function effect (fn: () => void | (() => void)): () => void
+/** Several writes, one update. */
+export function batch<R> (fn: () => R): R
+export function untrack<R> (fn: () => R): R
+/** Leptos / Solid style getter and setter. */
+export function createSignal<T> (value: T): [() => T, (value: T | ((prev: T) => T)) => void]
+export function isSignal (x: unknown): x is ReadSignal<unknown>
+/** Writes in `fn` update what they affect after urgent work, in slices. Settles
+ *  when done; rejects with the error of an async `fn`. */
+export function startTransition (fn: () => void | Promise<void>): Promise<void>
+/** Run `fn` at urgent priority, even inside a transition. */
+export function urgent<R> (fn: () => R): R
+
+/** A ref whose `.current` effects and memos can follow (reading it while a
+ *  React component renders doesn't subscribe). */
+export class Ref<T> extends Signal<T> { current: T }
+export function ref<T> (value: T): Ref<T>
+/** Run `fn` outside any owning effect: effects it creates live until disposed. */
+export function unowned<R> (fn: () => R): R
+
+/** The addon (internal), plus counters for benchmarks. */
+export const native: {
+  /** CPU cycles of every thread of this process (Windows), or null. */
+  processCpuCycles (): number | null
+  /** The x86-64 time-stamp counter, or null. */
+  timestampCounter (): number | null
+  [key: string]: unknown
+}