ntk 8.1.1 → 8.3.0

package/lib/renderingcontext_2d.js

@@ -25,7 +25,9 @@ import {
   matMultiply,
 } from "./path.js";
 import Picture from "./picture.js";
+import { formatForDepth } from "./pictformat.js";
 import Pixmap from "./pixmap.js";
+import { REGION_DOCS, regionId } from "./region.js";
 import { routeRaster } from "./rasterize.js";
 import {
   blurCoverage,
@@ -52,6 +54,8 @@ import {
   compositeTraps,
   drawGlyphRuns,
   encodeGlyphItems,
+  positionedRunsInk,
+  runId,
 } from "./text/glyphs.js";
 import { TextLayout } from "./text/layout.js";
 import { reorderRuns } from "./text/shape.js";
@@ -73,6 +77,11 @@ function fillableShapes(polys) {
   return { shapes, edges };
 }
 
+/** Whether `v` is a whole number, give or take the slack a transform adds. */
+function isIntegral(v) {
+  return Math.abs(v - Math.round(v)) < 1e-6;
+}
+
 /** The overlap of two {x, y, w, h} boxes, or null when they have none. */
 function intersectBox(a, b) {
   const x = Math.max(a.x, b.x);
@@ -150,13 +159,17 @@ function variationsKey(variations) {
  * context owns is a Pixmap or a Picture, which carry their own finalizers,
  * and reaching into them from this one would race those.
  */
-const gcRegistry = new FinalizationRegistry(({ X, gcs }) => {
+const gcRegistry = new FinalizationRegistry(({ X, gcs, regions }) => {
   safeRelease(X, () => {
     for (const gc of gcs) {
       if (!gc) continue;
       X.FreeGC(gc);
       X.ReleaseID(gc);
     }
+    for (const { fixes, id } of regions) {
+      fixes.DestroyRegion(id);
+      X.ReleaseID(id);
+    }
   });
 });
 
@@ -189,6 +202,63 @@ const REPEAT_MODES = {
 const PATTERN_DOCS =
   "https://github.com/sidorares/ntk/blob/master/docs/context-2d.md#patterns";
 
+/**
+ * `clipRegion()` before anything loaded XFIXES.
+ *
+ * Not the same failure as a server that *has* no XFIXES (`app.fixes()` throws
+ * that one, with a code): here the extension is simply not on the connection
+ * yet, and it cannot be fetched from under a synchronous call that has to land
+ * in request order with the drawing around it. One await fixes it, and the
+ * call that hands back a region is already that await.
+ */
+function needXFixesError() {
+  return new Error(
+    "ntk: ctx.clipRegion() needs XFIXES loaded on this connection first.\n" +
+      "\n" +
+      "Making the region through ntk is that step:\n" +
+      "\n" +
+      "    const region = await app.createRegion([{ x: 0, y: 0, width: 100, height: 100 }]);\n" +
+      "    ctx.clipRegion(region);\n" +
+      "\n" +
+      "For a region you built through node-x11 yourself, one `await app.fixes()`\n" +
+      "anywhere before the first clipRegion() call is enough.\n" +
+      "\n" +
+      REGION_DOCS,
+  );
+}
+
+/**
+ * A drawable whose depth nothing has established yet, handed to
+ * createPattern.
+ *
+ * Three drawables are like this, and they want different answers. A window
+ * or a pixmap adopted by id knows nothing until the request ntk sent for it
+ * replies, and `ready` is the wait for exactly that — the visual a window
+ * tile's format really comes from among them. A window ntk created with the
+ * default `depth: 0` — CopyFromParent — has no reply pending at all, because
+ * only the server ever resolved that 0, so its depth has to be asked for.
+ * `getGeometry()` covers all of them, which is why it leads.
+ */
+function unknownDepthError() {
+  return new Error(
+    "createPattern: the tile's depth is not known yet, so there is no " +
+      "picture\nformat to read it through.\n" +
+      "\n" +
+      "Ask the server for it — the answer is written back to the tile:\n" +
+      "\n" +
+      "    await tile.getGeometry();\n" +
+      "    const pattern = ctx.createPattern(tile, 'repeat');\n" +
+      "\n" +
+      "For a window or a pixmap adopted by id — `new Window(app, { id })`,\n" +
+      "`new Pixmap(app, { id })`, or `ev.window` in a window manager — ntk\n" +
+      "has already sent that request: `await tile.ready` waits for the reply\n" +
+      "it is expecting rather than asking again, and resolves immediately on\n" +
+      "one ntk created. `Pixmap.adopt(app, id)` hands the pixmap over with\n" +
+      "this already done. A Surface carries its own depth and needs no wait.\n" +
+      `\n${PATTERN_DOCS}`,
+  );
+}
+
 /**
  * What a pattern tiles: a drawable holding the tile plus the picture format
  * to read it through. A repeating source Picture is created over it rather
@@ -197,13 +267,12 @@ const PATTERN_DOCS =
  */
 function patternSourceOf(app, source) {
   const Render = app.display.Render;
-  const formatFor = (depth) =>
-    depth === 32 ? Render.rgba32 : depth === 8 ? "a8" : Render.rgb24;
 
   let drawable = null;
   let width;
   let height;
   let format;
+  let coverage = false; // an a8 tile: no colour to paint with (see below)
   if (source instanceof Surface) {
     if (source.app !== app) {
       throw new Error(
@@ -211,7 +280,8 @@ function patternSourceOf(app, source) {
       );
     }
     drawable = source.pixmap;
-    format = source.format === "a8" ? "a8" : Render.rgba32;
+    coverage = source.format === "a8";
+    format = coverage ? Render.a8 : Render.rgba32;
     ({ width, height } = source);
   } else if (source instanceof Image) {
     drawable = source.pixmap(app);
@@ -222,12 +292,12 @@ function patternSourceOf(app, source) {
     // is where a double-buffered window's current pixels actually are)
     drawable = source._backing || source;
     const depth = drawable.depth ?? source.depth;
-    if (!depth) {
-      throw new Error(
-        "createPattern: the drawable's depth is not known yet — await the window's geometry, or pass a Surface",
-      );
-    }
-    format = formatFor(depth);
+    if (!depth) throw unknownDepthError();
+    // the tile's visual is what names its format; the depth is the fallback
+    // for a drawable that has none (issue #295)
+    const visual = drawable.visualId || source.visualId;
+    coverage = depth === 8;
+    format = app._knownPictFormat?.(visual, depth) ?? formatForDepth(Render, depth);
     width = drawable.width ?? source.width;
     height = drawable.height ?? source.height;
   } else {
@@ -236,7 +306,7 @@ function patternSourceOf(app, source) {
         (source === null ? "null" : typeof source),
     );
   }
-  if (format === "a8") {
+  if (coverage) {
     throw new Error(
       "createPattern: a coverage (a8) tile has no colour to paint with — XRender would " +
         "sample it as black. Draw the tile into an argb32 Surface and tile that, or keep " +
@@ -422,7 +492,10 @@ class RenderingContext2d {
     // ids land here as they are allocated; the finalizer holds this array
     // rather than the context, so registering cannot keep the context alive
     this._gcs = [];
-    gcRegistry.register(this, { X, gcs: this._gcs }, this);
+    // same for the scratch regions the region-clip path allocates: the
+    // finalizer holds the arrays, never the context
+    this._regions = [];
+    gcRegistry.register(this, { X, gcs: this._gcs, regions: this._regions }, this);
 
     this.window = window;
     this.display = window.app.display;
@@ -433,17 +506,40 @@ class RenderingContext2d {
     // buffering); re-bind when the backing pixmap is reallocated on resize
     this._target = null;
     this._gc = null;
-    this.picture = null;
+    this._picture = null;
     this._bindTarget();
+    // A window or pixmap adopted by id knows neither its depth nor its
+    // visual until the requests its constructor sent reply, and an unknown
+    // depth binds rgb24 — so a context taken on a depth-32 drawable before
+    // they land would silently drop the alpha channel, which is the ordinary
+    // case for a compositor taking the overlay window, its clients and their
+    // named pixmaps as bare ids (issues #293, #291). Awaiting `ready` first
+    // is the explicit fix; re-binding when the answer changes the format is
+    // the one that does not need to be known about.
+    if (!window.depth && typeof window.ready?.then === "function") {
+      window.ready.then(() => this._refreshFormat());
+    }
+    // The same, for the visual -> format table: it is one round trip on the
+    // connection (issue #295), taken while the connection is still being set
+    // up, so it is normally here already — this is the case where it is not,
+    // and the binding above took the depth's standard format. Where the
+    // visual names a different one — a 5:6:5 window, a 10-bit one, a BGR one
+    // — that binding is wrong and this is what puts it right.
+    if (window.app && !window.app._pictFormats) {
+      window.app.pictFormats?.().then(
+        () => this._refreshFormat(),
+        () => {},
+      );
+    }
     if (typeof window.on === "function") {
       window.on("_backing", () => this._bindTarget());
       // masks are sized to the drawable — recreate them after a resize
       window.on("resize", () => this._dropMasks());
       // window-backed pictures are freed server-side with the window
       window.on("_destroyed", () => {
-        if (this.picture && this._target === this.window) {
-          this.picture.forget();
-          this.picture = null;
+        if (this._picture && this._target === this.window) {
+          this._picture.forget();
+          this._picture = null;
         }
       });
     }
@@ -470,7 +566,26 @@ class RenderingContext2d {
     // drawings that took more than one.
     this.maskStats = { masks: 0, pixels: 0, split: 0 };
     this._stack = [];
-    this._clips = []; // [{ polys, rule }] in device space, already stacked
+    // [{ polys, rule, rect } | { region }] in device space, already stacked.
+    // Never mutated in place — save() shares the array with the snapshot and
+    // clip() concats a new one — so the two summary flags below only have to
+    // be recomputed where it is replaced (_setClips).
+    this._clips = [];
+    this._hasPolyClip = false; // any entry the a8 mask has to rasterize
+    this._hasRegionClip = false; // any XFIXES region entry
+    // XFIXES, once clipRegion() has been called on this context, and what
+    // the picture is currently clipped by. "No clip" is a state ntk tracks
+    // rather than a rectangle it stamps: a caller's region has to survive a
+    // drawing that only meant to narrow to a box (issue #292).
+    this._fixes = null;
+    this._pictureClipped = false;
+    // the rectangle the slot holds, when it is a plain one (no region in it),
+    // so a second drawing under the same clip can skip re-stamping it; and
+    // whether a reset is owed but not yet sent (issue #308)
+    this._pictureClipRect = null;
+    this._clipStale = false;
+    this._regionScratch = null; // region entries intersected, when >1
+    this._regionBox = null; // that ∩ the rectangular clip
     this._gco = "source-over";
     this.globalAlpha = 1;
     this.lineCap = "butt";
@@ -493,9 +608,46 @@ class RenderingContext2d {
     this.lineWidth = 1;
   }
 
-  _bindTarget() {
+  /**
+   * The picture format the target drawable is read and written through.
+   *
+   * The visual is what names it — depth alone does not (issue #295) — and
+   * the depth is the fallback for a drawable that has no visual to name
+   * (a pixmap, an `a8` coverage surface) or whose visual has not been
+   * answered for yet.
+   */
+  _formatFor(depth, visual) {
+    return (
+      this.window.app?._knownPictFormat?.(visual, depth) ?? formatForDepth(this.Render, depth)
+    );
+  }
+
+  /** The depth and visual of whatever the context is currently bound to. */
+  _targetPixels() {
+    const target = this._target;
+    return {
+      depth: target?.depth ?? this.window.depth,
+      // a backing pixmap carries the window's visual; nothing else about a
+      // pixmap says what its pixels mean
+      visual: target?.visualId || this.window.visualId,
+    };
+  }
+
+  /**
+   * Re-bind if what is now known about the target's pixels names a different
+   * format than the picture was built with. Both answers arrive late on an
+   * adopted window, and neither costs anything when it changes nothing.
+   */
+  _refreshFormat() {
+    const target = this.window._backing || this.window;
+    if (!this._picture || this._target !== target) return;
+    const { depth, visual } = this._targetPixels();
+    if (this._formatFor(depth, visual) !== this._picture.format) this._bindTarget(true);
+  }
+
+  _bindTarget(force = false) {
     const target = this.window._backing || this.window;
-    if (this._target === target) return;
+    if (this._target === target && !force) return;
     this._target = target;
     this._layoutCache = null; // the new target may be a different depth
 
@@ -506,36 +658,210 @@ class RenderingContext2d {
       this._gcs.push(this._gc);
       this.X.CreateGC(this._gc, target.id);
     }
-    if (this.picture) this.picture.destroy();
+    if (this._picture) this._picture.destroy();
     // a8 targets are coverage, not colour: drawing into one and using the
     // result as a mask is how a monochrome drawing gets rendered once and
     // recoloured on every use (see Surface).
-    const depth = target.depth ?? this.window.depth;
-    const format =
-      depth === 32
-        ? this.Render.rgba32
-        : depth === 8
-          ? this.Render.a8
-          : this.Render.rgb24;
+    const { depth, visual } = this._targetPixels();
+    const format = this._formatFor(depth, visual);
     // Does the target have a real alpha channel? Only then is "transparent"
     // a colour it can hold, which is what clearRect turns on.
     this._hasAlpha = depth === 32;
-    this.picture = new Picture(this.window.app, {
+    this._picture = new Picture(this.window.app, {
       drawable: target,
       format,
       polyEdge: 1,
       polyMode: 1,
     });
+    // a new picture carries no clip; a region one is context state and has to
+    // be re-installed on it (this runs on every backing-pixmap reallocation)
+    this._pictureClipped = false;
+    this._pictureClipRect = null;
+    this._invalidatePictureClip();
     this._dropMasks();
   }
 
-  // Undo a rectangular server-side clip. "No clip" has to be stamped as a
-  // rectangle that outlives window growth: the backing pixmap has headroom
-  // past the window and growing into it does not rebind the picture, so a
-  // restore at today's window size would keep clipping tomorrow's pixels.
-  // Coordinates are INT16 — one rect at their maximum covers any drawable.
-  _resetPictureClip() {
-    this.Render.SetPictureClipRectangles(this.picture.id, 0, 0, [0, 0, 0x7fff, 0x7fff]);
+  // ------------------------------------------------------------------
+  // the picture's clip
+  //
+  // Two things narrow a drawing server-side: a rectangle from the clip stack
+  // (SetPictureClipRectangles, the fast path text and rounded boxes take) and
+  // an XFIXES region from clipRegion(). Both land on the same one slot — a
+  // Picture holds exactly one client clip — so they go through here, and here
+  // is also what puts the slot back afterwards.
+  //
+  // "Back" is the load-bearing word (issue #292). Undoing a narrow used to
+  // mean stamping a full-plane rectangle, which is a clip, not the absence of
+  // one: it overwrote whatever else was in the slot. Now the slot's contents
+  // are state the context tracks, so a region clip survives a fill or a glyph
+  // run that only meant to narrow to a box.
+  //
+  // Tracking the contents also makes the stamping *lazy* (issue #308). Every
+  // rect-clipped fast path brackets its own drawing — set, draw, reset — so
+  // two drawings under one clip used to emit a reset immediately followed by
+  // an identical set, with nothing in between that reads the slot. Instead
+  // the reset is only recorded as owed, `_dst()` flushes it before any
+  // drawing that does *not* set its own clip, and a set whose rectangle is
+  // already in the slot supersedes it and sends nothing. A rounded box under
+  // a damage clip goes from four stamps to one, and a repaint of the same
+  // rectangle next frame to none.
+
+  /** Narrow the picture to `rect`, intersected with any region clip. */
+  _setPictureClip(rect) {
+    const region = this._effectiveRegion();
+    if (region === null) {
+      const held = this._pictureClipRect;
+      // The owed reset (if any) is superseded either way: what follows draws
+      // under exactly this rectangle, which is what the slot is about to hold.
+      this._clipStale = false;
+      if (
+        held &&
+        held.x === rect.x &&
+        held.y === rect.y &&
+        held.w === rect.w &&
+        held.h === rect.h
+      ) {
+        return; // already stamped, and nothing since has read the slot
+      }
+      this.Render.SetPictureClipRectangles(this._picture.id, 0, 0, [
+        rect.x,
+        rect.y,
+        rect.w,
+        rect.h,
+      ]);
+      this._pictureClipped = true;
+      // a copy: the caller owns `rect` and _clipRect() hands out fresh ones,
+      // but nothing here should depend on that
+      this._pictureClipRect = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
+      return;
+    }
+    // region ∩ rectangle, computed by the server: three requests and no round
+    // trip, against a full-surface a8 mask for the same answer.
+    //
+    // Always re-emitted, never skipped: the region is the caller's and they
+    // may have edited it — server-side, invisibly to us — since the last
+    // drawing, for the same reason _effectiveRegion() is recomputed.
+    const box = this._scratchRegion("_regionBox");
+    this._fixes.SetRegion(box, [
+      { x: rect.x, y: rect.y, width: rect.w, height: rect.h },
+    ]);
+    this._fixes.IntersectRegion(region, box, box);
+    this._fixes.SetPictureClipRegion(this._picture.id, box, 0, 0);
+    this._pictureClipped = true;
+    this._pictureClipRect = null; // a region is in there, not a plain rect
+    this._clipStale = false;
+  }
+
+  /**
+   * Note that the picture's clip no longer matches what the clip stack says,
+   * without sending anything: the next drawing either sets its own clip
+   * (which supersedes this) or goes through `_dst()`, which flushes it first.
+   *
+   * This is what every rect-clipped fast path calls after its drawing, and
+   * also what installs a region in the first place — `clipRegion()` and a
+   * `restore()` that changes the stack both come through here, so the region
+   * is on the picture for every route, including the ones that composite an
+   * a8 mask and never touch a clip rectangle.
+   */
+  _invalidatePictureClip() {
+    this._clipStale = true;
+  }
+
+  /**
+   * Put the picture's clip back to what the clip stack says it is between
+   * drawings: the region clip if there is one, nothing otherwise. Sends
+   * nothing when the slot already says that.
+   */
+  _flushPictureClip() {
+    if (!this._clipStale) return;
+    this._clipStale = false;
+    if (!this._picture) return; // destroyed, or a window that went away
+    const region = this._effectiveRegion();
+    if (region !== null) {
+      this._fixes.SetPictureClipRegion(this._picture.id, region, 0, 0);
+      this._pictureClipped = true;
+      this._pictureClipRect = null;
+      return;
+    }
+    if (!this._pictureClipped) return; // nothing of ours is in the slot
+    if (this._fixes) {
+      // None is the real "no clip"; a rectangle would only be a wider one
+      this._fixes.SetPictureClipRegion(this._picture.id, 0, 0, 0);
+    } else {
+      // Without XFIXES the widest rectangle is all there is, and it has to
+      // outlive window growth: the backing pixmap has headroom past the
+      // window and growing into it does not rebind the picture, so a reset at
+      // today's window size would keep clipping tomorrow's pixels.
+      // Coordinates are INT16 — one rect at their maximum covers any drawable.
+      this.Render.SetPictureClipRectangles(this._picture.id, 0, 0, [0, 0, 0x7fff, 0x7fff]);
+    }
+    this._pictureClipped = false;
+    this._pictureClipRect = null;
+  }
+
+  /**
+   * The destination picture id for a drawing request, with any owed clip
+   * reset flushed first.
+   *
+   * Everything that draws into this context's own picture goes through here
+   * — including the composites that bypass the set/reset bracket entirely
+   * (`_fillRect`, the `clearRect` fast path, the a8-mask routes) — because
+   * that is what keeps a lazily-owed reset from leaking a narrower clip into
+   * a drawing that never asked for one.
+   */
+  _dst() {
+    this._flushPictureClip();
+    return this._picture.id;
+  }
+
+  /**
+   * The RENDER Picture this context draws through — a real server-side
+   * picture a caller can composite from, or hang a clip region on
+   * (docs/context-2d.md). Reading it settles the clip slot first, so what an
+   * outside request sees is what the clip stack says, not whatever the last
+   * fast path left behind.
+   */
+  get picture() {
+    this._flushPictureClip();
+    return this._picture;
+  }
+
+  /**
+   * The region the clip stack currently means, or null when it holds no
+   * region entry. One entry is used as it is; several are intersected into a
+   * scratch region owned by this context.
+   *
+   * Recomputed rather than cached: the intersection is of regions the caller
+   * owns and may edit under us, and nesting region clips is rare enough that
+   * a few requests are the cheaper mistake to make.
+   */
+  _effectiveRegion() {
+    if (!this._hasRegionClip) return null;
+    let first = null;
+    let dst = null;
+    for (const entry of this._clips) {
+      if (!entry.region) continue;
+      if (first === null) {
+        first = entry.region;
+        continue;
+      }
+      if (dst === null) {
+        dst = this._scratchRegion("_regionScratch");
+        this._fixes.CopyRegion(first, dst);
+      }
+      this._fixes.IntersectRegion(dst, entry.region, dst);
+    }
+    return dst === null ? first : dst;
+  }
+
+  /** One of this context's two scratch regions, allocated on first use. */
+  _scratchRegion(slot) {
+    if (this[slot] !== null) return this[slot];
+    const id = this.X.AllocID();
+    this._fixes.CreateRegion(id, []);
+    this[slot] = id;
+    this._regions.push({ fixes: this._fixes, id });
+    return id;
   }
 
   /**
@@ -559,8 +885,16 @@ class RenderingContext2d {
     this._destroyed = true;
     gcRegistry.unregister(this);
 
-    this._clips = [];
+    this._setClips([]);
     this._dropMasks();
+    for (const { fixes, id } of this._regions) {
+      safeRelease(this.X, () => {
+        fixes.DestroyRegion(id);
+        this.X.ReleaseID(id);
+      });
+    }
+    this._regions.length = 0;
+    this._regionScratch = this._regionBox = null;
     for (const gc of [this._gc, this._fillMaskGC, this._clipMaskGC]) {
       if (!gc) continue;
       safeRelease(this.X, () => {
@@ -573,15 +907,15 @@ class RenderingContext2d {
 
     this._backgroundPicture = this._glyphSource = null;
 
-    if (this.picture) {
+    if (this._picture) {
       // a picture on a *window* is freed by the server with the window;
       // asking again would raise BadPicture. Same rule as `_destroyed`.
       if (this._target === this.window && !(this.window instanceof Pixmap)) {
-        this.picture.forget();
+        this._picture.forget();
       } else {
-        this.picture.destroy();
+        this._picture.destroy();
       }
-      this.picture = null;
+      this._picture = null;
     }
   }
 
@@ -613,7 +947,7 @@ class RenderingContext2d {
     // a hover repaint of two tab headers used to blit the whole window. A
     // context with no rectangular clip reports nothing, and the window falls
     // back to a full blit, which is what any drawing outside a clip needs.
-    this.window._markDirty(this._clips.length ? this._clipRect() : null);
+    this.window._markDirty(this._clipRect());
   }
 
   // html context2d compatibility: canvas.getContext('2d').canvas == canvas
@@ -762,8 +1096,12 @@ class RenderingContext2d {
     this._shadowOffsetY = s.shadowOffsetY;
     this._m = s.m;
     if (s.clips !== this._clips) {
-      this._clips = s.clips;
+      const hadRegion = this._hasRegionClip;
+      this._setClips(s.clips);
       this._rebuildClipMask();
+      // a region clip going out of scope (or coming back into it) is a change
+      // to the picture's clip, and nothing else will notice it
+      if (hadRegion || this._hasRegionClip) this._invalidatePictureClip();
     }
   }
 
@@ -1099,6 +1437,110 @@ class RenderingContext2d {
     );
   }
 
+  /**
+   * The shadow of positioned glyph runs, cached — what `drawGlyphs`, and
+   * therefore every `TextLayout.draw`, casts (issue #283).
+   *
+   * A paragraph gets **one** coverage surface, not one per line: the runs
+   * already carry their own baselines, so they all go into the same surface
+   * exactly as they all go into the same glyph composite. Nothing is
+   * re-shaped — the caller handed us the runs, which is why this path is
+   * cheaper than `_shadowOfText`, not dearer.
+   *
+   * The cached copy is position-independent, as `fillText`'s is: geometry is
+   * stored relative to the first run's origin and the composite carries it
+   * to wherever the text is drawn. The key is that relative geometry plus
+   * the identity of each run, so the same string laid out to two widths —
+   * same runs, different line origins — is two shadows, and re-drawing one
+   * layout is one lookup no matter how many glyphs are in it.
+   *
+   * @param {Array<{run, x, y, textRendering?}>} positioned device-space runs
+   */
+  _shadowOfGlyphs(positioned) {
+    if (!positioned.length) return;
+    const app = this.window.app;
+    const policy = shadowPolicyOf(app);
+    const sigma = shadowSigma(this._shadowBlur, policy);
+    const reach = shadowReach(sigma);
+
+    // Run origins relative to the first, rounded: whole-pixel offsets are
+    // what the bitmap glyph path draws at anyway, and they keep the key
+    // stable as the paragraph moves — `(x + a) - (x + b)` is not exactly
+    // `a - b` in floating point, and an origin-dependent key would miss the
+    // cache on every scroll.
+    const ax = positioned[0].x;
+    const ay = positioned[0].y;
+    const local = positioned.map((p) => ({
+      run: p.run,
+      x: Math.round(p.x - ax),
+      y: Math.round(p.y - ay),
+      textRendering: p.textRendering,
+    }));
+    const key = `${local
+      .map((p) => `${runId(p.run)},${p.x},${p.y},${p.textRendering ?? ""}`)
+      .join("\u0000")}\u0000${sigma}`;
+
+    let ink = null;
+    const surface = cachedShadow(app, key, () => {
+      ink = positionedRunsInk(local);
+      if (!ink) return null; // a line of spaces inks nothing
+      const box = {
+        x: Math.floor(ink.minX) - 1 - reach,
+        y: Math.floor(ink.minY) - 1 - reach,
+      };
+      box.w = Math.ceil(ink.maxX) + 1 + reach - box.x;
+      box.h = Math.ceil(ink.maxY) + 1 + reach - box.y;
+      if (box.w * box.h > policy.maxPixels) return null;
+      let coverage = new Surface(app, {
+        width: box.w,
+        height: box.h,
+        format: "a8",
+      });
+      coverage.render((sctx) => {
+        this._loadShadowState(sctx, 0, 0);
+        // the origins are already device-space and placed by hand
+        sctx._m = [1, 0, 0, 1, 0, 0];
+        sctx._drawGlyphsDevice(
+          this.Render.PictOp.Over,
+          sctx._backgroundPicture,
+          local.map((p) => ({ ...p, x: p.x - box.x, y: p.y - box.y })),
+        );
+      });
+      if (sigma > 0) coverage = blurCoverage(coverage, sigma);
+      // where the anchor sits inside the surface — whole pixels, so the
+      // composite below can carry it anywhere
+      coverage._shadowOrigin = { x: -box.x, y: -box.y };
+      return coverage;
+    });
+    if (surface) {
+      const origin = surface._shadowOrigin;
+      this._paintShadow(
+        surface,
+        Math.round(ax + this._shadowOffsetX) - origin.x,
+        Math.round(ay + this._shadowOffsetY) - origin.y,
+      );
+      return;
+    }
+    if (!ink) return;
+    // Padded ink larger than a shadow surface may be: fall back to the
+    // clipped, uncached path, which sizes itself to the part of the shadow
+    // that can actually be seen — the same escape `_shadowOfText` takes.
+    this._shadowOfDrawing(
+      {
+        minX: ax + ink.minX,
+        maxX: ax + ink.maxX,
+        minY: ay + ink.minY,
+        maxY: ay + ink.maxY,
+      },
+      (sctx, dx, dy) =>
+        sctx._drawGlyphsDevice(
+          this.Render.PictOp.Over,
+          sctx._backgroundPicture,
+          positioned.map((p) => ({ ...p, x: p.x + dx, y: p.y + dy })),
+        ),
+    );
+  }
+
   /** the shadow of a `fill()`/`stroke()`-shaped call, from its arguments */
   _shadowOfPath(args, stroke) {
     if (stroke) {
@@ -1525,16 +1967,19 @@ class RenderingContext2d {
     // A rectangular clip narrows where the coverage is *composited*; the
     // mask content outside it is stale by the same argument as outside `b`,
     // and a box the clip rejects outright needs no coverage at all. A stack
-    // whose mask was dropped by restore() may still hold a poly — _clipRect
-    // says null then, and the mask comes back on demand.
+    // whose mask was dropped by restore() may still hold a poly, and the mask
+    // comes back on demand. A region clip needs nothing here: the picture
+    // carries it, and it applies to the composite below like any other.
     let out = b;
-    if (this._clips.length && !this.clipMask) {
-      const cr = this._clipRect();
-      if (cr) {
-        out = intersectBox(b, cr);
-        if (!out) return false;
-      } else {
+    if (!this.clipMask) {
+      if (this._hasPolyClip) {
         this._requireClipMask();
+      } else {
+        const cr = this._clipRect();
+        if (cr) {
+          out = intersectBox(b, cr);
+          if (!out) return false;
+        }
       }
     }
     if (!this._uploadCoverage({ ...job, dx: -b.x, dy: -b.y }, b, edges)) {
@@ -1578,7 +2023,7 @@ class RenderingContext2d {
       op,
       src.id,
       this.fillMask.id,
-      this.picture.id,
+      this._dst(),
       out.x,
       out.y,
       out.x,
@@ -1976,7 +2421,10 @@ class RenderingContext2d {
     const direct =
       !hasRound &&
       this.globalAlpha >= 1 &&
-      !this._clips.length &&
+      // a region clip stays on the picture and needs nothing here; a
+      // rectangle or a mask does
+      !this._hasPolyClip &&
+      !this._clipRect() &&
       op === this.Render.PictOp.Over;
     const chunk = 4000 * 6;
     if (direct) {
@@ -1994,7 +2442,7 @@ class RenderingContext2d {
           src.id,
           Math.floor(batch[0]),
           Math.floor(batch[1]),
-          this.picture.id,
+          this._dst(),
           this.Render.a8,
           batch,
         );
@@ -2152,6 +2600,12 @@ class RenderingContext2d {
    * 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).
+   *
+   * The shadow state applies too, as it does to `fillText`: one blurred
+   * coverage surface for the whole call, cached on the runs' identity and
+   * relative positions, painted under the glyphs (issue #283). A paragraph
+   * whose spans change colour draws as several calls, and — as several
+   * `fillText`s would — casts a shadow per call.
    */
   drawGlyphs(op, src, positioned) {
     const m = this._m;
@@ -2161,6 +2615,7 @@ class RenderingContext2d {
         return { ...p, x, y };
       });
     }
+    if (this._shadowed()) this._shadowOfGlyphs(positioned);
     this._drawGlyphsDevice(op, src, positioned);
   }
 
@@ -2182,26 +2637,20 @@ class RenderingContext2d {
     const app = this.window.app;
     const R = this.Render;
     if (!prepareStyle(src, this._m)) return;
-    if (!this._clips.length) {
-      drawGlyphRuns(app, op, src.id, this.picture.id, positioned);
-      this._markDirty();
-      return;
-    }
-    // Fast path: a rectangular clip is something the server can do itself.
-    // Two small requests around the ordinary glyph composite, instead of
-    // clearing and compositing a full-surface a8 mask three times — which
-    // costs the same on the wire but many times the pixel work.
-    const rect = this._clipRect();
-    if (rect) {
-      if (rect.w === 0 || rect.h === 0) return;
-      R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-        rect.x,
-        rect.y,
-        rect.w,
-        rect.h,
-      ]);
-      drawGlyphRuns(app, op, src.id, this.picture.id, positioned);
-      this._resetPictureClip();
+    if (!this._hasPolyClip) {
+      // Fast path: a rectangular clip is something the server can do itself.
+      // Two small requests around the ordinary glyph composite, instead of
+      // clearing and compositing a full-surface a8 mask three times — which
+      // costs the same on the wire but many times the pixel work. No clip
+      // stack at all, or only a region one, needs neither: the picture is
+      // already carrying whatever applies.
+      const rect = this._clipRect();
+      if (rect) {
+        if (rect.w === 0 || rect.h === 0) return;
+        this._setPictureClip(rect);
+      }
+      drawGlyphRuns(app, op, src.id, this._dst(), positioned);
+      if (rect) this._invalidatePictureClip();
       this._markDirty();
       return;
     }
@@ -2240,7 +2689,7 @@ class RenderingContext2d {
       op,
       src.id,
       this.fillMask.id,
-      this.picture.id,
+      this._dst(),
       0,
       0,
       0,
@@ -2263,22 +2712,14 @@ class RenderingContext2d {
     if (!traps.length) return;
     const app = this.window.app;
     const R = this.Render;
-    if (!this._clips.length) {
-      compositeTraps(app, op, src.id, this.picture.id, traps);
-      this._markDirty();
-      return;
-    }
-    const rect = this._clipRect();
-    if (rect) {
-      if (rect.w === 0 || rect.h === 0) return;
-      R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-        rect.x,
-        rect.y,
-        rect.w,
-        rect.h,
-      ]);
-      compositeTraps(app, op, src.id, this.picture.id, traps);
-      this._resetPictureClip();
+    if (!this._hasPolyClip) {
+      const rect = this._clipRect();
+      if (rect) {
+        if (rect.w === 0 || rect.h === 0) return;
+        this._setPictureClip(rect);
+      }
+      compositeTraps(app, op, src.id, this._dst(), traps);
+      if (rect) this._invalidatePictureClip();
       this._markDirty();
       return;
     }
@@ -2316,7 +2757,7 @@ class RenderingContext2d {
       op,
       src.id,
       this.fillMask.id,
-      this.picture.id,
+      this._dst(),
       0,
       0,
       0,
@@ -2329,19 +2770,111 @@ class RenderingContext2d {
     this._markDirty();
   }
 
+  /**
+   * The cheap form of a direct composite, when there is one: the box to
+   * composite over and what belongs in its mask slot, with no surface-sized
+   * a8 mask anywhere (issue #307).
+   *
+   * Neither thing `_compositeMask()` puts in a mask is really mask work.
+   * A **rectangular clip** is a smaller composite box: for an op that leaves
+   * the destination alone where the mask is zero, zeroing the mask outside
+   * the rectangle and never compositing there are the same picture — and a
+   * rect clip is an integer rectangle stamped as binary coverage, so the two
+   * agree pixel for pixel rather than approximately. **`globalAlpha`** is a
+   * 1x1 solid, which is that alpha everywhere the server samples it, for the
+   * price of no pixels at all. A **region** clip needs neither: the picture
+   * carries it, and it applies to the composite like any other.
+   *
+   * What is left needing a mask is what genuinely needs one: a
+   * non-rectangular clip entry, or an op that writes where the mask is zero
+   * — `copy`, `source-in`, `destination-in`, `source-out` and
+   * `destination-atop` cover the whole composite box, so a shrunk box would
+   * leave behind the pixels the mask path clears.
+   *
+   * `box` is the composite's destination box in device coordinates. Callers
+   * pass their own arguments through, so it is only intersected when it is
+   * integral: clip rectangles are integers and caller coordinates are not
+   * necessarily, and rounding one here could land a pixel away from where
+   * the mask path draws.
+   *
+   * @returns {{box: ?object, mask: number}|null} the box to composite over —
+   * null when the clip rejects it whole and nothing should be drawn — and
+   * the mask slot for it; or null when this route does not apply and the
+   * caller has to fall back to `_compositeMask()`.
+   */
+  _boxedComposite(box, op) {
+    if (this._hasPolyClip) return null;
+    let out = box;
+    const clip = this._clipRect();
+    if (clip) {
+      if (!this._maskBounded(op)) return null;
+      if (![box.x, box.y, box.w, box.h].every(isIntegral)) return null;
+      out = intersectBox(box, clip);
+    }
+    return { box: out, mask: this._alphaMask() };
+  }
+
+  /**
+   * `globalAlpha` as something to put in a mask slot: a 1x1 solid, which is
+   * that alpha over any box the server samples it across, or 0 when there is
+   * no alpha to apply. The surface-sized a8 `_compositeMask()` fills for the
+   * same answer is pure pixel work.
+   */
+  _alphaMask() {
+    if (this.globalAlpha >= 1) return 0;
+    return this.createSolidPicture(0, 0, 0, this.globalAlpha).id;
+  }
+
+  /**
+   * The composite's own box, as somewhere to put pixels: `box` grown to
+   * whole pixels and clamped to the surface, or the whole surface when the
+   * caller has no box to give.
+   *
+   * Growing outward rather than rounding is the safe direction — the mask
+   * has to cover every pixel the composite samples, and a pixel of slack
+   * outside it is never read.
+   */
+  _maskBox(box) {
+    // no box, or one the caller never normalized: the whole surface, which
+    // is what this always used to be
+    if (!box || !(box.w > 0) || !(box.h > 0))
+      return { x: 0, y: 0, w: this.width, h: this.height };
+    const x = Math.max(0, Math.floor(box.x));
+    const y = Math.max(0, Math.floor(box.y));
+    const right = Math.min(this.width, Math.ceil(box.x + box.w));
+    const bottom = Math.min(this.height, Math.ceil(box.y + box.h));
+    if (right <= x || bottom <= y) return { x: 0, y: 0, w: 0, h: 0 };
+    return { x, y, w: right - x, h: bottom - y };
+  }
+
   // combined clip ∩ globalAlpha mask for direct composites (rect/image
   // fast paths); returns a picture id or 0. Reuses the fill scratch mask.
-  _compositeMask() {
-    // reached only when the clip is not a rectangle (those went through the
-    // SetPictureClipRectangles path), so a clip here always means the mask
-    const clipMask = this._clips.length ? this._requireClipMask() : null;
+  //
+  // The fallback, not the common case: `_boxedComposite` above answers for a
+  // rect-only clip stack without materializing anything, and every caller
+  // here asks it first. A **region** clip needs nothing either — the picture
+  // carries it, and the mask must not try to hold it.
+  //
+  // `box` is the destination box of the composite the mask is for, in device
+  // coordinates. The composite samples the mask over that box and nowhere
+  // else, so both writes here take it instead of the whole surface (issue
+  // #313): a translucent fill inside a rounded-corner clip used to stamp the
+  // alpha across the full surface and intersect the clip across it again,
+  // per fill, for pixels nothing reads. Stale content outside the box is
+  // fine — every caller re-stamps the scratch unconditionally, so there is
+  // no reuse to preserve.
+  _compositeMask(box) {
+    const clipMask =
+      this._hasPolyClip || this._clipRect() ? this._requireClipMask() : null;
     if (this.globalAlpha >= 1) return clipMask ? clipMask.id : 0;
     this._ensureFillMask();
+    const b = this._maskBox(box);
+    if (b.w === 0 || b.h === 0) return this.fillMask.id; // nothing is sampled
     this.Render.FillRectangles(
       this.Render.PictOp.Src,
       this.fillMask.id,
       [0, 0, 0, this.globalAlpha],
-      [0, 0, this.width, this.height],
+      [b.x, b.y, b.w, b.h],
     );
     if (clipMask) {
       this.Render.Composite(
@@ -2349,14 +2882,14 @@ class RenderingContext2d {
         clipMask.id,
         0,
         this.fillMask.id,
+        b.x,
+        b.y,
         0,
         0,
-        0,
-        0,
-        0,
-        0,
-        this.width,
-        this.height,
+        b.x,
+        b.y,
+        b.w,
+        b.h,
       );
     }
     return this.fillMask.id;
@@ -2373,10 +2906,10 @@ class RenderingContext2d {
   // and what every caller predating ARGB windows expects.
   clearRect(x, y, w, h) {
     const alpha = this._hasAlpha;
-    if (matIsIdentity(this._m) && !this._clips.length) {
+    if (matIsIdentity(this._m) && !this._hasPolyClip && !this._clipRect()) {
       this.Render.FillRectangles(
         this.Render.PictOp.Src,
-        this.picture.id,
+        this._dst(),
         alpha ? [0, 0, 0, 0] : [1, 1, 1, 1],
         [x, y, w, h],
       );
@@ -2411,20 +2944,30 @@ class RenderingContext2d {
   _fillRect(x, y, w, h) {
     if (matIsIdentity(this._m)) {
       if (!prepareStyle(this._backgroundPicture, this._m)) return;
-      const mask = this._compositeMask();
+      const op = this._op();
+      // A rectangular clip is a smaller rectangle to fill, not a mask — this
+      // was the one drawing path that still built a surface-sized a8 for one
+      // (issue #307), and a renderer filling a window background inside a
+      // damage clip pays it every frame. Source, mask and destination
+      // coordinates all shift with the box, so a gradient or a pattern stays
+      // where it was and only the ink outside the clip goes away.
+      const direct =
+        w > 0 && h > 0 ? this._boxedComposite({ x, y, w, h }, op) : null;
+      if (direct && !direct.box) return; // the clip rejects the fill whole
+      const box = direct ? direct.box : { x, y, w, h };
       this.Render.Composite(
-        this._op(),
+        op,
         this._backgroundPicture.id,
-        mask,
-        this.picture.id,
-        x,
-        y,
-        x,
-        y,
-        x,
-        y,
-        w,
-        h,
+        direct ? direct.mask : this._compositeMask(box),
+        this._dst(),
+        box.x,
+        box.y,
+        box.x,
+        box.y,
+        box.x,
+        box.y,
+        box.w,
+        box.h,
       );
       this._markDirty();
       return;
@@ -2480,11 +3023,11 @@ class RenderingContext2d {
       this._shadowOfPolys(flattenPath(rectPath._cmds, this._m), {});
     }
 
-    const clip = this._clips.length ? this._clipRect() : null;
+    const clip = this._clipRect();
     if (
       !matIsIdentity(this._m) ||
       !isPlainColor(this._fillStyle) ||
-      (this._clips.length && !clip)
+      this._hasPolyClip
     ) {
       for (let i = 0; i < flat.length; i += 4)
         this._fillRect(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]);
@@ -2492,14 +3035,7 @@ class RenderingContext2d {
     }
     if (clip && (clip.w === 0 || clip.h === 0)) return; // clipped away
     const R = this.Render;
-    if (clip) {
-      R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-        clip.x,
-        clip.y,
-        clip.w,
-        clip.h,
-      ]);
-    }
+    if (clip) this._setPictureClip(clip);
     // globalAlpha folds into the premultiplied colour — scaling all four
     // components is exactly what compositing at that opacity means, for
     // any composite op (the mask slot would only scale the source the same
@@ -2510,12 +3046,12 @@ class RenderingContext2d {
     for (let i = 0; i < flat.length; i += chunk) {
       R.FillRectangles(
         this._op(),
-        this.picture.id,
+        this._dst(),
         color,
         i === 0 && flat.length <= chunk ? flat : flat.slice(i, i + chunk),
       );
     }
-    if (clip) this._resetPictureClip();
+    if (clip) this._invalidatePictureClip();
     this._markDirty();
   }
 
@@ -2628,8 +3164,8 @@ class RenderingContext2d {
     // 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");
+    if (this._hasPolyClip) return this._shapeMiss("clip-mask");
+    const clip = this._clipRect();
 
     const { x, y, w, h, radii } = box;
     if (
@@ -2735,8 +3271,8 @@ class RenderingContext2d {
     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");
+    if (this._hasPolyClip) return this._shapeMiss("clip-mask");
+    const clip = this._clipRect();
 
     const bw = this.lineWidth;
     if (!Number.isFinite(bw) || bw <= 0) return this._shapeMiss("geometry");
@@ -2866,22 +3402,16 @@ class RenderingContext2d {
     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 (clip) this._setPictureClip(clip);
     if (corners.length) {
       const page = getShapeGlyphPage(app);
       page.ensure(corners);
       const items = [];
       for (const spec of corners) {
+        const e = page.entry(spec.key);
         items.push({
-          gs: page.glyphset.id,
-          lid: page.entry(spec.key).lid,
+          gs: e.gs,
+          lid: e.lid,
           adv: 0,
           x: spec.px,
           y: spec.py,
@@ -2893,7 +3423,7 @@ class RenderingContext2d {
         encoded.bits,
         R.PictOp.Over,
         src.id,
-        this.picture.id,
+        this._dst(),
         0,
         encoded.gsid,
         items[0].x,
@@ -2903,9 +3433,9 @@ class RenderingContext2d {
       trimShapeGlyphs(app);
     }
     if (rects.length) {
-      R.FillRectangles(R.PictOp.Over, this.picture.id, color, rects);
+      R.FillRectangles(R.PictOp.Over, this._dst(), color, rects);
     }
-    if (clip) this._resetPictureClip();
+    if (clip) this._invalidatePictureClip();
     this._markDirty();
   }
 
@@ -2940,8 +3470,7 @@ class RenderingContext2d {
     // be honoured by rounding — which would differ from the mask path's
     // antialiased edge by up to a pixel. Rare, so leave those to the mask
     // rather than quietly changing what they look like.
-    const integral = (v) => Math.abs(v - Math.round(v)) < 1e-6;
-    if (![x, y, w, h].every(integral)) return null;
+    if (![x, y, w, h].every(isIntegral)) return null;
     return {
       x: Math.round(x),
       y: Math.round(y),
@@ -2950,14 +3479,21 @@ class RenderingContext2d {
     };
   }
 
-  /** Intersection of the whole clip stack, or null if any part is not a
-   *  rectangle (or the stack is empty). */
+  /**
+   * Intersection of the rectangular part of the clip stack, or null when
+   * there is none — either because the stack is empty or because something
+   * in it is not a rectangle, and then the a8 mask owns the whole stack.
+   *
+   * Region entries are transparent here. They are not rectangles and never
+   * become one: the picture carries them, which is a different slot from
+   * this and composes with it (see _setPictureClip).
+   */
   _clipRect() {
-    if (!this._clips.length) return null;
+    if (this._hasPolyClip) return null;
     let out = null;
     for (const entry of this._clips) {
       const r = entry.rect;
-      if (!r) return null;
+      if (!r) continue; // a region entry
       if (!out) {
         out = { ...r };
         continue;
@@ -2968,6 +3504,7 @@ class RenderingContext2d {
       const bottom = Math.min(out.y + out.h, r.y + r.h);
       out = { x, y, w: Math.max(0, right - x), h: Math.max(0, bottom - y) };
     }
+    if (!out) return null;
     // clamp into the surface: the server rejects out-of-range rectangles
     const x = Math.max(0, Math.min(out.x, this.width));
     const y = Math.max(0, Math.min(out.y, this.height));
@@ -2976,11 +3513,31 @@ class RenderingContext2d {
     return { x, y, w, h };
   }
 
+  /**
+   * Replace the clip stack and re-derive what kinds of entry are in it.
+   *
+   * The two flags are what the drawing paths branch on, so they are computed
+   * once per change rather than scanned per drawing — and the stack is only
+   * ever replaced, never appended to in place, because save() hands the same
+   * array to its snapshot.
+   */
+  _setClips(next) {
+    this._clips = next;
+    let poly = false;
+    let region = false;
+    for (const entry of next) {
+      if (entry.region) region = true;
+      else if (!entry.rect) poly = true;
+    }
+    this._hasPolyClip = poly;
+    this._hasRegionClip = region;
+  }
+
   clip(...args) {
     const { polys, rule } = this._polysFor(args);
     const entry = { polys, rule, rect: RenderingContext2d._rectOfPolys(polys) };
     // copy-on-write: earlier save() snapshots keep their own clip list
-    this._clips = this._clips.concat([entry]);
+    this._setClips(this._clips.concat([entry]));
 
     // A stack of rectangles stays virtual: consumers apply the intersected
     // rectangle server-side (SetPictureClipRectangles, bounded composites),
@@ -2997,6 +3554,36 @@ class RenderingContext2d {
     this._intersectClip(entry);
   }
 
+  /**
+   * Intersect the clip with a server-side XFIXES region — a rectangle set the
+   * X server owns, which is how X describes damage from an expose, a window's
+   * SHAPE, or the area a compositor has left after subtracting the windows in
+   * front of this one. `app.createRegion(rects)` makes one (lib/region.js).
+   *
+   * Scoped like `clip()`: `restore()` takes it off again, and nothing else
+   * does. It intersects with rectangular and path clips in either order.
+   *
+   * The region is in **device pixels** and ignores the current transform —
+   * unlike `clip()`, whose path goes through it. A region is a set of integer
+   * rectangles, so there is no honest way to rotate or scale one; a caller who
+   * wants it moved can `region.translate(dx, dy)`, which the server does.
+   *
+   * Unlike installing the region on `ctx.picture` yourself, this is a clip ntk
+   * knows about: the fast paths that narrow the picture to a rectangle around
+   * a glyph run or a fill restore *to* it afterwards, instead of overwriting
+   * it with a full-plane rectangle (issue #292).
+   *
+   * @param {Region|number|{id: number}} region
+   */
+  clipRegion(region) {
+    const id = regionId(region);
+    const fixes = this._fixes || this.window.app._fixes;
+    if (!fixes) throw needXFixesError();
+    this._fixes = fixes;
+    this._setClips(this._clips.concat([{ region: id }]));
+    this._invalidatePictureClip();
+  }
+
   /**
    * Build the a8 mask from the whole clip stack, on first demand. Rect
    * entries are plain fills; only genuinely non-rectangular entries
@@ -3012,7 +3599,18 @@ class RenderingContext2d {
       [0, 0, 0, 0],
       [0, 0, this.width, this.height],
     );
-    const first = this._clips[0];
+    // region entries are the picture's clip, not the mask's business
+    const shapes = this._clips.filter((entry) => !entry.region);
+    if (!shapes.length) {
+      R.FillRectangles(
+        R.PictOp.Src,
+        this.clipMask.id,
+        [0, 0, 0, 1],
+        [0, 0, this.width, this.height],
+      );
+      return;
+    }
+    const first = shapes[0];
     if (first.rect) {
       const r = first.rect;
       const x = Math.max(0, Math.min(r.x, this.width));
@@ -3030,8 +3628,7 @@ class RenderingContext2d {
     } else {
       this._applyPolyClip(first, R.PictOp.Src);
     }
-    for (let i = 1; i < this._clips.length; i++)
-      this._intersectClip(this._clips[i]);
+    for (let i = 1; i < shapes.length; i++) this._intersectClip(shapes[i]);
   }
 
   /** The live mask, built if the stack has not needed one yet. Callers on
@@ -3739,28 +4336,27 @@ class RenderingContext2d {
    * Uniform alpha needs no surface-sized mask either: a 1x1 repeating
    * picture is the same thing to the server, with no pixel work at all.
    */
-  _beginDirectComposite() {
-    const rect = this._clips.length ? this._clipRect() : null;
-    if (!rect)
-      return { mask: this._compositeMask(), clipped: false, empty: false };
+  _beginDirectComposite(box) {
+    const rect = this._clipRect();
+    if (!rect) {
+      // a poly clip is the only thing left that needs a mask; without one
+      // there is nothing to apply here but the alpha. The mask it does need
+      // is bounded to `box`, the destination box of the composite it is for
+      // — the only pixels of it the server samples (issue #313).
+      const mask = this._hasPolyClip
+        ? this._compositeMask(box)
+        : this._alphaMask();
+      return { mask, clipped: false, empty: false };
+    }
     if (rect.w === 0 || rect.h === 0)
       return { mask: 0, clipped: false, empty: true };
-    this.Render.SetPictureClipRectangles(this.picture.id, 0, 0, [
-      rect.x,
-      rect.y,
-      rect.w,
-      rect.h,
-    ]);
-    const mask =
-      this.globalAlpha >= 1
-        ? 0
-        : this.createSolidPicture(0, 0, 0, this.globalAlpha).id;
-    return { mask, clipped: true, empty: false };
+    this._setPictureClip(rect);
+    return { mask: this._alphaMask(), clipped: true, empty: false };
   }
 
   _endDirectComposite(state) {
     if (!state.clipped) return;
-    this._resetPictureClip();
+    this._invalidatePictureClip();
   }
 
   /** The source colour for a coverage composite, with `globalAlpha` folded
@@ -3810,12 +4406,12 @@ class RenderingContext2d {
     const mx = scaled ? 0 : sx;
     const my = scaled ? 0 : sy;
 
-    const rect = this._clips.length ? this._clipRect() : null;
+    const rect = this._clipRect();
     // the mask slot can hold exactly one picture, so anything that cannot be
     // folded into the colour or handed to the server as a clip rectangle has
     // to be intersected into the scratch mask first
     const scratch =
-      (this._clips.length && !rect) ||
+      this._hasPolyClip ||
       (this.globalAlpha < 1 && !isPlainColor(this._fillStyle));
 
     if (scratch) {
@@ -3856,7 +4452,7 @@ class RenderingContext2d {
           this.height,
         );
       }
-      if (this._clips.length && !rect) {
+      if (this._hasPolyClip) {
         const clipMask = this._requireClipMask();
         R.Composite(
           R.PictOp.In,
@@ -3875,12 +4471,7 @@ class RenderingContext2d {
       } else if (rect) {
         // scratch was forced by alpha-over-gradient, not by the clip: the
         // rectangle still applies, server-side, around the final composite
-        R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-          rect.x,
-          rect.y,
-          rect.w,
-          rect.h,
-        ]);
+        this._setPictureClip(rect);
       }
       // The scratch mask is surface-sized and surface-aligned — the coverage
       // went into it at (dx, dy) — and so is a gradient source, so both are
@@ -3892,7 +4483,7 @@ class RenderingContext2d {
         op,
         this._backgroundPicture.id,
         this.fillMask.id,
-        this.picture.id,
+        this._dst(),
         dx,
         dy,
         dx,
@@ -3902,23 +4493,9 @@ class RenderingContext2d {
         dw,
         dh,
       );
-      if (rect) {
-        R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-          0,
-          0,
-          this.width,
-          this.height,
-        ]);
-      }
+      if (rect) this._invalidatePictureClip();
     } else if (!rect || (rect.w > 0 && rect.h > 0)) {
-      if (rect) {
-        R.SetPictureClipRectangles(this.picture.id, 0, 0, [
-          rect.x,
-          rect.y,
-          rect.w,
-          rect.h,
-        ]);
-      }
+      if (rect) this._setPictureClip(rect);
       // the source is a 1x1 repeating solid (offset irrelevant) or the fill
       // picture, which for a gradient is surface-aligned: same offset as the
       // destination, exactly as in _fillPolys
@@ -3926,7 +4503,7 @@ class RenderingContext2d {
         op,
         this._coverageSource().id,
         picture.id,
-        this.picture.id,
+        this._dst(),
         dx,
         dy,
         mx,
@@ -3936,9 +4513,7 @@ class RenderingContext2d {
         dw,
         dh,
       );
-      if (rect) {
-        this._resetPictureClip();
-      }
+      if (rect) this._invalidatePictureClip();
     }
 
     if (scaled) {
@@ -3984,7 +4559,7 @@ class RenderingContext2d {
         return;
       }
 
-      const state = this._beginDirectComposite();
+      const state = this._beginDirectComposite({ x: dx, y: dy, w: dw, h: dh });
       if (state.empty) return;
       const mask = state.mask;
       const scaled = dw !== sw || dh !== sh;
@@ -4007,7 +4582,7 @@ class RenderingContext2d {
           op,
           picture.id,
           mask,
-          this.picture.id,
+          this._dst(),
           0,
           0,
           dx,
@@ -4028,7 +4603,7 @@ class RenderingContext2d {
           op,
           picture.id,
           mask,
-          this.picture.id,
+          this._dst(),
           sx,
           sy,
           dx,
@@ -4054,19 +4629,25 @@ class RenderingContext2d {
     if (image instanceof RenderingContext2d) {
       // TODO: if need to scale, set transform
       // TODO: respect global compositing blend mode
+      const full = { x: 0, y: 0, w: this.width, h: this.height };
+      // source and destination are both surface-aligned here, so a clip
+      // rectangle is just a smaller box to copy (issue #307)
+      const direct = this._boxedComposite(full, this.Render.PictOp.Over);
+      if (direct && !direct.box) return;
+      const box = direct ? direct.box : full;
       this.Render.Composite(
         this.Render.PictOp.Over,
         image.picture.id,
-        this._compositeMask(),
-        this.picture.id,
-        0,
-        0,
-        0,
-        0,
-        0,
-        0,
-        this.width,
-        this.height,
+        direct ? direct.mask : this._compositeMask(box),
+        this._dst(),
+        box.x,
+        box.y,
+        box.x,
+        box.y,
+        box.x,
+        box.y,
+        box.w,
+        box.h,
       );
       this._markDirty();
     } else if (
@@ -4075,6 +4656,13 @@ class RenderingContext2d {
       typeof image.context.getImageData === "function"
     ) {
       // node-canvas Canvas ( or any ctx with ctx.canvas.getImageData returning pixels)
+      // What the clip leaves of the composite, decided before anything is
+      // uploaded: a clip that rejects it whole makes the upload below dead
+      // work (issue #307)
+      const full = { x: 0, y: 0, w: this.width, h: this.height };
+      const direct = this._boxedComposite(full, this.Render.PictOp.Over);
+      if (direct && !direct.box) return;
+      const box = direct ? direct.box : full;
       const imageData = image.context.getImageData(sx, sy, sWidth, sHeight);
       // node-canvas hands over straight RGBA, and the rgba32 picture below is
       // premultiplied — this used to swap the channels and stop there, which
@@ -4114,16 +4702,16 @@ class RenderingContext2d {
         this.Render.Composite(
           this.Render.PictOp.Over,
           picture.id,
-          this._compositeMask(),
-          this.picture.id,
-          0,
-          0,
-          0,
-          0,
-          0,
-          0,
-          this.width,
-          this.height,
+          direct ? direct.mask : this._compositeMask(box),
+          this._dst(),
+          box.x,
+          box.y,
+          box.x,
+          box.y,
+          box.x,
+          box.y,
+          box.w,
+          box.h,
         );
         this._markDirty();
       } finally {
@@ -4162,6 +4750,14 @@ class RenderingContext2d {
     );
     if (x1 <= x0 || y1 <= y0) return;
 
+    // A rectangular clip shrinks the box instead of becoming a mask (issue
+    // #307). Decided before the picture transform is installed, so a draw
+    // the clip rejects does not have to put it back.
+    const bbox = { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+    const direct = this._boxedComposite(bbox, op);
+    if (direct && !direct.box) return;
+    const box = direct ? direct.box : bbox;
+
     // device -> source sample (adding the source-rect origin)
     const srcM = [inv[0], inv[1], inv[2], inv[3], inv[4] + sx, inv[5] + sy];
     this.Render.SetPictureTransform(picture.id, [
@@ -4176,20 +4772,19 @@ class RenderingContext2d {
       1,
     ]);
     picture.setFilter("bilinear");
-    const mask = this._compositeMask();
     this.Render.Composite(
       op,
       picture.id,
-      mask,
-      this.picture.id,
-      x0,
-      y0,
-      x0,
-      y0,
-      x0,
-      y0,
-      x1 - x0,
-      y1 - y0,
+      direct ? direct.mask : this._compositeMask(box),
+      this._dst(),
+      box.x,
+      box.y,
+      box.x,
+      box.y,
+      box.x,
+      box.y,
+      box.w,
+      box.h,
     );
     this.Render.SetPictureTransform(picture.id, [1, 0, 0, 0, 1, 0, 0, 0, 1]);
     picture.setFilter("nearest");