react-x11 2.2.1 → 2.3.0

package/src/cocoa/glarea.js

@@ -0,0 +1,321 @@
+// <glarea> on the Cocoa backend: GL into a CALayer, no X server anywhere.
+//
+// The shape mirrors the X11 direct path (ntk's renderingcontext_cgl) with
+// the XQuartz-specific half swapped out: the same x11-dri CGL context and
+// WebGL-shaped `gl` table, but instead of attaching to a window surface the
+// X server exported, frames render into IOSurface-backed framebuffers
+// (x11-dri `createTarget`) and present by handing the IOSurface's process-
+// global id to the area's own sublayer (`setLayerContentsIOSurface`). Two
+// targets alternate, like any swapchain; the WindowServer composites.
+//
+// What GlAreaNode needs from us is the child-"window" contract it already
+// speaks (src/glnodes.js): `createWindow({ parent, … })` answering an
+// object with `getContext('opengl', config)`, `setState(rect)`, `map()`,
+// `destroy()`, `requestAnimationFrame`. On X11 that child is a real X
+// window stacked above the parent's drawing; here it is a sublayer of the
+// window's root layer with a high zPosition — the same "GL sits above the
+// 2D" semantics, by the same mechanism the platform gives us.
+//
+// ## The API ladder
+//
+// `chooseGLConfig(spec)` honours `spec.api` (the `<glarea glx>` prop):
+// `'auto'` and `'gl'` are this file — CGL, OpenGL 4.1 core on Metal, the
+// zero-dependency rung that exists on every Mac. `'gles'` (ANGLE on Metal)
+// and `'webgpu'` are named rungs that answer with what they would take,
+// so the ladder is visible before it is built. Policy decides, the machine
+// answers — the same rule the GL policy follows everywhere else.
+
+const RUNGS = ['auto', 'gl'];
+const KNOWN_RUNGS = ['auto', 'gl', 'gles', 'webgpu'];
+
+let driPromise = null;
+function loadDri() {
+  if (!driPromise) {
+    driPromise = import('x11-dri').then((m) => m.default ?? m);
+  }
+  return driPromise;
+}
+
+/**
+ * The app-wide GL runtime: one CGL context shared by every `<glarea>`, the
+ * way the X11 direct backend shares one GPU context per connection. Created
+ * lazily by the first `chooseGLConfig` and kept on the app.
+ */
+export class CocoaGLRuntime {
+  constructor(dri) {
+    this.dri = dri;
+    this.gl = dri.gl;
+    this.ctx = new dri.apple.Context({
+      alphaSize: 8,
+      depthSize: 24,
+      stencilSize: 8,
+      doubleBuffer: false,
+      profile: 'core',
+    });
+    this.ctx.makeCurrent();
+    this.glVersion = this.ctx.glVersion;
+    // frame pacing: how long a swap closes the canRender gate for. macOS
+    // answers directly — XQuartz's RandR never could (x11-dri >= 0.6).
+    const hz = dri.apple.refreshRate?.();
+    this.frameInterval = hz ? 1000 / hz : 1000 / 60;
+  }
+
+  destroy() {
+    this.ctx.destroy();
+  }
+}
+
+/** Resolve the app's runtime, throwing the reason when there is none. */
+export async function cocoaGLConfig(app, spec) {
+  const mode = app.glPolicy?.mode ?? 'auto';
+  if (mode === 'off') {
+    const err = new Error(
+      "glPolicy is 'off' on this connection, so no GL context is created at all",
+    );
+    err.code = 'GL_DISABLED';
+    throw err;
+  }
+  if (mode === 'indirect') {
+    const err = new Error(
+      "glPolicy is 'indirect', which is GLX — the Cocoa backend has no X " +
+        "server to speak it to. Use 'auto' (the default here) or 'direct'.",
+    );
+    err.code = 'GL_POLICY_INDIRECT';
+    throw err;
+  }
+  const api = spec?.api ?? 'auto';
+  if (!RUNGS.includes(api)) {
+    const err = new Error(
+      KNOWN_RUNGS.includes(api)
+        ? `<glarea> api '${api}' is a named rung this backend has not ` +
+            `built yet — today's rungs are ${RUNGS.join(', ')} (CGL, OpenGL ` +
+            `4.1 core on Metal). 'gles' arrives with vendored ANGLE, ` +
+            `'webgpu' with a wgpu bridge.`
+        : `<glarea> api '${api}' is not a rung — expected one of ` +
+            `${KNOWN_RUNGS.join(', ')}.`,
+    );
+    err.code = 'GL_API_UNAVAILABLE';
+    throw err;
+  }
+  await resolveCocoaGLRuntime(app);
+  return { backend: 'direct', api: 'gl' };
+}
+
+/**
+ * One runtime per app, one probe per app: chooseGLConfig and
+ * `app.glCapabilities()` share this promise, so two `<glarea>`s mounting in
+ * the same commit cannot race two contexts into existence, and the settled
+ * answer lands in `_glCapsResolved` either way — the property
+ * `useSupports('shaders')` reads (src/glbackend.js).
+ */
+export function resolveCocoaGLRuntime(app) {
+  if (!app._cocoaGLPromise) {
+    app._cocoaGLPromise = loadDri()
+      .then((dri) => {
+        app._cocoaGL = new CocoaGLRuntime(dri);
+        app._glCapsResolved = { direct: true };
+        return app._cocoaGL;
+      })
+      .catch((cause) => {
+        const err = new Error(
+          '<glarea> on the Cocoa backend needs the x11-dri addon (the ' +
+            'GPU/GL half); it did not load: ' +
+            cause.message,
+        );
+        err.code = 'GL_NO_ADDON';
+        app._glCapsResolved = { direct: false, reason: err };
+        throw err;
+      });
+  }
+  return app._cocoaGLPromise;
+}
+
+/**
+ * The child-"window" a GlAreaNode owns here: one sublayer of the owning
+ * window's root layer, above everything the 2D presenters put there.
+ */
+export class CocoaGLArea {
+  constructor(app, options) {
+    this.app = app;
+    this.parent = options.parent;
+    this._native = app._native;
+    this.scale = this.parent.scale ?? app.scale ?? 1;
+    this.destroyed = false;
+    this._reactX11Node = null;
+    this.onWheel = options.onWheel ?? null;
+    this.layer = this._native.createLayer();
+    this._native.addSublayer(this.parent._layer, this.layer);
+    this.rect = null;
+    this.setState({
+      x: options.x ?? 0,
+      y: options.y ?? 0,
+      width: options.width ?? 1,
+      height: options.height ?? 1,
+    });
+    this._context = null;
+    this._listeners = new Map();
+  }
+
+  /** Geometry in device px, the unit GlAreaNode's rects are in. */
+  setState(rect) {
+    if (this.destroyed) return;
+    this.rect = rect;
+    const s = this.scale;
+    this._native.setLayerProps(this.layer, {
+      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+      // above both presenters' content: the surface presenter's contents
+      // live on the root layer itself, the layers presenter's visuals top
+      // out at paintOrder zPositions — this clears either.
+      zPosition: 1e7,
+      // GL renders bottom-up and an IOSurface displays row 0 at the top;
+      // mirroring the layer is the flip, applied where the compositor is
+      // already transforming instead of in anyone's shader.
+      transform: { scaleY: -1 },
+      hidden: false,
+    });
+    this._context?._resized(rect.width, rect.height);
+  }
+
+  get width() {
+    return this.rect?.width ?? 0;
+  }
+
+  get height() {
+    return this.rect?.height ?? 0;
+  }
+
+  move(x, y) {
+    this.setState({ ...this.rect, x, y });
+  }
+
+  resize(width, height) {
+    this.setState({ ...this.rect, width, height });
+  }
+
+  map() {
+    if (!this.destroyed) {
+      this._native.setLayerProps(this.layer, { hidden: false });
+    }
+  }
+
+  on(name, fn) {
+    let set = this._listeners.get(name);
+    if (!set) this._listeners.set(name, (set = new Set()));
+    set.add(fn);
+  }
+
+  emit(name, ev) {
+    for (const fn of this._listeners.get(name) ?? []) fn(ev);
+  }
+
+  requestAnimationFrame(cb) {
+    return this.parent.requestAnimationFrame(cb);
+  }
+
+  getContext(kind, config) {
+    if (kind !== 'opengl' || this.destroyed) return null;
+    if (!this._context) {
+      this._context = createGLAreaContext(this.app._cocoaGL, this, config);
+    }
+    return this._context;
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this._context?._destroy();
+    this._context = null;
+    this._native.removeFromSuperlayer(this.layer);
+  }
+}
+
+/**
+ * The `gl` a `<glarea>`'s onDraw receives: the shared WebGL-shaped table
+ * with this area's swapchain behind it. Prototype-delegates to the table so
+ * every entry point is present without copying; the own properties are the
+ * per-area contract GlAreaNode drives (`backend`, `ready`, `makeCurrent`,
+ * `SwapBuffers`, `canRender`, `onFrameAvailable`).
+ */
+function createGLAreaContext(runtime, area, config) {
+  const native = area._native;
+  const ctx = Object.create(runtime.gl);
+  let front = null;
+  let back = null;
+  let width = 0;
+  let height = 0;
+  let gateClosed = false;
+  let gateTimer = null;
+  let destroyed = false;
+
+  const ensureTargets = () => {
+    const w = Math.max(1, area.rect?.width ?? 1);
+    const h = Math.max(1, area.rect?.height ?? 1);
+    if (front && width === w && height === h) return;
+    front?.destroy();
+    back?.destroy();
+    front = runtime.ctx.createTarget(w, h);
+    back = runtime.ctx.createTarget(w, h);
+    width = w;
+    height = h;
+  };
+
+  ctx.backend = 'direct';
+  ctx.config = config;
+  ctx.glVersion = runtime.glVersion;
+  ctx.ready = Promise.resolve();
+  ctx.onFrameAvailable = null;
+
+  // On the direct backend every buffer may still be held by the display;
+  // here the WindowServer reads the front IOSurface while we draw the back
+  // one, so the honest gate is one display period per swap — the same
+  // timer-reopened gate the XQuartz CGL flavor uses (no backpressure
+  // exists on either).
+  ctx.canRender = () => !destroyed && !gateClosed;
+
+  ctx.makeCurrent = () => {
+    if (destroyed) return;
+    ensureTargets();
+    runtime.ctx.bindTarget(back);
+  };
+
+  // WebGL's "null means the default framebuffer" — and this surface's
+  // default is the back target's FBO, not GL's framebuffer zero, which on
+  // a swapchain like this is nothing at all. A scene that renders through
+  // its own FBO and unbinds at the end (the SSAA pattern) lands back here.
+  ctx.bindFramebuffer = (target, fb) => {
+    runtime.gl.bindFramebuffer(target, fb == null ? (back?.fbo ?? 0) : fb);
+  };
+
+  ctx.SwapBuffers = () => {
+    if (destroyed || !back) return;
+    runtime.gl.flush();
+    native.setLayerContentsIOSurface(area.layer, back.iosurfaceId);
+    const shown = back;
+    back = front;
+    front = shown;
+    gateClosed = true;
+    gateTimer = setTimeout(() => {
+      gateTimer = null;
+      gateClosed = false;
+      ctx.onFrameAvailable?.();
+    }, runtime.frameInterval);
+    // the timer must not hold the process open for an idle scene
+    gateTimer.unref?.();
+  };
+
+  ctx._resized = () => {
+    // targets are rebuilt lazily on the next makeCurrent, so a resize
+    // storm costs two allocations per drawn frame, not per notify
+  };
+
+  ctx._destroy = () => {
+    if (destroyed) return;
+    destroyed = true;
+    if (gateTimer) clearTimeout(gateTimer);
+    front?.destroy();
+    back?.destroy();
+    front = back = null;
+  };
+
+  return ctx;
+}

