react-x11 2.2.1 → 2.3.0

package/src/frame/index.js

@@ -43,6 +43,7 @@ import React, {
   useState,
 } from 'react';
 
+import { useAppOrNull } from '../appcontext.js';
 import { FrameEnv } from './env.js';
 import { CallbackTable, PROTOCOL } from './protocol.js';
 
@@ -220,6 +221,11 @@ export function Frame({
   ref,
 }) {
   const env = useContext(FrameEnv);
+  // A backend that composites panes from shared memory (Cocoa) declares
+  // itself with createPaneHost; everything else embeds the pane's real
+  // window through <foreign>, exactly as before.
+  const appOrNull = useAppOrNull();
+  const paneApp = appOrNull?.createPaneHost ? appOrNull : null;
   const [state, setState] = useState({
     phase: 'starting',
     windowId: null,
@@ -365,9 +371,10 @@ export function Frame({
     // rather than one frame of default before an update lands.
     const { props: p, env: e, bridge: b } = current.current;
     const node = containerRef.current;
+    const sc = node?.scale ?? 1;
     const rect = {
-      width: Math.max(1, Math.round(node?.abs?.width || 0)) || 400,
-      height: Math.max(1, Math.round(node?.abs?.height || 0)) || 300,
+      width: Math.round((node?.abs?.width || 0) / sc) || 400,
+      height: Math.round((node?.abs?.height || 0) / sc) || 300,
     };
     s.sent = { props: p, env: e, bridge: b };
     trySend({
@@ -413,6 +420,23 @@ export function Frame({
   }, [props, env, bridge, generation]);
 
   if (state.phase === 'running') {
+    if (paneApp) {
+      return h(PaneHostView, {
+        containerRef,
+        session,
+        app: paneApp,
+        style,
+        focusable,
+        onEmbedError: (err) => {
+          session.current?.shutdown?.();
+          setState({
+            phase: 'failed',
+            windowId: null,
+            error: Object.assign(err, { phase: 'embed' }),
+          });
+        },
+      });
+    }
     return h('foreign', {
       ref: containerRef,
       windowId: state.windowId,
@@ -442,3 +466,139 @@ export function Frame({
       : null,
   );
 }
+
+/**
+ * The Cocoa pane region: a box for layout, focus and input — hit-tested
+ * here, in the host, and forwarded over the channel — with a backend pane
+ * host object carrying the composited layer. The pane process presents by
+ * message; this view points the layer at each presented buffer.
+ */
+function PaneHostView({
+  containerRef,
+  session,
+  app,
+  style,
+  focusable,
+  onEmbedError,
+}) {
+  // `onEmbedError` is a fresh closure every host render (it captures
+  // setState), and the host ticks its own state many times a second — so it
+  // must not be an effect dependency, or the effect below tears the pane
+  // layer down and rebuilds it on every host render, and the gap between
+  // `host.destroy()` and the next present is a visible full-pane flash. A
+  // ref carries the latest callback into a once-per-session effect.
+  const embedErrorRef = useRef(onEmbedError);
+  embedErrorRef.current = onEmbedError;
+
+  useEffect(() => {
+    const s = session.current;
+    const node = containerRef.current;
+    const wnd = node?.root?.window;
+    if (!s || !node || !wnd) {
+      embedErrorRef.current?.(
+        new Error('the pane region has no window to sit in'),
+      );
+      return undefined;
+    }
+    let host;
+    try {
+      host = app.createPaneHost(wnd);
+    } catch (err) {
+      embedErrorRef.current?.(err);
+      return undefined;
+    }
+    s.paneHost = host;
+
+    // The pane's size is this box's laid-out size, told to the pane whenever
+    // it changes — the same absolutize hook a <foreign> child window uses
+    // (src/foreignnodes.js), because onViewport fires only for scrollers.
+    let sentSize = null;
+    const syncSize = () => {
+      host.setRect(node.abs);
+      const sc = node.scale ?? 1;
+      const width = Math.max(1, Math.round(node.abs.width / sc));
+      const height = Math.max(1, Math.round(node.abs.height / sc));
+      if (sentSize && sentSize.width === width && sentSize.height === height) {
+        return;
+      }
+      sentSize = { width, height };
+      s.trySend?.({ type: 'pane-rect', width, height, scale: sc });
+    };
+    const origAbsolutize = node.absolutize.bind(node);
+    node.absolutize = (ox, oy) => {
+      origAbsolutize(ox, oy);
+      syncSize();
+    };
+    const origShift = node._shiftAbs?.bind(node);
+    if (origShift) {
+      node._shiftAbs = (dx, dy) => {
+        origShift(dx, dy);
+        host.setRect(node.abs);
+      };
+    }
+    if (node.abs?.width) syncSize();
+
+    const off = s.transport.onMessage((msg) => {
+      if (msg?.type === 'pane-present') {
+        host.setRect(node.abs);
+        host.present(msg.id);
+      }
+    });
+    return () => {
+      off();
+      node.absolutize = origAbsolutize;
+      if (origShift) node._shiftAbs = origShift;
+      if (s.paneHost === host) s.paneHost = null;
+      host.destroy();
+    };
+  }, [app, session, containerRef]);
+
+  const forward = (name, data) => (ev) => {
+    const s = session.current;
+    const node = containerRef.current;
+    if (!s || !node) return;
+    const sc = node.scale ?? 1;
+    const payload = {
+      x: Math.max(0, Math.round(ev.x * sc - node.abs.x)),
+      y: Math.max(0, Math.round(ev.y * sc - node.abs.y)),
+      rootx: Math.round(ev.x * sc),
+      rooty: Math.round(ev.y * sc),
+      buttons: ev.buttons ?? 0,
+      time: Date.now(),
+      ...data(ev),
+    };
+    try {
+      s.trySend?.({ type: 'pane-event', name, ev: payload });
+    } catch {
+      // the exit path owns the failure story
+    }
+  };
+
+  return h('box', {
+    ref: containerRef,
+    style,
+    focusable: focusable ?? true,
+    onMouseDown: forward('mousedown', (ev) => ({ keycode: ev.button ?? 1 })),
+    onMouseUp: forward('mouseup', (ev) => ({ keycode: ev.button ?? 1 })),
+    onMouseMove: forward('mousemove', () => ({})),
+    onWheel: forward('wheel', (ev) => ({
+      deltaX: ev.deltaX ?? 0,
+      deltaY: ev.deltaY ?? 0,
+      deltaMode: ev.deltaMode ?? 'line',
+      smooth: Boolean(ev.smooth),
+      source: 'forwarded',
+    })),
+    onKeyDown: forward('keydown', (ev) => ({
+      keysym: ev.keysym,
+      baseKeysym: ev.baseKeysym ?? ev.keysym,
+      codepoint: ev.codepoint,
+      keycode: ev.keycode ?? 0,
+    })),
+    onKeyUp: forward('keyup', (ev) => ({
+      keysym: ev.keysym,
+      baseKeysym: ev.baseKeysym ?? ev.keysym,
+      codepoint: ev.codepoint,
+      keycode: ev.keycode ?? 0,
+    })),
+  });
+}

package/src/glnodes.js

@@ -194,6 +194,21 @@ export class GlAreaNode extends Node {
       // GL draws into the window itself: no 2d backing pixmap, and the
       // frame clock is ours to drive
       backingStore: false,
+      // The wheel, and only the wheel. A GL surface owns a real X window, so
+      // the pointer events over it are delivered *there* rather than to the
+      // window the rest of the tree is hit-tested in — which is why nothing
+      // over a `<glarea>` reached an application before. Selecting it here
+      // and handing it back to the owning window's manager (`_onWheel`
+      // below) is the whole of it: from there the event is an ordinary
+      // synthetic `Wheel` at this node, so it bubbles, `preventDefault()`
+      // takes it back for a scene that zooms instead, and the default action
+      // scrolls the nearest container the way it does anywhere else.
+      //
+      // Selected unconditionally rather than when a handler is declared: the
+      // default action is what a reader expects from a wheel over a page,
+      // and an element that wants it back has `preventDefault()`. One
+      // ButtonPress per notch is not a cost worth a conditional.
+      onWheel: (ev) => this._onWheel(ev),
     });
     this.window = wnd;
     this.rect = rect;
@@ -313,6 +328,34 @@ export class GlAreaNode extends Node {
     if (this.props.frameLoop === 'always') this.requestFrame();
   }
 
+  /**
+   * A wheel over the surface, handed to the window the tree lives in.
+   *
+   * ntk reports the position inside *this* window; the manager hit-tests in
+   * the owning window's space, so the node's own origin goes back on. Both
+   * are device pixels — the scale is applied at the far end, where a handler
+   * reads `ev.x` (src/events.js).
+   *
+   * Smooth deltas are not part of this yet: XI2 is selected on the window
+   * the manager owns, not on this child, so a touchpad's fractions arrive
+   * here as whole notches from buttons 4-7.
+   */
+  _onWheel(native) {
+    const events = this.root?.events;
+    if (!events || this.destroyed) return;
+    events._onWheel(
+      {
+        ...native,
+        x: (native.x ?? 0) + this.abs.x,
+        y: (native.y ?? 0) + this.abs.y,
+      },
+      // named rather than hit-tested: a window-owning child is not in its
+      // parent's paint order, so the hit test would answer with the box
+      // behind this surface
+      this,
+    );
+  }
+
   applyProps(newProps, oldProps) {
     super.applyProps(newProps, oldProps);
     // onDraw/clearColor are read at frame time, so any update is a new frame

package/src/globalmenu.js

@@ -67,6 +67,7 @@ import {
   snapshot,
   IdAllocator,
 } from './dbusmenu.js';
+import { useAppOrNull } from './appcontext.js';
 import { useTopLevelWindow, windowIdOf } from './windowid.js';
 
 export const REGISTRAR_NAME = 'com.canonical.AppMenu.Registrar';
@@ -649,6 +650,7 @@ export function useGlobalMenu(
   { onSelect, onAboutToShow, enabled = true } = {},
 ) {
   const target = useTopLevelWindow();
+  const app = useAppOrNull();
   const [exported, setExported] = useState(false);
   const exportRef = useRef(null);
 
@@ -661,7 +663,7 @@ export function useGlobalMenu(
 
   useEffect(() => {
     if (!enabled) return undefined;
-    const owner = new GlobalMenuExport({
+    const config = {
       getMenus: () => live.current.menus ?? [],
       onSelect: (item) => {
         item.onSelect?.(item);
@@ -670,7 +672,13 @@ export function useGlobalMenu(
       onAboutToShow: (item) => live.current.onAboutToShow?.(item),
       target,
       onChange: setExported,
-    });
+    };
+    // The transport is the backend's where it has one — the Cocoa backend
+    // owns the macOS menu bar and answers immediately — and D-Bus with the
+    // registrar dance everywhere else. Same owner contract either way.
+    const owner = app?.createGlobalMenuExport
+      ? app.createGlobalMenuExport(config)
+      : new GlobalMenuExport(config);
     exportRef.current = owner;
     owner.start().catch(() => {});
     return () => {
@@ -678,7 +686,7 @@ export function useGlobalMenu(
       setExported(false);
       owner.stop().catch(() => {});
     };
-  }, [enabled, target]);
+  }, [enabled, target, app]);
 
   useEffect(() => {
     exportRef.current?.update(menus ?? []);

package/src/index.d.ts

@@ -170,6 +170,16 @@ export interface ErrorInfo {
 }
 
 export interface RootOptions {
+  /**
+   * Which display system a root that opens its own connection talks to.
+   * `'auto'` (the default) uses the native Core Animation backend on macOS
+   * and X11 via `$DISPLAY` everywhere else; on a mac without the
+   * `@windowkit/appkit` bridge installed it falls back to X11. Naming
+   * `'cocoa'` makes the bridge required. `REACT_X11_BACKEND` overrides.
+   * Ignored when {@link RootOptions.app} is passed — a connection already
+   * is a backend.
+   */
+  backend?: 'auto' | 'x11' | 'cocoa';
   /** `':1'`, `'host:0.0'`, or a unix socket path. Defaults to `$DISPLAY`. */
   display?: string;
   /**

package/src/nodes.js

@@ -1547,6 +1547,13 @@ export class Node {
     // delete themselves as they land; a loop entry (`loop: true`) is removed
     // by `_updateLoops` and by nothing else
     this._anim = null;
+    // False until the first frame places this node (`absolutize`). Read by
+    // `_retarget`: a style can be re-resolved several times between
+    // construction and that first frame — the attach-time theme merge is the
+    // common one, replacing a detached resolution against the desktop
+    // palette with one against the app's own — and none of those is a
+    // *change* the user saw, so no transition may start from it.
+    this._placed = false;
     // the loops this node's style declares, whether or not they are running
     this._loops = null;
     // `resolvedTextStyle()`'s cache: this node's own text style over what it
@@ -1701,24 +1708,32 @@ export class Node {
       }
       return this.style;
     }
-    for (const prop of Object.keys(target)) {
-      const to = target[prop];
-      const from = displayed[prop];
-      if (from === to || from === undefined) continue;
-      const duration = transitionFor(target, prop);
-      if (duration <= 0) continue;
-      if (interpolate(from, to, 0.5) === null) continue; // no midpoint: snap
-      (this._anim ??= new Map()).set(prop, {
-        from,
-        to,
-        duration,
-        // *now*, not the last frame's timestamp: between two user actions
-        // the window is idle and draws nothing, so the previous frame can
-        // be seconds old — and the first tick would then find the
-        // transition already over and jump straight to the end
-        start: now(),
-      });
-      this.root?._startAnimating(this);
+    // Only for a node the user has seen (`_placed`): between construction
+    // and the first frame a style is re-resolved several times — attach
+    // merges the real theme over the detached resolution's desktop palette,
+    // queries settle — and animating any of those would travel from a value
+    // that was never on screen. An inserted element *appears* at its style;
+    // transitions start on later changes, which is CSS's rule too.
+    if (this._placed) {
+      for (const prop of Object.keys(target)) {
+        const to = target[prop];
+        const from = displayed[prop];
+        if (from === to || from === undefined) continue;
+        const duration = transitionFor(target, prop);
+        if (duration <= 0) continue;
+        if (interpolate(from, to, 0.5) === null) continue; // no midpoint: snap
+        (this._anim ??= new Map()).set(prop, {
+          from,
+          to,
+          duration,
+          // *now*, not the last frame's timestamp: between two user actions
+          // the window is idle and draws nothing, so the previous frame can
+          // be seconds old — and the first tick would then find the
+          // transition already over and jump straight to the end
+          start: now(),
+        });
+        this.root?._startAnimating(this);
+      }
     }
     // After the transitions, before the style is assembled: a loop that just
     // arrived contributes a value to this very swap, so the first frame the
@@ -3253,6 +3268,9 @@ export class Node {
   }
 
   absolutize(originX, originY) {
+    // before the yoga check, so a span — placed by its paragraph, no box of
+    // its own — counts as on screen too
+    this._placed = true;
     if (!this.yoga) return;
     this._assignAbs(
       originX + this.yoga.getComputedLeft(),
@@ -4176,19 +4194,28 @@ export class Node {
    * One blurred shadow, through the paint cache when there is one.
    *
    * The surface is the shadow's rectangle plus `pad` on every side, and the
-   * padding is load-bearing: the convolution reads outside the picture as
+   * padding is load-bearing: a convolution reads outside the picture as
    * transparent, so a kernel that runs off the edge ends the shadow in a
-   * straight line. The blur is set on the *picture* rather than baked into
-   * the pixels, which is why it survives in a cached entry and why the
-   * surface itself is a plain white rectangle.
+   * straight line. `blurKernel` takes that reach from the same function
+   * ntk builds the kernel with, so the two cannot drift apart.
+   *
+   * The blur is **baked into the pixels** by `blurCoverage` (ntk 8.6,
+   * ntk#335) rather than set as a filter on the picture. That is the
+   * difference between a cached shadow and a cached shadow that costs
+   * nothing to draw: a picture's filter is re-applied by the server on every
+   * composite, so the entry would hit, re-render nothing, and still pay its
+   * whole kernel every frame — 244M multiply-accumulates for one card-sized
+   * shadow, which was 1.6s per `:hover` on XQuartz. Baked, what the cache
+   * holds composites as an ordinary mask however wide the blur was, and the
+   * two separable passes run once per distinct geometry.
    *
    * `maxPixels` is raised well above the cache's default: a card's shadow is
    * as big as the card, an entry for one is a8 (a byte a pixel), and the
-   * thing being avoided — a convolution per frame over the whole box — is
-   * exactly the cost the default cap exists to bound elsewhere.
+   * thing being avoided is exactly the cost the default cap bounds
+   * elsewhere.
    */
   _paintBlurredShadow(ctx, rect, radius, blur, color) {
-    const { sigma, size, pad } = blurKernel(blur);
+    const { sigma, pad } = blurKernel(blur);
     // integral, because the surface is pixels; the blur is far wider than
     // the rounding, so nothing about the result is visibly quantized
     const width = Math.round(rect.width);
@@ -4202,6 +4229,10 @@ export class Node {
       format: 'a8',
       tint: color,
       maxPixels: 1024 * 1024,
+      // Cache on the first sighting rather than the second: what the gate
+      // saves elsewhere is a cheap redraw, and what it costs here is a whole
+      // gaussian — the one thing this entry exists to avoid running twice.
+      eager: true,
       draw: (sctx, box) => {
         // full coverage: the colour arrives at composite time
         sctx.fillStyle = '#ffffff';
@@ -4212,7 +4243,7 @@ export class Node {
         );
         sctx.fill();
       },
-      after: (surface) => surface.picture().setBlurFilter(size, sigma),
+      after: (surface) => ntk.blurCoverage(surface, sigma),
       live: () => this._paintShadowLive(ctx, plan),
     };
     const cache = this.root?._paintCache;
@@ -4225,7 +4256,9 @@ export class Node {
    * build, an entry too big for the budget, and the first frame of a shadow
    * the cache has only seen once. A surface per frame is what a shadow costs
    * without a cache; it is still one composite on the wire, and the
-   * alternative is not painting it.
+   * alternative is not painting it. The blur is baked here too: two
+   * separable passes and a plain composite still beat one composite through
+   * a k x k kernel, by the ratio of 2k to k squared.
    */
   _paintShadowLive(ctx, plan) {
     if (typeof ntk.Surface !== 'function' || !this.app?.display?.Render) return;
@@ -4239,7 +4272,10 @@ export class Node {
       surface.render((sctx) =>
         plan.draw(sctx, { x: 0, y: 0, width: plan.width, height: plan.height }),
       );
-      plan.after(surface);
+      // `after` may hand back a *different* surface — the blur is baked into
+      // a second one and the sharp copy destroyed — so both the drawing and
+      // the cleanup below follow what it returned.
+      surface = plan.after(surface) ?? surface;
       const before = ctx.fillStyle;
       ctx.fillStyle = plan.tint;
       ctx.drawImage(surface, plan.x, plan.y);
@@ -5479,6 +5515,7 @@ export const Scrollable = (Base) =>
     }
 
     absolutize(originX, originY) {
+      this._placed = true;
       if (!this.yoga) return;
       this._assignAbs(
         originX + this.yoga.getComputedLeft(),
@@ -6530,13 +6567,16 @@ export function openEditMenu(node, at, actions = {}) {
   if (items.length === 0) return;
 
   const style = node.resolvedTextStyle();
+  // `at` is `{x: ev.x, y: ev.y}` per the doc above — logical, like every
+  // coordinate a handler reads — and everything below is device: the
+  // geometry takes the scale so its chrome lands on the same grid as the
+  // device-sized text it measures.
+  const s = node.scale;
   const geometry = editMenuGeometry(
     items,
     (text) => app?.fonts?.layout(text, style)?.width,
+    s,
   );
-  // `at` is `{x: ev.x, y: ev.y}` per the doc above — logical, like every
-  // coordinate a handler reads — and the origin math below is device.
-  const s = node.scale;
   const deviceAt = at && {
     ...at,
     ...(Number.isFinite(at.x) && { x: at.x * s }),
@@ -10227,8 +10267,20 @@ export class WindowNode extends Scrollable(Node) {
    * before laying out. This is the whole reason a size query may carry
    * layout properties while a state block may not: it only ever runs inside
    * a layout pass the resize already required.
-   */
-  _resolveSizeQueries(width, height) {
+   *
+   * Callers pass the size in device pixels — it comes off the window or out
+   * of yoga, and both live on the device grid — but `querySize` is stored
+   * in **logical** pixels, because that is the unit the thresholds were
+   * written in: `'@width >= 620'` sits in a style block next to `width:
+   * 620`, and the same number must mean the same thing. At scale 1 the two
+   * coincide, which is how comparing device pixels survived every 1x
+   * display it was ever run on and broke on the first retina one (every
+   * query read double, so none of them ever changed answer under a drag).
+   */
+  _resolveSizeQueries(deviceWidth, deviceHeight) {
+    const s = this.scale || 1;
+    const width = deviceWidth / s;
+    const height = deviceHeight / s;
     if (this._sizeQueryNodes.size === 0) {
       this.querySize = this.querySize ?? { width, height };
       return false;
@@ -10452,6 +10504,11 @@ export class WindowNode extends Scrollable(Node) {
       }
       (this._frameReasons ??= new Set()).add(reason);
     }
+    // A retained presenter keeps a per-node diff instead of damage rects,
+    // and this is the one channel every change already announces itself on
+    // (docs/macos.md §"One renderer, two presenters"). Feature-detected: an
+    // ntk window has no ear here and the X11 path is byte-identical.
+    this.window?.noteInvalidate?.(damage, layoutChanged, reason);
     if (layoutChanged) {
       this.needsLayout = true;
       // The content floors are measured from the tree, so anything that
@@ -10616,6 +10673,7 @@ export class WindowNode extends Scrollable(Node) {
       this.yoga.setHeight(height);
       this.yoga.calculateLayout(width, height, this._rootDirection);
       this.abs = { x: 0, y: 0, width, height };
+      this._placed = true;
       // the root's rect is written here, not through _assignAbs, so its
       // cached hit reach is dropped here too (children bubble their own)
       this._hitBoundsCache = null;
@@ -10691,6 +10749,16 @@ export class WindowNode extends Scrollable(Node) {
       );
     }
     this._fullRepaintCause = null;
+    // A retained presenter takes the frame from here: the model half above —
+    // animations, layout, absolutize, the scroll offsets — is shared, and
+    // what changes per backend is how a frame reaches the screen. The damage
+    // list was still taken (its bookkeeping is what keeps the two paths one
+    // code) and is simply not consumed; the presenter diffs at the layer.
+    if (typeof this.window.presentFrame === 'function') {
+      this.window.presentFrame(this, damage);
+      this.app._reactX11Startup?.painted();
+      return;
+    }
     if (typeof this.window.getContext !== 'function') return; // headless mock
     // ntk getContext creates a fresh context (with window-event
     // subscriptions) on every call — cache one per window
@@ -10711,6 +10779,12 @@ export class WindowNode extends Scrollable(Node) {
     // after every region: an entry drawn in one damage rect must not be
     // evicted before the next rect of the same frame asks for it
     this._paintCache?.endFrame();
+    // The swapchain seam: a backend presenting from double buffers has to
+    // know exactly which pixels each flush touched — several flushes can
+    // land between two presents, so reading only the last frame's rects
+    // would leave the flipped-in back buffer stale where an earlier flush
+    // painted. Feature-detected like presentFrame; null means everything.
+    this.window.noteFrameDamage?.(damage ?? null);
     if (frameHook) {
       frameHook({
         root: this,

package/src/paintcache.js

@@ -232,7 +232,13 @@ export class PaintCache {
     }
 
     this.stats.misses++;
-    const seen = (this.pending.get(plan.key) ?? 0) + 1;
+    // `eager` skips the gate below for a drawing whose *live* path is the
+    // expensive thing — a blurred shadow, whose first sighting otherwise
+    // runs a convolution that is then thrown away, and a second one to keep.
+    // The gate is there so a page cycling unique content cannot fill the
+    // cache with entries drawn once; an eager plan opts out of that
+    // protection deliberately, and the LRU budget is what still bounds it.
+    const seen = plan.eager ? 2 : (this.pending.get(plan.key) ?? 0) + 1;
     if (seen < 2) {
       if (this.pending.size >= MAX_PENDING) this.pending.clear();
       this.pending.set(plan.key, seen);
@@ -260,12 +266,17 @@ export class PaintCache {
       surface.render((sctx) =>
         plan.draw(this.verify ? recordingContext(sctx, state) : sctx, box),
       );
-      plan.after?.(surface);
+      // `after` may hand back a *different* surface than it was given — a
+      // blurred shadow bakes its convolution into a second one and destroys
+      // the sharp copy, so that what this entry holds composites as a plain
+      // mask instead of re-running a kernel on every blit. What it returns
+      // is what the cache owns from here on.
+      const final = plan.after?.(surface) ?? surface;
       this.stats.renders++;
       return {
         key: plan.key,
-        surface,
-        bytes: surface.bytes,
+        surface: final,
+        bytes: final.bytes,
         digest: this.verify ? state.digest : 0,
       };
     } catch (err) {

package/src/palette.js

@@ -222,6 +222,19 @@ export const DefaultTheme = {
   // than it looks next to a CSS padding for that reason: 12 here is about
   // what 8 came to once a typical face's ascent had been added on.
   paddingY: 12,
+  // Which scheme this palette *is* — 'light' or 'dark'. Not a colour but a
+  // fact about the colours, for the consumers that have to match them with
+  // something they do not paint themselves: the Cocoa backend picks the
+  // AppKit appearance its native control bezels are rendered in from this,
+  // so a pinned-light app gets light bezels on a dark desktop. A custom
+  // dark palette built over the light base should say `scheme: 'dark'`.
+  scheme: 'light',
+  // How the core controls render where the backend offers the platform's
+  // own: `'auto'` (native where supported — today the Cocoa backend),
+  // `'native'` (ask for it; warns and falls back to drawn where there is
+  // none) or `'drawn'` (always the themed rendering). Per-instance escape
+  // hatch: `native={false}` on the one custom-branded control.
+  controls: 'auto',
 };
 
 // Which pressed token is derived from which pair, when the palette does not
@@ -332,6 +345,7 @@ export function resolveTheme(value, base = DefaultTheme) {
  * theme after it gets to do.
  */
 export const DarkTheme = resolveTheme({
+  scheme: 'dark',
   // A near-black with a little blue in it rather than #000: pure black shows
   // every seam between a window and the widgets on it, and no desktop's dark
   // theme uses it.

package/src/styles.js

@@ -466,6 +466,11 @@ const isState = (key) => key.charCodeAt(0) === 58; /* ':' */
  * what a style can usefully ask about here is the window it is being laid
  * out in, not the screen.
  *
+ * The threshold is **logical** pixels, like every other number in a style
+ * block: `'@width >= 620'` flips where `width: 620` would fit, whatever
+ * the display scale (the window node divides its device size out before
+ * matching — `_resolveSizeQueries`).
+ *
  * Unlike a state block, a size query *may* set layout properties. That is
  * not an inconsistency: pointer state changes must never reflow the tree,
  * but a size query is only ever re-evaluated during a layout pass that a

package/src/types/elements.d.ts

@@ -23,6 +23,7 @@ import type {
   SubmitEvent,
   SyntheticEvent,
   ViewportEvent,
+  WheelEvent,
   WindowResizeEvent,
 } from './events.js';
 
@@ -841,6 +842,15 @@ export interface GlAreaProps extends DrawnProps<DrawnNode> {
   onDraw?: (gl: any, info: DrawInfo) => void;
   /** No GL surface — no GLX, or no matching visual. */
   onError?: (err: Error) => void;
+  /**
+   * The wheel over the surface. Inherited from `EventHandlers` like every
+   * other element's, and listed here because it is the **only** pointer
+   * event a `<glarea>` currently reports: the surface owns its own X window,
+   * so it selects the wheel there and hands it to the window's event manager
+   * (see docs/elements.md). Deltas are pixels, `preventDefault()` takes the
+   * default scroll action back, and it bubbles from this node.
+   */
+  onWheel?: (ev: WheelEvent<DrawnNode>) => void;
   /** A click inside the surface that hit no mesh. */
   onPointerMissed?: (ev: MouseEvent<DrawnNode>) => void;
 }