react-x11 2.4.0 → 2.6.0

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/paintcache.js

@@ -22,6 +22,14 @@
 // Multi-colour drawings bake their colours in, which is right, because those
 // colours belong to the drawing. `SvgView.paintKind` decides which is which.
 //
+// Coverage needs a backend that composites a mask through a colour, which
+// X Render does and the Cocoa backend's surfaces do not (src/cocoa/
+// surface.js — no `a8`). There a mono drawing is cached as argb32 with its
+// colour in the key: one entry per colour it is seen in rather than one for
+// all of them, which is still one render per colour instead of one per
+// cell per frame. A coverage-only plan — a blurred shadow, whose blur is a
+// pass over the mask — stays live on that backend.
+//
 // ## Self-limiting, on purpose
 //
 // X gives no back-pressure: the first sign of overspending is `BadAlloc` on
@@ -36,6 +44,12 @@
 // `typeof wnd?.scrollRegion !== 'function'` guard for ntk without #139.
 import * as ntk from 'ntk';
 
+// The surface this cache draws into is `react-x11/ntk`'s: ntk's pixmap on
+// an X connection, the app's own (`app.createSurface`) on a backend that
+// makes them — the Cocoa backend's CG bitmap. One import, so the cache
+// names neither.
+import { Surface } from './ntk.js';
+
 /** Stale pixels are undebuggable, and every other optimization here has an
  * escape hatch — see NO_SCROLL_BLIT. */
 const DISABLED = process.env.REACT_X11_NO_PAINT_CACHE === '1';
