ntk 8.4.0 → 8.5.0

package/lib/app.js

@@ -1,7 +1,7 @@
 import { connectionGone } from './cleanup.js';
 import Clipboard from './clipboard.js';
 import { CursorCache } from './cursor.js';
-import { GLError, backendFor, glCapabilities, glError, resolveGLPolicy } from './gl.js';
+import { GLError, backendFor, glCapabilities, glError, nativeRefreshRate, resolveGLPolicy } from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
@@ -254,6 +254,19 @@ export default class App {
   _probeRefreshRate() {
     this._refreshProbe = null; // in progress; only ever started once
     const X = this.X;
+    // RandR's answer, or the native layer's where RandR has no usable one.
+    // An implausible rate is treated as no answer, not clamped: XQuartz
+    // synthesizes real timing for its canned mode list but fills the current
+    // desktop-sized mode with dot_clock = width * height — exactly 1 Hz — so
+    // the number that describes what is actually driving the panel has to
+    // come from the OS (x11-dri >= 0.6.0, apple.refreshRate()).
+    const plausible = (rate) => rate >= MIN_REFRESH_RATE && rate <= MAX_REFRESH_RATE;
+    const settle = (rate) => {
+      if (!plausible(rate)) rate = nativeRefreshRate();
+      if (!rate || !plausible(rate)) return;
+      this._refreshRate = rate;
+      this._adoptFrameInterval(1000 / rate);
+    };
     // A connection on its way out is one more "no rate to be had". The probe
     // is started lazily by the first window built on this connection, which
     // may be one adopted from an event still arriving as it closes — and
@@ -261,10 +274,10 @@ export default class App {
     // event dispatch has no caller to catch it (issue #321).
     if (connectionGone(X)) return;
     X.require('randr', (err, R) => {
-      if (err || !R) return;
+      if (err || !R) return settle(0);
       const root = this.display.screen[0].root;
       R.GetScreenResourcesCurrent(root, (resourcesError, resources) => {
-        if (resourcesError || !resources?.crtcs?.length) return;
+        if (resourcesError || !resources?.crtcs?.length) return settle(0);
         const modes = new Map(resources.modeinfos.map((mode) => [mode.id, mode]));
         let pending = resources.crtcs.length;
         let best = 0;
@@ -273,9 +286,7 @@ export default class App {
             // a crtc with no mode is one that is switched off
             if (!crtcError && info) best = Math.max(best, modeRate(modes.get(info.mode)));
             if (--pending) return;
-            if (best < MIN_REFRESH_RATE || best > MAX_REFRESH_RATE) return;
-            this._refreshRate = best;
-            this._adoptFrameInterval(1000 / best);
+            settle(best);
           });
         }
       });

package/lib/gl.js

@@ -171,6 +171,22 @@ export function setDriAddon(module) {
   addon = module;
 }
 
+/**
+ * The display's refresh rate asked of the native layer, in Hz, for servers
+ * whose RandR carries no usable timing — XQuartz reports the current
+ * desktop-sized mode with dot_clock = width * height, exactly 1 Hz.
+ * `null` everywhere there is no answer: not darwin, no addon (or one
+ * predating 0.6.0), or a session with no display to ask.
+ */
+export function nativeRefreshRate() {
+  if (globalThis.process?.platform !== 'darwin') return null;
+  try {
+    return loadDriAddon()?.apple?.refreshRate?.() ?? null;
+  } catch {
+    return null;
+  }
+}
+
 const INSTALL_HINT = `Direct rendering needs the optional native addon:
 
   npm install x11-dri

package/lib/renderingcontext_2d.js

@@ -1057,6 +1057,7 @@ class RenderingContext2d {
       textStyle: this._textStyle,
       fontString: this._lastFontString,
       fontVariations: this._fontVariations,
+      fontOpticalSizing: this._fontOpticalSizing,
       textRendering: this._textRendering,
       textAlign: this.textAlign,
       textBaseline: this.textBaseline,
@@ -1086,6 +1087,7 @@ class RenderingContext2d {
     this._textStyle = s.textStyle;
     this._lastFontString = s.fontString;
     this._fontVariations = s.fontVariations;
+    this._fontOpticalSizing = s.fontOpticalSizing;
     this._textRendering = s.textRendering;
     this.textAlign = s.textAlign;
     this.textBaseline = s.textBaseline;
@@ -1249,6 +1251,7 @@ class RenderingContext2d {
     sctx._textStyle = this._textStyle;
     sctx._lastFontString = this._lastFontString;
     sctx._fontVariations = this._fontVariations;
+    sctx._fontOpticalSizing = this._fontOpticalSizing;
     sctx._textRendering = this._textRendering;
     sctx.textAlign = this.textAlign;
     sctx.textBaseline = this.textBaseline;
@@ -4029,6 +4032,7 @@ class RenderingContext2d {
       style: parsed.style,
       size: parsed.size,
       variations: this._fontVariations,
+      opticalSizing: this._fontOpticalSizing,
     };
     style.font = this.window.app.fonts.match(style.family, style);
     this._lastFontString = val;
@@ -4061,6 +4065,32 @@ class RenderingContext2d {
     return this._fontVariations ?? null;
   }
 
+  /**
+   * CSS's `font-optical-sizing`: `'auto'` (the default) sets a face's `opsz`
+   * axis at the size the text is drawn at, `'none'` leaves it wherever the
+   * font file's default is.
+   *
+   * `'auto'` is what the CSS initial value has always been and what a
+   * reader expects — small text set in the family's Text cut, headlines in
+   * its Display cut — so this is the escape hatch, not the switch that
+   * turns the feature on. Reach for it when the size the canvas is drawing
+   * at is not the size the text is *read* at (a canvas scaled up by a
+   * transform, glyphs measured for something else), and pin the axis with
+   * `fontVariationSettings = { opsz: … }` when the answer is a specific
+   * optical size rather than the file's default.
+   *
+   * Order-independent, like `fontVariationSettings`: setting it re-resolves
+   * the face already in force.
+   */
+  set fontOpticalSizing(val) {
+    this._fontOpticalSizing = val === "none" ? "none" : "auto";
+    if (this._textStyle) this.font = this._lastFontString;
+  }
+
+  get fontOpticalSizing() {
+    return this._fontOpticalSizing ?? "auto";
+  }
+
   /**
    * CSS's `text-rendering`: which glyph path this text takes, overriding the
    * size thresholds in `app.textPolicy`.

package/lib/text/fontmanager.js

@@ -20,26 +20,69 @@ function variationsKeyOf(variations) {
     .join(',');
 }
 
+/**
+ * The optical size a style is set at, or `undefined` for "leave `opsz`
+ * alone" — see `instantiate()`.
+ *
+ * `opsz` is the one axis whose coordinate is not a design choice but a
+ * consequence of the size, so it defaults from `size` and needs an escape
+ * hatch for each way that default can be wrong:
+ *
+ * - `opticalSizing: 'none'` is CSS's `font-optical-sizing: none` — the face
+ *   stays at its own default optical size;
+ * - `opticalSize` is the typographic size to use when it is not `size`.
+ *   `size` on this path is CSS px, and a caller that has already multiplied
+ *   by a device scale is holding device pixels: a 13px label on a 2×
+ *   display arrives here as 26 and would pick a display cut. Such a caller
+ *   passes the unscaled size as `opticalSize` and keeps the scaled one for
+ *   the glyphs.
+ */
+function opticalSizeFor(style) {
+  if (!style || style.opticalSizing === 'none') return undefined;
+  const size = style.opticalSize ?? style.size;
+  return typeof size === 'number' && Number.isFinite(size) ? size : undefined;
+}
+
+/** Cache-key fragment for the optical size, `''` when the axis is left alone. */
+function opticalKeyOf(style) {
+  return opticalSizeFor(style) ?? '';
+}
+
 /**
  * Put a resolved face at the point in its design space the style asked for.
  *
- * The interesting half is `weight`. CSS has said for years that
- * `font-weight: 460` on a variable font means the `wght` axis at 460, not
- * "the nearest face"; a face with a `wght` axis therefore takes the
- * requested weight as a coordinate, and an app that hands ntk a variable
- * file gets the weight it asked for without knowing an axis exists. An
- * explicit `variations.wght` wins, because a caller naming the axis
- * directly is being more specific than one naming a weight.
+ * Two axes get a coordinate from a style that never names them, because CSS
+ * says both are consequences of properties the style does name:
+ *
+ * - `weight`. `font-weight: 460` on a variable font means the `wght` axis at
+ *   460, not "the nearest face", so an app that hands ntk a variable file
+ *   gets the weight it asked for without knowing an axis exists.
+ * - `size`. `font-optical-sizing: auto` has been the initial value since
+ *   optical sizing was specified: `opsz` tracks `font-size` unless the
+ *   author says otherwise. Without this a face is drawn at whatever optical
+ *   size its file happens to default to — on macOS the only San Francisco
+ *   fontconfig can see is a variable file defaulting to `opsz` 28, a
+ *   *display* cut, so every 13px menu label was set in display-sized
+ *   letterforms. Clamping does the rest: 13 against SF's `17..96` lands on
+ *   17, which is exactly Apple's Text end.
+ *
+ * An explicit `variations.wght` / `variations.opsz` wins in both cases,
+ * because a caller naming the axis directly is being more specific than one
+ * naming a weight or a size — the same order CSS gives
+ * `font-variation-settings` over the properties it overlaps.
  *
  * Everything here is a no-op for a static face: `variation()` returns the
  * font unchanged when the settings do not apply, so this costs one property
  * read on the path every non-variable app is already on.
  */
-function instantiate(font, weight, variations) {
+function instantiate(font, weight, variations, opticalSize) {
   const axes = font.variationAxes;
-  if (!axes || (!axes.wght && !variations)) return font;
+  if (!axes || (!axes.wght && !axes.opsz && !variations)) return font;
   const settings = { ...variations };
   if (axes.wght && settings.wght === undefined) settings.wght = weight;
+  if (axes.opsz && settings.opsz === undefined && opticalSize !== undefined) {
+    settings.opsz = opticalSize;
+  }
   return font.variation(settings);
 }
 
@@ -151,19 +194,30 @@ export default class FontManager {
    * Resolve a family (or CSS-style comma-separated family list) to a Font.
    * Registered fonts are consulted first, then fontconfig.
    *
+   * What is cached here is the *face* the pattern resolved to — the
+   * expensive half, since it is an fc-match and a file parse — and not the
+   * instance `instantiate()` cuts out of it. Two things follow. The map
+   * stays one entry per family/weight/style however many points of an axis
+   * an app asks for, so a slider animating `wght`, or a tree of labels at a
+   * dozen sizes, walks a face's own bounded instance cache rather than
+   * evicting other families out of this one. And `size` can drive `opsz`
+   * without joining the key: the coordinate is applied per call, so the
+   * first size asked for does not become every later one's.
+   *
    * @param {string} family e.g. `'Ubuntu Mono', monospace`
-   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic' }
+   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic',
+   *   size, variations, opticalSize, opticalSizing: 'auto'|'none' }
    */
   match(family = 'sans-serif', opts = {}) {
     const weight = numWeight(opts.weight);
     const italic = !!(opts.style && opts.style.includes('italic'));
-    const cacheKey = `${family}|${weight}|${italic}|${variationsKeyOf(opts.variations)}`;
-    let font = this._matches.get(cacheKey);
-    if (font) {
+    const cacheKey = `${family}|${weight}|${italic}`;
+    let face = this._matches.get(cacheKey);
+    if (face) {
       // insertion order is LRU order; re-inserting a hit moves it to the tail
       this._matches.delete(cacheKey);
-      this._matches.set(cacheKey, font);
-      return font;
+      this._matches.set(cacheKey, face);
+      return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
     }
 
     const families = String(family)
@@ -171,26 +225,23 @@ export default class FontManager {
       .map((f) => f.trim().replace(/^["']|["']$/g, ''))
       .filter(Boolean);
 
-    font = this._matchRegistered(
+    face = this._matchRegistered(
       families.map((f) => f.toLowerCase()),
       weight,
       italic
     );
-    if (!font) {
+    if (!face) {
       // sources understand comma-separated family lists natively
       const candidates = this.source.matchSorted({
         family: families.join(','),
         weight,
         style: italic ? 'italic' : 'normal'
       });
-      font = this._open(candidates[0]);
+      face = this._open(candidates[0]);
     }
-    font = instantiate(font, weight, opts.variations);
-    this._matches.set(cacheKey, font);
-    // The key now carries a point in a continuous space rather than one of a
-    // handful of weights, so an app animating an axis walks this map instead
-    // of hitting it. Same sweep as the shaping memo: drop the stale half in
-    // one pass rather than one entry per insert.
+    this._matches.set(cacheKey, face);
+    // A long-lived app can name a lot of families. Same sweep as the shaping
+    // memo: drop the stale half in one pass rather than one entry per insert.
     if (this._matches.size > MAX_MATCHES) {
       let drop = this._matches.size >> 1;
       for (const key of this._matches.keys()) {
@@ -198,7 +249,7 @@ export default class FontManager {
         this._matches.delete(key);
       }
     }
-    return font;
+    return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
   }
 
   /**
@@ -292,14 +343,14 @@ export default class FontManager {
   _shapeCached(text, style, levelsKey = '0') {
     const font = style.font;
     // A resolved `font` already carries its coordinates in its key, so the
-    // variations fragment only earns its 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.
+    // 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.
     const key = font
       ? `${font.key}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`
       : `${style.family}|${style.size}|${style.weight}|${style.style}|${variationsKeyOf(
           style.variations
-        )}|${levelsKey}|${text}`;
+        )}|${opticalKeyOf(style)}|${levelsKey}|${text}`;
     let shaped = this._shapeCache.get(key);
     if (shaped) {
       // Map iterates in insertion order: re-inserting a hit moves it to the

package/lib/text/layout.js

@@ -67,6 +67,8 @@ export class TextLayout {
         weight: s.weight ?? style.weight,
         style: s.style ?? style.style,
         variations: s.variations ?? style.variations,
+        opticalSize: s.opticalSize ?? style.opticalSize,
+        opticalSizing: s.opticalSizing ?? style.opticalSizing,
         textRendering: s.textRendering ?? style.textRendering,
         features: s.features ?? style.features,
         language: s.language ?? style.language,

package/lib/text/shape.js

@@ -69,7 +69,10 @@ export function normalizedLevels(levels, start, end) {
 export function shapeText(fonts, text, style, levels) {
   const size = style.size ?? 16;
   const family = style.family ?? 'sans-serif';
-  const baseFont = style.font ?? fonts.match(family, style);
+  // `size` is what drives the `opsz` axis, so a style that leaves it out
+  // hands `match()` the size this actually sets at rather than nothing
+  const baseFont =
+    style.font ?? fonts.match(family, style.size === undefined ? { ...style, size } : style);
 
   let baseLevel = 0;
   if (!levels) {

package/lib/window.js

@@ -109,6 +109,16 @@ const REFRESH_QUANTILE = 0.25;
 const STALL_TIMEOUT = 2000;
 const STALL_TIMEOUT_FIRST = 250;
 
+/**
+ * MotionNotify detail saying "this is the only motion you get until you ask".
+ *
+ * The core protocol calls it NotifyHint and puts it in the event's detail
+ * byte; node-x11 parses a MotionNotify's detail into `keycode`, the field
+ * that carries a button number on ButtonPress — so this is compared against
+ * `ev.keycode`, not `ev.detail`, which motion events do not have.
+ */
+const MOTION_NOTIFY_HINT = 1;
+
 function rectArea(r) {
   return Math.max(0, r.w) * Math.max(0, r.h);
 }
@@ -493,6 +503,15 @@ export default class Window extends Drawable {
     this._geSinkOpcode = 0;
     // XI2 state, once a window has selected it (see selectXI2)
     this._xi2 = null;
+    // PointerMotionHint bookkeeping (see setMouseHintOnly and
+    // _rearmMotionHint): whether a frame owes the server the QueryPointer
+    // that re-arms the hint, whether one is already in flight, the timestamp
+    // of the hint that asked for it, and the last position delivered — a
+    // reply that repeats it is not an event.
+    this._hintRearm = false;
+    this._hintPollPending = false;
+    this._hintTime = 0;
+    this._hintLast = null;
     // The vblank clock (see _onPresentComplete): the period learnt from
     // completion events, the samples it is drawn from, and the latch the
     // watchdog sets when completions stop arriving.
@@ -762,6 +781,21 @@ export default class Window extends Drawable {
           if (key.codepoint !== undefined) ev.codepoint = key.codepoint;
         }
       }
+      // the server saying "the pointer moved, and I will say no more about it
+      // until you ask": the event still carries the position it was generated
+      // at, so it is delivered like any other move, but the conversation has
+      // to be picked back up or this is the last one (see _rearmMotionHint)
+      if (eventName === 'mousemove' && ev.keycode === MOTION_NOTIFY_HINT) {
+        this._hintTime = ev.time;
+        this._hintLast = { x: ev.x, y: ev.y };
+        this._hintRearm = true;
+        this._deliverEvent(eventName, ntkev);
+        // the frame that just took the move sends the poll — one per frame,
+        // which is the rate a frame's worth of motion is reduced to anyway.
+        // An uncoalesced window has no frame to hang it on, so it goes now.
+        if (!this._coalesce) this._rearmMotionHint();
+        return;
+      }
       // a wheel is a button in the core protocol; say so in the units a
       // consumer wants. Suppressed once XI2 is delivering the same scroll as
       // valuators, which is the whole reason to select it (see selectXI2).
@@ -1393,6 +1427,9 @@ export default class Window extends Drawable {
     )
       return;
     this._flushCoalesced();
+    // after the flush: the frame's motion has been delivered, so what the
+    // server is asked for now is what happened since
+    if (this._hintRearm) this._rearmMotionHint();
     if (f.needsRedraw) {
       f.needsRedraw = false;
       const ev = {
@@ -1987,6 +2024,9 @@ export default class Window extends Drawable {
     f.rafCbs = [];
     f.needsRedraw = false;
     this._presentPending = false;
+    // a window with no frames left has nothing to send the poll from
+    this._hintRearm = false;
+    this._hintLast = null;
   }
 
   /**
@@ -3252,11 +3292,45 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Trade motion events for round trips: ask the server to report the pointer
+   * moving *once*, and then wait to be asked where it went.
+   *
+   * PointerMotionHint is a two-party protocol. With it selected the server
+   * may send a single MotionNotify carrying detail NotifyHint and then say
+   * nothing more about the pointer until the client asks — so a window that
+   * only sets the bit hears about one move and then silence (issue #319).
+   * ntk holds up the other end: a hinted move is delivered with the position
+   * it carries, and the frame it lands in sends the QueryPointer that lets
+   * the server speak again (see _rearmMotionHint).
+   *
+   * What that buys, and what it costs, are the same thing. Motion stops being
+   * paced by the input device and starts being paced by the connection: one
+   * event per round trip instead of one per hardware sample, which is a large
+   * saving on a link where bytes are scarce — X over ssh, a tunnel, a slow
+   * network — and no saving at all on a local socket, where the poll costs
+   * more bytes than the events it replaced. It also means a handler acts on a
+   * position that is up to one round trip old. Reach for it when bandwidth is
+   * the problem; leave it alone when latency is.
+   *
+   * Two things it is not:
+   *
+   *   - not a substitute for selecting motion. The hint modifies
+   *     PointerMotion, it does not imply it — a window with no `mousemove`
+   *     listener and no PointerMotion in its mask receives nothing either way.
+   *   - not an XI2 control. A window that called `selectXI2(['Motion'])` is
+   *     off the core motion stream entirely (see lib/xi2.js), and the core
+   *     hint has nothing left to thin.
+   */
   setMouseHintOnly(isOn) {
     if (isOn && !(this.eventMask & x11.eventMask.PointerMotionHint)) {
       this.eventMask |= x11.eventMask.PointerMotionHint;
     } else if (!isOn && this.eventMask & x11.eventMask.PointerMotionHint) {
       this.eventMask &= ~x11.eventMask.PointerMotionHint;
+      // the server will report motion on its own again, so no frame owes it a
+      // question. A poll already in flight is left alone: its answer is a
+      // real position, and it is deduped against the last one like any other.
+      this._hintRearm = false;
     } else {
       return this;
     }
@@ -3265,6 +3339,63 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Answer a NotifyHint: ask where the pointer is, which is what re-arms the
+   * server, and deliver the answer if it moved somewhere no event reported.
+   *
+   * The reply is not redundant with the hint that asked for it. Between the
+   * hint being generated and the server processing this request the pointer
+   * may have moved again, and that motion produces no event — it is exactly
+   * what the hint suppressed. Dropped, the last position of a gesture that
+   * ends mid-flight is lost and the window's idea of where the pointer is
+   * stays wrong until it moves again. So the poll's position is delivered as
+   * a motion event when it differs from the last one delivered, and nothing
+   * is emitted when the pointer sat still.
+   *
+   * One poll at a time, and one per frame: a burst of motion cannot queue a
+   * round trip each, and the flag stays raised if a poll is already out, so
+   * the next frame picks it up.
+   */
+  _rearmMotionHint() {
+    if (this._hintPollPending) return;
+    this._hintRearm = false;
+    if (this._destroyed || connectionGone(this.X)) return;
+    this._hintPollPending = true;
+    const time = this._hintTime;
+    this.X.QueryPointer(this.id, (err, pointer) => {
+      this._hintPollPending = false;
+      if (err || this._destroyed || connectionGone(this.X)) return;
+      // the pointer is on another screen: `child` and the window-relative
+      // coordinates are zero by protocol, not a position (core QueryPointer)
+      if (!pointer.sameScreen) return;
+      const last = this._hintLast;
+      if (last && last.x === pointer.childX && last.y === pointer.childY) return;
+      this._hintLast = { x: pointer.childX, y: pointer.childY };
+      this._deliverEvent('mousemove', {
+        type: 6,
+        name: 'MotionNotify',
+        // the poll has no timestamp of its own — QueryPointer's reply carries
+        // no time — so the event is stamped with the hint that prompted it
+        time,
+        keycode: 0,
+        root: pointer.root,
+        wid: this.id,
+        child: pointer.child,
+        rootx: pointer.rootX,
+        rooty: pointer.rootY,
+        x: pointer.childX,
+        y: pointer.childY,
+        buttons: pointer.keyMask,
+        sameScreen: pointer.sameScreen,
+        // built from a reply rather than read off the wire, the way a paced
+        // window's redraw events are
+        synthetic: true,
+        window: this,
+        target: this
+      });
+    });
+  }
+
   queryPointer(callback) {
     this.X.QueryPointer(this.id, callback);
     return this;

package/package.json

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