ntk 5.2.0 → 5.4.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

@@ -1,6 +1,7 @@
 import jpeg from 'jpeg-js';
 import { PNG } from 'pngjs';
 
+import { fromStraightRgba, pixelLayout } from './imagedata.js';
 import Picture from './picture.js';
 
 /**
@@ -40,26 +41,19 @@ export class Image {
     const Render = app.display.Render;
     const pixmap = app.createPixmap({ depth: 32, width: this.width, height: this.height });
 
-    // XRender composites premultiplied alpha; PutImage on a 32-bit ZPixmap
-    // wants BGRA byte order (see AGENTS.md gotchas)
-    const bgra = Buffer.allocUnsafe(this.width * this.height * 4);
-    const src = this.data;
-    for (let i = 0; i < bgra.length; i += 4) {
-      const a = src[i + 3];
-      if (a === 255) {
-        bgra[i] = src[i + 2];
-        bgra[i + 1] = src[i + 1];
-        bgra[i + 2] = src[i];
-      } else {
-        bgra[i] = (src[i + 2] * a + 127) / 255;
-        bgra[i + 1] = (src[i + 1] * a + 127) / 255;
-        bgra[i + 2] = (src[i] * a + 127) / 255;
-      }
-      bgra[i + 3] = a;
-    }
+    // straight RGBA in, the server's own premultiplied layout out. This used
+    // to assume BGRA, which is only what a little-endian server with the
+    // standard visual masks happens to want.
+    const bgra = fromStraightRgba(
+      this.data,
+      pixelLayout(app.display, 32),
+      this.width,
+      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/imagedata.js

@@ -0,0 +1,388 @@
+/**
+ * The canvas pixel contract, and the conversions between it and what an X
+ * server actually hands over.
+ *
+ * Canvas `ImageData` is straight (non-premultiplied) RGBA bytes, one byte per
+ * channel, rows top to bottom. An X drawable is none of those things by
+ * default:
+ *
+ *   - `GetImage` returns the drawable's raw words in the *server's*
+ *     `image_byte_order`, which is a different field from the byte order this
+ *     connection speaks;
+ *   - which bits inside a word hold which channel comes from the visual's
+ *     masks, not from a convention;
+ *   - anything XRender composited into is premultiplied, and a drawable
+ *     without an alpha channel has a fourth byte that is undefined padding
+ *     rather than opaque.
+ *
+ * Everything crossing that boundary goes through here, so callers see RGBA
+ * and only this file knows about the rest. `readPixels()` is the way out for
+ * code that genuinely wants the server's own bytes — it reports the layout
+ * alongside them instead of leaving the caller to assume one.
+ */
+
+/** shift of the lowest set bit, i.e. where a channel starts inside a word */
+function shiftOf(mask) {
+  let s = 0;
+  while (s < 32 && !((mask >>> s) & 1)) s++;
+  return s;
+}
+
+/** width of a contiguous mask, so 5- and 6-bit channels can be scaled to 8 */
+function widthOf(mask, shift) {
+  let w = 0;
+  while (shift + w < 32 && (mask >>> (shift + w)) & 1) w++;
+  return w;
+}
+
+/**
+ * How pixels of `depth` are laid out on this display: which bits hold which
+ * channel, whether there is an alpha channel at all, and which end of a word
+ * the server writes first.
+ *
+ * Channel positions come from a TrueColor visual of that depth when the
+ * screen has one. Depth 32 has no visual on most servers (XQuartz has none at
+ * all) but every depth-32 drawable ntk makes is paired with a `Render.rgba32`
+ * picture, whose PictStandardARGB32 format pins A=24 R=16 G=8 B=0 — so that
+ * is the fallback, and it is a specification rather than a guess.
+ */
+export function pixelLayout(display, depth) {
+  const screen = display.screen[0];
+  let masks = null;
+  for (const visual of Object.values(screen.depths?.[depth] ?? {})) {
+    if (visual.class === 4 || visual.class === 5) {
+      // TrueColor / DirectColor
+      masks = { red: visual.red_mask, green: visual.green_mask, blue: visual.blue_mask };
+      break;
+    }
+  }
+  if (!masks) masks = { red: 0xff0000, green: 0x00ff00, blue: 0x0000ff };
+
+  const bitsPerPixel = display.format?.[depth]?.bits_per_pixel ?? (depth > 16 ? 32 : depth);
+  if (bitsPerPixel !== 32) {
+    throw new Error(
+      `ntk works in 32-bit pixels; depth ${depth} on this server is ` +
+        `${bitsPerPixel} bits per pixel. Use readPixels() and unpack it yourself.`
+    );
+  }
+
+  const hasAlpha = depth === 32;
+  // whatever the colour masks leave over, which for ARGB32 is the top byte
+  const alpha = hasAlpha ? (~(masks.red | masks.green | masks.blue) & 0xffffffff) >>> 0 : 0;
+
+  return {
+    depth,
+    bitsPerPixel,
+    masks: { ...masks, alpha },
+    // 0 LSBFirst, 1 MSBFirst — the server's pixel order, NOT display.byte_order
+    byteOrder: display.image_byte_order ? 'msb' : 'lsb',
+    // XRender composites premultiplied, so anything with an alpha channel
+    // that ntk has drawn into holds premultiplied colour
+    premultiplied: hasAlpha
+  };
+}
+
+/** the common case: LSBFirst words with 8-bit channels at ARGB32 positions */
+function isStandardLsb(layout) {
+  return (
+    layout.byteOrder === 'lsb' &&
+    layout.masks.red === 0xff0000 &&
+    layout.masks.green === 0x00ff00 &&
+    layout.masks.blue === 0x0000ff
+  );
+}
+
+/**
+ * Server pixels -> straight RGBA. `raw` is a `GetImage` reply body.
+ *
+ * @param {Buffer} raw
+ * @param {object} layout from `pixelLayout()`
+ * @param {number} width
+ * @param {number} height
+ * @returns {Uint8ClampedArray}
+ */
+export function toStraightRgba(raw, layout, width, height) {
+  const n = width * height;
+  const out = new Uint8ClampedArray(n * 4);
+  const { premultiplied } = layout;
+
+  if (isStandardLsb(layout)) {
+    // bytes arrive B, G, R, A — a straight index shuffle, which measures
+    // faster than reading 32-bit words back out of the Buffer
+    for (let i = 0; i < n * 4; i += 4) {
+      const a = layout.depth === 32 ? raw[i + 3] : 255;
+      if (a === 255) {
+        out[i] = raw[i + 2];
+        out[i + 1] = raw[i + 1];
+        out[i + 2] = raw[i];
+      } else if (a === 0 || !premultiplied) {
+        out[i] = raw[i + 2];
+        out[i + 1] = raw[i + 1];
+        out[i + 2] = raw[i];
+      } else {
+        out[i] = (raw[i + 2] * 255) / a;
+        out[i + 1] = (raw[i + 1] * 255) / a;
+        out[i + 2] = (raw[i] * 255) / a;
+      }
+      out[i + 3] = a;
+    }
+    return out;
+  }
+
+  const { masks } = layout;
+  const rs = shiftOf(masks.red);
+  const gs = shiftOf(masks.green);
+  const bs = shiftOf(masks.blue);
+  const as = masks.alpha ? shiftOf(masks.alpha) : 0;
+  const rw = widthOf(masks.red, rs);
+  const gw = widthOf(masks.green, gs);
+  const bw = widthOf(masks.blue, bs);
+  // scale a channel of `w` bits up to 8, so 0b11111 becomes 255 not 248
+  const up = (v, w) => (w === 8 ? v : Math.round((v * 255) / ((1 << w) - 1)));
+  const readWord = layout.byteOrder === 'msb'
+    ? (o) => raw.readUInt32BE(o)
+    : (o) => raw.readUInt32LE(o);
+
+  for (let i = 0; i < n; i++) {
+    const px = readWord(i * 4);
+    const a = masks.alpha ? (px & masks.alpha) >>> as : 255;
+    let r = up((px & masks.red) >>> rs, rw);
+    let g = up((px & masks.green) >>> gs, gw);
+    let b = up((px & masks.blue) >>> bs, bw);
+    if (premultiplied && a !== 0 && a !== 255) {
+      r = (r * 255) / a;
+      g = (g * 255) / a;
+      b = (b * 255) / a;
+    }
+    out[i * 4] = r;
+    out[i * 4 + 1] = g;
+    out[i * 4 + 2] = b;
+    out[i * 4 + 3] = a;
+  }
+  return out;
+}
+
+/**
+ * Straight RGBA -> server pixels, ready for `PutImage`.
+ *
+ * @param {Uint8Array} rgba straight RGBA, 4 bytes per pixel
+ * @param {object} layout from `pixelLayout()`
+ * @param {number} width
+ * @param {number} height
+ * @returns {Buffer}
+ */
+export function fromStraightRgba(rgba, layout, width, height) {
+  const n = width * height;
+  const out = Buffer.allocUnsafe(n * 4);
+  const { premultiplied } = layout;
+
+  if (isStandardLsb(layout)) {
+    for (let i = 0; i < n * 4; i += 4) {
+      const a = rgba[i + 3];
+      if (!premultiplied || a === 255) {
+        out[i] = rgba[i + 2];
+        out[i + 1] = rgba[i + 1];
+        out[i + 2] = rgba[i];
+      } else {
+        // +127 rounds to nearest rather than truncating, which otherwise
+        // drifts a translucent fill visibly darker over repeated round trips
+        out[i] = (rgba[i + 2] * a + 127) / 255;
+        out[i + 1] = (rgba[i + 1] * a + 127) / 255;
+        out[i + 2] = (rgba[i] * a + 127) / 255;
+      }
+      out[i + 3] = layout.depth === 32 ? a : 0;
+    }
+    return out;
+  }
+
+  const { masks } = layout;
+  const rs = shiftOf(masks.red);
+  const gs = shiftOf(masks.green);
+  const bs = shiftOf(masks.blue);
+  const as = masks.alpha ? shiftOf(masks.alpha) : 0;
+  const rw = widthOf(masks.red, rs);
+  const gw = widthOf(masks.green, gs);
+  const bw = widthOf(masks.blue, bs);
+  const down = (v, w) => (w === 8 ? v : Math.round((v * ((1 << w) - 1)) / 255));
+  const writeWord = layout.byteOrder === 'msb'
+    ? (v, o) => out.writeUInt32BE(v, o)
+    : (v, o) => out.writeUInt32LE(v, o);
+
+  for (let i = 0; i < n; i++) {
+    const a = rgba[i * 4 + 3];
+    let r = rgba[i * 4];
+    let g = rgba[i * 4 + 1];
+    let b = rgba[i * 4 + 2];
+    if (premultiplied && a !== 255) {
+      r = (r * a + 127) / 255;
+      g = (g * a + 127) / 255;
+      b = (b * a + 127) / 255;
+    }
+    const word =
+      ((down(r | 0, rw) << rs) |
+        (down(g | 0, gw) << gs) |
+        (down(b | 0, bw) << bs) |
+        (masks.alpha ? (a << as) & masks.alpha : 0)) >>>
+      0;
+    writeWord(word, i * 4);
+  }
+  return out;
+}
+
+/**
+ * Canvas `ImageData`: straight RGBA in a `Uint8ClampedArray`, rows top to
+ * bottom. Both spec constructor forms work:
+ *
+ *   new ImageData(width, height)
+ *   new ImageData(data, width[, height])
+ *
+ * `data` may be any `Uint8Array` — a node `Buffer` included — and is adopted
+ * as-is when it is already a `Uint8ClampedArray`, copied otherwise.
+ */
+export class ImageData {
+  constructor(a, b, c) {
+    if (typeof a === 'number') {
+      const width = a;
+      const height = b;
+      if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+        throw new Error('ImageData: width and height must be positive integers');
+      }
+      this.width = width;
+      this.height = height;
+      this.data = new Uint8ClampedArray(width * height * 4);
+      return;
+    }
+    if (!ArrayBuffer.isView(a)) {
+      throw new TypeError('ImageData: first argument must be a width or a typed array');
+    }
+    const width = b;
+    if (!Number.isInteger(width) || width <= 0) {
+      throw new Error('ImageData: width must be a positive integer');
+    }
+    if (a.length % 4 !== 0) {
+      throw new Error(`ImageData: data length ${a.length} is not a whole number of RGBA pixels`);
+    }
+    const height = c ?? a.length / 4 / width;
+    if (!Number.isInteger(height) || height <= 0) {
+      throw new Error(`ImageData: ${a.length} bytes is not a whole number of ${width}px rows`);
+    }
+    if (a.length !== width * height * 4) {
+      throw new Error(
+        `ImageData: data must be ${width * height * 4} bytes for ${width}x${height}, got ${a.length}`
+      );
+    }
+    this.width = width;
+    this.height = height;
+    this.data =
+      a instanceof Uint8ClampedArray
+        ? a
+        : new Uint8ClampedArray(a.buffer, a.byteOffset, a.byteLength).slice();
+  }
+
+  /** the sRGB colour space, for parity with the browser's property */
+  get colorSpace() {
+    return 'srgb';
+  }
+}
+
+// --- EWMH _NET_WM_ICON -----------------------------------------------------
+//
+// The property is a run of CARD32s, repeated once per size:
+//
+//   width, height, pixel[0] … pixel[width*height-1]
+//
+// Each pixel is straight ARGB inside the word — A=24 R=16 G=8 B=0. Straight,
+// not premultiplied, which is the same thing ImageData holds, so this is a
+// repack rather than a conversion. The one thing to get right is which byte
+// order: a format-32 property is read back by the server in the *connection's*
+// byte order, which is a different handshake field from the image_byte_order
+// that `pixelLayout()` uses for GetImage.
+
+const wordIO = (display) =>
+  display.byte_order
+    ? { read: (b, o) => b.readUInt32BE(o), write: (b, v, o) => b.writeUInt32BE(v, o) }
+    : { read: (b, o) => b.readUInt32LE(o), write: (b, v, o) => b.writeUInt32LE(v, o) };
+
+/**
+ * Pack one or more images into `_NET_WM_ICON` property bytes.
+ *
+ * @param {Array<{width: number, height: number, data: Uint8Array}>} images
+ *   straight RGBA, as `Image` and `ImageData` both are
+ * @param {object} display
+ * @returns {Buffer}
+ */
+export function packIcons(images, display) {
+  let words = 0;
+  images.forEach((img, i) => {
+    const { width, height, data } = img ?? {};
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+      throw new Error(`icon ${i}: width and height must be positive integers`);
+    }
+    if (!data || data.length !== width * height * 4) {
+      throw new Error(
+        `icon ${i}: data must be ${width * height * 4} RGBA bytes for ${width}x${height}, ` +
+          `got ${data ? data.length : 'nothing'}`
+      );
+    }
+    words += 2 + width * height;
+  });
+
+  const out = Buffer.allocUnsafe(words * 4);
+  const { write } = wordIO(display);
+  let o = 0;
+  for (const { width, height, data } of images) {
+    write(out, width, o);
+    write(out, height, o + 4);
+    o += 8;
+    for (let i = 0; i < width * height; i++) {
+      write(
+        out,
+        (((data[i * 4 + 3] << 24) |
+          (data[i * 4] << 16) |
+          (data[i * 4 + 1] << 8) |
+          data[i * 4 + 2]) >>>
+          0),
+        o
+      );
+      o += 4;
+    }
+  }
+  return out;
+}
+
+/**
+ * Read `_NET_WM_ICON` bytes back into images.
+ *
+ * Deliberately forgiving about what it is handed: a window manager runs this
+ * over properties written by other people's clients, so a truncated or
+ * nonsensical run stops the scan and returns whatever parsed cleanly rather
+ * than throwing or trying to allocate a claimed 4-gigapixel icon.
+ *
+ * @returns {ImageData[]}
+ */
+export function unpackIcons(buf, display) {
+  const { read } = wordIO(display);
+  const out = [];
+  let o = 0;
+  while (o + 8 <= buf.length) {
+    const width = read(buf, o);
+    const height = read(buf, o + 4);
+    // guard the multiplication itself, not just its result
+    if (width <= 0 || height <= 0 || width > 0xffff || height > 0xffff) break;
+    const pixels = width * height;
+    if (o + 8 + pixels * 4 > buf.length) break;
+    o += 8;
+
+    const rgba = new Uint8ClampedArray(pixels * 4);
+    for (let i = 0; i < pixels; i++) {
+      const px = read(buf, o + i * 4);
+      rgba[i * 4] = (px >>> 16) & 0xff;
+      rgba[i * 4 + 1] = (px >>> 8) & 0xff;
+      rgba[i * 4 + 2] = px & 0xff;
+      rgba[i * 4 + 3] = (px >>> 24) & 0xff;
+    }
+    o += pixels * 4;
+    out.push(new ImageData(rgba, width, height));
+  }
+  return out;
+}

