react-x11 2.45.3 → 2.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.45.3",
+  "version": "2.47.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -221,6 +221,10 @@
     "./cocoa-main": {
       "types": "./src/cocoa/main.d.ts",
       "default": "./src/cocoa/main.js"
+    },
+    "./frame/child": {
+      "types": "./src/frame/child.d.ts",
+      "default": "./src/frame/child.js"
     }
   },
   "types": "./src/index.d.ts"

package/src/backend/context2d.js

@@ -28,6 +28,7 @@ import { cssColorStraight } from 'ntk/color';
 import { normalizeRadii, planShadowTiles } from 'ntk/shadow-tiles';
 
 import {
+  blurPixels,
   filterColour,
   filterPixels,
   filterStops,
@@ -183,9 +184,10 @@ function warnUndrawable(image) {
   );
 }
 
-class LinearGradient {
-  constructor(x0, y0, x1, y1) {
-    this._coords = [x0, y0, x1, y1];
+/** A canvas gradient's stops, which `fillStyle` takes: `LinearGradient`
+ *  and `RadialGradient` are where they run. */
+class Gradient {
+  constructor() {
     this._stops = [];
   }
 
@@ -194,6 +196,25 @@ class LinearGradient {
     this._stops.push(offset, r, g, b, a);
   }
 
+  /** The stops as `[offset, r, g, b, a]`, in order of offset, two at
+   *  least: one stop is a colour from end to end. */
+  _sorted() {
+    const stops = [];
+    for (let i = 0; i + 4 < this._stops.length; i += 5) {
+      stops.push(this._stops.slice(i, i + 5));
+    }
+    stops.sort((p, q) => p[0] - q[0]);
+    if (stops.length === 1) stops.push([...stops[0]]);
+    return stops;
+  }
+}
+
+class LinearGradient extends Gradient {
+  constructor(x0, y0, x1, y1) {
+    super();
+    this._coords = [x0, y0, x1, y1];
+  }
+
   /**
    * CoreGraphics requires stop locations inside [0, 1]; the decorations
    * parser deliberately pads a gradient's line past both ends (its end
@@ -203,13 +224,8 @@ class LinearGradient {
    * remaps into [0, 1].
    */
   _normalized() {
-    const stops = [];
-    for (let i = 0; i + 4 < this._stops.length; i += 5) {
-      stops.push(this._stops.slice(i, i + 5));
-    }
-    stops.sort((p, q) => p[0] - q[0]);
+    const stops = this._sorted();
     if (stops.length === 0) return { coords: this._coords, flat: [] };
-    if (stops.length === 1) stops.push([...stops[0]]);
     const min = Math.min(0, stops[0][0]);
     const max = Math.max(1, stops[stops.length - 1][0]);
     let [x0, y0, x1, y1] = this._coords;
@@ -230,6 +246,35 @@ class LinearGradient {
   }
 }
 
+/**
+ * Canvas's radial gradient: the colours spread from the start circle to
+ * the end one (@windowkit/appkit's `ctxFillRadialGradient`, whose
+ * CoreGraphics gradient is canvas's two-circle one). Canvas keeps every
+ * stop's offset in [0, 1], so they are only put in order.
+ */
+class RadialGradient extends Gradient {
+  constructor(x0, y0, r0, x1, y1, r1) {
+    super();
+    this._circles = [x0, y0, r0, x1, y1, r1];
+  }
+
+  _normalized() {
+    const stops = this._sorted();
+    for (const stop of stops) stop[0] = Math.min(1, Math.max(0, stop[0]));
+    return { circles: this._circles, flat: stops.flat() };
+  }
+}
+
+/**
+ * `createRadialGradient` on a bridge with no radial fill: a linear gradient
+ * along no line, which paints flat, as every radial gradient did before
+ * the bridge had one. It takes no circles, which is how a caller tells it
+ * from the one that draws them (`<Html>` asks `createRadialGradient.length`).
+ */
+function flatRadialGradient() {
+  return new LinearGradient(0, 0, 0, 0);
+}
+
 const clamp01 = (v) => Math.min(1, Math.max(0, Number(v) || 0));
 
 // What `textAlign`, `textBaseline` and `direction` take. A value outside
@@ -431,6 +476,10 @@ function meets(a, b) {
   );
 }
 
+/** How many pixels across a blur's standard deviation is kept as the
+ *  source is scaled down for it (`_drawBlurred`). */
+const BLUR_SCALE = 2;
+
 /** The qualities `imageSmoothingQuality` takes, canvas's. */
 const SMOOTHING_QUALITIES = new Set(['low', 'medium', 'high']);
 
@@ -525,6 +574,15 @@ export class BackendContext2D {
     this._filters = ['createSurface', 'ctxGetImageData', 'ctxPutImageData']
       .map((name) => name in native && typeof native[name] === 'function')
       .every(Boolean);
+    // and a radial gradient's fill, @windowkit/appkit 0.28.0's: where the
+    // bridge has none, the flat stand-in it always had, which takes no
+    // circles — the one a caller asks for, and keys on
+    if (!(
+      'ctxFillRadialGradient' in native &&
+      typeof native.ctxFillRadialGradient === 'function'
+    )) {
+      this.createRadialGradient = flatRadialGradient;
+    }
     this._onDirty = null;
     // the recorded path, and whether the native one still matches it (a
     // chunked stroke leaves only its last chunk behind)
@@ -1330,9 +1388,13 @@ export class BackendContext2D {
     return new LinearGradient(x0, y0, x1, y1);
   }
 
-  createRadialGradient() {
-    // radial paints flat until someone needs it; the stop list still works
-    return new LinearGradient(0, 0, 0, 0);
+  createRadialGradient(x0, y0, r0, x1, y1, r1) {
+    if (r0 < 0 || r1 < 0) {
+      throw new RangeError(
+        "Failed to execute 'createRadialGradient': a radius is negative.",
+      );
+    }
+    return new RadialGradient(x0, y0, r0, x1, y1, r1);
   }
 
   _applyFill() {
@@ -1452,7 +1514,14 @@ export class BackendContext2D {
   _fillPath(rule) {
     this._path();
     const style = this._state.fillStyle;
-    if (style instanceof LinearGradient) {
+    if (style instanceof RadialGradient) {
+      const { circles, flat: stops } = style._normalized();
+      this._native.ctxFillRadialGradient(
+        this._s(),
+        ...circles,
+        this._stops(stops),
+      );
+    } else if (style instanceof LinearGradient) {
       const { coords, flat: stops } = style._normalized();
       const flat = this._stops(stops);
       this._native.ctxFillLinearGradient(
@@ -1688,7 +1757,18 @@ export class BackendContext2D {
 
   _fillRectNow(x, y, w, h) {
     const style = this._state.fillStyle;
-    if (style instanceof LinearGradient) {
+    if (style instanceof RadialGradient) {
+      const { circles, flat: stops } = style._normalized();
+      this._native.ctxFillRadialGradient(
+        this._s(),
+        ...circles,
+        this._stops(stops),
+        x,
+        y,
+        w,
+        h,
+      );
+    } else if (style instanceof LinearGradient) {
       const { coords, flat: stops } = style._normalized();
       const flat = this._stops(stops);
       this._native.ctxFillLinearGradient(
@@ -1802,6 +1882,10 @@ export class BackendContext2D {
    * resampling an `imageSmoothingQuality` sets all take as before.
    */
   _drawFiltered(src, size, [sx, sy, sw, sh, dx, dy, dw, dh], ink) {
+    if (ink.blur > 0) {
+      this._drawBlurred(src, size, [sx, sy, sw, sh, dx, dy, dw, dh], ink);
+      return;
+    }
     const x0 = Math.max(0, Math.floor(sx));
     const y0 = Math.max(0, Math.floor(sy));
     const w = Math.min(size.width, Math.ceil(sx + sw)) - x0;
@@ -1832,6 +1916,83 @@ export class BackendContext2D {
     }
   }
 
+  /**
+   * `drawImage` under a filter with a `blur()`: the part of the source the
+   * source rect covers and as far round it as the blur reaches, three
+   * standard deviations, scaled down so that the blur is a few pixels
+   * across — the resampling the bridge does as it draws, which averages —
+   * blurred and run through the rest of the filter there, and drawn back up
+   * over the destination and as far round it, smoothed. A Gaussian is
+   * smooth to the scale it was taken at, so the pixels it lost scaling down
+   * were ones it would have blurred away, as Skia blurs a large radius. What
+   * is past the source is nothing, which a blur fades into, as canvas has it.
+   */
+  _drawBlurred(src, size, [sx, sy, sw, sh, dx, dy, dw, dh], ink) {
+    if (!(sw > 0 && sh > 0 && dw !== 0 && dh !== 0)) return;
+    // the blur in source pixels, across and down
+    const bx = (ink.blur * sw) / Math.abs(dw);
+    const by = (ink.blur * sh) / Math.abs(dh);
+    const mx = Math.ceil(3 * bx);
+    const my = Math.ceil(3 * by);
+    // what is read, in source pixels, the source's part of it, and the
+    // factor it is scaled down by
+    const left = Math.floor(sx) - mx;
+    const top = Math.floor(sy) - my;
+    const across = Math.ceil(sx + sw) + mx - left;
+    const down = Math.ceil(sy + sh) + my - top;
+    const factor = Math.max(1, Math.floor(Math.min(bx, by) / BLUR_SCALE));
+    const w = Math.max(1, Math.ceil(across / factor));
+    const h = Math.max(1, Math.ceil(down / factor));
+    const n = this._native;
+    const small = n.createSurface(w, h, 1);
+    const st = this._state;
+    try {
+      const ix = Math.max(0, left);
+      const iy = Math.max(0, top);
+      const iw = Math.min(size.width, left + across) - ix;
+      const ih = Math.min(size.height, top + down) - iy;
+      if (iw > 0 && ih > 0) {
+        if (this._smoothing) n.ctxSetImageSmoothing(small, 'high');
+        n.ctxDrawSurface(
+          small,
+          src,
+          ix,
+          iy,
+          iw,
+          ih,
+          (ix - left) / factor,
+          (iy - top) / factor,
+          iw / factor,
+          ih / factor,
+        );
+      }
+      const pixels = n.ctxGetImageData(small, 0, 0, w, h);
+      blurPixels(pixels, w, h, Math.min(bx, by) / factor);
+      if (ink.matrices.length || ink.alpha < 1) {
+        filterPixels(pixels, pixels, ink);
+      }
+      n.ctxPutImageData(small, pixels, w, h, 0, 0);
+      st.filterInk = null;
+      // the destination's units a source pixel is
+      const kx = dw / sw;
+      const ky = dh / sh;
+      this.drawImage(
+        { _surfaceHandle: small },
+        0,
+        0,
+        across / factor,
+        down / factor,
+        dx + (left - sx) * kx,
+        dy + (top - sy) * ky,
+        across * kx,
+        down * ky,
+      );
+    } finally {
+      st.filterInk = ink;
+      release(n, small);
+    }
+  }
+
   /**
    * Whether a surface is drawn under this `globalAlpha` from its pixels
    * scaled by it (@windowkit/appkit's `ctxDrawSurfaceFaded`): where the
@@ -2129,7 +2290,7 @@ export class BackendContext2D {
       ];
     }
     const style = this._state.fillStyle;
-    return style instanceof LinearGradient ? BLACK : parseColor(style);
+    return style instanceof Gradient ? BLACK : parseColor(style);
   }
 
   // --- text (minimal: enough for <canvas onDraw> users) --------------------

package/src/backend/filter.js

@@ -9,10 +9,21 @@
 // glyph run's ink and a symbol's colour are filtered by filtering the colour
 // they are drawn in, exactly. An image and a surface are filtered pixel by
 // pixel, and a text layout that carries colours of its own on a surface of
-// its own (src/backend/context2d.js). `blur()`, `drop-shadow()` and a
-// `url()` reach past what is drawn, which a colour cannot say; this context
-// does not apply them, so a list with one in it does not stick, and a
-// caller knows from reading the property back.
+// its own (src/backend/context2d.js). `drop-shadow()` and a `url()` reach
+// past what is drawn, which a colour cannot say; this context does not
+// apply them, so a list with one in it does not stick, and a caller knows
+// from reading the property back.
+//
+// `blur()` reaches past what is drawn too, and is applied to an image or a
+// surface drawn — `drawImage`, what a renderer composites a layer of its
+// own with, CSS's `backdrop-filter` among them — by blurring its pixels
+// (`blurPixels`). A fill, a stroke and text are drawn sharp under it, in
+// the colours the rest of the list makes. Its standard deviation is in the
+// units `drawImage`'s destination is given in. Several `blur()`s are one,
+// the root of the sum of their squares, as two Gaussians make one; and each
+// colour function here is a linear map on premultiplied colour, which a
+// blur, a weighted sum of premultiplied pixels, commutes with, so where in
+// the list a blur is written changes nothing but where the clamps fall.
 
 /** A function's amount where none is written: all of the effect for the
  *  ones whose argument is how much of it to take, and none for the others
@@ -38,17 +49,19 @@ const ANGLE_UNITS = {
 };
 
 /**
- * A filter list as this context applies it: `{ matrices, alpha }`, the
- * colour matrices in the order written, each over straight RGB in 0–1 with
- * an offset — none for a function that changes no colour — and what alpha
- * is multiplied by. Null for `none`; undefined for what is no filter list,
- * or one with a function this context does not apply.
+ * A filter list as this context applies it: `{ matrices, alpha, blur }`,
+ * the colour matrices in the order written, each over straight RGB in 0–1
+ * with an offset — none for a function that changes no colour — what alpha
+ * is multiplied by, and the standard deviation of the blur, 0 for none.
+ * Null for `none`; undefined for what is no filter list, or one with a
+ * function this context does not apply.
  */
 export function parseCanvasFilter(value) {
   const text = String(value).trim();
   if (text.toLowerCase() === 'none') return null;
   const matrices = [];
   let alpha = 1;
+  let blur2 = 0;
   let rest = text;
   let seen = 0;
   while (rest.length) {
@@ -57,8 +70,14 @@ export function parseCanvasFilter(value) {
     rest = rest.slice(m[0].length);
     seen += 1;
     const name = m[1].toLowerCase();
-    if (!COLOUR.has(name)) return undefined;
     const arg = m[2].trim();
+    if (name === 'blur') {
+      const radius = arg ? lengthOf(arg) : 0;
+      if (radius === null || radius < 0) return undefined;
+      blur2 += radius * radius;
+      continue;
+    }
+    if (!COLOUR.has(name)) return undefined;
     if (name === 'hue-rotate') {
       const angle = arg ? angleOf(arg) : 0;
       if (angle === null) return undefined;
@@ -76,12 +95,24 @@ export function parseCanvasFilter(value) {
     if (matrix) matrices.push(matrix);
   }
   if (!seen) return undefined;
-  return { matrices, alpha };
+  return { matrices, alpha, blur: Math.sqrt(blur2) };
 }
 
 /** Whether a parsed filter changes anything drawn. */
 export function filters(filter) {
-  return !!filter && (filter.matrices.length > 0 || filter.alpha < 1);
+  return (
+    !!filter &&
+    (filter.matrices.length > 0 || filter.alpha < 1 || filter.blur > 0)
+  );
+}
+
+/** A length in pixels; a bare 0 is one. */
+function lengthOf(arg) {
+  const m = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(px)?$/i.exec(arg);
+  if (!m) return null;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n)) return null;
+  return m[2] || n === 0 ? n : null;
 }
 
 /** A number or a percentage of one. */
@@ -283,3 +314,117 @@ export function filterPixels(src, dst, filter) {
 function clampByte(v) {
   return v <= 0 ? 0 : v >= 255 ? 255 : Math.round(v);
 }
+
+/**
+ * Straight RGBA pixels, 0–255, `width` by `height`, blurred in place by a
+ * Gaussian of standard deviation `sigma` pixels: three box blurs across and
+ * three down, each as wide as the Gaussian they come to (Kovesi, "Fast
+ * almost-Gaussian filtering", 2010), on premultiplied colour — a blur of
+ * straight colour bleeds the colour of what is transparent into its edge —
+ * with nothing past the edge, as canvas has it.
+ */
+export function blurPixels(pixels, width, height, sigma) {
+  if (!(sigma > 0) || !(width > 0 && height > 0)) return;
+  const n = width * height;
+  // premultiplied, the four channels of a pixel side by side
+  const plane = new Float32Array(n * 4);
+  for (let p = 0; p < n * 4; p += 4) {
+    const alpha = pixels[p + 3] / 255;
+    plane[p] = pixels[p] * alpha;
+    plane[p + 1] = pixels[p + 1] * alpha;
+    plane[p + 2] = pixels[p + 2] * alpha;
+    plane[p + 3] = pixels[p + 3];
+  }
+  const line = new Float32Array(Math.max(width, height) * 4);
+  for (const radius of boxRadii(sigma)) {
+    if (radius < 1) continue;
+    boxPass(plane, width, height, radius, 4, width * 4, line);
+    boxPass(plane, height, width, radius, width * 4, 4, line);
+  }
+  for (let p = 0; p < n * 4; p += 4) {
+    const alpha = plane[p + 3];
+    if (alpha <= 0.5) {
+      pixels[p] = pixels[p + 1] = pixels[p + 2] = pixels[p + 3] = 0;
+      continue;
+    }
+    const k = 255 / alpha;
+    pixels[p] = clampByte(plane[p] * k);
+    pixels[p + 1] = clampByte(plane[p + 1] * k);
+    pixels[p + 2] = clampByte(plane[p + 2] * k);
+    pixels[p + 3] = clampByte(alpha);
+  }
+}
+
+/** The radii of three box blurs that come to a Gaussian of `sigma`. */
+function boxRadii(sigma) {
+  const passes = 3;
+  const ideal = Math.sqrt((12 * sigma * sigma) / passes + 1);
+  let lower = Math.floor(ideal);
+  if (lower % 2 === 0) lower -= 1;
+  const upper = lower + 2;
+  const m = Math.round(
+    (12 * sigma * sigma -
+      passes * lower * lower -
+      4 * passes * lower -
+      3 * passes) /
+      (-4 * lower - 4),
+  );
+  const out = [];
+  for (let i = 0; i < passes; i += 1) {
+    out.push(((i < m ? lower : upper) - 1) / 2);
+  }
+  return out;
+}
+
+/**
+ * One box blur of `radius` along every line of a plane of RGBA pixels:
+ * `lines` lines of `length` pixels, a pixel `step` values from the next
+ * along a line and a line `stride` values from the next. Past either end
+ * is nothing.
+ */
+function boxPass(plane, length, lines, radius, step, stride, line) {
+  const scale = 1 / (2 * radius + 1);
+  for (let l = 0; l < lines; l += 1) {
+    const base = l * stride;
+    for (let i = 0, q = base; i < length; i += 1, q += step) {
+      const o = i * 4;
+      line[o] = plane[q];
+      line[o + 1] = plane[q + 1];
+      line[o + 2] = plane[q + 2];
+      line[o + 3] = plane[q + 3];
+    }
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let a = 0;
+    for (let i = 0; i <= radius && i < length; i += 1) {
+      const o = i * 4;
+      r += line[o];
+      g += line[o + 1];
+      b += line[o + 2];
+      a += line[o + 3];
+    }
+    for (let i = 0, q = base; i < length; i += 1, q += step) {
+      plane[q] = r * scale;
+      plane[q + 1] = g * scale;
+      plane[q + 2] = b * scale;
+      plane[q + 3] = a * scale;
+      const enter = i + radius + 1;
+      if (enter < length) {
+        const o = enter * 4;
+        r += line[o];
+        g += line[o + 1];
+        b += line[o + 2];
+        a += line[o + 3];
+      }
+      const leave = i - radius;
+      if (leave >= 0) {
+        const o = leave * 4;
+        r -= line[o];
+        g -= line[o + 1];
+        b -= line[o + 2];
+        a -= line[o + 3];
+      }
+    }
+  }
+}

package/src/cocoa/relaunch.js

@@ -143,6 +143,19 @@ export const WORKER_START = `(function (process, global) {
 // process for ever.
 const WORKER_END_MS = 5000;
 
+// Where Node starts an app (`startedRunning`): the script that loads the
+// `--require` preloads and then the entry, and the module that runs the
+// entry, an ES module's graph from an async function.
+const ENTRY_POINT = new Set([
+  'node:internal/main/run_main_module',
+  'node:internal/modules/run_main',
+]);
+
+// How a process is started under an ES module loader, as a flag of its own
+// or in NODE_OPTIONS: `--import tsx`, `--import=tsx`, `--loader
+// ts-node/esm`, `--experimental-loader ./hooks.mjs`.
+const LOADER_FLAG = /^--(?:import|loader|experimental-loader)(?:=|$)/;
+
 /**
  * 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
@@ -152,6 +165,8 @@ export function relaunchVeto({
   isMainThread: main,
   platform,
   env,
+  execArgv,
+  node,
   entry,
   compiled,
   late,
@@ -184,13 +199,33 @@ export function relaunchVeto({
   ) {
     return 'a test runner';
   }
-  // Imported after the app started running — a dynamic import from a
-  // timer, say. Relaunching would run again, on the worker, everything the
-  // entry has already done on this thread.
+  // Imported after the app started running: by an `import()` from a timer,
+  // say, or one the entry's body awaits. Relaunching would run again, on
+  // the worker, everything the entry has already done on this thread.
   if (late) return 'imported after the app started running';
+  // Started under an ES module loader, before Node 24. The worker gets the
+  // loader's flags, and whether its hooks follow is the loader's to say:
+  // tsx, the one an app is likeliest to run under, keeps them to the main
+  // thread on Node 20 and 22 — before 22.22.3, by tsx 4.23's own check —
+  // and a worker without them stops on the entry's first .jsx or .ts module
+  // (measured, 20.20 and 22.16). No loader can be asked before the move, so
+  // any `--import` or `--loader` counts. From 24 an app under one moves,
+  // and tsx follows it there from 4.21.1 on 24.11.1 (an older one does not,
+  // docs/macos.md); `react-x11/cocoa-main` moves one on 20 or 22 whose
+  // loader follows.
+  if (node && node < 24 && startedUnderLoader(execArgv, env.NODE_OPTIONS)) {
+    return 'an ES module loader before Node 24';
+  }
   return null;
 }
 
+/** Whether node's flags, its own or NODE_OPTIONS', name an ES module loader. */
+function startedUnderLoader(execArgv = [], nodeOptions = '') {
+  return [...execArgv, ...nodeOptions.split(/\s+/)].some((flag) =>
+    LOADER_FLAG.test(flag),
+  );
+}
+
 /** What `relaunchVeto` reads, from this process. */
 export function describeProcess(moduleUrl) {
   const bun = globalThis.Bun;
@@ -199,6 +234,9 @@ export function describeProcess(moduleUrl) {
     isMainThread,
     platform: process.platform,
     env: process.env,
+    execArgv: process.execArgv,
+    // Node's major version; Bun answers with one of its own choosing
+    node: bun ? null : Number(process.versions.node.split('.')[0]),
     entry: typeof entry === 'string' && fs.existsSync(entry) ? entry : null,
     compiled: compiledExecutable(bun),
     late: startedRunning(bun, moduleUrl, entry),
@@ -216,15 +254,36 @@ function compiledExecutable(bun) {
 }
 
 /**
- * Whether the entry's own code has started. Node's event loop has not
- * turned while the entry's static imports evaluate —
- * `performance.nodeTiming.loopStart` is -1 until it does. 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 (both measured, Node 26 and Bun 1.4).
+ * Whether the entry's own code has started: whether this import is one the
+ * app made after its start, rather than part of it.
+ *
+ * Node tells by where the import is evaluated from. It starts an app from
+ * two modules of its own (`ENTRY_POINT`): a CommonJS entry, and every
+ * `require()` of its first run and of a `--require` preload, evaluate under
+ * them synchronously, and an ES module entry's graph — static imports, an
+ * `--import` preload's — from an async function there, which V8 keeps on
+ * the stack as an async frame. An `import()` is evaluated by a job of its
+ * own, whose stack ends in the module loader, or in the app's own code when
+ * that awaits it: an `await import()` in the entry's body, an async
+ * function of the app's. Measured on Node 20.20, 22.16, 23.2, 24.12, 25.4
+ * and 26.0, static imports nested and behind a module with a top-level
+ * await, and under tsx, `--experimental-loader`, source maps and a stack
+ * trace limit of 0. A Node that moved those modules would read every
+ * import as late, which keeps the app where it is rather than running it
+ * twice; test/cocoa-relaunch.test.js would say so on any OS.
+ *
+ * `performance.nodeTiming.loopStart`, -1 until the event loop turns, is the
+ * public signal and is wrong both ways: Node 20 and 22 turn the loop while
+ * they load an ES module entry, so no such entry moved there, and Node 24
+ * 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).
  */
 function startedRunning(bun, moduleUrl, entry) {
-  if (!bun) return performance.nodeTiming?.loopStart > 0;
+  if (!bun) return !evaluatedFromEntryPoint();
   try {
     return Boolean(createRequire(moduleUrl).cache?.[entry]?.loaded);
   } catch {
@@ -232,13 +291,40 @@ function startedRunning(bun, moduleUrl, entry) {
   }
 }
 
+/** Whether this stack, async frames and all, comes from `ENTRY_POINT`. */
+function evaluatedFromEntryPoint() {
+  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);
+    const held = {};
+    Error.captureStackTrace(held);
+    sites = held.stack;
+  } finally {
+    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;
+}
+
 /**
  * The import-time move (src/bootstrap.js): relaunch when nothing vetoes it
  * and a bridge that can run AppKit's loop is installed. Returns why it did
  * not, for anyone asking; when it does, it does not return.
  */
 export function relaunchOnImport(moduleUrl) {
-  const veto = relaunchVeto(describeProcess(moduleUrl));
+  const facts = describeProcess(moduleUrl);
+  const veto = relaunchVeto(facts);
   if (veto) return veto;
   let native;
   try {
@@ -248,7 +334,7 @@ export function relaunchOnImport(moduleUrl) {
     return 'no cocoa bridge';
   }
   if (typeof native.runMain !== 'function') return 'the bridge has no runMain';
-  return relaunch(describeProcess(moduleUrl).entry, native);
+  return relaunch(facts.entry, native);
 }
 
 /**

package/src/frame/child.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `react-x11/frame/child` — the entry a `<Frame>` forks: a pane process's
+ * whole bootstrap, over the IPC channel `fork()` sets up. **Resolved, not
+ * imported**: a `transport` that starts the pane its own way — under a
+ * sandbox, with a runtime of its own choosing — forks
+ * `fileURLToPath(import.meta.resolve('react-x11/frame/child'))`, and
+ * importing it anywhere else exits the process. No exports.
+ */
+export {};

package/src/frame/childmain.js

@@ -168,6 +168,18 @@ export async function runFrameChild(transport, options = {}) {
   }
   markFramed();
 
+  // The host's watchdog asks whether this process is still answering; the
+  // answer comes from the event loop, which is the thing it asks about.
+  // From the first moment, since the host asks from its hello on.
+  transport.onMessage((msg) => {
+    if (msg?.type !== 'ping') return;
+    try {
+      transport.send({ type: 'pong', seq: msg.seq });
+    } catch {
+      // the host is going away
+    }
+  });
+
   const hello = await new Promise((resolve) => {
     const off = transport.onMessage((msg) => {
       if (msg?.type !== 'hello') return;

package/src/frame/index.js

@@ -73,21 +73,22 @@ const childPath = () =>
 
 /** The default transport: fork this package's child entry. `execArgv` is
  * inherited, which is what carries a dev loader (tsx, the refresh loader)
- * into the pane; a bundled app forks plain JS and needs none. */
-function forkTransport({ src, display }) {
+ * into the pane; a bundled app forks plain JS and needs none. The pane's
+ * own flags and environment (`<Frame execArgv env>`) go on top. */
+function forkTransport({ src, display, execArgv = [], env = {} }) {
   const child = fork(childPath(), [], {
     serialization: 'advanced',
     // dev loaders (tsx, the refresh loader) follow into the pane; the test
     // runner's own flags must not — `--test` in execArgv would run the pane
-    // entry as a test file
-    execArgv: process.execArgv.filter(
-      (a) => a !== '--test' && !a.startsWith('--test-'),
-    ),
-    env: {
-      ...process.env,
-      REACT_X11_FRAME: '1',
-      ...(display ? { DISPLAY: display } : {}),
-    },
+    // entry as a test file. The pane's come after, so a flag it names is
+    // the one in force where the two disagree.
+    execArgv: [
+      ...process.execArgv.filter(
+        (a) => a !== '--test' && !a.startsWith('--test-'),
+      ),
+      ...execArgv,
+    ],
+    env: paneEnv(env, display),
   });
   void src; // resolved by the child from the hello, not from argv
   return {
@@ -121,6 +122,84 @@ function forkTransport({ src, display }) {
   };
 }
 
+/**
+ * The environment a pane process starts with: this one's, with what the
+ * `<Frame>` names over it — `undefined` takes a variable away — and then
+ * the two that are not the app's to set: `REACT_X11_FRAME`, which is how a
+ * pane knows it is one (`isFramed`), and `DISPLAY`, which `display` names.
+ */
+function paneEnv(env, display) {
+  const out = { ...process.env };
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) delete out[name];
+    else out[name] = value;
+  }
+  out.REACT_X11_FRAME = '1';
+  if (display) out.DISPLAY = display;
+  return out;
+}
+
+/**
+ * What a pane's process is started with, checked and as one string: the
+ * session's key, so that an `execArgv` array or an `env` object written in
+ * place — a new one each render — restarts nothing, and one that says
+ * something else restarts the pane. Throws on what a fork cannot take,
+ * which the session reports as a `spawn` failure.
+ */
+/** How long a pane may go without answering by default: long enough for a
+ *  pane that is working, through a collection or a long layout, short
+ *  enough that one that is not is noticed before the reader gives up. */
+const WATCHDOG_MS = 15000;
+
+/**
+ * The watchdog's limit, in ms, or 0 where the pane is not watched: `false`,
+ * or a pane started under the inspector — by its own flags, this process's
+ * that it inherits, or `NODE_OPTIONS` — which a debugger stops on purpose.
+ * The flags that turn the inspector on, and not its kin that only set it
+ * up: Node's test runner hands every test process `--inspect-port` and
+ * `--inspect-publish-uid`, and a pane in a test is not being debugged.
+ */
+function watchdogMs(watchdog, execArgv) {
+  if (watchdog === false) return 0;
+  const limit = Number(watchdog);
+  if (!(limit > 0)) return 0;
+  const flags = [
+    ...process.execArgv,
+    ...(execArgv ?? []),
+    ...(process.env.NODE_OPTIONS ?? '').split(/\s+/),
+  ];
+  return flags.some((flag) => INSPECTING.test(flag)) ? 0 : limit;
+}
+const INSPECTING = /^--inspect(?:-brk|-wait)?(?:=|$)/;
+
+function launchOf(execArgv, env) {
+  if (
+    execArgv !== undefined &&
+    (!Array.isArray(execArgv) || execArgv.some((a) => typeof a !== 'string'))
+  ) {
+    throw new TypeError(
+      'react-x11: <Frame execArgv> is an array of strings — the flags the ' +
+        "pane's process is started with.",
+    );
+  }
+  if (
+    env !== undefined &&
+    (env === null ||
+      typeof env !== 'object' ||
+      Object.values(env).some((v) => v !== undefined && typeof v !== 'string'))
+  ) {
+    throw new TypeError(
+      "react-x11: <Frame env> maps a variable's name to a string, or to " +
+        'undefined to take it away.',
+    );
+  }
+  // `undefined` is kept apart from a variable left alone, which
+  // JSON.stringify would drop
+  return JSON.stringify([execArgv ?? [], env ?? {}], (_, v) =>
+    v === undefined ? { unset: true } : v,
+  );
+}
+
 function srcString(src) {
   if (src !== null && typeof src === 'object' && typeof src.href === 'string') {
     return src.href;
@@ -220,6 +299,9 @@ export function Frame({
   props = EMPTY_PROPS,
   style,
   display,
+  execArgv,
+  env: processEnv,
+  watchdog = WATCHDOG_MS,
   bridge = true,
   fallback,
   focusable,
@@ -262,8 +344,22 @@ export function Frame({
   const source = srcString(src);
   const makeTransport = transport ?? forkTransport;
   const containerRef = useRef(null);
+  // the pane process's own flags and environment, by what they say
+  let launch;
+  let launchError = null;
+  try {
+    launch = launchOf(execArgv, processEnv);
+  } catch (err) {
+    launch = '';
+    launchError = err;
+  }
+  const paneProcess = useRef(null);
+  paneProcess.current = { execArgv: execArgv ?? [], env: processEnv ?? {} };
+  // how long the pane may go without answering, where it is watched at all
+  const watched = watchdogMs(watchdog, execArgv);
 
-  // The session: one child process per (src, display, transport, restart).
+  // The session: one child process per (src, display, the process's flags
+  // and environment, transport, restart).
   // Declared before the update effect so that on the mounting commit the
   // hello goes out first and the update pass sees itself already sent.
   useEffect(() => {
@@ -297,7 +393,13 @@ export function Frame({
 
     let t;
     try {
-      t = makeTransport({ src: source, display });
+      if (launchError) throw launchError;
+      t = makeTransport({
+        src: source,
+        display,
+        execArgv: paneProcess.current.execArgv,
+        env: paneProcess.current.env,
+      });
     } catch (err) {
       fail(Object.assign(err, { phase: 'spawn' }));
       return undefined;
@@ -309,6 +411,8 @@ export function Frame({
       fatal: null,
       sent: null,
       shutdown: null,
+      answered: performance.now(),
+      watch: null,
     };
     session.current = s;
 
@@ -337,6 +441,8 @@ export function Frame({
           pid: t.pid ?? null,
           windowId: msg.windowId,
         });
+      } else if (msg?.type === 'pong') {
+        s.answered = performance.now();
       } else if (msg?.type === 'invoke') {
         s.table.invoke(msg.id, msg.args);
       } else if (msg?.type === 'fatal') {
@@ -354,6 +460,7 @@ export function Frame({
     };
     offExit = t.onExit(({ code = null, signal = null, error } = {}) => {
       clearEscalation?.();
+      clearInterval(s.watch);
       detach();
       const expected = s.closing;
       if (alive && !expected) {
@@ -382,6 +489,7 @@ export function Frame({
     s.shutdown = () => {
       if (s.closing) return;
       s.closing = true;
+      clearInterval(s.watch);
       let sent = false;
       try {
         t.send({ type: 'unmount' });
@@ -430,6 +538,48 @@ export function Frame({
       ...(paneApp?.playsForPanes && { players: true }),
     });
 
+    // The watchdog. A pane whose event loop is stuck stays `running`, is
+    // sent updates it never reads, and on X11 holds the keys while the
+    // pointer is over it — and says nothing. So it is asked, about once a
+    // second, and answers from its event loop (`runFrameChild`); one that
+    // has not answered in `watchdog` ms has stopped, and goes the way a
+    // pane that crashed goes: failed, phase `'unresponsive'`, and its
+    // process ended, so `fallback` can offer to start it again. A tick of
+    // this side's own that comes late — the machine slept, or this
+    // process was the one stuck — is no news of the pane's, and the
+    // count starts again from it.
+    if (watched > 0) {
+      const every = Math.max(50, Math.min(1000, watched / 4));
+      let ticked = performance.now();
+      let seq = 0;
+      s.watch = setInterval(() => {
+        if (s.closing) return;
+        const now = performance.now();
+        const late = now - ticked > every * 3;
+        ticked = now;
+        if (late) s.answered = now;
+        else if (now - s.answered > watched) {
+          clearInterval(s.watch);
+          const message = `the pane stopped answering for ${Math.round(
+            now - s.answered,
+          )} ms`;
+          s.fatal = { phase: 'unresponsive', message };
+          fail(Object.assign(new Error(message), { phase: 'unresponsive' }));
+          // it cannot read an unmount: ended, from outside
+          t.kill?.('SIGTERM');
+          const kill = setTimeout(() => t.kill?.('SIGKILL'), 2000);
+          kill.unref?.();
+          return;
+        }
+        try {
+          t.send({ type: 'ping', seq: (seq += 1) });
+        } catch {
+          // the channel is going; the exit says the rest
+        }
+      }, every);
+      s.watch.unref?.();
+    }
+
     return () => {
       alive = false;
       s.shutdown();
@@ -439,7 +589,15 @@ export function Frame({
       // ask, and everything is unref'd so nothing holds the host open
       if (session.current === s) session.current = null;
     };
-  }, [source, display, generation, makeTransport, canShowPane]);
+  }, [
+    source,
+    display,
+    launch,
+    generation,
+    makeTransport,
+    canShowPane,
+    watched,
+  ]);
 
   // One update per commit that changed the pane's inputs, props and env in
   // the same message — so a theme flip and the state change that caused it

package/src/frame/protocol.js

@@ -3,17 +3,19 @@
 // channel (the fork transport), a loopback pair (the tests), or whatever a
 // custom transport is built on.
 //
-// Six messages, all objects with a `type`:
+// Eight messages, all objects with a `type`:
 //
 //   parent → child
 //     hello    { protocol, src, display, rect, props, env, players? }   first, once
 //     update   { props, env }        full snapshots, one per parent commit
 //     unmount  {}                    run close handlers, unmount, exit
+//     ping     { seq }               the watchdog: still answering?
 //
 //   child → parent
 //     ready    { windowId }          the pane mounted; embed this
 //     invoke   { id, args }          a bridged callback fired
 //     fatal    { phase, message, stack }   why the exit about to happen is one
+//     pong     { seq }               yes, from the event loop
 //
 // Values cross by **structured clone** (fork uses `serialization:
 // 'advanced'`), so Dates, Maps, TypedArrays and cycles survive — and
@@ -33,7 +35,9 @@
 // what makes the grace window about racing messages rather than about how
 // the app was written.
 
-export const PROTOCOL = 1;
+// 2: the watchdog's ping and pong. A pane of protocol 1 answers no ping,
+// and would be ended as one that stopped; it fails the handshake instead.
+export const PROTOCOL = 2;
 
 /** The marker key a function in `props` becomes on the wire. */
 export const CALLBACK = '$$reactX11FrameCallback';

package/src/node.d.ts

@@ -90,10 +90,11 @@ export interface Context2D {
    * Canvas's: a CSS filter list applied to what is drawn after it. Native
    * contexts only (macOS, Windows), and only the colour functions —
    * `grayscale()`, `sepia()`, `saturate()`, `hue-rotate()`, `invert()`,
-   * `brightness()`, `contrast()` and `opacity()` — over a bridge that reads
-   * a surface's pixels back. Anything else does not stick: assign and read
-   * back to know. Absent on X11, whose server runs no colour matrix and
-   * answers a read a round trip later.
+   * `brightness()`, `contrast()` and `opacity()` — and `blur()`, which
+   * blurs what `drawImage` draws and leaves fills, strokes and text sharp,
+   * over a bridge that reads a surface's pixels back. Anything else does
+   * not stick: assign and read back to know. Absent on X11, whose server
+   * runs no colour matrix and answers a read a round trip later.
    */
   filter?: string;
   save(): void;

package/src/types/frame.d.ts

@@ -16,7 +16,7 @@ export type FrameProps = Record<string, unknown>;
 /** Why a pane is not running, for `fallback` and `onExit` to read. */
 export interface FrameError extends Error {
   /** Where it went wrong: `'spawn' | 'load' | 'connect' | 'handshake' |
-   * 'runtime' | 'send' | 'embed' | 'exit'`. */
+   * 'runtime' | 'send' | 'embed' | 'unresponsive' | 'exit'`. */
   phase?: string;
   code?: number | null;
   signal?: string | null;
@@ -45,6 +45,30 @@ export interface FrameComponentProps {
   style?: StyleProp;
   /** X display for the pane process; defaults to the inherited `$DISPLAY`. */
   display?: string;
+  /**
+   * Flags for the pane's process, after the ones it inherits from this one
+   * (a dev loader's): `['--max-old-space-size=256']` bounds the pane's heap,
+   * which nothing inside the pane can. They are handed to the runtime that
+   * forks it, so they are that runtime's flags. A change restarts the pane;
+   * the same flags in a new array do not.
+   */
+  execArgv?: readonly string[];
+  /**
+   * How long the pane may go without answering, in ms, before it is taken
+   * for one whose event loop is stuck: failed with phase `'unresponsive'`,
+   * its process ended, and `fallback` shown. Asked about once a second,
+   * from its event loop. Default 15000; `false` never. A pane started
+   * under the inspector is never watched.
+   */
+  watchdog?: number | false;
+  /**
+   * Environment variables for the pane's process, over this one's; a value
+   * of `undefined` takes a variable away. `DISPLAY` is `display`'s and
+   * `REACT_X11_FRAME` marks the pane (`isFramed`), so neither can be set
+   * here. A change restarts the pane; the same variables in a new object do
+   * not.
+   */
+  env?: Readonly<Record<string, string | undefined>>;
   /**
    * Which bridged contexts follow the app into this pane: `true` (default)
    * for every registered one — the theme included — `false` for none, or an
@@ -75,10 +99,23 @@ export interface FrameComponentProps {
    * (a loopback pair into `runFrameChild`), and the door to running a pane
    * somewhere other than a child process. Advanced; see docs/frame.md.
    */
-  transport?(options: { src: string; display?: string }): FrameTransport;
+  transport?(options: FrameTransportOptions): FrameTransport;
   ref?: Ref<FrameHandle>;
 }
 
+/** What a transport is asked to start: the pane module, and the display,
+ *  flags and environment `<Frame>` names for its process. The default
+ *  transport forks `react-x11/frame/child` with them. */
+export interface FrameTransportOptions {
+  src: string;
+  display?: string;
+  /** `<Frame execArgv>`, or none: added to what the pane inherits. */
+  execArgv: readonly string[];
+  /** `<Frame env>`, or none: over this process's environment, `undefined`
+   *  taking a variable away. */
+  env: Readonly<Record<string, string | undefined>>;
+}
+
 /** The parent's end of the wire to a pane. */
 export interface FrameTransport {
   /** May throw when the channel is gone or the message will not clone. */