ntk 5.3.0 → 5.4.0

package/lib/app.js

@@ -13,8 +13,10 @@ import Window from './window.js';
 export default class App {
   /**
    * @param {object} display node-x11 display
-   * @param {object} [options] environment hooks: { fontSource (see
-   *   text/fontsource.js), rasterizer and rasterPolicy (see rasterize.js),
+   * @param {object} [options] environment hooks: { fontSource — a FontSource
+   *   or a font spec (see text/fontsource.js); `createClient` resolves a spec
+   *   before it gets here, so a hand-built App may pass either —
+   *   rasterizer and rasterPolicy (see rasterize.js),
    *   glxVisual (visual id for getContext('opengl') instead of querying the
    *   server for one) }
    */

package/lib/clipboard.js

@@ -114,6 +114,59 @@ export default class Clipboard {
     }
   }
 
+  /**
+   * Give a selection back: stop owning it, and stop answering for it.
+   *
+   *   await app.clipboard.clear();                 // CLIPBOARD
+   *   await app.clipboard.clear('XdndSelection');  // at the end of a drag
+   *
+   * The counterpart to `write()`, which otherwise holds a selection until
+   * another client takes it or the app exits. Two things want this: a drag
+   * source, which should stop offering its payload once the drag is over
+   * (a stale offer answered later is exactly what XDND's "throw out
+   * extremely old data" rule is about), and apps that clear the clipboard
+   * on purpose — a password manager, say.
+   *
+   * Clearing a selection this app does not own does nothing, and in
+   * particular sends nothing: `SetSelectionOwner(None)` from a non-owner
+   * would take the selection away from whoever legitimately holds it.
+   *
+   * A transfer already in flight still completes — an INCR transfer keeps
+   * its own copy of the payload (ICCCM 2.7.2), the same as when another
+   * client takes the selection from us.
+   *
+   * @param {string} [selection] selection atom name, default 'CLIPBOARD'
+   * @returns {Promise<void>}
+   */
+  async clear(selection = 'CLIPBOARD') {
+    // nothing has ever been written, so nothing can be owned: answer
+    // without interning an atom or creating the helper window
+    if (!this._owned.size) return;
+    const sel = await this._atom(selection);
+    const entry = this._owned.get(sel);
+    if (!entry) return;
+    this._owned.delete(sel);
+    // ICCCM 2.3.1: release with the timestamp the selection was acquired
+    // with, not a fresh one. A SetSelectionOwner is ignored when its time is
+    // earlier than the selection's current last-change time, so the old
+    // stamp is what makes this lose to a client that has taken the selection
+    // since — where a fresh one would take it away from them.
+    this.X.SetSelectionOwner(0, sel, entry.time);
+    // The server answers the release with a SelectionClear addressed to the
+    // helper window; _onXEvent deletes an _owned entry that is already gone,
+    // which is harmless.
+    //
+    // GetSelectionOwner here is a barrier, not a check: requests are
+    // buffered (one socket write per frame) and it is a reply that forces
+    // the flush, so without it the release could still be sitting in our
+    // output buffer when the caller's next await resumes. Whoever owns the
+    // selection afterwards is not our business — we only promised to stop
+    // being the owner.
+    await new Promise((resolve, reject) =>
+      this.X.GetSelectionOwner(sel, (err) => (err ? reject(err) : resolve()))
+    );
+  }
+
   /**
    * Read the current text of a selection from whoever owns it.
    * Rejects when the selection has no owner, when the owner supports
@@ -121,14 +174,17 @@ export default class Clipboard {
    * (`timeout` ms, default 2000).
    *
    * @param {object} [options] { selection: 'CLIPBOARD' | 'PRIMARY' | ...,
-   *   timeout: ms to wait for the owner at each protocol step }
-   * @returns {Promise<string>}
+   *   timeout: ms to wait for the owner at each protocol step;
+   *   target: one named target, returned as bytes, instead of text;
+   *   time: the server timestamp of the event that asked for the paste
+   *   (ICCCM 2.4) — see `targets()` for why it is worth passing }
+   * @returns {Promise<string|Buffer>}
    */