package/src/cocoa/globalmenu.js

@@ -0,0 +1,149 @@
+// The macOS menu bar as a global-menu export (docs/macos.md §Menus).
+//
+// The Linux global menu was built for exactly this moment: the item
+// vocabulary is data, and the pure snapshot/IdAllocator machinery in
+// dbusmenu.js produces stable ids with no D-Bus in sight. This adapter
+// consumes precisely that — same owner shape as GlobalMenuExport
+// (start/stop/update/onChange), so `useGlobalMenu` swaps the transport and
+// nothing above it can tell. Where the D-Bus export must wait for a
+// registrar to answer, the menu bar is a platform constant: `onChange(true)`
+// fires as soon as the menu is installed, and `MenuBar`'s drawn fallback
+// never renders here.
+//
+// Activation comes back as a backend event carrying the item's id —
+// AppKit's menu tracking is a modal loop, and those already deliver into JS
+// on this backend (live resize does) — routed by the app to the active
+// export, which runs the item's own onSelect: the same contract the
+// registrar path has.
+import { IdAllocator, ROOT_ID, snapshot } from '../dbusmenu.js';
+
+// The synthesized app menu's Quit item. Negative on purpose: IdAllocator
+// only counts up from ROOT_ID, so no real item can collide with it.
+const QUIT_ID = -2;
+
+// NSEventModifierFlags. No Control here on purpose: a cross-platform
+// shortcut's primary modifier maps to Command, not the Mac's own ⌃.
+const FLAG_SHIFT = 1 << 17;
+const FLAG_OPTION = 1 << 19;
+const FLAG_COMMAND = 1 << 20;
+
+/**
+ * One dbusmenu chord — `[['Control', 'z']]` — as NSMenu key equivalents.
+ * `Control` maps to Command deliberately: a cross-platform app writes its
+ * shortcuts in the primary modifier, and on macOS the primary modifier is
+ * ⌘ — a literal mapping would put every accelerator on a modifier no Mac
+ * user presses. Multi-chord sequences and non-character keys have no
+ * NSMenu spelling and are dropped (the shortcut still works — the app's
+ * own key handling is untouched; only the menu's hint goes unshown).
+ */
+function keyEquivalent(shortcut) {
+  const chord = Array.isArray(shortcut) ? shortcut[0] : null;
+  if (!Array.isArray(chord) || shortcut.length !== 1) return null;
+  let modifiers = 0;
+  let key = null;
+  for (const part of chord) {
+    if (part === 'Control' || part === 'Super') modifiers |= FLAG_COMMAND;
+    else if (part === 'Shift') modifiers |= FLAG_SHIFT;
+    else if (part === 'Alt') modifiers |= FLAG_OPTION;
+    else key = part;
+  }
+  if (typeof key !== 'string' || [...key].length !== 1) return null;
+  return { key: key.toLowerCase(), modifiers: modifiers || FLAG_COMMAND };
+}
+
+export class CocoaGlobalMenuExport {
+  constructor(app, { getMenus, onSelect, onAboutToShow, target, onChange }) {
+    this.app = app;
+    this.getMenus = getMenus;
+    this.onSelect = onSelect;
+    this.onAboutToShow = onAboutToShow;
+    this.target = target;
+    this.onChange = onChange;
+    this.alloc = new IdAllocator();
+    this.nodes = null;
+    this.exported = false;
+  }
+
+  async start() {
+    this.app._registerGlobalMenu(this);
+    this.update(this.getMenus?.() ?? []);
+    this.exported = true;
+    this.onChange?.(true);
+  }
+
+  async stop() {
+    this.exported = false;
+    this.app._unregisterGlobalMenu(this);
+    this.onChange?.(false);
+  }
+
+  update(menus) {
+    this.nodes = snapshot(menus ?? [], this.alloc);
+    if (this.app._activeGlobalMenu === this) this._install();
+  }
+
+  _install() {
+    this.app._native.setMainMenu(this._spec());
+  }
+
+  /**
+   * The snapshot as the bridge's menu spec. The app menu is synthesized in
+   * front — macOS requires the first menu and shows the process name on it
+   * regardless of title — carrying Quit, which routes back through
+   * `activate` like every real item.
+   */
+  _spec() {
+    const itemsOf = (ids) =>
+      ids.map((id) => {
+        const node = this.nodes.get(id);
+        const props = node.props;
+        const out = { id };
+        if (props.type === 'separator') {
+          out.separator = true;
+          if (props.visible === false) out.hidden = true;
+          return out;
+        }
+        out.title = String(props.label ?? '');
+        if (props.enabled === false) out.enabled = false;
+        if (props.visible === false) out.hidden = true;
+        if (props['toggle-state'] === 1) out.checked = true;
+        // the serialisable icon pair (menuitem.js): the name is read in
+        // the platform's icon theme — SF Symbols here, freedesktop on a
+        // Linux panel — and the bytes are the literal-pixel fallback
+        if (props['icon-name']) out.iconName = props['icon-name'];
+        if (props['icon-data']) out.iconData = props['icon-data'];
+        const key = keyEquivalent(props.shortcut);
+        if (key) {
+          out.key = key.key;
+          out.modifiers = key.modifiers;
+        }
+        if (node.childIds.length) out.items = itemsOf(node.childIds);
+        return out;
+      });
+    const root = this.nodes.get(ROOT_ID);
+    const menus = itemsOf(root.childIds).map((menu) => ({
+      title: menu.title ?? '',
+      items: menu.items ?? [],
+    }));
+    return [
+      {
+        title: 'App',
+        items: [{ id: QUIT_ID, title: 'Quit', key: 'q' }],
+      },
+      ...menus,
+    ];
+  }
+
+  /** A backend menu-activate event landed on this export. */
+  activate(id) {
+    if (id === QUIT_ID) {
+      // the same route the close button takes: the app decides what
+      // closing means, exactly as it would for the red light
+      const wnd = this.target?.window ?? [...this.app._windows.values()][0];
+      wnd?.emit('close', { preventDefault() {} });
+      return;
+    }
+    const item = this.nodes?.get(id)?.item;
+    if (item) this.onSelect?.(item);
+  }
+}