package/lib/index.js

@@ -9,12 +9,22 @@ import { decodeKey, groupForState } from './keyboard.js';
 import Pixmap from './pixmap.js';
 import Picture from './picture.js';
 import { Image, decodeImage, loadImage } from './image.js';
+import {
+  ImageData,
+  fromStraightRgba,
+  packIcons,
+  pixelLayout,
+  toStraightRgba,
+  unpackIcons
+} from './imagedata.js';
+import { Surface } from './surface.js';
 import { Path2D, parseSvgPath } from './path.js';
 import Font from './text/font.js';
 import FontManager from './text/fontmanager.js';
 import {
   FontconfigFontSource,
   StaticFontSource,
+  createFontSource,
   defaultFontSource,
   setDefaultFontSource
 } from './text/fontsource.js';
@@ -60,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
@@ -86,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);
 
@@ -121,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));
         });
       });
     });
@@ -149,7 +171,14 @@ export {
   resolveCursorShape,
   Pixmap,
   Picture,
+  Surface,
   Image,
+  ImageData,
+  pixelLayout,
+  toStraightRgba,
+  fromStraightRgba,
+  packIcons,
+  unpackIcons,
   decodeImage,
   loadImage,
   Path2D,
@@ -158,6 +187,7 @@ export {
   FontManager,
   FontconfigFontSource,
   StaticFontSource,
+  createFontSource,
   defaultFontSource,
   setDefaultFontSource,
   CoverageAccumulator,