react-x11 2.52.0 → 2.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.52.0",
+  "version": "2.53.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {
@@ -72,6 +72,7 @@
     "labs:direct-gl": "tsx examples/labs/direct-gl.jsx",
     "labs:gl-overlay": "tsx examples/labs/gl-overlay.jsx",
     "examples:viewer3d": "tsx examples/viewer3d.jsx",
+    "examples:video": "tsx examples/video.jsx",
     "examples:transparent": "tsx examples/transparent.jsx",
     "examples:windows": "tsx examples/windows.jsx",
     "examples:wm": "tsx examples/wm.jsx",
@@ -110,7 +111,7 @@
     "ical.js": "^2.2.1",
     "image-in-browser": "^3.6.0",
     "linebreak": "^1.1.0",
-    "ntk": "^8.23.2",
+    "ntk": "^8.24.0",
     "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },

package/src/Reconciler.js

@@ -678,7 +678,7 @@ const isNtkApp = (v) =>
  *
  * `'auto'` — the default — is one rule: macOS gets the native Core
  * Animation backend, everything else gets X11 via `$DISPLAY`. (More rungs —
- * Wayland — join this ladder, not a new one; docs/wayland.md.) On a mac
+ * Wayland — join this ladder, not a new one; design/wayland.md.) On a mac
  * without the `@windowkit/appkit` bridge installed, auto falls back to X11 so
  * an XQuartz setup keeps working; asking for `'cocoa'` by name means the
  * bridge is required, and its absence is an error that says how to fix it.