package/src/cocoa/keymap.js

@@ -0,0 +1,86 @@
+// macOS key events -> the renderer's keysym vocabulary (src/keysyms.js).
+//
+// The rule mirrors X's own: Latin-1 keysyms are their code points, everything
+// else printable is 0x01000000 + code point, and the editing/navigation keys
+// have fixed keysyms looked up here by kVK_* virtual key code. NSEvent's
+// three character views map onto the three keysym roles events.js reads:
+//
+//   charsBase    (modifiers stripped)  -> baseKeysym — what chords match
+//   charsShifted (only Shift applied)  -> keysym / codepoint — what was typed
+//
+// Function and editing keys type Unicode private-use characters (U+F700…),
+// which must never leak out as code points; the kVK table wins over the
+// character rule for exactly those.
+import { keysymOf, MOD } from '../keysyms.js';
+
+// kVK_* virtual key codes -> X keysyms, for the keys whose characters are
+// private-use or nothing at all.
+const VK_KEYSYMS = new Map([
+  [36, 0xff0d], // Return
+  [48, 0xff09], // Tab
+  // NOT space (kVK 49): space TYPES a character, so it goes through the
+  // character rule below and keeps its code point — a table entry here made
+  // `codepoint` undefined and a pressed spacebar inserted nothing.
+  [51, 0xff08], // Delete (backspace)
+  [53, 0xff1b], // Escape
+  [76, 0xff8d], // KP_Enter
+  [115, 0xff50], // Home
+  [116, 0xff55], // Page Up
+  [117, 0xffff], // Forward Delete
+  [119, 0xff57], // End
+  [121, 0xff56], // Page Down
+  [123, 0xff51], // Left
+  [124, 0xff53], // Right
+  [125, 0xff54], // Down
+  [126, 0xff52], // Up
+  [114, 0xff63], // Help -> Insert
+  [122, 0xffbe], // F1
+  [120, 0xffbf], // F2
+  [99, 0xffc0], // F3
+  [118, 0xffc1], // F4
+  [96, 0xffc2], // F5
+  [97, 0xffc3], // F6
+  [98, 0xffc4], // F7
+  [100, 0xffc5], // F8
+  [101, 0xffc6], // F9
+  [109, 0xffc7], // F10
+  [103, 0xffc8], // F11
+  [111, 0xffc9], // F12
+]);
+
+const PRIVATE_USE = (cp) => cp >= 0xf700 && cp <= 0xf8ff;
+
+function keysymFromChars(chars) {
+  if (!chars) return 0;
+  const cp = chars.codePointAt(0);
+  if (cp == null || cp < 0x20 || PRIVATE_USE(cp)) return 0;
+  return keysymOf(String.fromCodePoint(cp));
+}
+
+/**
+ * The three key facts events.js reads off a native key event, from the raw
+ * @windowkit/appkit payload.
+ */
+export function decodeKey(ev) {
+  const fixed = VK_KEYSYMS.get(ev.keyCode);
+  if (fixed) {
+    return { keysym: fixed, baseKeysym: fixed, codepoint: undefined };
+  }
+  const keysym = keysymFromChars(ev.charsShifted);
+  const baseKeysym = keysymFromChars(ev.charsBase) || keysym;
+  const cp = ev.charsShifted?.codePointAt(0);
+  const codepoint =
+    cp != null && cp >= 0x20 && !PRIVATE_USE(cp) ? cp : undefined;
+  return { keysym: keysym || baseKeysym, baseKeysym, codepoint };
+}
+
+/** AppKit modifier booleans -> the X-style state mask events carry. */
+export function modifierMask(ev) {
+  let mask = 0;
+  if (ev.shift) mask |= MOD.Shift;
+  if (ev.capsLock) mask |= MOD.Lock;
+  if (ev.control) mask |= MOD.Control;
+  if (ev.option) mask |= MOD.Alt; // ⌥ is Alt (Mod1), the DOM's own mapping
+  if (ev.command) mask |= MOD.Super; // ⌘ is Super (Mod4) -> ev.metaKey
+  return mask;
+}

