@blender-ui/react 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# @blender-ui/react
 
-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/react)](https://www.npmjs.com/package/@blender-ui/react)
+[![license](https://img.shields.io/npm/l/@blender-ui/react)](https://github.com/ppmpreetham/BUI/blob/main/LICENSE)
+
+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 Tailwind
+classes, and BUI renders it in native windows on the CPU or the GPU. There's
+no browser, no webview and no Electron.
+
+- **React's hooks, by React's names, holding signals.** A change updates the
+  one node that shows it, without re-rendering the component.
+- **Node.js and Bun.**
+- **One small executable:** `bui build` makes an app of about 5 MB that
+  reaches its first frame in about 70 ms.
+
+```sh
+npm install @blender-ui/react react        # or: bun add @blender-ui/react react
+```
+
+```jsx
+/** @jsxImportSource @blender-ui/react */
+import { render, useState } from '@blender-ui/react'
+
+function Counter () {
+  const [count, setCount] = useState(0)
+  return (
+    <main className="p-6 flex flex-col gap-3 bg-[#2b2b2b] text-[#e6e6e6]">
+      <span>Clicks: {count}</span>
+      <button onClick={() => setCount(c => c + 1)}>Add one</button>
+    </main>
+  )
+}
+
+render(<Counter />, { title: 'Counter', width: 360, height: 200, gpu: true })
+```
+
+```sh
+bun app.jsx                 # run it (Bun reads JSX as is)
+npx bui build app.jsx       # ship it: app.exe, one ~5 MB file
+```
+
+Put `"jsxImportSource": "@blender-ui/react"` in your `tsconfig.json`, or in
+your bundler's JSX options; the `/** @jsxImportSource */` comment works per
+file. Without JSX, use this package's `createElement`.
+
+## Hooks
+
+The hooks have React's names, arguments and timing, but the state they hold
+is a **signal**:
+
+- **Passed into JSX** (`<span>{count}</span>`, `style={styleMemo}`,
+  `style={{ color: colorSignal }}`): a change updates that node. The
+  component doesn't re-render.
+- **Read while rendering** (`count.value`; in plain JavaScript also
+  `count + 1` or `count > 5`): the component re-renders when it changes, as
+  with React.
+- **Conditions and `===` need `.value`.** A signal is an object, so it's
+  always truthy: write `{isPending.value && <Spinner />}` and
+  `count.value === 0`. TypeScript also needs `.value` for arithmetic.
+
+| Hook | Returns |
+|---|---|
+| `useState(init)` | `[signal, setState]` |
+| `useReducer(reducer, arg, init?)` | `[signal, dispatch]` |
+| `useMemo(fn, deps?)` | a memo, recomputed when the signals it reads change |
+| `useRef(v)` | `{ current }`, observable by effects and memos |
+| `useCallback(fn, deps?)` / `useEffectEvent(fn)` | a function whose calls are batched |
+| `useEffect` / `useLayoutEffect` / `useInsertionEffect` | React's timing and deps, plus a re-run when the signals the effect read change |
+| `useSyncExternalStore(subscribe, get)` | a signal following the store |
+| `useTransition()` | `[isPending, startTransition]`; signal updates run after urgent ones |
+| `useDeferredValue(value, initial?)` | a signal that follows `value` at low priority |
+| `useActionState(action, initial)` | `[state, dispatch, isPending]` |
+| `useOptimistic(state, reducer?)` | `[optimistic, addOptimistic]` |
+| `use`, `useContext`, `useId`, `useDebugValue`, `useImperativeHandle` | React's own |
+
+Also exported:
+
+- **Rust-style names:** `useSignal(v)` and `useComputed(fn)`.
+- **`useSignalValue(sig)`:** re-renders its component when `sig` changes.
+- **Plain signals:** `signal`, `computed`, `effect`, `batch`, `untrack`,
+  `startTransition`.
+
+React's plain-value hooks still work: import them from `react`.
+
+Every hook is built from React's public hooks. A conformance suite runs each
+one beside React's original, in development and production builds and under
+StrictMode. It fails when a React release adds a hook this package doesn't
+cover yet.
+
+## The renderer
+
+- **Host components are HTML elements.** `className` takes Tailwind classes,
+  `style` takes strings, objects or signals, and the mouse, keyboard and form
+  events work (`onClick`, `onChange` ...). Events bubble, and
+  `stopPropagation` works.
+- **One native batch per commit:** only what changed crosses to BUI's UI
+  thread.
+- **React 19.3:** `<Suspense>`, `<Activity>`, transitions, actions and
+  `<ViewTransition>`, which commits without animating.
+- **API:** `render(element, options)` opens a window. `createRoot(window)`
+  renders into one you opened with
+  [`@blender-ui/native`](https://www.npmjs.com/package/@blender-ui/native),
+  and `act(fn)` is for tests.
+  - Window options: `title`, `width`, `height`, `resizable`, `gpu`,
+    `slug`, `headless`, and `theme` (`'dark'`, the default, or `'light'`:
+    Blender's Light theme; `BUI_THEME` applies otherwise).
+
+## Standalone apps
+
+`bui` comes with this package, through `@blender-ui/native`:
+
+```sh
+npx bui build app.jsx              # app.exe: BUI + embedded QuickJS, ~5 MB
+npx bui build app.jsx --bun        # app.exe: Bun, with Node's APIs and a JIT, ~115 MB
+npx bui run app.jsx                # run on the QuickJS runtime, no build
+```
+
+Options:
+
+- `-o <file>`: the output file.
+- `--console`: keep a console window for logs.
+- `--dev`: React's development build.
+
+Bundling uses [Bun](https://bun.sh), so it must be installed.
+
+The default build runs your app on QuickJS, a small JavaScript engine embedded
+in BUI. It has no Node modules (`fs` and the like) and no JIT, so keep large
+lists updating through signals, or use `--bun`.
+
+## Benchmarks
+
+Ryzen 7 5800U laptop, Windows 11, GPU renderer, React's production build,
+measured before the latest features landed.
+The full method is in the [guide](https://github.com/ppmpreetham/BUI/blob/main/docs/javascript.md#performance).
+
+**Startup:** a small React app that quits at its first frame; medians of 12
+launches.
+
+| | 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 | |
+
+**Animation:** 3,000 cells, one changing per frame.
+
+- **With signals:** the changing values are signals, so the grid renders once.
+- **With state:** the grid re-renders every frame.
+
+| 3,000 cells | FPS | CPU per frame | RAM |
+|---|---:|---:|---:|
+| Bun: with signals / with state | 58.4 / 55.8 | 13.3 / 20.8 ms | 85 / 118 MB |
+| Node: with signals / with state | 56.7 / 54.8 | 14.0 / 18.9 ms | 93 / 121 MB |
+| QuickJS: with signals / with state | 58.7 / 19.7 | 14.9 / 51.0 ms | 61 / 67 MB |
+| *Rust, for reference* | 59.6 | 12.0 ms | 43 MB |
+
+## Requirements
+
+- **Windows x64** prebuilt. On **Linux**, build the `@blender-ui/native`
+  addon from source (`npm run build` in `bindings/node`) and windows are
+  native X11 windows. On **macOS** it's headless for now. `headless: true`
+  renders off-screen anywhere.
+- **Node.js 18** or newer, or Bun.
+- **React 19.3.**
+
+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-later

package/hooks.js

@@ -0,0 +1,397 @@
+// React's hooks, by React's names, with signals for state.
+//
+// `useState`, `useReducer`, `useMemo` ... take React's arguments, run at
+// React's moments and return React's shapes, but the state they hold is a
+// signal. Pass it as a prop or child (`<span>{count}</span>`) and a change
+// updates that one node: the component doesn't re-render. Read it while
+// rendering (`count.value`, `count + 1`, a condition) and the component
+// re-renders when it changes, exactly as with React's own hooks.
+//
+// The second part needs to know which component is rendering: components
+// created through this package's JSX runtime (`jsxImportSource:
+// "@blender-ui/react"`) or `createElement` are wrapped with `track()`.
+//
+// Built only on React's public hooks (useState, useReducer, useRef, useMemo,
+// the effect hooks, startTransition), so React's semantics (StrictMode,
+// concurrent rendering) come from React itself. test/hooks.test.js runs each
+// hook beside React's original and fails when React adds a hook that has
+// neither a signal version here nor an entry in NO_TWIN.
+//
+// SPDX-License-Identifier: GPL-2.0-or-later
+'use strict'
+
+const React = require('react')
+const S = require('@blender-ui/native')
+const { signal, memo, effect, batch, untrack, isSignal, Tracker, Ref } = S
+
+/** React hooks re-exported unchanged, and why (the coverage test reads this). */
+const NO_TWIN = {
+  use: 'suspends rendering: inherently a render-time read',
+  useContext: 'pass a signal as the context value: consumers bind to it without re-rendering',
+  useDebugValue: 'no state',
+  useId: 'no state',
+  useImperativeHandle: 'no state (works with useRef)',
+}
+
+// The latest value, for callbacks that outlive the render that made them.
+function useLatest (value) {
+  const ref = React.useRef(value)
+  ref.current = value
+  return ref
+}
+
+/** A component-owned value, created once. */
+function useOnce (create) {
+  return React.useState(create)[0]
+}
+
+// ---- render tracking -----------------------------------------------------------
+
+const bump = (n) => n + 1
+
+/** Re-render this component when a signal its render read changes. */
+function useRenderTracker () {
+  const [, force] = React.useReducer(bump, 0)
+  const tracker = useOnce(() => new Tracker(() => force()))
+  const reads = React.useRef(null)
+  // after each commit: follow what that render read
+  React.useLayoutEffect(() => { tracker.commit(reads.current) })
+  // mount / unmount (StrictMode re-mounts: pause, then resume)
+  React.useLayoutEffect(() => {
+    tracker.resume()
+    return () => tracker.pause()
+  }, [tracker])
+  return { tracker, reads }
+}
+
+const tracked = new WeakMap()
+const MEMO = Symbol.for('react.memo')
+const FORWARD_REF = Symbol.for('react.forward_ref')
+
+/** `type` with render tracking: function components, `memo` and `forwardRef`. */
+function track (type) {
+  if (type == null) return type
+  if (typeof type === 'function') {
+    if (type.prototype?.isReactComponent) return type // class components: no hooks
+  } else if (typeof type !== 'object' || (type.$$typeof !== MEMO && type.$$typeof !== FORWARD_REF)) {
+    return type // host components, fragments, providers, lazy ...
+  }
+  let t = tracked.get(type)
+  if (t !== undefined) return t
+  if (typeof type === 'function') {
+    t = function (props, secondArg) {
+      const { tracker, reads } = useRenderTracker()
+      const [result, r] = tracker.run(() => type(props, secondArg))
+      reads.current = r
+      return result
+    }
+    Object.defineProperty(t, 'name', { value: type.name })
+    t.displayName = type.displayName || type.name
+  } else if (type.$$typeof === MEMO) {
+    t = React.memo(track(type.type), type.compare)
+    t.displayName = type.displayName
+  } else {
+    t = React.forwardRef(track(type.render))
+    t.displayName = type.displayName
+  }
+  tracked.set(type, t)
+  tracked.set(t, t)
+  return t
+}
+
+/** React's `createElement`, with render tracking for components. */
+function createElement (type, props, ...children) {
+  return React.createElement(track(type), props, ...children)
+}
+
+// ---- state -----------------------------------------------------------------
+
+/** Rust's `use_signal`: a signal owned by this component. */
+function useSignal (initial) {
+  return useOnce(() => signal(typeof initial === 'function' ? initial() : initial))
+}
+
+/** `[signal, setState]`; `setState(v | prev => next)`; the same value: no update. */
+function useState (initialState) {
+  const s = useSignal(initialState)
+  const set = React.useCallback((v) => s.set(typeof v === 'function' ? v(s.peek()) : v), [s])
+  return [s, set]
+}
+
+/** `[signal, dispatch]`, with the latest render's reducer (as React does). */
+function useReducer (reducer, initialArg, init) {
+  const s = useOnce(() => signal(init !== undefined ? init(initialArg) : initialArg))
+  const latest = useLatest(reducer)
+  const dispatch = React.useCallback((action) => s.set(latest.current(s.peek(), action)), [s])
+  return [s, dispatch]
+}
+
+/** `{ current }`, observable by effects and memos (an element mounting re-runs
+ *  them); reading it while rendering doesn't subscribe, as with React's refs. */
+function useRef (initialValue) {
+  return useOnce(() => new Ref(initialValue))
+}
+
+// ---- derived values ----------------------------------------------------------
+
+/** A memo: recomputed when the signals it reads change, and replaced (like
+ *  useMemo's value) when `deps` change; without deps, every render. */
+function useMemo (fn, deps) {
+  const latest = useLatest(fn)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useMemo(() => memo(() => latest.current()), deps)
+}
+
+/** Rust's `Memo::new`: `useMemo` with `deps = []` by default. */
+function useComputed (fn, deps = []) {
+  return useMemo(fn, deps)
+}
+
+/** React's `useCallback`; calls are batched (their writes make one update) and
+ *  untracked (calling it in an effect doesn't subscribe to what it reads). */
+function useCallback (fn, deps) {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useCallback((...args) => batch(() => untrack(() => fn(...args))), deps)
+}
+
+/** React's `useEffectEvent`: a stable function that calls the latest render's
+ *  `fn`; calls are batched and untracked (an effect calling it doesn't
+ *  subscribe to the signals `fn` reads). */
+function useEffectEvent (fn) {
+  const latest = useLatest(fn)
+  return React.useCallback((...args) => batch(() => untrack(() => latest.current(...args))), [latest])
+}
+
+// ---- effects -----------------------------------------------------------------
+
+function effectHook (reactHook) {
+  return function (fn, deps) {
+    const latest = useLatest(fn)
+    // React's timing and deps; in between, re-runs when the signals it read change
+    reactHook(() => effect(() => latest.current()), deps)
+  }
+}
+
+/** React's `useEffect`, also re-run when the signals it read change. */
+const useEffect = effectHook(React.useEffect)
+/** React's `useLayoutEffect`, also re-run when the signals it read change. */
+const useLayoutEffect = effectHook(React.useLayoutEffect)
+/** React's `useInsertionEffect`, also re-run when the signals it read change. */
+const useInsertionEffect = effectHook(React.useInsertionEffect)
+
+// ---- external stores ---------------------------------------------------------
+
+/** A signal following the store. */
+function useSyncExternalStore (subscribe, getSnapshot) {
+  const s = useOnce(() => signal(getSnapshot()))
+  const latest = useLatest(getSnapshot)
+  React.useLayoutEffect(() => {
+    const check = () => s.set(latest.current())
+    check() // changed between render and subscribe
+    return subscribe(check)
+  }, [subscribe, s])
+  React.useLayoutEffect(() => { s.set(latest.current()) }) // a new getSnapshot
+  return s
+}
+
+/** Re-render this component when `source` changes; returns its value (for
+ *  components rendered without this package's JSX runtime). */
+function useSignalValue (source) {
+  const subscribe = React.useCallback((onChange) => {
+    let first = true
+    return effect(() => {
+      source.value // subscribe
+      if (first) first = false
+      else onChange()
+    })
+  }, [source])
+  return React.useSyncExternalStore(subscribe, () => source.peek())
+}
+
+// ---- transitions and actions -------------------------------------------------
+
+// Run `action` as a BUI transition and a React transition at once: signal
+// writes defer their effects, React state updates render at transition priority.
+// React tracks the action's promise (its optimistic updates last until it
+// settles) but never sees its rejection: each hook sends errors where React's does.
+const quiet = () => {}
+function transition (action) {
+  return S.startTransition(() => {
+    let result
+    let failure = null
+    React.startTransition(() => {
+      try {
+        result = action()
+      } catch (error) {
+        failure = { error } // React would report it globally and swallow it
+        return
+      }
+      return result && typeof result.then === 'function' ? result.then(quiet, quiet) : undefined
+    })
+    if (failure !== null) throw failure.error
+    return result
+  })
+}
+
+/** React's `startTransition`, for signal writes too. Returns a promise that
+ *  settles when the action and the updates it caused are done. */
+function startTransition (action) {
+  return transition(action)
+}
+
+/** A setter that rethrows `error` during render: React's way to reach the
+ *  nearest error boundary from an async callback. */
+function useThrowToBoundary () {
+  const [, set] = React.useState(null)
+  return React.useCallback((error) => set(() => { throw error }), [])
+}
+
+/** `[isPending signal, startTransition(action)]`. `action` may be async;
+ *  isPending stays true until it settles and its deferred updates have run.
+ *  An error goes to the nearest error boundary. */
+function useTransition () {
+  const isPending = useOnce(() => signal(false))
+  const fail = useThrowToBoundary()
+  const start = React.useCallback((action) => {
+    isPending._count = (isPending._count ?? 0) + 1
+    S.urgent(() => isPending.set(true))
+    const settle = () => {
+      if (--isPending._count === 0) S.urgent(() => isPending.set(false))
+    }
+    let done
+    try {
+      done = transition(action)
+    } catch (error) {
+      settle()
+      return fail(error)
+    }
+    done.then(settle, (error) => { settle(); fail(error) })
+  }, [isPending, fail])
+  return [isPending, start]
+}
+
+/** A signal following `value` (a signal or a value) at transition priority,
+ *  after urgent updates; `initialValue` first, if given. */
+function useDeferredValue (value, initialValue) {
+  const read = () => (isSignal(value) ? value.peek() : value)
+  const out = useOnce(() => signal(initialValue !== undefined ? initialValue : read()))
+  const latest = useLatest(value)
+  React.useEffect(() => {
+    let scheduled = false
+    let live = true
+    const push = () => {
+      if (scheduled) return
+      scheduled = true
+      S.scheduleDeferred(() => {
+        scheduled = false
+        if (!live) return
+        const v = latest.current
+        out.set(isSignal(v) ? v.peek() : v)
+      })
+    }
+    if (isSignal(value)) {
+      const stop = effect(() => { value.value; push() })
+      return () => { live = false; stop() }
+    }
+    push()
+    return () => { live = false }
+  }, [value, out])
+  return out
+}
+
+/** `[state signal, dispatch, isPending signal]`. Dispatches queue and run in
+ *  order, each with the previous state; an action may be async. A thrown
+ *  error goes to the nearest error boundary and drops the queue, as in React. */
+function useActionState (action, initialState) {
+  const state = useOnce(() => signal(initialState))
+  const isPending = useOnce(() => signal(false))
+  const latest = useLatest(action)
+  const queue = useOnce(() => ({ items: [], running: false }))
+  const fail = useThrowToBoundary()
+
+  const runNext = React.useCallback(() => {
+    const payload = queue.items.shift()
+    queue.running = true
+    let result
+    try {
+      transition(() => {
+        result = latest.current(state.peek(), payload)
+        return result
+      }).catch(quiet) // the error is handled below, from `result`
+    } catch (error) {
+      result = Promise.reject(error)
+    }
+    Promise.resolve(result).then((next) => {
+      const more = queue.items.length > 0
+      batch(() => {
+        state.set(next)
+        if (!more) isPending.set(false)
+      })
+      if (more) runNext()
+      else queue.running = false
+    }, (err) => {
+      queue.items.length = 0
+      queue.running = false
+      isPending.set(false)
+      fail(err)
+    })
+  }, [state, isPending, queue, fail])
+
+  const dispatch = React.useCallback((payload) => {
+    queue.items.push(payload)
+    if (!queue.running) {
+      S.urgent(() => isPending.set(true))
+      runNext()
+    }
+  }, [queue, isPending, runNext])
+
+  return [state, dispatch, isPending]
+}
+
+/** `[optimistic signal, addOptimistic]`. Updates added during a transition or
+ *  action show at once and are dropped when it ends; `passthrough` (a signal
+ *  or a value) shows through otherwise. */
+function useOptimistic (passthrough, reducer) {
+  const updates = useOnce(() => signal([]))
+  const latestReducer = useLatest(reducer)
+  const out = React.useMemo(() => memo(() => {
+    let v = isSignal(passthrough) ? passthrough.value : passthrough
+    for (const u of updates.value) v = latestReducer.current ? latestReducer.current(v, u.action) : u.action
+    return v
+  }), [passthrough, updates])
+  const add = React.useCallback((action) => {
+    const entry = { action }
+    const remove = () => S.urgent(() => updates.set(updates.peek().filter((e) => e !== entry)))
+    S.urgent(() => updates.set([...updates.peek(), entry]))
+    if (!S.onTransitionDone(remove)) {
+      console.error('An optimistic state update occurred outside a transition or action. ' +
+        'To fix, move the update to an action, or wrap it in startTransition.')
+      setTimeout(remove, 0)
+    }
+  }, [updates])
+  return [out, add]
+}
+
+module.exports = {
+  NO_TWIN,
+  track,
+  createElement,
+  startTransition,
+  useSignal,
+  useComputed,
+  useSignalValue,
+  useState,
+  useReducer,
+  useRef,
+  useMemo,
+  useCallback,
+  useEffectEvent,
+  useEffect,
+  useLayoutEffect,
+  useInsertionEffect,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  useActionState,
+  useOptimistic,
+}

package/index.d.ts

@@ -0,0 +1,110 @@
+// Types for @blender-ui/react.
+import type { ReactNode, ReactElement, DependencyList, EffectCallback, Dispatch, SetStateAction, ElementType } from 'react'
+import type { App, Window, AppOptions, WindowOptions, Signal, Memo, ReadSignal, Ref } from '@blender-ui/native'
+
+export interface Root {
+  render (element: ReactNode): void
+  unmount (): void
+}
+
+/** A React root rendering into `window`'s body (unmounted when the window closes). */
+export function createRoot (window: Window): Root
+
+/** Open a window (and an App, unless `app` is given) and render `element` into it. */
+export function render (element: ReactNode, options?: WindowOptions & AppOptions & { app?: App }):
+  { app: App, window: Window, root: Root }
+
+/** Run `fn` and flush React's work synchronously (tests). */
+export function act<R> (fn: () => R): R
+
+/** React's `createElement`, with render tracking for components. */
+export const createElement: typeof import('react').createElement
+/** A component type with render tracking (re-renders when a signal its render read changes). */
+export function track<T extends ElementType> (type: T): T
+
+// React's hooks that hold no state, as React exports them.
+export { use, useContext, useDebugValue, useId, useImperativeHandle } from 'react'
+
+// Signals.
+export { signal, effect, batch, untrack, createSignal, isSignal, Signal, Memo, ReadSignal, Ref } from '@blender-ui/native'
+/** A derived, cached signal (`memo` in @blender-ui/native; here `memo` stays React's). */
+export { memo as computed, ref } from '@blender-ui/native'
+
+/** React hooks re-exported unchanged, and why. */
+export const NO_TWIN: Record<string, string>
+
+// React's hooks by React's names, with signals for state. Same arguments and
+// timing as React's. A signal passed as a prop or child updates that node
+// alone; read while rendering (`.value`, `count + 1`), it re-renders the
+// component when it changes. Conditions and `===` need `.value`: a signal
+// object is always truthy.
+
+/** `[signal, setState]`: `setState(v)` or `setState(prev => next)`. */
+export function useState<T> (initialState: T | (() => T)): [Signal<T>, Dispatch<SetStateAction<T>>]
+export function useState<T = undefined> (): [Signal<T | undefined>, Dispatch<SetStateAction<T | undefined>>]
+/** `[signal, dispatch]`, with the latest render's reducer. */
+export function useReducer<S, A> (reducer: (state: S, action: A) => S, initialArg: S): [Signal<S>, Dispatch<A>]
+export function useReducer<S, A, I> (reducer: (state: S, action: A) => S, initialArg: I, init: (arg: I) => S): [Signal<S>, Dispatch<A>]
+/** `{ current }`, observable by effects and memos; reading it while rendering doesn't subscribe. */
+export function useRef<T> (initialValue: T): Ref<T>
+export function useRef<T = undefined> (): Ref<T | undefined>
+/** A memo following its signals, replaced when `deps` change (without deps: every render). */
+export function useMemo<T> (fn: () => T, deps?: DependencyList): Memo<T>
+/** React's `useCallback`; calls are batched and untracked. */
+export function useCallback<F extends (...args: any[]) => any> (fn: F, deps?: DependencyList): F
+/** React's `useEffectEvent`; calls are batched and untracked. */
+export function useEffectEvent<F extends (...args: any[]) => any> (fn: F): F
+/** React's `useEffect`, also re-run when the signals it read change. */
+export function useEffect (effect: EffectCallback, deps?: DependencyList): void
+/** React's `useLayoutEffect`, also re-run when the signals it read change. */
+export function useLayoutEffect (effect: EffectCallback, deps?: DependencyList): void
+/** React's `useInsertionEffect`, also re-run when the signals it read change. */
+export function useInsertionEffect (effect: EffectCallback, deps?: DependencyList): void
+/** A signal following the store. */
+export function useSyncExternalStore<T> (subscribe: (onChange: () => void) => () => void, getSnapshot: () => T,
+  getServerSnapshot?: () => T): Signal<T>
+/** `[isPending, startTransition]`: what the action's writes trigger runs after urgent updates. */
+export function useTransition (): [Signal<boolean>, (action: () => void | Promise<void>) => void]
+/** React's `startTransition`, for signal writes too; settles when the action and its updates are done. */
+export function startTransition (action: () => void | Promise<void>): Promise<void>
+/** A signal following `value` (a signal or a value) at transition priority. */
+export function useDeferredValue<T> (value: T | ReadSignal<T>, initialValue?: T): Signal<T>
+/** `[state, dispatch, isPending]`: actions run in order, each with the previous state. */
+export function useActionState<S, P = void> (action: (state: S, payload: P) => S | Promise<S>, initialState: S,
+  permalink?: string): [Signal<S>, (payload: P) => void, Signal<boolean>]
+/** `[optimistic, addOptimistic]`: updates last until their transition or action ends. */
+export function useOptimistic<S> (passthrough: S | ReadSignal<S>): [Memo<S>, (value: S) => void]
+export function useOptimistic<S, A> (passthrough: S | ReadSignal<S>, reducer: (state: S, action: A) => S):
+  [Memo<S>, (action: A) => void]
+
+/** Rust's `use_signal`: a signal owned by this component. */
+export function useSignal<T> (initial: T | (() => T)): Signal<T>
+/** Rust's `Memo::new`: `useMemo(fn, deps = [])`. */
+export function useComputed<T> (fn: () => T, deps?: DependencyList): Memo<T>
+/** Re-render this component when `source` changes; returns its value (components
+ *  rendered without this package's JSX runtime or createElement). */
+export function useSignalValue<T> (source: ReadSignal<T>): T
+
+export type { ReactElement }
+
+// A signal is a valid child: `<span>Clicks: {count}</span>`.
+declare module 'react' {
+  interface DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES {
+    buiSignal: ReadSignal<unknown>
+  }
+}
+
+/** Blender's widgets as components: always drawn and handled like Blender.
+ *  Their lowercase HTML counterparts look like a browser's form controls
+ *  (and like Blender inside an element with the `styled` attribute). */
+type BlenderProps = Record<string, unknown> & { children?: ReactNode }
+export function Button (props: BlenderProps): ReactNode
+export function Checkbox (props: BlenderProps): ReactNode
+export function Radio (props: BlenderProps): ReactNode
+export function NumberField (props: BlenderProps): ReactNode
+export function NumberSlider (props: BlenderProps): ReactNode
+export function TextField (props: BlenderProps): ReactNode
+export function TextArea (props: BlenderProps): ReactNode
+export function ColorSwatch (props: BlenderProps): ReactNode
+export function Dropdown (props: BlenderProps): ReactNode
+export function ProgressBar (props: BlenderProps): ReactNode