react-x11 2.31.0 → 2.33.0

package/src/styles.js

@@ -6,6 +6,7 @@
 import { cssColorStraight } from 'ntk/color';
 
 import { parseBoxShadow, parseLinearGradient } from './decorations.js';
+import { OBJECT_FITS } from './nodes/fit.js';
 import {
   validateGridValue,
   GRID_CONTAINER_PROPS,
@@ -575,6 +576,9 @@ const STYLE_PROPS = new Set([
   ...TEXT_PAINT_PROPS,
   'color',
   'borderStyle',
+  // Where an `<image>`'s or a `<video>`'s picture goes in its box — CSS's
+  // `object-fit`. Paint: the box is laid out the same whichever it is.
+  'objectFit',
   'transition',
   // a loop rather than a change with an end — see `animationsOf`
   'animation',
@@ -938,6 +942,13 @@ function validateValue(key, value, where) {
     }
     return;
   }
+  if (key === 'objectFit') {
+    if (value == null || OBJECT_FITS.includes(value) || isToken(value)) return;
+    throw new Error(
+      `react-x11: invalid objectFit ${JSON.stringify(value)} in ${where} ` +
+        `(expected ${OBJECT_FITS.map((v) => `'${v}'`).join(', ')})`,
+    );
+  }
   if (key === 'opacity') {
     // unset, the way a conditional writes it: `opacity: dim ? 0.5 : undefined`
     if (value == null) return;
@@ -1189,6 +1200,8 @@ const NOT_ANIMATABLE = new Set([
   'cursor',
   'pointerEvents',
   'borderStyle',
+  // a keyword: there is no halfway between filling a box and covering it
+  'objectFit',
   'fontFamily',
   'fontWeight',
   'fontStyle',
@@ -2269,11 +2282,13 @@ export function paintPropsChanged(props, oldProps = {}) {
   for (const key of PAINT_PROPS) {
     if (props[key] !== oldProps[key]) return true;
   }
-  // `color` and `borderStyle` paint but are deliberately not in PAINT_PROPS:
-  // that set also decides what a state block is allowed to set, and widening
-  // it would change validation rather than just this comparison
+  // `color`, `borderStyle` and `objectFit` paint but are deliberately not in
+  // PAINT_PROPS: that set also decides what a state block is allowed to set,
+  // and widening it would change validation rather than just this comparison
   return (
-    props.color !== oldProps.color || props.borderStyle !== oldProps.borderStyle
+    props.color !== oldProps.color ||
+    props.borderStyle !== oldProps.borderStyle ||
+    props.objectFit !== oldProps.objectFit
   );
 }
 

package/src/types/elements.d.ts

@@ -11,8 +11,10 @@ import type {
   NtkWindow,
   ScrollableNode,
   TextInputNode,
+  VideoNode,
 } from './nodes.js';
 import type { AnchorOptions, ScreenAnchorRect } from './components.js';
+import type { VideoFrames, VideoMetadataEvent } from './video.js';
 import type {
   ChangeEvent,
   SelectionChangeEvent,
@@ -904,6 +906,57 @@ export interface ImageProps extends DrawnProps<DrawnNode> {
 // style size, the source's own size (stated, for the server-side sources)
 // is the natural one, kept to its aspect ratio.
 
+/**
+ * `<video>`: frames the application decodes (`frames`), or a file or URL the
+ * platform plays (`src`, where `useSupports('mediaPlayback')` is true),
+ * fitted into the box by `objectFit` — `'contain'` unless the style says
+ * otherwise, with `backgroundColor` in the bars. Laid out at the stream's
+ * size in logical pixels, kept to its ratio when the style names one axis;
+ * before that is known, the poster's, and then HTML's 300x150.
+ *
+ * On macOS the picture goes on a layer of its own while nothing is painted
+ * over it, and every `push` reaches the screen with no frame of the window's
+ * own; elsewhere, and whenever something overlaps it, it is drawn in paint
+ * order like an `<image>` whose pixels changed. `borderRadius` on an
+ * ancestor that clips it costs the layer, not the picture.
+ */
+export interface VideoProps extends DrawnProps<VideoNode> {
+  /** A sink the application pushes decoded frames into
+   * (`useVideoFrames`). Works on every backend. */
+  frames?: VideoFrames;
+  /**
+   * A path or URL the platform plays itself. Where there is no player the
+   * element reports one `NoMediaPlaybackError` through `onError`, on a
+   * microtask, and shows its poster. Exclusive with `frames`: passing both
+   * throws.
+   */
+  src?: string;
+  /** Shown until there is a frame, and whenever there is none — an
+   * `<image src>` value. */
+  poster?: ImageSource;
+  /** HTML's names and defaults: nothing plays until asked. For `src`; a
+   * sink plays what it is pushed. */
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  /** 0 to 1. */
+  volume?: number;
+  playbackRate?: number;
+  /** Controlled when present; the element plays or pauses to match. */
+  paused?: boolean;
+  /** The stream's size is known — for a sink, once it is mounted. */
+  onLoadedMetadata?: (ev: VideoMetadataEvent) => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  /** A few times a second while playing, as HTML's is, and after a seek. */
+  onTimeUpdate?: (ev: { currentTime: number; node: VideoNode }) => void;
+  /** The source failed, or this backend has no player for `src`
+   * (`NoMediaPlaybackError`). Without a handler the failure is a console
+   * warning. */
+  onError?: (err: Error) => void;
+}
+
 /** What `onDraw` is told about the node it is painting. */
 export interface DrawInfo {
   /**
@@ -1075,6 +1128,7 @@ export interface ReactX11Elements {
   textinput: TextInputProps;
   textarea: TextAreaProps;
   image: ImageProps;
+  video: VideoProps;
   canvas: CanvasProps;
   svg: SvgProps;
   glarea: GlAreaProps;

package/src/types/nodes.d.ts

@@ -157,6 +157,25 @@ export interface ScrollableNode extends DrawnNode {
 }
 
 /** `<textinput>` / `<textarea>`. */
+/**
+ * A `<video>`, as its `ref` sees it: HTMLMediaElement's imperative half.
+ * `play`, `pause` and `seek` act on `src`'s player and do nothing for a sink,
+ * which plays what it is pushed.
+ */
+export interface VideoNode extends DrawnNode {
+  /** Play — from the start if the item has ended. */
+  play(): void;
+  pause(): void;
+  /** To `seconds` in, exactly. */
+  seek(seconds: number): void;
+  /** Seconds in; for a sink, its newest frame's `time`, or 0. */
+  readonly currentTime: number;
+  /** Seconds; `Infinity` for a live stream and for a sink, NaN before it is
+   * known. */
+  readonly duration: number;
+  readonly paused: boolean;
+}
+
 export interface TextInputNode extends DrawnNode {
   /**
    * The control's current text. Inside an `onChange` handler this is the

package/src/types/style.d.ts

@@ -72,6 +72,15 @@ export type JustifyItems = 'flex-start' | 'center' | 'flex-end' | 'stretch';
 export type JustifySelf = 'auto' | JustifyItems;
 export type Overflow = 'visible' | 'hidden' | 'scroll';
 export type BorderStyle = 'solid' | 'dashed';
+/**
+ * Where an `<image>`'s or a `<video>`'s picture goes in its content box —
+ * CSS's `object-fit`, centred. `'fill'` stretches it to the box (`<image>`'s
+ * default); `'contain'` fits it inside, with bars of the background
+ * (`<video>`'s); `'cover'` fills the box and cuts what overflows; `'none'`
+ * keeps its own size; `'scale-down'` is the smaller of `'none'` and
+ * `'contain'`.
+ */
+export type ObjectFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
 /**
  * Whether the pointer can land on a node. `'none'`: not on it nor anything
  * inside it. `'box-none'` (React Native's): not on the node itself, but on
@@ -450,6 +459,8 @@ export type HitSlop =
 /** Every property a style may set, before the block forms. */
 export interface StyleProperties extends LayoutStyle, PaintStyle, TextStyle {
   borderStyle?: BorderStyle;
+  /** `<image>` and `<video>`: where the picture goes in the box. */
+  objectFit?: ObjectFit;
   cursor?: Cursor;
   pointerEvents?: PointerEvents;
   /**

package/src/types/video.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Video: frames an application decodes into a sink, and the platform's own
+ * player behind `<video src>` (docs/elements.md#video).
+ */
+
+import type { NtkApp } from './nodes.js';
+
+/**
+ * How a frame's bytes are laid out. `'NV12'`: a Y plane, then one plane of
+ * Cb/Cr pairs at half the size each way — what a hardware decoder emits.
+ * `'I420'`: Y, Cb, Cr, three planes, the chroma at half size — `yuv420p`,
+ * most software decoders' default. `'BGRA'`: four bytes a pixel, blue first;
+ * the fourth byte is ignored, since a frame is opaque.
+ */
+export type VideoFormat = 'NV12' | 'I420' | 'BGRA';
+
+/** The formats, in the order they are listed in. */
+export const VIDEO_FORMATS: readonly VideoFormat[];
+
+/** What a YCbCr frame's numbers mean — the matrix and the primaries. SDR
+ * only. */
+export type VideoColorSpace = 'bt709' | 'bt601' | 'bt2020';
+
+/** `'video'` puts black at 16 and white at 235; `'full'` at 0 and 255. */
+export type VideoRange = 'video' | 'full';
+
+export interface VideoFramesOptions {
+  /** The frame size in whole pixels — source pixels, which `<video>` lays
+   * out as logical pixels, as `<image>` does. */
+  width: number;
+  height: number;
+  /** `'BGRA'` when left out. A decoder that can choose asks
+   * `preferredFormats`. */
+  format?: VideoFormat;
+  /** `'bt709'` when left out. */
+  colorSpace?: VideoColorSpace;
+  /** `'video'` when left out. */
+  range?: VideoRange;
+}
+
+/** One pushed frame, as a sink holds it. */
+export interface VideoFrame {
+  /** One view per plane, over the bytes `push` was handed — not copied. */
+  readonly planes: readonly Uint8Array[];
+  /** Each plane's bytes per row. */
+  readonly strides: readonly number[];
+  /** The presentation time `push` was given, in seconds, or null. */
+  readonly time: number | null;
+  /** Which push this was, counting from 1. */
+  readonly version: number;
+}
+
+export interface VideoPushOptions {
+  /** Each plane's bytes per row, when a decoder pads them; packed when left
+   * out. */
+  strides?: number[];
+  /** The frame's presentation time in seconds, kept as `frame.time`. */
+  time?: number;
+}
+
+/**
+ * Where decoded frames go to be shown, and what `<video frames>` takes. The
+ * newest frame is the frame: a push replaces the last, shown or not.
+ */
+export class VideoFrames {
+  readonly width: number;
+  readonly height: number;
+  readonly format: VideoFormat;
+  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. */
+  readonly preferredFormats: readonly VideoFormat[];
+  /** Frames pushed so far. */
+  readonly version: number;
+  /** The newest frame, or null before the first push and after `close()`. */
+  readonly frame: VideoFrame | null;
+  readonly closed: boolean;
+  /**
+   * One decoded frame: a Buffer per plane (`[y, uv]` for NV12, `[y, cb, cr]`
+   * for I420, `[bgra]`), or one Buffer holding the planes back to back, the
+   * way an `ffmpeg -f rawvideo` pipe delivers them. The planes are read
+   * until the next push, not copied at the call. Throws a `TypeError` for
+   * planes too small for the frame; does nothing after `close()`.
+   */
+  push(
+    planes: ArrayBufferView | readonly ArrayBufferView[],
+    options?: VideoPushOptions,
+  ): void;
+  /** Drop the frame and take no more: what shows the sink shows its poster
+   * or its background from the next frame on. */
+  close(): void;
+}
+
+/** A sink for frames of one size and format, on `app`. */
+export function createVideoFrames(
+  app: NtkApp,
+  options: VideoFramesOptions,
+): VideoFrames;
+
+/**
+ * A sink for a component: the same object across renders, a new one when the
+ * size, the format or the colour changes. Nothing to close on unmount.
+ */
+export function useVideoFrames(options: VideoFramesOptions): VideoFrames;
+
+/** `<video src>` on a backend with no platform player — what `onError` is
+ * handed there. `useSupports('mediaPlayback')` asks first. */
+export class NoMediaPlaybackError extends Error {
+  readonly name: 'NoMediaPlaybackError';
+  readonly code: 'ENOMEDIAPLAYBACK';
+}
+
+/** `onLoadedMetadata`: the stream's size, and how long it is. */
+export interface VideoMetadataEvent {
+  /** Source pixels. */
+  width: number;
+  height: number;
+  /** Seconds; `Infinity` for a live source — a sink is one. */
+  duration: number;
+  node: unknown;
+}

package/src/videoframes.js

@@ -0,0 +1,375 @@
+// `VideoFrames`: a sink an application pushes decoded video frames into,
+// and a `<video frames>` shows (docs/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
+// application's business, and every one of them ends in `push`. What this
+// module owns is the contract between that decoder and whatever shows the
+// frame, which is one of two things per element and per frame:
+//
+// - **lifted**, on a backend that can put a frame on a layer of its own
+//   (Cocoa, over `@windowkit/appkit`'s video surfaces): `push` writes the
+//   frame into a surface the render server scans out and repoints the layer,
+//   right there, and react-x11's frame clock is not involved at all
+//   (src/cocoa/video.js);
+// - **drawn**, everywhere else and whenever something is painted over the
+//   video: `push` claims the element's picture, and the next frame copies
+//   the newest frame into a surface of the element's own and composites it
+//   in paint order (src/nodes/video.js).
+//
+// Three rules, each of which is a cost somewhere:
+//
+// - **The newest frame is the frame.** A push while the last one is not yet
+//   shown replaces it; nothing queues. A sink mirrors a decoder's output —
+//   the decoder's own clock is the pacing, as a `<canvas>` animation's is.
+// - **A push hands the planes over until the next push.** The drawn path
+//   reads them at the next frame, not at the call, so a frame pushed faster
+//   than the display shows is never converted at all. A decoder that writes
+//   every frame into one buffer pushes that buffer again after writing it,
+//   which is exactly when the old contents stop mattering.
+// - **Every format is accepted everywhere; the cheap one differs.** NV12 is
+//   what a hardware decoder emits and what a layer shows as it is; BGRA is
+//   what a 2D context draws. `preferredFormats` is this display's order, for
+//   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.
+
+export const VIDEO_FORMATS = Object.freeze(['NV12', 'I420', 'BGRA']);
+const COLOR_SPACES = ['bt709', 'bt601', 'bt2020'];
+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.
+const MAX_SIDE = 16384;
+
+/**
+ * The planes of a `format` frame at `width` x `height`: how many bytes of
+ * picture a row of each holds, and how many rows. A 4:2:0 chroma plane is
+ * half the size, rounded up.
+ */
+export function planeLayout(format, width, height) {
+  const cw = Math.ceil(width / 2);
+  const ch = Math.ceil(height / 2);
+  switch (format) {
+    case 'NV12':
+      return [
+        { rowBytes: width, rows: height },
+        { rowBytes: cw * 2, rows: ch },
+      ];
+    case 'I420':
+      return [
+        { rowBytes: width, rows: height },
+        { rowBytes: cw, rows: ch },
+        { rowBytes: cw, rows: ch },
+      ];
+    case 'BGRA':
+      return [{ rowBytes: width * 4, rows: height }];
+  }
+  throw new TypeError(`react-x11: unknown video format ${format}`);
+}
+
+const isBytes = (v) => ArrayBuffer.isView(v) && !(v instanceof DataView);
+
+const asBytes = (v) =>
+  v instanceof Uint8Array || v instanceof Uint8ClampedArray
+    ? v
+    : new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+
+/**
+ * `push`'s argument as planes: one `Uint8Array` view per plane (no copy)
+ * and each one's stride, checked to hold every row it claims. `planes` is
+ * an array of them, or one buffer holding them back to back — what an
+ * `ffmpeg -f rawvideo` pipe delivers per frame.
+ */
+export function readPlanes(sink, planes, strides) {
+  const { format, width, height } = sink;
+  const layout = planeLayout(format, width, height);
+  if (strides !== undefined) {
+    if (
+      !Array.isArray(strides) ||
+      strides.length !== layout.length ||
+      !strides.every((s, i) => Number.isInteger(s) && s >= layout[i].rowBytes)
+    ) {
+      throw new TypeError(
+        `react-x11: VideoFrames.push: strides must be ${layout.length} ` +
+          `whole numbers of bytes, at least ` +
+          `[${layout.map((p) => p.rowBytes).join(', ')}] for a ` +
+          `${width}x${height} ${format} frame`,
+      );
+    }
+  }
+  const pitch = layout.map((p, i) => strides?.[i] ?? p.rowBytes);
+  const sizes = layout.map((p, i) => pitch[i] * (p.rows - 1) + p.rowBytes);
+  let views;
+  if (isBytes(planes)) {
+    // one buffer: the planes back to back, each a whole number of strides
+    // except the last row of the last
+    const all = asBytes(planes);
+    views = [];
+    let at = 0;
+    for (let i = 0; i < layout.length; i++) {
+      const length =
+        i === layout.length - 1 ? sizes[i] : pitch[i] * layout[i].rows;
+      views.push(all.subarray(at, at + length));
+      at += length;
+    }
+    if (at > all.length) {
+      throw new TypeError(
+        `react-x11: VideoFrames.push: a ${width}x${height} ${format} frame ` +
+          `in one buffer needs ${at} bytes, and this one has ${all.length}`,
+      );
+    }
+  } else if (Array.isArray(planes) && planes.length === layout.length) {
+    views = planes.map((p, i) => {
+      if (!isBytes(p)) {
+        throw new TypeError(
+          `react-x11: VideoFrames.push: plane ${i} is not a Buffer or a typed array`,
+        );
+      }
+      return asBytes(p);
+    });
+  } else {
+    throw new TypeError(
+      `react-x11: VideoFrames.push: a ${format} frame is ` +
+        (layout.length === 1
+          ? 'one buffer'
+          : `an array of ${layout.length} planes (${format === 'NV12' ? 'Y, CbCr' : 'Y, Cb, Cr'}), or one buffer holding them back to back`),
+    );
+  }
+  views.forEach((view, i) => {
+    if (view.length < sizes[i]) {
+      throw new TypeError(
+        `react-x11: VideoFrames.push: plane ${i} of a ${width}x${height} ` +
+          `${format} frame needs ${sizes[i]} bytes, and has ${view.length}`,
+      );
+    }
+  });
+  return { planes: views, strides: pitch };
+}
+
+/**
+ * Where decoded video frames go to be shown — `createVideoFrames(app, …)`,
+ * or `useVideoFrames(…)` in a component — and what `<video frames>` takes.
+ *
+ * A sink owns nothing native. What shows it — a `<video>`'s surface, a
+ * layer's ring of video surfaces — owns that, and lets it go when it stops
+ * showing it, so a sink that is dropped needs no call.
+ */
+export class VideoFrames {
+  constructor(app, options = {}) {
+    const {
+      width,
+      height,
+      format = 'BGRA',
+      colorSpace = 'bt709',
+      range = 'video',
+    } = options;
+    if (
+      !Number.isInteger(width) ||
+      !Number.isInteger(height) ||
+      width < 1 ||
+      height < 1 ||
+      width > MAX_SIDE ||
+      height > MAX_SIDE
+    ) {
+      throw new TypeError(
+        'react-x11: createVideoFrames: width and height are the frame size ' +
+          `in whole pixels, 1 to ${MAX_SIDE} (got ${width}x${height})`,
+      );
+    }
+    if (!VIDEO_FORMATS.includes(format)) {
+      throw new TypeError(
+        `react-x11: createVideoFrames: format ${JSON.stringify(format)} — ` +
+          `expected one of ${VIDEO_FORMATS.join(', ')}`,
+      );
+    }
+    if (!COLOR_SPACES.includes(colorSpace)) {
+      throw new TypeError(
+        `react-x11: createVideoFrames: colorSpace ${JSON.stringify(colorSpace)} ` +
+          `— expected one of ${COLOR_SPACES.join(', ')}`,
+      );
+    }
+    if (!RANGES.includes(range)) {
+      throw new TypeError(
+        `react-x11: createVideoFrames: range ${JSON.stringify(range)} — ` +
+          "expected 'video' or 'full'",
+      );
+    }
+    this.app = app;
+    this.width = width;
+    this.height = height;
+    this.format = format;
+    this.colorSpace = colorSpace;
+    this.range = range;
+    /** frames pushed; what a presentation compares to know it is behind */
+    this.version = 0;
+    this.closed = false;
+    this._frame = null;
+    this._listeners = new Set();
+    this._preferred = null;
+  }
+
+  /**
+   * 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.
+   */
+  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'],
+      );
+    }
+    return this._preferred;
+  }
+
+  /** The newest frame — `{ planes, strides, time, version }` — or null. */
+  get frame() {
+    return this._frame;
+  }
+
+  /**
+   * One decoded frame: a Buffer per plane (`[y, uv]` for NV12, `[y, u, v]`
+   * for I420, `[bgra]`), or one Buffer holding the planes back to back.
+   * `strides` are the planes' bytes per row when a decoder pads them;
+   * `time` is the frame's presentation time in seconds, kept as `frame.time`
+   * for whoever wants it. Replaces the frame before it, shown or not.
+   * Ignored once `close()` has run, so a decoder racing an unmount does not
+   * have to know it lost.
+   */
+  push(planes, { strides, time } = {}) {
+    if (this.closed) return;
+    const frame = readPlanes(this, planes, strides);
+    this.version += 1;
+    frame.time = typeof time === 'number' ? time : null;
+    frame.version = this.version;
+    this._frame = frame;
+    for (const fn of [...this._listeners]) fn(frame);
+  }
+
+  /** Drop the frame and take no more: what shows the sink shows its poster
+   *  or its background from the next frame on. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this._frame = null;
+    this.version += 1;
+    for (const fn of [...this._listeners]) fn(null);
+    this._listeners.clear();
+  }
+
+  /** `fn(frame)` on every push, and `fn(null)` on `close()`; answers the
+   *  unsubscribe. For what shows a sink, not for applications. */
+  _subscribe(fn) {
+    if (this.closed) return () => {};
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  }
+}
+
+/** A sink for frames of one size and format, on `app`. */
+export function createVideoFrames(app, options) {
+  return new VideoFrames(app, options);
+}
+
+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 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
+// applied, because none of those backends colour-manages anything else
+// either, and a video brighter or darker than every other thing on the
+// screen beside it is worse than one that is wrong the same way they are.
+
+const MATRIX = {
+  bt709: [0.2126, 0.0722],
+  bt601: [0.299, 0.114],
+  bt2020: [0.2627, 0.0593],
+};
+
+const tables = new Map();
+
+/** Per-byte contributions in 0..255 units, made once per matrix and range:
+ *  R = Y + crR, G = Y - cbG - crG, B = Y + cbB. */
+function tablesFor(colorSpace, range) {
+  const key = `${colorSpace}/${range}`;
+  let t = tables.get(key);
+  if (t) return t;
+  const [kr, kb] = MATRIX[colorSpace];
+  const kg = 1 - kr - kb;
+  const full = range === 'full';
+  const y = new Float32Array(256);
+  const crR = new Float32Array(256);
+  const crG = new Float32Array(256);
+  const cbG = new Float32Array(256);
+  const cbB = new Float32Array(256);
+  for (let i = 0; i < 256; i++) {
+    y[i] = full ? i : ((i - 16) * 255) / 219;
+    const c = full ? (i - 128) * 1 : ((i - 128) * 255) / 224;
+    crR[i] = 2 * (1 - kr) * c;
+    cbB[i] = 2 * (1 - kb) * c;
+    crG[i] = ((2 * kr * (1 - kr)) / kg) * c;
+    cbG[i] = ((2 * kb * (1 - kb)) / kg) * c;
+  }
+  t = { y, crR, crG, cbG, cbB };
+  tables.set(key, t);
+  return t;
+}
+
+/**
+ * `frame` from `sink` as straight RGBA into `out` (a Uint8ClampedArray of
+ * width x height x 4, which clamps and rounds what is written into it).
+ */
+export function frameToRGBA(sink, frame, out) {
+  const { width: w, height: h, format } = sink;
+  const [p0, p1, p2] = frame.planes;
+  const [s0, s1, s2] = frame.strides;
+  if (format === 'BGRA') {
+    for (let row = 0; row < h; row++) {
+      let si = row * s0;
+      let di = row * w * 4;
+      for (let x = 0; x < w; x++, si += 4, di += 4) {
+        out[di] = p0[si + 2];
+        out[di + 1] = p0[si + 1];
+        out[di + 2] = p0[si];
+        out[di + 3] = 255;
+      }
+    }
+    return out;
+  }
+  const { y: Y, crR, crG, cbG, cbB } = tablesFor(sink.colorSpace, sink.range);
+  const nv12 = format === 'NV12';
+  for (let row = 0; row < h; row++) {
+    const yi = row * s0;
+    const ci = (row >> 1) * s1;
+    const vi = nv12 ? 0 : (row >> 1) * s2;
+    let di = row * w * 4;
+    for (let x = 0; x < w; x++, di += 4) {
+      const cx = x >> 1;
+      let cb;
+      let cr;
+      if (nv12) {
+        cb = p1[ci + cx * 2];
+        cr = p1[ci + cx * 2 + 1];
+      } else {
+        cb = p1[ci + cx];
+        cr = p2[vi + cx];
+      }
+      const l = Y[p0[yi + x]];
+      out[di] = l + crR[cr];
+      out[di + 1] = l - cbG[cb] - crG[cr];
+      out[di + 2] = l + cbB[cb];
+      out[di + 3] = 255;
+    }
+  }
+  return out;
+}