package/src/cocoa/native.js

@@ -0,0 +1,51 @@
+// The bridge to @windowkit/appkit — the macOS Cocoa/Core Animation
+// backend's native half. Resolved lazily so that importing react-x11 on
+// Linux (or on a mac without the addon installed) costs nothing;
+// `createRoot` only walks in here once the backend decision has landed on
+// 'cocoa'. That laziness is what lets the package be an *optional*
+// dependency: on Linux npm skips it (its `os` field is darwin-only) and
+// nothing here ever asks for it.
+//
+// Resolution order: `REACT_X11_CALAYERS_PATH` (a checkout, for
+// development), then the installed `@windowkit/appkit` package. The addon
+// is CommonJS + a .node binary, so `createRequire` is the honest loader.
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const PACKAGE = '@windowkit/appkit';
+
+let cached = null;
+
+export function loadNative() {
+  if (cached) return cached;
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      "react-x11: the 'cocoa' backend is macOS-only. On this platform use " +
+        'the X11 backend (the default when DISPLAY is set), or pass ' +
+        "createRoot({ backend: 'x11' }).",
+    );
+  }
+  const tried = [];
+  const path = process.env.REACT_X11_CALAYERS_PATH;
+  for (const spec of [path, PACKAGE].filter(Boolean)) {
+    try {
+      const mod = require(spec);
+      // the package's index.js exports the raw addon as `native`; a direct
+      // path to a built checkout may be the addon itself
+      cached = mod.native ?? mod;
+      return cached;
+    } catch (err) {
+      tried.push(`  ${spec}: ${err.message}`);
+    }
+  }
+  throw new Error(
+    `react-x11: the cocoa backend needs the ${PACKAGE} native bridge ` +
+      'and none could be loaded:\n' +
+      tried.join('\n') +
+      `\nInstall it with \`npm install ${PACKAGE}\` (macOS, needs the ` +
+      'Xcode command-line tools), or point REACT_X11_CALAYERS_PATH at a ' +
+      'built checkout. To use X11 instead, set DISPLAY and pass ' +
+      "createRoot({ backend: 'x11' }).",
+  );
+}

