react-x11 2.16.0 → 2.17.0

package/README.md

@@ -18,9 +18,10 @@ Build GUI programs for a Linux desktop, for a display at the other end of an
 ssh connection, or as a native Mac app, with your React / React Native
 experience — flexbox layout, components, hooks, synthetic events.
 
-### Two backends, one tree
+### Four backends, one tree
 
-The same components, the same hooks and the same `style` objects run on both:
+The same components, the same hooks and the same `style` objects run on all
+of them. The two that are mature:
 
 - **X11** ([the flagship](docs/remote.md)) — a Linux desktop, a display
   forwarded over `ssh -X`, `Xvfb` in CI, a thin client, or macOS through
@@ -35,20 +36,25 @@ The same components, the same hooks and the same `style` objects run on both:
   thin mechanism-only Objective-C++ bridge — an optional dependency shipping
   prebuilds, absent on Linux installs.
 
-`createRoot()` picks for you: **Cocoa on macOS** when the bridge is
-installed, X11 via `$DISPLAY` everywhere else, and X11 on a Mac without the
-bridge so an XQuartz setup keeps working. `createRoot({ backend: 'x11' })`
-or `REACT_X11_BACKEND=x11` pins it. On macOS the app's JS runs on a worker
+`createRoot()` picks for you: **Cocoa on macOS** and **win32 on Windows**
+when the matching bridge is installed, X11 via `$DISPLAY` everywhere else —
+and X11 on either of those without its bridge, so an XQuartz or WSLg setup
+keeps working. `createRoot({ backend: 'x11' })` or `REACT_X11_BACKEND=x11`
+pins it. On macOS the app's JS runs on a worker
 while AppKit keeps the main thread, so a menu, a drag or a live resize never
 stops it — `node app.js` is enough, and `REACT_X11_THREADED=0` keeps the
 main thread ([docs/macos.md](docs/macos.md#js-on-a-worker-a-ui-thread-of-the-bridges-own)).
 
-Two more backends are on the way, and the goal they serve is **full
-cross-platform support**: **Windows** — Win32 windows, Direct2D and
-DirectWrite, DWM compositing — with [docs/windows.md](docs/windows.md) as
-its PRD, and **native Wayland**, with [docs/wayland.md](docs/wayland.md)
-as its RFC. Both arrive as backends beside these two, not replacements for
-either: the same tree, the same components, the same `style` objects.
+Two more backends exist beside these, serving the goal of **full
+cross-platform support**, and both are younger than the two above.
+**native Wayland** ([docs/wayland.md](docs/wayland.md)) is opt-in rather than
+automatic, because X11 stays the default on Linux — the remote case is the
+flagship reason this project exists and Wayland has no network transparency.
+**Windows** ([docs/windows.md](docs/windows.md)) — Win32 windows, Direct2D
+and DirectWrite, DWM compositing through DirectComposition — renders and
+takes mouse input, with the desktop integrations still to come. Each is a
+backend beside the others rather than a replacement for any of them: the
+same tree, the same components, the same `style` objects.
 
 Layout is [yoga-layout](https://www.npmjs.com/package/yoga-layout) (WASM) on
 both, and text shaping is [fontkit](https://github.com/foliojs/fontkit) on
@@ -125,17 +131,26 @@ That is the shape of the problem this is good at:
 And the shape it is not good at, so you can stop here rather than in week
 three:
 
-- **Windows — today.** There is no Windows backend yet, so an app that has
-  to ship on Windows now wants Electron or Tauri. One is coming: a native
-  backend over Win32 windows, Direct2D and DirectWrite, composited by DWM
-  through DirectComposition, on a mechanism-only bridge shaped like the
-  Cocoa one. [docs/windows.md](docs/windows.md) is the PRD, from the
-  threading model up to what each desktop integration becomes. Two targets
-  ship meanwhile — X11 and Cocoa — and they are not the same app: the
-  desktop-shell half of X11 (`<foreign>` embedding, panel struts,
-  substructure redirect, the window-manager example below) has no macOS
-  equivalent, and `react-x11/test` drives the X11 backend only.
-  [docs/macos.md](docs/macos.md) says which is which.
+- **Windows — today.** The Windows backend is young, and further along than
+  that sounds. Win32 windows composited by DWM through DirectComposition,
+  Direct2D and DirectWrite behind the same contracts the Cocoa backend
+  proved, OpenGL, the keyboard and all five mouse buttons, popups, the
+  clipboard, file dialogs, the tray, the taskbar, global hotkeys,
+  notifications and window states — on a mechanism-only bridge shaped like
+  the Cocoa one, with a test suite and CI of its own. The examples run.
+  Drag and drop works both ways with the desktop, and the taskbar's own
+  surfaces — a thumbnail toolbar, a jump list, recent documents — are there
+  behind a capability, so an app that also runs elsewhere asks
+  `useSupports()` rather than the platform. What it does not have is **IME
+  and screen-reader support**: an app is unusable with a screen reader and
+  in CJK input. So an app that needs either on Windows _this month_ still
+  wants Electron or Tauri.
+  [docs/windows-integrations.md](docs/windows-integrations.md) is the
+  measured status and [docs/windows.md](docs/windows.md) the design. The three
+  targets are not the same app: the desktop-shell half of X11 (`<foreign>`
+  embedding, panel struts, substructure redirect, the window-manager example
+  below) has no macOS or Windows equivalent, and `react-x11/test` drives the
+  X11 backend only. [docs/macos.md](docs/macos.md) says which is which.
 - **native Wayland — today.** There is no Wayland backend yet. Ordinary
   application windows work fine on a Wayland desktop through Xwayland, which
   is not going away — but the desktop-shell half of X11 (panel struts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -33,6 +33,7 @@
     "examples:attention": "tsx examples/attention.jsx",
     "examples:badge": "tsx examples/badge.jsx",
     "examples:tray": "tsx examples/tray.jsx",
+    "examples:taskbar": "tsx examples/taskbar.jsx",
     "examples:desktop": "tsx examples/desktop.jsx",
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
@@ -109,6 +110,7 @@
   "optionalDependencies": {
     "@windowkit/appkit": "^0.12.0",
     "@windowkit/wayland": "^3.1.1",
+    "@windowkit/win32": "^0.0.1",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.9.0"
   },

package/src/Reconciler.js

@@ -116,6 +116,9 @@ const ROOT_CONTEXT = Object.freeze({
   isInsideText: false,
   isInsideSvg: false,
   atRoot: true,
+  // Nothing is above the root, so a window written straight into it waits for
+  // no palette — unlike one under a `<ThemeProvider>` there.
+  underRootScope: false,
   inWindow: false,
 });
 
@@ -191,6 +194,11 @@ const HostConfig = {
       // Still at the root under a `<ThemeProvider>` written there, which
       // draws nothing; under anything else, inside a window.
       atRoot: parentHostContext.atRoot && type === THEME_SCOPE,
+      // *Below* one of those providers, which is a different fact: a window
+      // here is handed its palette when the scope inserts it, after it was
+      // built. `atRoot` is true at the root itself, where no provider is
+      // waiting to hand anything over, so the two cannot be one flag.
+      underRootScope: parentHostContext.atRoot && type === THEME_SCOPE,
       // Directly inside a window, where a provider can hand a nested window
       // on to it.
       inWindow: type === 'window' || type === 'popup',
@@ -255,10 +263,19 @@ const HostConfig = {
       case 'window':
         // No X11 calls here: the render phase may be discarded. The real
         // window is created top-down in the commit phase (realize).
+        // `underRootScope` goes in at construction, not after it: this
+        // constructor resolves the window's own style, and a window under a
+        // root `<ThemeProvider>` is handed that palette only when the scope
+        // inserts it (nodes/scope.js). Until then its ancestry is incomplete
+        // and every `$token` the provider defines would be reported as
+        // unknown — a warning for a style that resolves correctly a moment
+        // later, and under `REACT_X11_STRICT_TOKENS=1` a throw that killed an
+        // app whose palette was fine.
         node = new WindowNode(
           rootContainer,
           windowAttributes(props, scaleOf(rootContainer)),
           props,
+          { awaitsRootScope: hostContext.underRootScope },
         );
         break;
       case 'popup':
@@ -641,11 +658,18 @@ const isNtkApp = (v) =>
  */
 function resolveBackend(options) {
   const asked = options.backend ?? process.env.REACT_X11_BACKEND ?? 'auto';
-  if (asked === 'x11' || asked === 'cocoa' || asked === 'wayland') return asked;
+  if (
+    asked === 'x11' ||
+    asked === 'cocoa' ||
+    asked === 'wayland' ||
+    asked === 'win32'
+  ) {
+    return asked;
+  }
   if (asked !== 'auto') {
     throw new Error(
       `react-x11: unknown backend ${JSON.stringify(asked)} — expected ` +
-        "'x11', 'cocoa', 'wayland' or 'auto'.",
+        "'x11', 'cocoa', 'wayland', 'win32' or 'auto'.",
     );
   }
   // Naming an X endpoint is choosing X11: a `display` or a `stream` (the
@@ -655,7 +679,13 @@ function resolveBackend(options) {
   if (options.display !== undefined || options.stream !== undefined) {
     return 'x11';
   }
-  return process.platform === 'darwin' ? 'cocoa' : 'x11';
+  if (process.platform === 'darwin') return 'cocoa';
+  // Windows has no X server to fall back to in the ordinary case, so 'auto'
+  // reaches for the native backend the way it does on a mac — and falls back
+  // to X11 below if the bridge is not installed, which is what keeps a Cygwin
+  // or WSLg setup with DISPLAY set working.
+  if (process.platform === 'win32') return 'win32';
+  return 'x11';
 }
 
 // What a root that opens its own connection forwards to ntk. `stream` is
@@ -769,17 +799,27 @@ export async function createRoot(options = {}) {
   // synchronous block, and only where the handshake takes longer than it. It
   // is not measurable on a Unix socket, and it is lost in the noise on a link
   // slow enough to matter. This is the right order, not a fast one.
-  const connectX11 = () =>
-    connect(
-      Object.fromEntries(
-        CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
-          k,
-          rest[k],
-        ]),
-      ),
+  // `REACT_X11_FONT_SOURCE` is the companion to `REACT_X11_BACKEND` above:
+  // an A/B run without touching code. ntk finds its fonts through fontconfig,
+  // and a machine with no `fc-match` — a slim container, or Windows, where
+  // the X11 backend is only ever run to compare it against the native one —
+  // has to be told where the fonts are instead. An explicit `fontSource`
+  // wins; this only fills the gap.
+  const connectX11 = () => {
+    const options = Object.fromEntries(
+      CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
+        k,
+        rest[k],
+      ]),
     );
+    options.fontSource ??= process.env.REACT_X11_FONT_SOURCE || undefined;
+    if (options.fontSource === undefined) delete options.fontSource;
+    return connect(options);
+  };
   const cocoaAsked =
     rest.backend === 'cocoa' || process.env.REACT_X11_BACKEND === 'cocoa';
+  const win32Asked =
+    rest.backend === 'win32' || process.env.REACT_X11_BACKEND === 'win32';
   const connecting = !owned
     ? Promise.resolve(borrowed)
     : backend === 'wayland'
@@ -791,25 +831,44 @@ export async function createRoot(options = {}) {
         import('./wayland/app.js').then(({ createWaylandApp }) =>
           createWaylandApp(rest),
         )
-      : backend === 'cocoa'
-        ? import('./cocoa/app.js')
-            .then(({ createCocoaApp }) => createCocoaApp(rest))
+      : backend === 'win32'
+        ? import('./win32/app.js')
+            .then(({ createWin32App }) => createWin32App(rest))
             .catch((err) => {
-              // Asked for by name, the bridge is required and its absence is
-              // the error (it says how to install). Reached by 'auto', a mac
-              // without it falls back to X11 so an XQuartz setup keeps
-              // working — said once, because a silent fallback would look
-              // like the native backend being broken rather than absent.
-              if (cocoaAsked) throw err;
+              // Same bargain as cocoa's below: asked for by name the bridge is
+              // required and its absence is the error, reached by 'auto' a
+              // machine without it falls back to X11 so a WSLg or Cygwin setup
+              // with DISPLAY set keeps working — said once, because a silent
+              // fallback reads as the native backend being broken rather than
+              // absent.
+              if (win32Asked) throw err;
               if (process.env.NODE_ENV !== 'production') {
                 console.warn(
-                  'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                  'react-x11: no @windowkit/win32 bridge — falling back to the ' +
                     `X11 backend. (${err.message.split('\n')[0]})`,
                 );
               }
               return connectX11();
             })
-        : connectX11();
+        : backend === 'cocoa'
+          ? import('./cocoa/app.js')
+              .then(({ createCocoaApp }) => createCocoaApp(rest))
+              .catch((err) => {
+                // Asked for by name, the bridge is required and its absence is
+                // the error (it says how to install). Reached by 'auto', a mac
+                // without it falls back to X11 so an XQuartz setup keeps
+                // working — said once, because a silent fallback would look
+                // like the native backend being broken rather than absent.
+                if (cocoaAsked) throw err;
+                if (process.env.NODE_ENV !== 'production') {
+                  console.warn(
+                    'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                      `X11 backend. (${err.message.split('\n')[0]})`,
+                  );
+                }
+                return connectX11();
+              })
+          : connectX11();
   const layout = loadLayout();
   const integrations = loadIntegrations(); // null when there is nothing to install
   const [app] = await Promise.all([connecting, layout, integrations]);
@@ -843,7 +902,7 @@ export async function createRoot(options = {}) {
   // critical path — every rung that fails is a normal, silent "off"
   // (docs/accessibility.md). Deliberately not awaited: a root must not
   // wait on a bus that is not there.
-  startA11y();
+  startA11y(app);
 
   // Before anything renders: the launch id has to be on the first toplevel
   // before it maps, and the environment variable has to be consumed whether

package/src/a11y.js

@@ -1275,12 +1275,29 @@ function a11yEnabled() {
  * it stopped — which is the debugging story for "why does Orca not see my
  * app".
  */
-export function startA11y() {
+export function startA11y(app) {
   if (startPromise) return startPromise;
   if (!a11yEnabled()) {
     startPromise = Promise.resolve(null);
     return startPromise;
   }
+  // A backend with an accessibility bridge of its own answers first, and its
+  // 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
+  // questions are answered from the tree itself, below.
+  if (typeof app?.startAccessibility === 'function') {
+    startPromise = Promise.resolve()
+      .then(() => app.startAccessibility())
+      .catch((err) => {
+        if (process.env.REACT_X11_A11Y) {
+          console.warn('react-x11: accessibility bridge failed to start:', err);
+        }
+        return null;
+      });
+    return startPromise;
+  }
   startPromise = import('./atspi.js')
     .then((atspi) => atspi.start())
     .catch((err) => {

package/src/acceleratorhooks.js

@@ -11,6 +11,35 @@ import { useEffect, useMemo, useRef } from 'react';
 import { matchesShortcut } from './accelerators.js';
 import { useTopLevelWindow } from './windowid.js';
 
+/**
+ * A binding whose anchor resolved to nothing binds nothing — there is no
+ * event manager to register it with, and the effect runs once, so it will
+ * not come back. Silent, that is a shortcut that simply never fires, with
+ * the tree, the chord and the handler all looking correct (issue #616).
+ *
+ * Once per process, in development: the mistake is structural, and an app
+ * that made it once made it for every chord it declares.
+ */
+let warnedAboutAnchor = false;
+export function resetAcceleratorWarningForTests() {
+  warnedAboutAnchor = false;
+}
+
+function warnUnanchored() {
+  if (process.env.NODE_ENV === 'production' || warnedAboutAnchor) return;
+  warnedAboutAnchor = true;
+  console.warn(
+    'react-x11: a shortcut was bound in a component with no window to hang ' +
+      'it off, so it is bound to nothing and will never fire. By default a ' +
+      "binding belongs to the tree's top-level <window> or, in an app with " +
+      'none, the root-level <popup> holding the keyboard. Anchor it ' +
+      'explicitly with `scope`:\n' +
+      '  const here = useRef(null);\n' +
+      "  useAccelerator([['space']], onToggle, { scope: here });\n" +
+      '  return <box ref={here}>…</box>;',
+  );
+}
+
 /**
  * Bind a chord for as long as this component is mounted, anchored at
  * `anchorRef` — the node the binding belongs to, which is what decides
@@ -30,7 +59,10 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
   useEffect(() => {
     if (!enabled) return undefined;
     const manager = anchorRef.current?.root?.events;
-    if (!manager) return undefined;
+    if (!manager) {
+      warnUnanchored();
+      return undefined;
+    }
     return manager.registerAccelerator({
       anchor: () => anchorRef.current ?? null,
       handle: (ev) => live.current?.(ev) ?? false,
@@ -52,11 +84,13 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
  * The handler is called with the key event, and the key is consumed.
  *
  * By default the binding belongs to the window the component is in, which is
- * what an application-wide shortcut wants. Two options for when it is not:
- * `enabled: false` unbinds it without unmounting anything, and `scope` takes
- * a ref to a node the binding hangs off instead — the way to give a modal
- * `<Dialog>` a shortcut of its own, since a binding on the window behind it
- * is one the modal has taken the keyboard from.
+ * what an application-wide shortcut wants — or, in an app with no `<window>`
+ * at all, to the root-level `<popup>` that took the keyboard, which is the
+ * whole of a tray popover's UI (`useTopLevelWindow`). Two options for when
+ * that is not it: `enabled: false` unbinds it without unmounting anything,
+ * and `scope` takes a ref to a node the binding hangs off instead — the way
+ * to give a modal `<Dialog>` a shortcut of its own, since a binding on the
+ * window behind it is one the modal has taken the keyboard from.
  */
 export function useAccelerator(shortcut, handler, options = {}) {
   const { enabled = true, scope } = options;

package/src/anchor.js

@@ -148,7 +148,20 @@ export function deviceAnchorArea(node) {
   if (!app) return null;
   const at = screenRect(node);
   const s = node.scale ?? 1;
-  return availableArea(app, at ? { x: at.x * s, y: at.y * s } : null);
+  // The whole rect, not its corner: a window straddling two monitors has
+  // nodes on each, and the monitor a node is on is the one it covers most of
+  // (`monitorAt`, src/screens.js).
+  return availableArea(
+    app,
+    at
+      ? {
+          x: at.x * s,
+          y: at.y * s,
+          width: at.width * s,
+          height: at.height * s,
+        }
+      : null,
+  );
 }
 
 /**
@@ -248,7 +261,12 @@ export function anchorScreenRect(app, rect, options = {}) {
     width: (rect.width ?? 0) * s,
     height: (rect.height ?? 0) * s,
   };
-  const area = app ? availableArea(app, { x: anchor.x, y: anchor.y }) : null;
+  // The monitor is picked from the whole rect rather than its top-left
+  // corner, because a tray item's frame is not inside its own display: a
+  // menu-bar button reports a rect that starts a few points above the top
+  // edge, and the corner alone lands on whichever display happens to reach
+  // up past it — a different one, on a desk with a taller head (#618).
+  const area = app ? availableArea(app, anchor) : null;
   return placeAgainst(anchor, anchor, area, s, options);
 }
 

package/src/appcontext.js

@@ -80,6 +80,14 @@ const FEATURES = {
   },
   embedding: { watch: NEVER_CHANGES, read: canEmbed },
   glOverlay: { watch: NEVER_CHANGES, read: canOverlay },
+  // Everything here is a property of the **display**: what the server, the
+  // compositor and the drawing pipeline can do. A desktop's own surfaces --
+  // a tray, a launcher icon and what hangs off it, a notification daemon --
+  // are a different question with a different shape, because they can appear
+  // and vanish while the process runs and because "available" alone is a lie
+  // about them. They go through `desktopCapability()` (src/capabilities.js),
+  // which answers `{ available, backend, features }`. Adding one here would
+  // flatten that to a boolean and lose the mechanism with it.
 };
 
 /**

package/src/appearance.js

@@ -955,6 +955,38 @@ async function macosRung() {
   return runWatcher();
 }
 
+// --------------------------------------------------------------------------
+// Rung 4: Windows
+// --------------------------------------------------------------------------
+
+/**
+ * The backend answers this one rather than this file reaching for a bridge:
+ * the values live behind a native addon that exists only on Windows, and
+ * asking the app for them is the capability test every other ladder here
+ * makes (AGENTS.md, "Find the mechanism, not the platform").
+ *
+ * All four values come from one source — the Personalize key for light or
+ * dark, DWM for the accent, and the two accessibility flags from
+ * `SystemParametersInfo` — so this rung owns every field, which is the rule
+ * the ladder is ordered for.
+ *
+ * Live rather than polled: Windows broadcasts `WM_SETTINGCHANGE`,
+ * `WM_THEMECHANGED` and `WM_DWMCOLORIZATIONCOLORCHANGED` to every top-level
+ * window, and the bridge's UI thread has one.
+ */
+async function windowsRung(app) {
+  if (typeof app?.systemAppearance !== 'function') return false;
+  const values = app.systemAppearance();
+  if (!values) return false;
+  publish(values, 'windows');
+  app.onAppearanceChange?.(() => {
+    if (owner !== 'windows') return;
+    const next = app.systemAppearance();
+    if (next) publish(next, 'windows');
+  });
+  return true;
+}
+
 // Killed rather than left behind: `unref()` keeps it from holding *this*
 // process open, and nothing keeps it from outliving it.
 process.on('exit', () => {
@@ -975,6 +1007,10 @@ async function runLadder(app) {
     // an XQuartz display never reaches this at all, which is correct — it
     // cannot read that Mac's defaults.
     ['macos', macosRung],
+    // Before XSETTINGS for the same reason macOS is: where the process is
+    // Windows, the desktop's own preference is the one the user set, and an
+    // XSETTINGS daemon there would be something they installed by hand.
+    ['windows', () => windowsRung(app)],
     ['xsettings', () => xsettingsRung(app)],
   ]) {
     let answered = false;

package/src/{cocoa → backend}/context2d.js

@@ -1,9 +1,23 @@
-// A canvas-shaped 2d context over a @windowkit/appkit CoreGraphics surface.
+// 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 the raster half of the Cocoa backend: on the surface presenter it
-// is the whole drawing path, and on the layer presenter it stays as the
-// fallback every painted-code node (<canvas>, <svg>, registered elements)
-// rasters through — docs/macos.md §"Custom drawing on a layer tree".
+// This is 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
+// optional verb is feature-detected (`ctxSetBlendMode`, `blitSurface`,
+// `ctxDrawSymbol`) and degrades rather than throwing.
+//
+// **Wayland is deliberately not here.** src/wayland/context2d.js is not
+// another copy of this file — it is a GLES rasterizer, wayland.md's Tier D,
+// which implements the same dialect by drawing it rather than by forwarding
+// it. The two are different layers, not duplicates, and folding one into the
+// other would lose that.
+//
+// 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
+// drawing on a layer tree".
 //
 // The native surface holds the real graphics state (paths, CTM, clip); this
 // class keeps the JS-visible state (fillStyle strings, gradient objects,
@@ -265,7 +279,7 @@ class SolidPicture {
   }
 }
 
-export class CocoaContext2D {
+export class BackendContext2D {
   /**
    * @param native the @windowkit/appkit module
    * @param surfaceOf () => current surface handle — the owner replaces the
@@ -1425,9 +1439,15 @@ export class CocoaContext2D {
     const family = m ? m[4] : 'sans-serif';
     const weight = m?.[2] === 'bold' ? 700 : m?.[2] ? Number(m[2]) : 400;
     const style = m?.[1] ? 'italic' : 'normal';
+    // No colour unless the caller named one, which is what `_contextInk`
+    // above is waiting for: a layout with no ink of its own is drawn with the
+    // context's fill, the way `fillText` is defined to be. Defaulting the
+    // base to black instead made every layout carry an ink, so `fillStyle`
+    // was read, found to be irrelevant, and never applied — a `fillText`
+    // under a white fill came out black on both backends.
     return fonts.layout(
       [{ text: String(text), family, size, weight, style, color }],
-      { family, size, weight, style, color: color ?? '#000' },
+      { family, size, weight, style, color },
       {},
     );
   }