ntk 8.0.0 → 8.1.1

package/lib/renderingcontext_2d.js

@@ -27,6 +27,13 @@ import {
 import Picture from "./picture.js";
 import Pixmap from "./pixmap.js";
 import { routeRaster } from "./rasterize.js";
+import {
+  blurCoverage,
+  cachedShadow,
+  shadowPolicyOf,
+  shadowReach,
+  shadowSigma,
+} from "./shadow.js";
 import { Surface } from "./surface.js";
 import {
   BL,
@@ -76,6 +83,37 @@ function intersectBox(a, b) {
   return { x, y, w: right - x, h: bottom - y };
 }
 
+/** The device-space ink bounds of a flattened path, unclamped. */
+function polysInk(polys) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const poly of polys) {
+    const pts = poly.pts;
+    for (let i = 0; i < pts.length; i += 2) {
+      if (pts[i] < minX) minX = pts[i];
+      if (pts[i] > maxX) maxX = pts[i];
+      if (pts[i + 1] < minY) minY = pts[i + 1];
+      if (pts[i + 1] > maxY) maxY = pts[i + 1];
+    }
+  }
+  return maxX === -Infinity ? null : { minX, minY, maxX, maxY };
+}
+
+/** the same list, moved — the shadow's copy of a drawing is the same
+ * geometry in the coverage surface's coordinates */
+function shiftPolys(polys, dx, dy) {
+  return polys.map((poly) => {
+    const pts = new Array(poly.pts.length);
+    for (let i = 0; i < pts.length; i += 2) {
+      pts[i] = poly.pts[i] + dx;
+      pts[i + 1] = poly.pts[i + 1] + dy;
+    }
+    return { ...poly, pts };
+  });
+}
+
 const DEFAULT_FONT = "20px sans-serif";
 
 // `"wght" 460, "wdth" 87.5` — the CSS grammar, quotes optional. An object is
@@ -95,6 +133,17 @@ function parseVariationSettings(val) {
   return any ? out : null;
 }
 
+/** a stable string for a variation setting, for cache keys — two Fonts of
+ * one file at different axis positions share a `key`, so the coordinates
+ * have to be part of anything keyed on the rendered result */
+function variationsKey(variations) {
+  if (!variations) return "";
+  return Object.keys(variations)
+    .sort()
+    .map((tag) => `${tag}=${variations[tag]}`)
+    .join(",");
+}
+
 /**
  * Fallback for a context dropped without `destroy()`, matching Pixmap,
  * Picture and GlyphSet. Only the GCs are freed here: everything else a
@@ -198,13 +247,21 @@ function patternSourceOf(app, source) {
 }
 
 /**
- * Point a pattern's picture transform at the transform in force for this
- * fill — patterns are painted in user space, so the CTM is part of the
- * mapping. Returns false when nothing would be painted (a singular matrix),
- * true for anything else, including every non-pattern style.
+ * Point a style's picture transform at the transform in force for this
+ * paint. Gradients and patterns are both defined in *user* space, so the CTM
+ * is part of the mapping — and per the canvas spec it is the CTM at paint
+ * time, not the one that happened to be current when the style was made
+ * (verified against browsers: a gradient created untransformed and filled
+ * after a `translate` moves with the fill, and one created under a translate
+ * and filled without it does not).
+ *
+ * Returns false when nothing would be painted (a singular matrix), true for
+ * anything else, including every plain-colour style.
  */
