ntk 6.4.0 → 6.6.0

package/lib/app.js

@@ -146,6 +146,26 @@ export default class App {
     return chooseGLXConfig(this, spec);
   }
 
+  /**
+   * Find a 32-bit TrueColor visual with an alpha channel, for per-pixel
+   * transparent windows (ARGB). Returns `{ visual, depth: 32 }` — pass
+   * these to `createWindow()` together with `backgroundPixel: 0`. Returns
+   * `null` when the server has no such visual (XQuartz, for example).
+   *
+   * The compositor blends the window's alpha channel automatically; no
+   * Composite extension calls or EWMH properties are needed from the client.
+   * Without a running compositor, transparent regions render black.
+   */
+  findArgbVisual(screen = 0) {
+    const depths = this.display.screen[screen].depths;
+    const visuals = depths?.[32];
+    if (!visuals) return null;
+    for (const [id, visual] of Object.entries(visuals)) {
+      if (visual.class === 4) return { visual: Number(id), depth: 32 };
+    }
+    return null;
+  }
+
   rootWindow(screen = 0) {
     return new Window(this, { id: this.display.screen[screen].root });
   }

package/lib/builtin.js

@@ -0,0 +1,47 @@
+// Reach a Node builtin from ESM across Node versions.
+//
+// `process.getBuiltinModule(id)` is the browser-safe accessor — the string is
+// a function argument, so no bundler treats it as a module specifier — but it
+// only exists on Node >= 20.16. ntk's floor is lower (Node 18.19, for
+// react-x11), and there is no browser-safe, synchronous way to reach a builtin
+// from ESM on an older Node: `getBuiltinModule` is the API that was added to
+// fill exactly that gap. So where it is absent we fall back to `createRequire`.
+//
+// The `node:module` import below is a real specifier and the one place in lib/
+// allowed to statically import a builtin other than node:events — a sanctioned
+// exception in test/packaging.test.js, scoped to this file. A *browser* bundle
+// of the text stack must stub this one specifier, but the fallback that uses it
+// never runs in a browser (guarded on process.versions.node) and ntk ships no
+// browser build. It is not a top-level await, so the CJS/SEA bundle path (see
+// docs/packaging.md) is unaffected.
+import { createRequire } from 'node:module';
+
+let _require;
+
+// One createRequire bound to ntk, made lazily. Builtins ('node:*') resolve
+// regardless of the base URL, so this also serves callers that resolve a
+// package in ntk's own dependency graph (e.g. KaTeX's font directory).
+function req() {
+  return (_require ??= createRequire(import.meta.url));
+}
+
+/**
+ * `process.getBuiltinModule(id)` with a Node-18 fallback.
+ * @param {string} id e.g. 'node:child_process'
+ * @returns the builtin module, or `undefined` outside Node (a browser
+ *   embedding of the text stack — supply a custom FontSource / callback there).
+ */
+export function builtin(id) {
+  const p = globalThis.process;
+  if (!p?.versions?.node) return undefined;
+  if (typeof p.getBuiltinModule === 'function') return p.getBuiltinModule(id);
+  return req()(id);
+}
+
+/**
+ * A `require` for resolving packages in ntk's dependency graph.
+ * @returns {NodeRequire|null} `null` outside Node.
+ */
+export function nodeRequire() {
+  return globalThis.process?.versions?.node ? req() : null;
+}

package/lib/fontconfig.js

@@ -1,8 +1,10 @@
-// node:child_process is fetched lazily (not via static import) so that
-// browser bundles of the package never try to resolve it; in non-node
+// node:child_process is fetched lazily (via builtin(), not a static import) so
+// that browser bundles of the package never try to resolve it; in non-node
 // environments use a custom FontSource instead (see text/fontsource.js).
