react-x11 2.4.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

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

@@ -279,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 = [

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/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);
+  }
+}