react-x11 2.48.0 → 2.50.0

package/src/cocoa/relaunch.js

@@ -22,6 +22,8 @@
 // name: it runs before the entry is even loaded, and skips the checks.
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { isMainThread, SHARE_ENV, Worker } from 'node:worker_threads';
 
 import { loadNative } from './native.js';
@@ -156,6 +158,15 @@ const ENTRY_POINT = new Set([
 // ts-node/esm`, `--experimental-loader ./hooks.mjs`.
 const LOADER_FLAG = /^--(?:import|loader|experimental-loader)(?:=|$)/;
 
+// The module Bun runs an entry from (`startedRunning`): one it writes
+// itself, which imports the entry (measured, Bun 1.4).
+const BUN_MAIN = 'bun:main';
+
+// What Bun parses an entry as, by its extension: a .ts file may hold a
+// `<T>x` cast, which TSX reads as an element, and JSX is allowed in a .js
+// file, where the JSX reader takes any script a plain one would.
+const SCAN_LOADER = { '.tsx': 'tsx', '.ts': 'ts', '.mts': 'ts', '.cts': 'ts' };
+
 /**
  * Why this import should not move the app onto a worker, or null when it
  * should. A pure answer over what the process says about itself, so that
@@ -278,14 +289,14 @@ function compiledExecutable(bun) {
  * and later evaluate an `import()` the entry makes before the loop's first
  * turn, so an app that made one moved and ran its entry twice.
  *
- * Bun reports 1 there from the first line; what tells in Bun is the entry's
- * record in the module cache, which is there once the entry has been
- * evaluated and absent while its imports are (measured, Bun 1.4).
+ * Bun reports no loop there, its `nodeTiming` a stand-in at 1 once
+ * `node:perf_hooks` is loaded, and leaves no frame below a module it
+ * evaluates, so it is read its own way (`bunStartedRunning`).
  */
 function startedRunning(bun, moduleUrl, entry) {
   if (!bun) return !evaluatedFromEntryPoint();
   try {
-    return Boolean(createRequire(moduleUrl).cache?.[entry]?.loaded);
+    return bunStartedRunning(bun, moduleUrl, entry);
   } catch {
     return false;
   }
@@ -293,13 +304,106 @@ function startedRunning(bun, moduleUrl, entry) {
 
 /** Whether this stack, async frames and all, comes from `ENTRY_POINT`. */
 function evaluatedFromEntryPoint() {
+  const sites = callSites();
+  if (!sites) return false;
+  for (const site of sites) {
+    const file = site.getFileName() ?? '';
+    if (ENTRY_POINT.has(file)) return true;
+    // the app's own code awaits this import, so it has run already
+    if (site.isAsync() && !file.startsWith('node:')) return false;
+  }
+  return false;
+}
+
+/**
+ * `startedRunning` in Bun, read from three things it shows of the entry's
+ * run (each measured, Bun 1.4).
+ *
+ * Its module registry. Bun runs the entry from a module it writes itself,
+ * `bun:main`, which imports it, and `require.cache` lists an ES module once
+ * it has been evaluated: `bun:main` is there once the entry has finished,
+ * top-level awaits and all, and an import made after that is late. Before
+ * then the entry's own record says nothing either way. Bun marks a CommonJS
+ * module `loaded` before its body runs, which read as late from a CommonJS
+ * entry's first line, so it never moved; and an ES module has no record
+ * until it is evaluated, which read as not started for an entry awaiting
+ * its `import()` of react-x11, so it moved and ran a second time on the
+ * worker.
+ *
+ * The stack. Bun's loader evaluates an ES module's imports with no frame
+ * below the module, so a frame below react-x11 is code that loaded it
+ * synchronously. A CommonJS entry is in `require.cache` from its first line,
+ * and on its first run its own wrapper is the outermost frame. Bun runs the
+ * nextTicks and microtasks that first run queues before it evaluates
+ * `bun:main`: a callback there in another module reads as late, and one in
+ * the entry itself as its first run, unless in strict code it ends by
+ * returning its `require()`, which JavaScriptCore makes a tail call that
+ * leaves it no frame. For an ES module entry, a frame below react-x11 is a
+ * CommonJS module the entry imports, on its first run, or a `require()` in
+ * a module's body, and a bundle carries react-x11 inside the entry itself:
+ * each of them the start.
+ *
+ * The entry's static imports. An ES module's body runs once every module it
+ * imports statically has been evaluated: while one has not, the entry has
+ * not run a line and react-x11 is part of its graph, an `import()` that one
+ * of those modules awaits included; once all have, the entry's body is
+ * running or waiting on a top-level await, and asked for react-x11 itself.
+ * Read with Bun's own scanner and resolver, and what they cannot answer
+ * throws, which reads as the start.
+ */
+function bunStartedRunning(bun, moduleUrl, entry) {
+  const cache = createRequire(entry).cache;
+  // the entry has finished
+  if (BUN_MAIN in cache) return true;
+  const outer = outermostFile();
+  // a CommonJS entry: late unless on its first run
+  if (entry in cache) return outer !== undefined && outer !== entry;
+  let own = null;
+  try {
+    own = fileURLToPath(moduleUrl);
+  } catch {
+    // a CommonJS bundle has no import.meta.url
+  }
+  // react-x11 inside the entry, or loaded by code below it on the stack
+  if (own === entry || (outer !== undefined && outer !== own)) return false;
+  // reached by an import: late once the entry's body has started
+  const { imports } = new bun.Transpiler({
+    loader: SCAN_LOADER[path.extname(entry)] ?? 'jsx',
+  }).scan(fs.readFileSync(entry, 'utf8'));
+  const dir = path.dirname(entry);
+  return imports.every(
+    ({ kind, path: specifier }) =>
+      kind !== 'import-statement' || bun.resolveSync(specifier, dir) in cache,
+  );
+}
+
+/**
+ * The file of the outermost frame on this stack that is not native code,
+ * or undefined where the stack cannot be read.
+ */
+function outermostFile() {
+  const sites = callSites();
+  if (!sites) return undefined;
+  for (let i = sites.length - 1; i >= 0; i--) {
+    if (!sites[i].isNative()) return sites[i].getFileName() ?? undefined;
+  }
+  return undefined;
+}
+
+/**
+ * This stack as call sites, every frame of it, or null where it cannot be
+ * read as call sites — an `Error` the app has frozen, say. Raises the stack
+ * trace limit and sets a formatter for as long as it takes, and puts back
+ * the app's own.
+ */
+function callSites() {
   const { prepareStackTrace, stackTraceLimit } = Error;
   let sites;
   try {
     // Reflect.set: an Error the app has frozen is not a reason to throw
     // from its import of react-x11
     Reflect.set(Error, 'stackTraceLimit', Infinity);
-    Reflect.set(Error, 'prepareStackTrace', (_, callSites) => callSites);
+    Reflect.set(Error, 'prepareStackTrace', (_, frames) => frames);
     const held = {};
     Error.captureStackTrace(held);
     sites = held.stack;
@@ -307,14 +411,7 @@ function evaluatedFromEntryPoint() {
     Reflect.set(Error, 'prepareStackTrace', prepareStackTrace);
     Reflect.set(Error, 'stackTraceLimit', stackTraceLimit);
   }
-  if (!Array.isArray(sites)) return false;
-  for (const site of sites) {
-    const file = site.getFileName() ?? '';
-    if (ENTRY_POINT.has(file)) return true;
-    // the app's own code awaits this import, so it has run already
-    if (site.isAsync() && !file.startsWith('node:')) return false;
-  }
-  return false;
+  return Array.isArray(sites) ? sites : null;
 }
 
 /**

package/src/currentcolor.js

@@ -0,0 +1,28 @@
+// CSS's `currentColor`: the colour keyword that is not a colour yet.
+//
+// A leaf, like decorations.js, because every layer that reads a colour asks
+// about it — the grammar (styles.js, shorthands.js, decorations.js) to let
+// it through, and the paint (nodes/boxpaint.js and every backend's reader
+// of a style colour) to resolve it.
+//
+// It stays the keyword in `node.style` — CSS's computed value — and becomes
+// a colour only where something is about to paint it, against the node's
+// resolved ink (`Node.resolveColor`). Resolving it once in the style funnel
+// instead would bake the ink into the style object, which no inherited
+// change reaches: a `:hover { color }` on a row moves the ink of every node
+// under it without restyling any of them.
+
+/** `currentColor`, spelled any way CSS accepts — its keywords are ASCII
+ *  case-insensitive — and with the whitespace a style value may carry. */
+const KEYWORD = /^\s*currentcolor\s*$/i;
+const MENTION = /currentcolor/i;
+
+/** Whether `value` is the keyword. Asked per colour per paint, so a value
+ *  too short to be it is answered without the match. */
+export const isCurrentColor = (value) =>
+  typeof value === 'string' && value.length >= 12 && KEYWORD.test(value);
+
+/** Whether a value made of several — a gradient, a shadow list — names the
+ *  keyword anywhere in it. */
+export const mentionsCurrentColor = (value) =>
+  typeof value === 'string' && value.length >= 12 && MENTION.test(value);

package/src/decorations.js

@@ -37,6 +37,8 @@
 import { cssColorStraight } from 'ntk/color';
 import { shadowReach, shadowSigma } from 'ntk/shadow-math';
 
+import { isCurrentColor } from './currentcolor.js';
+
 /** A number, with or without the `px` CSS wants and this vocabulary does not. */
 const LENGTH = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:px)?$/i;
 /** …and the same thing as a percentage, which colour stops also take. */
@@ -50,9 +52,11 @@ const HORIZONTAL = new Set(['left', 'right']);
 /**
  * Split on `,` or on whitespace, but only at the top level: a stop is
  * `rgba(0, 0, 0, .4)` as often as it is `#333`, and every naive split on
- * this vocabulary gets that wrong.
+ * this vocabulary gets that wrong. The shorthands split by it too
+ * (src/shorthands.js) — `border: '1px solid rgba(0, 0, 0, .1)'` is three
+ * values, not six.
  */
-function splitTop(text, byComma) {
+export function splitTop(text, byComma) {
   const out = [];
   let depth = 0;
   let start = 0;
@@ -207,14 +211,16 @@ function readStop(part, value) {
   return { color: stopColor(part, value), position: null };
 }
 
-/** A stop's colour, which RENDER is handed as written — and ntk throws on
- *  one it cannot parse from inside the frame, where nothing can catch it. */
+/** A stop's colour, which RENDER is handed as written once a `currentColor`
+ *  is resolved (`_backgroundGradient`) — and ntk throws on one it cannot
+ *  parse from inside the frame, where nothing can catch it. */
 function stopColor(color, value) {
   if (isColorOrToken(color)) return color;
   throw new Error(
     `react-x11: backgroundImage ${JSON.stringify(value)} has a colour stop ` +
       `that is not a colour ("${color}"; expected one like '#2980b9', ` +
-      "'tomato' or 'rgba(0, 0, 0, .4)', or a $token, before its position)",
+      "'tomato', 'rgba(0, 0, 0, .4)' or 'currentColor', or a $token, before " +
+      'its position)',
   );
 }
 
@@ -223,10 +229,15 @@ function stopColor(color, value) {
  * One that mentions a `$token` is let through where the style is written,
  * since the token means nothing yet; the paint parses the value it resolves
  * to, and a colour that is still not one drops the whole decoration there
- * rather than throwing (see "memoized parsing" below).
+ * rather than throwing (see "memoized parsing" below). `currentColor` is
+ * the node's ink, which only the paint knows (`Node.resolveColor`).
  */
 function isColorOrToken(color) {
-  return color.includes('$') || cssColorStraight(color) !== null;
+  return (
+    color.includes('$') ||
+    cssColorStraight(color) !== null ||
+    isCurrentColor(color)
+  );
 }
 
 /**
@@ -349,7 +360,8 @@ function resolveStopOffsets(stops, length) {
  * renderer draws the list back to front.
  *
  * `color` may be null, which is CSS's `currentColor` — the node's own ink,
- * which the caller resolves because only it knows the cascade.
+ * which the caller resolves because only it knows the cascade. The keyword
+ * written out reads as null too, so a shadow has one way to say it.
  *
  * Throws on `inset` and on anything unparseable; see the note at the top of
  * this file for why a shadow that silently does the wrong thing is worse
@@ -394,7 +406,7 @@ function readShadow(part, value) {
   }
   const [dx, dy, blur = 0, spread = 0] = lengths;
   if (blur < 0) throw bad('has a negative blur radius');
-  return { dx, dy, blur, spread, color };
+  return { dx, dy, blur, spread, color: isCurrentColor(color) ? null : color };
 }
 
 /**

package/src/editor.js

@@ -0,0 +1,151 @@
+// Source locations and the editor that opens them: reading a stack trace
+// into frames, telling the frames of an app's own code from React's and this
+// renderer's, and handing a file and line to the developer's editor. Shared by
+// click-to-component (an Alt+Click on an element) and `react-x11 dev`'s error
+// window (a click on a frame), so the two open the same editor the same way.
+// A leaf: nothing here reaches the renderer or React DevTools.
+import { spawn } from 'node:child_process';
+import { dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const STACK_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/;
+
+// The frames to walk past before the JSX call site itself: React captures
+// the Error inside `jsxDEV`/`createElement`, and an element created by this
+// renderer (or by node internals) is never what a click means. `SELF_DIR` is
+// whichever copy of react-x11 is running — the repo's own `src/` for the
+// examples and tests, an installed `node_modules/react-x11/src` for an app.
+//
+// Everything *else* in `node_modules` is deliberately not skipped here: a
+// frame inside an installed package is a real call site, it is just not one
+// in the application's source, and telling the two apart is what lets
+// `resolveOwnedLocation` climb to the owner that is. Skipping every
+// `node_modules` frame instead would walk straight past the library
+// component and land on whatever application frame happens to be deeper in
+// the render stack — usually the `render()` call at startup, which looks
+// like an answer and isn't.
+const REACT_RUNTIME =
+  /[\\/]node_modules[\\/](react|react-dom|react-reconciler|react-refresh|scheduler)[\\/]/;
+const SELF_DIR = dirname(fileURLToPath(import.meta.url)) + sep;
+
+export function isInternalFrame(file) {
+  return (
+    file.startsWith('node:') ||
+    file === '<anonymous>' ||
+    file.startsWith(SELF_DIR) ||
+    REACT_RUNTIME.test(file)
+  );
+}
+
+// GUI editors: navigate their registered URI scheme (same idea as
+// https://github.com/sidorares/show-component, minus the browser) instead of
+// spawning their CLI shim. The CLI wrapper (e.g. `cursor -g ...`) round-trips
+// through a shell script that re-detects and re-execs the real app, which is
+// visibly slower than the OS handing the URL straight to the already-running
+// instance via Launch Services (macOS) / xdg-open (Linux).
+const EDITOR_SCHEMES = {
+  cursor: 'cursor',
+  code: 'vscode',
+  vscode: 'vscode',
+  'code-insiders': 'vscode-insiders',
+  'vscode-insiders': 'vscode-insiders',
+  windsurf: 'windsurf',
+};
+
+// Terminal editors have no URI scheme to navigate — spawn them directly.
+const EDITOR_CLI = {
+  vim: (file, line, column) => [
+    'vim',
+    [`+call cursor(${line},${column})`, file],
+  ],
+  nvim: (file, line, column) => [
+    'nvim',
+    [`+call cursor(${line},${column})`, file],
+  ],
+};
+
+const OPEN_URI_COMMAND = process.platform === 'darwin' ? 'open' : 'xdg-open';
+
+function editorUri(scheme, file, line, column) {
+  return `${scheme}://file${encodeURI(file)}:${line}:${column}`;
+}
+
+export function openInEditor({ file, line, column }) {
+  const name = editorName();
+  let bin, args;
+  if (EDITOR_CLI[name]) {
+    [bin, args] = EDITOR_CLI[name](file, line, column);
+  } else {
+    // an unrecognized name is assumed to be a URI scheme itself, so any
+    // editor that registers one works without a matching entry above
+    const scheme = EDITOR_SCHEMES[name] || name;
+    bin = OPEN_URI_COMMAND;
+    args = [editorUri(scheme, file, line, column)];
+  }
+  // stderr is kept (rather than the whole stdio ignored) for one reason:
+  // `open`/`xdg-open` exit non-zero and print *there* when nothing claims
+  // the scheme — an editor that isn't installed, or one whose URL handler
+  // was never registered. Swallowing that is what makes click-to-component
+  // look like it only logs: the location resolves, the console line prints,
+  // and the editor silently never opens.
+  const child = spawn(bin, args, {
+    detached: true,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  let stderr = '';
+  // ...and unref'd, so keeping it does not keep the process alive: a pipe is
+  // a ref'd handle, and an editor that outlives the app it was launched from
+  // is the normal case, not a reason to hold the event loop open.
+  child.stderr.unref();
+  child.stderr.on('data', (chunk) => {
+    stderr += chunk;
+  });
+  child.on('error', (err) => {
+    console.warn(
+      `react-x11: could not launch "${bin}" to open ${file}:${line} (${err.code ?? err.message}). ` +
+        'Set REACT_X11_EDITOR to your editor CLI (cursor, code, code-insiders, windsurf, vim, nvim).',
+    );
+  });
+  child.on('exit', (code) => {
+    if (!code) return;
+    console.warn(
+      `react-x11: opening ${file}:${line} — \`${bin} ${args.join(' ')}\` exited ${code}. ` +
+        (stderr.trim() ? `${stderr.trim()} ` : '') +
+        `Set REACT_X11_EDITOR to the editor you actually use (currently "${name}"; ` +
+        'cursor, code, code-insiders, windsurf, vim, nvim, or any registered URI scheme).',
+    );
+  });
+  child.unref();
+}
+
+/** The editor `openInEditor` opens: `REACT_X11_EDITOR`, else `cursor`. */
+export function editorName() {
+  return process.env.REACT_X11_EDITOR || 'cursor';
+}
+
+/**
+ * A stack trace's frames, in order: where each one is, what it is called, and
+ * whether it is React's, Node's or this renderer's own (`internal`) or inside
+ * an installed package (`installed`). Lines that are not frames — the message,
+ * a `[cause]` — are not in the list.
+ */
+export function stackFrames(stack) {
+  const frames = [];
+  for (const text of String(stack ?? '').split('\n')) {
+    const match = text.match(STACK_FRAME);
+    if (!match) continue;
+    const [, functionName, rawFile, lineStr, columnStr] = match;
+    const file = rawFile.startsWith('file://')
+      ? fileURLToPath(rawFile)
+      : rawFile;
+    frames.push({
+      functionName: functionName ?? null,
+      file,
+      line: Number(lineStr),
+      column: Number(columnStr),
+      internal: isInternalFrame(file),
+      installed: file.includes(`${sep}node_modules${sep}`),
+    });
+  }
+  return frames;
+}

package/src/errors.js

@@ -6,6 +6,14 @@
 // `data` handler and takes the process with it, or wedges the frame loop,
 // which is worse: it looks like a hang rather than a crash.
 
+/**
+ * The `code` of the error a drawn element at the root of the tree throws
+ * (Reconciler.js, `notAtRoot`). A code because a tool acts on it: `react-x11
+ * dev` mounts a component that renders no `<window>` inside one of its own,
+ * and the message is prose that is free to change.
+ */
+export const NOT_IN_WINDOW = 'NOT_IN_WINDOW';
+
 // container -> the root's onUncaughtError, when it set one
 const perContainer = new WeakMap();
 

package/src/foreignnodes.js

@@ -482,12 +482,19 @@ export class ForeignNode extends Node {
   _applyBackground() {
     const wnd = this.socket?.window;
     if (typeof wnd?.setBackgroundPixel !== 'function') return;
-    const pixel = pixelFor(this.style.backgroundColor);
+    const pixel = pixelFor(this.resolveColor(this.style.backgroundColor));
     if (pixel === null || pixel === this._backgroundPixel) return;
     this._backgroundPixel = pixel;
     wnd.setBackgroundPixel(pixel);
   }
 
+  /** …which a `currentColor` takes from the ink, and the ink can move with
+   *  no commit here. */
+  _inkMoved() {
+    super._inkMoved();
+    this._applyBackground();
+  }
+
   /** The client's window is a window of the display system over this one,
    *  so it follows the whole subtree's visibility — see
    *  `GlAreaNode._syncSurfaceVisibility`, which answers the same call. */

package/src/gloverlay.js

@@ -86,6 +86,7 @@
 import { cssColorStraight } from 'ntk/color';
 
 import { FULL_DAMAGE, addDamageRect } from './nodes/damage.js';
+import { radiusOf } from './styles.js';
 import {
   innerPixels,
   intersectRects,
@@ -1200,7 +1201,7 @@ export class GlOverlay {
     }
     const area = this.area;
     // a rounded surface clips its children to an arc, and the arc stays put
-    if ((area.style?.borderRadius ?? 0) > 0) return false;
+    if (radiusOf(area.style, area.abs) > 0) return false;
     // the whole pixels of the surface's box: a fractional edge is an
     // antialiased clip, and that does not move either
     const box = innerPixels(area.abs);

package/src/node.d.ts

@@ -624,6 +624,11 @@ export declare class Node {
    * with none of its own is set in. An element that draws text inherits
    * exactly what `<text>` inherits by asking. */
   resolvedTextStyle(): TextStyle;
+  /** A colour from this node's style as one a context can paint: the value
+   * itself, or — for `currentColor` — the node's ink, the colour
+   * `resolvedTextStyle()` resolves. Everything core paints from a style
+   * colour asks here; an element painting one of its own should too. */
+  resolveColor<T>(value: T): T | string;
   /** The flattened `style` prop with the active state blocks overlaid.
    * Everything that paints or lays out reads this, never `props`. */
   readonly style: Style;

package/src/nodes/animation.js

@@ -11,9 +11,11 @@ import {
   transitionFor,
   interpolate,
   ease,
+  isColor,
   isLayoutProp,
   TEXT_LAYOUT_PROPS,
 } from '../styles.js';
+import { isCurrentColor } from '../currentcolor.js';
 import { GRID_CONTAINER_PROPS, GRID_ITEM_PROPS } from '../grid.js';
 import { isPlaced } from '../layouts.js';
 import { desktopSettings, watchDesktopSettings } from '../desktopsettings.js';
@@ -85,11 +87,16 @@ export class NodeAnimation {
     // transitions start on later changes, which is CSS's rule too.
     if (this._placed) {
       for (const prop of Object.keys(target)) {
-        const to = target[prop];
-        const from = displayed[prop];
+        let to = target[prop];
+        let from = displayed[prop];
         if (from === to || from === undefined) continue;
         const duration = transitionFor(target, prop);
         if (duration <= 0) continue;
+        if (isCurrentColor(from) || isCurrentColor(to)) {
+          from = this._swapInk(prop, from, displayed);
+          to = this._swapInk(prop, to, target);
+          if (from === to) continue;
+        }
         if (interpolate(from, to, 0.5) === null) continue; // no midpoint: snap
         const entry = {
           from,
@@ -260,6 +267,27 @@ export class NodeAnimation {
     return this.style;
   }
 
+  /**
+   * A `currentColor` end of a transition as the colour it is at the swap:
+   * the ink `style` gives this node, or on `color` itself the ink it
+   * inherits. The keyword has no midpoint of its own, so the transition
+   * runs between the two colours as they are now — and lands on the style,
+   * where the keyword follows the ink again. An ink that moves mid-flight
+   * is caught up with at the end, not chased: a `color` that should carry
+   * a border with it is the property to transition.
+   */
+  _swapInk(prop, value, style) {
+    if (!isCurrentColor(value)) return value;
+    const inherited = this.inheritedTextStyle.color;
+    if (prop === 'color') return inherited;
+    // the displayed style's ink is cached; the target's is not yet
+    return style === this.style
+      ? this.resolvedTextStyle().color
+      : isColor(style.color)
+        ? style.color
+        : inherited;
+  }
+
   _animatedValues() {
     const values = {};
     for (const [prop, a] of this._anim) {
@@ -388,7 +416,7 @@ export class NodeAnimation {
     const specs =
       target.animation == null
         ? null
-        : animationsOf(target, 'a style', this.scale);
+        : animationsOf(target, 'a style', this.scale, this._units);
     if (!specs && !this._loops) return false;
     this._loops = specs;
     if (!specs) this.root?._forgetLoopNode(this);