react-x11 2.52.0 → 2.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.52.0",
+  "version": "2.54.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {
@@ -72,6 +72,7 @@
     "labs:direct-gl": "tsx examples/labs/direct-gl.jsx",
     "labs:gl-overlay": "tsx examples/labs/gl-overlay.jsx",
     "examples:viewer3d": "tsx examples/viewer3d.jsx",
+    "examples:video": "tsx examples/video.jsx",
     "examples:transparent": "tsx examples/transparent.jsx",
     "examples:windows": "tsx examples/windows.jsx",
     "examples:wm": "tsx examples/wm.jsx",
@@ -110,7 +111,7 @@
     "ical.js": "^2.2.1",
     "image-in-browser": "^3.6.0",
     "linebreak": "^1.1.0",
-    "ntk": "^8.23.2",
+    "ntk": "^8.24.0",
     "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },

package/src/Reconciler.js

@@ -678,7 +678,7 @@ const isNtkApp = (v) =>
  *
  * `'auto'` — the default — is one rule: macOS gets the native Core
  * Animation backend, everything else gets X11 via `$DISPLAY`. (More rungs —
- * Wayland — join this ladder, not a new one; docs/wayland.md.) On a mac
+ * Wayland — join this ladder, not a new one; design/wayland.md.) On a mac
  * without the `@windowkit/appkit` bridge installed, auto falls back to X11 so
  * an XQuartz setup keeps working; asking for `'cocoa'` by name means the
  * bridge is required, and its absence is an error that says how to fix it.