+import { builtin } from './builtin.js';
+
 function childProcess() {
-  return globalThis.process?.getBuiltinModule?.('node:child_process');
+  return builtin('node:child_process');
 }
 
 function execFileSync(...args) {

package/lib/image.js

@@ -1,6 +1,7 @@
 import jpeg from 'jpeg-js';
 import { PNG } from 'pngjs';
 
+import { builtin } from './builtin.js';
 import { fromStraightRgba, pixelLayout } from './imagedata.js';
 import Picture from './picture.js';
 
@@ -126,7 +127,7 @@ export function decodeImage(buffer) {
 export async function loadImage(source) {
   if (typeof source === 'string' || source instanceof URL) {
     // lazy builtin lookup: browser bundles must not depend on node:fs
-    const fsp = globalThis.process?.getBuiltinModule?.('node:fs/promises');
+    const fsp = builtin('node:fs/promises');
     if (!fsp) {
       throw new Error('loadImage: file paths need node — pass the encoded bytes instead');
     }

package/lib/renderingcontext_2d.js

@@ -284,6 +284,9 @@ class RenderingContext2d {
         : depth === 8
           ? this.Render.a8
           : this.Render.rgb24;
+    // Does the target have a real alpha channel? Only then is "transparent"
+    // a colour it can hold, which is what clearRect turns on.
+    this._hasAlpha = depth === 32;
     this.picture = new Picture(this.window.app, {
       drawable: target,
       format,
@@ -325,14 +328,14 @@ class RenderingContext2d {
 
     this._clips = [];
     this._dropMasks();
-    for (const gc of [this._gc, this._fillMaskGC]) {
+    for (const gc of [this._gc, this._fillMaskGC, this._clipMaskGC]) {
       if (!gc) continue;
       safeRelease(this.X, () => {
         this.X.FreeGC(gc);
         this.X.ReleaseID(gc);
       });
     }
-    this._gc = this._fillMaskGC = null;
+    this._gc = this._fillMaskGC = this._clipMaskGC = null;
     this._gcs.length = 0;
 
     this._backgroundPicture = this._glyphSource = null;
@@ -1363,12 +1366,19 @@ class RenderingContext2d {
   // ------------------------------------------------------------------
   // drawing
 
+  // Clearing means "back to nothing", and what nothing looks like depends on
+  // whether the target can hold transparency. A depth-32 ARGB window gets
+  // transparent black, the canvas spec's answer, and the compositor shows
+  // whatever is behind it. Anything else has no alpha channel to write, so
+  // clearing stays opaque white — the paper an opaque window starts from,
+  // and what every caller predating ARGB windows expects.
   clearRect(x, y, w, h) {
+    const alpha = this._hasAlpha;
     if (matIsIdentity(this._m) && !this._clips.length) {
       this.Render.FillRectangles(
         this.Render.PictOp.Src,
         this.picture.id,
-        [1, 1, 1, 1],
+        alpha ? [0, 0, 0, 0] : [1, 1, 1, 1],
         [x, y, w, h],
       );
       this._markDirty();
@@ -1376,11 +1386,18 @@ class RenderingContext2d {
     }
     const tmp = new Path2D();
     tmp.rect(x, y, w, h);
-    // clear = opaque white, ignoring alpha and the composite op (but
-    // honoring the clip), matching the identity fast path above
+    // Transformed or clipped, so the rect is a polygon and the erase has to
+    // run through the coverage mask. OutReverse is `dst OUT src`: against an
+    // opaque source it scales the destination by 1 - coverage, erasing to
+    // transparent with an antialiased edge. PictOpSrc would take the whole
+    // bounding box with it, coverage or not. Opaque targets keep the old
+    // behaviour: paint white over the shape, ignoring alpha and the
+    // composite op but honoring the clip, matching the fast path above.
     this._fillPolys(flattenPath(tmp._cmds, this._m), "nonzero", {
-      src: this.createSolidPicture(1, 1, 1, 1),
-      op: this.Render.PictOp.Over,
+      src: alpha
+        ? this.createSolidPicture(0, 0, 0, 1)
+        : this.createSolidPicture(1, 1, 1, 1),
+      op: alpha ? this.Render.PictOp.OutReverse : this.Render.PictOp.Over,
       alpha: 1,
     });
   }
@@ -1644,13 +1661,15 @@ class RenderingContext2d {
       drawable: tmpPixmap,
       format: R.a8,
     });
-    R.FillRectangles(
-      R.PictOp.Src,
-      tmpMask.id,
-      [0, 0, 0, 0],
-      [0, 0, bb.w, bb.h],
-    );
-    this._rasterizePolys(tmpMask, entry.polys, entry.rule, -bb.x, -bb.y);
+    if (!this._uploadClipCoverage(tmpPixmap, entry, bb)) {
+      R.FillRectangles(
+        R.PictOp.Src,
+        tmpMask.id,
+        [0, 0, 0, 0],
+        [0, 0, bb.w, bb.h],
+      );
+      this._rasterizePolys(tmpMask, entry.polys, entry.rule, -bb.x, -bb.y);
+    }
     R.Composite(
       op,
       tmpMask.id,
@@ -1669,6 +1688,96 @@ class RenderingContext2d {
     tmpPixmap.destroy();
   }
 
+  /**
+   * The clip-mask twin of `_uploadCoverage`: rasterize one clip entry here
+   * and PutImage the coverage into the bbox temp, instead of asking the
+   * server for trapezoids. Returns false — caller falls back to AddTraps —
+   * with no rasterizer, when the policy routes this shape to the server, or
+   * when the rasterizer declines.
+   *
+   * Without this the routing was only half applied. `_uploadCoverage` covers
+   * fills and strokes, so an app that set `rasterPolicy` to keep every
+   * drawing local still emitted an AddTraps per non-rectangular clip, and on
+   * glamor those were the whole remaining cost: a wall of 48 rounded cards
+   * spent 12 AddTraps a frame on clips alone (react-x11#199), 116ms of
+   * server drain per frame, with no policy able to reach them.
+   *
+   * PutImage writes Src, so it replaces the temp's clear as well.
+   */
+  _uploadClipCoverage(tmpPixmap, entry, bb) {
+    const rasterizer = this.window.app.rasterizer;
+    if (!rasterizer) return false;
+    const flat = [];
+    let edges = 0;
+    for (const p of entry.polys) {
+      if (p.pts.length < 6) continue;
+      flat.push(p.pts);
+      edges += p.pts.length / 2;
+    }
+    if (!flat.length) return false;
+    if (
+      routeRaster(bb.w, bb.h, edges, this.window.app.rasterPolicy) !== "local"
+    ) {
+      return false;
+    }
+
+    const coverage = rasterizer.rasterize({
+      polys: flat,
+      rule: entry.rule,
+      dx: -bb.x,
+      dy: -bb.y,
+      width: bb.w,
+      height: bb.h,
+    });
+    if (!coverage) return false;
+
+    // scanlines padded to 4 bytes, as in _uploadCoverage — and as there, a
+    // width that is already a multiple of 4 goes out as a view over the
+    // rasterizer's own bytes with no copy
+    const stride = (bb.w + 3) & ~3;
+    let data;
+    if (stride === bb.w) {
+      data = Buffer.isBuffer(coverage)
+        ? coverage
+        : Buffer.from(coverage.buffer, coverage.byteOffset, coverage.length);
+    } else {
+      data = Buffer.alloc(stride * bb.h);
+      for (let y = 0; y < bb.h; ++y) {
+        Buffer.from(coverage.buffer, coverage.byteOffset + y * bb.w, bb.w).copy(
+          data,
+          y * stride,
+        );
+      }
+    }
+    this.X.PutImage(
+      2,
+      tmpPixmap.id,
+      this._clipGC(tmpPixmap),
+      bb.w,
+      bb.h,
+      0,
+      0,
+      0,
+      8,
+      data,
+    );
+    return true;
+  }
+
+  /**
+   * GC for uploading coverage into a clip temp. Created against the first
+   * temp and kept: every one of them is depth 8 on the same root, which is
+   * all a GC binds to, and the temps themselves come and go per clip entry.
+   */
+  _clipGC(tmpPixmap) {
+    if (!this._clipMaskGC) {
+      this._clipMaskGC = this.X.AllocID();
+      this._gcs.push(this._clipMaskGC);
+      this.X.CreateGC(this._clipMaskGC, tmpPixmap.id);
+    }
+    return this._clipMaskGC;
+  }
+
   _rebuildClipMask() {
     // The stack changed shape (restore, resize): drop the mask rather than
     // rebuild it eagerly. A stack that went back to rectangles never needs

package/lib/text/fontsource.js

@@ -30,10 +30,11 @@
 // fontconfig: ntk ships no fonts, so the app has to hand over the ones it
 // ships, and the spec is the short way to say so.
 //
-// node:fs is fetched through `getBuiltinModule` inside the path branch rather
-// than imported, because this file is the one the browser bundle keeps — its
-// whole purpose is running the text stack without a filesystem. Do not turn
-// that into a static import (test/packaging.test.js fails if you do).
+// node:fs is fetched lazily through builtin() inside the path branch, never a
+// direct static import, because this file is the one the browser bundle keeps
+// — its whole purpose is running the text stack without a filesystem. See
+// builtin.js for how the lazy lookup stays version-tolerant.
+import { builtin } from '../builtin.js';
 import { charsetHas, matchSortedSync, noFontsError, prewarm, supported } from '../fontconfig.js';
 import Font from './font.js';
 
@@ -267,7 +268,7 @@ const ACCEPTED =
   'docs/fonts.md';
 
 function fs() {
-  const mod = globalThis.process?.getBuiltinModule?.('node:fs');
+  const mod = builtin('node:fs');
   if (!mod) {
     throw new Error(
       'ntk: a font path can only be read in node. In a browser, fetch the font ' +

package/lib/widgets/htmlview.js

@@ -1,6 +1,7 @@
 import { selectAll } from 'css-select';
 import { textContent } from 'domutils';
 import { parseDocument } from 'htmlparser2';
+import { builtin } from '../builtin.js';
 import Yoga from '../yoga.js';
 
 import { decodeImage, Image } from '../image.js';
@@ -467,15 +468,14 @@ export default class HtmlView {
     // default policy: local files, only relative to an explicit baseUrl.
     // node builtins are fetched lazily — in environments without them
     // (browser bundles) pass a `loadResource` callback instead.
-    const getBuiltin = globalThis.process?.getBuiltinModule;
-    const fs = getBuiltin?.call(process, 'node:fs');
+    const fs = builtin('node:fs');
     if (!fs || !this.baseUrl) return null;
     let base = this.baseUrl;
     if (typeof base === 'string' && !/^[a-z][a-z0-9+.-]*:/i.test(base)) {
       // filesystem path; point at the directory itself when given one
       let p = base;
       if (!/[/\\]$/.test(p) && fs.existsSync(p) && fs.statSync(p).isDirectory()) p += '/';
-      base = getBuiltin.call(process, 'node:url').pathToFileURL(p);
+      base = builtin('node:url').pathToFileURL(p);
     }
     const url = new URL(src, base);
     if (url.protocol !== 'file:') return null;

package/lib/widgets/tex.js

@@ -21,14 +21,11 @@
 import { parseSvgPath } from '../path.js';
 import { flatten } from '../rasterize.js';
 import { trapezoidize } from '../trapezoid.js';
+import { builtin, nodeRequire } from '../builtin.js';
 import Font from '../text/font.js';
 
-// node builtins are fetched lazily so browser bundles never resolve them;
-// there, inject the assets with configureTex() instead.
-function nodeRequire() {
-  const mod = globalThis.process?.getBuiltinModule?.('node:module');
-  return mod ? mod.createRequire(import.meta.url) : null;
-}
+// node builtins are fetched lazily (nodeRequire/builtin) so browser bundles
+// never resolve them; there, inject the assets with configureTex() instead.
 
 // katex is sizable — load it on first formula, not on package import
 let katex = null;
@@ -82,8 +79,8 @@ function katexFontFiles() {
           'TeX rendering: KaTeX fonts cannot be read here — inject them with configureTex({ fonts })'
         );
       }
-      const { readdirSync } = process.getBuiltinModule('node:fs');
-      const { dirname, join } = process.getBuiltinModule('node:path');
+      const { readdirSync } = builtin('node:fs');
+      const { dirname, join } = builtin('node:path');
       fontDir = join(dirname(require.resolve('katex/package.json')), 'dist', 'fonts');
       fontFiles = new Set(readdirSync(fontDir).filter((f) => f.endsWith('.ttf')));
     }

package/lib/window.js

@@ -1,5 +1,6 @@
 import x11 from 'x11';
 
+import { builtin } from './builtin.js';
 import { safeRelease } from './cleanup.js';
 import Drawable from './drawable.js';
 import { packIcons, unpackIcons } from './imagedata.js';
@@ -696,27 +697,25 @@ export default class Window extends Drawable {
   }
 
   // grow-only backing pixmap (re)allocation, with headroom (see
-  // BACKING_GRANULARITY); new area is cleared to white
+  // BACKING_GRANULARITY); new area is cleared to the window's background
+  // (white for opaque windows, fully transparent for depth-32 ARGB ones)
   _allocBacking(w, h) {
     const cur = this._backing;
     if (cur && cur.width >= w && cur.height >= h) return;
     const roundUp = (v) => Math.ceil(v / BACKING_GRANULARITY) * BACKING_GRANULARITY;
     const newW = roundUp(Math.max(w, cur ? cur.width : 0));
     const newH = roundUp(Math.max(h, cur ? cur.height : 0));
+    const depth = this.depth || this.display.screen[0].root_depth;
     const pixmap = new Pixmap(this.app, {
       parent: this,
       width: newW,
       height: newH,
-      // must match the window's depth: CopyArea between drawables of
-      // different depths is a BadMatch
-      depth: this.depth || this.display.screen[0].root_depth
+      depth
     });
     if (!this._clearGc) {
-      // reusable across reallocs: a GC is valid for any drawable of the
-      // same screen and depth, so one outlives every backing pixmap
       this._clearGc = this.X.AllocID();
       this.X.CreateGC(this._clearGc, pixmap.id, {
-        foreground: this.display.screen[0].white_pixel,
+        foreground: depth === 32 ? 0 : this.display.screen[0].white_pixel,
         graphicsExposures: 0
       });
     }
@@ -1086,29 +1085,35 @@ export default class Window extends Drawable {
   }
 
   /**
-   * Whether the fence for the last frame is still unanswered — the server has
-   * not yet confirmed it consumed everything that frame drew.
+   * Whether a blit this window already owes is still waiting to go out —
+   * because the fence for the last frame is unanswered, or because a present
+   * is deferred behind the minimum inter-blit interval.
    *
    * The one bit of frame-clock state worth publishing, because it is the
    * difference between the two ways a toolkit can answer a discrete input.
    * Drawing the response inside the event handler costs a frame less latency:
    * the blit goes out with the handler's own requests (see the `_present()`
    * at the end of the event dispatch) instead of waiting for the next paced
-   * frame — provided the last blit is at least `frameInterval` old, which is
-   * what a discrete input arriving out of the blue always is. Drawing it while
-   * a frame is in flight costs a frame's *work* for nothing: the present is
-   * deferred until the ack and coalesces with the one already pending, so only
-   * the last paint is ever seen. So `false`
+   * frame. Drawing it when a blit is already queued costs a frame's *work* for
+   * nothing: the paint lands in the same backing store and coalesces into the
+   * present already pending, so only the last one is ever seen. So `false`
    * means "draw it now", `true` means "leave it to the frame clock" — which
    * is how a burst of discrete events (a spun wheel) paints its first notch
    * immediately and folds the rest into one catch-up frame.
    *
-   * Always `false` under `frameSync: false`: no fence is ever sent, so there
-   * is nothing to wait for, and a caller gating on this gets the unpaced
-   * behaviour that option asks for.
+   * Both gates have to be reported, not just the fence. The fence is the one
+   * that bites on a slow connection. The minimum inter-blit interval (#195) is
+   * the one that bites on a fast local server, where the fence for a notch is
+   * answered well before the next notch is even read, and what actually holds
+   * the burst back is the interval. Reporting only the fence there answers
+   * "draw it now" to every notch — the precise work this gate exists to skip.
+   *
+   * `false` whenever nothing gates blits at all: `frameSync: false` sends no
+   * fence and `frameInterval: 0` keeps no interval, so a caller who asked for
+   * both gets the unpaced behaviour those options ask for.
    */
   frameInFlight() {
-    return this._frame.inFlight;
+    return this._frame.inFlight || this._presentPending;
   }
 
   _present() {
@@ -1911,7 +1916,7 @@ export default class Window extends Drawable {
   /** os.hostname(), looked up once, and absent in a browser bundle. */
   static _hostname() {
     if (Window._cachedHostname === undefined) {
-      const os = globalThis.process?.getBuiltinModule?.('node:os');
+      const os = builtin('node:os');
       Window._cachedHostname = os?.hostname?.() ?? null;
     }
     return Window._cachedHostname;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "6.4.0",
+  "version": "6.6.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "lib"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=18.19.0"
   },
   "dependencies": {
     "bidi-js": "^1.0.3",