@@ -809,7 +809,7 @@ export async function createRoot(options = {}) {
   // The cocoa backend's desktop is not freedesktop's: the AT-SPI bridge and
   // the D-Bus global menu have nothing to register against there, so they
   // default off (their macOS replacements are their own workstream —
-  // docs/macos.md). The appearance ladder stays on: its macOS rung is the
+  // design/macos.md). The appearance ladder stays on: its macOS rung is the
   // one that answers. An explicit `desktop` option still wins.
   setDesktopIntegration(
     rest.desktop ??

package/src/a11y.js

@@ -1289,7 +1289,7 @@ export function startA11y(app) {
   // presence *is* the capability — the same rule the rest of the library
   // uses. The Windows backend installs one, because UI Automation asks
   // synchronously and has to be answered from a pushed copy rather than from
-  // the live tree (docs/windows.md §Accessibility); AT-SPI's asynchronous
+  // the live tree (design/windows.md §Accessibility); AT-SPI's asynchronous
   // questions are answered from the tree itself, below.
   if (typeof app?.startAccessibility === 'function') {
     startPromise = Promise.resolve()

package/src/backend/context2d.js

@@ -1,7 +1,7 @@
 // A canvas-shaped 2d context over a **verb table** — the drawing dialect
 // every native backend answers, and the one place it is written down.
 //
-// This is macos.md §"The split" step 4, taken when a second native backend
+// This is design/macos.md §"The split" step 4, taken when a second native backend
 // started: the class takes its `native` as a constructor argument and calls
 // nothing else, so one wrapper drives @windowkit/appkit's CoreGraphics verbs
 // and @windowkit/win32's Direct2D verbs alike. A bridge that lacks an
@@ -16,7 +16,7 @@
 //
 // On the surface presenter this is the whole drawing path; on the layer
 // presenter it stays as the fallback every painted-code node (<canvas>,
-// <svg>, registered elements) rasters through — docs/macos.md §"Custom
+// <svg>, registered elements) rasters through — design/macos.md §"Custom
 // drawing on a layer tree".
 //
 // The native surface holds the real graphics state (paths, CTM, clip); this
@@ -322,7 +322,7 @@ const NON_RECT = Symbol('non-rectangular clip');
  * linear in it: 14ms, 29ms, 56ms, 113ms. The driver is the subpath count,
  * not the vertex count — one 26,000-vertex subpath strokes in 4ms where
  * two thousand 13-vertex ones take 208. The full table, the two shapes
- * left whole and why, are in docs/macos.md
+ * left whole and why, are in design/macos.md
  * §"Stroking a path with many subpaths".
  *
  * Note the X11 context wants the opposite — there a stroke is an a8

package/src/bootstrap.js

@@ -4,7 +4,7 @@
 // an app on macOS moves onto a worker (src/cocoa/relaunch.js), and on that
 // worker the same import sets it up. A Windows backend's UI thread will be
 // the addon's own, and X11 has none, so neither needs this step
-// (docs/windows.md §"Three shapes on Windows"). Imported first by
+// (design/windows.md §"Three shapes on Windows"). Imported first by
 // src/index.js, so that it runs before the rest of the package.
 import { isMainThread, workerData } from 'node:worker_threads';
 

package/src/cocoa/app.js

@@ -5,7 +5,7 @@
 // that stands in for the X socket.
 //
 // Two run loops. By default Node's loop is master and a timer pumps AppKit
-// (docs/macos.md §"Input and the run loop", option 1): input waits for the
+// (design/macos.md §"Input and the run loop", option 1): input waits for the
 // pump, and AppKit's modal loops (live resize, menu tracking, a drag) stall
 // JS timers — but not the delegate callbacks, which is why live resize
 // still relayouts: the resize event flushes the frame synchronously on its
@@ -13,7 +13,7 @@
 // Under the launcher (`node --import react-x11/cocoa-main`, src/cocoa/
 // main.js) the app runs on a worker instead, AppKit keeps the main thread
 // in a real `[NSApp run]`, and this object is fed by the bridge's batches
-// (`_routeBatch`) with no pump at all (docs/macos.md §"JS on a worker").
+// (`_routeBatch`) with no pump at all (design/macos.md §"JS on a worker").
 import { isMainThread } from 'node:worker_threads';
 
 import { cssColorStraight } from 'ntk/color';
@@ -64,11 +64,11 @@ const PUMP_INTERVAL_MS = 8;
 // The edge moves when the delegate returns, so the budget is how long a
 // slow frame may hold the drag back. 50 covers what a large tree costs —
 // the Cocoa `resize` cell measures 28ms a tick at 3,662 nodes
-// (docs/macos.md) — with room, where the bridge's own test met every tick
+// (design/macos.md) — with room, where the bridge's own test met every tick
 // in 3.1ms against 3ms of layout. Past three 60Hz frames an edge that waits
 // reads as the drag stuttering, so a tree slower than that lets the edge
 // go first and its frame land after (Flutter's Windows embedder waits up
-// to 100, docs/windows.md §"Resize"). `createRoot({ cocoa: { resizeWait } })`
+// to 100, design/windows.md §"Resize: where the threads meet"). `createRoot({ cocoa: { resizeWait } })`
 // sets it; 0 is no handshake at all.
 const RESIZE_WAIT_MS = 50;
 // What `createRoot({ cocoa: { paneStretch } })` and
@@ -272,7 +272,7 @@ export class CocoaApp {
     }
 
     // 'surface' (the measured default) or 'layers' — the retained CALayer
-    // presenter, opt-in while docs/macos.md's measure-first gate is open.
+    // presenter, opt-in while design/macos.md's measure-first gate is open.
     this._presenterMode =
       options.cocoa?.presenter ??
       process.env.REACT_X11_COCOA_PRESENTER ??
@@ -391,7 +391,7 @@ export class CocoaApp {
 
     // the global-menu exports, newest active: the macOS menu bar is one per
     // app, so the most recent MenuBar owns it (per-focused-window switching
-    // is the follow-up — docs/macos.md §Menus)
+    // is the follow-up — design/macos.md §Menus)
     this._globalMenus = [];
     this._activeGlobalMenu = null;
 

package/src/cocoa/bezels.js

@@ -1,5 +1,5 @@
 // Native control bezels — AppKit's own pixels for the core controls, cached
-// as surfaces the ordinary 2d paint path can blit (docs/macos.md §Native
+// as surfaces the ordinary 2d paint path can blit (design/macos.md §Native
 // controls). The mechanism is offscreen NSCell/NSControl rendering, the
 // WebKit/Gecko form-control technique: interaction, focus and keyboard stay
 // the shared component implementation, and only the *bezel* — the pixels of

package/src/cocoa/fonts.js

@@ -1,6 +1,6 @@
 // The Cocoa text engine: CoreText behind the same `app.fonts` contract ntk's
 // FontManager answers on the X11 backend. The renderer touches exactly this
-// surface (docs/macos.md §"Text: the engine contract"):
+// surface (design/macos.md §"Text: the engine contract"):
 //
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })

package/src/cocoa/globalmenu.js

@@ -1,4 +1,4 @@
-// The macOS menu bar as a global-menu export (docs/macos.md §Menus).
+// The macOS menu bar as a global-menu export (design/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

package/src/cocoa/keymap.js

@@ -23,7 +23,7 @@
 //
 // There is no input method behind this. The bridge's view swallows
 // `keyDown:` without `interpretKeyEvents:` and is no `NSTextInputClient`
-// (docs/macos.md, "IME"), so these fields are all the text there is. Two
+// (design/macos.md, "IME"), so these fields are all the text there is. Two
 // consequences, both handled below:
 //
 // - **A dead key types nothing.** ⌥E on a US layout leaves `chars` empty, and

package/src/cocoa/panewindow.js

@@ -1,4 +1,4 @@
-// The pane process's "window" on the Cocoa backend — docs/frame.md's child
+// The pane process's "window" on the Cocoa backend — design/frame.md's child
 // half, with the X server replaced by shared memory.
 //
 // On X11 a pane renders into a real window of its own and the host embeds

package/src/cocoa/player.js

@@ -1,4 +1,4 @@
-// `<video src>` on macOS (docs/architecture/video.md §3.2, §9): a file or URL
+// `<video src>` on macOS (design/architecture/video.md §3.2, §9): a file or URL
 // played by AVFoundation through @windowkit/appkit's player verbs — the
 // platform's decoder, audio, seeking and HLS — with the picture on the
 // player's own AVPlayerLayer.

package/src/cocoa/presenter.js

@@ -1,4 +1,4 @@
-// The retained layer presenter — Tier L of docs/macos.md: one CALayer per
+// The retained layer presenter — Tier L of design/macos.md: one CALayer per
 // drawn node, React commits landing as property sets inside a single
 // disabled-actions CATransaction per frame, the WindowServer compositing.
 //
@@ -350,7 +350,7 @@ export function stylePaintsPlain(node, style = node.style ?? {}) {
 /**
  * Style property → the key path on a PropBox's own layer, for the
  * animations the presenter takes off the frame clock and hands to the
- * render server (docs/architecture/animation.md §4.2). Only what the layer
+ * render server (design/architecture/animation.md §4.2). Only what the layer
  * expresses as a property of itself qualifies: a colour on `<text>` is a
  * re-raster per frame, a layout property moves the siblings, and both stay
  * on the JS loop. `scaled` values go out in points, as `_syncPropBox`

package/src/cocoa/promotion.js

@@ -36,7 +36,7 @@
 // overlapped, hidden, clipped, faded or non-plain returns to the bitmap in
 // the frame that finds it, the animation handed back to the clock — and a
 // loop the clock runs is offered again once the scene would take it
-// (`wouldTake`), where it is in its cycle. docs/macos.md §"Layer
+// (`wouldTake`), where it is in its cycle. design/macos.md §"Layer
 // promotion" is the account.
 import { now } from '../nodes/animation.js';
 import { BoxNode } from '../nodes/box.js';

package/src/cocoa/relaunch.js

@@ -1,4 +1,4 @@
-// Threaded mode by default (docs/macos.md §"JS on a worker"). On macOS the
+// Threaded mode by default (design/macos.md §"JS on a worker"). On macOS the
 // process main thread is AppKit's — the only thread it lets own a window —
 // and while the app's JS runs there, every menu, drag, live resize and
 // modal panel stops it. So the first import of react-x11 on the main thread

package/src/cocoa/threaded.js

@@ -1,4 +1,4 @@
-// Threaded mode's worker half (docs/macos.md §"JS on a worker: a UI thread
+// Threaded mode's worker half (design/macos.md §"JS on a worker: a UI thread
 // of the bridge's own"): with the launcher (src/cocoa/main.js) holding the
 // process main thread in the bridge's `runMain()`, the app's JS runs on a
 // `worker_threads` Worker, and this module is what that worker needs to

package/src/cocoa/video.js

@@ -1,4 +1,4 @@
-// A video's frames on a layer of their own (docs/architecture/video.md §7):
+// A video's frames on a layer of their own (design/architecture/video.md §7):
 // what the surface presenter's sprites (src/cocoa/sprites.js) do with a part
 // whose `contents` is a `VideoFrames` sink instead of a `paint`.
 //

package/src/cocoa/window.js

@@ -39,7 +39,7 @@ const FENCE_TIMEOUT_MS = 100;
 // (`_takeBack`). Three, a `CAMetalLayer`'s depth, is what an animation
 // mostly needs; an input answered between two of its frames puts two flips
 // inside one refresh, and four kept every write of a clicked 120Hz animation
-// off a held buffer (docs/macos.md, "Measured: the swapchain and the
+// off a held buffer (design/macos.md, "Measured: the swapchain and the
 // WindowServer's hold").
 const MAX_BUFFERS = 4;
 // Past this many rects, what a buffer missed is copied whole: a buffer left
@@ -235,14 +235,14 @@ export class CocoaWindow {
     // change.
     this.damageRectCap = 16;
 
-    // The retained layer presenter (docs/macos.md Tier L), behind
+    // The retained layer presenter (design/macos.md Tier L), behind
     // REACT_X11_COCOA_PRESENTER=layers while the surface path is the
     // measured default. Its hooks exist only in this mode, so the feature
     // detection in src/nodes/ keeps the surface path byte-identical; the
     // scroll blit is shadowed off because a layer frame has no backing
     // bitmap to blit. The last two are the animation seam: a transition or
     // a loop the presenter takes runs in the render server and schedules no
-    // frames here (docs/architecture/animation.md §4).
+    // frames here (design/architecture/animation.md §4).
     if (app._presenterMode === 'layers') {
       this._presenter = new CocoaLayerPresenter(this);
       this.presentFrame = (windowNode) => this._presenter.frame(windowNode);
@@ -659,7 +659,7 @@ export class CocoaWindow {
    * A new size retires the chain, released on the spot (`_releaseBacking`):
    * left to the handles' finalizers, a forty-tick drag of the two-buffer
    * chain this used to be held 800MB until a collection happened to run —
-   * the `rss +80MB` docs/macos.md measured. The layer keeps its own
+   * the `rss +80MB` design/macos.md measured. The layer keeps its own
    * reference to whichever IOSurface it is still showing, so the free is
    * safe while that frame is on glass. A new chain starts with the one
    * buffer its first frame paints: a live-resize tick paints its size once,

package/src/components/Menu.js

@@ -984,7 +984,9 @@ function useMenuAccelerators(
  *
  * The wrapper is focusable and takes focus when the menu opens, because the
  * popup is override-redirect and never gets focus itself — the same trick
- * `Select` uses to keep arrow keys working while its menu is open.
+ * `Select` uses to keep arrow keys working while its menu is open. It is not
+ * a Tab stop: it has no role or name, so Tab landing on it would announce
+ * nothing, and the controls inside are stops of their own.
  */
 export function ContextMenu({
   items = [],
@@ -1087,7 +1089,10 @@ export function ContextMenu({
     'box',
     {
       ref,
-      focusable: true,
+      // focusable by a press and by `focus()` above, but out of the Tab
+      // cycle: a stop here is a nameless "filler" around content whose own
+      // controls are already reachable
+      tabIndex: -1,
       onMouseDown: (ev) => {
         if (ev.button !== 3 && rect) close();
       },

package/src/components/Switch.js

@@ -98,7 +98,7 @@ export function Switch({
   );
 
   // NSSwitch's own pixels, on/off as two cached bezels. The knob slide is
-  // the fidelity this loses for now (docs/macos.md flags the switch as the
+  // the fidelity this loses for now (design/macos.md flags the switch as the
   // one control worth revisiting if that disappoints); the press keeps its
   // answer as the wash, since NSSwitch renders no pressed state offscreen.
   if (nativeControls) {

package/src/components/native.js

@@ -1,4 +1,4 @@
-// The native half of the widget set (docs/macos.md §Native controls).
+// The native half of the widget set (design/macos.md §Native controls).
 //
 // House rule: **default native, seam out.** On a backend that renders the
 // platform's own control bezels — today the Cocoa backend — the core

package/src/dnd.js

@@ -1,7 +1,7 @@
 // XDND drag and drop, the drop-target half: react-x11 windows accept drags
 // from other X11 applications (file managers, editors, browsers).
 //
-// Design: docs/architecture/drag-and-drop.md; protocol: XDND version 5.
+// Design: design/architecture/drag-and-drop.md; protocol: XDND version 5.
 // The advertisement (`XdndAware`) is a 4-byte property written
 // unconditionally on every top-level window at realize time — it creates no
 // X windows, so it is orthogonal to the windowed/windowless split.
@@ -1080,7 +1080,7 @@ export class DropSession {
 // ---------------------------------------------------------------------------
 // The drag source.
 //
-// One drag session, two transports (docs/architecture/drag-and-drop.md §6.3):
+// One drag session, two transports (design/architecture/drag-and-drop.md §6.3):
 // while the pointer is over this process's own windows the drag is local —
 // no wire, live JS payloads, the DropSession above delivering to the same
 // handlers with `e.source === 'internal'`. The moment it leaves them, the

package/src/glnodes.js

@@ -95,7 +95,7 @@ export function glxConfig(app, spec) {
           process.platform === 'win32'
             ? 'react-x11: <glarea> is not built on the win32 backend yet — it ' +
                 'needs ANGLE (EGL and GLES over Direct3D 11), which ' +
-                'docs/windows.md plans as an optional dependency the way ' +
+                'design/windows.md plans as an optional dependency the way ' +
                 'x11-dri is on X11. Everything else on this backend works ' +
                 'without it; for GL content today, use the X11 backend.'
             : 'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',

package/src/grid.js

@@ -1,5 +1,5 @@
 // CSS grid, built in (docs/styling.md "Grid"; the design record is
-// docs/architecture/grid-layout.md). A box with `display: 'grid'` — or
+// design/architecture/grid-layout.md). A box with `display: 'grid'` — or
 // `layout: 'grid'`, the same request under the name every layout goes by —
 // arranges its children by CSS Grid's placement and track sizing algorithms
 // (css-grid-2 §8.5 and §12), inside the pass that lays the window out. It is

package/src/layouts.js

@@ -1,5 +1,5 @@
 // Layout algorithms and positions from outside the renderer — the two seams
-// docs/architecture/custom-layout.md is the design record for.
+// design/architecture/custom-layout.md is the design record for.
 //
 // A **layout** arranges a box's children. It is asked how big the box is for
 // the room on offer, and then where each child goes in the room the box got.

package/src/nodes/animation.js

@@ -310,7 +310,7 @@ export class NodeAnimation {
   // loop-stop rule and `sameAnimation` all see it — but it contributes no
   // value to the style, is skipped by the tick, and keeps the node out of the
   // window's animating set. The X11 path has none of these hooks and is
-  // byte-identical (docs/architecture/animation.md §4).
+  // byte-identical (design/architecture/animation.md §4).
 
   _offload(prop, entry) {
     const wnd = this.root?.window;

package/src/nodes/invalidate.js

@@ -361,7 +361,7 @@ export class WindowInvalidate {
     }
     // 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
+    // (design/macos.md §"One renderer, two presenters"). Feature-detected: an
     // ntk window has no ear here and the X11 path is byte-identical. A
     // presenter that answers `true` has taken the claim onto a layer of its
     // own (src/cocoa/promotion.js): the bitmap owes nothing for it, and the

package/src/nodes/layouthost.js

@@ -2,7 +2,7 @@
 // in layouts.js arranges its children itself. Each child is a yoga root of
 // its own, and the host is a measured leaf in its parent — so what the
 // algorithm decides is on screen in the frame that asked.
-// docs/architecture/custom-layout.md is the design record.
+// design/architecture/custom-layout.md is the design record.
 
 import {
   createLayoutNode,

package/src/nodes/video.js

@@ -1,6 +1,6 @@
 // <video>: frames an application decodes (`frames`, a VideoFrames sink), or a
 // file or URL the platform plays (`src`, where there is a player), fitted
-// into the node's box (docs/architecture/video.md §6–7).
+// into the node's box (design/architecture/video.md §6–7).
 //
 // A drawn node like `<image>`: it joins yoga, it is in the paint order and it
 // is hit like anything else — which is the whole point. A video in a form
@@ -18,9 +18,10 @@
 // - **drawn** — everywhere else, and in every frame the presenter declines
 //   the part (something is painted over it, it fades, a rounded card does
 //   not hold it): the newest frame is copied into a surface of the node's
-//   own at paint, natively where the backend can (`app.writeVideoFrame`) and
-//   through `frameToRGBA` where it cannot, and composited at the picture's
-//   rect like an `<image>` whose pixels changed. A push claims the picture.
+//   own at paint, natively where the backend can (`writeVideoFrame`,
+//   src/videobackend.js) and through `frameToRGBA` where it cannot, and
+//   composited at the picture's rect like an `<image>` whose pixels
+//   changed. A push claims the picture.
 //
 // `src` needs a platform player, which this backend has when
 // `useSupports('mediaPlayback')` says so — the app's `createPlayer`, on macOS
@@ -41,6 +42,7 @@ import {
 } from '../imagesource.js';
 import { canPlayMedia, NoMediaPlaybackError } from '../mediaplayback.js';
 import { Surface } from '../offscreen.js';
+import { videoBackendOf } from '../videobackend.js';
 import { frameToRGBA, isVideoFrames } from '../videoframes.js';
 import { fitRect, objectFitOf } from './fit.js';
 import { intrinsicSize } from './layout.js';
@@ -592,10 +594,18 @@ export class VideoNode extends Node {
   }
 
   _upload(surface, sink, frame) {
-    // natively where the backend converts in its own code (the Cocoa
-    // bridge's writeVideoSurface: a copy for BGRA, VideoToolbox for YCbCr,
-    // colour-matched to what a layer shows)
-    if (this.app?.writeVideoFrame?.(surface, sink, frame)) return;
+    // natively where the backend converts in its own code: the Cocoa
+    // bridge's writeVideoSurface (a copy for BGRA, VideoToolbox for YCbCr,
+    // colour-matched to what a layer shows), the Wayland context's shader,
+    // an Xv port on X11 (src/videobackend.js)
+    if (
+      videoBackendOf(this.app)?.writeVideoFrame?.(surface, sink, frame, this)
+    ) {
+      // a frame converted in JavaScript earlier — the first, on X11, before
+      // the window was mapped — left a buffer the native path does not need
+      this._rgba = null;
+      return;
+    }
     const w = sink.width;
     const h = sink.height;
     if (this._rgba?.width !== w || this._rgba?.height !== h) {
@@ -632,6 +642,7 @@ export class VideoNode extends Node {
     this._surface = null;
     this._rgba = null;
     this._drawn = -1;
+    if (surface) videoBackendOf(this.app)?.releaseVideoFrame?.(surface);
     try {
       surface?.destroy();
     } catch {

package/src/nodes/window/droptarget.js

@@ -1,4 +1,4 @@
-// The window's half of XDND (docs/architecture/drag-and-drop.md): the drop
+// The window's half of XDND (design/architecture/drag-and-drop.md): the drop
 // targets registered under it and the types they accept.
 
 import {

package/src/pacing.js

@@ -49,7 +49,7 @@
 // Off by default: `'display'` is the built-in, and paints every frame the
 // clock gives, after React's own batching — a UI answers its input as
 // quickly as it can unless it says otherwise. `'adaptive'` is what a window
-// that streams asks for. docs/architecture/frame-pacing.md is the account.
+// that streams asks for. design/architecture/frame-pacing.md is the account.
 
 export const DEFAULT_FRAME_RATE = 'display';
 

package/src/refresh/index.js

@@ -1,6 +1,7 @@
 // react-x11/refresh — the runtime half of state-preserving hot reload
 // (Fast Refresh). The loader half is ./loader.js; `react-x11/refresh/register`
-// wires both up for `node --import`. See docs/ecosystem/dev-tooling.md.
+// wires both up for `node --import`. See docs/ecosystem/dev-tooling.md, and
+// design/ecosystem/dev-tooling.md §"How it reloads" for the loader's rules.
 //
 // Import order is what this module exists to own:
 //

package/src/types/video.d.ts

@@ -69,8 +69,11 @@ export class VideoFrames {
   readonly colorSpace: VideoColorSpace;
   readonly range: VideoRange;
   /** This display's formats, cheapest first: what a decoder that can choose
-   * should emit (`ffmpeg -pix_fmt nv12`). NV12 leads where a frame goes on
-   * a layer as it is — macOS — and BGRA wherever a 2D context draws it. */
+   * should emit (`ffmpeg -pix_fmt nv12`). NV12 leads wherever something
+   * native takes it as it is — a layer on macOS, a shader on Wayland, an Xv
+   * port on X11 — and BGRA where a frame is converted in JavaScript. On X11
+   * it is BGRA, and not kept, until the port has answered, a few round
+   * trips after the first sink is made. */
   readonly preferredFormats: readonly VideoFormat[];
   /** Frames pushed so far. */
   readonly version: number;

package/src/videobackend.js

@@ -0,0 +1,28 @@
+// Who writes a `<video>`'s frames natively on an app, if anyone — the seam
+// `VideoFrames.preferredFormats` and the drawn presentation ask through
+// (design/architecture/video.md §6.3).
+//
+// The app itself where its backend has the verbs: the Cocoa app over the
+// bridge's video surfaces, the Wayland app over its own GL context. On X11
+// the app is ntk's, which knows nothing of sinks, so the answer is the Xv
+// writer react-x11 keeps for the connection (src/xvideo.js). A feature test,
+// not a question about which backend this is — `typeof app.xv` is an ntk
+// with XVideo discovery. Null where nothing will, and every frame is
+// converted in JavaScript (`frameToRGBA`, src/videoframes.js).
+import { xvVideoFor } from './xvideo.js';
+
+/**
+ * `{ videoFormats(), writeVideoFrame(surface, sink, frame, node),
+ * releaseVideoFrame?(surface), prepare?(sink) }` for `app`, or null.
+ */
+export function videoBackendOf(app) {
+  if (!app) return null;
+  if (
+    typeof app.writeVideoFrame === 'function' ||
+    typeof app.videoFormats === 'function'
+  ) {
+    return app;
+  }
+  if (typeof app.xv === 'function') return xvVideoFor(app);
+  return null;
+}

package/src/videoframes.js

@@ -1,5 +1,5 @@
 // `VideoFrames`: a sink an application pushes decoded video frames into,
-// and a `<video frames>` shows (docs/architecture/video.md §6.3).
+// and a `<video frames>` shows (design/architecture/video.md §6.3).
 //
 // react-x11 decodes nothing. Where the bytes come from — an `ffmpeg` child
 // writing rawvideo to a pipe, a WASM decoder, an addon over libmpv — is the
@@ -33,12 +33,16 @@
 //   a decoder that can choose (`ffmpeg -pix_fmt`); one that cannot still
 //   works, with the conversion charged where it happens.
 //
-// Pure: no node, no backend. The app is asked for its formats
-// (`app.videoFormats()`, the Cocoa app's answer from the bridge) and nothing
-// else.
+// No node and no backend: the one question asked of the display is its
+// formats, through `videoBackendOf` (src/videobackend.js) — the Cocoa app's
+// answer from the bridge, the Wayland app's own, and on X11 the Xv writer's,
+// which a sink starts asking for when it is made.
+
+import { videoBackendOf } from './videobackend.js';
 
 export const VIDEO_FORMATS = Object.freeze(['NV12', 'I420', 'BGRA']);
 const COLOR_SPACES = ['bt709', 'bt601', 'bt2020'];
+const BGRA_ONLY = Object.freeze(['BGRA']);
 const RANGES = ['video', 'full'];
 // The largest side a frame may have: a surface's limit on every backend, and
 // a number past which a size is a bug rather than a video.
@@ -209,22 +213,30 @@ export class VideoFrames {
     this._frame = null;
     this._listeners = new Set();
     this._preferred = null;
+    // On X11 the formats are a port's, and asking for one is round trips:
+    // started here, so they are known by the time a decoder that waits for
+    // anything at all — a probe of the file, a spawn — reads them.
+    videoBackendOf(app)?.prepare?.(this);
   }
 
   /**
    * This display's formats, cheapest first: what a decoder that can choose
-   * should emit. NV12 first where a frame can go on a layer as it is
-   * (Cocoa); BGRA first wherever a 2D context draws it.
+   * should emit. YCbCr first wherever something native takes it as it is —
+   * a layer on Cocoa, a shader on Wayland, an Xv port on X11 — and BGRA
+   * first where a frame is converted in JavaScript on its way to a 2D
+   * context. On X11 the answer is BGRA until the port has answered, a few
+   * round trips after the first sink is made, and is not kept until then.
    */
   get preferredFormats() {
-    if (this._preferred === null) {
-      const asked = this.app?.videoFormats?.();
-      this._preferred = Object.freeze(
-        Array.isArray(asked) && asked.length !== 0
-          ? asked.filter((f) => VIDEO_FORMATS.includes(f))
-          : ['BGRA'],
-      );
-    }
+    if (this._preferred !== null) return this._preferred;
+    const asked = videoBackendOf(this.app)?.videoFormats?.();
+    // null: still being asked — answer for now, and ask again next time
+    if (asked === null) return BGRA_ONLY;
+    this._preferred = Object.freeze(
+      Array.isArray(asked) && asked.length !== 0
+        ? asked.filter((f) => VIDEO_FORMATS.includes(f))
+        : ['BGRA'],
+    );
     return this._preferred;
   }
 
@@ -281,8 +293,9 @@ export const isVideoFrames = (v) => v instanceof VideoFrames;
 
 // --- converting a frame where nothing native will ----------------------------
 //
-// The drawn path on a backend with no native write (X11, win32, Wayland, a
-// Cocoa bridge older than its video surfaces): the frame converted here to
+// The drawn path where nothing native writes the frame (win32, an X server
+// with no Xv adaptor, a Cocoa bridge older than its video surfaces, and on
+// any backend a frame the native writer declines): the frame converted here to
 // the straight RGBA `putImageData` takes. Not free — two million pixels a
 // frame at 1080p — which is why `preferredFormats` says BGRA first there.
 // The matrix and the range are the frame's; no transfer function is