ntk 6.6.0 → 6.7.0

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);

package/lib/renderingcontext_2d.js

@@ -13,6 +13,7 @@ import {
 } from "./imagedata.js";
 import {
   Path2D,
+  arcSegmentCount,
   flattenPath,
   transformCommands,
   ellipseSegments,
@@ -25,7 +26,24 @@ import {
 import Picture from "./picture.js";
 import Pixmap from "./pixmap.js";
 import { routeRaster } from "./rasterize.js";
-import { compositeTraps, drawGlyphRuns } from "./text/glyphs.js";
+import {
+  BL,
+  BR,
+  TL,
+  TR,
+  cornerKey,
+  countShapeHit,
+  countShapeMiss,
+  getShapeGlyphPage,
+  roundRectBandRects,
+  shapePolicyOf,
+  trimShapeGlyphs,
+} from "./shapeglyphs.js";
+import {
+  compositeTraps,
+  drawGlyphRuns,
+  encodeGlyphItems,
+} from "./text/glyphs.js";
 import { TextLayout } from "./text/layout.js";
 import { reorderRuns } from "./text/shape.js";
 import { trapezoidize } from "./trapezoid.js";
@@ -245,6 +263,10 @@ class RenderingContext2d {
 
     this._path = new Path2D();
     this._m = [1, 0, 0, 1, 0, 0];
+    // Rounded-rect fast-path observability (issue #211): every bail-out is
+    // a silent perf cliff, so hits and misses-by-reason are always counted.
+    // NTK_DEBUG_SHAPES=1 prints the process-wide aggregate at exit.
+    this.shapeStats = { hits: 0, misses: {} };
     this._stack = [];
     this._clips = []; // [{ polys, rule }] in device space, already stacked
     this._gco = "source-over";
@@ -653,7 +675,28 @@ class RenderingContext2d {
   roundRect(x, y, w, h, radii) {
     const tmp = new Path2D();
     tmp.roundRect(x, y, w, h, radii);
+    const wasEmpty = this._path._cmds.length === 0;
     this._path.addPath(tmp, this._m);
+    // Re-derive the recognition tag in device space (addPath cleared it): it
+    // survives only when this roundRect is the whole path and the CTM is a
+    // pure translation at record time — the default path bakes the transform
+    // into its commands here, so this is the last moment the box exists.
+    if (!tmp._roundRect || !wasEmpty) return;
+    const m = this._m;
+    if (m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1) {
+      const t = tmp._roundRect;
+      this._path._roundRect = {
+        x: t.x + m[4],
+        y: t.y + m[5],
+        w: t.w,
+        h: t.h,
+        radii: t.radii,
+      };
+    } else {
+      // a box recorded under rotation/scale can never take the glyph route;
+      // leave the reason behind so fill()/stroke() count the bail-out
+      this._path._roundRectMiss = "transform";
+    }
   }
 
   // args: ([path], [fillRule]) — returns device-space polys + rule
@@ -933,12 +976,29 @@ class RenderingContext2d {
     const thickness = this.lineWidth * scale;
     const roundCap = this.lineCap === "round";
     const roundJoin = this.lineJoin === "round";
+    const cap = LINE_CAP[this.lineCap] || "butt";
+    const join = LINE_JOIN[this.lineJoin] || "miter";
     const stroke = extrudePolyline({
       thickness,
-      cap: LINE_CAP[this.lineCap] || "butt",
-      join: LINE_JOIN[this.lineJoin] || "miter",
+      cap,
+      join,
       miterLimit: this.miterLimit,
     });
+    // A closed subpath has no ends, so the canvas spec gives it no caps.
+    // That cannot share the extruder above: with lineCap 'square'
+    // extrude-polyline pushes the first and last points outward along the
+    // line, which on a closed loop extends the seam over band it already
+    // covers — invisible against an opaque colour, a double-blended edge
+    // against a translucent one.
+    const closedStroke =
+      cap === "butt"
+        ? stroke
+        : extrudePolyline({
+            thickness,
+            cap: "butt",
+            join,
+            miterLimit: this.miterLimit,
+          });
     // dash distances are user-space lengths; scale them like the line width
     const dash = this._lineDash.length
       ? this._lineDash.map((d) => d * scale)
@@ -952,7 +1012,12 @@ class RenderingContext2d {
     // cap, and a disk at an interior vertex fills the bevel notch
     let hasRound = false;
     const r = thickness / 2;
-    const diskSegs = Math.max(8, Math.min(32, Math.ceil(r * 2)));
+    // A disk is an arc like any other: the sagitta formula sizes it to the
+    // flatness tolerance instead of a floor of 8 (which spent 16 triangles
+    // on the half-pixel cap of a 1px line) and a ceiling of 32 (which was
+    // coarse enough to show on a fat one). Three is the fewest that
+    // enclose any area at all.
+    const diskSegs = Math.max(3, arcSegmentCount(2 * Math.PI, r));
     const addDisk = (x, y) => {
       hasRound = true;
       let ex = x + r;
@@ -988,18 +1053,35 @@ class RenderingContext2d {
         return;
       }
       if (pts.length < 2) return;
-      const mesh = stroke.build(pts);
+      if (closed && pts.length >= 3) {
+        // Move the seam to the middle of the first edge. extrude-polyline
+        // treats every polyline as open — it butt-extrudes both ends and
+        // emits no join between them — so a closed loop lost the join at
+        // whichever vertex it happened to start on: a stroked rectangle
+        // came out with three square corners and a notched one, the notch
+        // being a quarter of the line width square. Cutting the loop in
+        // the middle of a straight edge instead leaves the two ends
+        // collinear, so they meet exactly, and makes every real vertex
+        // interior, so extrude-polyline gives each the join it asked for
+        // — miter, bevel and round alike.
+        const mid = [
+          (pts[0][0] + pts[1][0]) / 2,
+          (pts[0][1] + pts[1][1]) / 2,
+        ];
+        pts = [mid, ...pts.slice(1), mid];
+      }
+      const mesh = (closed ? closedStroke : stroke).build(pts);
       for (const tri of mesh.cells) {
         for (let i = 0; i < 3; ++i) {
           tris.push(mesh.positions[tri[i]][0], mesh.positions[tri[i]][1]);
         }
       }
       if (roundJoin) {
+        // every real vertex is interior now, the seam included: a closed
+        // run was rotated to break at a collinear point, which needs no
+        // join disk of its own
         for (let i = 1; i < pts.length - 1; i++)
           maybeJoinDisk(pts[i - 1], pts[i], pts[i + 1]);
-        // the seam of a closed loop is a join too (pts[0] === pts[last])
-        if (closed && pts.length > 2)
-          maybeJoinDisk(pts[pts.length - 2], pts[0], pts[1]);
       }
       if (roundCap && !closed) {
         addDisk(pts[0][0], pts[0][1]);
@@ -1428,17 +1510,34 @@ class RenderingContext2d {
   }
 
   strokeRect(x, y, w, h) {
+    const m = this._m;
+    if (m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1) {
+      const zero = { x: 0, y: 0 };
+      const box = {
+        x: x + m[4],
+        y: y + m[5],
+        w,
+        h,
+        radii: [zero, zero, zero, zero],
+      };
+      if (this._tryStrokeBox(box)) return;
+    } else {
+      this._shapeMiss("transform");
+    }
     const tmp = new Path2D();
     tmp.rect(x, y, w, h);
     this._strokePolys(flattenPath(tmp._cmds, this._m));
   }
 
   fill(...args) {
+    if (this._tryRoundRectFill(args)) return;
     const { polys, rule } = this._polysFor(args);
     this._fillPolys(polys, rule);
   }
 
   stroke(...args) {
+    const box = this._shapeBoxFor(args);
+    if (box && this._tryStrokeBox(box)) return;
     const polys =
       args[0] instanceof Path2D
         ? flattenPath(args[0]._cmds, this._m)
@@ -1446,6 +1545,342 @@ class RenderingContext2d {
     this._strokePolys(polys);
   }
 
+  // ------------------------------------------------------------------
+  // rounded-rect fast path (issue #211)
+  //
+  // A fill/stroke of an axis-aligned rounded rect on integer geometry is
+  // emitted as corner glyphs + FillRectangles — the box's only curved ink
+  // rides the glyph path, cached server-side after first use, and nothing
+  // is rasterized or uploaded afterwards. The pieces partition the pixels
+  // (glyphs own their integer-cut corner boxes, rects the strips between),
+  // so translucent colours are safe with no mask and no accumulation. Every
+  // condition below that fails falls through to the polygon route untouched,
+  // counting the reason in `shapeStats`.
+
+  /** count one fast-path bail-out; always returns false for tail-calling */
+  _shapeMiss(reason) {
+    const misses = this.shapeStats.misses;
+    misses[reason] = (misses[reason] || 0) + 1;
+    countShapeMiss(reason);
+    return false;
+  }
+
+  /**
+   * The device-space rounded-rect a fill/stroke argument list describes, or
+   * null. The default path carries its tag in device space already (recorded
+   * under a translate-only CTM); a Path2D argument is user-space, so the CTM
+   * must be translate-only *now*.
+   */
+  _shapeBoxFor(args) {
+    const path = args[0] instanceof Path2D ? args[0] : this._path;
+    const tag = path._roundRect;
+    if (path === this._path) {
+      if (tag) return tag;
+      // a roundRect that could not be tagged at record time left the reason
+      if (path._roundRectMiss) this._shapeMiss(path._roundRectMiss);
+      return null;
+    }
+    if (!tag) return null;
+    const m = this._m;
+    if (!(m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1)) {
+      this._shapeMiss("transform");
+      return null;
+    }
+    return {
+      x: tag.x + m[4],
+      y: tag.y + m[5],
+      w: tag.w,
+      h: tag.h,
+      radii: tag.radii,
+    };
+  }
+
+  /** premultiplied solid colour with globalAlpha folded in — scaling all
+   * four components of a premultiplied colour is exactly what compositing
+   * it at that opacity means */
+  _foldedColor(style) {
+    const c = parseColor(style);
+    const a = this.globalAlpha;
+    return a >= 1 ? c : [c[0] * a, c[1] * a, c[2] * a, c[3] * a];
+  }
+
+  _tryRoundRectFill(args) {
+    const box = this._shapeBoxFor(args);
+    if (!box) return false;
+    // maxRadius <= 0 is the documented off switch (NTK_NO_SHAPE_GLYPHS
+    // sets it too): everything falls through, including zero-radius boxes
+    const policy = shapePolicyOf(this.window.app);
+    if (policy.maxRadius <= 0) return this._shapeMiss("radius-cap");
+    // (a rounded rect is one simple closed curve, so the fill rule cannot
+    // change what it covers — the rule argument needs no inspection)
+    if (!isPlainColor(this._fillStyle)) return this._shapeMiss("gradient");
+    if (this._gco !== "source-over") return this._shapeMiss("composite-op");
+    const clip = this._clips.length ? this._clipRect() : null;
+    if (this._clips.length && !clip) return this._shapeMiss("clip-mask");
+
+    const { x, y, w, h, radii } = box;
+    if (
+      !Number.isInteger(x) ||
+      !Number.isInteger(y) ||
+      !Number.isInteger(w) ||
+      !Number.isInteger(h)
+    ) {
+      return this._shapeMiss("fractional");
+    }
+    for (const r of radii) {
+      if (!Number.isInteger(r.x) || !Number.isInteger(r.y))
+        return this._shapeMiss("fractional");
+      if (r.x > policy.maxRadius || r.y > policy.maxRadius)
+        return this._shapeMiss("radius-cap");
+    }
+    // wire coordinates are INT16, and glyph position deltas too
+    if (
+      x < -32768 ||
+      y < -32768 ||
+      x + w > 32767 ||
+      y + h > 32767 ||
+      w > 32767 ||
+      h > 32767
+    ) {
+      return this._shapeMiss("geometry");
+    }
+    const [tl, tr, br, bl] = radii;
+    // effective corner boxes — a corner with either radius 0 is square
+    const c = {
+      tlw: tl.x && tl.y ? tl.x : 0,
+      tlh: tl.x && tl.y ? tl.y : 0,
+      trw: tr.x && tr.y ? tr.x : 0,
+      trh: tr.x && tr.y ? tr.y : 0,
+      blw: bl.x && bl.y ? bl.x : 0,
+      blh: bl.x && bl.y ? bl.y : 0,
+      brw: br.x && br.y ? br.x : 0,
+      brh: br.x && br.y ? br.y : 0,
+    };
+    // diagonally opposite corner boxes must not overlap or the partition
+    // would paint pixels twice (same-edge pairs are bounded by the radii
+    // normalization, but the diagonal is not)
+    if (
+      (c.tlw + c.brw > w && c.tlh + c.brh > h) ||
+      (c.trw + c.blw > w && c.trh + c.blh > h)
+    ) {
+      return this._shapeMiss("geometry");
+    }
+    if (this.globalAlpha <= 0 || w <= 0 || h <= 0) {
+      // nothing to draw — and the fallback would draw nothing too
+      countShapeHit();
+      this.shapeStats.hits++;
+      return true;
+    }
+
+    const corners = [];
+    if (c.tlw) {
+      corners.push({
+        key: cornerKey("fill", c.tlw, c.tlh, 0, TL),
+        kind: "fill", rx: c.tlw, ry: c.tlh, bw: 0, corner: TL,
+        px: x, py: y,
+      });
+    }
+    if (c.trw) {
+      corners.push({
+        key: cornerKey("fill", c.trw, c.trh, 0, TR),
+        kind: "fill", rx: c.trw, ry: c.trh, bw: 0, corner: TR,
+        px: x + w - c.trw, py: y,
+      });
+    }
+    if (c.blw) {
+      corners.push({
+        key: cornerKey("fill", c.blw, c.blh, 0, BL),
+        kind: "fill", rx: c.blw, ry: c.blh, bw: 0, corner: BL,
+        px: x, py: y + h - c.blh,
+      });
+    }
+    if (c.brw) {
+      corners.push({
+        key: cornerKey("fill", c.brw, c.brh, 0, BR),
+        kind: "fill", rx: c.brw, ry: c.brh, bw: 0, corner: BR,
+        px: x + w - c.brw, py: y + h - c.brh,
+      });
+    }
+    const rects = roundRectBandRects(x, y, w, h, c);
+    this._emitShapeGlyphs(corners, rects, this._foldedColor(this._fillStyle), clip);
+    return true;
+  }
+
+  /**
+   * Stroke fast path for a device-space box (from a roundRect tag or
+   * strokeRect). Beyond the fill's conditions: uniform lineWidth, no
+   * dashes — and the half-pixel one that matters: the stroke band must land
+   * on pixel boundaries. A 1px border drawn the correct way (path inset by
+   * bw/2, so the band [X, X+1] sits on integers) passes; a 1px stroke on
+   * integer path coordinates is genuinely a two-row 50% band and must keep
+   * falling back, because the fast path would not reproduce it.
+   */
+  _tryStrokeBox(box) {
+    // the same off switch as the fill's — see _tryRoundRectFill
+    const policy = shapePolicyOf(this.window.app);
+    if (policy.maxRadius <= 0) return this._shapeMiss("radius-cap");
+    if (!isPlainColor(this._strokeStyle)) return this._shapeMiss("gradient");
+    if (this._gco !== "source-over") return this._shapeMiss("composite-op");
+    if (this._lineDash.length) return this._shapeMiss("dashes");
+    const clip = this._clips.length ? this._clipRect() : null;
+    if (this._clips.length && !clip) return this._shapeMiss("clip-mask");
+
+    const bw = this.lineWidth;
+    if (!Number.isFinite(bw) || bw <= 0) return this._shapeMiss("geometry");
+    const { x, y, w, h, radii } = box;
+    if (!(w > 0 && h > 0)) return this._shapeMiss("geometry");
+    // one circular radius for all four corners: the ring glyph is keyed on
+    // a single (r, bw) and mixed or elliptical corners fall back
+    const r0 = radii[0];
+    for (const r of radii) {
+      if (r.x !== r0.x || r.y !== r0.y) return this._shapeMiss("radii-mix");
+    }
+    if (r0.x !== r0.y) return this._shapeMiss("radii-mix");
+    const r = r0.x;
+
+    const X0 = x - bw / 2; // outer band corner
+    const Y0 = y - bw / 2;
+    const W = w + bw; // outer band size
+    const H = h + bw;
+    if (
+      !Number.isInteger(X0) ||
+      !Number.isInteger(Y0) ||
+      !Number.isInteger(W) ||
+      !Number.isInteger(H) ||
+      !Number.isInteger(r)
+    ) {
+      return this._shapeMiss("fractional");
+    }
+    if (
+      X0 < -32768 ||
+      Y0 < -32768 ||
+      X0 + W > 32767 ||
+      Y0 + H > 32767 ||
+      W > 32767 ||
+      H > 32767
+    ) {
+      return this._shapeMiss("geometry");
+    }
+    if (this.globalAlpha <= 0) {
+      countShapeHit();
+      this.shapeStats.hits++;
+      return true;
+    }
+    const color = this._foldedColor(this._strokeStyle);
+
+    if (r === 0) {
+      // square corners lower to four FillRectangles with no glyphs at all —
+      // but only when the miter join actually squares them (the default);
+      // bevel or round corners look different and keep the polygon route
+      if (this.lineJoin !== "miter" || this.miterLimit < Math.SQRT2)
+        return this._shapeMiss("join");
+      if (W < 2 * bw || H < 2 * bw) return this._shapeMiss("geometry");
+      const rects = [X0, Y0, W, bw, X0, Y0 + H - bw, W, bw];
+      if (H > 2 * bw) {
+        rects.push(X0, Y0 + bw, bw, H - 2 * bw);
+        rects.push(X0 + W - bw, Y0 + bw, bw, H - 2 * bw);
+      }
+      this._emitShapeGlyphs([], rects, color, clip);
+      return true;
+    }
+
+    // a border thicker than the corner radius swallows the arc's centre;
+    // the ring glyph does not model that, so it stays on the polygon route
+    if (r - bw / 2 < 0) return this._shapeMiss("geometry");
+    const K = Math.ceil(r + bw / 2); // corner glyph box, integer cut lines
+    if (K > policy.maxRadius) return this._shapeMiss("radius-cap");
+    if (2 * K > W || 2 * K > H) return this._shapeMiss("geometry");
+
+    const corners = [
+      {
+        key: cornerKey("stroke", r, r, bw, TL),
+        kind: "stroke", rx: r, ry: r, bw, corner: TL,
+        px: X0, py: Y0,
+      },
+      {
+        key: cornerKey("stroke", r, r, bw, TR),
+        kind: "stroke", rx: r, ry: r, bw, corner: TR,
+        px: X0 + W - K, py: Y0,
+      },
+      {
+        key: cornerKey("stroke", r, r, bw, BL),
+        kind: "stroke", rx: r, ry: r, bw, corner: BL,
+        px: X0, py: Y0 + H - K,
+      },
+      {
+        key: cornerKey("stroke", r, r, bw, BR),
+        kind: "stroke", rx: r, ry: r, bw, corner: BR,
+        px: X0 + W - K, py: Y0 + H - K,
+      },
+    ];
+    const rects = [];
+    if (W > 2 * K) {
+      rects.push(X0 + K, Y0, W - 2 * K, bw);
+      rects.push(X0 + K, Y0 + H - bw, W - 2 * K, bw);
+    }
+    if (H > 2 * K) {
+      rects.push(X0, Y0 + K, bw, H - 2 * K);
+      rects.push(X0 + W - bw, Y0 + K, bw, H - 2 * K);
+    }
+    this._emitShapeGlyphs(corners, rects, color, clip);
+    return true;
+  }
+
+  /**
+   * Emit one recognized box: ensure the corner glyphs, one CompositeGlyphs
+   * run for them, one FillRectangles for the strips — inside a server-side
+   * clip rectangle when the clip stack is rectangular (the way glyph runs
+   * for text already do it).
+   */
+  _emitShapeGlyphs(corners, rects, color, clip) {
+    countShapeHit();
+    this.shapeStats.hits++;
+    if (clip && (clip.w === 0 || clip.h === 0)) return; // clipped away
+    const R = this.Render;
+    const app = this.window.app;
+    if (clip) {
+      R.SetPictureClipRectangles(this.picture.id, 0, 0, [
+        clip.x,
+        clip.y,
+        clip.w,
+        clip.h,
+      ]);
+    }
+    if (corners.length) {
+      const page = getShapeGlyphPage(app);
+      page.ensure(corners);
+      const items = [];
+      for (const spec of corners) {
+        items.push({
+          gs: page.glyphset.id,
+          lid: page.entry(spec.key).lid,
+          adv: 0,
+          x: spec.px,
+          y: spec.py,
+        });
+      }
+      const encoded = encodeGlyphItems(items, page.bits);
+      const src = app.solidPicture(color[0], color[1], color[2], color[3]);
+      R.CompositeGlyphs(
+        encoded.bits,
+        R.PictOp.Over,
+        src.id,
+        this.picture.id,
+        0,
+        encoded.gsid,
+        items[0].x,
+        items[0].y,
+        encoded.elts,
+      );
+      trimShapeGlyphs(app);
+    }
+    if (rects.length) {
+      R.FillRectangles(R.PictOp.Over, this.picture.id, color, rects);
+    }
+    if (clip) this._resetPictureClip();
+    this._markDirty();
+  }
+
   /**
    * Intersect the clip region with the given path (or the current path).
    * Cleared by restore() to the state at the matching save() — like the

package/lib/shapeglyphs.js

@@ -0,0 +1,327 @@
+// Rounded-rectangle fast path (issue #211): the server-side corner-glyph
+// cache and the geometry helpers behind it.
+//
+// A recognized `fill()`/`stroke()` of an axis-aligned rounded rect is not
+// rasterized as a polygon at all: its only curved ink — the corners — is
+// emitted as XRender *glyphs* (the one path every server accelerates, cached
+// server-side after first use), and the straight runs between them as
+// FillRectangles. The 2d context owns the recognition and the emission
+// (lib/renderingcontext_2d.js); this module owns the cache and the corner
+// bitmaps.
+//
+// The pieces partition the pixels: corner glyphs own their integer-cut
+// boxes, rects own the strips between, and no pixel is painted twice — which
+// is what makes translucent colours safe with no mask format and no
+// accumulation tricks. Each corner rasterizes the true geometry inside its
+// region through the same ellipse lowering and coverage accumulator the
+// polygon fallback uses, so the two routes agree to the last antialiased
+// step.
+//
+// Corners are the whole cache: keyed by (kind, rx, ry, borderWidth, corner),
+// so width and height are *not* in the key — an animating progress bar or
+// pill keeps all its glyphs while the rects stretch. The server additionally
+// deduplicates glyph bitmaps across clients by content hash, so every app
+// using the same radii shares storage.
+//
+// Mirrored corners: only the top-left corner of a (kind, rx, ry, bw) family
+// is ever rasterized; the other three are byte-level mirror flips of that
+// bitmap (see `orientCorner`). RENDER has no per-glyph transform, so the
+// *server* still needs all four bitmaps — the flip saves the three extra
+// rasterizations and makes the four corners of a box pixel-exact mirror
+// images of each other, which direct per-corner rasterization does not
+// guarantee (floating-point coverage accumulation is not symmetric under
+// reflection).
+
+import GlyphSet from './glyphset.js';
+import { ellipseSegments, flattenPath } from './path.js';
+import { rasterizePolys } from './rasterize.js';
+
+/**
+ * Shape rendering policy, overridable per app via `app.shapePolicy`
+ * (partial objects are fine — `app.shapePolicy = { maxRadius: 0 }` disables
+ * the fast path entirely, which is also what `NTK_NO_SHAPE_GLYPHS=1` does).
+ *
+ * - `maxRadius` — corners with a radius (or stroke-band extent) above this
+ *   fall back to the polygon route. Glyph-atlas behaviour past ~64px is
+ *   driver-specific; the conservative default keeps every plausible widget
+ *   inside and every atlas happy.
+ * - `cacheBytes` — budget for uploaded corner bitmaps per connection. A
+ *   design system's whole population is 8 glyphs x r^2 bytes per (r, bw) —
+ *   typically 10-20KB — so even this small budget is generous. Exceeding it
+ *   (an adversarial animated-radius load) resets the page; steady states
+ *   never do.
+ */
+export const DEFAULT_SHAPE_POLICY = {
+  maxRadius: 64,
+  cacheBytes: 256 << 10
+};
+
+const envDisabled =
+  typeof process !== 'undefined' && process.env && process.env.NTK_NO_SHAPE_GLYPHS;
+
+export function shapePolicyOf(app) {
+  const policy = app.shapePolicy
+    ? { ...DEFAULT_SHAPE_POLICY, ...app.shapePolicy }
+    : DEFAULT_SHAPE_POLICY;
+  return envDisabled ? { ...policy, maxRadius: 0 } : policy;
+}
+
+// corner codes, also the two flip bits: bit 0 = mirrored in x, bit 1 = in y
+export const TL = 0;
+export const TR = 1;
+export const BL = 2;
+export const BR = 3;
+
+/** cache key of one corner glyph. `bw` is 0 for fills. */
+export function cornerKey(kind, rx, ry, bw, corner) {
+  return `${kind}|${rx}|${ry}|${bw}|${corner}`;
+}
+
+/**
+ * Rasterize the top-left master bitmap of a corner family.
+ *
+ * kind 'fill': the quarter disc — the corner box is rx x ry with the ellipse
+ * centred on its bottom-right point; everything inside the arc has full
+ * coverage, so the box's straight cut edges land on interior pixels.
+ *
+ * kind 'stroke': the quarter ring — the stroke band around a corner of path
+ * radius `r = rx` with line width `bw`. The box is K x K, K = ceil(r + bw/2),
+ * anchored on the *outer* corner of the band; the ink is the annulus sector
+ * plus the straight band continuations out to the box edges, so the box
+ * edges cut the band where its pixels are fully covered whatever half-pixel
+ * the arc ends on (a 1px border's path sits on half-integers).
+ *
+ * The arc is lowered exactly the way the polygon fallback lowers it —
+ * `ellipseSegments` cubics flattened by `flattenPath` at the default
+ * tolerance, rasterized by the same coverage accumulator — so the fast path
+ * agrees with the fallback to the last antialiased step.
+ *
+ * @returns {{ w, h, stride, data: Uint8Array }} unpadded w x h coverage
+ */
+export function rasterizeCornerMaster(kind, rx, ry, bw) {
+  let w;
+  let h;
+  let cmds;
+  if (kind === 'fill') {
+    w = rx;
+    h = ry;
+    const arc = ellipseSegments(rx, ry, rx, ry, 0, Math.PI, Math.PI * 1.5);
+    cmds = [
+      { type: 'M', x: arc.start.x, y: arc.start.y }, // (0, ry)
+      ...arc.cmds, // -> (rx, 0)
+      { type: 'L', x: rx, y: ry },
+      { type: 'Z' }
+    ];
+  } else {
+    const r = rx;
+    const ro = r + bw / 2;
+    const ri = r - bw / 2;
+    const K = Math.ceil(ro);
+    w = K;
+    h = K;
+    const outer = ellipseSegments(ro, ro, ro, ro, 0, Math.PI, Math.PI * 1.5);
+    // the inner arc runs backwards, closing the ring; at ri = 0 it collapses
+    // to the centre point and the ink is the whole quarter disc
+    const inner = ellipseSegments(ro, ro, ri, ri, 0, Math.PI * 1.5, Math.PI, true);
+    cmds = [
+      { type: 'M', x: 0, y: K },
+      { type: 'L', x: 0, y: ro },
+      ...outer.cmds, // -> (ro, 0)
+      { type: 'L', x: K, y: 0 },
+      { type: 'L', x: K, y: bw },
+      { type: 'L', x: inner.start.x, y: inner.start.y }, // (ro, bw)
+      ...inner.cmds, // -> (bw, ro)
+      { type: 'L', x: bw, y: K },
+      { type: 'Z' }
+    ];
+  }
+  const polys = [];
+  for (const poly of flattenPath(cmds)) if (poly.pts.length >= 6) polys.push(poly.pts);
+  const data = rasterizePolys(polys, w, h, 'nonzero');
+  return { w, h, stride: (w + 3) & ~3, data };
+}
+
+/**
+ * One oriented corner bitmap from the top-left master: a byte-level mirror
+ * flip, padded to the 4-byte row stride AddGlyphs wants. Flipping bytes
+ * rather than re-rasterizing mirrored geometry keeps the four corners exact
+ * mirror images and costs a copy instead of a coverage accumulation.
+ */
+export function orientCorner(master, corner) {
+  const { w, h, stride, data } = master;
+  const out = Buffer.alloc(stride * h);
+  const flipX = (corner & 1) !== 0;
+  const flipY = (corner & 2) !== 0;
+  for (let y = 0; y < h; y++) {
+    const srow = (flipY ? h - 1 - y : y) * w;
+    const orow = y * stride;
+    if (flipX) {
+      for (let x = 0; x < w; x++) out[orow + x] = data[srow + (w - 1 - x)];
+    } else {
+      out.set(data.subarray(srow, srow + w), orow);
+    }
+  }
+  return out;
+}
+
+/**
+ * Server-side cache of corner glyphs — one page per app, all radii and
+ * border widths together, mirroring `GlyphPage` for text (text/glyphs.js).
+ *
+ * Local ids are compact and sequential so CompositeGlyphs uses the 8-bit
+ * encoding for the first 256 distinct corners (a shape population never
+ * leaves it in practice); new corners upload lazily in one AddGlyphs batch
+ * per draw that introduces any.
+ */
+export class ShapeGlyphPage {
+  constructor(app) {
+    this.app = app;
+    this.glyphset = new GlyphSet(app);
+    this.entries = new Map(); // cornerKey -> { lid }
+    this.bytes = 0; // uploaded bitmap bytes, for the cache budget
+  }
+
+  /** bits per glyph id needed to address this page */
+  get bits() {
+    return this.entries.size <= 256 ? 8 : 16;
+  }
+
+  /**
+   * Ensure the corners of one drawing are uploaded. `specs` is
+   * [{ key, kind, rx, ry, bw, corner }] — a spec whose key is present costs
+   * a Map hit and nothing else. Within one batch the top-left master of each
+   * (kind, rx, ry, bw) family rasterizes once and the other corners mirror
+   * it (see `orientCorner`).
+   */
+  ensure(specs) {
+    let batch = null;
+    let masters = null;
+    for (const spec of specs) {
+      if (this.entries.has(spec.key)) continue;
+      const lid = this.entries.size;
+      if (lid >= 65536) {
+        // 2^16 corners on one connection — unreachable (the cache budget
+        // resets the page long before), but fail loudly rather than corrupt
+        throw new Error('shape glyph page overflow');
+      }
+      const mkey = `${spec.kind}|${spec.rx}|${spec.ry}|${spec.bw}`;
+      if (!masters) masters = new Map();
+      let master = masters.get(mkey);
+      if (!master) {
+        master = rasterizeCornerMaster(spec.kind, spec.rx, spec.ry, spec.bw);
+        masters.set(mkey, master);
+      }
+      const image = orientCorner(master, spec.corner);
+      this.entries.set(spec.key, { lid });
+      if (!batch) batch = [];
+      batch.push({
+        id: lid,
+        // width is the padded stride, like the text page: node-x11 then
+        // ships the buffer as-is instead of re-padding a copy, and the spare
+        // zero columns composite as no-ops under Over
+        width: master.stride,
+        height: master.h,
+        // x/y 0: the glyph's top-left lands exactly on its elt position
+        x: 0,
+        y: 0,
+        // corners do not advance a pen. node-x11 expects offX/offY in 26.6
+        // fixed point and mutates the objects it is given, which is why
+        // these are fresh one-shot objects (see AGENTS.md)
+        offX: 0,
+        offY: 0,
+        image
+      });
+      this.bytes += image.length;
+    }
+    if (batch) this.glyphset.addGlyphs(batch);
+  }
+
+  entry(key) {
+    return this.entries.get(key);
+  }
+
+  /** free the server-side glyphset (budget reset / shutdown) */
+  destroy() {
+    this.glyphset.destroy();
+    this.entries.clear();
+    this.bytes = 0;
+  }
+}
+
+/** the per-app page, created on first use */
+export function getShapeGlyphPage(app) {
+  if (!app._shapeGlyphPage) app._shapeGlyphPage = new ShapeGlyphPage(app);
+  return app._shapeGlyphPage;
+}
+
+/**
+ * Enforce the cache budget after a draw. Corner populations are so small
+ * that per-glyph LRU would be bookkeeping for its own sake — over budget
+ * (an adversarial animated-radius load) the whole page resets and the
+ * corners still in use re-upload on the next draw, bounding server memory
+ * at `cacheBytes` plus one animation step. FreeGlyphSet is queued after any
+ * CompositeGlyphs already issued, so mid-frame resets are ordering-safe.
+ */
+export function trimShapeGlyphs(app, policy = shapePolicyOf(app)) {
+  const page = app._shapeGlyphPage;
+  if (page && page.bytes > policy.cacheBytes) {
+    page.destroy();
+    app._shapeGlyphPage = null;
+  }
+}
+
+/**
+ * The strips of a rounded-rect fill that are not corner glyphs, as a flat
+ * FillRectangles list. Rows are cut at every corner-box edge; each band
+ * spans between the corner boxes that reach it. Uniform radii produce the
+ * classic 3 bands; fully general per-corner radii at most 5.
+ *
+ * `c` holds the effective corner box sizes { tlw, tlh, trw, trh, blw, blh,
+ * brw, brh } (zero for square corners). Caller guarantees same-edge sums fit
+ * (normalizeRadii does) and that diagonally opposite boxes do not overlap.
+ */
+export function roundRectBandRects(x, y, w, h, c) {
+  const cuts = [...new Set([0, c.tlh, c.trh, h - c.blh, h - c.brh, h])]
+    .filter((v) => v >= 0 && v <= h)
+    .sort((a, b) => a - b);
+  const rects = [];
+  for (let i = 0; i + 1 < cuts.length; i++) {
+    const y0 = cuts[i];
+    const y1 = cuts[i + 1];
+    if (y1 <= y0) continue;
+    const left = Math.max(y0 < c.tlh ? c.tlw : 0, y1 > h - c.blh ? c.blw : 0);
+    const right = Math.max(y0 < c.trh ? c.trw : 0, y1 > h - c.brh ? c.brw : 0);
+    const bandW = w - left - right;
+    if (bandW > 0) rects.push(x + left, y + y0, bandW, y1 - y0);
+  }
+  return rects;
+}
+
+// process-wide observability: every bail-out is a silent perf cliff, so the
+// counters are always collected (cheap increments) and printed at exit under
+// NTK_DEBUG_SHAPES=1. Contexts carry their own copies for per-surface
+// inspection (ctx.shapeStats).
+export const shapeGlyphCounters = { hits: 0, misses: {} };
+
+export function countShapeMiss(reason) {
+  shapeGlyphCounters.misses[reason] = (shapeGlyphCounters.misses[reason] || 0) + 1;
+}
+
+export function countShapeHit() {
+  shapeGlyphCounters.hits++;
+}
+
+if (
+  typeof process !== 'undefined' &&
+  process.env &&
+  process.env.NTK_DEBUG_SHAPES &&
+  typeof process.on === 'function'
+) {
+  process.on('exit', () => {
+    const { hits, misses } = shapeGlyphCounters;
+    const parts = Object.entries(misses).map(([k, v]) => `${k}: ${v}`);
+    console.error(
+      `ntk shapes: ${hits} fast-path draws, misses { ${parts.join(', ')} }`
+    );
+  });
+}

package/lib/window.js

@@ -348,6 +348,9 @@ export default class Window extends Drawable {
     this._foreign = !!args.id;
     this._backingOptOut = args.backingStore === false;
     this._backing = null;
+    // What the backing store clears to, and the window attribute it mirrors.
+    // Undefined means "nothing was asked for" — see _clearColour.
+    this._clearPixel = args.backgroundPixel;
     this._dirty = false;
     this._presentPending = false;
 
@@ -696,9 +699,60 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * The pixel the backing store's unpainted area is cleared to.
+   *
+   * A pixmap's contents start *undefined* — whatever was in that memory — so
+   * something has to be written before it can be presented, and the same goes
+   * for the region a grow adds. What that something is follows the window's
+   * own `backgroundPixel`, which is exactly what the server would paint into
+   * exposed area on a window with no backing store. Without one: transparent
+   * for a depth-32 ARGB window, and the screen's white otherwise.
+   */
+  _clearColour() {
+    if (this._clearPixel !== undefined) return this._clearPixel;
+    const depth = this.depth || this.display.screen[0].root_depth;
+    return depth === 32 ? 0 : this.display.screen[0].white_pixel;
+  }
+
+  /**
+   * The window's background colour, as an X pixel value.
+   *
+   * A double-buffered window has two of them and they have to agree: the X
+   * window attribute the server paints into exposed area, and the colour the
+   * backing store clears to. Setting one and not the other is why a resize
+   * could show white on a window that draws itself dark.
+   *
+   * The backing store's *headroom* — the area a future grow will expand
+   * into, which by definition holds nothing yet — is recoloured too, so a
+   * later resize does not expose the previous colour.
+   */
+  setBackgroundPixel(pixel) {
+    this._clearPixel = pixel;
+    if (this._destroyed) return this;
+    if (this._clearGc) this.X.ChangeGC(this._clearGc, { foreground: pixel });
+    if (!this._foreign) {
+      this.X.ChangeWindowAttributes(this.id, { backgroundPixel: pixel }, () => {});
+    }
+    const backing = this._backing;
+    if (backing && this._clearGc) {
+      const rects = [];
+      if (backing.width > this.width) {
+        rects.push(this.width, 0, backing.width - this.width, backing.height);
+      }
+      if (backing.height > this.height) {
+        rects.push(0, this.height, this.width, backing.height - this.height);
+      }
+      if (rects.length) this.X.PolyFillRectangle(backing.id, this._clearGc, rects);
+    }
+    return this;
+  }
+
   // grow-only backing pixmap (re)allocation, with headroom (see
-  // BACKING_GRANULARITY); new area is cleared to the window's background
-  // (white for opaque windows, fully transparent for depth-32 ARGB ones)
+  // BACKING_GRANULARITY). What is already drawn is carried across and only
+  // the region the grow adds is cleared (see _clearColour) — clearing the
+  // whole pixmap made the *entire* window flash the clear colour between a
+  // resize and the redraw, not just the new strip.
   _allocBacking(w, h) {
     const cur = this._backing;
     if (cur && cur.width >= w && cur.height >= h) return;
@@ -715,11 +769,21 @@ export default class Window extends Drawable {
     if (!this._clearGc) {
       this._clearGc = this.X.AllocID();
       this.X.CreateGC(this._clearGc, pixmap.id, {
-        foreground: depth === 32 ? 0 : this.display.screen[0].white_pixel,
+        foreground: this._clearColour(),
         graphicsExposures: 0
       });
     }
-    this.X.PolyFillRectangle(pixmap.id, this._clearGc, [0, 0, newW, newH]);
+    if (cur) {
+      // The new pixmap is strictly larger, so the old content lands at the
+      // same coordinates and only the L-shaped remainder is new.
+      this.X.CopyArea(cur.id, pixmap.id, this._clearGc, 0, 0, 0, 0, cur.width, cur.height);
+      const rects = [];
+      if (newW > cur.width) rects.push(cur.width, 0, newW - cur.width, newH);
+      if (newH > cur.height) rects.push(0, cur.height, cur.width, newH - cur.height);
+      if (rects.length) this.X.PolyFillRectangle(pixmap.id, this._clearGc, rects);
+    } else {
+      this.X.PolyFillRectangle(pixmap.id, this._clearGc, [0, 0, newW, newH]);
+    }
     if (cur) cur.destroy();
     this._backing = pixmap;
     this._backingValid = false;

package/package.json

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