ntk 8.8.1 → 8.9.0

package/lib/app.js

@@ -5,12 +5,15 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glCapabilities,
   glError,
   nativeRefreshRate,
   requestedSamples,
+  requestedStencil,
   resolveGLPolicy,
-  warnDirectSamples
+  warnDirectSamples,
+  warnDirectStencil
 } from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
@@ -637,6 +640,14 @@ export default class App {
    * request that cannot be met also warns once per connection, because an
    * aliased edge is otherwise found months later in a screenshot.
    *
+   * `stencilSize` is answered the same way, and matters more: a stencil test
+   * against a framebuffer with no stencil buffer passes everywhere, so
+   * stencil-based drawing renders wrong instead of failing. `STENCIL_SIZE`
+   * becomes the CGL context's stencil size on macOS (8 when the spec names
+   * none, as the Cocoa backend's surfaces have); the dri3 flavor has nothing
+   * to ask EGL with, so it answers 0 and a request for more warns once
+   * (`directStencilSize` in lib/gl.js).
+   *
    * @param {object} [spec] GLX attributes, e.g. `{ DEPTH_SIZE: 24 }`
    */
   async chooseGLConfig(spec = {}) {
@@ -659,6 +670,12 @@ export default class App {
     // answer honestly below rather than dropping the attribute (issue #341)
     const wantSamples = requestedSamples(spec);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(this, caps.flavor, wantSamples);
+    // the same for stencil, where it matters more: a flavor that cannot ask
+    // for a stencil buffer answers 0, because a stencil test against no
+    // buffer passes everywhere and the draw code would never find out
+    const wantStencil = requestedStencil(spec);
+    const stencilSize = directStencilSize(caps.flavor, wantStencil);
+    if (wantStencil > stencilSize) warnDirectStencil(this, caps.flavor, wantStencil);
 
     return {
       backend: 'direct',
@@ -671,6 +688,9 @@ export default class App {
       class: 4, // TrueColor; the only class these buffers can be read as
       doubleBuffer: true, // a swap chain, always
       depthSize: spec.DEPTH_SIZE ?? 16,
+      // what the context will ask for (8 on appledri unless the spec says),
+      // carried here so the spec reaches getContext with the rest of it
+      stencilSize,
       // no flavor can allocate a multisampled window buffer yet; said out
       // loud so a caller can supersample instead of assuming MSAA
       samples: DIRECT_SAMPLES,

package/lib/fontconfig.js

@@ -133,8 +133,67 @@ function fcMatchError(err) {
   return err;
 }
 
+/**
+ * macOS's own face for a CSS generic family that fontconfig answers there
+ * with the wrong script's face, keyed by the generic.
+ *
+ * Only `sans-serif` is here, because it is the only generic fontconfig
+ * resolves to a CJK face on a Mac (see `platformFamilies`). `serif` and
+ * `monospace` land on PT Serif and Andale Mono, both of which set Latin,
+ * Cyrillic and Greek at their own widths.
+ */
+const DARWIN_GENERICS = new Map([['sans-serif', 'Helvetica']]);
+
+/**
+ * A family list with macOS's own face for a generic named ahead of it — on
+ * macOS only, and only for the generics in `DARWIN_GENERICS`. Everywhere
+ * else the list goes to fc-match exactly as it came.
+ *
+ * Homebrew's fontconfig (2.18) ships 48-guessfamily.conf, which tags a query
+ * naming a generic with that generic, and under it a `sans-serif` query
+ * ranks every face with "Sans" in its name ahead of all of 60-latin.conf's
+ * preferences — Verdana, Arial and Helvetica come in past the hundredth
+ * candidate. So `fc-match sans-serif` answers with whichever "…Sans…" face
+ * ranks first, and on a Mac that is Hiragino Sans: a Japanese face whose
+ * Cyrillic, Greek, `…` and `—` are full-width. "Мост" set in it is four
+ * em-wide cells, and CoreText sets it the same way — the advances are the
+ * font's own, so what is wrong is the face, not the shaping. Without that
+ * one file (XQuartz's fontconfig ships without it) the same query answers
+ * Verdana.
+ *
+ * Browsers never ask fontconfig on macOS, and all of them give `sans-serif`
+ * Helvetica. Naming it first does the same here, and the generic stays
+ * after it, so a codepoint Helvetica lacks still falls back through
+ * fontconfig's sans-serif list — CJK to Hiragino, as before.
+ *
+ * @param {string} family CSS-style family list, as FontManager hands it over
+ * @param {string} [platform] `process.platform`; a parameter so that a test
+ *   can ask for either answer on any machine
+ * @returns {string} the family list to hand fc-match
+ */
+export function platformFamilies(family, platform = globalThis.process?.platform) {
+  if (platform !== 'darwin') return family;
+  const names = String(family)
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+  const lower = names.map((name) => name.replace(/^["']|["']$/g, '').toLowerCase());
+  const out = [];
+  let changed = false;
+  for (let i = 0; i < names.length; i++) {
+    const face = DARWIN_GENERICS.get(lower[i]);
+    // a list that already names the face ahead of the generic needs nothing
+    if (face && !lower.slice(0, i).includes(face.toLowerCase())) {
+      out.push(face);
+      changed = true;
+    }
+    out.push(names[i]);
+  }
+  return changed ? out.join(',') : family;
+}
+
 function patternFor({ family, weight, style }) {
-  let fc = family || 'sans-serif';
+  let fc = platformFamilies(family || 'sans-serif');
   const fcWeight = normalizeWeight(weight);
   if (fcWeight !== undefined) fc += `:weight=${fcWeight}`;
   if (style && style.includes('italic')) fc += ':slant=italic';

package/lib/gl.js

@@ -535,6 +535,78 @@ export function warnDirectSamples(app, flavor, wanted) {
   );
 }
 
+/**
+ * The stencil bits a CGL context asks for when the config names no size:
+ * eight, what the Cocoa backend's GL surfaces carry (DEPTH24_STENCIL8), so
+ * a window on the `appledri` flavor has the same buffers whichever of the
+ * two macOS paths draws it. A stencil buffer costs next to nothing, and the
+ * failure without one is silent: a stencil test with no buffer behind it
+ * passes everywhere, so a stencil-then-cover fill does not fail — it fills
+ * its whole cover quad.
+ */
+export const DEFAULT_STENCIL_SIZE = 8;
+
+/**
+ * The stencil size a spec or config asks for, read the way the depth size
+ * is: `stencilSize` (a config `chooseGLConfig` answered) before
+ * `STENCIL_SIZE` (GLX's vocabulary). `undefined` when it names neither,
+ * which means "the flavor's default" rather than 0 — an explicit 0 asks for
+ * no stencil buffer and is honoured as such. `null` is GLX's "don't care"
+ * and reads as unnamed too.
+ */
+export function requestedStencil(spec = {}) {
+  const bits = spec.stencilSize ?? spec.STENCIL_SIZE;
+  if (bits === undefined || bits === null) return undefined;
+  return Number(bits) || 0;
+}
+
+/**
+ * The stencil bits a direct-backend window gets for a request, per flavor —
+ * the one place that decides it, as `DIRECT_SAMPLES` is for samples.
+ *
+ * - `appledri`: what was asked, `DEFAULT_STENCIL_SIZE` when nothing was. It
+ *   travels to `kCGLPFAStencilSize` on the CGL pixel format, which CGL
+ *   treats as a minimum.
+ * - `dri3`: 0, whatever was asked. x11-dri's `Gpu` builds its EGLConfig from
+ *   the colour format and a depth size and takes no stencil size, so none is
+ *   asked for — and EGL sorts configs smallest stencil first, so assume
+ *   none. There is nothing here to ask with; what can be done is say so
+ *   (`warnDirectStencil`). When the addon grows the option, this becomes the
+ *   request.
+ */
+export function directStencilSize(flavor, wanted) {
+  if (flavor === 'appledri') return wanted ?? DEFAULT_STENCIL_SIZE;
+  return 0;
+}
+
+/**
+ * Say — once per connection, on the console — that a stencil request cannot
+ * be met on this flavor.
+ *
+ * Unlike a missing sample buffer this is not a downgrade that merely looks
+ * worse: a stencil test against a framebuffer with no stencil buffer passes
+ * everywhere, so draw code built on it renders wrong instead of failing, and
+ * this warning and the `stencilSize` field are the only signals it gets.
+ */
+export function warnDirectStencil(app, flavor, wanted) {
+  if (app._warnedDirectStencil) return;
+  app._warnedDirectStencil = true;
+  console.warn(
+    `ntk: this GL request asks for STENCIL_SIZE=${wanted}, and the direct backend` +
+      `${flavor ? ` (${flavor} flavor)` : ''} cannot give its window a stencil buffer, so it has ` +
+      'stencilSize: 0 — and a stencil test with no buffer behind it passes everywhere.\n' +
+      '\n' +
+      '  The stencil size belongs to the EGLConfig x11-dri builds one layer below\n' +
+      '  ntk, and its Gpu takes no such option yet — there is nothing here to ask with.\n' +
+      '\n' +
+      '  Branch on config.stencilSize (or gl.stencilSize) rather than on having asked.\n' +
+      '  For a stencil buffer today: draw into a framebuffer of your own with a\n' +
+      '  DEPTH24_STENCIL8 renderbuffer attached, or use indirect GLX, where\n' +
+      "  STENCIL_SIZE picks an fbconfig that has one (glPolicy: 'indirect').\n" +
+      '  See docs/context-gles.md#stencil.'
+  );
+}
+
 /**
  * The backend `getContext('opengl')` should use right now, synchronously.
  *

package/lib/glx.js

@@ -227,11 +227,12 @@ function matchLegacy(configs, spec) {
  *   `null` means "don't care". `screen` picks the X screen (default 0),
  *   `visual` pins a specific visual id and skips the search.
  * @returns {Promise<{visual: number, depth: number, class: number,
- *   doubleBuffer: boolean, depthSize: number, samples: number|null,
- *   fbconfig: number|null, config: object}>} `samples` is the colour
- *   samples per pixel the chosen config has — 0 for no multisampling, and
- *   `null` only in the pinned-`visual` case, where no fbconfig was looked
- *   at to know.
+ *   doubleBuffer: boolean, depthSize: number, stencilSize: number|null,
+ *   samples: number|null, fbconfig: number|null, config: object}>}
+ *   `samples` is the colour samples per pixel the chosen config has — 0 for
+ *   no multisampling — and `stencilSize` its stencil bits; both are `null`
+ *   only in the pinned-`visual` case, where no fbconfig was looked at to
+ *   know.
  */
 export async function chooseGLXConfig(app, spec = {}) {
   const GLX = app.display.GLX;
@@ -268,6 +269,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       depthSize: toNumber(want.DEPTH_SIZE) || 0,
       // the caller pinned the visual, so nothing was chosen and no fbconfig
       // was read: unknown, which is not the same claim as "none"
+      stencilSize: null,
       samples: null,
       screen: screenNum,
       fbconfig: null,
@@ -286,6 +288,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.DOUBLEBUFFER,
       depthSize: cfg.DEPTH_SIZE || 0,
+      stencilSize: cfg.STENCIL_SIZE || 0,
       samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: cfg.FBCONFIG_ID,
@@ -307,6 +310,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.doubleBufferMode,
       depthSize: cfg.depthBits || 0,
+      stencilSize: cfg.stencilBits || 0,
       samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: null,

package/lib/renderingcontext_cgl.js

@@ -47,9 +47,11 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glError,
   loadDriAddon,
   requestedSamples,
+  requestedStencil,
   warnDirectSamples
 } from './gl.js';
 
@@ -134,6 +136,13 @@ does not make it retroactive. Either:
     const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, 'appledri', wantSamples);
 
+    /**
+     * Stencil bits the context asked CGL for: the config's `stencilSize` /
+     * `STENCIL_SIZE`, and 8 when it names none (`directStencilSize`). CGL
+     * takes the size as a minimum, so the buffer has at least this many.
+     */
+    this.stencilSize = directStencilSize('appledri', requestedStencil(config));
+
     this._screen = config.screen ?? 0;
     this._clientId = caps.appleClientId ?? dri.apple.clientId();
 
@@ -145,7 +154,11 @@ does not make it retroactive. Either:
     // covered (docs/context-gles.md#macos).
     try {
       this.ctx = new dri.apple.Context({
-        depthSize: config.depthSize ?? config.DEPTH_SIZE ?? 16
+        depthSize: config.depthSize ?? config.DEPTH_SIZE ?? 16,
+        // Without this the pixel format has no stencil buffer at all, and GL
+        // raises no error over it: a stencil test against a missing buffer
+        // passes everywhere, so a stencil-then-cover fill covers its whole quad.
+        stencilSize: this.stencilSize
       });
     } catch (err) {
       throw glError(

package/lib/renderingcontext_gles.js

@@ -21,10 +21,13 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glError,
   loadDriAddon,
   requestedSamples,
-  warnDirectSamples
+  requestedStencil,
+  warnDirectSamples,
+  warnDirectStencil
 } from './gl.js';
 import { GLSwapchain } from './glswapchain.js';
 
@@ -116,6 +119,17 @@ does not make it retroactive. Either:
     const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, caps.flavor, wantSamples);
 
+    /**
+     * Stencil bits the window's buffers have: 0 on this flavor, whatever the
+     * config asks for, because x11-dri's `Gpu` takes no stencil size to pass
+     * on (`directStencilSize`). A request for one is answered the way a
+     * sample count is — once, out loud — because a stencil test with no
+     * buffer behind it passes everywhere rather than failing.
+     */
+    const wantStencil = requestedStencil(config);
+    this.stencilSize = directStencilSize('dri3', wantStencil);
+    if (wantStencil > this.stencilSize) warnDirectStencil(app, 'dri3', wantStencil);
+
     const policy = app.glPolicy;
     this.gpu = sharedGpu(app, dri, {
       format: depth === 32 ? dri.FORMAT.ARGB8888 : dri.FORMAT.XRGB8888,

package/lib/text/fontmanager.js

@@ -43,6 +43,26 @@ function opticalSizeFor(style) {
   return typeof size === 'number' && Number.isFinite(size) ? size : undefined;
 }
 
+/**
+ * Cache-key fragment for what shapes a run beyond its face and size: the
+ * OpenType features (either form fontkit takes — an array of tags, or an
+ * object of tag → on/off), the language and the letter spacing. `''` for a
+ * style with none of them, which is nearly every style.
+ */
+function shapingKeyOf(style) {
+  const { features, language, letterSpacing } = style;
+  if (!features && !language && !letterSpacing) return '';
+  let feats = '';
+  if (Array.isArray(features)) feats = [...features].sort().join(',');
+  else if (features) {
+    feats = Object.keys(features)
+      .sort()
+      .map((tag) => `${tag}=${features[tag] ? 1 : 0}`)
+      .join(',');
+  }
+  return `${feats}|${language ?? ''}|${letterSpacing || 0}`;
+}
+
 /** Cache-key fragment for the optical size, `''` when the axis is left alone. */
 function opticalKeyOf(style) {
   return opticalSizeFor(style) ?? '';
@@ -346,11 +366,16 @@ export default class FontManager {
     // variations and optical-size fragments only earn their keep on the
     // family path — where two points of one axis would otherwise share a
     // shaped run, and the second would be drawn with the first's advances.
+    // Features, language and spacing change the glyphs a word shapes to, so
+    // they are part of the key on both paths: without them a word shaped once
+    // plain answered every later request for it with the plain glyphs, and a
+    // `tnum` asked for after that point was silently ignored.
+    const shaping = shapingKeyOf(style);
     const key = font
-      ? `${font.key}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`
+      ? `${font.key}|${style.size}|${style.weight}|${style.style}|${shaping}|${levelsKey}|${text}`
       : `${style.family}|${style.size}|${style.weight}|${style.style}|${variationsKeyOf(
           style.variations
-        )}|${opticalKeyOf(style)}|${levelsKey}|${text}`;
+        )}|${opticalKeyOf(style)}|${shaping}|${levelsKey}|${text}`;
     let shaped = this._shapeCache.get(key);
     if (shaped) {
       // Map iterates in insertion order: re-inserting a hit moves it to the
@@ -390,13 +415,10 @@ export default class FontManager {
    * levels cannot recover it (RTL text in an RTL paragraph carries level 1,
    * which reads as an even base) and start/end alignment depends on it.
    *
-   * `features` and `language` change shaped output but are not part of the
-   * memo key (styles reaching it via TextLayout never carry them into the
-   * key either), so a style with either shapes uncached rather than
-   * poisoning entries other callers share.
+   * `features`, `language` and `letterSpacing` are part of the memo key, so
+   * a style with any of them has entries of its own.
    */
   _shapeCachedWhole(text, style) {
-    if (style.features || style.language) return shapeText(this, text, style);
     const emb = embeddingLevels(text, style.direction);
     const baseLevel = emb.paragraphs.length ? emb.paragraphs[0].level : 0;
     const shaped = this._shapeCached(text, style, normalizedLevels(emb.levels, 0, text.length));

package/lib/text/layout.js

@@ -21,7 +21,8 @@ function isWsGlyph(g) {
  * across relayouts), and bidi reordering is applied per line (UAX#9 L2).
  *
  * Content is a plain string or an array of spans
- * `{ text, family?, size?, weight?, style?, features?, language?, color? }`;
+ * `{ text, family?, size?, weight?, style?, features?, language?,
+ * letterSpacing?, color? }`;
  * span fields override the base style. Options:
  *
  * - `maxWidth` — target container width (default: unlimited)
@@ -72,6 +73,7 @@ export class TextLayout {
         textRendering: s.textRendering ?? style.textRendering,
         features: s.features ?? style.features,
         language: s.language ?? style.language,
+        letterSpacing: s.letterSpacing ?? style.letterSpacing,
         color: s.color ?? style.color ?? null
       };
       merged.font = s.font ?? style.font ?? fonts.match(merged.family, merged);
@@ -322,7 +324,9 @@ export class TextLayout {
       const m = TRAILING_WS.exec(last.text);
       if (m) {
         const spaceGlyph = last.span.font.fk.glyphForCodePoint(0x20);
-        wsWidth = m[0].length * spaceGlyph.advanceWidth * last.span.font.scale(last.span.size);
+        const spacing = Number.isFinite(last.span.letterSpacing) ? last.span.letterSpacing : 0;
+        wsWidth =
+          m[0].length * (spaceGlyph.advanceWidth * last.span.font.scale(last.span.size) + spacing);
       }
     }
     return { fragments, width, wsWidth, required, start, end };

package/lib/text/shape.js

@@ -45,6 +45,62 @@ export function normalizedLevels(levels, start, end) {
   return Array.prototype.slice.call(levels, start, end).join(',');
 }
 
+/**
+ * The ligatures a font applies by default and a reader can do without. CSS
+ * turns them off wherever letters are spaced apart, since an `fi` drawn as
+ * one glyph cannot be spaced in its middle: the gap would open on one side of
+ * the pair and not the other. Required ones — Arabic joining forms, `rlig` —
+ * stay on.
+ */
+const OPTIONAL_LIGATURES = ['liga', 'clig', 'dlig', 'hlig'];
+
+/**
+ * The features a letter-spaced run shapes with: the optional ligatures off,
+ * underneath whatever the caller asked for — a style that names `liga`
+ * itself still gets it. `features` is either form fontkit takes, an array of
+ * tags to turn on or an object of tag → on/off.
+ */
+/**
+ * A copy of `features` for fontkit, which **adds to the object it is handed**
+ * — `rvrn` and the like, as it plans the shaping. Handed a caller's own
+ * object that is a style quietly growing keys, which changes the memo key it
+ * is filed under next time, and a frozen one throws.
+ */
+function ownFeatures(features) {
+  if (!features) return features;
+  return Array.isArray(features) ? [...features] : { ...features };
+}
+
+function spacedFeatures(features) {
+  const off = Object.fromEntries(OPTIONAL_LIGATURES.map((tag) => [tag, false]));
+  if (!features) return off;
+  if (Array.isArray(features)) {
+    for (const tag of features) off[tag] = true;
+    return off;
+  }
+  return { ...off, ...features };
+}
+
+/**
+ * Space a shaped run's glyphs apart by `spacing` px: added to the advance of
+ * every glyph that has one, so a combining mark keeps sitting on its base.
+ * An rtl run stores its glyphs in visual order, and its spacing belongs on
+ * the *reading* side of each glyph — the left — so there the glyph is drawn
+ * that much further along its advance as well.
+ */
+function spaceGlyphs(shaped, spacing) {
+  const rtl = shaped.direction === 'rtl';
+  let width = 0;
+  for (const g of shaped.glyphs) {
+    if (g.ax > 0) {
+      g.ax += spacing;
+      if (rtl) g.dx += spacing;
+    }
+    width += g.ax;
+  }
+  shaped.width = width;
+}
+
 /**
  * Shape a string through the full pipeline:
  *
@@ -61,7 +117,7 @@ export function normalizedLevels(levels, start, end) {
  * @param {FontManager} fonts
  * @param {string} text
  * @param {object} style { font | family/weight/style, size, features,
- *   language, direction: 'ltr'|'rtl'|'auto' }
+ *   language, letterSpacing, direction: 'ltr'|'rtl'|'auto' }
  * @param {ArrayLike<number>} [levels] precomputed embedding levels for `text`
  * @returns {{text, width, baseLevel, runs: Array<{font, size, direction,
  *   level, width, glyphs, text, start, end}>}}
@@ -108,6 +164,11 @@ export function shapeText(fonts, text, style, levels) {
     i += ch.length;
   }
 
+  // px added after every glyph, CSS's `letter-spacing`; 0 leaves the run
+  // exactly as the font shapes it, ligatures and all
+  const spacing = Number.isFinite(style.letterSpacing) ? style.letterSpacing : 0;
+  const features = spacing ? spacedFeatures(style.features) : ownFeatures(style.features);
+
   const runs = [];
   let width = 0;
   for (const item of items) {
@@ -115,9 +176,10 @@ export function shapeText(fonts, text, style, levels) {
     const sub = text.slice(item.start, item.end);
     const shaped = item.font.shape(sub, size, {
       direction,
-      features: style.features,
+      features,
       language: style.language
     });
+    if (spacing) spaceGlyphs(shaped, spacing);
     shaped.level = item.level;
     shaped.text = sub;
     shaped.start = item.start;

package/package.json

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