react-x11 2.52.0 → 2.54.0

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/ntk.d.ts

@@ -115,8 +115,20 @@ export interface DecodedImage {
  */
 export function decodeImageBytes(
   bytes: Uint8Array,
+  options?: DecodeImageOptions,
 ): DecodedImage | Promise<DecodedImage>;
 
+/** How `decodeImageBytes` decodes. */
+export interface DecodeImageOptions {
+  /**
+   * Decode on a worker thread where the runtime decodes in JavaScript (Node),
+   * for bytes long enough to pay for the trip: the answer is then a promise
+   * for a PNG and a JPEG too. Under Bun every decode is off the thread
+   * already.
+   */
+  offThread?: boolean;
+}
+
 /** `code` values on a failed GL setup — see `<glarea onError>`. */
 export const GLXError: {
   NO_EXTENSION: 'GLX_NO_EXTENSION';

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

package/src/wayland/app.js

@@ -30,6 +30,7 @@ import { releaseDevice } from './device.js';
 import { WaylandSeat } from './seat.js';
 import { WaylandBackendWindow } from './backendwindow.js';
 import { WaylandSurface } from './surface.js';
+import { releaseVideoFrame, writeVideoFrame } from './video.js';
 import { InputRouter } from './input.js';
 import { WaylandTouch } from './touch.js';
 import { WaylandTablet } from './tablet.js';
@@ -440,6 +441,32 @@ export class WaylandApp extends EventEmitter {
     return new WaylandSurface(this, options);
   }
 
+  /**
+   * The formats a `VideoFrames` sink is cheapest in here
+   * (`preferredFormats`, src/videoframes.js): all three, YCbCr first. Every
+   * one goes up as textures as it is and is converted by a shader
+   * (src/wayland/video.js), and NV12 or I420 is less than half of BGRA's
+   * bytes on the way.
+   */
+  videoFormats() {
+    return ['NV12', 'I420', 'BGRA'];
+  }
+
+  /**
+   * A `<video>`'s frame into `surface`, its drawn presentation, on the GPU:
+   * planes as textures, the matrix in a fragment shader. False where the
+   * frame cannot be — a size past the GPU's textures — and the node
+   * converts it in JavaScript instead (src/nodes/video.js).
+   */
+  writeVideoFrame(surface, sink, frame) {
+    return writeVideoFrame(this, surface, sink, frame);
+  }
+
+  /** The node let `surface` go: its plane textures go too. */
+  releaseVideoFrame(surface) {
+    releaseVideoFrame(this, surface);
+  }
+
   /**
    * What the machine can do, as a promise like the X11 and Cocoa answers
    * (src/glbackend.js chains on it): here the answer was settled when the

package/src/wayland/video.js

@@ -0,0 +1,376 @@
+// `<video frames>` on Wayland: a frame's planes go up as textures as the
+// decoder made them, and the colour conversion is a fragment shader drawing
+// into the `<video>`'s own surface (design/architecture/video.md §5).
+//
+// The backend's 2D context is already a GLES rasterizer, so this is the GLX
+// transport of §2.3 made native: no conversion in JavaScript for any format,
+// and NV12 and I420 cross into the GPU at 1.5 bytes a pixel. Y is an R8
+// texture; NV12's chroma one RG8 texture at half size, I420's two R8 ones;
+// BGRA one RGBA8 texture read back to front. The shader applies the sink's
+// matrix and range exactly as `frameToRGBA` does — no transfer function,
+// because nothing else on this backend is colour-managed either — so a frame
+// drawn here and one converted in JavaScript are the same picture, chroma
+// apart: sampled bilinearly here, as a player does, and by nearest there.
+//
+// What it writes into is the surface the drawn presentation already keeps
+// (src/nodes/video.js): a render target, which the window's context then
+// composites at the picture's rect like any `drawImage`. Nothing lifts on
+// Wayland — no subsurfaces, by the backend's own design — so this is the
+// whole presentation.
+//
+// The GL is shared with every 2D context on the app (device.js): whatever
+// the device's owner still has buffered is drawn before the target is
+// written, the shader's vertex state lives in a vertex array of its own,
+// and the device is released afterwards so the next context to draw puts
+// its own state back. `UNPACK_ROW_LENGTH`, which a decoder's padded rows
+// need, is set back to 0 for the uploads that assume it.
+
+import { flushDevice, releaseDevice } from './device.js';
+
+const VERT = `
+attribute vec2 aPos;
+attribute vec2 aUV;
+varying vec2 vUV;
+void main() {
+  vUV = aUV;
+  gl_Position = vec4(aPos, 0.0, 1.0);
+}`;
+
+const FRAG = `
+#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+varying vec2 vUV;
+uniform int uLayout;
+uniform sampler2D uY;
+uniform sampler2D uC;
+uniform sampler2D uV;
+uniform vec2 uChroma;
+uniform mat3 uMatrix;
+uniform vec3 uOffset;
+void main() {
+  if (uLayout == 0) {
+    // BGRA bytes uploaded as RGBA: blue is in r. Opaque, whatever the
+    // fourth byte held.
+    gl_FragColor = vec4(texture2D(uY, vUV).bgr, 1.0);
+    return;
+  }
+  float y = texture2D(uY, vUV).r;
+  vec2 cuv = vUV * uChroma;
+  vec2 c = uLayout == 1
+    ? texture2D(uC, cuv).rg
+    : vec2(texture2D(uC, cuv).r, texture2D(uV, cuv).r);
+  vec3 rgb = uMatrix * (vec3(y, c) - uOffset);
+  gl_FragColor = vec4(clamp(rgb, 0.0, 1.0), 1.0);
+}`;
+
+const LAYOUT = { BGRA: 0, NV12: 1, I420: 2 };
+
+// Kr and Kb, as src/videoframes.js has them
+const MATRIX = {
+  bt709: [0.2126, 0.0722],
+  bt601: [0.299, 0.114],
+  bt2020: [0.2627, 0.0593],
+};
+
+const matrices = new Map();
+
+/**
+ * The column-major mat3 and the offset that take normalized Y'CbCr to
+ * R'G'B' for a matrix and a range — the same numbers `frameToRGBA`'s tables
+ * are made of, in units of 1 rather than of 255.
+ */
+export function videoMatrix(colorSpace, range) {
+  const key = `${colorSpace}/${range}`;
+  let m = matrices.get(key);
+  if (m) return m;
+  const [kr, kb] = MATRIX[colorSpace];
+  const kg = 1 - kr - kb;
+  const full = range === 'full';
+  const ys = full ? 1 : 255 / 219;
+  const cs = full ? 1 : 255 / 224;
+  m = {
+    matrix: Float32Array.of(
+      // the column Y' multiplies
+      ys,
+      ys,
+      ys,
+      // Cb
+      0,
+      -cs * ((2 * kb * (1 - kb)) / kg),
+      cs * 2 * (1 - kb),
+      // Cr
+      cs * 2 * (1 - kr),
+      -cs * ((2 * kr * (1 - kr)) / kg),
+      0,
+    ),
+    offset: Float32Array.of(full ? 0 : 16 / 255, 128 / 255, 128 / 255),
+  };
+  matrices.set(key, m);
+  return m;
+}
+
+/** The planes of a frame as textures: format, size and the bytes per texel
+ *  `UNPACK_ROW_LENGTH` counts a decoder's stride in. */
+function planesOf(gl, format, width, height) {
+  const cw = Math.ceil(width / 2);
+  const ch = Math.ceil(height / 2);
+  const r8 = { internal: gl.R8, format: gl.RED, texel: 1 };
+  switch (format) {
+    case 'NV12':
+      return [
+        { ...r8, width, height },
+        { internal: gl.RG8, format: gl.RG, texel: 2, width: cw, height: ch },
+      ];
+    case 'I420':
+      return [
+        { ...r8, width, height },
+        { ...r8, width: cw, height: ch },
+        { ...r8, width: cw, height: ch },
+      ];
+    case 'BGRA':
+      return [{ internal: gl.RGBA, format: gl.RGBA, texel: 4, width, height }];
+  }
+  return null;
+}
+
+/** One per GL device: the program, and the quad it draws. */
+const programs = new WeakMap();
+
+function programFor(gl) {
+  let p = programs.get(gl);
+  if (p) return p;
+  const vs = compile(gl, gl.VERTEX_SHADER, VERT, 'video vertex');
+  let fs;
+  try {
+    fs = compile(gl, gl.FRAGMENT_SHADER, FRAG, 'video fragment');
+  } catch (err) {
+    gl.deleteShader(vs);
+    throw err;
+  }
+  const program = gl.createProgram();
+  gl.attachShader(program, vs);
+  gl.attachShader(program, fs);
+  gl.linkProgram(program);
+  const linked = gl.getProgramParameter(program, gl.LINK_STATUS);
+  const log = linked ? '' : gl.getProgramInfoLog(program);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!linked) {
+    gl.deleteProgram(program);
+    throw new Error(`video program failed to link: ${log}`);
+  }
+  const u = (name) => gl.getUniformLocation(program, name);
+  const aPos = gl.getAttribLocation(program, 'aPos');
+  const aUV = gl.getAttribLocation(program, 'aUV');
+  // A strip over the whole target. The 2D context draws device row 0 at the
+  // top of clip space, so the frame's first row — texture row 0 — goes
+  // there: v = 0 at clip y = +1.
+  const buffer = gl.createBuffer();
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+  gl.bufferData(
+    gl.ARRAY_BUFFER,
+    Float32Array.of(-1, 1, 0, 0, -1, -1, 0, 1, 1, 1, 1, 0, 1, -1, 1, 1),
+    gl.STATIC_DRAW,
+  );
+  // its own vertex array, so the 2D contexts' attribute state — on the
+  // default one, re-pointed every batch — is never this program's
+  const vao = gl.createVertexArray();
+  gl.bindVertexArray(vao);
+  gl.enableVertexAttribArray(aPos);
+  gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 16, 0);
+  gl.enableVertexAttribArray(aUV);
+  gl.vertexAttribPointer(aUV, 2, gl.FLOAT, false, 16, 8);
+  gl.bindVertexArray(null);
+  p = {
+    program,
+    buffer,
+    vao,
+    maxSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
+    loc: {
+      uLayout: u('uLayout'),
+      uY: u('uY'),
+      uC: u('uC'),
+      uV: u('uV'),
+      uChroma: u('uChroma'),
+      uMatrix: u('uMatrix'),
+      uOffset: u('uOffset'),
+    },
+  };
+  programs.set(gl, p);
+  return p;
+}
+
+/** Each surface's plane textures, kept across frames of one size. */
+const uploads = new WeakMap();
+
+function texturesFor(gl, surface, format, width, height) {
+  let kept = uploads.get(surface);
+  if (
+    kept &&
+    kept.format === format &&
+    kept.width === width &&
+    kept.height === height
+  ) {
+    return kept;
+  }
+  if (kept) deleteTextures(gl, kept);
+  const planes = planesOf(gl, format, width, height);
+  kept = {
+    format,
+    width,
+    height,
+    planes,
+    textures: planes.map(() => gl.createTexture()),
+    fresh: true,
+  };
+  uploads.set(surface, kept);
+  return kept;
+}
+
+function deleteTextures(gl, kept) {
+  for (const tex of kept.textures) gl.deleteTexture(tex);
+  kept.textures = [];
+}
+
+/**
+ * A plane's rows at a stride `UNPACK_ROW_LENGTH` cannot say — one that is
+ * not a whole number of texels — packed tight. Every decoder pads to whole
+ * pixels, so this is the case that should never come.
+ */
+function tight(data, stride, rowBytes, rows) {
+  const out = new Uint8Array(rowBytes * rows);
+  for (let r = 0; r < rows; r++) {
+    out.set(data.subarray(r * stride, r * stride + rowBytes), r * rowBytes);
+  }
+  return out;
+}
+
+/**
+ * `frame` from `sink` into `surface` (a WaylandSurface at the frame's size).
+ * False — and the frame is converted in JavaScript instead — where the
+ * surface is not one of this backend's, the app has no GL, or the frame is
+ * larger than a texture can be.
+ */
+export function writeVideoFrame(app, surface, sink, frame) {
+  const gl = app?.gl;
+  const target = surface?.target;
+  if (!gl || !target?.fbo || target.destroyed) return false;
+  if (!(sink.format in LAYOUT)) return false;
+  app.makeCurrent();
+  const p = programFor(gl);
+  if (sink.width > p.maxSize || sink.height > p.maxSize) return false;
+  // Anything a context still has buffered is drawn first: one of its draws
+  // may read this target, and must read the frame it was given (device.js).
+  flushDevice(gl);
+  const kept = texturesFor(gl, surface, sink.format, sink.width, sink.height);
+  try {
+    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+    kept.planes.forEach((plane, i) => {
+      const rowBytes = plane.width * plane.texel;
+      const stride = frame.strides[i];
+      let data = frame.planes[i];
+      let rowLength = 0;
+      if (stride !== rowBytes) {
+        if (stride % plane.texel === 0) rowLength = stride / plane.texel;
+        else data = tight(data, stride, rowBytes, plane.height);
+      }
+      gl.pixelStorei(gl.UNPACK_ROW_LENGTH, rowLength);
+      gl.activeTexture(gl.TEXTURE0 + i);
+      gl.bindTexture(gl.TEXTURE_2D, kept.textures[i]);
+      if (kept.fresh) {
+        // Y and BGRA meet the target texel for texel; chroma is half size,
+        // and read between its samples as a player reads it
+        const filter = i === 0 ? gl.NEAREST : gl.LINEAR;
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texImage2D(
+          gl.TEXTURE_2D,
+          0,
+          plane.internal,
+          plane.width,
+          plane.height,
+          0,
+          plane.format,
+          gl.UNSIGNED_BYTE,
+          data,
+        );
+      } else {
+        gl.texSubImage2D(
+          gl.TEXTURE_2D,
+          0,
+          0,
+          0,
+          plane.width,
+          plane.height,
+          plane.format,
+          gl.UNSIGNED_BYTE,
+          data,
+        );
+      }
+    });
+    kept.fresh = false;
+
+    target.bind();
+    gl.disable(gl.BLEND);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.disable(gl.STENCIL_TEST);
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.CULL_FACE);
+    gl.colorMask(true, true, true, true);
+    gl.useProgram(p.program);
+    const { loc } = p;
+    gl.uniform1i(loc.uLayout, LAYOUT[sink.format]);
+    gl.uniform1i(loc.uY, 0);
+    gl.uniform1i(loc.uC, 1);
+    gl.uniform1i(loc.uV, 2);
+    // full-size texture coordinates onto a chroma plane rounded up: an odd
+    // frame's last chroma column covers one picture column, not two
+    gl.uniform2f(
+      loc.uChroma,
+      sink.width / (2 * Math.ceil(sink.width / 2)),
+      sink.height / (2 * Math.ceil(sink.height / 2)),
+    );
+    const { matrix, offset } = videoMatrix(sink.colorSpace, sink.range);
+    gl.uniformMatrix3fv(loc.uMatrix, false, matrix);
+    gl.uniform3fv(loc.uOffset, offset);
+    gl.bindVertexArray(p.vao);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+    gl.bindVertexArray(null);
+  } finally {
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0);
+    gl.activeTexture(gl.TEXTURE0);
+    // the program, the blend and the framebuffer were the 2D contexts' to
+    // say: the next one to draw says them again
+    releaseDevice(gl);
+    app.rebindWindowTarget?.();
+  }
+  return true;
+}
+
+/** `surface` is let go: its plane textures with it. */
+export function releaseVideoFrame(app, surface) {
+  const kept = uploads.get(surface);
+  if (!kept) return;
+  uploads.delete(surface);
+  const gl = app?.gl;
+  if (!gl) return;
+  app.makeCurrent();
+  deleteTextures(gl, kept);
+}
+
+function compile(gl, type, src, what) {
+  const sh = gl.createShader(type);
+  gl.shaderSource(sh, src);
+  gl.compileShader(sh);
+  if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(sh);
+    gl.deleteShader(sh);
+    throw new Error(`${what} shader failed to compile: ${log}`);
+  }
+  return sh;
+}

