react-x11 2.11.0 → 2.12.0

package/src/cocoa/window.js

@@ -12,6 +12,11 @@ import { CocoaLayerPresenter } from './presenter.js';
 import { CocoaPromotion } from './promotion.js';
 
 let nextWindowId = 1;
+// How long a worker's flip may keep its window's back buffer before the
+// window draws into it anyway (`_armFence`). The release is reported once
+// the replacing frame has committed, a fraction of a millisecond later, and
+// a window must not freeze on a report that never came.
+const FENCE_TIMEOUT_MS = 100;
 
 export class CocoaWindow {
   constructor(app, attributes = {}) {
@@ -34,6 +39,9 @@ export class CocoaWindow {
     // — the period of the display it is on (`_refreshFrameInterval`).
     this._rafLast = 0;
     this._frameInterval = 0;
+    // …and when a frame last reached glass, whoever painted it: the pump's
+    // paced frame or an input answered on the spot (`frameInFlight`)
+    this._presentedAt = -Infinity;
 
     const s = this.scale;
     // Snapped to whole POINTS: AppKit rounds window sizes to the point
@@ -75,7 +83,7 @@ export class CocoaWindow {
     // Transparent to the pointer, the preview is passed over and the hit
     // reaches what it covers (#488; @windowkit/appkit >= 0.6.0, an older
     // bridge ignores the option). The drop side is excluded separately:
-    // nodes.js `_initDnd` gives a preview no DropSession and registers
+    // nodes/window/droptarget.js `_initDnd` gives a preview no DropSession and registers
     // nothing.
     if (attributes.dragPreview) options.ignoresMouseEvents = true;
     // The root layer's background is the "what newly exposed area shows"
@@ -87,14 +95,48 @@ export class CocoaWindow {
       const parsed = app._parseColor(attributes.backgroundColor);
       if (parsed) options.backgroundColor = parsed;
     }
+    // Where it was asked to go, until AppKit says where it went
+    // (`_refreshOrigin`) — which on a worker is not before the window exists.
+    this.x = Math.round(attributes.x ?? 0);
+    this.y = Math.round(attributes.y ?? 0);
+    this._screenOrigin = { x: this.x, y: this.y };
+    // AppKit's content size in points, as the bridge last reported it
+    // (`_frameSize`)
+    this._points = null;
+    // Threaded mode's swapchain fence (`frameInFlight`): the IOSurface id
+    // on the layer as far as this window has asked, the one the last flip
+    // is taking off glass until the bridge says it is released, and the
+    // catch-up copy the back buffer is owed once it is back.
+    this._onGlass = null;
+    this._awaiting = null;
+    this._catchUp = null;
+    this._fenceTimer = null;
+    this._shadowTimer = null;
+    // AppKit's live resize, between the bridge's `window-live-resize` begin
+    // and end (`CocoaApp._routeLiveResize`): a tick of it lays out with the
+    // floors it has, and fresh ones are measured after the drag
+    // (nodes/window/size.js, `_deferContentFloors`)
+    this.liveResizing = false;
     this._h = this._native.createWindow2(options);
+    // On a worker the bridge answers a handle at the call and makes the
+    // window when its command runs: the number is null until then, and
+    // `window-created` brings it (`_created`).
     this.windowNumber = this._native.windowNumber(this._h);
+    // What the app's window map and the events name this window by: the
+    // handle on a worker, where every window event carries it, and the
+    // number in pump mode, where the events carry only that.
+    this._key = app._threaded ? this._h : this.windowNumber;
     this._layer = this._native.windowRootLayer(this._h);
+    // A worker's frame lands after AppKit has moved the window's edge, so
+    // AppKit is asked to wait for it (`RESIZE_WAIT_MS`, src/cocoa/app.js).
+    if (app._threaded && app._resizeWait > 0) {
+      this._native.setResizeHandshake(this._h, { waitMs: app._resizeWait });
+    }
     this._refreshOrigin();
     this._refreshFrameInterval();
     if (attributes.sizeHints) this.setSizeHints(attributes.sizeHints);
 
-    // How many damage rects a frame may keep before merging them (nodes.js,
+    // How many damage rects a frame may keep before merging them (nodes/damage.js,
     // MAX_DAMAGE_RECTS is the X11 answer). A pass here costs one CoreGraphics
     // clip and a culled walk, where an X pass costs the server a clip mask,
     // so a frame in which a clock, a graph and a status row all ticked keeps
@@ -106,7 +148,7 @@ export class CocoaWindow {
     // The retained layer presenter (docs/macos.md Tier L), behind
     // REACT_X11_COCOA_PRESENTER=layers while the surface path is the
     // measured default. Its hooks exist only in this mode, so the feature
-    // detection in nodes.js keeps the surface path byte-identical; the
+    // detection in src/nodes/ keeps the surface path byte-identical; the
     // scroll blit is shadowed off because a layer frame has no backing
     // bitmap to blit. The last two are the animation seam: a transition or
     // a loop the presenter takes runs in the render server and schedules no
@@ -159,6 +201,8 @@ export class CocoaWindow {
 
   _refreshOrigin() {
     const f = this._native.getWindowFrame(this._h);
+    // a worker's window AppKit has not made yet: the asked-for origin stands
+    if (!f) return;
     const s = this.scale;
     this.x = Math.round(f.x * s);
     this.y = Math.round(f.y * s);
@@ -177,8 +221,17 @@ export class CocoaWindow {
     this._frameInterval = this.app.frameIntervalFor(this);
   }
 
+  /** `window-created`: AppKit has made the window a worker asked for, and
+   * published where it put it. */
+  _created(ev) {
+    this.windowNumber = ev.windowNumber;
+    this._refreshOrigin();
+    this._refreshFrameInterval();
+  }
+
   /** Native geometry changed (delegate event, points). */
   _nativeResized(points) {
+    this._points = { width: points.width, height: points.height };
     const s = this.scale;
     this.width = Math.max(1, Math.round(points.width * s));
     this.height = Math.max(1, Math.round(points.height * s));
@@ -186,12 +239,6 @@ export class CocoaWindow {
     this.y = Math.round(points.y * s);
     this._screenOrigin = { x: this.x, y: this.y };
     this._refreshFrameInterval();
-    // AppKit's inLiveResize, as the delegate reported it: the renderer
-    // answers a live tick with the layout floors it has and measures fresh
-    // ones after the drag (nodes.js, `_deferContentFloors`). Cleared by
-    // the pump (`_endLiveResizes`), because the pump cannot run while the
-    // resize loop owns the thread — a tick of it is the drag being over.
-    if (points.live === true) this.liveResizing = true;
   }
 
   resize(width, height) {
@@ -251,12 +298,14 @@ export class CocoaWindow {
       this.app.cancelAttention(this._attentionRequest);
       this._attentionRequest = null;
     }
+    clearTimeout(this._shadowTimer);
+    this._shadowTimer = null;
     this._promotion?.destroy();
     this._native.destroyWindow2(this._h);
     this._releaseBacking();
   }
 
-  // --- window-manager-ish surface (feature-detected by nodes.js) -----------
+  // --- window-manager-ish surface (feature-detected by src/nodes/) ---------
 
   setTitle(title) {
     this.title = title;
@@ -287,7 +336,7 @@ export class CocoaWindow {
    * until the state is removed or the window goes. Every other name resolves
    * `false` — ntk's own contract for a state the server cannot honour —
    * because the bridge has no zoom/miniaturize/fullscreen verbs yet
-   * (windowkit/appkit#15 scoped them out); nodes.js swallows the false.
+   * (windowkit/appkit#15 scoped them out); WindowNode swallows the false.
    */
   setWmState(names, action = 'add') {
     const list = Array.isArray(names) ? names : [names];
@@ -312,9 +361,9 @@ export class CocoaWindow {
   // --- drag and drop (src/cocoa/dnd.js) ------------------------------------
 
   /**
-   * The drop side: nodes.js hands over the window's DropSession at realize
+   * The drop side: WindowNode hands over the window's DropSession at realize
    * (`_initDnd`), and from then on the app routes this window's `drag-*`
-   * events into it. Its presence on the window is what tells nodes.js the
+   * events into it. Its presence on the window is what tells WindowNode the
    * backend has drop machinery of its own.
    */
   attachDropTransport(session, node) {
@@ -404,6 +453,9 @@ export class CocoaWindow {
    * that frame is on glass.
    */
   _ensureSurface() {
+    // a paint that did not wait for the fence: the back buffer gets its
+    // catch-up now, so what it paints lands over the frame before it
+    this._settleBack();
     const w = this.width;
     const h = this.height;
     if (
@@ -461,10 +513,15 @@ export class CocoaWindow {
     }
     this._chain = null;
     this._surface = null;
+    // a new pair owes nothing to what the old one was showing
+    clearTimeout(this._fenceTimer);
+    this._fenceTimer = null;
+    this._awaiting = null;
+    this._catchUp = null;
   }
 
   /**
-   * The per-flush painted rects (nodes.js's swapchain seam), accumulated
+   * The per-flush painted rects (WindowNode's swapchain seam), accumulated
    * until the next present: they are what the flip's catch-up copy covers.
    * `'full'`/null collapse the set — one full copy beats bookkeeping.
    */
@@ -473,7 +530,7 @@ export class CocoaWindow {
     if (this._freshSurface) {
       this._freshSurface = false;
       // A full flush painted every pixel of the new surface, and a resize
-      // event's flush is one (nodes.js, the 'resize' listener). A bounded
+      // event's flush is one (nodes/window/listeners.js, the 'resize' listener). A bounded
       // one left garbage outside its rects: hold the present until the full
       // frame asked for here lands, so the garbage is never on glass.
       if (rects) {
@@ -537,6 +594,9 @@ export class CocoaWindow {
    * caller falls back to the plain repaint. */
   scrollRegion(rect, dx, dy) {
     if (!this._surface) return false;
+    // the band moves over the frame before this one, not over a buffer
+    // still owed its catch-up
+    this._settleBack();
     if (!Number.isInteger(dx) || !Number.isInteger(dy)) return false;
     const moved = this._native.scrollSurface(
       this._surface,
@@ -566,8 +626,51 @@ export class CocoaWindow {
     return Boolean(moved);
   }
 
+  /**
+   * Whether this window's last frame still holds the buffer the next one
+   * would be drawn into — the X11 contract's fence (src/frames.js). The
+   * pump never needs it: a pump-mode flip is applied in the call, so the
+   * other buffer is off glass before the next paint. A worker's flip is a
+   * command the UI thread applies later, and until the bridge reports the
+   * buffer it replaced as released (`_surfaceReleased`), drawing into that
+   * buffer draws into what is on glass. A new size is never in flight: it
+   * paints into a new pair that nothing is showing.
+   *
+   * And while a batch is being routed (`CocoaApp._routeBatch`), its frame
+   * is the one owed: it goes out when the batch is done, answering every
+   * input in it at once. The early flush a discrete event asks for on its
+   * way out (src/frames.js) waits those few microseconds, rather than
+   * painting a state the next event in the same batch replaces.
+   */
   frameInFlight() {
-    return false;
+    if (this.app._batching) return true;
+    return (
+      this._awaiting != null &&
+      this._surfaceSize?.width === this.width &&
+      this._surfaceSize?.height === this.height
+    );
+  }
+
+  /**
+   * Whether this window flipped less than one of its frame intervals ago —
+   * the wheel's gate (`CocoaApp._routeWheel`), and only the wheel's.
+   *
+   * A trackpad routinely lands two scroll events in one pump tick, and each
+   * used to paint and flip on the spot: the second frame was drawn into the
+   * buffer the first flip had taken off glass microseconds before, while the
+   * WindowServer could still be compositing from it. A scroll's frame blits,
+   * then repaints what the shift got wrong, so a composite caught between the
+   * two shows the blit alone — a held sticky header dragged up a pixel for a
+   * frame, or the rows under it painted over it, then corrected. No other
+   * input has both halves of that: a resize paints into a pair it has just
+   * made, and a press or a key does not come in bursts inside a refresh.
+   *
+   * Off with the interval: `frameInterval: 0` asks for no pacing at all.
+   */
+  _flippedRecently(now = performance.now()) {
+    return (
+      this._frameInterval > 0 && now - this._presentedAt < this._frameInterval
+    );
   }
 
   requestAnimationFrame(cb) {
@@ -597,47 +700,158 @@ export class CocoaWindow {
     // again next tick and the frame goes out the moment the window is back.
     if (this._holdPresent || !this._visible()) return false;
     this._dirty = false;
+    this._presentedAt = performance.now();
     if (this._chain) {
       const shown = this._chain.back;
       this._native.surfaceUnlock(shown.handle);
-      this._native.setLayerContentsIOSurface(this._layer, shown.iosurfaceId);
+      this._flip(() =>
+        this._native.setLayerContentsIOSurface(this._layer, shown.iosurfaceId),
+      );
       this._chain.back = this._chain.front;
       this._chain.front = shown;
       this._surface = this._chain.back.handle;
       // a different native surface owns the graphics state now — the
       // context re-syncs its sticky state off the generation
       this._surfaceGen++;
-      this._native.surfaceLock(this._surface);
-      const damage = this._flushDamage;
+      const catchUp = { from: shown.handle, damage: this._flushDamage };
       this._flushDamage = null;
-      this._native.copySurfaceRegion(
-        shown.handle,
-        this._surface,
-        damage === 'full' || !damage
-          ? null
-          : damage.flatMap((r) => [
-              Math.floor(r.x),
-              Math.floor(r.y),
-              Math.ceil(r.width) + 1,
-              Math.ceil(r.height) + 1,
-            ]),
-      );
-      if (this._transparentWindow) this.app._shadowStale.add(this);
+      // The buffer drawn into next is the one this flip takes off glass —
+      // when it was on glass at all: a new pair's first flip replaces a
+      // buffer of the old pair, or nothing. On a worker the flip has not
+      // happened yet, so its catch-up and the next paint wait for the
+      // bridge to say it has (`frameInFlight`).
+      const previous = this._onGlass;
+      this._onGlass = shown.iosurfaceId;
+      if (this.app._threaded && previous === this._chain.back.iosurfaceId) {
+        this._awaiting = previous;
+        this._catchUp = catchUp;
+        this._armFence();
+      } else {
+        this._settle(catchUp);
+      }
+      this._shadowAfterFlip();
       return true;
     }
-    this._native.surfaceToLayer(this._surface, this._layer);
-    // AppKit derives a transparent window's shadow from the content's
-    // opaque shape and does not recompute it on repaints — a popup whose
-    // card lands a frame after the map keeps the full-frame square AppKit
-    // guessed first. Recompute — but only once this present's transaction
-    // has actually flushed to the render server, or the recompute reads
-    // the frame BEFORE this one and keeps the square rim for menus that
-    // paint once and are only hovered after.
-    if (this._transparentWindow) this.app._shadowStale.add(this);
+    this._flip(() => this._native.surfaceToLayer(this._surface, this._layer));
+    this._shadowAfterFlip();
+    return true;
+  }
+
+  /**
+   * Hand a frame to the layer. In pump mode that is the verb alone: the
+   * bridge flips in a transaction of its own, in the call. On a worker the
+   * flip is recorded and committed as one frame (windowkit/appkit#52), and
+   * the commit says what size the frame was painted at, which is what a
+   * resize waits for (`setResizeHandshake`, #53). Actions off, as the
+   * bridge's own transaction has them.
+   */
+  _flip(apply) {
+    if (!this.app._threaded) return apply();
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      return apply();
+    } finally {
+      native.txCommit(this._frameSize());
+    }
+  }
+
+  /**
+   * The size this window's frames are painted at, in the points AppKit
+   * measures a window by: the bridge's own figures when they describe the
+   * current size, so that the handshake's comparison is exact.
+   */
+  _frameSize() {
+    const p = this._points;
+    const s = this.scale;
+    if (
+      p &&
+      Math.max(1, Math.round(p.width * s)) === this.width &&
+      Math.max(1, Math.round(p.height * s)) === this.height
+    ) {
+      return { width: p.width, height: p.height };
+    }
+    return { width: this.width / s, height: this.height / s };
+  }
+
+  /** The back buffer is off glass: lock it for drawing and copy across what
+   * the frame now shown painted, so that the next frame starts from it. */
+  _settle({ from, damage }) {
+    this._native.surfaceLock(this._surface);
+    this._native.copySurfaceRegion(
+      from,
+      this._surface,
+      damage === 'full' || !damage
+        ? null
+        : damage.flatMap((r) => [
+            Math.floor(r.x),
+            Math.floor(r.y),
+            Math.ceil(r.width) + 1,
+            Math.ceil(r.height) + 1,
+          ]),
+    );
+  }
+
+  /** Stop waiting on the fence: the back buffer's catch-up, now. */
+  _settleBack() {
+    if (this._awaiting == null) return;
+    clearTimeout(this._fenceTimer);
+    this._fenceTimer = null;
+    this._awaiting = null;
+    const catchUp = this._catchUp;
+    this._catchUp = null;
+    if (catchUp && this._chain) this._settle(catchUp);
+  }
+
+  /** `surface-released` for `id`: true when it was the buffer this window
+   * was waiting on. */
+  _surfaceReleased(id) {
+    if (this._awaiting == null || this._awaiting !== id) return false;
+    this._settleBack();
     return true;
   }
 
+  _armFence() {
+    clearTimeout(this._fenceTimer);
+    this._fenceTimer = setTimeout(() => {
+      this._fenceTimer = null;
+      if (this._awaiting == null || this.destroyed) return;
+      this._settleBack();
+      this.app._tickFrames();
+      this.app._presentAll();
+    }, FENCE_TIMEOUT_MS);
+  }
+
+  /**
+   * AppKit derives a transparent window's shadow from the content's opaque
+   * shape and does not recompute it on repaints — a popup whose card lands
+   * a frame after the map keeps the full-frame square AppKit guessed first.
+   * Recompute — but only once this present's transaction has actually
+   * flushed to the render server, or the recompute reads the frame BEFORE
+   * this one and keeps the square rim for menus that paint once and are
+   * only hovered after. In pump mode that is the next pump tick; on a
+   * worker, where the flip is a command and the recompute would be another
+   * one drained beside it, a frame interval later.
+   */
+  _shadowAfterFlip() {
+    if (!this._transparentWindow) return;
+    if (!this.app._threaded) {
+      this.app._shadowStale.add(this);
+      return;
+    }
+    if (this._shadowTimer) return;
+    this._shadowTimer = setTimeout(
+      () => {
+        this._shadowTimer = null;
+        if (!this.destroyed) this._native.invalidateWindowShadow(this._h);
+      },
+      Math.max(1, Math.round(this._frameInterval || 16)),
+    );
+  }
+
+  /** The window's content as a PNG at `path`; resolves whether it was
+   * written. A promise on either thread: on a worker AppKit answers later. */
   snapshot(path) {
-    return this._native.snapshotWindow(this._h, path);
+    return this.app._ask('snapshotWindow', this._h, path);
   }
 }

package/src/components/Select.js

@@ -73,7 +73,7 @@ const itemHeight = (fontSize) => capBand(fontSize) + ITEM_PAD * 2;
 // what NSPopUpButtonCell does with a title too long for its cell. It is
 // also what makes the label *give way*: an eliding `nowrap` floors at the
 // mark it would end in, where a clipping one keeps its full width and
-// pushes whatever contains it wider (nodes.js, `_wrapWidth`).
+// pushes whatever contains it wider (nodes/text.js, `_wrapWidth`).
 const ONE_LINE = Object.freeze({
   textWrap: 'nowrap',
   textOverflow: 'ellipsis',
@@ -139,7 +139,7 @@ const MENU_BORDER = 1;
 // the trigger (`menuAnchorOptions`).
 const TRIGGER_PAD_LEFT = 10;
 // the scrollbar is drawn *over* the content rather than insetting it
-// (`nodes.js`, SCROLLBAR_WIDTH), so a menu that scrolls reserves the room
+// (`nodes/scrollbars.js`, SCROLLBAR_WIDTH), so a menu that scrolls reserves the room
 const SCROLLBAR_WIDTH = 6;
 
 function normalizeOption(option) {

package/src/components/anchor.js

@@ -50,7 +50,7 @@ function sameAnchorRect(a, b) {
  * hanging over stale ground.
  *
  * Subscribes to the anchoring node's owner window (`WindowNode.onAnchorChange`,
- * `nodes.js`) rather than polling: that fires exactly on the events which
+ * `nodes/window/anchoring.js`) rather than polling: that fires exactly on the events which
  * can actually move the rect — a layout pass and a fresh `_screenOrigin` —
  * so a still trigger costs nothing and a moved one is caught the same frame.
  * `getOptions` is read fresh through a ref on every notification, so callers
@@ -64,7 +64,7 @@ function sameAnchorRect(a, b) {
  * it floating over content it no longer belongs to, detached from anything
  * the user can see it points at. So once the trigger is entirely past a
  * clipping ancestor's own bounds or past the owner window itself
- * (`Node._offscreen()`, the same check paint culling uses), tracking calls
+ * (`Node._offscreen()`, paint culling's check less its slop), tracking calls
  * `onOutOfView` instead of measuring — closing the popup, or hiding it, is
  * the caller's call — and does not resume until re-opened. With no
  * `onOutOfView` this just stops updating rather than snapping to a rect
@@ -133,7 +133,7 @@ export function useAnchorTracking(
  * with it, so the first click anywhere goes to dismissing it.
  *
  * The window manager's own focus, then, rather than anything in the tree:
- * `WindowNode.onWindowFocusChange` (nodes.js), which the event manager
+ * `WindowNode.onWindowFocusChange` (nodes/window/window.js), which the event manager
  * notifies from the same place it suspends the caret.
  */
 export function useDismissOnWindowBlur(ref, active, onDismiss) {

package/src/components/native.js

@@ -17,7 +17,7 @@
 // `native={false}` (the widgets keep today's drawn rendering everywhere the
 // bezel is off, so custom-designed apps lose nothing).
 
-import React, { useCallback } from 'react';
+import React, { useCallback, useRef } from 'react';
 import { useAppOrNull } from '../appcontext.js';
 import { useTheme } from './theme.js';
 
@@ -252,18 +252,23 @@ export function Bezel({
   if (value !== undefined) params.value = value;
   const sig = JSON.stringify(params);
   const store = app?.nativeBezels;
+  // What this canvas drew last, drawn again while a worker's store is still
+  // drawing the next one (src/cocoa/bezels.js, "On a worker"): the old
+  // state for a frame reads better than no control at all.
+  const last = useRef(null);
   // Keyed on the parameter signature so an unchanged bezel keeps its
   // `onDraw` identity — CanvasNode invalidates when the closure changes,
   // and a Button re-rendered by its parent must not repaint its bezel.
   const onDraw = useCallback(
     (ctx, info) => {
       if (!store || !info.width || !info.height) return;
-      const bezel = store.get(
-        JSON.parse(sig),
-        info.width,
-        info.height,
-        info.scale,
-      );
+      const node = info.node;
+      const bezel =
+        store.get(JSON.parse(sig), info.width, info.height, info.scale, () => {
+          if (!node.destroyed) node.invalidate();
+        }) ?? last.current;
+      if (!bezel) return;
+      last.current = bezel;
       ctx.drawImage(
         { _surfaceHandle: bezel.surface },
         bezel.sx,

package/src/components/theme.js

@@ -183,7 +183,7 @@ function planted(children, theme, style) {
  *
  * **With no provider it is the desktop's**, and this re-renders when the
  * desktop changes, which is what makes a react-x11 app that says nothing
- * about colour go dark on a dark desktop. `node.theme` in `nodes.js` answers
+ * about colour go dark on a dark desktop. `node.theme` in `nodes/cascade.js` answers
  * the same question for the other route.
  *
  * Identity matters: widgets plant what this returns on their own root node,
@@ -368,7 +368,7 @@ export const capBand = (fontSize) => Math.round(fontSize * 0.72);
  *
  * `undefined` for the width when off, never `0`: a node with no
  * `outlineWidth` of its own is one core can leave out of the widened damage
- * rects entirely (`_outlineExtent`, src/nodes.js), and `0` is the documented
+ * rects entirely (`_outlineExtent`, src/nodes/boxpaint.js), and `0` is the documented
  * way to opt *out* of a ring the node would otherwise get.
  */
 export const focusRingStyle = (theme, on) =>

package/src/debug.js

@@ -243,7 +243,7 @@ function stackForSeq(X, seq16) {
 
 /**
  * Every 2d context this app paints windows through. react-x11 caches one
- * per window node (nodes.js), which is where ntk keeps `shapeStats`.
+ * per window node (`WindowNode`), which is where ntk keeps `shapeStats`.
  */
 function contextsOf(app) {
   return (app?._rootChildren ?? [])

package/src/decorations.js

@@ -1,6 +1,6 @@
 // The two decorations that are not a colour: the gradient behind a box
 // (`backgroundImage`) and the shadow under it (`boxShadow`). Both are pure
-// here — strings in, numbers out — so the renderer half in `nodes.js` is
+// here — strings in, numbers out — so the renderer half in `nodes/boxpaint.js` is
 // only geometry and compositing, and the parsing can be tested without a
 // server (issue #345).
 //

package/src/editmenu.js

@@ -6,7 +6,7 @@
  * wiring at all. That rules out building it from the `Menu` components,
  * which live a layer above the nodes and cannot be mounted from one — so
  * the rows are measured and drawn here, and a node hangs them in a
- * `<popup>` (`openEditMenu`, nodes.js, which is the public seam).
+ * `<popup>` (`openEditMenu`, nodes/editmenupopup.js, which is the public seam).
  *
  * Deliberately free of node imports: this takes plain data, a measuring
  * function and a 2d context. It can be tested without a tree, and falls
@@ -64,7 +64,7 @@ export function editMenuColors(theme) {
 /**
  * The rows, in the standard order, each enabled exactly when it would do
  * something — the whole of the menu's policy, as a pure function of the
- * verbs a target offers (`openEditMenu`, nodes.js).
+ * verbs a target offers (`openEditMenu`, nodes/editmenupopup.js).
  *
  * **A verb that was not handed over is a row that is not there**, rather
  * than a greyed one. It was motivated by `<textinput sensitive>`, where a

package/src/errors.js

@@ -59,6 +59,35 @@ export function reportHandlerError(node, handler, error) {
   markFailed();
 }
 
+/**
+ * A throw from a layout or a placement (docs/extending.md) — code that runs
+ * inside a frame, where no error boundary is on the stack either. Reported
+ * the way a handler's throw is, `onUncaughtError` included, and the frame
+ * carries on with the fallback `consequence` names: one bad algorithm must
+ * not stop the window from painting.
+ */
+export function reportLayoutError(node, what, error, consequence) {
+  const element = node?.kind ? `<${node.kind}>` : '(unknown)';
+  const owner = ownerName(node);
+  const custom = node?.app && perContainer.get(node.app);
+  if (custom) {
+    custom(error, {
+      componentStack: owner ? `\n    in ${owner}` : undefined,
+      element,
+      handler: what,
+      node,
+    });
+    return;
+  }
+  console.error(
+    `react-x11: ${what} on ${element}${owner ? ` in ${owner}` : ''} threw. ` +
+      'It ran inside a frame rather than a render, so no error boundary ' +
+      `could catch it. ${consequence}.`,
+    error,
+  );
+  markFailed();
+}
+
 /**
  * `REACT_X11_STRICT_TOKENS=1` makes a `$token` the theme does not define
  * fatal again, for a build that would rather stop than paint something
@@ -104,6 +133,23 @@ export function reportStyleError(
   markFailed();
 }
 
+/**
+ * A style that asks for something that is not there — a layout or a
+ * placement nobody registered, an option of the wrong type. Reported and
+ * carried on from, once per node and message, the way an unknown token is;
+ * with no strict switch, because the fallback it names is a real one and
+ * not a property silently dropped.
+ */
+export function reportStyleProblem(node, message, consequence) {
+  const seen = reportedStyleErrors.get(node);
+  if (seen?.has(message)) return;
+  if (seen) seen.add(message);
+  else reportedStyleErrors.set(node, new Set([message]));
+  const owner = ownerName(node);
+  console.error(`${message}${owner ? ` — in ${owner}` : ''}. ${consequence}.`);
+  markFailed();
+}
+
 /** Wrap a call to user code so a throw is reported instead of escaping. */
 export function callHandler(node, handler, fn, ev) {
   try {