-  read({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT, target } = {}) {
+  read({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT, target, time } = {}) {
     return this._serialize(() =>
       target === undefined
-        ? this._read(selection, timeout)
-        : this._readTarget(selection, target, timeout)
+        ? this._read(selection, timeout, time)
+        : this._readTarget(selection, target, timeout, time)
     );
   }
 
@@ -142,11 +198,18 @@ export default class Clipboard {
    * `TARGETS` cheaply, where guessing costs a failed conversion per guess.
    * Returns `[]` when nothing owns the selection.
    *
-   * @param {object} [options] { selection, timeout }
+   * `time` is the timestamp of the event that asked for the data. ICCCM 2.4
+   * says to pass it rather than CurrentTime, so that an owner which has
+   * since replaced its data can tell that the request is for the older
+   * value; XDND makes it binding, since a drop must convert with the
+   * timestamp from its `XdndDrop` message. Omitting it means CurrentTime,
+   * which every mainstream owner accepts and a strict one may not.
+   *
+   * @param {object} [options] { selection, timeout, time }
    * @returns {Promise<string[]>}
    */
-  targets({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT } = {}) {
-    return this._serialize(() => this._targets(selection, timeout));
+  targets({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT, time } = {}) {
+    return this._serialize(() => this._targets(selection, timeout, time));
   }
 
   /** Concurrent conversions would share the one transfer property on the
@@ -157,11 +220,11 @@ export default class Clipboard {
     return result;
   }
 
-  async _targets(selection, timeout) {
+  async _targets(selection, timeout, time) {
     await this._ensure();
     const sel = await this._atom(selection);
     const prop = this._transferProp;
-    const notify = await this._convert(sel, this._atoms.TARGETS, prop, selection, timeout);
+    const notify = await this._convert(sel, this._atoms.TARGETS, prop, selection, timeout, time);
     if (notify.property === 0) return [];
     const { data, format } = await this._fetchProperty(prop, selection, timeout);
     // an INCR reassembly reports no format, and a target list is far too
@@ -178,12 +241,12 @@ export default class Clipboard {
    * `write({ 'image/png': buf })` publishes, this is how another ntk app
    * gets it back.
    */
-  async _readTarget(selection, target, timeout) {
+  async _readTarget(selection, target, timeout, time) {
     await this._ensure();
     const sel = await this._atom(selection);
     const atom = await this._atom(target);
     const prop = this._transferProp;
-    const notify = await this._convert(sel, atom, prop, selection, timeout);
+    const notify = await this._convert(sel, atom, prop, selection, timeout, time);
     if (notify.property === 0) {
       const owner = await new Promise((resolve, reject) =>
         this.X.GetSelectionOwner(sel, (err, wid) => (err ? reject(err) : resolve(wid)))
@@ -204,17 +267,18 @@ export default class Clipboard {
     );
   }
 
-  async _read(selection, timeout) {
+  async _read(selection, timeout, time) {
     await this._ensure();
     const X = this.X;
     const sel = await this._atom(selection);
     const prop = this._transferProp;
 
-    let notify = await this._convert(sel, this._atoms.UTF8_STRING, prop, selection, timeout);
+    let notify = await this._convert(sel, this._atoms.UTF8_STRING, prop, selection, timeout, time);
     if (notify.property === 0) {
       // property None: no owner, or the owner refused UTF8_STRING (old
-      // Xt/Motif apps) — ask again for latin-1 STRING before giving up
-      notify = await this._convert(sel, X.atoms.STRING, prop, selection, timeout);
+      // Xt/Motif apps) — ask again for latin-1 STRING before giving up.
+      // Same timestamp: this is a retry of one paste, not a second one.
+      notify = await this._convert(sel, X.atoms.STRING, prop, selection, timeout, time);
     }
     if (notify.property === 0) {
       const owner = await new Promise((resolve, reject) =>
@@ -711,8 +775,11 @@ export default class Clipboard {
 
   // ---- INCR, requestor side ----
 
-  // ConvertSelection and wait for the owner's SelectionNotify answer
-  _convert(sel, target, prop, selectionName, timeout) {
+  // ConvertSelection and wait for the owner's SelectionNotify answer.
+  // `time` is the timestamp of the event that asked for the data; ICCCM 2.4
+  // says to send it rather than CurrentTime. Undefined coerces to 0, which
+  // is CurrentTime — the documented default for callers with no event.
+  _convert(sel, target, prop, selectionName, timeout, time) {
     return new Promise((resolve, reject) => {
       const X = this.X;
       const wid = this._window.id;
@@ -734,7 +801,7 @@ export default class Clipboard {
         X.removeListener('event', onEvent);
       };
       X.on('event', onEvent);
-      X.ConvertSelection(wid, sel, target, prop, 0);
+      X.ConvertSelection(wid, sel, target, prop, time >>> 0);
     });
   }
 

package/lib/fontconfig.js

@@ -4,13 +4,56 @@
 function execFileSync(...args) {
   const cp = globalThis.process?.getBuiltinModule?.('node:child_process');
   if (!cp) {
-    throw new Error(
-      'fontconfig matching needs node (fc-match CLI); in this environment pass a custom fontSource — see docs/fonts.md'
+    throw noFontsError(
+      'fontconfig matching needs node (the fc-match CLI) and this is not a node environment'
     );
   }
   return cp.execFileSync(...args);
 }
 
+const DOCS = 'https://github.com/sidorares/ntk/blob/master/docs/fonts.md#environments-without-fontconfig';
+
+/**
+ * The one error for "this environment has nothing to render text with" —
+ * fc-match missing, fc-match unhappy, fc-match matching nothing parseable, or
+ * a StaticFontSource with no faces.
+ *
+ * It exists because of where it lands. Font lookup is lazy, so the failure
+ * surfaces inside the first text layout with no hint that fonts are involved:
+ * a fontconfig-less container used to report exactly `spawnSync fc-match
+ * ENOENT` from deep inside shapeText, which reads as "ntk is broken in
+ * Docker". The message is long on purpose — it is thrown once, at a reader
+ * who does not yet know the subject.
+ *
+ * `code` is the load-bearing part rather than decoration: FontManager's
+ * fallbackFor distinguishes "this environment has no fonts" (degrade to
+ * .notdef) from "your custom source threw" (propagate), and it gives a host
+ * renderer something to branch on without matching message text.
+ *
+ * @param {string} reason first line — what specifically was missing
+ * @param {Error} [cause] the underlying failure, preserved for debugging
+ */
+export function noFontsError(reason, cause) {
+  const err = new Error(
+    `ntk: no fonts available — ${reason}.\n` +
+      '\n' +
+      'ntk ships no font files, so a slim/distroless container, a single-executable\n' +
+      'build, a kiosk image or a CI box without font packages has to supply them:\n' +
+      '\n' +
+      "    createClient({ fontSource: '/app/fonts' })   // a directory of .ttf/.otf files\n" +
+      '    createClient({ fontSource: [bytes] })        // font bytes — no filesystem needed\n' +
+      '\n' +
+      'Where a package manager is available, installing fontconfig plus a font package\n' +
+      'is simpler: Debian/Ubuntu `apt-get install -y --no-install-recommends fontconfig\n' +
+      'fonts-dejavu-core`; Alpine `apk add fontconfig font-dejavu`.\n' +
+      '\n' +
+      DOCS,
+    cause ? { cause } : undefined
+  );
+  err.code = 'ERR_NTK_NO_FONTS';
+  return err;
+}
+
 // css weight -> fontconfig weight constants
 const cssToFcWeight = {
   100: 0, // thin
@@ -24,11 +67,32 @@ const cssToFcWeight = {
   900: 210 // black
 };
 
-// formats fontkit can parse
-const supported = /\.(ttf|otf|woff|woff2|ttc|dfont)$/i;
+// formats fontkit can parse. Exported so the font-spec resolver filters a
+// directory listing by exactly the same rule fc-match output is filtered by —
+// bitmap .pcf/.bdf fonts are the common near-miss.
+export const supported = /\.(ttf|otf|woff|woff2|ttc|dfont)$/i;
 
 const sortedCache = new Map();
 
+// Why fc-match could not be used, remembered so a render loop that catches
+// the error does not respawn a missing binary every frame. The reason string
+// is cached rather than the Error, so each throw still carries its own stack.
+// A process that somehow gains fontconfig mid-run will not notice; nobody
+// installs fontconfig into a running process.
+let unavailable = null;
+
+/**
+ * Did the spawn itself fail, as opposed to fc-match running and being
+ * unhappy? `status` is null only when the child never ran, and these are the
+ * codes that mean "no usable binary at this name" rather than a transient
+ * failure worth reporting verbatim.
+ */
+function isSpawnFailure(err) {
+  return (
+    err.status == null && ['ENOENT', 'EACCES', 'EPERM', 'ENOTDIR'].includes(err.code)
+  );
+}
+
 function patternFor({ family, weight, style }) {
   let fc = family || 'sans-serif';
   const fcWeight = normalizeWeight(weight);
@@ -51,12 +115,31 @@ export function matchSortedSync(pattern) {
   const fc = patternFor(pattern);
   let list = sortedCache.get(fc);
   if (list) return list;
+  if (unavailable) throw noFontsError(unavailable);
+
+  let out;
+  try {
+    out = execFileSync(
+      'fc-match',
+      ['-s', '--format', '%{file}\t%{postscriptname}\t%{charset}\n', fc],
+      { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }
+    );
+  } catch (err) {
+    if (err.code === 'ERR_NTK_NO_FONTS') throw err; // no child_process at all
+    if (isSpawnFailure(err)) {
+      unavailable = 'the fc-match CLI (fontconfig) is not installed here';
+      throw noFontsError(unavailable, err);
+    }
+    if (err.status != null) {
+      // fontconfig is installed and said no — an image with fontconfig but no
+      // font package answers "No fonts installed on the system" and exits 1.
+      // Not memoized: unlike a missing binary this can depend on the pattern.
+      const stderr = String(err.stderr || '').trim().split('\n')[0];
+      throw noFontsError(`fc-match exited ${err.status}${stderr ? `: ${stderr}` : ''}`, err);
+    }
+    throw err;
+  }
 
-  const out = execFileSync(
-    'fc-match',
-    ['-s', '--format', '%{file}\t%{postscriptname}\t%{charset}\n', fc],
-    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }
-  );
   list = [];
   for (const line of out.split('\n')) {
     const [path, postscriptName, charset] = line.split('\t');
@@ -65,7 +148,10 @@ export function matchSortedSync(pattern) {
     }
   }
   if (list.length === 0) {
-    throw new Error(`No usable font found for pattern "${fc}" (need .ttf/.otf/.ttc)`);
+    throw noFontsError(
+      `fontconfig matched no font ntk can parse for "${fc}" (needs ` +
+        '.ttf/.otf/.woff/.woff2/.ttc/.dfont — bitmap .pcf/.bdf fonts are not usable)'
+    );
   }
   sortedCache.set(fc, list);
   return list;
@@ -74,8 +160,9 @@ export function matchSortedSync(pattern) {
 /**
  * Resolve a font pattern ({family, weight, style}) to the best matching font
  * file. Returns { path, postscriptName } or throws if nothing suitable is
- * installed. Requires the fc-match CLI (fontconfig), present on any system
- * running X11.
+ * installed. Requires the fc-match CLI (fontconfig) — usual on a Linux
+ * desktop, absent from slim containers and from stock macOS. Where it is
+ * missing, hand ntk the fonts instead (see docs/fonts.md).
  */
 export function listFontsSync(pattern) {
   const [best] = matchSortedSync(pattern);

package/lib/image.js

@@ -51,8 +51,9 @@ export class Image {
       this.height
     );
 
-    // node-x11 has no FreeGC — share one upload GC per app (valid for any
-    // depth-32 drawable on the screen)
+    // One upload GC per app: a GC is valid for any depth-32 drawable on the
+    // screen, so sharing is cheaper than creating and freeing one per image.
+    // It outlives every Image and is released with the connection.
     let gc = app._imageUploadGC;
     if (!gc) {
       gc = app._imageUploadGC = X.AllocID();

package/lib/index.js

@@ -24,6 +24,7 @@ import FontManager from './text/fontmanager.js';
 import {
   FontconfigFontSource,
   StaticFontSource,
+  createFontSource,
   defaultFontSource,
   setDefaultFontSource
 } from './text/fontsource.js';
@@ -69,7 +70,11 @@ const DEFAULT_BUFFER_REQUESTS = { maxSize: 64 * 1024 };
  *
  * @param {object} [options] passed through to x11.createClient
  *   (e.g. { display: ':1' }); ntk additionally understands
- *   { fontSource } — a pluggable system-font lookup (see docs/fonts.md) —
+ *   { fontSource } — where fonts come from: a FontSource, `'system'` (the
+ *   default, fontconfig via fc-match), or a font spec naming the faces the
+ *   app itself ships — `'/app/fonts'`, `'./Inter.ttf'`, `[bytes]`,
+ *   `{ fonts, alias }` — which is what an environment without fontconfig
+ *   needs, since ntk ships no fonts (see docs/fonts.md) —
  *   { rasterizer, rasterPolicy } — where small fills and strokes are
  *   rasterized, and the thresholds for that choice (see docs/context-2d.md) —
  *   { glxVisual } — a visual id for getContext('opengl') to use instead of
@@ -95,6 +100,14 @@ export function createClient(options, callback) {
   const layout = loadLayout();
 
   const connecting = new Promise((resolve, reject) => {
+    // Resolve the font spec here rather than lazily in `app.fonts`, so a
+    // missing directory is a rejected connect instead of a surprise inside
+    // the first paint. Inside the executor so it rejects rather than throws
+    // synchronously, which keeps the legacy callback form working. The
+    // caller's options object is copied, never mutated.
+    const appOptions = options ? { ...options } : {};
+    if (appOptions.fontSource != null) appOptions.fontSource = createFontSource(appOptions.fontSource);
+
     x11.createClient(x11Options, (error, display) => {
       if (error) return reject(error);
 
@@ -130,7 +143,7 @@ export function createClient(options, callback) {
           });
           updateKeyboardMapping(display.min_keycode, display.max_keycode);
 
-          resolve(new App(display, options || {}));
+          resolve(new App(display, appOptions));
         });
       });
     });
@@ -174,6 +187,7 @@ export {
   FontManager,
   FontconfigFontSource,
   StaticFontSource,
+  createFontSource,
   defaultFontSource,
   setDefaultFontSource,
   CoverageAccumulator,

package/lib/renderingcontext_2d.js

@@ -27,6 +27,22 @@ import { trapezoidize } from './trapezoid.js';
 
 const DEFAULT_FONT = '20px sans-serif';
 
+/**
+ * Fallback for a context dropped without `destroy()`, matching Pixmap,
+ * Picture and GlyphSet. Only the GCs are freed here: everything else a
+ * context owns is a Pixmap or a Picture, which carry their own finalizers,
+ * and reaching into them from this one would race those.
+ */
+const gcRegistry = new FinalizationRegistry(({ X, gcs }) => {
+  safeRelease(X, () => {
+    for (const gc of gcs) {
+      if (!gc) continue;
+      X.FreeGC(gc);
+      X.ReleaseID(gc);
+    }
+  });
+});
+
 /**
  * What `drawImage` takes as a server-side source: anything that knows its own
  * size and can hand over a `Picture` for this connection.
@@ -174,6 +190,10 @@ class RenderingContext2d {
   constructor(window) {
     const X = window.X;
     this.X = X;
+    // ids land here as they are allocated; the finalizer holds this array
+    // rather than the context, so registering cannot keep the context alive
+    this._gcs = [];
+    gcRegistry.register(this, { X, gcs: this._gcs }, this);
 
     this.window = window;
     this.display = window.app.display;
@@ -236,6 +256,7 @@ class RenderingContext2d {
       // one GC is enough: it stays valid for any drawable of the same
       // screen and depth (the backing pixmap matches the window depth)
       this._gc = this.X.AllocID();
+      this._gcs.push(this._gc);
       this.X.CreateGC(this._gc, target.id);
     }
     if (this.picture) this.picture.destroy();
@@ -276,6 +297,7 @@ class RenderingContext2d {
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;
+    gcRegistry.unregister(this);
 
     this._clips = [];
     this._dropMasks();
@@ -287,6 +309,7 @@ class RenderingContext2d {
       });
     }
     this._gc = this._fillMaskGC = null;
+    this._gcs.length = 0;
 
     for (const picture of this._solidPictures.values()) {
       picture.destroy();
@@ -656,6 +679,7 @@ class RenderingContext2d {
   _maskGC() {
     if (!this._fillMaskGC) {
       this._fillMaskGC = this.X.AllocID();
+      this._gcs.push(this._fillMaskGC);
       this.X.CreateGC(this._fillMaskGC, this.fillMaskDrawable.id);
     }
     return this._fillMaskGC;
@@ -1782,24 +1806,40 @@ class RenderingContext2d {
         sHeight
       );
 
-      const pixmap = new Pixmap(this.window.app, { depth: 32, width: sWidth, height: sHeight });
-      const picture = new Picture(this.window.app, { drawable: pixmap, format: this.Render.rgba32 });
-      pixmap._gc = this.X.AllocID();
-      this.X.CreateGC(pixmap._gc, pixmap.id);
-      // the crop already happened in getImageData, so it lands at the pixmap's
-      // origin — sx/sy here wrote it off the edge
-      this.X.PutImage(2, pixmap.id, pixmap._gc, sWidth, sHeight, 0, 0, 0, 32, data);
+      // One upload GC per app rather than one per call, the same sharing
+      // Image.picture does: a GC is valid for any drawable of the same screen
+      // and depth. This used to allocate a GC, a pixmap and a picture every
+      // time and free none of them, so drawing a node-canvas source in an
+      // animation loop leaked three server resources per frame.
+      const app = this.window.app;
+      const pixmap = new Pixmap(app, { depth: 32, width: sWidth, height: sHeight });
+      const picture = new Picture(app, { drawable: pixmap, format: this.Render.rgba32 });
+      try {
+        let gc = app._imageUploadGC;
+        if (!gc) {
+          gc = app._imageUploadGC = this.X.AllocID();
+          this.X.CreateGC(gc, pixmap.id);
+        }
+        // the crop already happened in getImageData, so it lands at the
+        // pixmap's origin — sx/sy here wrote it off the edge
+        this.X.PutImage(2, pixmap.id, gc, sWidth, sHeight, 0, 0, 0, 32, data);
 
-      this.Render.Composite(
-        this.Render.PictOp.Over,
-        picture.id,
-        this._compositeMask(),
-        this.picture.id,
-        0, 0, 0, 0, 0, 0,
-        this.width,
-        this.height
-      );
-      this._markDirty();
+        this.Render.Composite(
+          this.Render.PictOp.Over,
+          picture.id,
+          this._compositeMask(),
+          this.picture.id,
+          0, 0, 0, 0, 0, 0,
+          this.width,
+          this.height
+        );
+        this._markDirty();
+      } finally {
+        // the composite is queued, and X executes requests in order, so the
+        // server is done with these by the time it reads the frees
+        picture.destroy();
+        pixmap.destroy();
+      }
     }
   }
 

package/lib/text/fontmanager.js

@@ -1,5 +1,10 @@
 import Font from './font.js';
-import { defaultFontSource, detectStyle, numericWeight as numWeight } from './fontsource.js';
+import {
+  createFontSource,
+  defaultFontSource,
+  detectStyle,
+  numericWeight as numWeight
+} from './fontsource.js';
 import { shapeText } from './shape.js';
 import { TextLayout } from './layout.js';
 
@@ -21,11 +26,14 @@ import { TextLayout } from './layout.js';
  *
  * All system lookup goes through a pluggable FontSource (see
  * text/fontsource.js) — pass `{ source }` to use something other than
- * fontconfig, e.g. a StaticFontSource in a browser bundle.
+ * fontconfig, e.g. a StaticFontSource in a browser bundle. `source` also
+ * takes a font spec: a path, a directory of faces, or font bytes.
  */
 export default class FontManager {
   constructor({ source } = {}) {
-    this._source = source ?? null; // resolved lazily so the process-wide default can be set late
+    // coerced here rather than in the getter, which is on the match path;
+    // null stays null so the process-wide default can still be set late
+    this._source = createFontSource(source) ?? null;
     this._fonts = new Map(); // candidate key -> Font
     this._matches = new Map(); // family|weight|style -> Font
     this._fallbacks = new Map(); // family|weight|style -> Map(codepoint -> Font|null)
@@ -146,6 +154,13 @@ export default class FontManager {
    * font doesn't. Registered fonts first, then the source's fallback chain
    * (filtered by the source's coverage data — font files are only opened to
    * confirm). Returns null when nothing on the system covers the codepoint.
+   *
+   * "Nothing covers it" includes "this environment has no system fonts at
+   * all". An app that loaded its own faces still reaches here for the first
+   * character they lack — a bullet, a curly quote — and before this returned
+   * null there, a fontconfig-less box crashed mid-shape on that character,
+   * arbitrarily far from anything about fonts. `shapeText` renders .notdef
+   * for a null, which is the right answer to "no font has this glyph".
    */
   fallbackFor(codepoint, family = 'sans-serif', opts = {}) {
     const cacheKey = `${family}|${numWeight(opts.weight)}|${opts.style || ''}`;
@@ -165,7 +180,15 @@ export default class FontManager {
     }
     if (!found) {
       const source = this.source;
-      const candidates = source.matchSorted({ family, weight: opts.weight, style: opts.style });
+      let candidates;
+      try {
+        candidates = source.matchSorted({ family, weight: opts.weight, style: opts.style });
+      } catch (err) {
+        // no system fonts to fall back to is an answer, not a crash; a source
+        // that failed for any other reason is a real bug and still propagates
+        if (err.code !== 'ERR_NTK_NO_FONTS') throw err;
+        candidates = [];
+      }
       for (const c of candidates) {
         if (source.covers && !source.covers(c, codepoint)) continue;
         try {

package/lib/text/fontsource.js

@@ -23,7 +23,18 @@
 // The default source shells out to fc-match (fontconfig) — the behavior ntk
 // always had. Swap it per-app (`createClient({ fontSource })`), per-manager
 // (`new FontManager({ source })`) or globally (`setDefaultFontSource()`).
-import { charsetHas, matchSortedSync } from '../fontconfig.js';
+//
+// All three of those also accept a **font spec** — a path, a directory, font
+// bytes, or a list of them — which `createFontSource` turns into a
+// StaticFontSource. That is the whole answer for an environment with no
+// 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).
+import { charsetHas, matchSortedSync, noFontsError, supported } from '../fontconfig.js';
 import Font from './font.js';
 
 const WEIGHTS = { normal: 400, bold: 700 };
@@ -53,6 +64,23 @@ export function detectStyle(font) {
   };
 }
 
+// A font is monospaced if it says so, or if it draws a period as wide as a W.
+// The probe is the part that carries its weight — `post.isFixedPitch` is 0 on
+// plenty of genuinely fixed-pitch faces.
+const PROBE = ['i', 'M', 'W', '.'].map((c) => c.codePointAt(0));
+
+function isMonospaced(font) {
+  if (font.fk.post?.isFixedPitch) return true;
+  let width = null;
+  for (const cp of PROBE) {
+    if (!font.hasGlyph(cp)) return false;
+    const advance = font.fk.glyphForCodePoint(cp).advanceWidth;
+    if (width === null) width = advance;
+    else if (advance !== width) return false;
+  }
+  return width !== null && width > 0;
+}
+
 /** split a CSS font-family list into normalized lowercase names */
 export function parseFamilies(family) {
   return String(family ?? '')
@@ -95,6 +123,8 @@ export class StaticFontSource {
     this._faces = []; // { font, family, weight, italic, candidate }
     this._aliases = new Map(); // 'sans-serif' -> 'dejavu sans'
     this._n = 0;
+    /** files a font spec could not parse: [{ file, error }] */
+    this.skipped = [];
   }
 
   /**
@@ -129,9 +159,55 @@ export class StaticFontSource {
     this._aliases.set(name.toLowerCase(), family.toLowerCase());
   }
 
+  /** what the generic families currently resolve to, for inspection */
+  get aliases() {
+    return Object.fromEntries(this._aliases);
+  }
+
+  /**
+   * Point `sans-serif`, `serif` and `monospace` at added faces.
+   *
+   * This is not cosmetic. Every widget default in the toolkit is
+   * `sans-serif`, and `code`/`pre` ask for `monospace`; with no alias for
+   * them `matchSorted` ranks every face equally and breaks the tie on weight
+   * distance and then insertion order, so `monospace` silently renders in a
+   * proportional face. Inference happens automatically for a source built
+   * from a font spec; a hand-built source calls this when it wants it.
+   *
+   * A generic is only aliased on positive evidence, and a generic with none
+   * is deliberately left out — its absence from `aliases` is the signal to
+   * pass an explicit one. Monospace is decided structurally, because fonts
+   * lie about it: KaTeX_Typewriter reports `isFixedPitch = 0` while every
+   * advance is 525. Sans/serif read the font's own family name, the
+   * convention DejaVu, Noto, Liberation, Source and IBM Plex all follow —
+   * never the filename, which loses on `Inter_18pt-SemiBold.ttf`.
+   *
+   * Explicit aliases are never overridden.
+   */
+  inferGenerics() {
+    const mono = [];
+    const rest = [];
+    for (const face of this._faces) (isMonospaced(face.font) ? mono : rest).push(face);
+
+    // "sans" is checked first and its matches are then excluded, because
+    // "SansSerif" and "Sans Serif" contain "serif" — without that, the one
+    // family named for both wins the generic it is least suited to
+    const sans = rest.filter((f) => /sans/i.test(f.font.familyName || ''));
+    const serif = rest.filter((f) => !sans.includes(f) && /serif/i.test(f.font.familyName || ''));
+    const evidence = {
+      monospace: mono[0]?.family,
+      'sans-serif': sans[0]?.family,
+      serif: serif[0]?.family
+    };
+    for (const [generic, family] of Object.entries(evidence)) {
+      if (family && !this._aliases.has(generic)) this._aliases.set(generic, family);
+    }
+    return this;
+  }
+
   matchSorted(pattern = {}) {
     if (this._faces.length === 0) {
-      throw new Error('StaticFontSource: no fonts added');
+      throw noFontsError('this font source has no fonts added');
     }
     const families = parseFamilies(pattern.family).map((f) => this._aliases.get(f) ?? f);
     const weight = numericWeight(pattern.weight);
@@ -160,6 +236,179 @@ export class StaticFontSource {
   }
 }
 
+// A directory of an app's own faces is a handful of files; a system font
+// tree is hundreds, and every one of them is parsed and then retained for
+// the life of the FontManager (one macOS emoji collection alone is 188 MB).
+// Rather than document that and hope, the walk stops and names the option —
+// an app that really means it says so.
+const MAX_FILES = 64;
+const MAX_DEPTH = 8;
+
+// Said whenever ntk is handed something it cannot read as fonts. It names
+// every accepted shape rather than the one that was wrong, and states the
+// premise — ntk has no fonts of its own — because the spec that brings people
+// here is `'bundled'`, from an issue proposing a font package that does not
+// exist. Naming that value in the matcher would enshrine an API that never
+// shipped; this answers the question without making it real.
+const ACCEPTED =
+  ". Pass 'system', a path to a font file or directory, font bytes, an array of " +
+  'those, { fonts, alias }, or a FontSource. ntk ships no fonts of its own — see ' +
+  'docs/fonts.md';
+
+function fs() {
+  const mod = globalThis.process?.getBuiltinModule?.('node:fs');
+  if (!mod) {
+    throw new Error(
+      'ntk: a font path can only be read in node. In a browser, fetch the font ' +
+        'bytes yourself and pass them: fontSource: [bytes] — see docs/fonts.md'
+    );
+  }
+  return mod;
+}
+
+/** stat a spec'd path, reporting a missing one as the spec mistake it is
+ * rather than as a bare ENOENT from somewhere inside ntk */
+function statOf(path) {
+  try {
+    return fs().statSync(path);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // A bare word is far more likely a spec someone invented — 'bundled' is
+      // the one the issue asks for — than a path they mistyped. Answer the
+      // question they were actually asking.
+      const guess = /[/\\.]/.test(path) ? '' : ACCEPTED;
+      throw new Error(`ntk: no such font file or directory: "${path}"${guess}`, { cause: err });
+    }
+    throw err;
+  }
+}
+
+/** every font file in a directory, sorted — never readdir order, which would
+ * let the filesystem pick which face `sans-serif` lands on */
+function fontFilesIn(dir, recursive, budget, depth = 0) {
+  const { readdirSync } = fs();
+  const found = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  for (const entry of entries) {
+    const path = `${dir}/${entry.name}`;
+    // isDirectory() is false for a symlink, so this skips linked directories
+    // and with them any chance of a cycle
+    if (entry.isDirectory()) {
+      if (recursive && depth < MAX_DEPTH) found.push(...fontFilesIn(path, true, budget, depth + 1));
+    } else if (supported.test(entry.name)) {
+      found.push(path);
+      if (++budget.count > budget.max) {
+        throw new Error(
+          `ntk: more than ${budget.max} font files under "${budget.root}". That is a font ` +
+            "tree rather than an app's own faces, and every one of them would be parsed and " +
+            'kept in memory for the life of the process. List the faces you want, or raise ' +
+            `the limit deliberately: { fonts: '${budget.root}', maxFiles: N } — see docs/fonts.md`
+        );
+      }
+    }
+  }
+  return found;
+}
+
+/** does this look like a face rather than a typo? */
+function isFace(face) {
+  return (
+    typeof face === 'string' ||
+    ArrayBuffer.isView(face) ||
+    face instanceof ArrayBuffer ||
+    (!!face && typeof face === 'object' && (typeof face.path === 'string' || face.data != null))
+  );
+}
+
+function addFace(source, face, skipped) {
+  try {
+    if (typeof face === 'string') return source.add(Font.loadSync(face));
+    if (ArrayBuffer.isView(face) || face instanceof ArrayBuffer) return source.add(face);
+    const { path, data, ...opts } = face;
+    return source.add(path ? Font.loadSync(path, opts.postscriptName) : data, opts);
+  } catch (err) {
+    // one unparseable file should not take a whole directory down; a spec
+    // that yields no usable face at all still throws, below
+    skipped.push({ file: typeof face === 'string' ? face : face?.path, error: err });
+    return null;
+  }
+}
+
+function describe(value) {
+  if (typeof value === 'string') return `"${value}"`;
+  if (Array.isArray(value)) return 'that array';
+  return value === null ? 'null' : typeof value;
+}
+
+/**
+ * Resolve a **font spec** to a FontSource.
+ *
+ * ```
+ * spec  := FontSource | 'system' | null | undefined
+ *        | faces | { fonts: faces, alias?, recursive?, maxFiles? }
+ * faces := face | face[]
+ * face  := string (path to a font FILE or DIRECTORY)
+ *        | Uint8Array | Buffer | ArrayBuffer
+ *        | { path | data, family?, weight?, style?, postscriptName? }
+ * ```
+ *
+ * Idempotent — a FontSource passes straight through, which is what lets
+ * `createClient`, `FontManager` and `setDefaultFontSource` all coerce
+ * without caring whether someone already did.
+ *
+ * Anything built from faces is a `StaticFontSource`, so there is one
+ * matching implementation to reason about rather than two. Generic families
+ * are inferred (see `inferGenerics`) with an explicit `alias` map winning.
+ *
+ * @param {*} spec
+ * @returns {object|null|undefined} a FontSource
+ */
+export function createFontSource(spec) {
+  if (spec == null) return spec; // preserves setDefaultFontSource(null)'s reset
+  if (typeof spec.matchSorted === 'function') return spec;
+  if (spec === 'system') return new FontconfigFontSource();
+
+  const configured = !Array.isArray(spec) && typeof spec === 'object' && 'fonts' in spec;
+  const { fonts, alias, recursive = false, maxFiles = MAX_FILES } = configured ? spec : { fonts: spec };
+  const list = Array.isArray(fonts) ? fonts : [fonts];
+
+  if (list.length === 0 || !list.every(isFace)) {
+    throw new Error(`ntk: ${describe(spec)} is not a font source${ACCEPTED}`);
+  }
+
+  const source = new StaticFontSource();
+  const skipped = [];
+  const budget = { count: 0, max: maxFiles, root: null };
+  let added = 0;
+  for (const face of list) {
+    if (typeof face === 'string' && statOf(face).isDirectory()) {
+      budget.root = face;
+      const files = fontFilesIn(face, recursive, budget);
+      if (files.length === 0) {
+        throw new Error(
+          `ntk: no font files in "${face}" — looked for .ttf/.otf/.woff/.woff2/.ttc/.dfont` +
+            (recursive ? '' : '. Pass { fonts, recursive: true } to walk subdirectories')
+        );
+      }
+      for (const file of files) if (addFace(source, file, skipped)) added++;
+    } else if (addFace(source, face, skipped)) {
+      added++;
+    }
+  }
+
+  source.skipped = skipped;
+  if (added === 0) {
+    throw new Error(
+      `ntk: none of the ${skipped.length} font file(s) given could be parsed — ` +
+        `${skipped[0]?.file ?? 'the first'}: ${skipped[0]?.error?.message ?? 'unknown error'}`
+    );
+  }
+
+  for (const [generic, family] of Object.entries(alias ?? {})) source.alias(generic, family);
+  return source.inferGenerics();
+}
+
 let _default = null;
 
 /** the process-wide default FontSource (fontconfig unless overridden) */
@@ -173,7 +422,10 @@ export function defaultFontSource() {
  * created afterwards without an explicit source — including the ones
  * widgets create internally. The primary hook for browser playgrounds:
  * call it once with a StaticFontSource before creating any app/window.
+ *
+ * Takes a font spec as well as a source, so pointing the whole process at a
+ * directory is one line. `null` restores the fontconfig default.
  */
 export function setDefaultFontSource(source) {
-  _default = source;
+  _default = createFontSource(source);
 }

package/lib/window.js

@@ -655,7 +655,7 @@ export default class Window extends Drawable {
     });
     if (!this._clearGc) {
       // reusable across reallocs: a GC is valid for any drawable of the
-      // same screen and depth (node-x11 has no FreeGC request)
+      // 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",