ntk 5.2.0 → 5.4.0

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/widgets/svgview.js

@@ -202,6 +202,95 @@ function pathBBox(path) {
   return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
 }
 
+/**
+ * How many distinct colours a document actually commits to, decided once at
+ * parse time.
+ *
+ * `mono` means every fill and stroke that reaches a shape is `none` or the
+ * *same* paint — one literal colour, or `currentColor` throughout. Such a
+ * drawing is really a coverage mask plus a colour, so a caller can render it
+ * once and recolour it on every draw. `multi` is everything else: a second
+ * distinct paint, or a gradient/pattern reference, whose colours belong to
+ * the drawing rather than to the UI around it.
+ *
+ * Opacity does not enter into it: `opacity`, `fill-opacity` and
+ * `stroke-opacity` scale coverage, which a mask carries perfectly well.
+ *
+ * The walk mirrors `_style` and `_renderNode` — fill and stroke inherit,
+ * inline `style` beats the presentation attribute, the initial fill is black
+ * and the initial stroke is none, `<line>` never fills, `<use>` paints its
+ * target with the *use* element's style, and non-rendered subtrees
+ * contribute nothing. It starts at the root's children rather than the root,
+ * because `draw` does: presentation attributes on the root `<svg>` are not
+ * applied, and a scan that applied them would disagree with what is painted.
+ *
+ * @returns {{ kind: 'mono'|'multi', solo: string|null }} `solo` is the one
+ *   paint a `mono` document uses — a colour, or the literal `'currentColor'`
+ *   when the document defers to its caller — and null when nothing paints.
+ */
+function scanPaints(root, ids) {
+  const paints = new Set();
+  let multi = false;
+
+  const paintOf = (node, name, inherited) => {
+    let v = attr(node, name);
+    for (const decl of (node.attribs?.style || '').split(';')) {
+      const idx = decl.indexOf(':');
+      if (idx > 0 && decl.slice(0, idx).trim() === name) v = decl.slice(idx + 1);
+    }
+    if (v === undefined || v === '' || v === 'inherit') return inherited;
+    return String(v).trim();
+  };
+
+  const note = (paint) => {
+    if (paint === 'none') return;
+    if (/^url\(/i.test(paint)) multi = true;
+    else paints.add(paint);
+  };
+
+  const kids = (node, fill, stroke, depth) => {
+    for (const child of node.children || []) {
+      if (child.type === 'tag') visit(child, fill, stroke, depth + 1);
+    }
+  };
+
+  const visit = (node, fill, stroke, depth) => {
+    if (multi || depth > 32) return;
+    const name = tag(node);
+    if (NON_RENDERED.has(name)) return;
+    const f = paintOf(node, 'fill', fill);
+    const s = paintOf(node, 'stroke', stroke);
+    switch (name) {
+      case 'svg':
+      case 'g':
+      case 'a':
+        kids(node, f, s, depth);
+        return;
+      case 'use': {
+        const href = node.attribs?.href || node.attribs?.['xlink:href'] || '';
+        const target = href.startsWith('#') ? ids.get(href.slice(1)) : null;
+        if (!target) return;
+        // <symbol> is non-rendered on its own but renders through <use>
+        if (tag(target) === 'symbol') kids(target, f, s, depth);
+        else visit(target, f, s, depth + 1);
+        return;
+      }
+      case 'text':
+        note(f);
+        return;
+      default:
+        if (name !== 'line') note(f);
+        note(s);
+    }
+  };
+
+  kids(root, INHERITED.fill, INHERITED.stroke, 0);
+  return {
+    kind: multi || paints.size > 1 ? 'multi' : 'mono',
+    solo: paints.size === 1 ? [...paints][0] : null
+  };
+}
+
 /**
  * Widget rendering a static SVG document into a window (or any 2d context
  * via `draw()`). Scripting, CSS stylesheets, filters, masks and external
@@ -213,12 +302,22 @@ export default class SvgView {
     this.theme = { background: 'white', ...(opts.theme || {}) };
     /** fit mode in window mode: 'contain' (default) | 'fill' */
     this.fit = opts.fit || 'contain';
+    /**
+     * What `currentColor` resolves to, for documents that defer their colour
+     * to the surrounding UI the way an icon set does. Per-draw `opts.color`
+     * overrides it; both fall back to the CSS initial value, black.
+     */
+    this.color = opts.color ?? INHERITED.color;
 
     this._root = null;
     this._ids = new Map();
     this.naturalWidth = 0;
     this.naturalHeight = 0;
     this.viewBox = null;
+    /** see `scanPaints`: 'mono' | 'multi', and the single paint of a mono
+     * document — `'currentColor'` when it defers its colour to the caller */
+    this.paintKind = 'mono';
+    this.soloPaint = null;
 
     if (this.window) {
       this._ctx = this.window.getContext('2d');
@@ -263,6 +362,10 @@ export default class SvgView {
     };
     collect(this._root);
 
+    const scanned = scanPaints(this._root, this._ids);
+    this.paintKind = scanned.kind;
+    this.soloPaint = scanned.solo;
+
     const a = this._root.attribs || {};
     const vb = (attr(this._root, 'viewBox') || '')
       .split(/[\s,]+/)
@@ -305,8 +408,15 @@ export default class SvgView {
   /**
    * Draw the document into any 2d context. `w`/`h` default to the
    * document's natural size; the viewBox (when present) is scaled to fit.
+   *
+   * `opts.color` is what `fill="currentColor"` and `stroke="currentColor"`
+   * resolve to for this draw, overriding the view's own `color`. That is how
+   * an icon takes its colour from the UI around it — the document itself
+   * names no colour, so the same parsed document paints in whatever the
+   * caller is using, and a caller caching the result can recolour a cached
+   * `paintKind === 'mono'` drawing without re-rendering it.
    */
-  draw(ctx, x = 0, y = 0, w = this.naturalWidth, h = this.naturalHeight) {
+  draw(ctx, x = 0, y = 0, w = this.naturalWidth, h = this.naturalHeight, opts = {}) {
     if (!this._root) return;
     ctx.save();
     ctx.translate(x, y);
@@ -319,7 +429,13 @@ export default class SvgView {
     } else if (this.naturalWidth > 0 && this.naturalHeight > 0) {
       ctx.scale(w / this.naturalWidth, h / this.naturalHeight);
     }
-    this._renderChildren(this._root, ctx, { ...INHERITED }, 1, 0);
+    this._renderChildren(
+      this._root,
+      ctx,
+      { ...INHERITED, color: opts.color ?? this.color },
+      1,
+      0
+    );
     ctx.restore();
   }