@@ -145,6 +159,9 @@ export class PaintCache {
     this.app = app;
     this.budget = budget;
     this.verify = verify;
+    /** whether an `a8` entry can be painted through a colour here — X
+     * Render composites a mask through the fill; nothing else does yet */
+    this.coverage = Boolean(app?.display?.Render);
     /** key -> entry. Map iteration is insertion order, so re-inserting on
      * access makes this an LRU list for free — same trick as getGlyphPage. */
     this.entries = new Map();
@@ -193,7 +210,7 @@ export class PaintCache {
     return this.drawing(ctx, {
       ...plan,
       label: `<${node.kind}>`,
-      draw: (sctx, box) => node.paintCached(sctx, box),
+      draw: (sctx, box, ink) => node.paintCached(sctx, box, ink),
       live: () => node.paintContent(ctx),
     });
   }
@@ -211,9 +228,22 @@ export class PaintCache {
    *
    * `maxPixels` overrides the per-item cap for a caller whose drawing is
    * legitimately box-sized rather than icon-sized.
+   *
+   * `draw` is handed the ink a mono drawing paints in as its third
+   * argument: white into a coverage surface, where only the alpha survives
+   * and the tint arrives at blit time, and the tint itself on a backend
+   * without coverage, where the entry bakes its colour and carries it in
+   * the key (`_bakeTint`).
    */
   drawing(ctx, plan) {
     if (!isDeviceSpace(ctx)) return plan.live(ctx);
+    if (plan.format === 'a8' && !this.coverage) {
+      // A plan whose `after` pass works on the mask — a blurred shadow —
+      // has no argb32 equivalent: it paints live, which is what the frame
+      // owed with no cache at all.
+      if (plan.after) return plan.live(ctx);
+      plan = this._bakeTint(plan);
+    }
 
     if (plan.width * plan.height > (plan.maxPixels ?? MAX_ITEM_PIXELS)) {
       this.stats.tooBig++;
@@ -254,9 +284,30 @@ export class PaintCache {
     return this._blit(ctx, entry, plan);
   }
 
+  /**
+   * A coverage plan on a backend that cannot composite coverage, as an
+   * argb32 plan that paints its tint: the same pixels, one entry per colour
+   * instead of one per drawing.
+   */
+  _bakeTint(plan) {
+    const tint = plan.tint;
+    return {
+      ...plan,
+      format: 'argb32',
+      key: `${plan.key}|ink:${tint}`,
+      draw: (sctx, box) => plan.draw(sctx, box, tint),
+    };
+  }
+
+  /** The colour a drawing paints in: white into coverage, the tint into a
+   * baked entry, and nothing a multi-colour drawing reads. */
+  static inkFor(plan) {
+    return plan.format === 'a8' ? '#ffffff' : (plan.tint ?? '#ffffff');
+  }
+
   _render(plan) {
     try {
-      const surface = new ntk.Surface(this.app, {
+      const surface = new Surface(this.app, {
         width: plan.width,
         height: plan.height,
         format: plan.format,
@@ -264,7 +315,11 @@ export class PaintCache {
       const box = { x: 0, y: 0, width: plan.width, height: plan.height };
       const state = { digest: 0x811c9dc5 };
       surface.render((sctx) =>
-        plan.draw(this.verify ? recordingContext(sctx, state) : sctx, box),
+        plan.draw(
+          this.verify ? recordingContext(sctx, state) : sctx,
+          box,
+          PaintCache.inkFor(plan),
+        ),
       );
       // `after` may hand back a *different* surface than it was given — a
       // blurred shadow bakes its convolution into a second one and destroys
@@ -310,18 +365,17 @@ export class PaintCache {
     const state = { digest: 0x811c9dc5 };
     let scratch = null;
     try {
-      scratch = new ntk.Surface(this.app, {
+      scratch = new Surface(this.app, {
         width: plan.width,
         height: plan.height,
         format: plan.format,
       });
       scratch.render((sctx) =>
-        plan.draw(recordingContext(sctx, state), {
-          x: 0,
-          y: 0,
-          width: plan.width,
-          height: plan.height,
-        }),
+        plan.draw(
+          recordingContext(sctx, state),
+          { x: 0, y: 0, width: plan.width, height: plan.height },
+          PaintCache.inkFor(plan),
+        ),
       );
     } catch {
       return; // verification is best-effort; never break a frame over it
@@ -365,6 +419,12 @@ export class PaintCache {
  * cannot, and the answer is simply that nothing is cached. */
 export const paintCacheSupported = () => typeof ntk.Surface === 'function';
 
+/** Whether `app` can make an offscreen surface at all: an X connection
+ * with the Render extension (ntk's pixmap surface), or a backend with a
+ * surface of its own — the Cocoa app's `createSurface` (docs/macos.md). */
+const canMakeSurfaces = (app) =>
+  Boolean(app?.display?.Render) || typeof app?.createSurface === 'function';
+
 /**
  * The cache for an app, created on first use. Null when caching is off, when
  * the installed ntk is too old, or when the app cannot make surfaces — the
@@ -372,6 +432,6 @@ export const paintCacheSupported = () => typeof ntk.Surface === 'function';
  * there must paint live.
  */
 export function paintCacheFor(app) {
-  if (DISABLED || !paintCacheSupported() || !app?.display?.Render) return null;
+  if (DISABLED || !paintCacheSupported() || !canMakeSurfaces(app)) return null;
   return (app._paintCache ??= new PaintCache(app));
 }

package/src/svgnodes.js

@@ -294,13 +294,14 @@ export class SvgNode extends Node {
     };
   }
 
-  paintCached(ctx, box) {
+  paintCached(ctx, box, ink = '#ffffff') {
     const view = this._ensureView();
     if (!view) return;
     // Into a coverage surface, only the alpha of a paint survives, and the
-    // tint arrives at blit time — so any opaque colour renders the same mask.
+    // tint arrives at blit time — so any opaque colour renders the same
+    // mask, and the cache says white then, or the tint where it bakes colour.
     view.draw(ctx, box.x, box.y, box.width, box.height, {
-      color: view.paintKind === 'mono' ? '#ffffff' : this._currentColor(),
+      color: view.paintKind === 'mono' ? ink : this._currentColor(),
     });
   }
 }

package/src/types/elements.d.ts

@@ -188,6 +188,19 @@ export interface DrawnProps<T = DrawnNode>
     SelectionProps<T>,
     EventHandlers<T> {
   ref?: Ref<T>;
+  /**
+   * Zoom this subtree, CSS `zoom` rather than a transform: every length
+   * under here — and this element's *own* style — is multiplied by it, so
+   * `scale={2}` is a card twice the size with text shaped at twice the size
+   * inside it, not a 1x picture stretched. Nested props multiply, and the
+   * display scale is the floor they multiply
+   * ([scale.md](scale.md#a-subtree-of-its-own)).
+   *
+   * A positive number; leaving it out means 1. `<window>` and `<popup>`
+   * take no `scale`: a real X window is its own root, so a menu opened from
+   * a zoomed card comes up at the app's own size.
+   */
+  scale?: number;
 }
 
 /**