react-x11 2.3.1 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -90,7 +90,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.1.0",
+    "@windowkit/appkit": "^0.3.0",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.7.0"
   },

package/src/cocoa/app.js

@@ -24,13 +24,14 @@ import { CocoaGlobalMenuExport } from './globalmenu.js';
 import { CocoaPaneHost } from './panehost.js';
 import { CocoaPaneWindow } from './panewindow.js';
 import { CocoaFontManager } from './fonts.js';
+import { CocoaSurface } from './surface.js';
 import { CocoaWindow } from './window.js';
 import { decodeKey, modifierMask } from './keymap.js';
 import { loadNative } from './native.js';
 
 const RAF_INTERVAL_MS = 16;
 
-class CocoaApp {
+export class CocoaApp {
   constructor(native, options = {}) {
     this._native = native;
     this.options = options;
@@ -53,7 +54,10 @@ class CocoaApp {
       process.env.REACT_X11_COCOA_PRESENTER ??
       'surface';
 
-    this.fonts = new CocoaFontManager();
+    // the app's own bridge, so an app over a fake one (the tests) needs no
+    // real bridge on the machine — the manager's default loads it only when
+    // it is built standalone
+    this.fonts = new CocoaFontManager(native);
 
     // AppKit-rendered control bezels. Its *presence* is the capability:
     // `useSupports('nativeControls')` and the widget set's `controls:
@@ -189,6 +193,17 @@ class CocoaApp {
     return new CocoaPaneHost(this, wnd);
   }
 
+  /**
+   * The offscreen-surface seam `react-x11/ntk`'s `Surface` dispatches on:
+   * ntk's `Surface` contract over a CG bitmap (src/cocoa/surface.js). Its
+   * presence is what makes `new Surface(app, { width, height })` answer a
+   * surface here rather than ntk's pixmap, which needs an X connection — a
+   * backend without the method gets ntk's, so an X app is never asked.
+   */
+  createSurface(options) {
+    return new CocoaSurface(this, options);
+  }
+
   /**
    * The `useGlobalMenu` transport seam: same owner shape as the D-Bus
    * GlobalMenuExport (start/stop/update), pointed at the macOS menu bar.

package/src/cocoa/context2d.js

@@ -65,6 +65,32 @@ class LinearGradient {
   }
 }
 
+const clamp01 = (v) => Math.min(1, Math.max(0, Number(v) || 0));
+
+/**
+ * The Render ops text draws with, numbered as XRender numbers them so a
+ * caller's `ctx.Render?.PictOp?.Over ?? 3` reads the same on both
+ * backends. Every op draws as Over here: the bridge composites glyph
+ * coverage with the context's fill and offers no blend-mode switch, and
+ * for the opaque inks text uses Src and Over agree.
+ */
+const PICT_OP = Object.freeze({ Src: 1, Over: 3 });
+const RENDER = Object.freeze({ PictOp: PICT_OP });
+
+/**
+ * A solid ink for `drawGlyphs` — ntk's `createSolidPicture` answers an
+ * XRender picture; here it is the colour itself. Premultiplied 0..1 in, as
+ * XRender solids are (the identity for the opaque inks text uses), straight
+ * for CoreGraphics inside.
+ */
+class SolidPicture {
+  constructor(r, g, b, a) {
+    const alpha = clamp01(a);
+    const straight = (c) => (alpha > 0 ? clamp01(c / alpha) : 0);
+    this._rgba = [straight(r), straight(g), straight(b), alpha];
+  }
+}
+
 export class CocoaContext2D {
   /**
    * @param native the @windowkit/appkit module
@@ -253,16 +279,34 @@ export class CocoaContext2D {
   }
 
   save() {
+    // Sync before pushing: a fresh surface empties the stack on its way in,
+    // and a state pushed ahead of that sync was lost to it — the first
+    // save/restore pair on a new context restored nothing.
+    const surface = this._s();
     this._stack.push({ ...this._state, dash: [...this._state.dash] });
-    this._native.ctxSave(this._s());
+    this._native.ctxSave(surface);
   }
 
   restore() {
+    // Canvas's rule: a restore with nothing saved does nothing. It is also
+    // what keeps a surface's base state safe under an unbalanced painter —
+    // the native stack below the JS one is the surface's own — and what a
+    // replaced backing surface wants, since it has nothing saved either.
+    const surface = this._s();
     const prev = this._stack.pop();
-    if (prev) this._state = prev;
-    this._native.ctxRestore(this._s());
+    if (!prev) return;
+    this._state = prev;
+    this._native.ctxRestore(surface);
   }
 
+  /**
+   * ntk's contract has a caller who took a context owing it a `destroy()`
+   * — there it is a GC and a Picture. Here a context is JS state over the
+   * surface's own graphics state, so there is nothing to free; the call is
+   * honoured so a caller written against ntk needs no branch.
+   */
+  destroy() {}
+
   _concat(a2, b2, c2, d2, e2, f2) {
     const [a, b, c, d, e, f] = this._state.ctm;
     this._state.ctm = [
@@ -617,6 +661,107 @@ export class CocoaContext2D {
     return promise;
   }
 
+  // --- glyph runs (ntk's documented run contract) --------------------------
+
+  /** ntk's Render extension object, as much of it as text needs. */
+  get Render() {
+    return RENDER;
+  }
+
+  createSolidPicture(r, g, b, a) {
+    return new SolidPicture(r, g, b, a);
+  }
+
+  /**
+   * Composite glyph runs — ntk's contract (its docs/text.md#glyph-runs),
+   * so a renderer written against ntk's context runs here unchanged:
+   * `positioned` is `[{ run: { font, size, glyphs: [{ id, ax, dx, dy }] },
+   * x, y }]`, `x`/`y` the run's baseline origin in user space, the pen
+   * starting at `x` and each glyph inking at `(pen + dx, y - dy)` — `dy`
+   * y-up — before advancing by `ax`. `op` is `Render.PictOp.Over` or
+   * `.Src`; `src` a `createSolidPicture` ink.
+   *
+   * The glyphs are grouped by face and size and go out as one native call
+   * — `CTFontDrawGlyphs` per group, with the fill set to `src`'s colour —
+   * so a frame of terminal text is one call per foreground colour.
+   * `run.font` is a face from `fonts.match()`/`fallbackFor()`, or an ntk
+   * `Font` from `openFont()` (resolved to CoreText from the same bytes, so
+   * its glyph ids hold); a glyph carrying a `font` of its own — what
+   * `shape()` produces when CoreText substituted a face — draws with that
+   * face.
+   *
+   * One difference from ntk, stated: the transform applies to the glyphs as
+   * well as to their origins, because CoreGraphics draws text through the
+   * CTM like everything else, where ntk moves the origins and keeps the
+   * advances in device pixels. Under a translate, which is what a node's
+   * paint runs in, the two agree.
+   */
+  drawGlyphs(op, src, positioned) {
+    if (!Array.isArray(positioned) || positioned.length === 0) return;
+    const fonts = this._fonts;
+    if (typeof fonts?._runHandle !== 'function') return;
+    const batches = new Map(); // CTFont handle -> { font, glyphs, positions }
+    for (const placed of positioned) {
+      const run = placed?.run;
+      const glyphs = run?.glyphs;
+      if (!glyphs?.length) continue;
+      const size = run.size;
+      const runHandle = fonts._runHandle(run.font, size);
+      let pen = 0;
+      for (const g of glyphs) {
+        const handle = g.font ? fonts._runHandle(g.font, size) : runHandle;
+        if (handle) {
+          let batch = batches.get(handle);
+          if (!batch) {
+            batch = { font: handle, glyphs: [], positions: [] };
+            batches.set(handle, batch);
+          }
+          batch.glyphs.push(g.id);
+          batch.positions.push(
+            placed.x + pen + (g.dx || 0),
+            placed.y - (g.dy || 0),
+          );
+        }
+        pen += g.ax || 0;
+      }
+    }
+    if (batches.size === 0) return;
+    const [r, g, b, a] = this._inkOf(src);
+    const surface = this._s();
+    this._native.ctxSetFillColor(surface, r, g, b, a);
+    const runs = [];
+    for (const batch of batches.values()) {
+      runs.push({
+        font: batch.font,
+        glyphs: Uint16Array.from(batch.glyphs),
+        positions: Float64Array.from(batch.positions),
+      });
+    }
+    this._native.ctxDrawGlyphs(surface, runs);
+    this._dirty();
+  }
+
+  /**
+   * The straight colour a `drawGlyphs` source paints with: a solid ink, a
+   * CSS colour string, a straight `[r, g, b, a]` — or, for anything else
+   * (a gradient, which glyph runs do not fill through here), the fill
+   * style in force.
+   */
+  _inkOf(src) {
+    if (src instanceof SolidPicture) return src._rgba;
+    if (typeof src === 'string') return parseColor(src);
+    if (Array.isArray(src) && src.length >= 3) {
+      return [
+        clamp01(src[0]),
+        clamp01(src[1]),
+        clamp01(src[2]),
+        src.length > 3 ? clamp01(src[3]) : 1,
+      ];
+    }
+    const style = this._state.fillStyle;
+    return style instanceof LinearGradient ? BLACK : parseColor(style);
+  }
+
   // --- text (minimal: enough for <canvas onDraw> users) --------------------
 
   _drawLayout(layout, x, y) {

package/src/cocoa/fonts.js

@@ -6,7 +6,15 @@
 //                               overflow, direction })
 //     -> { width, height, lines, draw(ctx, x, y),
 //          indexAt(x, y), caretPosition(cp) }
-//   fonts.match(family, { weight, style }) -> { metrics(size) }
+//   fonts.match(family, { weight, style }) -> face
+//   fonts.fallbackFor(codepoint, family, { weight, style }) -> face | null
+//
+// and a face is ntk's `Font` as far as a renderer that positions glyphs
+// itself reads it — `metrics(size)`, `hasGlyph(cp)`, `glyphIdFor(cp)`,
+// `advanceOf(id, size)`, `shape(text, size)` — so a run built here draws
+// through `ctx.drawGlyphs` here (issue #432, over @windowkit/appkit 0.3's
+// fontGlyphForCodepoint / fontGlyphAdvances / fontFallbackFor /
+// fontShapeText / fontWithSize / ctxDrawGlyphs).
 //
 // Index spaces, because two meet here: `lines[].start/end` and
 // `runs[].start/end` are UTF-16 code units (what `rangeBands` in nodes.js
@@ -156,15 +164,199 @@ const GENERIC_FAMILIES = new Set([
   'ui-monospace',
 ]);
 
+/** The size a face is probed at when the question has no size in it. */
+const PROBE_SIZE = 14;
+
+/**
+ * A face — what `match()` and `fallbackFor()` answer — in the shape of
+ * ntk's `Font` as far as a renderer that positions glyphs itself reads it
+ * (ntk docs/text.md#glyph-runs): `metrics`, `hasGlyph`, `glyphIdFor`,
+ * `advanceOf`, `shape`. The face defers size the way ntk's does: `_handle`
+ * is the CTFont at a concrete pixel size, and every member that needs one
+ * asks for it, so one face serves a terminal at 13px and a label at 24px.
+ *
+ * Glyph ids are the font's own indices in both engines, so a run built
+ * from `glyphIdFor` here draws through `ctx.drawGlyphs` here with no
+ * translation; `run.font` is simply this object.
+ */
+export class CocoaFace {
+  /**
+   * @param manager the CocoaFontManager
+   * @param key stable identity (the match key, or the PostScript name of a
+   *   face that arrived by substitution)
+   * @param sizedHandle (size) => CTFont handle for this face at that size
+   */
+  constructor(manager, key, sizedHandle) {
+    this._manager = manager;
+    this.key = key;
+    this._sizedHandle = sizedHandle;
+    this._sized = new Map(); // size -> handle
+    this._covers = new Map(); // code point -> face that covers it | null
+    this._names = null;
+  }
+
+  _handle(size) {
+    const s = Number.isFinite(size) && size > 0 ? size : PROBE_SIZE;
+    let handle = this._sized.get(s);
+    if (handle === undefined) {
+      handle = this._sizedHandle(s) ?? null;
+      this._sized.set(s, handle);
+    }
+    return handle;
+  }
+
+  _name() {
+    if (!this._names) {
+      const m = this._manager._native.fontMetrics(this._handle(PROBE_SIZE));
+      this._names = {
+        familyName: m.familyName ?? '',
+        postscriptName: m.postScriptName ?? '',
+      };
+    }
+    return this._names;
+  }
+
+  /** The family CoreText resolved — `Menlo`, `Apple Color Emoji`. */
+  get familyName() {
+    return this._name().familyName;
+  }
+
+  /** ntk's spelling of the PostScript name, for callers written against
+   *  its `Font`. */
+  get postscriptName() {
+    return this._name().postscriptName;
+  }
+
+  /**
+   * Scaled to a pixel size. CoreText's names (`leading`) and ntk's
+   * (`lineGap`, `lineHeight`) side by side, so a caller written against
+   * either reads a finite line height.
+   */
+  metrics(size) {
+    const m = this._manager._native.fontMetrics(this._handle(size));
+    return {
+      ...m,
+      lineGap: m.leading,
+      lineHeight: m.ascent + m.descent + m.leading,
+    };
+  }
+
+  /**
+   * Coverage. A code point (ntk's contract) or a string — the two forms
+   * `hasGlyph` has been asked in.
+   */
+  hasGlyph(codepoint) {
+    if (typeof codepoint === 'number')
+      return this.glyphIdFor(codepoint) !== null;
+    return this._manager._native.fontHasGlyph(
+      this._handle(PROBE_SIZE),
+      String(codepoint),
+    );
+  }
+
+  /**
+   * Glyph id for a code point, or `null` when this face does not map it —
+   * the lookup twin of `hasGlyph` (ntk#254). A cmap lookup only: no
+   * shaping, so text that needs ligatures or marks goes through `shape()`.
+   */
+  glyphIdFor(codepoint) {
+    if (typeof codepoint !== 'number') return null;
+    return this._manager._native.fontGlyphForCodepoint(
+      this._handle(PROBE_SIZE),
+      codepoint,
+    );
+  }
+
+  /** Nominal (unshaped) horizontal advance of a glyph id, in pixels at
+   *  `size`. */
+  advanceOf(glyphId, size) {
+    const advances = this._manager._native.fontGlyphAdvances(
+      this._handle(size),
+      [glyphId],
+    );
+    return advances[0] ?? 0;
+  }
+
+  /**
+   * Shape a run of text at a pixel size: `{ font, size, direction, width,
+   * glyphs: [{ id, ax, dx, dy }] }`, glyphs in visual order with ntk's
+   * pen contract — `ax` the advance, `dx`/`dy` the drawing offset from the
+   * pen (y up). One CTLine through the typesetter (`fontShapeText`),
+   * which is what a cluster — a base with combining marks, an emoji
+   * sequence, a variation selector — needs and a grid renderer bypasses
+   * for everything else; the terminal shapes a cluster at a time and
+   * caches the run, so the typesetter runs once per distinct cluster.
+   *
+   * One thing ntk's `shape()` never does happens here: CoreText substitutes
+   * a face for characters this one lacks instead of shaping them as
+   * `.notdef`, and a glyph from a substituted run carries that face as
+   * `font` — an extra field ntk's contract ignores and this backend's
+   * `drawGlyphs` honours, so `☺️` in Menlo comes out as the emoji rather
+   * than Menlo's glyph at the emoji font's index.
+   */
+  shape(text, size, opts = {}) {
+    const manager = this._manager;
+    const raw = manager._native.fontShapeText(this._handle(size), String(text));
+    const glyphs = [];
+    let pen = 0;
+    for (const run of raw.runs) {
+      const face = run.font ? manager._faceOfHandle(run.font, size) : null;
+      for (let i = 0; i < run.glyphs.length; i++) {
+        const ax = run.advances[i];
+        const glyph = {
+          id: run.glyphs[i],
+          ax,
+          dx: run.positions[i * 2] - pen,
+          dy: run.positions[i * 2 + 1],
+        };
+        if (face) glyph.font = face;
+        glyphs.push(glyph);
+        pen += ax;
+      }
+    }
+    return {
+      font: this,
+      size,
+      direction: opts.direction ?? 'ltr',
+      width: raw.width,
+      glyphs,
+    };
+  }
+
+  /**
+   * A face that covers `codepoint` when this one does not — this face
+   * itself when it does, `null` when nothing on the system does. Faces the
+   * app loaded first, then CoreText's cascade off this face
+   * (`fontFallbackFor`). Cached per code point.
+   */
+  _coverFor(codepoint) {
+    if (this._covers.has(codepoint)) return this._covers.get(codepoint);
+    const found = this._manager._fallbackFrom(this, codepoint);
+    this._covers.set(codepoint, found);
+    return found;
+  }
+}
+
 export class CocoaFontManager {
-  constructor() {
-    this._native = loadNative();
+  /** @param native the @windowkit/appkit module; the tests hand in a fake */
+  constructor(native = loadNative()) {
+    this._native = native;
     this._fonts = new Map(); // family|weight|italic|size -> handle
     this._faces = new Map(); // family|weight|italic -> face wrapper
     this._registered = new Map(); // lowercase family -> [{cg, weight, italic}]
     this._byKey = new Map(); // ntk Font key -> { cg } | { ps }
     this._sized = new Map(); // face key|size|variations -> CTFont handle
     this._layouts = new Map(); // layout signature -> CocoaTextLayout (LRU)
+    this._faceByPs = new Map(); // PostScript name -> face CoreText chose itself
+  }
+
+  /** A face the app loaded joins every fallback chain: what the faces that
+   *  outlive `_faces.clear()` remembered about coverage is stale. */
+  _forgetCovers() {
+    for (const face of this._faceByPs.values()) face._covers.clear();
+    for (const faces of this._registered.values()) {
+      for (const reg of faces) reg.face?._covers.clear();
+    }
   }
 
   /**
@@ -211,6 +403,7 @@ export class CocoaFontManager {
           this._fonts.clear();
           this._faces.clear();
           this._sized.clear();
+          this._forgetCovers();
         }
       }
     } catch {
@@ -354,8 +547,10 @@ export class CocoaFontManager {
 
   /**
    * A face by family/weight/style — what `textBoxTrim` reads `capHeight`
-   * from. The face defers size, like ntk's: `metrics(size)` answers for a
-   * concrete pixel size.
+   * from and what a terminal builds its glyph runs on. The face defers
+   * size, like ntk's: `metrics(size)` answers for a concrete pixel size,
+   * and the family re-resolves per size through `_font` (SF's optical
+   * sizing is a different face at 13px and at 28px).
    */
   match(family, { weight, style } = {}) {
     const w = numericWeight(weight);
@@ -363,25 +558,116 @@ export class CocoaFontManager {
     const key = `${family}|${w}|${italic}`;
     let face = this._faces.get(key);
     if (!face) {
-      const manager = this;
-      face = {
-        metrics(size) {
-          return manager._native.fontMetrics(
-            manager._font(family, w, italic, size ?? 14),
-          );
-        },
-        hasGlyph(char) {
-          return manager._native.fontHasGlyph(
-            manager._font(family, w, italic, 14),
-            String(char),
-          );
-        },
-      };
+      face = new CocoaFace(this, key, (size) =>
+        this._font(family, w, italic, size),
+      );
       this._faces.set(key, face);
     }
     return face;
   }
 
+  /**
+   * A face that covers `codepoint` when the one for `family` does not, or
+   * `null` when nothing on the system does — ntk's
+   * `FontManager.fallbackFor`, in its order: faces the app loaded first (an
+   * app that ships a font means the one it ships), then CoreText's cascade
+   * off the matched face (`CTFontCreateForString`), the same substitution
+   * `layout()` gets from the typesetter. Cached per family, weight, style
+   * and code point; the matched face itself when it already covers the
+   * code point, so runs group with the base's.
+   */
+  fallbackFor(codepoint, family = 'sans-serif', opts = {}) {
+    if (typeof codepoint !== 'number') {
+      codepoint = String(codepoint).codePointAt(0) ?? -1;
+    }
+    return this.match(family, opts)._coverFor(codepoint);
+  }
+
+  /** `fallbackFor` from a face rather than a family — see `_coverFor`. */
+  _fallbackFrom(base, codepoint) {
+    let found = null;
+    for (const faces of this._registered.values()) {
+      for (const reg of faces) {
+        const face = this._registeredFace(reg);
+        if (face.glyphIdFor(codepoint) !== null) {
+          found = face;
+          break;
+        }
+      }
+      if (found) break;
+    }
+    if (!found) {
+      let text = null;
+      try {
+        text = String.fromCodePoint(codepoint);
+      } catch {
+        text = null; // not a scalar value: nothing covers it
+      }
+      if (text !== null) {
+        const probe = base._handle(PROBE_SIZE);
+        const handle = this._native.fontFallbackFor(probe, text);
+        // the bridge answers the probe handle itself when the face covers
+        // the text: no substitution needed
+        if (handle === probe) found = base;
+        else if (handle) found = this._faceOfHandle(handle, PROBE_SIZE);
+      }
+    }
+    if (
+      found &&
+      found !== base &&
+      found.postscriptName === base.postscriptName
+    ) {
+      found = base;
+    }
+    return found;
+  }
+
+  /** The face of a loaded file, over its own CGFont handle. */
+  _registeredFace(reg) {
+    if (!reg.face) {
+      reg.face = new CocoaFace(this, 'registered', (size) =>
+        this._native.cgFontWithSize(reg.cg, size),
+      );
+      reg.face.key = `registered:${reg.face.postscriptName}`;
+    }
+    return reg.face;
+  }
+
+  /**
+   * The face behind a CTFont handle CoreText chose itself — a fallback, or
+   * a substituted run inside `shape()` — one object per PostScript name, so
+   * runs from either route group together in `drawGlyphs`. The handle seeds
+   * the size it came at; other sizes are copies of it (`fontWithSize`),
+   * which is how a face with no family to re-match by answers
+   * `metrics(size)` and advances everywhere, as itself.
+   */
+  _faceOfHandle(handle, size) {
+    const ps = this._native.fontMetrics(handle).postScriptName;
+    let face = this._faceByPs.get(ps);
+    if (!face) {
+      face = new CocoaFace(this, `ps:${ps}`, (s) =>
+        this._native.fontWithSize(handle, s),
+      );
+      this._faceByPs.set(ps, face);
+    }
+    if (!face._sized.has(size)) face._sized.set(size, handle);
+    return face;
+  }
+
+  /**
+   * The CTFont a glyph run draws with (`CocoaContext2D.drawGlyphs`): a face
+   * of this engine's at the run's size, or an ntk `Font` — `openFont()`'s —
+   * resolved to CoreText from the same bytes, so the glyph ids it shaped
+   * with hold. Null for anything else, and the run is skipped.
+   */
+  _runHandle(font, size) {
+    if (font instanceof CocoaFace) return font._handle(size);
+    if (font && (font.postscriptName || font.path || font.fk)) {
+      return this._faceFont(font, size);
+    }
+    return null;
+  }
+
   /**
    * `loadFont()`'s engine half: register the face with CoreText so the
    * process can match it by family name (with real weight/italic traits —
@@ -444,6 +730,7 @@ export class CocoaFontManager {
     this._faces.clear();
     this._sized.clear();
     this._layouts.clear();
+    this._forgetCovers();
     // `null` on purpose: src/fonts.js keeps the fontkit face it already
     // opened as the handle, which is the one whose metrics apps can read;
     // the registry above is what rendering resolves against.
@@ -500,9 +787,11 @@ export class CocoaFontManager {
       // which is how the fonts app renders exactly the file it opened.
       const face = span.font ?? base.font;
       let handle =
-        face && (face.postscriptName || face.path || face.fk)
-          ? this._faceFont(face, size, variations)
-          : null;
+        face instanceof CocoaFace
+          ? this._withVariations(face._handle(size), variations)
+          : face && (face.postscriptName || face.path || face.fk)
+            ? this._faceFont(face, size, variations)
+            : null;
       handle ??= this._withVariations(
         this._font(
           span.family ?? base.family,

package/src/cocoa/surface.js

@@ -0,0 +1,229 @@
+// An offscreen drawing surface on the Cocoa backend — ntk's `Surface`
+// contract (draw once, composite many, and shift a retained band in place)
+// over one @windowkit/appkit CG bitmap. `react-x11/ntk`'s `Surface` hands
+// out one of these when the app it is given is a Cocoa app (the app's
+// `createSurface` seam, src/cocoa/app.js), so a component allocates its
+// buffer the same way on both backends and names neither:
+//
+//   const surface = new Surface(app, { width, height });   // device pixels
+//   const ctx = surface.getContext('2d');                    // a CocoaContext2D
+//   ctx.fillRect(0, 0, width, height);
+//   surface.copyWithin({ x: 0, y: 0, width, height }, 0, -rowHeight);
+//   windowCtx.drawImage(surface, x, y);                      // one composite
+//
+// What is the same as ntk's: the constructor, `width`/`height`/`format`/
+// `depth`/`bytes`, `getContext`, `render`, `clear`, `copyWithin` down to its
+// clamping (ntk#252 — integer deltas, the band that survives, false when
+// nothing does), `destroy`/`Symbol.dispose`, and `drawImage` taking the
+// surface as a source. What differs is stated here, because this is where
+// it lives:
+//
+// - **One graphics state per surface.** CoreGraphics keeps the CTM, the
+//   clip and the path in the bitmap context itself, where an X connection
+//   keeps them per Picture/GC. So `getContext('2d')` answers the same
+//   context every time — a JS object over that one state, nothing to free,
+//   and `destroy()` on it is a no-op — and `render()` brackets its callback
+//   in save/restore from the identity transform, so a one-shot draw leaves
+//   no residue for the next painter, which is what ntk gets from building a
+//   fresh context per call.
+// - **`format: 'a8'` is not here yet.** Coverage surfaces are what the paint
+//   cache's masks and the shadows use, and both stay on their X path; every
+//   consumer that allocates a surface of its own asks for argb32. Asking
+//   for a8 throws rather than answering a colour surface that would
+//   composite differently.
+// - **No Picture.** `picture()` is X's compositing handle; here a surface
+//   composites through `ctx.drawImage`, and asking for the picture says so.
+// - **Freed on collection.** The bridge frees the bitmap from the handle's
+//   finalizer; `destroy()` drops the handle and refuses further use, so the
+//   memory goes with the next GC rather than on the call.
+//
+// Units are device pixels, like the window's backing store: a caller sizes
+// one from `contentBox()` numbers, which are device pixels already
+// (docs/scale.md). The bridge is told the app's scale so the bitmap carries
+// it — inert for a `drawImage` source, right for a layer's contents.
+import { CocoaContext2D } from './context2d.js';
+
+export class CocoaSurface {
+  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 === 'a8') {
+      throw new Error(
+        "Surface: format 'a8' (a coverage surface) is not on the cocoa " +
+          'backend yet — allocate argb32, which every backend has, and ' +
+          'tint through fillStyle/globalAlpha; track docs/macos.md ' +
+          '"Custom drawing on a layer tree".',
+      );
+    }
+    if (format !== 'argb32') {
+      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 = 32;
+    this._native = app._native;
+    this._fonts = app.fonts ?? null;
+    this._ctx = null;
+    this._destroyed = false;
+    this._surfaceHandle = this._native.createSurface(
+      width,
+      height,
+      app.scale ?? 1,
+    );
+    // a fresh bitmap's contents are the allocator's; a surface that is only
+    // partly drawn must composite nothing where nothing was drawn
+    this.clear();
+  }
+
+  /** bytes of backing storage — what a cache budgets against */
+  get bytes() {
+    return this.width * this.height * 4;
+  }
+
+  /** X's compositing handle, which this backend does not have. */
+  picture() {
+    throw new Error(
+      'Surface: a surface on the cocoa backend has no XRender Picture — ' +
+        'composite it with ctx.drawImage(surface, x, y), which takes a ' +
+        'surface directly on both backends.',
+    );
+  }
+
+  _handle() {
+    if (this._destroyed) {
+      throw new Error(
+        'Surface: destroyed — a context on a destroyed surface cannot ' +
+          'draw; allocate a new Surface and draw into that.',
+      );
+    }
+    return this._surfaceHandle;
+  }
+
+  _context() {
+    if (!this._ctx) {
+      this._ctx = new CocoaContext2D(
+        this._native,
+        () => this._handle(),
+        () => 1,
+      );
+      this._ctx._fonts = this._fonts;
+    }
+    return this._ctx;
+  }
+
+  /**
+   * The 2d context on the bitmap — the same one every time, since the
+   * bitmap has one graphics state (see the header). ntk's contract has the
+   * caller owning it and owing it a `destroy()`; that call is honoured as a
+   * no-op, so a caller written against ntk needs no branch.
+   */
+  getContext(name = '2d') {
+    this._handle();
+    if (name !== '2d') {
+      throw new Error(
+        `Surface: getContext(${JSON.stringify(name)}) — a surface on the ` +
+          "cocoa backend has a '2d' context and nothing else.",
+      );
+    }
+    return this._context();
+  }
+
+  /**
+   * Draw into the surface through a context that starts clean — identity
+   * transform, the fill and line state as they were — and leaves the
+   * surface's state as it found it: the save/restore bracket stands in for
+   * the per-call context ntk builds and destroys.
+   */
+  render(fn) {
+    const ctx = this.getContext('2d');
+    ctx.save();
+    try {
+      ctx.resetTransform();
+      fn(ctx);
+    } finally {
+      ctx.restore();
+    }
+    return this;
+  }
+
+  /** Reset every pixel to fully transparent, whatever transform a live
+   * context holds — the clear is issued from the identity. */
+  clear() {
+    if (this._destroyed) return this;
+    const ctx = this._context();
+    ctx.save();
+    try {
+      ctx.resetTransform();
+      ctx.clearRect(0, 0, this.width, this.height);
+    } finally {
+      ctx.restore();
+    }
+    return this;
+  }
+
+  /**
+   * Scroll the pixels of `src` (surface coordinates, `{x, y, width,
+   * height}`) by (dx, dy) in place: one in-place copy of the band that
+   * survives the shift (the bridge's `scrollSurface`, a memmove per row), in
+   * place of redrawing everything that merely moved. True when the copy was
+   * issued; false means "nothing survives the shift here" and the caller
+   * repaints `src` exactly as it would have without this method.
+   *
+   * ntk#252's contract, clamp for clamp: refused when the delta is
+   * fractional (a sub-pixel shift changes every pixel), when it is zero,
+   * when nothing of `src` survives after clamping to the surface, or on a
+   * destroyed surface. The band is `clamped src ∩ (clamped src + delta)`,
+   * so nothing outside `src` is written; the overlap is safe because the
+   * copy walks rows in the direction that reads before it overwrites.
+   */
+  copyWithin(src, dx, dy) {
+    if (this._destroyed) return false;
+    if (!Number.isInteger(dx) || !Number.isInteger(dy)) return false;
+    if (dx === 0 && dy === 0) return false;
+    const x0 = Math.max(0, Math.floor(src.x));
+    const y0 = Math.max(0, Math.floor(src.y));
+    const x1 = Math.min(this.width, Math.ceil(src.x + src.width));
+    const y1 = Math.min(this.height, Math.ceil(src.y + src.height));
+    const dstX0 = Math.max(x0, x0 + dx);
+    const dstY0 = Math.max(y0, y0 + dy);
+    const dstX1 = Math.min(x1, x1 + dx);
+    const dstY1 = Math.min(y1, y1 + dy);
+    // written as the positive test so a NaN edge (a rect with no numbers
+    // in it) is a refusal too, never a native call with garbage
+    if (!(dstX1 > dstX0 && dstY1 > dstY0)) return false;
+    return Boolean(
+      this._native.scrollSurface(
+        this._surfaceHandle,
+        x0,
+        y0,
+        x1 - x0,
+        y1 - y0,
+        dx,
+        dy,
+      ),
+    );
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._surfaceHandle = null;
+    this._ctx = null;
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}
+
+export default CocoaSurface;

package/src/cocoa/window.js

@@ -321,7 +321,22 @@ export class CocoaWindow {
       dx,
       dy,
     );
-    if (moved) this._dirty = true;
+    if (moved) {
+      this._dirty = true;
+      // The band moved inside the BACK buffer only. After the flip the
+      // other buffer still holds the band where it was, and the catch-up
+      // copy only covers what the flush painted — the strips the shift
+      // exposed — so the next frame would blit a band one frame stale.
+      // Record the shifted rect as painted, and the flip's copy carries it.
+      this.noteFrameDamage([
+        {
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+        },
+      ]);
+    }
     return Boolean(moved);
   }
 

package/src/nodes.js

@@ -486,6 +486,25 @@ function rectsBounds(rects) {
 }
 
 /** Do two rects share any area? Touching edges do not count. */
+/** Does `rect` reach into any of the four `radius`-sized corner squares of
+ * `box` — the only part of a rounded border a translation cannot keep? */
+function cornerSquaresOverlap(box, radius, rect) {
+  const r = Math.min(radius, box.width / 2, box.height / 2);
+  if (!(r > 0)) return false;
+  const corners = [
+    { x: box.x, y: box.y, width: r, height: r },
+    { x: box.x + box.width - r, y: box.y, width: r, height: r },
+    { x: box.x, y: box.y + box.height - r, width: r, height: r },
+    {
+      x: box.x + box.width - r,
+      y: box.y + box.height - r,
+      width: r,
+      height: r,
+    },
+  ];
+  return corners.some((square) => rectsOverlap(square, rect));
+}
+
 function rectsOverlap(a, b) {
   return (
     a.x < b.x + b.width &&
@@ -11127,12 +11146,51 @@ export class WindowNode extends Scrollable(Node) {
     }
     const keep = this._blitKeptDamage(vp, true);
     if (!keep) return;
-    if (!this._scrollBlitSafe(node, vp)) return;
+    // An ancestor's rounded corners reach into the top and bottom rows of
+    // the region (a graph pane inside a rounded card is the common shape):
+    // those rows do not translate, so they leave the blit and get repainted
+    // as bands — the same carve the element does for its own furniture —
+    // and the band that shifts is what is left between them.
+    const bands = this._cornerBands(node, vp);
+    const shifted =
+      bands.top || bands.bottom
+        ? {
+            x: vp.x,
+            y: vp.y + bands.top,
+            width: vp.width,
+            height: vp.height - bands.top - bands.bottom,
+          }
+        : vp;
+    if (shifted.height <= 0 || Math.abs(dy) >= shifted.height) return;
+    if (
+      (shifted.width - Math.abs(dx)) * (shifted.height - Math.abs(dy)) <
+      area * SCROLL_BLIT_MIN_KEEP
+    ) {
+      return;
+    }
+    if (!this._scrollBlitSafe(node, shifted)) return;
     // the element's deltas are already how far the pixels moved, the sense
     // scrollRegion takes (0 + x rather than x: a caller's -0 would survive
     // into request buffers and test comparisons)
-    if (!this.window.scrollRegion({ ...vp }, 0 + dx, 0 + dy)) return;
+    if (!this.window.scrollRegion({ ...shifted }, 0 + dx, 0 + dy)) return;
     let rects = keep;
+    if (bands.top) {
+      rects = addDamageRect(rects, {
+        x: vp.x,
+        y: vp.y,
+        width: vp.width,
+        height: bands.top,
+      });
+    }
+    if (bands.bottom) {
+      rects = addDamageRect(rects, {
+        x: vp.x,
+        y: shifted.y + shifted.height,
+        width: vp.width,
+        height: bands.bottom,
+      });
+    }
+    vp = shifted;
     // The strips the shift exposed, on the sides the pixels came from. The
     // horizontal one takes the full width and the vertical one takes what
     // is left, so a diagonal shift claims two rects that do not overlap —
@@ -11157,6 +11215,28 @@ export class WindowNode extends Scrollable(Node) {
     this._damage = rects;
   }
 
+  /**
+   * How many rows at the top and at the bottom of `vp` an ancestor's rounded
+   * corners reach into — the rows an element blit has to leave behind and
+   * repaint, so that what shifts stays clear of every corner square
+   * (`_scrollBlitSafe`). Whole pixels, and zero when no corner reaches in.
+   */
+  _cornerBands(node, vp) {
+    let top = 0;
+    let bottom = 0;
+    for (let n = node.parent; n && n !== this; n = n.parent) {
+      const radius = n.style?.borderRadius ?? 0;
+      if (!(radius > 0) || !n.abs) continue;
+      if (!cornerSquaresOverlap(n.abs, radius, vp)) continue;
+      top = Math.max(top, Math.ceil(n.abs.y + radius - vp.y));
+      bottom = Math.max(
+        bottom,
+        Math.ceil(vp.y + vp.height - (n.abs.y + n.abs.height - radius)),
+      );
+    }
+    return { top: Math.max(0, top), bottom: Math.max(0, bottom) };
+  }
+
   /**
    * May the viewport's pixels be moved wholesale? Only if every pixel in it
    * belongs to the scrolled content (or to a plain solid fill behind it):
@@ -11186,14 +11266,18 @@ export class WindowNode extends Scrollable(Node) {
             child.style ?? EMPTY_STYLE,
             child.direction,
           );
-          const inset = Math.max(
-            bw.top,
-            bw.right,
-            bw.bottom,
-            bw.left,
-            child.style?.borderRadius ?? 0,
-          );
-          if (inset > 0 && !rectContains(insetRect(child.abs, inset), vp)) {
+          const ring = Math.max(bw.top, bw.right, bw.bottom, bw.left);
+          if (ring > 0 && !rectContains(insetRect(child.abs, ring), vp)) {
+            return false;
+          }
+          // A rounded corner is not a ring: the arc lives in the four
+          // radius-sized squares at the corners, and the straight run of
+          // the edge between them is the border ring already excluded
+          // above. A viewport that reaches the edge but stays clear of the
+          // squares — an element that carved the corner rows into bands it
+          // repaints (`_cornerBands`) — is translation-safe.
+          const radius = child.style?.borderRadius ?? 0;
+          if (radius > 0 && cornerSquaresOverlap(child.abs, radius, vp)) {
             return false;
           }
           if (typeof child._scrollbars === 'function') {

package/src/ntk.d.ts

@@ -16,7 +16,13 @@
  * than a hand-written mirror that would drift out of date silently. The
  * named exports are the ones an extension actually reaches for; anything
  * else ntk has is still there at runtime.
+ *
+ * `Surface` is the exception, typed in full: it is react-x11's own class,
+ * answering ntk's pixmap on an X connection and a CG bitmap on the cocoa
+ * backend, so its shape is this package's to declare.
  */
+import type { Context2D } from './node.js';
+
 export const createClient: (
   options?: Record<string, unknown>,
 ) => Promise<unknown>;
@@ -26,12 +32,65 @@ export const Clipboard: new (...args: unknown[]) => unknown;
 export const Path2D: new (...args: unknown[]) => unknown;
 export const Image: new (...args: unknown[]) => unknown;
 export const Pixmap: new (...args: unknown[]) => unknown;
+
+/** What `new Surface(app, options)` takes: a size in device pixels. */
+export interface SurfaceOptions {
+  width: number;
+  height: number;
+  /**
+   * `'argb32'` (the default) on every backend. `'a8'`, a coverage surface
+   * that composites as a mask for the fill style, is X11-only today and
+   * throws on the cocoa backend.
+   */
+  format?: 'argb32' | 'a8';
+}
+
+/** A rectangle in surface coordinates — what `copyWithin` shifts. */
+export interface SurfaceRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
 /**
- * Draw once, composite many — and, for an element that scrolls a retained
- * buffer, `copyWithin(src, dx, dy)` shifts the surviving band server-side.
- * See [extending.md](../docs/extending.md).
+ * An offscreen surface: draw once, composite many — and, for an element
+ * that scrolls a retained buffer, `copyWithin(src, dx, dy)` shifts the
+ * surviving band in place. On an X connection it is ntk's pixmap and
+ * Picture; on the cocoa backend a CG bitmap; the same object shape either
+ * way, and `ctx.drawImage(surface, …)` takes it as a source on both. See
+ * [extending.md](../docs/extending.md) "Scrolling the pixels, not just the
+ * offset".
  */
-export const Surface: new (...args: unknown[]) => unknown;
+export interface Surface {
+  readonly app: unknown;
+  readonly width: number;
+  readonly height: number;
+  readonly format: 'argb32' | 'a8';
+  readonly depth: 8 | 32;
+  /** Bytes of backing storage — what a cache budgets against. */
+  readonly bytes: number;
+  /**
+   * A 2d context on the surface. The caller owns it and owes it a
+   * `destroy()` — real on X11 (a GC and a Picture), a no-op on cocoa, where
+   * a surface has one context for its whole life.
+   */
+  getContext(name: '2d', ...args: unknown[]): Context2D;
+  /** Draw through a context that exists for the call. */
+  render(fn: (ctx: Context2D) => void): this;
+  /** Reset every pixel to fully transparent. */
+  clear(): this;
+  /**
+   * Shift `src` by a whole-pixel delta in place; true when a band survived
+   * the shift and was copied, false when the caller should repaint `src`.
+   */
+  copyWithin(src: SurfaceRect, dx: number, dy: number): boolean;
+  /** X11 only — the server-side Picture, for `<image picture>`. Throws on the cocoa backend. */
+  picture(app?: unknown): unknown;
+  destroy(): void;
+  [Symbol.dispose](): void;
+}
+export const Surface: new (app: unknown, options: SurfaceOptions) => Surface;
 /** `code` values on a failed GL setup — see `<glarea onError>`. */
 export const GLXError: {
   NO_EXTENSION: 'GLX_NO_EXTENSION';

package/src/ntk.js

@@ -21,5 +21,35 @@
 // for one — they were reachable but never declared — wants
 // `@react-x11/components` (`<Markdown>`, `<Formula>`). `SvgView` is still
 // here; a drawing is not a document.
+//
+// One name is not a plain re-export. `Surface` below asks the app it is
+// handed for the implementation, because ntk's own is a pixmap and a
+// Picture — an X connection's — and a component allocates its buffer
+// without knowing which backend it was mounted on. This subpath is where a
+// drawing-adjacent name gets its backend-neutral answer; the X-only names
+// (`createClient`, `Pixmap`, `Picture`, `XEmbedSocket`) stay X-only.
+import { Surface as NtkSurface } from 'ntk';
+
 export * from 'ntk';
 export { default } from 'ntk';
+
+/**
+ * ntk's offscreen `Surface`, on whichever backend `app` is.
+ *
+ * An app that makes its own surfaces answers `createSurface(options)` —
+ * the Cocoa app does, over a CG bitmap (src/cocoa/surface.js) — and an ntk
+ * connection has no such method and gets ntk's pixmap. The result is
+ * whichever implementation answered, not an instance of this class: the
+ * contract is the shape — `width`/`height`, `getContext('2d')`, `render`,
+ * `clear`, `copyWithin`, `destroy`, and `ctx.drawImage(surface, …)` —
+ * (docs/extending.md "Scrolling the pixels, not just the offset"), and
+ * nothing needs `instanceof`.
+ */
+export class Surface {
+  constructor(app, options) {
+    if (typeof app?.createSurface === 'function') {
+      return app.createSurface(options);
+    }
+    return new NtkSurface(app, options);
+  }
+}

package/src/textselection.js

@@ -169,7 +169,7 @@ export class TextSelection {
 
   press(ev) {
     if (ev.button !== 1) return;
-    const at = this.positionAt(ev.x, ev.y);
+    const at = this.positionAt(...this.devicePoint(ev));
     if (!at) return;
     this.granularity =
       ev.detail >= 3 ? 'block' : ev.detail === 2 ? 'word' : 'char';
@@ -190,7 +190,7 @@ export class TextSelection {
 
   drag(ev) {
     if (!this.dragging) return;
-    const at = this.positionAt(ev.x, ev.y);
+    const at = this.positionAt(...this.devicePoint(ev));
     if (!at) return;
     this.focus = at;
     this.apply();
@@ -221,9 +221,27 @@ export class TextSelection {
     }
   }
 
+  /**
+   * The pointer in the space `abs` and the four accessors are in — device
+   * pixels (docs/scale.md). A synthetic event's `x`/`y` are logical, so on
+   * a 2x panel they name a point half as far from the window's origin as the
+   * pointer is: a press landed on the wrong character and a drag stopped
+   * short at half its distance. The X event underneath already carries the
+   * device numbers; an event synthesized without one is multiplied up, the
+   * way every other pointer consumer in nodes.js does it.
+   */
+  devicePoint(ev) {
+    const scale = this.node.scale > 0 ? this.node.scale : 1;
+    return [
+      ev.nativeEvent?.x ?? ev.x * scale,
+      ev.nativeEvent?.y ?? ev.y * scale,
+    ];
+  }
+
   // --- the selection itself ----------------------------------------------
 
-  /** The participant and index nearest a point in window coordinates. */
+  /** The participant and index nearest a point in window coordinates —
+   * device pixels, the unit `abs` and `textIndexAt` speak. */
   positionAt(x, y) {
     let best = null;
     let bestScore = Infinity;