ntk 5.2.0 → 5.4.0

package/lib/renderingcontext_2d.js

@@ -1,9 +1,11 @@
 import parseFontStyle from 'canvas-fontstyle';
 import extrudePolyline from 'extrude-polyline';
 
+import { safeRelease } from './cleanup.js';
 import { cssColor } from './color.js';
 import Drawable from './drawable.js';
 import { Image } from './image.js';
+import { ImageData, fromStraightRgba, pixelLayout, toStraightRgba } from './imagedata.js';
 import {
   Path2D,
   flattenPath,
@@ -25,6 +27,48 @@ import { trapezoidize } from './trapezoid.js';
 
 const DEFAULT_FONT = '20px sans-serif';
 
+/**
+ * Fallback for a context dropped without `destroy()`, matching Pixmap,
+ * Picture and GlyphSet. Only the GCs are freed here: everything else a
+ * 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 }) => {
+  safeRelease(X, () => {
+    for (const gc of gcs) {
+      if (!gc) continue;
+      X.FreeGC(gc);
+      X.ReleaseID(gc);
+    }
+  });
+});
+
+/**
+ * What `drawImage` takes as a server-side source: anything that knows its own
+ * size and can hand over a `Picture` for this connection.
+ *
+ * `Image` is client pixels uploaded once; `Surface` is pixels the server drew
+ * itself. Neither is special — the contract is the two members, so a caller
+ * with its own cache of rendered things can satisfy it without ntk knowing
+ * the type. A `RenderingContext2d` deliberately does not match: its `picture`
+ * is a property rather than a method, and it keeps its own branch below.
+ */
+/** a fillStyle with a single colour behind it, as opposed to a gradient or a
+ * caller-supplied Picture */
+function isPlainColor(style) {
+  return typeof style === 'string' || Array.isArray(style);
+}
+
+function isPictureSource(image) {
+  return (
+    image instanceof Image ||
+    (image != null &&
+      typeof image.picture === 'function' &&
+      Number.isFinite(image.width) &&
+      Number.isFinite(image.height))
+  );
+}
+
 // canvas globalCompositeOperation -> XRender PictOp name. Porter-Duff ops
 // map directly; with a clip/shape mask active the op only applies inside
 // the mask coverage (outside pixels are left untouched).
@@ -146,9 +190,15 @@ class RenderingContext2d {
   constructor(window) {
     const X = window.X;
     this.X = X;
+    // 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);
 
     this.window = window;
-    this.Render = window.app.display.Render;
+    this.display = window.app.display;
+    this.Render = this.display.Render;
+    this._layoutCache = null;
 
     // draw into the window's backing pixmap when it has one (double
     // buffering); re-bind when the backing pixmap is reallocated on resize
@@ -200,17 +250,26 @@ class RenderingContext2d {
     const target = this.window._backing || this.window;
     if (this._target === target) return;
     this._target = target;
+    this._layoutCache = null; // the new target may be a different depth
 
     if (!this._gc) {
       // one GC is enough: it stays valid for any drawable of the same
       // screen and depth (the backing pixmap matches the window depth)
       this._gc = this.X.AllocID();
+      this._gcs.push(this._gc);
       this.X.CreateGC(this._gc, target.id);
     }
     if (this.picture) this.picture.destroy();
-    // TODO: support a8
+    // 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 : this.Render.rgb24;
+    const format =
+      depth === 32
+        ? this.Render.rgba32
+        : depth === 8
+          ? this.Render.a8
+          : this.Render.rgb24;
     this.picture = new Picture(this.window.app, {
       drawable: target,
       format,
@@ -220,6 +279,61 @@ class RenderingContext2d {
     this._dropMasks();
   }
 
+  /**
+   * Release everything this context allocated server-side. Idempotent, and
+   * the context must not be drawn with afterwards.
+   *
+   * A context bound to a window normally lives as long as the window and the
+   * connection outlives both, which is why this went missing for so long (see
+   * issue #156). It matters as soon as contexts are created *dynamically* —
+   * one per offscreen `Surface`, say — because without it each one
+   * permanently costs a GC, a Picture, and a 1x1 pixmap per fill colour used.
+   *
+   * `_backgroundPicture` and `_glyphSource` are deliberately not freed here:
+   * both are either aliases into `_solidPictures`, already freed below, or a
+   * `Picture`/`CanvasGradient` the caller passed in through `fillStyle`,
+   * which is not ours to free.
+   */
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    gcRegistry.unregister(this);
+
+    this._clips = [];
+    this._dropMasks();
+    for (const gc of [this._gc, this._fillMaskGC]) {
+      if (!gc) continue;
+      safeRelease(this.X, () => {
+        this.X.FreeGC(gc);
+        this.X.ReleaseID(gc);
+      });
+    }
+    this._gc = this._fillMaskGC = null;
+    this._gcs.length = 0;
+
+    for (const picture of this._solidPictures.values()) {
+      picture.destroy();
+      picture._sourcePixmap?.destroy();
+    }
+    this._solidPictures.clear();
+    this._backgroundPicture = this._glyphSource = null;
+
+    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();
+      } else {
+        this.picture.destroy();
+      }
+      this.picture = null;
+    }
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+
   _dropMasks() {
     if (this.fillMask) {
       this.fillMask.destroy();
@@ -565,6 +679,7 @@ class RenderingContext2d {
   _maskGC() {
     if (!this._fillMaskGC) {
       this._fillMaskGC = this.X.AllocID();
+      this._gcs.push(this._fillMaskGC);
       this.X.CreateGC(this._fillMaskGC, this.fillMaskDrawable.id);
     }
     return this._fillMaskGC;
@@ -1320,25 +1435,137 @@ class RenderingContext2d {
     return new CanvasGradient('conical', this, x0, y0, angle);
   }
 
-  createImageData(w, h) {
-    return {
-      width: w,
-      height: h,
-      data: Buffer.alloc(w * h * 4)
-    };
+  /** the pixel layout of whatever this context currently draws into */
+  get _layout() {
+    const depth = this._target.depth ?? this.window.depth ?? this.display.screen[0].root_depth;
+    if (!this._layoutCache || this._layoutCache.depth !== depth) {
+      this._layoutCache = pixelLayout(this.display, depth);
+    }
+    return this._layoutCache;
+  }
+
+  /**
+   * A blank `ImageData`, or a copy of one — both canvas forms:
+   *
+   *   createImageData(width, height)
+   *   createImageData(imagedata)
+   */
+  createImageData(a, b) {
+    if (typeof a === 'number') return new ImageData(a, b);
+    if (a && typeof a.width === 'number' && a.data) return new ImageData(a.width, a.height);
+    throw new TypeError('createImageData: pass (width, height) or an ImageData');
   }
 
-  // TODO: remove, add drawImage
-  putImageData(data, x, y) {
-    // todo: use constants
-    this.X.PutImage(2, this._target.id, this._gc, data.width, data.height, x, y, 0, 24, data.data);
+  /**
+   * Write straight RGBA pixels into the drawable at `(x, y)`.
+   *
+   * `data` is an `ImageData` or anything shaped like one; its bytes are
+   * non-premultiplied RGBA, and they are converted to the drawable's own
+   * pixel layout on the way out. The optional `dirty*` rectangle limits the
+   * write to part of the source, as in the canvas spec.
+   */
+  putImageData(data, x, y, dirtyX = 0, dirtyY = 0, dirtyWidth, dirtyHeight) {
+    const { width, height } = data;
+    const src = data.data;
+    if (!src || src.length !== width * height * 4) {
+      throw new Error(
+        `putImageData: data must be ${width * height * 4} RGBA bytes for ${width}x${height}`
+      );
+    }
+    dirtyWidth ??= width;
+    dirtyHeight ??= height;
+    // the spec normalises negative extents by moving the origin
+    if (dirtyWidth < 0) { dirtyX += dirtyWidth; dirtyWidth = -dirtyWidth; }
+    if (dirtyHeight < 0) { dirtyY += dirtyHeight; dirtyHeight = -dirtyHeight; }
+    const sx = Math.max(0, dirtyX);
+    const sy = Math.max(0, dirtyY);
+    const sw = Math.min(width, dirtyX + dirtyWidth) - sx;
+    const sh = Math.min(height, dirtyY + dirtyHeight) - sy;
+    if (!(sw > 0) || !(sh > 0)) return;
+
+    let rgba = src;
+    if (sx !== 0 || sy !== 0 || sw !== width || sh !== height) {
+      const cropped = new Uint8ClampedArray(sw * sh * 4);
+      for (let row = 0; row < sh; row++) {
+        cropped.set(
+          src.subarray((sy + row) * width * 4 + sx * 4, (sy + row) * width * 4 + (sx + sw) * 4),
+          row * sw * 4
+        );
+      }
+      rgba = cropped;
+    }
+
+    const layout = this._layout;
+    const bytes = fromStraightRgba(rgba, layout, sw, sh);
+    // stay under the server's maximum request size by uploading row bands
+    const stride = sw * 4;
+    const maxBytes = ((this.display.max_request_length ?? 65535) - 8) * 4;
+    const rowsPerBand = Math.max(1, Math.floor(maxBytes / stride));
+    for (let row = 0; row < sh; row += rowsPerBand) {
+      const rows = Math.min(rowsPerBand, sh - row);
+      this.X.PutImage(
+        2, // ZPixmap
+        this._target.id,
+        this._gc,
+        sw, rows,
+        x + sx, y + sy + row,
+        0,
+        layout.depth,
+        bytes.subarray(row * stride, (row + rows) * stride)
+      );
+    }
     this._markDirty();
   }
 
+  /**
+   * Read pixels back as canvas `ImageData` — straight (non-premultiplied)
+   * RGBA in a `Uint8ClampedArray`, exactly like the browser's.
+   *
+   * Reads the backing pixmap on double-buffered windows, so it is valid even
+   * where the window is occluded. Returns a promise; a trailing
+   * `cb(err, imageData)` is still accepted.
+   *
+   * The drawable's own bytes are none of those things — see
+   * `lib/imagedata.js` — so this costs a pass over the pixels. `readPixels()`
+   * is the way to skip that when you want the server's layout.
+   */
   getImageData(x, y, w, h, cb) {
-    // reads the backing pixmap on double-buffered windows: always valid,
-    // even where the window is occluded on screen
-    this.X.GetImage(2, this._target.id, x, y, w, h, 0xffffffff, cb);
+    const promise = this.readPixels(x, y, w, h).then(
+      (raw) => new ImageData(toStraightRgba(raw.data, raw.layout, w, h), w, h)
+    );
+    if (typeof cb === 'function') {
+      promise.then((data) => cb(null, data), cb);
+      return undefined;
+    }
+    return promise;
+  }
+
+  /**
+   * Read pixels in the server's own layout, with no conversion.
+   *
+   * The escape hatch under `getImageData` for code that wants to hand the
+   * bytes straight back to `PutImage`, feed a codec, or do its own unpacking.
+   * Unlike a bare `GetImage` it says what the bytes mean:
+   *
+   *   { width, height, data, depth, bitsPerPixel, byteOrder, masks,
+   *     premultiplied }
+   *
+   * `byteOrder` is `'lsb'` or `'msb'` and is the *server's* pixel order,
+   * which is a different handshake field from the one this connection
+   * speaks. `masks` gives the bit position of each channel inside a pixel
+   * word, `alpha` being 0 when the drawable has no alpha channel — in which
+   * case the spare byte is undefined padding, not opacity.
+   *
+   * @returns {Promise<object>}
+   */
+  readPixels(x, y, w, h) {
+    const layout = this._layout;
+    return new Promise((resolve, reject) => {
+      this.X.GetImage(2, this._target.id, x, y, w, h, 0xffffffff, (err, img) => {
+        if (err) return reject(err);
+        resolve({ width: w, height: h, data: img.data, layout, ...layout });
+      });
+    });
   }
 
   /**
@@ -1354,8 +1581,127 @@ class RenderingContext2d {
    * RenderingContext2d, or a node-canvas-like object. Images honor the
    * current transform (server-side, via the picture transform).
    */
+  /**
+   * Clip and mask for a direct composite, as a bracket around it.
+   *
+   * A rectangular clip is something the server can do itself: two small
+   * requests around the composite instead of intersecting a full-surface a8
+   * mask, which costs the same on the wire and many times the pixel work.
+   * This is the fast path `drawGlyphs` already has — and a renderer that
+   * clips to a damage rect makes it the common case, not a rare one.
+   *
+   * 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.clipMask ? this._clipRect() : null;
+    if (!rect) return { mask: this._compositeMask(), 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 };
+  }
+
+  _endDirectComposite(state) {
+    if (!state.clipped) return;
+    this.Render.SetPictureClipRectangles(this.picture.id, 0, 0, [0, 0, this.width, this.height]);
+  }
+
+  /** The source colour for a coverage composite, with `globalAlpha` folded
+   * into it. The mask slot is taken by the coverage, so the alpha has to go
+   * somewhere — and a 1x1 solid is free, where a surface-sized alpha mask is
+   * not. Falls back to the fill picture for gradients, which have no single
+   * colour to fold into; `_drawCoverage` routes those through the scratch. */
+  _coverageSource() {
+    const style = this._fillStyle;
+    if (this.globalAlpha >= 1 || !isPlainColor(style)) return this._backgroundPicture;
+    const c = parseColor(style);
+    return this.createSolidPicture(c[0], c[1], c[2], c[3] * this.globalAlpha);
+  }
+
+  /**
+   * Composite a coverage source: the a8 picture is the *mask* and the current
+   * `fillStyle` is what gets painted through it.
+   *
+   * This is the same shape as `drawGlyphs`, and for the same reason — a
+   * monochrome drawing rendered once as coverage can then be painted in any
+   * colour, so a hover, a disabled state and a theme change all reuse the one
+   * rendered copy instead of each needing their own.
+   */
+  _drawCoverage(picture, sx, sy, sw, sh, dx, dy, dw, dh, op) {
+    const R = this.Render;
+    const scaled = dw !== sw || dh !== sh;
+    if (scaled) {
+      R.SetPictureTransform(picture.id, [sw / dw, 0, sx, 0, sh / dh, sy, 0, 0, 1]);
+      picture.setFilter('bilinear');
+    }
+    // with a transform in place the mask is already sampled from (sx, sy)
+    const mx = scaled ? 0 : sx;
+    const my = scaled ? 0 : sy;
+
+    const rect = this.clipMask ? this._clipRect() : null;
+    // 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.clipMask && !rect) || (this.globalAlpha < 1 && !isPlainColor(this._fillStyle));
+
+    if (scratch) {
+      this._ensureFillMask();
+      R.FillRectangles(R.PictOp.Src, this.fillMask.id, [0, 0, 0, 0], [0, 0, this.width, this.height]);
+      R.Composite(R.PictOp.Src, picture.id, 0, this.fillMask.id, mx, my, 0, 0, dx, dy, dw, dh);
+      if (this.globalAlpha < 1) {
+        R.Composite(
+          R.PictOp.InReverse,
+          this.createSolidPicture(0, 0, 0, this.globalAlpha).id,
+          0,
+          this.fillMask.id,
+          0, 0, 0, 0, 0, 0,
+          this.width, this.height
+        );
+      }
+      if (this.clipMask) {
+        R.Composite(R.PictOp.In, this.clipMask.id, 0, this.fillMask.id, 0, 0, 0, 0, 0, 0, this.width, this.height);
+      }
+      R.Composite(
+        op,
+        this._backgroundPicture.id,
+        this.fillMask.id,
+        this.picture.id,
+        0, 0, 0, 0,
+        dx, dy,
+        dw, dh
+      );
+    } 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]);
+      }
+      R.Composite(
+        op,
+        this._coverageSource().id,
+        picture.id,
+        this.picture.id,
+        0, 0,
+        mx, my,
+        dx, dy,
+        dw, dh
+      );
+      if (rect) {
+        R.SetPictureClipRectangles(this.picture.id, 0, 0, [0, 0, this.width, this.height]);
+      }
+    }
+
+    if (scaled) {
+      // restore defaults so the cached surface stays reusable as-is
+      R.SetPictureTransform(picture.id, [1, 0, 0, 0, 1, 0, 0, 0, 1]);
+      picture.setFilter('nearest');
+    }
+    this._markDirty();
+  }
+
   drawImage(image, ...args) {
-    if (image instanceof Image) {
+    if (isPictureSource(image)) {
       let sx = 0;
       let sy = 0;
       let sw = image.width;
@@ -1383,7 +1729,14 @@ class RenderingContext2d {
         return;
       }
 
-      const mask = this._compositeMask();
+      if (image.format === 'a8') {
+        this._drawCoverage(picture, sx, sy, sw, sh, dx, dy, dw, dh, op);
+        return;
+      }
+
+      const state = this._beginDirectComposite();
+      if (state.empty) return;
+      const mask = state.mask;
       const scaled = dw !== sw || dh !== sh;
       if (scaled) {
         // the picture transform maps composite coordinates into source
@@ -1415,6 +1768,7 @@ class RenderingContext2d {
           dw, dh
         );
       }
+      this._endDirectComposite(state);
       this._markDirty();
       return;
     }
@@ -1424,7 +1778,8 @@ class RenderingContext2d {
     const sx = 0;
     const sy = 0;
 
-    // TODO: allow to draw Window, Pixmap, Picture
+    // Drawables reach the branch above by way of Surface, which is what a
+    // Window/Pixmap/Picture source actually needs: a size and a Picture.
     if (image instanceof RenderingContext2d) {
       // TODO: if need to scale, set transform
       // TODO: respect global compositing blend mode
@@ -1441,31 +1796,50 @@ class RenderingContext2d {
     } else if (image && image.context && typeof image.context.getImageData === 'function') {
       // node-canvas Canvas ( or any ctx with ctx.canvas.getImageData returning pixels)
       const imageData = image.context.getImageData(sx, sy, sWidth, sHeight);
-      // rgba -> bgra
-      const data = Buffer.alloc(imageData.data.length);
-      for (let i = 0; i < data.length; i += 4) {
-        data[i + 2] = imageData.data[i];
-        data[i + 1] = imageData.data[i + 1];
-        data[i] = imageData.data[i + 2];
-        data[i + 3] = imageData.data[i + 3]; // multiply source alpha by context globalAlpha?
-      }
+      // node-canvas hands over straight RGBA, and the rgba32 picture below is
+      // premultiplied — this used to swap the channels and stop there, which
+      // composited translucent images at full brightness
+      const data = fromStraightRgba(
+        imageData.data,
+        pixelLayout(this.display, 32),
+        sWidth,
+        sHeight
+      );
 
-      const pixmap = new Pixmap(this.window.app, { depth: 32, width: sWidth, height: sHeight });
-      const picture = new Picture(this.window.app, { drawable: pixmap, format: this.Render.rgba32 });
-      pixmap._gc = this.X.AllocID();
-      this.X.CreateGC(pixmap._gc, pixmap.id);
-      this.X.PutImage(2, pixmap.id, pixmap._gc, sWidth, sHeight, sx, sy, 0, 32, data);
+      // One upload GC per app rather than one per call, the same sharing
+      // Image.picture does: a GC is valid for any drawable of the same screen
+      // and depth. This used to allocate a GC, a pixmap and a picture every
+      // time and free none of them, so drawing a node-canvas source in an
+      // animation loop leaked three server resources per frame.
+      const app = this.window.app;
+      const pixmap = new Pixmap(app, { depth: 32, width: sWidth, height: sHeight });
+      const picture = new Picture(app, { drawable: pixmap, format: this.Render.rgba32 });
+      try {
+        let gc = app._imageUploadGC;
+        if (!gc) {
+          gc = app._imageUploadGC = this.X.AllocID();
+          this.X.CreateGC(gc, pixmap.id);
+        }
+        // the crop already happened in getImageData, so it lands at the
+        // pixmap's origin — sx/sy here wrote it off the edge
+        this.X.PutImage(2, pixmap.id, gc, sWidth, sHeight, 0, 0, 0, 32, data);
 
-      this.Render.Composite(
-        this.Render.PictOp.Over,
-        picture.id,
-        this._compositeMask(),
-        this.picture.id,
-        0, 0, 0, 0, 0, 0,
-        this.width,
-        this.height
-      );
-      this._markDirty();
+        this.Render.Composite(
+          this.Render.PictOp.Over,
+          picture.id,
+          this._compositeMask(),
+          this.picture.id,
+          0, 0, 0, 0, 0, 0,
+          this.width,
+          this.height
+        );
+        this._markDirty();
+      } finally {
+        // the composite is queued, and X executes requests in order, so the
+        // server is done with these by the time it reads the frees
+        picture.destroy();
+        pixmap.destroy();
+      }
     }
   }
 

package/lib/surface.js

@@ -0,0 +1,118 @@
+import Picture from './picture.js';
+import Pixmap from './pixmap.js';
+
+/**
+ * An offscreen drawing surface: a pixmap, its Picture, and enough of the
+ * `Image` shape that `ctx.drawImage` takes it as a source.
+ *
+ *   const surface = new Surface(app, { width: 20, height: 20 });
+ *   surface.render((ctx) => icon.draw(ctx, 0, 0, 20, 20));
+ *   ctx.drawImage(surface, x, y);            // one server-side composite
+ *
+ * The point is drawing something once and compositing it many times. An
+ * `Image` already does that for decoded PNG/JPEG pixels uploaded from the
+ * client; a Surface is the same contract for pixels drawn *by* the server,
+ * so nothing crosses the wire but the composite.
+ *
+ * ### Coverage surfaces
+ *
+ * `format: 'a8'` makes a surface that stores coverage instead of colour.
+ * Drawn through `drawImage` it acts as a mask for the current `fillStyle`,
+ * so one rendered copy of a monochrome drawing serves every colour it is
+ * ever asked for — the trick the glyph cache already runs on text, applied
+ * to arbitrary drawings. See `SvgView.paintKind` for deciding when a drawing
+ * qualifies.
+ *
+ * ### Lifetime
+ *
+ * `destroy()` frees the pixmap and the picture; both of those carry their own
+ * finalizers, so a dropped surface still releases. `render()` builds a
+ * context, hands it over, and
+ * destroys it again, which keeps the steady-state cost of a surface to two
+ * server objects — a context is much heavier than it looks, and holding one
+ * per surface is what issue #156 is about.
+ */
+export class Surface {
+  constructor(app, { width, height, format = 'argb32' } = {}) {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+      throw new Error('Surface: width and height must be positive integers');
+    }
+    if (format !== 'argb32' && format !== 'a8') {
+      throw new Error(`Surface: unknown format ${JSON.stringify(format)} (argb32 or a8)`);
+    }
+    this.app = app;
+    this.width = width;
+    this.height = height;
+    this.format = format;
+    this.depth = format === 'a8' ? 8 : 32;
+
+    this.pixmap = new Pixmap(app, { depth: this.depth, width, height });
+    this._picture = new Picture(app, {
+      drawable: this.pixmap,
+      format: format === 'a8' ? app.display.Render.a8 : app.display.Render.rgba32
+    });
+    // a fresh pixmap's contents are undefined per the protocol, so a surface
+    // that is only partly drawn would otherwise composite server garbage
+    this.clear();
+  }
+
+  /** bytes of server-side storage — what a cache budgets against */
+  get bytes() {
+    return this.width * this.height * (this.depth === 8 ? 1 : 4);
+  }
+
+  /** The server-side Picture, on the app this surface belongs to. Mirrors
+   * `Image.picture(app)` so `drawImage` can take either without asking which
+   * it has. */
+  picture(app) {
+    if (app && app !== this.app) {
+      throw new Error('Surface: belongs to a different X connection');
+    }
+    return this._picture;
+  }
+
+  /** reset every pixel to fully transparent */
+  clear() {
+    const R = this.app.display.Render;
+    R.FillRectangles(R.PictOp.Src, this._picture.id, [0, 0, 0, 0], [0, 0, this.width, this.height]);
+    return this;
+  }
+
+  /**
+   * Draw into the surface through a 2d context, in surface-local coordinates
+   * where (0, 0) is its top-left corner.
+   *
+   * The context is created for the call and destroyed after it, so a surface
+   * kept in a cache holds no context of its own. Callers doing many draws
+   * into the same surface should `getContext('2d')` once and destroy it
+   * themselves instead.
+   */
+  render(fn) {
+    const ctx = this.getContext('2d');
+    try {
+      fn(ctx);
+    } finally {
+      ctx.destroy();
+    }
+    return this;
+  }
+
+  /** a rendering context on the backing pixmap — the caller owns it, and
+   * owes it a `destroy()` */
+  getContext(name, ...args) {
+    return this.pixmap.getContext(name, ...args);
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._picture.destroy();
+    this.pixmap.destroy();
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}
+
+export default Surface;