package/src/cocoa/panehost.js

@@ -0,0 +1,50 @@
+// The host's half of a Cocoa frame pane: one sublayer over the window
+// content (the same stacking a glarea and an X11 foreign window get), whose
+// contents are whatever IOSurface the pane process last presented. The pane
+// owns its buffers and its drawing; this side owns the layer, the layout
+// and the input — CPU offloading, not isolation (docs/frame.md).
+export class CocoaPaneHost {
+  constructor(app, wnd) {
+    this.app = app;
+    this.wnd = wnd;
+    this._native = app._native;
+    this.layer = this._native.createLayer();
+    this._native.addSublayer(wnd._layer, this.layer);
+    this.destroyed = false;
+    this._rect = null;
+  }
+
+  /** Geometry in device px, the node's abs — points at the layer. */
+  setRect(rect) {
+    if (this.destroyed) return;
+    const s = this.wnd.scale;
+    const prev = this._rect;
+    if (
+      prev &&
+      prev.x === rect.x &&
+      prev.y === rect.y &&
+      prev.width === rect.width &&
+      prev.height === rect.height
+    ) {
+      return;
+    }
+    this._rect = { ...rect };
+    this._native.setLayerProps(this.layer, {
+      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+      zPosition: 1e7,
+      hidden: false,
+    });
+  }
+
+  /** A pane-present landed: scan out of the named shared surface. */
+  present(iosurfaceId) {
+    if (this.destroyed) return;
+    this._native.setLayerContentsIOSurface(this.layer, iosurfaceId);
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this._native.removeFromSuperlayer(this.layer);
+  }
+}