ntk 6.6.1 → 7.0.0

package/lib/app.js

@@ -8,6 +8,41 @@ import { ShmUploader } from './shm-upload.js';
 import FontManager from './text/fontmanager.js';
 import Window from './window.js';
 
+/**
+ * Frame interval used before the display has been asked, in ms — and the one
+ * kept on a server that cannot answer.
+ */
+const DEFAULT_FRAME_INTERVAL = 16;
+
+/**
+ * The range a refresh rate has to fall in to be paced against, in Hz. Below
+ * this a display is not something a UI should be throttled to, and above it
+ * the numbers are not describing a display at all.
+ */
+const MIN_REFRESH_RATE = 20;
+const MAX_REFRESH_RATE = 1000;
+
+/**
+ * A RandR mode's vertical refresh rate in Hz, or 0 when it does not describe
+ * one.
+ *
+ * `dot_clock / (h_total * v_total)`, with the two flags that make a frame
+ * something other than one pass down the mode, exactly as xrandr computes it:
+ * an interlaced mode paints half the lines per pass, a doublescan mode paints
+ * each line twice.
+ *
+ * The zero check is not defensive: a virtual output has no pixel clock to
+ * report and Xvfb — which is what CI runs against — fills all three fields
+ * with zeroes, so the arithmetic yields NaN rather than a rate.
+ */
+function modeRate(mode) {
+  if (!mode || !mode.dot_clock || !mode.h_total || !mode.v_total) return 0;
+  let vTotal = mode.v_total;
+  if (mode.modeflags & 0x10) vTotal /= 2; // Interlace
+  if (mode.modeflags & 0x20) vTotal *= 2; // DoubleScan
+  return mode.dot_clock / (mode.h_total * vTotal);
+}
+
 /**
  * A connection to an X server. Owns the underlying node-x11 client
  * (`app.X`) and acts as a factory for windows and pixmaps.
@@ -59,6 +94,79 @@ export default class App {
     });
   }
 
+  /**
+   * The fastest refresh rate any active output is running at, in Hz, or
+   * `null` until the display has been asked — and on a server with no RandR
+   * or no mode worth pacing to.
+   *
+   * The fastest rather than the one this or that window is on, because what
+   * it feeds is a rate *ceiling* (see `frameInterval`), and a window paced
+   * faster than its own monitor is bounded by the next gate along rather than
+   * drawing more than anyone can see. Tracking which output every window
+   * overlaps would cost a per-window RandR lookup plus change tracking, to
+   * make a ceiling slightly tighter.
+   */
+  get refreshRate() {
+    if (this._refreshProbe === undefined) this._probeRefreshRate();
+    return this._refreshRate ?? null;
+  }
+
+  /**
+   * The frame interval windows on this connection take by default, in ms:
+   * the display's own period rather than a guess, so an animation loop on a
+   * 165Hz output is not held to the 62.5fps a hardcoded 16 implies. `null`
+   * until the probe has answered; windows created before then start on the
+   * default and adopt this when it lands.
+   *
+   * A window that presents takes its rate from the display directly and needs
+   * none of this — see docs/window.md "What ends a frame". This is what the
+   * fence clock paces to, which is every window on a server without Present,
+   * and every window before its first frames have been shown.
+   */
+  get frameInterval() {
+    const rate = this.refreshRate;
+    return rate ? 1000 / rate : null;
+  }
+
+  /**
+   * Ask RandR what the outputs are running at, once per connection, in the
+   * background.
+   *
+   * Not on the connect path: `createClient` is already four round trips deep
+   * and this is three more, for something no window needs before its first
+   * frame. Failures are silent by design — every one of them means "no rate
+   * to be had", which is exactly what the default covers.
+   */
+  _probeRefreshRate() {
+    this._refreshProbe = null; // in progress; only ever started once
+    const X = this.X;
+    X.require('randr', (err, R) => {
+      if (err || !R) return;
+      const root = this.display.screen[0].root;
+      R.GetScreenResourcesCurrent(root, (resourcesError, resources) => {
+        if (resourcesError || !resources?.crtcs?.length) return;
+        const modes = new Map(resources.modeinfos.map((mode) => [mode.id, mode]));
+        let pending = resources.crtcs.length;
+        let best = 0;
+        for (const crtc of resources.crtcs) {
+          R.GetCrtcInfo(crtc, resources.config_timestamp, (crtcError, info) => {
+            // 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);
+          });
+        }
+      });
+    });
+  }
+
+  /** hand the measured default to the windows that are still on the guess */
+  _adoptFrameInterval(ms) {
+    for (const wnd of Window._cacheFor(this).values()) wnd._adoptDefaultFrameInterval(ms);
+  }
+
   /** the text API entry point: font matching/loading, shaping, layout */
   get fonts() {
     if (!this._fonts) this._fonts = new FontManager({ source: this.options.fontSource });

package/lib/index.js

@@ -36,6 +36,7 @@ import {
   defaultRasterizer,
   setDefaultRasterizer
 } from './rasterize.js';
+import { DEFAULT_SHAPE_POLICY } from './shapeglyphs.js';
 import { TextLayout } from './text/layout.js';
 import HtmlView from './widgets/htmlview.js';
 import SvgView from './widgets/svgview.js';
@@ -214,6 +215,7 @@ export {
   defaultRasterizer,
   setDefaultRasterizer,
   DEFAULT_RASTER_POLICY,
+  DEFAULT_SHAPE_POLICY,
   TextLayout,
   HtmlView,
   SvgView,

package/lib/path.js

@@ -45,6 +45,100 @@ export function matIsIdentity(m) {
   return m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1 && m[4] === 0 && m[5] === 0;
 }
 
+// --------------------------------------------------------------------------
+// arc tags
+//
+// A cubic emitted by ellipseCubics carries the arc it approximates, so the
+// flattener can subdivide the arc itself instead of rediscovering its shape
+// by bisecting the cubic (issue #213). The tag is the centre-plus-axis-
+// vectors form:
+//
+//   P(t) = (cx, cy) + u·cos t + v·sin t,   t from t0 to t1
+//
+// u and v are the semi-axis *vectors*, which is what makes the tag survive
+// transforms: an affine map takes this form to the same form — the centre
+// moves, u and v go through the linear part — where radii plus a rotation
+// angle would only survive a similarity, and a shear or a non-uniform scale
+// would have to drop the tag and fall back.
+//
+// The tag also carries its own start point (sx, sy), which the lowering
+// computes anyway. Flattening a cubic starts from the path's current point,
+// so the arc route is only valid when that point is where the arc begins —
+// true of every way a tagged cubic can be built here, and checked rather
+// than assumed, since a path that broke the invariant would otherwise be
+// drawn quietly wrong instead of falling back to bisection.
+//
+// Tags are treated as immutable: transformArc always builds a new one, so
+// Path2D copies and addPath can share them by reference.
+
+/** the flatness tolerance, in output pixels, everything here defaults to */
+export const FLATTEN_TOLERANCE = 0.25;
+
+// how many chords an arc may be split into, whatever the arithmetic says.
+// Only reachable through a degenerate tolerance (0 or negative); a real
+// drawing at tol 0.25 asks for ~800 chords for a full circle the size of
+// the largest addressable surface.
+const MAX_ARC_SEGMENTS = 4096;
+
+/**
+ * The fewest equal chords that approximate an arc within `tol`.
+ *
+ * A chord spanning angle θ of a circle of radius R misses the arc by the
+ * sagitta R·(1 - cos(θ/2)) at its midpoint, so the largest angle a chord may
+ * span is 2·acos(1 - tol/R) and the count follows by division. Recursive
+ * bisection can only land on powers of two and so overshoots this by up to
+ * 2x — an arc needing 9 chords used to get 16.
+ *
+ * @param {number} sweep total angle covered, radians (unsigned)
+ * @param {number} radius the arc's radius — for an ellipse, the largest
+ *   singular value of its axis matrix (see arcScale), which bounds the
+ *   sagitta everywhere on the curve
+ * @param {number} tol allowed deviation, in the same units as radius
+ */
+export function arcSegmentCount(sweep, radius, tol = FLATTEN_TOLERANCE) {
+  if (!(sweep > 0) || !(radius > 0)) return 1;
+  // tol >= 2R: the whole circle is within tolerance of a single chord
+  const cos = 1 - tol / radius;
+  if (!(cos > -1)) return 1;
+  const theta = 2 * Math.acos(Math.min(1, cos));
+  if (!(theta > 0)) return MAX_ARC_SEGMENTS; // tol <= 0: as fine as allowed
+  return Math.max(1, Math.min(MAX_ARC_SEGMENTS, Math.ceil(sweep / theta)));
+}
+
+/**
+ * The radius to measure an arc tag's sagitta against: the largest singular
+ * value of `[u | v]`, i.e. how far the map from the unit circle can stretch
+ * a distance. For a circle that is exactly its radius; for an ellipse it is
+ * the semi-major axis, which bounds the deviation everywhere on the curve
+ * (|A·d| <= σmax·|d|) and so is safe, if conservative on eccentric ones.
+ *
+ * σ1² + σ2² = ‖A‖_F² and σ1·σ2 = |det A| give it in closed form.
+ */
+function arcScale({ ux, uy, vx, vy }) {
+  const frob = ux * ux + uy * uy + vx * vx + vy * vy;
+  const det = ux * vy - uy * vx;
+  const disc = Math.sqrt(Math.max(0, frob * frob - 4 * det * det));
+  return Math.sqrt((frob + disc) / 2);
+}
+
+/** an arc tag through an affine map — the centre and start point move, the
+ *  axes go through the linear part; exact for every affine, shear and
+ *  reflection included */
+function transformArc(a, m) {
+  return {
+    cx: m[0] * a.cx + m[2] * a.cy + m[4],
+    cy: m[1] * a.cx + m[3] * a.cy + m[5],
+    ux: m[0] * a.ux + m[2] * a.uy,
+    uy: m[1] * a.ux + m[3] * a.uy,
+    vx: m[0] * a.vx + m[2] * a.vy,
+    vy: m[1] * a.vx + m[3] * a.vy,
+    sx: m[0] * a.sx + m[2] * a.sy + m[4],
+    sy: m[1] * a.sx + m[3] * a.sy + m[5],
+    t0: a.t0,
+    t1: a.t1
+  };
+}
+
 // --------------------------------------------------------------------------
 // elliptical arcs -> cubics
 
@@ -53,6 +147,9 @@ export function matIsIdentity(m) {
  * radii (rx, ry), rotated by phi, from angle a0 sweeping by da (signed,
  * |da| <= 2π). Returns { start: {x, y}, cmds: [{type:'C', ...}, ...] };
  * segments are split to <= 90° so the approximation error stays tiny.
+ *
+ * Each command carries an `arc` tag (see above) describing the piece of the
+ * true arc it stands for, which is what `flattenPath` subdivides.
  */
 export function ellipseCubics(cx, cy, rx, ry, phi, a0, da) {
   const cosPhi = Math.cos(phi);
@@ -68,6 +165,12 @@ export function ellipseCubics(cx, cy, rx, ry, phi, a0, da) {
     return [cosPhi * x - sinPhi * y, sinPhi * x + cosPhi * y];
   };
 
+  // the ellipse's semi-axis vectors, the form the arc tag keeps
+  const ux = rx * cosPhi;
+  const uy = rx * sinPhi;
+  const vx = -ry * sinPhi;
+  const vy = ry * cosPhi;
+
   const [sx, sy] = point(a0);
   const cmds = [];
   const n = Math.max(1, Math.ceil(Math.abs(da) / (Math.PI / 2)));
@@ -87,7 +190,8 @@ export function ellipseCubics(cx, cy, rx, ry, phi, a0, da) {
       x2: x3 - k * dx3,
       y2: y3 - k * dy3,
       x: x3,
-      y: y3
+      y: y3,
+      arc: { cx, cy, ux, uy, vx, vy, sx: x0, sy: y0, t0: a, t1: b }
     });
     a = b;
   }
@@ -416,12 +520,22 @@ export class Path2D {
     this._y = null;
     this._sx = null; // subpath start
     this._sy = null;
+    // When the whole path is exactly one roundRect(), this records what
+    // roundRect knew — { x, y, w, h, radii: [tl, tr, br, bl] } with the
+    // radii already normalized — so the 2d context can recognize the shape
+    // and route it to corner glyphs + FillRectangles instead of polygon
+    // rasterization (issue #211). Any other path verb clears it. The 2d
+    // context parks a bail-out reason in _roundRectMiss when it records a
+    // box the fast path can never take (e.g. under rotation).
+    this._roundRect = null;
+    this._roundRectMiss = null;
     if (init instanceof Path2D) {
       this._cmds = init._cmds.map((c) => ({ ...c }));
       this._x = init._x;
       this._y = init._y;
       this._sx = init._sx;
       this._sy = init._sy;
+      this._roundRect = init._roundRect;
     } else if (typeof init === 'string') {
       this._append(parseSvgPath(init));
     }
@@ -443,6 +557,10 @@ export class Path2D {
   }
 
   _append(cmds) {
+    // every mutation funnels through here; a path that is no longer exactly
+    // one roundRect() loses the tag (roundRect itself re-sets it at the end)
+    this._roundRect = null;
+    this._roundRectMiss = null;
     for (const c of cmds) {
       this._cmds.push(c);
       this._track(c);
@@ -532,7 +650,18 @@ export class Path2D {
   }
 
   roundRect(x, y, w, h, radii) {
-    if (typeof radii === 'number' && radii === 0) return this.rect(x, y, w, h);
+    // The tag is set only when this call is the whole path: recorded after
+    // the geometry lands (the builder calls below clear it via _append) and
+    // only if the path held nothing before.
+    const wasEmpty = this._cmds.length === 0;
+    if (typeof radii === 'number' && radii === 0) {
+      this.rect(x, y, w, h);
+      if (wasEmpty && w >= 0 && h >= 0) {
+        const zero = { x: 0, y: 0 };
+        this._roundRect = { x, y, w, h, radii: [zero, zero, zero, zero] };
+      }
+      return;
+    }
     const [tl, tr, br, bl] = normalizeRadii(Math.abs(w), Math.abs(h), radii);
     if (w < 0 || h < 0) {
       // degenerate: fall back to a plain rect on flipped geometry
@@ -549,6 +678,7 @@ export class Path2D {
     if (tl.x || tl.y) this.ellipse(x + tl.x, y + tl.y, tl.x, tl.y, 0, Math.PI, Math.PI * 1.5);
     this.closePath();
     this.moveTo(x, y);
+    if (wasEmpty) this._roundRect = { x, y, w, h, radii: [tl, tr, br, bl] };
   }
 
   /** append another path, optionally transformed ([a,b,c,d,e,f] or {a..f}) */
@@ -578,7 +708,12 @@ export function transformCommands(cmds, m) {
         const [x1, y1] = matApply(m, c.x1, c.y1);
         const [x2, y2] = matApply(m, c.x2, c.y2);
         const [x, y] = matApply(m, c.x, c.y);
-        out.push({ type: 'C', x1, y1, x2, y2, x, y });
+        const out_ = { type: 'C', x1, y1, x2, y2, x, y };
+        // an arc tag transforms exactly under any affine, so baking the CTM
+        // into the commands (which is what the context's default path does)
+        // keeps the arc route available downstream
+        if (c.arc) out_.arc = transformArc(c.arc, m);
+        out.push(out_);
         break;
       }
       case 'Q': {
@@ -604,7 +739,6 @@ function addCubic(pts, x0, y0, x1, y1, x2, y2, x3, y3, tol2, depth) {
   // cross products = (distance of control point from the chord) * |chord|
   const d1 = (x1 - x0) * dy - (y1 - y0) * dx;
   const d2 = (x2 - x0) * dy - (y2 - y0) * dx;
-  const err = (Math.abs(d1) + Math.abs(d2)) ** 2;
   let flat;
   if (chord2 < 1e-9) {
     // degenerate chord: flat only if the control points are also close
@@ -612,7 +746,12 @@ function addCubic(pts, x0, y0, x1, y1, x2, y2, x3, y3, tol2, depth) {
     const c2 = (x2 - x0) ** 2 + (y2 - y0) ** 2;
     flat = Math.max(c1, c2) <= tol2;
   } else {
-    // (dist1 + dist2)² <= tol² — absolute flatness in output pixels
+    // The curve's distance from its chord is bounded by (3/4)·max(dist1,
+    // dist2): B(t) - chord(t) = 3t(1-t)·((1-t)·D1 + t·D2), and 3t(1-t)
+    // peaks at 3/4. Testing dist1 + dist2 here (as this used to) is up to
+    // 8/3 stricter than that bound on symmetric cubics — every arc — which
+    // over-subdivided a quarter circle ~2x at any radius (issue #213).
+    const err = (0.75 * Math.max(Math.abs(d1), Math.abs(d2))) ** 2;
     flat = err <= tol2 * chord2;
   }
   if (flat || depth >= 18) {
@@ -636,14 +775,64 @@ function addCubic(pts, x0, y0, x1, y1, x2, y2, x3, y3, tol2, depth) {
   addCubic(pts, mx, my, bcx, bcy, cx, cy, x3, y3, tol2, depth + 1);
 }
 
+/**
+ * Chords of the arc a tagged cubic stands for, appended to `pts`. Returns
+ * false — flatten the cubic instead — when the path's current point is not
+ * where the arc begins, so a caller that spliced commands together still
+ * gets a curve from where it actually is.
+ *
+ * The count comes from the sagitta formula rather than from bisecting the
+ * cubic, so an arc gets the fewest chords its tolerance allows instead of
+ * the next power of two (issue #213). The points are evaluated on the arc
+ * itself — closer to the geometry the caller asked for than the cubic
+ * proxy, whose own error is ~2.7e-4·R for the <=90° pieces used here.
+ *
+ * The last point is the command's own endpoint rather than a re-evaluated
+ * one, so consecutive segments still meet exactly, and an SVG arc whose
+ * final point was snapped to the requested endpoint keeps that snap.
+ */
+function addArcChords(pts, cmd, m, tol, x0, y0) {
+  const arc = m ? transformArc(cmd.arc, m) : cmd.arc;
+  const scale = arcScale(arc);
+  // The two agree bit-for-bit when the lowering produced both, so this only
+  // fires on spliced paths — and on the ~1e-13 drift where an SVG arc's
+  // endpoint was snapped and the next arc starts from the snapped value.
+  const slack = 1e-6 * (1 + scale);
+  if (Math.abs(x0 - arc.sx) > slack || Math.abs(y0 - arc.sy) > slack) {
+    return false;
+  }
+  const sweep = arc.t1 - arc.t0;
+  const n = arcSegmentCount(Math.abs(sweep), scale, tol);
+  for (let i = 1; i < n; i++) {
+    const t = arc.t0 + (sweep * i) / n;
+    const cos = Math.cos(t);
+    const sin = Math.sin(t);
+    pts.push(
+      arc.cx + arc.ux * cos + arc.vx * sin,
+      arc.cy + arc.uy * cos + arc.vy * sin
+    );
+  }
+  if (m) {
+    const [x, y] = matApply(m, cmd.x, cmd.y);
+    pts.push(x, y);
+  } else {
+    pts.push(cmd.x, cmd.y);
+  }
+  return true;
+}
+
 /**
  * Flatten normalized commands into polylines. `m` (optional affine) is
  * applied to control points before subdivision, so the flatness tolerance
  * `tol` (default 0.25) is measured in output/device pixels.
  *
+ * Cubics that came from an arc carry a tag and are subdivided from their own
+ * geometry (see addArcChords); genuine beziers — hand-built paths, SVG curve
+ * commands, font outlines — take the adaptive bisection route.
+ *
  * @returns {Array<{pts: number[], closed: boolean}>} flat [x0,y0,x1,y1,…]
  */
-export function flattenPath(cmds, m = null, tol = 0.25) {
+export function flattenPath(cmds, m = null, tol = FLATTEN_TOLERANCE) {
   if (m && matIsIdentity(m)) m = null;
   const tol2 = tol * tol;
   const polys = [];
@@ -668,6 +857,7 @@ export function flattenPath(cmds, m = null, tol = 0.25) {
         if (!pts) break;
         const x0 = pts.pts[pts.pts.length - 2];
         const y0 = pts.pts[pts.pts.length - 1];
+        if (c.arc && addArcChords(pts.pts, c, m, tol, x0, y0)) break;
         const [x1, y1] = p(c.x1, c.y1);
         const [x2, y2] = p(c.x2, c.y2);
         const [x, y] = p(c.x, c.y);