package/src/win32/a11y.js

@@ -7,7 +7,7 @@
 // property reads — so answering from JS would pace the screen reader by the
 // application's busiest moment. The bridge therefore *pushes*, and
 // `windows/src/uia.cc` answers from its copy. The reasoning is
-// docs/windows.md §"Accessibility: UI Automation"; what matters here is the
+// design/windows.md §"Accessibility: UI Automation"; what matters here is the
 // consequence: **this file's job is a diff, not an answer.**
 //
 // Everything it pushes comes from `src/a11y.js`, which is pure functions over

package/src/win32/app.js

@@ -362,7 +362,7 @@ export class Win32App {
     // `embeddable` is "created, not shown; somebody else will place me", and
     // on this backend that cannot be a window: a composition target stops
     // presenting the moment its window becomes a child, so an HWND is not
-    // something another process can take (docs/windows-embedding.md). What a
+    // something another process can take (design/windows-embedding.md). What a
     // host can take is the **buffer**, so an embeddable window here is the
     // same shared surface a `<Frame>` pane draws into — whether this process
     // was forked as a pane or is a guest somebody else started.
@@ -825,7 +825,7 @@ export class Win32App {
         break;
       }
       case 'dpichanged':
-        // The renderer cannot re-scale a live window yet (docs/windows.md
+        // The renderer cannot re-scale a live window yet (design/windows.md
         // §Layout, open question 8), so this is recorded and not acted on.
         wnd.emit('statechange', { scale: event.a / 96 });
         break;