@@ -809,7 +809,7 @@ export async function createRoot(options = {}) {
   // The cocoa backend's desktop is not freedesktop's: the AT-SPI bridge and
   // the D-Bus global menu have nothing to register against there, so they
   // default off (their macOS replacements are their own workstream —
-  // docs/macos.md). The appearance ladder stays on: its macOS rung is the
+  // design/macos.md). The appearance ladder stays on: its macOS rung is the
   // one that answers. An explicit `desktop` option still wins.
   setDesktopIntegration(
     rest.desktop ??

package/src/a11y.js

@@ -1289,7 +1289,7 @@ export function startA11y(app) {
   // presence *is* the capability — the same rule the rest of the library
   // uses. The Windows backend installs one, because UI Automation asks
   // synchronously and has to be answered from a pushed copy rather than from
-  // the live tree (docs/windows.md §Accessibility); AT-SPI's asynchronous
+  // the live tree (design/windows.md §Accessibility); AT-SPI's asynchronous
   // questions are answered from the tree itself, below.
   if (typeof app?.startAccessibility === 'function') {
     startPromise = Promise.resolve()

package/src/backend/context2d.js

@@ -1,7 +1,7 @@
 // A canvas-shaped 2d context over a **verb table** — the drawing dialect
 // every native backend answers, and the one place it is written down.
 //
-// This is macos.md §"The split" step 4, taken when a second native backend
+// This is design/macos.md §"The split" step 4, taken when a second native backend
 // started: the class takes its `native` as a constructor argument and calls
 // nothing else, so one wrapper drives @windowkit/appkit's CoreGraphics verbs
 // and @windowkit/win32's Direct2D verbs alike. A bridge that lacks an
@@ -16,7 +16,7 @@
 //
 // On the surface presenter this is the whole drawing path; on the layer
 // presenter it stays as the fallback every painted-code node (<canvas>,
-// <svg>, registered elements) rasters through — docs/macos.md §"Custom
+// <svg>, registered elements) rasters through — design/macos.md §"Custom
 // drawing on a layer tree".
 //
 // The native surface holds the real graphics state (paths, CTM, clip); this
@@ -322,7 +322,7 @@ const NON_RECT = Symbol('non-rectangular clip');
  * linear in it: 14ms, 29ms, 56ms, 113ms. The driver is the subpath count,
  * not the vertex count — one 26,000-vertex subpath strokes in 4ms where
  * two thousand 13-vertex ones take 208. The full table, the two shapes
- * left whole and why, are in docs/macos.md
+ * left whole and why, are in design/macos.md
  * §"Stroking a path with many subpaths".
  *
  * Note the X11 context wants the opposite — there a stroke is an a8

package/src/bootstrap.js

@@ -4,7 +4,7 @@
 // an app on macOS moves onto a worker (src/cocoa/relaunch.js), and on that
 // worker the same import sets it up. A Windows backend's UI thread will be
 // the addon's own, and X11 has none, so neither needs this step
-// (docs/windows.md §"Three shapes on Windows"). Imported first by
+// (design/windows.md §"Three shapes on Windows"). Imported first by
 // src/index.js, so that it runs before the rest of the package.
 import { isMainThread, workerData } from 'node:worker_threads';
 

package/src/cocoa/app.js

@@ -5,7 +5,7 @@
 // that stands in for the X socket.
 //
 // Two run loops. By default Node's loop is master and a timer pumps AppKit
-// (docs/macos.md §"Input and the run loop", option 1): input waits for the
+// (design/macos.md §"Input and the run loop", option 1): input waits for the
 // pump, and AppKit's modal loops (live resize, menu tracking, a drag) stall
 // JS timers — but not the delegate callbacks, which is why live resize
 // still relayouts: the resize event flushes the frame synchronously on its
@@ -13,7 +13,7 @@
 // Under the launcher (`node --import react-x11/cocoa-main`, src/cocoa/
 // main.js) the app runs on a worker instead, AppKit keeps the main thread
 // in a real `[NSApp run]`, and this object is fed by the bridge's batches
-// (`_routeBatch`) with no pump at all (docs/macos.md §"JS on a worker").
+// (`_routeBatch`) with no pump at all (design/macos.md §"JS on a worker").
 import { isMainThread } from 'node:worker_threads';
 
 import { cssColorStraight } from 'ntk/color';
@@ -64,11 +64,11 @@ const PUMP_INTERVAL_MS = 8;
 // The edge moves when the delegate returns, so the budget is how long a
 // slow frame may hold the drag back. 50 covers what a large tree costs —
 // the Cocoa `resize` cell measures 28ms a tick at 3,662 nodes
-// (docs/macos.md) — with room, where the bridge's own test met every tick
+// (design/macos.md) — with room, where the bridge's own test met every tick
 // in 3.1ms against 3ms of layout. Past three 60Hz frames an edge that waits
 // reads as the drag stuttering, so a tree slower than that lets the edge
 // go first and its frame land after (Flutter's Windows embedder waits up
-// to 100, docs/windows.md §"Resize"). `createRoot({ cocoa: { resizeWait } })`
+// to 100, design/windows.md §"Resize: where the threads meet"). `createRoot({ cocoa: { resizeWait } })`
 // sets it; 0 is no handshake at all.
 const RESIZE_WAIT_MS = 50;
 // What `createRoot({ cocoa: { paneStretch } })` and
@@ -272,7 +272,7 @@ export class CocoaApp {
     }
 
     // 'surface' (the measured default) or 'layers' — the retained CALayer
-    // presenter, opt-in while docs/macos.md's measure-first gate is open.
+    // presenter, opt-in while design/macos.md's measure-first gate is open.
     this._presenterMode =
       options.cocoa?.presenter ??
       process.env.REACT_X11_COCOA_PRESENTER ??
@@ -391,7 +391,7 @@ export class CocoaApp {
 
     // the global-menu exports, newest active: the macOS menu bar is one per
     // app, so the most recent MenuBar owns it (per-focused-window switching
-    // is the follow-up — docs/macos.md §Menus)
+    // is the follow-up — design/macos.md §Menus)
     this._globalMenus = [];
     this._activeGlobalMenu = null;
 

package/src/cocoa/bezels.js

@@ -1,5 +1,5 @@
 // Native control bezels — AppKit's own pixels for the core controls, cached
-// as surfaces the ordinary 2d paint path can blit (docs/macos.md §Native
+// as surfaces the ordinary 2d paint path can blit (design/macos.md §Native
 // controls). The mechanism is offscreen NSCell/NSControl rendering, the
 // WebKit/Gecko form-control technique: interaction, focus and keyboard stay
 // the shared component implementation, and only the *bezel* — the pixels of

package/src/cocoa/fonts.js

@@ -1,6 +1,6 @@
 // The Cocoa text engine: CoreText behind the same `app.fonts` contract ntk's
 // FontManager answers on the X11 backend. The renderer touches exactly this
-// surface (docs/macos.md §"Text: the engine contract"):
+// surface (design/macos.md §"Text: the engine contract"):
 //
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })

package/src/cocoa/globalmenu.js

@@ -1,4 +1,4 @@
-// The macOS menu bar as a global-menu export (docs/macos.md §Menus).
+// The macOS menu bar as a global-menu export (design/macos.md §Menus).
 //
 // The Linux global menu was built for exactly this moment: the item
 // vocabulary is data, and the pure snapshot/IdAllocator machinery in

package/src/cocoa/keymap.js

@@ -23,7 +23,7 @@
 //
 // There is no input method behind this. The bridge's view swallows
 // `keyDown:` without `interpretKeyEvents:` and is no `NSTextInputClient`
-// (docs/macos.md, "IME"), so these fields are all the text there is. Two
+// (design/macos.md, "IME"), so these fields are all the text there is. Two
 // consequences, both handled below:
 //
 // - **A dead key types nothing.** ⌥E on a US layout leaves `chars` empty, and

package/src/cocoa/panewindow.js

@@ -1,4 +1,4 @@
-// The pane process's "window" on the Cocoa backend — docs/frame.md's child
+// The pane process's "window" on the Cocoa backend — design/frame.md's child
 // half, with the X server replaced by shared memory.
 //
 // On X11 a pane renders into a real window of its own and the host embeds

package/src/cocoa/player.js

@@ -1,4 +1,4 @@
-// `<video src>` on macOS (docs/architecture/video.md §3.2, §9): a file or URL
+// `<video src>` on macOS (design/architecture/video.md §3.2, §9): a file or URL
 // played by AVFoundation through @windowkit/appkit's player verbs — the
 // platform's decoder, audio, seeking and HLS — with the picture on the
 // player's own AVPlayerLayer.

package/src/cocoa/presenter.js

@@ -1,4 +1,4 @@
-// The retained layer presenter — Tier L of docs/macos.md: one CALayer per
+// The retained layer presenter — Tier L of design/macos.md: one CALayer per
 // drawn node, React commits landing as property sets inside a single
 // disabled-actions CATransaction per frame, the WindowServer compositing.
 //
@@ -350,7 +350,7 @@ export function stylePaintsPlain(node, style = node.style ?? {}) {
 /**
  * Style property → the key path on a PropBox's own layer, for the
  * animations the presenter takes off the frame clock and hands to the
- * render server (docs/architecture/animation.md §4.2). Only what the layer
+ * render server (design/architecture/animation.md §4.2). Only what the layer
  * expresses as a property of itself qualifies: a colour on `<text>` is a
  * re-raster per frame, a layout property moves the siblings, and both stay
  * on the JS loop. `scaled` values go out in points, as `_syncPropBox`

package/src/cocoa/promotion.js

@@ -36,7 +36,7 @@
 // overlapped, hidden, clipped, faded or non-plain returns to the bitmap in
 // the frame that finds it, the animation handed back to the clock — and a
 // loop the clock runs is offered again once the scene would take it
-// (`wouldTake`), where it is in its cycle. docs/macos.md §"Layer
+// (`wouldTake`), where it is in its cycle. design/macos.md §"Layer
 // promotion" is the account.
 import { now } from '../nodes/animation.js';
 import { BoxNode } from '../nodes/box.js';

package/src/cocoa/relaunch.js

@@ -1,4 +1,4 @@
-// Threaded mode by default (docs/macos.md §"JS on a worker"). On macOS the
+// Threaded mode by default (design/macos.md §"JS on a worker"). On macOS the
 // process main thread is AppKit's — the only thread it lets own a window —
 // and while the app's JS runs there, every menu, drag, live resize and
 // modal panel stops it. So the first import of react-x11 on the main thread

package/src/cocoa/threaded.js

@@ -1,4 +1,4 @@
-// Threaded mode's worker half (docs/macos.md §"JS on a worker: a UI thread
+// Threaded mode's worker half (design/macos.md §"JS on a worker: a UI thread
 // of the bridge's own"): with the launcher (src/cocoa/main.js) holding the
 // process main thread in the bridge's `runMain()`, the app's JS runs on a
 // `worker_threads` Worker, and this module is what that worker needs to

package/src/cocoa/video.js

@@ -1,4 +1,4 @@
-// A video's frames on a layer of their own (docs/architecture/video.md §7):
+// A video's frames on a layer of their own (design/architecture/video.md §7):
 // what the surface presenter's sprites (src/cocoa/sprites.js) do with a part
 // whose `contents` is a `VideoFrames` sink instead of a `paint`.
 //

package/src/cocoa/window.js

@@ -39,7 +39,7 @@ const FENCE_TIMEOUT_MS = 100;
 // (`_takeBack`). Three, a `CAMetalLayer`'s depth, is what an animation
 // mostly needs; an input answered between two of its frames puts two flips
 // inside one refresh, and four kept every write of a clicked 120Hz animation
-// off a held buffer (docs/macos.md, "Measured: the swapchain and the
+// off a held buffer (design/macos.md, "Measured: the swapchain and the
 // WindowServer's hold").
 const MAX_BUFFERS = 4;
 // Past this many rects, what a buffer missed is copied whole: a buffer left
@@ -235,14 +235,14 @@ export class CocoaWindow {
     // change.
     this.damageRectCap = 16;
 
-    // The retained layer presenter (docs/macos.md Tier L), behind
+    // The retained layer presenter (design/macos.md Tier L), behind
     // REACT_X11_COCOA_PRESENTER=layers while the surface path is the
     // measured default. Its hooks exist only in this mode, so the feature
     // detection in src/nodes/ keeps the surface path byte-identical; the
     // scroll blit is shadowed off because a layer frame has no backing
     // bitmap to blit. The last two are the animation seam: a transition or
     // a loop the presenter takes runs in the render server and schedules no
-    // frames here (docs/architecture/animation.md §4).
+    // frames here (design/architecture/animation.md §4).
     if (app._presenterMode === 'layers') {
       this._presenter = new CocoaLayerPresenter(this);
       this.presentFrame = (windowNode) => this._presenter.frame(windowNode);
@@ -659,7 +659,7 @@ export class CocoaWindow {
    * A new size retires the chain, released on the spot (`_releaseBacking`):
    * left to the handles' finalizers, a forty-tick drag of the two-buffer
    * chain this used to be held 800MB until a collection happened to run —
-   * the `rss +80MB` docs/macos.md measured. The layer keeps its own
+   * the `rss +80MB` design/macos.md measured. The layer keeps its own
    * reference to whichever IOSurface it is still showing, so the free is
    * safe while that frame is on glass. A new chain starts with the one
    * buffer its first frame paints: a live-resize tick paints its size once,

package/src/components/Menu.js

@@ -984,7 +984,9 @@ function useMenuAccelerators(
  *
  * The wrapper is focusable and takes focus when the menu opens, because the
  * popup is override-redirect and never gets focus itself — the same trick
- * `Select` uses to keep arrow keys working while its menu is open.
+ * `Select` uses to keep arrow keys working while its menu is open. It is not
+ * a Tab stop: it has no role or name, so Tab landing on it would announce
+ * nothing, and the controls inside are stops of their own.
  */
 export function ContextMenu({
   items = [],
@@ -1087,7 +1089,10 @@ export function ContextMenu({
     'box',
     {
       ref,
-      focusable: true,
+      // focusable by a press and by `focus()` above, but out of the Tab
+      // cycle: a stop here is a nameless "filler" around content whose own
+      // controls are already reachable
+      tabIndex: -1,
       onMouseDown: (ev) => {
         if (ev.button !== 3 && rect) close();
       },

package/src/components/Switch.js

@@ -98,7 +98,7 @@ export function Switch({
   );
 
   // NSSwitch's own pixels, on/off as two cached bezels. The knob slide is
-  // the fidelity this loses for now (docs/macos.md flags the switch as the
+  // the fidelity this loses for now (design/macos.md flags the switch as the
   // one control worth revisiting if that disappoints); the press keeps its
   // answer as the wash, since NSSwitch renders no pressed state offscreen.
   if (nativeControls) {

package/src/components/native.js

@@ -1,4 +1,4 @@
-// The native half of the widget set (docs/macos.md §Native controls).
+// The native half of the widget set (design/macos.md §Native controls).
 //
 // House rule: **default native, seam out.** On a backend that renders the
 // platform's own control bezels — today the Cocoa backend — the core

package/src/dnd.js

@@ -1,7 +1,7 @@
 // XDND drag and drop, the drop-target half: react-x11 windows accept drags
 // from other X11 applications (file managers, editors, browsers).
 //
-// Design: docs/architecture/drag-and-drop.md; protocol: XDND version 5.
+// Design: design/architecture/drag-and-drop.md; protocol: XDND version 5.
 // The advertisement (`XdndAware`) is a 4-byte property written
 // unconditionally on every top-level window at realize time — it creates no
 // X windows, so it is orthogonal to the windowed/windowless split.
@@ -1080,7 +1080,7 @@ export class DropSession {
 // ---------------------------------------------------------------------------
 // The drag source.
 //
-// One drag session, two transports (docs/architecture/drag-and-drop.md §6.3):
+// One drag session, two transports (design/architecture/drag-and-drop.md §6.3):
 // while the pointer is over this process's own windows the drag is local —
 // no wire, live JS payloads, the DropSession above delivering to the same
 // handlers with `e.source === 'internal'`. The moment it leaves them, the

package/src/glnodes.js

@@ -95,7 +95,7 @@ export function glxConfig(app, spec) {
           process.platform === 'win32'
             ? 'react-x11: <glarea> is not built on the win32 backend yet — it ' +
                 'needs ANGLE (EGL and GLES over Direct3D 11), which ' +
-                'docs/windows.md plans as an optional dependency the way ' +
+                'design/windows.md plans as an optional dependency the way ' +
                 'x11-dri is on X11. Everything else on this backend works ' +
                 'without it; for GL content today, use the X11 backend.'
             : 'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',

package/src/grid.js

@@ -1,5 +1,5 @@
 // CSS grid, built in (docs/styling.md "Grid"; the design record is
-// docs/architecture/grid-layout.md). A box with `display: 'grid'` — or
+// design/architecture/grid-layout.md). A box with `display: 'grid'` — or
 // `layout: 'grid'`, the same request under the name every layout goes by —
 // arranges its children by CSS Grid's placement and track sizing algorithms
 // (css-grid-2 §8.5 and §12), inside the pass that lays the window out. It is

package/src/imagedecode-worker.js

@@ -0,0 +1,32 @@
+// The other end of `decodeImageBytes`'s `offThread` (imagedecode.js): the
+// JavaScript rung, run where it holds no frame. A decode's pixels go back
+// handed over, never copied, and its error as the message the caller's
+// rejection carries.
+import { parentPort } from 'node:worker_threads';
+
+import { decodeHere } from './imagedecode.js';
+
+parentPort.on('message', async ({ id, bytes }) => {
+  try {
+    const image = await decodeHere(bytes);
+    let data = image.data;
+    // a view of a larger buffer — a pooled Buffer — is copied out first,
+    // so what is handed over is the pixels and nothing beside them
+    if (
+      !(data.buffer instanceof ArrayBuffer) ||
+      data.byteOffset !== 0 ||
+      data.byteLength !== data.buffer.byteLength
+    ) {
+      data = new Uint8Array(data);
+    }
+    parentPort.postMessage(
+      { id, width: image.width, height: image.height, data: data.buffer },
+      [data.buffer],
+    );
+  } catch (err) {
+    parentPort.postMessage({
+      id,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+});

package/src/imagedecode.js

@@ -13,7 +13,11 @@
 //   2. JavaScript. ntk's PNG and JPEG decoders (pngjs, jpeg-js), which are
 //      synchronous, and WebP through image-in-browser's decoder — imported
 //      the first time a WebP arrives, because evaluating it takes ~140ms
-//      that an app showing no WebP should never pay at startup.
+//      that an app showing no WebP should never pay at startup. A caller
+//      that takes a promise anyway asks for `offThread`, and the same
+//      decoders run on a worker thread (`imagedecode-worker.js`) for bytes
+//      large enough to pay for the trip: a document's images, which held
+//      the JavaScript thread for half of the Guardian's load.
 //
 // Two things here are easy to undo:
 //
@@ -115,17 +119,41 @@ const hex = (bytes) =>
  * elsewhere). Throws — or rejects — on bytes that are not an image this
  * runtime can decode, with what to do about it.
  *
+ * `options.offThread` asks for the decode to run on a worker thread where
+ * the runtime decodes in JavaScript, which it does for bytes long enough
+ * (`OFF_THREAD_BYTES`): a PNG or a JPEG then lands as a promise too. A
+ * caller that waits for a promise anyway — a document's images — asks for
+ * it; `<image>` does not, so a PNG it is handed still shows in the first
+ * frame.
+ *
  * The bytes are read, never written, and under Bun they are read on another
  * thread after this returns: the caller must not change them meanwhile,
  * which `<image>`'s contract (a source is immutable content) already says.
  */
-export function decodeImageBytes(bytes) {
+export function decodeImageBytes(bytes, options) {
   if (bytes.length === 0) {
     throw new Error('react-x11: an empty buffer is not an image.');
   }
   const decoder = runtimeDecoder();
   if (decoder) return decodeWithRuntime(decoder, bytes);
   const format = imageFormat(bytes);
+  if (
+    options?.offThread &&
+    bytes.length >= OFF_THREAD_BYTES &&
+    (format === 'png' || format === 'jpeg' || format === 'webp')
+  ) {
+    const pool = decodePool();
+    if (pool) return pool.decode(bytes, format);
+  }
+  return decodeHere(bytes, format);
+}
+
+/**
+ * The JavaScript rung, on whichever thread runs it: what `decodeImageBytes`
+ * does where the runtime has no decoder of its own, and what its worker
+ * does with the bytes it is handed.
+ */
+export function decodeHere(bytes, format = imageFormat(bytes)) {
   if (format === 'png' || format === 'jpeg') return decodeImage(bytes);
   if (format === 'webp') return decodeWebP(bytes);
   if (format) {
@@ -142,6 +170,116 @@ export function decodeImageBytes(bytes) {
   );
 }
 
+/**
+ * How long encoded bytes are before a decode asked to run off the
+ * JavaScript thread is handed to a worker: under it, the message costs
+ * about what the decode does.
+ */
+const OFF_THREAD_BYTES = 8 * 1024;
+
+/** The most decode workers a process starts. */
+const MAX_WORKERS = 2;
+
+/** The pool `offThread` decodes on: undefined until asked, null where the
+ *  runtime has no worker threads. */
+let pool;
+
+function decodePool() {
+  if (pool !== undefined) return pool;
+  const threads = globalThis.process?.getBuiltinModule?.('node:worker_threads');
+  pool = threads?.Worker ? new DecodePool(threads.Worker) : null;
+  return pool;
+}
+
+/**
+ * Workers that decode with the JavaScript rung (`decodeHere`), started as
+ * decodes arrive, up to `MAX_WORKERS`. A worker holds the process open only
+ * while it has a decode to answer. One that cannot start, or dies, has its
+ * decodes made here, and none starts after it: a bundle that left the
+ * worker's file behind decodes as it always did.
+ */
+class DecodePool {
+  constructor(Worker) {
+    this._Worker = Worker;
+    this._workers = [];
+    this._jobs = new Map();
+    this._next = 1;
+    this._broken = false;
+  }
+
+  decode(bytes, format) {
+    const worker = this._worker();
+    if (!worker) return decodeHere(bytes, format);
+    const id = this._next++;
+    // a copy, handed over: the caller's bytes stay where they are, and a
+    // Buffer's `slice` is a view of them
+    const copy = new Uint8Array(bytes);
+    try {
+      worker.thread.postMessage({ id, bytes: copy }, [copy.buffer]);
+    } catch {
+      return decodeHere(bytes, format);
+    }
+    if (worker.pending++ === 0) worker.thread.ref();
+    return new Promise((resolve, reject) => {
+      this._jobs.set(id, { resolve, reject, worker, bytes, format });
+    });
+  }
+
+  /** The least busy worker, or a new one while every one is busy. */
+  _worker() {
+    if (this._broken) return null;
+    let best = null;
+    for (const w of this._workers) {
+      if (!best || w.pending < best.pending) best = w;
+    }
+    if (best && (best.pending === 0 || this._workers.length >= MAX_WORKERS)) {
+      return best;
+    }
+    let thread;
+    try {
+      thread = new this._Worker(
+        new URL('./imagedecode-worker.js', import.meta.url),
+      );
+    } catch {
+      this._broken = true;
+      return best;
+    }
+    const w = { thread, pending: 0 };
+    thread.unref();
+    thread.on('message', (message) => this._answer(w, message));
+    thread.on('error', () => this._lost(w));
+    thread.on('exit', () => this._lost(w));
+    this._workers.push(w);
+    return w;
+  }
+
+  _answer(w, { id, width, height, data, error }) {
+    const job = this._jobs.get(id);
+    if (!job) return;
+    this._jobs.delete(id);
+    if (--w.pending === 0) w.thread.unref();
+    if (error !== undefined) job.reject(new Error(error));
+    else job.resolve(new Image({ width, height, data: new Uint8Array(data) }));
+  }
+
+  _lost(w) {
+    this._broken = true;
+    this._workers = this._workers.filter((other) => other !== w);
+    for (const [id, job] of this._jobs) {
+      if (job.worker !== w) continue;
+      this._jobs.delete(id);
+      try {
+        Promise.resolve(decodeHere(job.bytes, job.format)).then(
+          job.resolve,
+          job.reject,
+        );
+      } catch (err) {
+        job.reject(err);
+      }
+    }
+  }
+}
+
 /** Read a file path or file URL and decode it. */
 export async function loadImageFile(path) {
   const { readFile } = await import('node:fs/promises');

package/src/layouts.js

@@ -1,5 +1,5 @@
 // Layout algorithms and positions from outside the renderer — the two seams
-// docs/architecture/custom-layout.md is the design record for.
+// design/architecture/custom-layout.md is the design record for.
 //
 // A **layout** arranges a box's children. It is asked how big the box is for
 // the room on offer, and then where each child goes in the room the box got.

package/src/nodes/animation.js

@@ -310,7 +310,7 @@ export class NodeAnimation {
   // loop-stop rule and `sameAnimation` all see it — but it contributes no
   // value to the style, is skipped by the tick, and keeps the node out of the
   // window's animating set. The X11 path has none of these hooks and is
-  // byte-identical (docs/architecture/animation.md §4).
+  // byte-identical (design/architecture/animation.md §4).
 
   _offload(prop, entry) {
     const wnd = this.root?.window;

package/src/nodes/invalidate.js

@@ -361,7 +361,7 @@ export class WindowInvalidate {
     }
     // A retained presenter keeps a per-node diff instead of damage rects,
     // and this is the one channel every change already announces itself on
-    // (docs/macos.md §"One renderer, two presenters"). Feature-detected: an
+    // (design/macos.md §"One renderer, two presenters"). Feature-detected: an
     // ntk window has no ear here and the X11 path is byte-identical. A
     // presenter that answers `true` has taken the claim onto a layer of its
     // own (src/cocoa/promotion.js): the bitmap owes nothing for it, and the

package/src/nodes/layouthost.js

@@ -2,7 +2,7 @@
 // in layouts.js arranges its children itself. Each child is a yoga root of
 // its own, and the host is a measured leaf in its parent — so what the
 // algorithm decides is on screen in the frame that asked.
-// docs/architecture/custom-layout.md is the design record.
+// design/architecture/custom-layout.md is the design record.
 
 import {
   createLayoutNode,