ntk 2.2.0 → 3.1.0

package/lib/text/fontsource.js

@@ -0,0 +1,179 @@
+// Pluggable system-font lookup — the seam that lets the text stack run in
+// environments without fontconfig or a filesystem (browser bundles, hermetic
+// tests). A font source answers "which fonts match this pattern, in fallback
+// order?" and hands the FontManager something it can open.
+//
+// FontSource interface (duck-typed):
+//
+//   matchSorted({ family, weight, style }) -> candidate[]
+//     Full match list for a pattern, best first — the fallback chain.
+//     `family` may be a CSS-style comma-separated list. Must return at
+//     least one candidate or throw. A candidate is openable:
+//       { key?, path?, data?, font?, postscriptName? }
+//     - `font`: an already-open Font instance (preferred when available)
+//     - `data`: font file bytes (Uint8Array/Buffer) for fontkit
+//     - `path`: font file path (node only)
+//     - `key`: stable cache key (defaults to `${path}#${postscriptName}`)
+//
+//   covers(candidate, codepoint) -> boolean   [optional]
+//     Cheap coverage pre-filter used during per-codepoint fallback, ideally
+//     without opening the font. When absent, candidates are opened and
+//     checked with `font.hasGlyph()`.
+//
+// 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';
+import Font from './font.js';
+
+const WEIGHTS = { normal: 400, bold: 700 };
+
+/** css-ish weight ('bold' | 400 | '600') -> number, default 400 */
+export function numericWeight(weight) {
+  if (weight === undefined) return 400;
+  if (WEIGHTS[weight] !== undefined) return WEIGHTS[weight];
+  const n = parseInt(weight, 10);
+  return Number.isNaN(n) ? 400 : n;
+}
+
+/**
+ * Detect a Font's weight/italic from its tables. Fonts are sloppy about
+ * italics — check the fsSelection bit, then italicAngle, then the
+ * subfamily name (KaTeX's italic faces set nothing but the name).
+ */
+export function detectStyle(font) {
+  const os2 = font.fk['OS/2'];
+  return {
+    weight: os2 ? os2.usWeightClass : 400,
+    italic: !!(
+      (os2 && os2.fsSelection.italic) ||
+      font.fk.italicAngle ||
+      /italic|oblique/i.test(font.fk.subfamilyName || '')
+    )
+  };
+}
+
+/** split a CSS font-family list into normalized lowercase names */
+export function parseFamilies(family) {
+  return String(family ?? '')
+    .split(',')
+    .map((f) => f.trim().replace(/^["']|["']$/g, '').toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * The default source: fontconfig via the fc-match CLI, font files opened
+ * from disk. Node-only (needs shell access); see StaticFontSource for a
+ * self-contained alternative.
+ */
+export class FontconfigFontSource {
+  matchSorted(pattern) {
+    return matchSortedSync(pattern);
+  }
+
+  covers(candidate, codepoint) {
+    return charsetHas(candidate, codepoint);
+  }
+}
+
+/**
+ * A font source backed entirely by fonts you hand it — no fontconfig, no
+ * filesystem. Works anywhere fontkit runs, including browser bundles:
+ *
+ *   const source = new StaticFontSource();
+ *   source.add(bytes, { family: 'DejaVu Sans' });
+ *   source.alias('sans-serif', 'DejaVu Sans');
+ *   const app = await createClient({ fontSource: source });
+ *
+ * Matching mirrors fontconfig semantics: every added face is a fallback
+ * candidate; faces matching a requested family (in list order) rank first,
+ * then closest weight, then style. Coverage checks use the real font
+ * tables, so per-codepoint fallback works exactly like the system path.
+ */
+export class StaticFontSource {
+  constructor() {
+    this._faces = []; // { font, family, weight, italic, candidate }
+    this._aliases = new Map(); // 'sans-serif' -> 'dejavu sans'
+    this._n = 0;
+  }
+
+  /**
+   * Register a font.
+   * @param {Uint8Array|Buffer|Font} data font file bytes (or an open Font)
+   * @param {object} [opts] { family (alias for matching; defaults to the
+   *   font's family name), weight, style, postscriptName (face of a .ttc) }
+   * @returns {Font}
+   */
+  add(data, opts = {}) {
+    const font =
+      data instanceof Font
+        ? data
+        : Font.fromData(data, {
+            key: `static:${this._n++}:${opts.family || opts.postscriptName || ''}`,
+            postscriptName: opts.postscriptName
+          });
+    const detected = detectStyle(font);
+    this._faces.push({
+      font,
+      family: (opts.family || font.familyName || '').toLowerCase(),
+      weight: opts.weight !== undefined ? numericWeight(opts.weight) : detected.weight,
+      italic:
+        opts.style !== undefined ? String(opts.style).includes('italic') : detected.italic,
+      candidate: null
+    });
+    return font;
+  }
+
+  /** map a generic family ('sans-serif', 'monospace', …) to an added family */
+  alias(name, family) {
+    this._aliases.set(name.toLowerCase(), family.toLowerCase());
+  }
+
+  matchSorted(pattern = {}) {
+    if (this._faces.length === 0) {
+      throw new Error('StaticFontSource: no fonts added');
+    }
+    const families = parseFamilies(pattern.family).map((f) => this._aliases.get(f) ?? f);
+    const weight = numericWeight(pattern.weight);
+    const italic = !!(pattern.style && String(pattern.style).includes('italic'));
+
+    const scored = this._faces.map((face) => {
+      let rank = families.indexOf(face.family);
+      if (rank === -1) rank = families.length; // non-matching faces trail
+      return {
+        face,
+        score:
+          rank * 1e6 + (face.italic !== italic ? 1e4 : 0) + Math.abs(face.weight - weight)
+      };
+    });
+    scored.sort((a, b) => a.score - b.score);
+    return scored.map(({ face }) => {
+      if (!face.candidate) {
+        face.candidate = { key: face.font.key, font: face.font };
+      }
+      return face.candidate;
+    });
+  }
+
+  covers(candidate, codepoint) {
+    return candidate.font.hasGlyph(codepoint);
+  }
+}
+
+let _default = null;
+
+/** the process-wide default FontSource (fontconfig unless overridden) */
+export function defaultFontSource() {
+  if (!_default) _default = new FontconfigFontSource();
+  return _default;
+}
+
+/**
+ * Replace the process-wide default FontSource. Affects every FontManager
+ * 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.
+ */
+export function setDefaultFontSource(source) {
+  _default = source;
+}

package/lib/text/glyphs.js

@@ -0,0 +1,456 @@
+import GlyphSet from '../glyphset.js';
+import Picture from '../picture.js';
+import Pixmap from '../pixmap.js';
+import { trapezoidize } from '../trapezoid.js';
+
+/**
+ * Text rendering policy — the bitmap/vector routing thresholds and the
+ * server-side glyph cache budget. Override per app via `app.textPolicy`
+ * (partial objects are fine, e.g. `app.textPolicy = { vectorFrom: Infinity }`
+ * to opt out of the vector path entirely). See docs/text.md.
+ *
+ * - `bitmapMax` — at or below this pixel size glyphs always render through
+ *   cached server-side bitmaps (upload once, ~1 byte per glyph per draw).
+ * - `vectorFrom` — above this size glyphs render as trapezoids every draw:
+ *   bitmap uploads scale with size² (a full Latin set at 256px is ~2.4MB of
+ *   server cache per face) while outlines scale with ~√size.
+ * - Between the two, bitmaps are used unless the size is fractional or the
+ *   face shows no size reuse across recent draws (continuous zoom/pinch
+ *   animation) — the cases where per-size caches never amortize.
+ * - `cacheBytes` — LRU budget for uploaded glyph bitmaps per connection;
+ *   least-recently-drawn (face, size) pages are freed server-side
+ *   (FreeGlyphSet) so transient sizes don't accumulate.
+ */
+export const DEFAULT_TEXT_POLICY = {
+  bitmapMax: 128,
+  vectorFrom: 256,
+  cacheBytes: 8 << 20
+};
+
+function policyOf(app) {
+  return app.textPolicy ? { ...DEFAULT_TEXT_POLICY, ...app.textPolicy } : DEFAULT_TEXT_POLICY;
+}
+
+/**
+ * Server-side glyph cache for one (font face, pixel size) pair.
+ *
+ * Wire-efficiency design (see docs/text.md):
+ *
+ * - Glyph ids inside an XRender glyphset are client-assigned. We assign
+ *   **compact sequential ids** (0, 1, 2, …) in upload order instead of using
+ *   font glyph indices, so CompositeGlyphs can use the 8-bit encoding
+ *   (1 byte per glyph) for the first 256 distinct glyphs of a face/size —
+ *   which covers virtually all Latin text — and 16-bit after that.
+ * - Each glyph's rounded nominal advance is baked into the glyph itself
+ *   (`offX`), so the server advances the pen automatically and runs of
+ *   unkerned text need no per-glyph position data at all.
+ * - Bitmaps upload lazily, once per glyph, batched into one AddGlyphs
+ *   request per draw that introduces new glyphs.
+ */
+export class GlyphPage {
+  constructor(app, font, size) {
+    this.app = app;
+    this.font = font;
+    this.size = size;
+    this.glyphset = new GlyphSet(app);
+    this.entries = new Map(); // font glyph id -> { lid, adv }
+    this.bytes = 0; // uploaded bitmap bytes, for the LRU budget
+  }
+
+  /** number of bits per glyph needed to address this page's ids */
+  get bits() {
+    return this.entries.size <= 256 ? 8 : 16;
+  }
+
+  /**
+   * Ensure all glyphs of a shaped run are uploaded; returns nothing.
+   * New glyphs are rasterized and sent in a single AddGlyphs request.
+   */
+  ensure(glyphs) {
+    let batch = null;
+    for (const g of glyphs) {
+      if (this.entries.has(g.id)) continue;
+      const lid = this.entries.size;
+      if (lid >= 65536) {
+        // 2^16 distinct glyphs at one size — not reachable in practice
+        // (fonts cap at 65535 glyphs) but fail loudly rather than corrupt
+        throw new Error('glyph page overflow');
+      }
+      const adv = Math.round(this.font.advanceOf(g.id, this.size));
+      const bitmap = this.font.rasterize(g.id, this.size);
+      this.entries.set(g.id, { lid, adv });
+      if (!batch) batch = [];
+      batch.push({
+        id: lid,
+        width: bitmap ? bitmap.width : 0,
+        height: bitmap ? bitmap.height : 0,
+        // XRender GLYPHINFO places the image at origin - (x, y); node-x11
+        // packs -x and +y, so x here is the bitmap's left bearing and y its
+        // (negated, y-down) top — i.e. the ascent above the baseline
+        x: bitmap ? bitmap.left : 0,
+        y: bitmap ? -bitmap.top : 0,
+        // node-x11 AddGlyphs expects 26.6 fixed point and divides by 64
+        offX: adv * 64,
+        offY: 0,
+        image: bitmap ? bitmap.data : Buffer.alloc(0)
+      });
+      this.bytes += bitmap ? bitmap.data.length : 0;
+    }
+    if (batch) this.glyphset.addGlyphs(batch);
+  }
+
+  entry(fontGlyphId) {
+    return this.entries.get(fontGlyphId);
+  }
+
+  /** free the server-side glyphset (LRU eviction / shutdown) */
+  destroy() {
+    this.glyphset.destroy();
+    this.entries.clear();
+    this.bytes = 0;
+  }
+}
+
+/** per-app page cache: pages (and their server glyphsets) are shared by all
+ *  windows/pixmaps of a connection. Access refreshes LRU order. */
+export function getGlyphPage(app, font, size) {
+  if (!app._glyphPages) app._glyphPages = new Map();
+  const key = `${font.key}@${size}`;
+  let page = app._glyphPages.get(key);
+  if (page) {
+    // Map iteration order is insertion order — re-insert to mark recent
+    app._glyphPages.delete(key);
+  } else {
+    page = new GlyphPage(app, font, size);
+  }
+  app._glyphPages.set(key, page);
+  return page;
+}
+
+/**
+ * Evict least-recently-used glyph pages until uploaded bitmaps fit the
+ * policy budget. `inUse` pages (referenced by requests queued this draw)
+ * are never evicted. Freeing is safe request-ordering-wise: FreeGlyphSet is
+ * queued after any CompositeGlyphs already issued on this connection.
+ */
+export function trimGlyphPages(app, policy = policyOf(app), inUse = null) {
+  const pages = app._glyphPages;
+  if (!pages) return;
+  let total = 0;
+  for (const page of pages.values()) total += page.bytes;
+  for (const [key, page] of pages) {
+    if (total <= policy.cacheBytes) break;
+    if (inUse && inUse.has(page)) continue;
+    pages.delete(key);
+    total -= page.bytes;
+    page.destroy();
+  }
+}
+
+const MAX_ELT_GLYPHS = 254; // 255 is the glyphset-switch marker
+
+/**
+ * Encode positioned glyphs into a minimal CompositeGlyphs elt list.
+ *
+ * `items` are visual-order glyphs with absolute integer device positions:
+ *   { gs: glyphsetId, lid: localGlyphId, adv: storedIntAdvance, x, y }
+ *
+ * The encoder tracks the server-side pen (which auto-advances by each
+ * glyph's stored `adv`) and emits position data only when the desired
+ * position deviates from it — i.e. at the start, on kerning/mark offsets,
+ * on subpixel-rounding drift, and at glyphset switches. Plain text costs
+ * 1 byte per glyph (8-bit ids) plus a single 8-byte elt header.
+ *
+ * @returns {{ gsid, bits, elts }|null} arguments for Render.CompositeGlyphs;
+ *   elts strings ride on the initial pen, arrays are [dx, dy, string],
+ *   numbers switch glyphsets (node-x11 wire format). Null when empty.
+ */
+export function encodeGlyphItems(items, bits) {
+  if (items.length === 0) return null;
+  const elts = [];
+  const gsid = items[0].gs;
+  let curGs = gsid;
+  let penX = 0;
+  let penY = 0;
+  let cur = null; // { dx, dy, str }
+
+  for (const item of items) {
+    if (item.gs !== curGs) {
+      if (cur) {
+        elts.push([cur.dx, cur.dy, cur.str]);
+        cur = null;
+      }
+      elts.push(item.gs);
+      curGs = item.gs;
+    }
+    if (!cur || item.x !== penX || item.y !== penY || cur.str.length >= MAX_ELT_GLYPHS) {
+      if (cur) elts.push([cur.dx, cur.dy, cur.str]);
+      cur = { dx: item.x - penX, dy: item.y - penY, str: '' };
+      penX = item.x;
+      penY = item.y;
+    }
+    cur.str += String.fromCharCode(item.lid);
+    penX += item.adv;
+  }
+  if (cur) elts.push([cur.dx, cur.dy, cur.str]);
+  return { gsid, bits, elts };
+}
+
+/**
+ * Compute device positions for shaped runs — the single source of truth for
+ * where each glyph's origin lands, shared by the renderer and by tests that
+ * verify server output pixel-by-pixel.
+ *
+ * `positioned` is an array of { run, x, y } where `run` comes from
+ * Font.shape()/shapeText() (already in visual order) and x/y is the run's
+ * baseline origin in device space.
+ *
+ * @returns {Array<{run, glyph, x, y}>} integer glyph-origin positions
+ */
+export function positionGlyphs(positioned) {
+  const out = [];
+  for (const { run, x, y } of positioned) {
+    let cursor = x;
+    for (const g of run.glyphs) {
+      out.push({ run, glyph: g, x: Math.round(cursor + g.dx), y: Math.round(y - g.dy) });
+      cursor += g.ax;
+    }
+  }
+  return out;
+}
+
+/**
+ * Decide how a (face, size) renders: cached bitmap glyphs or per-draw
+ * trapezoids. See DEFAULT_TEXT_POLICY for the reasoning; the middle band
+ * additionally watches a small ring of recently drawn sizes per face — a
+ * continuously animated size (zoom/pinch) never repeats, so it routes to
+ * vector where per-size caches would leak a glyphset every frame.
+ *
+ * @returns {'bitmap'|'vector'}
+ */
+export function routeGlyphSize(app, font, size, policy = policyOf(app)) {
+  if (size <= policy.bitmapMax) return 'bitmap';
+  if (size > policy.vectorFrom) return 'vector';
+
+  if (!app._sizeRings) app._sizeRings = new Map();
+  let ring = app._sizeRings.get(font.key);
+  if (!ring) {
+    ring = [];
+    app._sizeRings.set(font.key, ring);
+  }
+  const reused = ring.includes(size);
+  // dedupe consecutive entries so one frame drawing many runs at one size
+  // occupies a single slot — the ring then spans ~8 distinct frames
+  if (ring[ring.length - 1] !== size) {
+    ring.push(size);
+    if (ring.length > 8) ring.shift();
+  }
+
+  if (!Number.isInteger(size)) return 'vector';
+  if (!reused && new Set(ring).size >= 6) return 'vector'; // size churn: animating
+  return 'bitmap';
+}
+
+/**
+ * Draw shaped runs. Routes each run through the bitmap path (cached
+ * server-side glyphs, one CompositeGlyphs request) or the vector path
+ * (one AddTraps + Composite through a shared scratch a8 mask) according to
+ * `routeGlyphSize`.
+ *
+ * @param {App} app
+ * @param {number} op Render.PictOp
+ * @param {number} srcId source picture (fill color/gradient)
+ * @param {number} dstId destination picture
+ * @param {Array<{run, x, y}>} positioned visual-order runs with baseline origins
+ */
+export function drawGlyphRuns(app, op, srcId, dstId, positioned) {
+  const policy = policyOf(app);
+  let bitmap = positioned;
+  let vector = null;
+  for (let i = 0; i < positioned.length; i++) {
+    const { run } = positioned[i];
+    if (routeGlyphSize(app, run.font, run.size, policy) === 'vector') {
+      if (!vector) {
+        vector = [];
+        bitmap = positioned.slice(0, i);
+      }
+      vector.push(positioned[i]);
+    } else if (vector) {
+      bitmap.push(positioned[i]);
+    }
+  }
+  if (bitmap.length) drawBitmapGlyphRuns(app, op, srcId, dstId, bitmap, policy);
+  if (vector) drawVectorGlyphRuns(app, op, srcId, dstId, vector);
+}
+
+function drawBitmapGlyphRuns(app, op, srcId, dstId, positioned, policy) {
+  const Render = app.display.Render;
+  const items = [];
+  let bits = 8;
+  const pages = new Map();
+  for (const { run } of positioned) {
+    const page = getGlyphPage(app, run.font, run.size);
+    page.ensure(run.glyphs);
+    pages.set(run, page);
+  }
+  for (const page of pages.values()) {
+    if (page.bits > bits) bits = page.bits;
+  }
+  for (const pos of positionGlyphs(positioned)) {
+    const page = pages.get(pos.run);
+    const e = page.entry(pos.glyph.id);
+    items.push({ gs: page.glyphset.id, lid: e.lid, adv: e.adv, x: pos.x, y: pos.y });
+  }
+  const encoded = encodeGlyphItems(items, bits);
+  if (!encoded) return;
+  // srcX/srcY align the source with the FIRST glyph's origin (RENDER spec);
+  // passing that origin itself makes source coordinates equal destination
+  // coordinates, so gradient fill styles line up with canvas space
+  Render.CompositeGlyphs(
+    encoded.bits,
+    op,
+    srcId,
+    dstId,
+    0,
+    encoded.gsid,
+    items[0].x,
+    items[0].y,
+    encoded.elts
+  );
+  trimGlyphPages(app, policy, new Set(pages.values()));
+}
+
+// AddTraps length field is a plain 16-bit request length (no BigReq in
+// node-x11's encoder): stay well under 65535 4-byte units per request
+const MAX_TRAPS_PER_REQUEST = 6000;
+
+/**
+ * Vector glyph path (issue #45): flatten outlines at the exact (fractional)
+ * size, trapezoidate, accumulate every glyph of the draw into one scratch a8
+ * mask with a single batched AddTraps, then one Composite to the target.
+ * Nothing is cached server-side, so continuously animated sizes cost no
+ * cache memory; wire bytes scale with outline complexity (~√size), which
+ * beats size²-scaling bitmap uploads above ~128-256px.
+ *
+ * Positions are intentionally NOT rounded to whole pixels — fractional
+ * advances and origins keep zoom animations smooth.
+ */
+function drawVectorGlyphRuns(app, op, srcId, dstId, positioned) {
+  // unrounded glyph origins + ink bounding box
+  const placed = [];
+  let minX = Infinity;
+  let minY = Infinity;
+  for (const { run, x, y } of positioned) {
+    let cursor = x;
+    for (const g of run.glyphs) {
+      const gx = cursor + g.dx;
+      const gy = y - g.dy;
+      cursor += g.ax;
+      const e = run.font.glyphExtents(g.id, run.size);
+      if (!Number.isFinite(e.minX) || e.maxX <= e.minX) continue; // blank glyph
+      placed.push({ run, glyph: g, x: gx, y: gy });
+      if (gx + e.minX < minX) minX = gx + e.minX;
+      if (gy + e.minY < minY) minY = gy + e.minY;
+    }
+  }
+  if (placed.length === 0) return;
+
+  const bx = Math.floor(minX) - 1;
+  const by = Math.floor(minY) - 1;
+
+  const traps = [];
+  for (const p of placed) {
+    trapezoidize(p.run.font.outline(p.glyph.id, p.run.size), p.x - bx, p.y - by, traps);
+  }
+  compositeTraps(app, op, srcId, dstId, traps, bx, by);
+}
+
+/**
+ * Rasterize trapezoids (relative to (bx, by) device coordinates) into the
+ * shared scratch a8 mask with batched AddTraps requests, then Composite the
+ * source through it onto the destination. Shared by the vector glyph path
+ * and by widgets that fill arbitrary outlines (e.g. TeX radicals).
+ *
+ * When bx/by are omitted they are derived from the trapezoid bounds (the
+ * trap coordinates are then treated as absolute device coordinates).
+ */
+export function compositeTraps(app, op, srcId, dstId, traps, bx, by) {
+  if (traps.length === 0) return;
+  const Render = app.display.Render;
+
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  if (bx === undefined) {
+    let minX = Infinity;
+    let minY = Infinity;
+    for (let i = 0; i < traps.length; i += 6) {
+      if (traps[i] < minX) minX = traps[i];
+      if (traps[i + 3] < minX) minX = traps[i + 3];
+      if (traps[i + 1] > maxX) maxX = traps[i + 1];
+      if (traps[i + 4] > maxX) maxX = traps[i + 4];
+      if (traps[i + 2] < minY) minY = traps[i + 2];
+      if (traps[i + 5] > maxY) maxY = traps[i + 5];
+    }
+    bx = Math.floor(minX);
+    by = Math.floor(minY);
+    const shifted = new Array(traps.length);
+    for (let i = 0; i < traps.length; i += 6) {
+      shifted[i] = traps[i] - bx;
+      shifted[i + 1] = traps[i + 1] - bx;
+      shifted[i + 2] = traps[i + 2] - by;
+      shifted[i + 3] = traps[i + 3] - bx;
+      shifted[i + 4] = traps[i + 4] - bx;
+      shifted[i + 5] = traps[i + 5] - by;
+    }
+    traps = shifted;
+    maxX -= bx;
+    maxY -= by;
+  } else {
+    for (let i = 0; i < traps.length; i += 6) {
+      if (traps[i + 1] > maxX) maxX = traps[i + 1];
+      if (traps[i + 4] > maxX) maxX = traps[i + 4];
+      if (traps[i + 5] > maxY) maxY = traps[i + 5];
+    }
+  }
+  const bw = Math.max(1, Math.ceil(maxX));
+  const bh = Math.max(1, Math.ceil(maxY));
+
+  const mask = scratchMask(app, bw, bh);
+  Render.FillRectangles(Render.PictOp.Src, mask.picture.id, [0, 0, 0, 0], [0, 0, bw, bh]);
+  for (let i = 0; i < traps.length; i += MAX_TRAPS_PER_REQUEST * 6) {
+    Render.AddTraps(mask.picture.id, 0, 0, traps.slice(i, i + MAX_TRAPS_PER_REQUEST * 6));
+  }
+  // src coords = dst coords (see drawBitmapGlyphRuns) so gradients line up
+  Render.Composite(op, srcId, mask.picture.id, dstId, bx, by, 0, 0, bx, by, bw, bh);
+  releaseScratchMask(app);
+}
+
+// One connection-wide scratch a8 pixmap for trap masks, grown as needed and
+// dropped again when a huge draw would otherwise pin megabytes server-side.
+const SCRATCH_KEEP_AREA = 1 << 21; // ~2MB of a8
+
+function scratchMask(app, w, h) {
+  let s = app._trapScratch;
+  if (!s || s.width < w || s.height < h) {
+    if (s) {
+      s.picture.destroy();
+      s.pixmap.destroy();
+    }
+    const width = Math.max(w, s ? s.width : 0);
+    const height = Math.max(h, s ? s.height : 0);
+    const pixmap = new Pixmap(app, { depth: 8, width, height });
+    const picture = new Picture(app, { drawable: pixmap, format: app.display.Render.a8 });
+    s = { pixmap, picture, width, height };
+    app._trapScratch = s;
+  }
+  return s;
+}
+
+function releaseScratchMask(app) {
+  const s = app._trapScratch;
+  if (s && s.width * s.height > SCRATCH_KEEP_AREA) {
+    s.picture.destroy();
+    s.pixmap.destroy();
+    app._trapScratch = null;
+  }
+}