react-x11 2.2.0 → 2.3.0

package/src/nodes.js

@@ -109,7 +109,12 @@ import {
   windowOrigin,
 } from './anchor.js';
 import { baseTheme } from './palette.js';
-import { callHandler, ownerName } from './errors.js';
+import {
+  callHandler,
+  ownerName,
+  reportStyleError,
+  STRICT_TOKENS,
+} from './errors.js';
 import {
   hooks as a11yHooks,
   isFocusable as a11yFocusable,
@@ -1542,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
@@ -1557,6 +1569,11 @@ export class Node {
     // subtree's hit reach, invalidated through _clearHitBounds()
     this._paintOrderCache = null;
     this._hitBoundsCache = null;
+    // a `$token` the theme does not define, held for `commitMount` to throw
+    // on this node's own fiber — see `_tokenProblem`. Strict mode only.
+    // `null` is "commitMount is still to come", `false` is "it has been and
+    // gone", and an Error is one waiting for it
+    this._tokenError = null;
     this._syncStyle(props);
     this.yoga = yoga ? createLayoutNode() : null;
     if (this.yoga) {
@@ -1588,7 +1605,7 @@ export class Node {
    * them. `baseStyle` is the flattened `style` prop; `style` is that with
    * the active state blocks overlaid.
    */
-  _syncStyle(props) {
+  _syncStyle(props, mounting = false) {
     if (DEV && this.stylable) {
       assertNoFlatStyleProps(props, this.kind, this.semanticNames);
       validateStyle(flattenStyle(props.style), `<${this.kind} style>`);
@@ -1597,12 +1614,16 @@ export class Node {
     this._usesTokens = this.stylable && styleUsesTokens(this._baseStyle);
     if (this._usesTokens) {
       const theme = this.theme;
+      const strict = this.placed;
+      const problems = strict ? [] : null;
       this._baseStyle = resolveTokens(
         this._baseStyle,
         theme,
         `<${this.kind} style>`,
-        this.placed,
+        strict,
+        problems,
       );
+      if (problems?.length) this._tokenProblem(problems, mounting);
     }
     // `disabled` is a prop, not something the pointer does, so it is read
     // straight off props rather than driven by the event manager
@@ -1687,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
@@ -2241,6 +2270,46 @@ export class Node {
     return owner.isPopup ? owner.parent != null : true;
   }
 
+  /**
+   * A `$token` this node's completed ancestry does not define.
+   *
+   * The default is `reportStyleError`: say so loudly, set `process.exitCode`,
+   * and keep the property dropped. `REACT_X11_STRICT_TOKENS=1` makes it fatal
+   * again, and then *where* the throw lands is the whole question — an error
+   * boundary only catches what React invoked, on the fiber React thinks it
+   * is working on.
+   *
+   * `mounting` is the attach walk, which runs inside `appendInitialChild`
+   * while React is completing the nearest host *ancestor* — the `<window>`,
+   * for a whole tree rendered at once. A throw there is attributed to the
+   * window and sails past every boundary the app wrote inside it, which is
+   * the bug this deferral exists for (#420). Stashed instead, and thrown
+   * from `commitMount` on this node's own fiber, where the walk up finds a
+   * boundary at any depth.
+   *
+   * Every other caller already has the right fiber (`commitUpdate`) or has
+   * no React on the stack at all (`appearanceChanged`, from an X event) —
+   * for those, throwing here is both the earliest and the only option, and
+   * the second is the crash strict mode asked for.
+   *
+   * `commitMount` happens once per instance, so a node re-attached after it
+   * has been and gone has nothing left to defer *to*; stashing there would
+   * swallow the error instead of raising it late. Those throw at once, like
+   * the keyed reorder they resemble.
+   */
+  _tokenProblem(problems, mounting) {
+    if (!STRICT_TOKENS) {
+      // every one of them: two misspellings in a style are two things to
+      // fix, and a report that named only the first would send someone back
+      // for a second run to find the second
+      for (const message of problems) reportStyleError(this, message);
+      return;
+    }
+    const error = new Error(problems[0]);
+    if (mounting && this._tokenError === null) this._tokenError = error;
+    else throw error;
+  }
+
   /** The owning window resized: re-resolve, since a query block may now
    * match that did not, or the other way round. */
   _sizeQueriesChanged() {
@@ -2287,7 +2356,7 @@ export class Node {
       if (this.isWindow) this._syncWindowBackground();
       if (this._usesTokens) {
         const before = this.style;
-        this._syncStyle(this.props);
+        this._syncStyle(this.props, mounting);
         // a token change reaches the node without React re-rendering it, so
         // the invalidation a commit would have done has to happen here too
         if (localTextStyleChanged(this.style, before)) {
@@ -3199,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(),
@@ -4122,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);
@@ -4148,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';
@@ -4158,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;
@@ -4171,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;
@@ -4185,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);
@@ -5425,6 +5515,7 @@ export const Scrollable = (Base) =>
     }
 
     absolutize(originX, originY) {
+      this._placed = true;
       if (!this.yoga) return;
       this._assignAbs(
         originX + this.yoga.getComputedLeft(),
@@ -6476,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 }),
@@ -10173,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;
@@ -10398,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
@@ -10562,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;
@@ -10637,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
@@ -10657,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/style.d.ts

@@ -43,12 +43,15 @@ export function tokenNames(
   style: StyleProperties,
   out?: Set<string>,
 ): Set<string>;
-/** Replace `$token` references with values from the theme. */
+/** Replace `$token` references with values from the theme. A token the theme
+ *  does not define is dropped either way; with `strict`, the message naming
+ *  it is pushed onto `problems` for the caller to report or throw. */
 export function resolveTokens(
   style: StyleProperties,
   theme: Record<string, unknown> | null | undefined,
   where?: string,
   strict?: boolean,
+  problems?: string[] | null,
 ): StyleProperties;
 
 export function styleHasSizeQueries(style: StyleProperties): boolean;

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
@@ -1206,16 +1211,37 @@ export function stripTokens(style) {
  * `strict` says the node's ancestry is complete, so a token that does not
  * resolve is a mistake. While a subtree is still being built its nodes can
  * see only part of their ancestry — the theme two levels up does not exist
- * for them yet — so resolution there is provisional: unknown tokens are
- * dropped and the node restyles when it attaches.
+ * for them yet — so resolution there is provisional.
+ *
+ * Both cases drop the property, because a value is either resolved or absent
+ * and `'$textMuted1'` is not a colour. What `strict` changes is whether
+ * anyone hears about it: mistakes are pushed onto `problems` and the caller
+ * decides what one costs. Resolving itself never throws — it runs from a
+ * commit and from an X event alike, and only the caller knows whether React
+ * is on the stack to route a throw to a boundary (src/nodes.js).
+ *
+ * A cache hit replays the problems it recorded, so the second node to wear a
+ * misspelled shared style is reported like the first.
  */
-export function resolveTokens(style, theme, where = 'style', strict = true) {
+export function resolveTokens(
+  style,
+  theme,
+  where = 'style',
+  strict = true,
+  problems = null,
+) {
   if (!theme) return stripTokens(style);
   let byTheme = strict ? resolvedCache.get(style) : null;
   if (strict && !byTheme) resolvedCache.set(style, (byTheme = new WeakMap()));
   const hit = byTheme?.get(theme);
-  if (hit) return hit;
+  if (hit) {
+    if (problems && hit.problems) problems.push(...hit.problems);
+    return hit.out;
+  }
 
+  // collected here rather than pushed straight to `problems` so the cache
+  // entry can keep them: the caller that misses is not the only one to hear
+  const found = strict ? [] : null;
   const out = {};
   for (const key of Object.keys(style)) {
     const v = style[key];
@@ -1225,11 +1251,7 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
         out[key] = theme[name];
         continue;
       }
-      if (!strict) continue;
-      throw new Error(
-        `react-x11: unknown theme token "${v}" in ${where} ` +
-          `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-      );
+      if (strict) found.push(unknownToken(v, theme, where));
     } else if (mentionsToken(v)) {
       let unknown = null;
       const substituted = v.replace(TOKEN_IN_VALUE, (token) => {
@@ -1245,13 +1267,10 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       // frame instead of at the style.
       if (!unknown) out[key] = substituted;
       else if (strict) {
-        throw new Error(
-          `react-x11: unknown theme token "${unknown}" in ${where} ${key} ` +
-            `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-        );
+        found.push(unknownToken(unknown, theme, `${where} ${key}`));
       }
     } else if (key.charCodeAt(0) === 58 && v) {
-      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict);
+      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict, found);
     } else if (key === 'animation' && v && typeof v === 'object') {
       const loops = {};
       let incomplete = false;
@@ -1266,11 +1285,11 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
           theme,
           `${where} animation ${prop}`,
           strict,
+          found,
         );
-        // A provisional resolution drops what it cannot resolve, which for
-        // an ordinary property means "not styled yet". A loop with one end
-        // missing is not a shorter loop, so the whole declaration waits for
-        // the ancestry to complete rather than throwing at a half of one.
+        // A loop with one end missing is not a shorter loop, so a
+        // declaration that lost a value is dropped whole rather than run
+        // between a colour and nothing.
         if (Object.keys(resolved).length !== Object.keys(entry).length) {
           incomplete = true;
         }
@@ -1281,10 +1300,20 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       out[key] = v;
     }
   }
-  byTheme?.set(theme, out);
+  if (found?.length && problems) problems.push(...found);
+  byTheme?.set(theme, { out, problems: found?.length ? found : null });
   return out;
 }
 
+/** The one message, written once: what was named, and what the palette in
+ *  force actually has — listing the alternatives is most of the fix. */
+function unknownToken(token, theme, where) {
+  return (
+    `react-x11: unknown theme token "${token}" in ${where} ` +
+    `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`
+  );
+}
+
 export { validateStyle };
 
 /**

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;
 }