-function preparePattern(src, m) {
-  return src instanceof CanvasPattern ? src._sync(m) : true;
+function prepareStyle(src, m) {
+  return src instanceof CanvasPattern || src instanceof CanvasGradient
+    ? src._sync(m)
+    : true;
 }
 
 function isPictureSource(image) {
@@ -422,6 +479,15 @@ class RenderingContext2d {
     this._lineDash = [];
     this._lineDashOffset = 0;
 
+    this._shadowBlur = 0;
+    this._shadowOffsetX = 0;
+    this._shadowOffsetY = 0;
+    // "transparent black" — the spec's default, and the one value that
+    // skips the whole shadow path, so an app that never asks for a shadow
+    // never pays for one
+    this._shadowColor = "rgba(0, 0, 0, 0)";
+    this._shadowRgba = [0, 0, 0, 0];
+
     this.fillStyle = "white";
     this.strokeStyle = "black";
     this.lineWidth = 1;
@@ -660,6 +726,11 @@ class RenderingContext2d {
       textRendering: this._textRendering,
       textAlign: this.textAlign,
       textBaseline: this.textBaseline,
+      shadowBlur: this._shadowBlur,
+      shadowColor: this._shadowColor,
+      shadowRgba: this._shadowRgba,
+      shadowOffsetX: this._shadowOffsetX,
+      shadowOffsetY: this._shadowOffsetY,
       m: this._m.slice(),
       clips: this._clips,
     });
@@ -684,6 +755,11 @@ class RenderingContext2d {
     this._textRendering = s.textRendering;
     this.textAlign = s.textAlign;
     this.textBaseline = s.textBaseline;
+    this._shadowBlur = s.shadowBlur;
+    this._shadowColor = s.shadowColor;
+    this._shadowRgba = s.shadowRgba;
+    this._shadowOffsetX = s.shadowOffsetX;
+    this._shadowOffsetY = s.shadowOffsetY;
     this._m = s.m;
     if (s.clips !== this._clips) {
       this._clips = s.clips;
@@ -691,6 +767,398 @@ class RenderingContext2d {
     }
   }
 
+  // ------------------------------------------------------------------
+  // shadows (issue #272)
+  //
+  // The canvas properties, and the three server-side steps behind them: the
+  // drawing's coverage into a padded `a8` surface, a separable gaussian over
+  // it, and one masked composite in `shadowColor`. See lib/shadow.js for the
+  // blur and the cache, and docs/context-2d.md for what an app sees.
+
+  /**
+   * Gaussian blur applied to the shadow, in pixels. Canvas-spec units: this
+   * is a **diameter**, and the gaussian it names has σ = `shadowBlur / 2`,
+   * so a value here looks the same as the same value in a browser.
+   *
+   * Negative and non-finite values are ignored, as the spec requires.
+   */
+  set shadowBlur(value) {
+    const v = Number(value);
+    if (Number.isFinite(v) && v >= 0) this._shadowBlur = v;
+  }
+
+  get shadowBlur() {
+    return this._shadowBlur;
+  }
+
+  /**
+   * The shadow's colour. Defaults to fully transparent black, which is the
+   * spec's default and the switch that keeps every drawing operation on
+   * exactly the path it was on before shadows existed.
+   *
+   * A value that is not a colour is ignored (the spec's rule), so a
+   * mistyped colour leaves the previous shadow rather than throwing from
+   * inside a paint.
+   */
+  set shadowColor(value) {
+    let rgba;
+    try {
+      rgba = parseColor(value);
+    } catch {
+      return;
+    }
+    this._shadowColor = value;
+    this._shadowRgba = rgba;
+  }
+
+  get shadowColor() {
+    return this._shadowColor;
+  }
+
+  /**
+   * How far the shadow is offset. In **device** pixels: the spec puts
+   * shadow offsets outside the current transform, so a rotated drawing has
+   * an upright shadow, the same way a rotated element's box-shadow is
+   * upright in CSS.
+   *
+   * Offsets are rounded to whole pixels when the shadow is composited. The
+   * drawing's own sub-pixel position is preserved either way; what rounds
+   * is where its blurred copy lands.
+   */
+  set shadowOffsetX(value) {
+    const v = Number(value);
+    if (Number.isFinite(v)) this._shadowOffsetX = v;
+  }
+
+  get shadowOffsetX() {
+    return this._shadowOffsetX;
+  }
+
+  set shadowOffsetY(value) {
+    const v = Number(value);
+    if (Number.isFinite(v)) this._shadowOffsetY = v;
+  }
+
+  get shadowOffsetY() {
+    return this._shadowOffsetY;
+  }
+
+  /**
+   * Is there a shadow to paint at all?
+   *
+   * A shadow with no offset and no blur still paints — it lands exactly
+   * under the drawing, where it shows through anything translucent, which
+   * is what the spec says and what browsers do. Only a transparent
+   * `shadowColor` (the default) skips the work, so the answer is one array
+   * read on every fill of every app that never mentioned shadows.
+   */
+  _shadowed() {
+    return this._shadowRgba[3] > 0 && this.globalAlpha > 0;
+  }
+
+  /**
+   * The coverage surface's box in device space: the drawing's ink, padded by
+   * `reach` on every side so the blur has room to spread into, and clipped
+   * to the part of the drawing whose shadow could land on the target at all.
+   *
+   * That clip is exact rather than a heuristic. A source pixel at `s`
+   * spreads to shadow pixels `s + offset ± reach`, so ink further than
+   * `reach` outside the target (once the offset is undone) cannot contribute
+   * a single pixel of visible shadow — dropping it costs nothing and keeps a
+   * shape far off-screen from allocating a surface the size of its own
+   * bounding box.
+   */
+  _shadowBox(ink, reach) {
+    const ox = Math.round(this._shadowOffsetX);
+    const oy = Math.round(this._shadowOffsetY);
+    // a pixel of slack for the antialiased edge, as _clampBBox takes
+    const x0 = Math.max(Math.floor(ink.minX) - 1, -ox - reach);
+    const y0 = Math.max(Math.floor(ink.minY) - 1, -oy - reach);
+    const x1 = Math.min(Math.ceil(ink.maxX) + 1, this.width - ox + reach);
+    const y1 = Math.min(Math.ceil(ink.maxY) + 1, this.height - oy + reach);
+    if (x1 <= x0 || y1 <= y0) return null;
+    return {
+      x: x0 - reach,
+      y: y0 - reach,
+      w: x1 - x0 + reach * 2,
+      h: y1 - y0 + reach * 2,
+    };
+  }
+
+  /**
+   * Put this context's drawing state onto the coverage surface's context.
+   *
+   * `fillStyle` is opaque white and nothing else: an `a8` surface stores
+   * coverage, so what is drawn into it has to be at full alpha and takes its
+   * colour later, at the composite. `globalAlpha`, the composite op and the
+   * clip are deliberately *not* copied — they belong to that composite, not
+   * to the shape, and applying them twice would square the alpha.
+   */
+  _loadShadowState(sctx, dx, dy) {
+    // a device-space translation in front of the transform, so a user-space
+    // call replayed here lands where the surface expects it. Translation
+    // does not change the determinant, so the transform-aware line width
+    // in _strokePolys is the same one the real stroke will use.
+    sctx._m = matMultiply([1, 0, 0, 1, dx, dy], this._m);
+    sctx.fillStyle = "#fff";
+    sctx.strokeStyle = "#fff";
+    sctx.lineWidth = this.lineWidth;
+    sctx.lineCap = this.lineCap;
+    sctx.lineJoin = this.lineJoin;
+    sctx.miterLimit = this.miterLimit;
+    sctx._lineDash = this._lineDash;
+    sctx._lineDashOffset = this._lineDashOffset;
+    sctx._textStyle = this._textStyle;
+    sctx._lastFontString = this._lastFontString;
+    sctx._fontVariations = this._fontVariations;
+    sctx._textRendering = this._textRendering;
+    sctx.textAlign = this.textAlign;
+    sctx.textBaseline = this.textBaseline;
+    return sctx;
+  }
+
+  /**
+   * Composite finished shadow coverage: the surface is the mask,
+   * `shadowColor` is the source.
+   *
+   * Borrowing `fillStyle` for the length of the call is what puts the
+   * shadow through the same route a coverage `drawImage` takes — clip,
+   * `globalAlpha`, composite op and damage reporting all apply to it exactly
+   * as they do to the drawing it belongs to.
+   */
+  _paintShadow(surface, dx, dy) {
+    const style = this._fillStyle;
+    const picture = this._backgroundPicture;
+    this.fillStyle = this._shadowColor;
+    try {
+      this._drawCoverage(
+        surface.picture(this.window.app),
+        0,
+        0,
+        surface.width,
+        surface.height,
+        dx,
+        dy,
+        surface.width,
+        surface.height,
+        this._op(),
+      );
+    } finally {
+      this._fillStyle = style;
+      this._backgroundPicture = picture;
+    }
+  }
+
+  /**
+   * Paint the shadow of one drawing, given its device-space ink bounds and
+   * a way to draw it again into the coverage surface.
+   *
+   * `replay(sctx, dx, dy)` gets a context on that surface with this one's
+   * state already on it, and the device offset that maps this context's
+   * coordinates into it. Nothing is cached: the geometry of a path has no
+   * short name to key it by. Text does, and takes `_shadowOfText` instead.
+   */
+  _shadowOfDrawing(ink, replay) {
+    if (!ink) return;
+    const app = this.window.app;
+    const policy = shadowPolicyOf(app);
+    const sigma = shadowSigma(this._shadowBlur, policy);
+    const reach = shadowReach(sigma);
+    const box = this._shadowBox(ink, reach);
+    if (!box || box.w * box.h > policy.maxPixels) return;
+
+    let surface = new Surface(app, {
+      width: box.w,
+      height: box.h,
+      format: "a8",
+    });
+    surface.render((sctx) => {
+      this._loadShadowState(sctx, -box.x, -box.y);
+      replay(sctx, -box.x, -box.y);
+    });
+    if (sigma > 0) surface = blurCoverage(surface, sigma);
+    this._paintShadow(
+      surface,
+      box.x + Math.round(this._shadowOffsetX),
+      box.y + Math.round(this._shadowOffsetY),
+    );
+    surface.destroy();
+  }
+
+  /** the shadow of a path fill or stroke, from its device-space polys */
+  _shadowOfPolys(polys, { rule = "nonzero", stroke = false } = {}) {
+    const ink = polysInk(polys);
+    if (!ink) return;
+    if (stroke) {
+      // the stroke's ink is the extruded outline, which is not built yet —
+      // over-estimate it. Half the width covers the band, the miter limit
+      // covers the spike a sharp corner can throw, and the cost of guessing
+      // high is blur over a few empty pixels.
+      const det = this._m[0] * this._m[3] - this._m[1] * this._m[2];
+      const scale = Math.sqrt(Math.abs(det)) || 1;
+      const half = (this.lineWidth * scale) / 2;
+      const spike =
+        this.lineJoin === "miter" ? Math.min(Math.max(this.miterLimit, 1), 10) : 1.5;
+      const slack = half * spike + 1;
+      ink.minX -= slack;
+      ink.minY -= slack;
+      ink.maxX += slack;
+      ink.maxY += slack;
+    }
+    this._shadowOfDrawing(ink, (sctx, dx, dy) => {
+      const moved = shiftPolys(polys, dx, dy);
+      if (stroke) sctx._strokePolys(moved);
+      else sctx._fillPolys(moved, rule);
+    });
+  }
+
+  /**
+   * The shadow of a run of text, cached.
+   *
+   * Text is the one drawing with a short, stable name — the string, the
+   * font and the blur — so its coverage is built once and composited on
+   * every frame afterwards, which is the difference between a specimen that
+   * rebuilds two surfaces and a blur per slider tick and one that does not.
+   *
+   * The cached copy is position-independent: the run's origin sits at a
+   * whole pixel inside the surface, and the composite carries it to wherever
+   * the text is. Glyph origins are rounded to whole pixels on the way to the
+   * server anyway, so nothing is lost by it.
+   */
+  _shadowOfText(text, x, y) {
+    const app = this.window.app;
+    const policy = shadowPolicyOf(app);
+    const sigma = shadowSigma(this._shadowBlur, policy);
+    const reach = shadowReach(sigma);
+    const style = this._resolvedTextStyle();
+    // the same shaping memo fillText draws from, so a shadowed label shapes
+    // once per frame rather than twice
+    const shaped = app.fonts._shapeCachedWhole(text, style);
+    const ink = this._shapedInk(shaped);
+    // rounded outwards, with a pixel of antialiasing slack
+    const left = Math.ceil(-ink.minX) + 1;
+    const right = Math.ceil(ink.maxX) + 1;
+    const ascent = Math.ceil(-ink.minY) + 1;
+    const descent = Math.ceil(ink.maxY) + 1;
+    const width = left + right + reach * 2;
+    const height = ascent + descent + reach * 2;
+    if (width <= 0 || height <= 0) return;
+    // the run's origin inside the surface — whole pixels, so the coverage
+    // is the same wherever on the target the text is drawn
+    const originX = reach + left;
+    const originY = reach + ascent;
+
+    // where the run's origin lands on the target, exactly as fillText puts it
+    const [tx, ty] = matApply(this._m, x, y);
+    const runX = tx + this._alignOffset(shaped);
+    const runY = ty + this._baselineOffset(style.font.metrics(style.size));
+
+    // A run whose padded ink is larger than a shadow surface may be does not
+    // get one: fall back to the clipped, uncached path, which sizes itself
+    // to the part of the shadow that can actually be seen.
+    if (width * height > policy.maxPixels) {
+      this._shadowOfDrawing(
+        {
+          minX: runX + ink.minX,
+          maxX: runX + ink.maxX,
+          minY: runY + ink.minY,
+          maxY: runY + ink.maxY,
+        },
+        (sctx) => sctx.fillText(text, x, y),
+      );
+      return;
+    }
+
+    const key = [
+      text,
+      this._lastFontString,
+      style.font.key,
+      variationsKey(this._fontVariations),
+      this._textRendering ?? "",
+      sigma,
+    ].join("\u0000");
+    const surface = cachedShadow(app, key, () => {
+      let coverage = new Surface(app, { width, height, format: "a8" });
+      coverage.render((sctx) => {
+        this._loadShadowState(sctx, 0, 0);
+        // the origin is placed by hand, so neither alignment nor the
+        // baseline may move it again
+        sctx._m = [1, 0, 0, 1, 0, 0];
+        sctx.textAlign = "left";
+        sctx.textBaseline = "alphabetic";
+        sctx.fillText(text, originX, originY);
+      });
+      if (sigma > 0) coverage = blurCoverage(coverage, sigma);
+      return coverage;
+    });
+    if (!surface) return;
+    this._paintShadow(
+      surface,
+      Math.round(runX + this._shadowOffsetX) - originX,
+      Math.round(runY + this._shadowOffsetY) - originY,
+    );
+  }
+
+  /** the shadow of a `fill()`/`stroke()`-shaped call, from its arguments */
+  _shadowOfPath(args, stroke) {
+    if (stroke) {
+      const polys =
+        args[0] instanceof Path2D
+          ? flattenPath(args[0]._cmds, this._m)
+          : flattenPath(this._path._cmds, null);
+      this._shadowOfPolys(polys, { stroke: true });
+      return;
+    }
+    const { polys, rule } = this._polysFor(args);
+    this._shadowOfPolys(polys, { rule });
+  }
+
+  /**
+   * The shadow of a `drawImage`, from the destination rectangle its
+   * arguments describe.
+   *
+   * The image is drawn again into the coverage surface rather than its alpha
+   * being read out: an `a8` destination *is* the alpha channel, so an
+   * ordinary composite of the image onto one leaves exactly the coverage the
+   * shadow needs — including a translucent image's soft edges, and whatever
+   * scaling or transform the call asked for.
+   */
+  _shadowOfImage(image, args) {
+    const iw = image?.width;
+    const ih = image?.height;
+    if (!Number.isFinite(iw) || !Number.isFinite(ih)) return;
+    let rect;
+    if (args.length >= 8) rect = args.slice(4, 8);
+    else if (args.length >= 4) rect = args.slice(0, 4);
+    else rect = [args[0] ?? 0, args[1] ?? 0, iw, ih];
+    const [dx, dy, dw, dh] = rect;
+    if (!(dw > 0) || !(dh > 0)) return;
+    const corners = [
+      matApply(this._m, dx, dy),
+      matApply(this._m, dx + dw, dy),
+      matApply(this._m, dx, dy + dh),
+      matApply(this._m, dx + dw, dy + dh),
+    ];
+    const xs = corners.map((c) => c[0]);
+    const ys = corners.map((c) => c[1]);
+    this._shadowOfDrawing(
+      {
+        minX: Math.min(...xs),
+        maxX: Math.max(...xs),
+        minY: Math.min(...ys),
+        maxY: Math.max(...ys),
+      },
+      (sctx) => sctx.drawImage(image, ...args),
+    );
+  }
+
+  /** the shadow of an axis-aligned rectangle in user space */
+  _shadowOfRect(x, y, w, h, stroke) {
+    const tmp = new Path2D();
+    tmp.rect(x, y, w, h);
+    this._shadowOfPolys(flattenPath(tmp._cmds, this._m), { stroke });
+  }
+
   // ------------------------------------------------------------------
   // transform
 
@@ -1135,7 +1603,7 @@ class RenderingContext2d {
     op = op ?? this._op();
     alpha = alpha ?? this.globalAlpha;
     if (alpha <= 0) return;
-    if (!preparePattern(src, this._m)) return;
+    if (!prepareStyle(src, this._m)) return;
 
     // one box per subpath, so a path holding disjoint ones can be masked as
     // the pieces it is rather than as the box around all of them
@@ -1178,6 +1646,7 @@ class RenderingContext2d {
   _strokePolys(polys, { src = null } = {}) {
     src = src ?? this._strokePicture;
     if (this.globalAlpha <= 0) return;
+    if (!prepareStyle(src, this._m)) return;
     // approximate transform-aware line width by the average scale factor
     const det = this._m[0] * this._m[3] - this._m[1] * this._m[2];
     const scale = Math.sqrt(Math.abs(det)) || 1;
@@ -1662,7 +2131,9 @@ class RenderingContext2d {
    * @param {Picture} src source picture the glyphs paint with — a solid
    *   (`ctx.createSolidPicture(r, g, b, a)`, premultiplied 0..1) or a gradient
    * @param {Array<{run, x, y, textRendering?}>} positioned runs in visual
-   *   order; `x`/`y` is the run's baseline origin in device space. `run` is
+   *   order; `x`/`y` is the run's baseline origin in **user space** — the
+   *   current transform applies to it, as it does to every other drawing
+   *   call. `run` is
    *   `{ font, size, glyphs }` — a `Font`, a pixel size, and glyphs
    *   `{ id, ax, dx, dy }` in drawing order: `id` a font glyph id
    *   (`Font.shape()`'s `glyphs[].id`, or `Font.glyphIdFor(cp)`), `ax` the
@@ -1673,6 +2144,32 @@ class RenderingContext2d {
    *   (`codePoints`, `width`, …) are ignored. `textRendering` optionally
    *   overrides the bitmap/vector routing per run (docs/text.md).
    *
+   * The transform moves each run's origin, exactly as `fillText` moves its
+   * anchor; the glyphs themselves are not rotated or scaled by it (size the
+   * font via `ctx.font`, or `run.size`, instead). Advances and `dx`/`dy` are
+   * therefore device pixels on both calls. Without this, a `TextLayout`
+   * drawn into a translated context — which is every react-x11 canvas that
+   * is not at the window's origin — landed at the untransformed coordinates
+   * and was then cut by the clip, while the neighbouring `fillRect` and
+   * `drawImage` moved (issue #280).
+   */
+  drawGlyphs(op, src, positioned) {
+    const m = this._m;
+    if (!matIsIdentity(m)) {
+      positioned = positioned.map((p) => {
+        const [x, y] = matApply(m, p.x, p.y);
+        return { ...p, x, y };
+      });
+    }
+    this._drawGlyphsDevice(op, src, positioned);
+  }
+
+  /**
+   * `drawGlyphs` with the origins already in device space — the primitive
+   * under it, for callers that place glyphs themselves (`fillText`, which
+   * has to add the alignment and baseline offsets *after* the transform,
+   * because glyph advances are device pixels).
+   *
    * CompositeGlyphs writes straight to the destination picture, so it has
    * no way to consult our clip mask — text drawn through it used to spill
    * out of clipped boxes while every fill and stroke stayed inside. With a
@@ -1681,10 +2178,10 @@ class RenderingContext2d {
    * through the result — the same shape as _fillPolys. A rectangular clip
    * takes the server-side fast path below instead of the mask.
    */
-  drawGlyphs(op, src, positioned) {
+  _drawGlyphsDevice(op, src, positioned) {
     const app = this.window.app;
     const R = this.Render;
-    if (!preparePattern(src, this._m)) return;
+    if (!prepareStyle(src, this._m)) return;
     if (!this._clips.length) {
       drawGlyphRuns(app, op, src.id, this.picture.id, positioned);
       this._markDirty();
@@ -1905,8 +2402,15 @@ class RenderingContext2d {
   }
 
   fillRect(x, y, w, h) {
+    if (this._shadowed()) this._shadowOfRect(x, y, w, h, false);
+    this._fillRect(x, y, w, h);
+  }
+
+  /** fillRect minus the shadow — the batch in `fillRects` paints one shadow
+   * for the whole list and then draws the rectangles through here */
+  _fillRect(x, y, w, h) {
     if (matIsIdentity(this._m)) {
-      if (!preparePattern(this._backgroundPicture, this._m)) return;
+      if (!prepareStyle(this._backgroundPicture, this._m)) return;
       const mask = this._compositeMask();
       this.Render.Composite(
         this._op(),
@@ -1965,6 +2469,17 @@ class RenderingContext2d {
     }
     if (!flat.length) return;
 
+    // one shadow for the batch, not one per rectangle: the shadow of a
+    // group of rectangles is their combined coverage blurred once, and N
+    // separate shadows would darken every overlap
+    if (this._shadowed()) {
+      const rectPath = new Path2D();
+      for (let i = 0; i < flat.length; i += 4) {
+        rectPath.rect(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]);
+      }
+      this._shadowOfPolys(flattenPath(rectPath._cmds, this._m), {});
+    }
+
     const clip = this._clips.length ? this._clipRect() : null;
     if (
       !matIsIdentity(this._m) ||
@@ -1972,7 +2487,7 @@ class RenderingContext2d {
       (this._clips.length && !clip)
     ) {
       for (let i = 0; i < flat.length; i += 4)
-        this.fillRect(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]);
+        this._fillRect(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]);
       return;
     }
     if (clip && (clip.w === 0 || clip.h === 0)) return; // clipped away
@@ -2005,6 +2520,7 @@ class RenderingContext2d {
   }
 
   strokeRect(x, y, w, h) {
+    if (this._shadowed()) this._shadowOfRect(x, y, w, h, true);
     const m = this._m;
     if (m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1) {
       const zero = { x: 0, y: 0 };
@@ -2025,12 +2541,14 @@ class RenderingContext2d {
   }
 
   fill(...args) {
+    if (this._shadowed()) this._shadowOfPath(args, false);
     if (this._tryRoundRectFill(args)) return;
     const { polys, rule } = this._polysFor(args);
     this._fillPolys(polys, rule);
   }
 
   stroke(...args) {
+    if (this._shadowed()) this._shadowOfPath(args, true);
     const box = this._shapeBoxFor(args);
     if (box && this._tryStrokeBox(box)) return;
     const polys =
@@ -2803,6 +3321,7 @@ class RenderingContext2d {
   fillText(text, x, y) {
     text = String(text ?? "");
     if (!text) return;
+    if (this._shadowed()) this._shadowOfText(text, x, y);
     const style = this._resolvedTextStyle();
     const app = this.window.app;
     // through the shaping memo TextLayout uses: a label repainted every
@@ -2823,7 +3342,9 @@ class RenderingContext2d {
       });
       cursor += run.width;
     }
-    this.drawGlyphs(
+    // already device space: the anchor went through the matrix above, and
+    // the offsets and advances added to it are device pixels
+    this._drawGlyphsDevice(
       this.Render.PictOp.Over,
       this._backgroundPicture,
       positioned,
@@ -2835,9 +3356,13 @@ class RenderingContext2d {
    * `width` (advance), actual bounding box (ink extents relative to the
    * origin), and font bounding box (from font metrics).
    */
-  measureText(text) {
-    const style = this._resolvedTextStyle();
-    const shaped = this.window.app.fonts.shape(String(text ?? ""), style);
+  /**
+   * Ink extents of a shaped run, relative to its origin: the loop behind
+   * `measureText`'s actual bounding box, shared with the shadow path so a
+   * shadowed `fillText` does not shape its text a second time to find out
+   * how big its coverage surface has to be.
+   */
+  _shapedInk(shaped) {
     let minX = 0;
     let maxX = 0;
     let minY = 0;
@@ -2855,6 +3380,13 @@ class RenderingContext2d {
         cursor += g.ax;
       }
     }
+    return { minX, maxX, minY, maxY };
+  }
+
+  measureText(text) {
+    const style = this._resolvedTextStyle();
+    const shaped = this.window.app.fonts.shape(String(text ?? ""), style);
+    const { minX, maxX, minY, maxY } = this._shapedInk(shaped);
     const m = style.font.metrics(style.size);
     return {
       width: shaped.width,
@@ -3239,11 +3771,7 @@ class RenderingContext2d {
   _coverageSource() {
     const style = this._fillStyle;
     if (this.globalAlpha >= 1 || !isPlainColor(style)) {
-      // a pattern whose transform collapsed paints nothing, and "nothing" as
-      // a source is transparent black — no call site here has to know
-      return preparePattern(this._backgroundPicture, this._m)
-        ? this._backgroundPicture
-        : this.createSolidPicture(0, 0, 0, 0);
+      return this._backgroundPicture;
     }
     const c = parseColor(style);
     return this.createSolidPicture(c[0], c[1], c[2], c[3] * this.globalAlpha);
@@ -3260,6 +3788,9 @@ class RenderingContext2d {
    */
   _drawCoverage(picture, sx, sy, sw, sh, dx, dy, dw, dh, op) {
     const R = this.Render;
+    // the coverage is painted in the current fillStyle, on both branches
+    // below — a gradient/pattern whose transform collapsed paints nothing
+    if (!prepareStyle(this._backgroundPicture, this._m)) return;
     const scaled = dw !== sw || dh !== sh;
     if (scaled) {
       R.SetPictureTransform(picture.id, [
@@ -3419,6 +3950,7 @@ class RenderingContext2d {
   }
 
   drawImage(image, ...args) {
+    if (this._shadowed()) this._shadowOfImage(image, args);
     if (isPictureSource(image)) {
       let sx = 0;
       let sy = 0;
@@ -3665,6 +4197,21 @@ class RenderingContext2d {
   }
 }
 
+/**
+ * The fill/stroke style the `create*Gradient` methods return: colour stops
+ * along a line, between two circles, or around a point, backed by one
+ * XRender gradient picture.
+ *
+ * Its coordinates are **user space**, like every other coordinate a caller
+ * gives the context, and are resolved against the transform in force when
+ * the gradient is *painted* — the picture transform is that CTM's inverse,
+ * installed by `_sync` before each use, exactly as a pattern's is. A
+ * gradient made for a node's own coordinates therefore keeps painting in
+ * them after the context is translated to that node's origin (issue #271).
+ *
+ * The picture is created on first use and freed by the GC, through
+ * `Picture`'s finalizer.
+ */
 class CanvasGradient {
   constructor(type, ctx, p0, p1, p2, p3, p4, p5) {
     this.type = type;
@@ -3672,6 +4219,9 @@ class CanvasGradient {
     this.ctx = ctx;
     this._id = null;
     this._picture = null;
+    // what the server currently holds: a fresh gradient picture is
+    // untransformed, so an untransformed fill costs no extra request
+    this._applied = [1, 0, 0, 1, 0, 0];
 
     this.x0 = p0;
     this.y0 = p1;
@@ -3683,7 +4233,6 @@ class CanvasGradient {
     } else {
       this.angle = p2;
     }
-    // TODO: check if ChangePictureAttribute works on gradients ( set repeat edge pixels flag )
   }
 
   addColorStop(offset, color) {
@@ -3729,10 +4278,55 @@ class CanvasGradient {
       default:
         throw new Error("unknown gradient type");
     }
+    // Past the outermost stop a gradient clamps to that stop's colour, as
+    // the canvas and CSS specs say — which is XRender's RepeatPad, not the
+    // RepeatNone (transparent) a gradient picture is born with. Without it
+    // an app has to place its gradient exactly on the fill or lose the
+    // corners. The in-process JS server pads unconditionally, so only a real
+    // server can tell the difference.
+    Render.ChangePicture(this._id, { repeat: 2 }); // Repeat.Pad
     // wrap with picture so FreePicture is invoked on gc via FinalizationRegistry
     this._picture = new Picture(this.ctx.window.app, { id: this._id });
     return this._id;
   }
+
+  /**
+   * Make the server-side mapping match the CTM this paint runs under. The
+   * gradient's own coordinates are user space and every fill samples the
+   * source at device coordinates, so the picture transform — which takes a
+   * source coordinate to a gradient one — is the CTM's inverse.
+   *
+   * Returns false when the CTM collapses (a zero scale), which paints
+   * nothing, exactly as the canvas spec says.
+   */
+  _sync(ctm) {
+    const inv = matInvert(ctm);
+    if (!inv) return false;
+    const id = this.id; // lazily creates the picture
+    const a = this._applied;
+    if (
+      inv[0] !== a[0] ||
+      inv[1] !== a[1] ||
+      inv[2] !== a[2] ||
+      inv[3] !== a[3] ||
+      inv[4] !== a[4] ||
+      inv[5] !== a[5]
+    ) {
+      this.ctx.Render.SetPictureTransform(id, [
+        inv[0],
+        inv[2],
+        inv[4],
+        inv[1],
+        inv[3],
+        inv[5],
+        0,
+        0,
+        1,
+      ]);
+      this._applied = inv;
+    }
+    return true;
+  }
 }
 
 /**