@driftengine/media 3.61.0

package/src/clipEncoder.ts

@@ -0,0 +1,328 @@
+/**
+ * Encoding frames and samples into a file, on a timeline we choose.
+ *
+ * The difference between this and a screen recorder is one word: **timestamps.** A
+ * recorder stamps a frame with the instant it happened to arrive, so the file's cadence
+ * is a measurement of how busy the machine was. Here every frame is stamped with where
+ * it *belongs*, so a slow machine produces a slower export rather than a worse file.
+ *
+ * That was not a preference. Measured with `ffprobe` on real `MediaRecorder` output: a
+ * clip's audio led its picture by 51 ms in one run and 85 ms in the next, and the
+ * `outputLatency` it would have to be corrected by reported 0.048 then 0.024 — so the
+ * error is real, varies, and cannot be calibrated out from inside the page. Nothing
+ * below asks the browser what time it is.
+ *
+ * Game-agnostic on purpose (AGENTS.md): frames, samples, sizes and rates. A second game
+ * uses it unchanged.
+ */
+import type { FrameOverlay } from '@driftengine/core';
+import { clipCodecs } from './clipSupport.ts';
+import type { ClipEncodeRequest } from './clipSupport.ts';
+
+/**
+ * Everything an encode needs: the frame, the rate, the bitrate, and the score's sample rate.
+ *
+ * The first four are `ClipEncodeRequest`, which is what `clipEncodingSupported` asks about, so a
+ * caller can hand the same object to the gate and to `open` and know they asked one question.
+ */
+export interface ClipEncoderOptions extends ClipEncodeRequest {
+  /** Audio sample rate, so the score and the encoder agree. */
+  readonly sampleRate?: number;
+}
+
+/**
+ * Microseconds for frame `index` at `fps`.
+ *
+ * **The product is rounded, never a per-frame constant accumulated.** A 60 fps frame is
+ * 16666.67 µs and the nearest integer is 16667, which is a third of a microsecond long
+ * — trivial once and 20 ms over a minute, which is more than a frame of drift by the
+ * end of a clip. Deriving each stamp from its own index cannot drift at all.
+ */
+export function frameTimestampUs(index: number, fps: number): number {
+  return Math.round((index * 1_000_000) / Math.max(fps, 1));
+}
+
+/** How many frames may be in flight before the loop waits for the encoder. */
+const QUEUE_LIMIT = 8;
+/** Samples per encoded audio chunk. A power of two the encoders all accept. */
+const AUDIO_CHUNK = 1024;
+/** Seconds between key frames. Two is what every platform's transcoder expects. */
+const KEYFRAME_SEC = 2;
+
+interface MuxerLike {
+  addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata): void;
+  addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
+  finalize(): void;
+}
+
+/** Which audio codec a file ended up carrying. See `ClipEncoder.audioCodec`. */
+export type ClipAudioCodec = 'aac' | 'opus';
+
+export class ClipEncoder {
+  private video: VideoEncoder | null = null;
+  private audio: AudioEncoder | null = null;
+  private muxer: MuxerLike | null = null;
+  private target: { buffer: ArrayBuffer | null } | null = null;
+  /**
+   * The audio codec this file carries, once configured.
+   *
+   * Reported rather than kept private because the two answers are not equivalent to
+   * whoever receives the file, and the difference is invisible in it: an MP4 is an
+   * MP4 either way. AAC is what every share target ingests. Opus in MP4 is legal ISO
+   * and almost nothing consumer-side reads it — Android's MediaCodec decodes Opus
+   * only in Matroska, WebM and Ogg, so the TikTok app cannot open the file at all.
+   *
+   * A caller that knows which one it got can say so. One that cannot know hands over
+   * a file that fails somewhere it will never see, which is what happened.
+   */
+  private chosenAudio: ClipAudioCodec | null = null;
+  /** The first error either encoder reported. Read by the caller; never thrown at it. */
+  private failure: string | null = null;
+  private closed = false;
+
+  private constructor(private readonly options: ClipEncoderOptions) {}
+
+  /**
+   * Configure the encoders and the container.
+   *
+   * The muxer is imported here rather than at the top of the module, so a player who
+   * never exports never downloads it. Rejects when the browser cannot encode, which the
+   * caller answers by recording instead.
+   */
+  static async open(options: ClipEncoderOptions): Promise<ClipEncoder> {
+    const encoder = new ClipEncoder(options);
+    await encoder.configure();
+    return encoder;
+  }
+
+  /** The error that ended the encode, or null while it is going well. */
+  get error(): string | null {
+    return this.failure;
+  }
+
+  /**
+   * The audio codec the file carries, or null before `open` has configured one.
+   *
+   * Survives `finish`, deliberately: the caller asks *after* it has a blob.
+   */
+  get audioCodec(): ClipAudioCodec | null {
+    return this.chosenAudio;
+  }
+
+  private async configure(): Promise<void> {
+    const { width, height, fps, bitrate, sampleRate = 48000 } = this.options;
+
+    /*
+     * The audio codec is *asked about* before anything is built, and that omission is
+     * what broke the first export. AAC was configured without checking, and Chrome on
+     * Linux has no AAC encoder — so `configure` accepted it, the codec errored
+     * internally on the first frame, closed itself, and the loop's next call reported
+     * "Cannot call 'encode' on a closed codec". Which is a true statement about a
+     * consequence and says nothing about the cause.
+     *
+     * AAC first because it is what every share target ingests without transcoding.
+     * Opus second because Chrome muxes Opus into MP4 happily — its own `MediaRecorder`
+     * does, as `ffprobe` showed on a probe file earlier — so it is a real fallback
+     * rather than a theoretical one.
+     */
+    const audioCandidates = [
+      { codec: 'mp4a.40.2', muxed: 'aac' as const },
+      { codec: 'opus', muxed: 'opus' as const },
+    ];
+    let audioChoice: { codec: string; muxed: ClipAudioCodec } | null = null;
+    for (const candidate of audioCandidates) {
+      const config = {
+        codec: candidate.codec,
+        sampleRate,
+        numberOfChannels: 2,
+        bitrate: 192_000,
+      };
+      try {
+        const support = await AudioEncoder.isConfigSupported(config);
+        if (support.supported === true) {
+          audioChoice = candidate;
+          break;
+        }
+      } catch {
+        // A codec string this build does not recognise. Try the next.
+      }
+    }
+    if (audioChoice === null) throw new Error('This browser cannot encode clip audio.');
+    this.chosenAudio = audioChoice.muxed;
+
+    const { Muxer, ArrayBufferTarget } = await import('mp4-muxer');
+    const target = new ArrayBufferTarget();
+    const muxer = new Muxer({
+      target,
+      fastStart: 'in-memory',
+      video: { codec: 'avc', width, height },
+      audio: { codec: audioChoice.muxed, numberOfChannels: 2, sampleRate },
+    });
+    this.target = target;
+    this.muxer = muxer as unknown as MuxerLike;
+
+    /*
+     * The ladder is derived from the frame rather than written down here — see `clipCodecs`,
+     * which is also what `clipEncodingSupported` walks, so a gate and an export cannot answer
+     * differently.
+     *
+     * **Both rungs used to be level 4.0 spelled out as literals, and that is what stopped 4K.**
+     * A level is a promise about frame size: 4.0's 8192 macroblocks holds 1920x1080 and nothing
+     * larger, so `isConfigSupported` said no at 2560x1440 and above and `configure` below was
+     * never reached at those sizes. The comment that stood here reasoned that the level is a
+     * floor and that Chrome raises it, which is true of every file this produces and is not a
+     * thing that can happen to a config the browser refused first.
+     */
+    const video = new VideoEncoder({
+      output: (chunk, meta) => this.muxer?.addVideoChunk(chunk, meta),
+      error: (error) => this.fail(error.message),
+    });
+    const codecs = clipCodecs(width, height);
+    let configured = false;
+    for (const codec of codecs) {
+      const config = { codec, width, height, bitrate, framerate: fps };
+      const support = await VideoEncoder.isConfigSupported(config);
+      if (support.supported !== true) continue;
+      video.configure(config);
+      configured = true;
+      break;
+    }
+    if (!configured) throw new Error('This browser cannot encode video at that size.');
+    this.video = video;
+
+    const audio = new AudioEncoder({
+      output: (chunk, meta) => this.muxer?.addAudioChunk(chunk, meta),
+      error: (error) => this.fail(error.message),
+    });
+    audio.configure({
+      codec: audioChoice.codec,
+      sampleRate,
+      numberOfChannels: 2,
+      bitrate: 192_000,
+    });
+    this.audio = audio;
+  }
+
+  /**
+   * One frame, at its own index.
+   *
+   * Awaits while the encoder is behind, which is the only backpressure in the pipeline:
+   * a render loop with nothing to wait for will queue a thousand 1080x1920 frames and
+   * run the tab out of memory long before the encoder catches up.
+   */
+  async addFrame(source: CanvasImageSource, index: number): Promise<void> {
+    const video = this.video;
+    // `state`, not just the failure flag: a codec that hit an internal error closes
+    // itself, and the error callback that would set the flag may not have run yet.
+    // Encoding into it then throws a message about the closure and hides the cause.
+    if (video === null || video.state !== 'configured' || this.failure !== null) return;
+    const { fps } = this.options;
+    const frame = new VideoFrame(source, {
+      timestamp: frameTimestampUs(index, fps),
+      duration: Math.round(1_000_000 / fps),
+    });
+    try {
+      video.encode(frame, { keyFrame: index % Math.round(fps * KEYFRAME_SEC) === 0 });
+    } finally {
+      // Closed whatever happened: a `VideoFrame` holds a GPU surface, and leaking one a
+      // frame is how a long export becomes an out-of-memory crash.
+      frame.close();
+    }
+    while (
+      video.encodeQueueSize > QUEUE_LIMIT &&
+      this.failure === null &&
+      video.state === 'configured'
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+  }
+
+  /**
+   * The whole score, in order.
+   *
+   * Interleaved into the encoder's f32 planar layout by hand rather than handed the
+   * `AudioBuffer`, because `AudioData` takes a flat buffer and the two channels of an
+   * `AudioBuffer` are separate arrays.
+   */
+  async addAudio(buffer: AudioBuffer): Promise<void> {
+    const audio = this.audio;
+    if (audio === null || audio.state !== 'configured' || this.failure !== null) return;
+    const channels = Math.min(buffer.numberOfChannels, 2);
+    const left = buffer.getChannelData(0);
+    const right = channels > 1 ? buffer.getChannelData(1) : left;
+    const rate = buffer.sampleRate;
+    const scratch = new Float32Array(AUDIO_CHUNK * 2);
+
+    for (let start = 0; start < buffer.length; start += AUDIO_CHUNK) {
+      const count = Math.min(AUDIO_CHUNK, buffer.length - start);
+      // Planar: all of the left channel, then all of the right.
+      for (let i = 0; i < count; i++) {
+        scratch[i] = left[start + i] ?? 0;
+        scratch[count + i] = right[start + i] ?? 0;
+      }
+      const data = new AudioData({
+        format: 'f32-planar',
+        sampleRate: rate,
+        numberOfFrames: count,
+        numberOfChannels: 2,
+        timestamp: Math.round((start / rate) * 1_000_000),
+        data: scratch.subarray(0, count * 2),
+      });
+      if (audio.state !== 'configured' || this.failure !== null) {
+        data.close();
+        return;
+      }
+      try {
+        audio.encode(data);
+      } finally {
+        data.close();
+      }
+      if (this.failure !== null) return;
+      while (audio.encodeQueueSize > QUEUE_LIMIT * 4) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+      }
+    }
+  }
+
+  /** Flush both encoders, close the container, and hand back the file. */
+  async finish(): Promise<Blob | null> {
+    if (this.closed) return null;
+    this.closed = true;
+    try {
+      await this.video?.flush();
+      await this.audio?.flush();
+      this.muxer?.finalize();
+    } catch (error) {
+      this.fail(error instanceof Error ? error.message : 'the encoder gave up');
+    }
+    this.release();
+    const buffer = this.target?.buffer ?? null;
+    if (this.failure !== null || buffer === null) return null;
+    return new Blob([buffer], { type: 'video/mp4' });
+  }
+
+  /** Give everything back without producing a file. Safe at any point. */
+  abort(): void {
+    this.closed = true;
+    this.release();
+  }
+
+  private release(): void {
+    try {
+      if (this.video?.state === 'configured') this.video.close();
+      if (this.audio?.state === 'configured') this.audio.close();
+    } catch {
+      // Already closed. Nothing to do about an encoder we were discarding.
+    }
+    this.video = null;
+    this.audio = null;
+  }
+
+  /** First failure wins: the later ones are consequences of it. */
+  private fail(message: string): void {
+    this.failure ??= message;
+  }
+}
+
+/** Re-exported so a caller can composite a mark without importing two modules. */
+export type { FrameOverlay };

package/src/clipSupport.ts

@@ -0,0 +1,156 @@
+/**
+ * What this browser will encode, asked before anything is built.
+ *
+ * One responsibility: turn a frame size into the codec strings an encode is negotiated with, and
+ * answer whether this browser accepts them. `ClipEncoder.open` configures from the same ladder,
+ * so a caller greying out a control and a caller pressing Export are asking one question rather
+ * than two copies of it.
+ *
+ * **That was not the arrangement, and the gap shipped.** Both rungs used to be level 4.0 written
+ * into the string by hand, and a level is a promise about frame *size*: 4.0 holds 8192
+ * macroblocks, which is 1920x1080 with 32 to spare and nothing above it. So `isConfigSupported`
+ * refused 2560x1440, 2160x2160 and 3840x2160 outright, `VideoEncoder.configure` was never reached
+ * at those sizes, and a 4K export ended in "this browser cannot encode video at that size" on a
+ * card that encodes 4K. A second consumer found it by copying the two strings into its own
+ * repository to grey out a panel with, which is the shape of a decision that has no home.
+ */
+
+/**
+ * Whether this browser can render a clip offline rather than record one.
+ *
+ * Both halves are needed: frames without a score is a silent clip and a score without
+ * frames is nothing. A browser missing either falls back to the recorder.
+ *
+ * Says nothing about a *size*, deliberately: it is about the API being present at all, and it
+ * answers the same for a 64x64 frame and a 4K one. `clipEncodingSupported` is the size question.
+ */
+export function offlineEncodingSupported(): boolean {
+  return (
+    typeof VideoEncoder === 'function' &&
+    typeof AudioEncoder === 'function' &&
+    typeof VideoFrame === 'function' &&
+    typeof AudioData === 'function' &&
+    typeof OfflineAudioContext === 'function'
+  );
+}
+
+/**
+ * The four numbers an encode is negotiated with, before there is anything to encode.
+ *
+ * `ClipEncoderOptions` extends it, so the question a gate asks is the options the export opens
+ * with rather than a paraphrase of them.
+ */
+export interface ClipEncodeRequest {
+  readonly width: number;
+  readonly height: number;
+  readonly fps: number;
+  /** Bits per second for video. See `clipBitrate` for a figure worth passing. */
+  readonly bitrate: number;
+}
+
+/**
+ * H.264 levels, smallest first, with the largest frame each can represent.
+ *
+ * `maxMacroblocks` is the spec's MaxFS, and on Chrome 149 it is exactly what
+ * `isConfigSupported` enforces: measured over 9 sizes, 2 rates and 7 levels on an RX 9070 XT,
+ * every level at or above the one whose MaxFS holds the frame answered yes and every level below
+ * it answered no, in all 252 cells. Profile never moved an answer and neither did frame rate.
+ *
+ * **The rate bound is deliberately not part of the choice**, and that is the compromise here.
+ * The spec's MaxMBPS says 1920x1080 at 60 needs level 4.2 and at 120 needs 5.1; this asks 4.0 for
+ * both. It is defensible because the level in a codec string is a floor for the negotiation
+ * rather than a description of the file: asked for 4.0 at 1920x1080, Chrome wrote **level 4.2**
+ * into the file, and asked for 5.1 at 3840x2160 it wrote 5.2. What would make it wrong is a
+ * browser that honours the floor literally and encodes a stream its own level cannot carry, which
+ * nothing here has met. The rungs are worth having anyway for the size wall, which is real.
+ *
+ * Levels that hold no more than the one below are left out rather than listed: 4.1 has 4.0's
+ * 8192, 5.2 has 5.1's 36864, 6.1 and 6.2 have 6.0's 139264. Asking for one of them buys a bigger
+ * number in the string and no frame. Measured, at 3840x2160: a 5.1 request and a 5.2 request
+ * produced the same byte count and the same level in the file.
+ *
+ * The table starts at 4.0 rather than at 1.0 because nothing below it changes an answer. A 720p
+ * fallback frame is 3600 macroblocks and level 4.0 carries it, the encoder writes its own level
+ * regardless, and lowering the floor would only put a smaller number in front of a browser that
+ * has never been measured caring.
+ */
+const AVC_LEVELS: readonly { readonly id: number; readonly maxMacroblocks: number }[] = [
+  { id: 0x28, maxMacroblocks: 8192 }, // 4.0
+  { id: 0x2a, maxMacroblocks: 8704 }, // 4.2
+  { id: 0x32, maxMacroblocks: 22_080 }, // 5.0
+  { id: 0x33, maxMacroblocks: 36_864 }, // 5.1
+  { id: 0x3c, maxMacroblocks: 139_264 }, // 6.0
+];
+
+/**
+ * The codec strings to try for a frame this size, best first.
+ *
+ * High profile first, constrained baseline as the fallback, both at the smallest level that can
+ * represent the frame. High is what every phone decodes in hardware and what a transcoder
+ * prefers; baseline exists because a machine without hardware AVC will refuse the first and
+ * encode the second in software rather than refuse to export. **Both rungs move together**: a
+ * baseline rung pinned to 4.0 is no fallback at 4K, it is a second refusal.
+ *
+ * Empty when no level can hold the frame, which is a frame past 139,264 macroblocks. The caller
+ * turns that into the same refusal it gives when the browser says no, one round trip earlier.
+ *
+ * Not on the barrel on purpose. The ladder is the engine's decision, and a consumer that can read
+ * it is a consumer that can pin a codec string in its own repository, which is how one decision
+ * became two copies the last time.
+ */
+export function clipCodecs(width: number, height: number): readonly string[] {
+  /* Whole macroblocks: 1080 is 67.5 columns of 16 and costs 68 of them. */
+  const macroblocks = Math.ceil(width / 16) * Math.ceil(height / 16);
+  const level = AVC_LEVELS.find((rung) => macroblocks <= rung.maxMacroblocks);
+  if (level === undefined) return [];
+  const hex = level.id.toString(16).toUpperCase().padStart(2, '0');
+  return [`avc1.6400${hex}`, `avc1.42E0${hex}`];
+}
+
+/** One answer per distinct request, kept for the session. See `clipEncodingSupported`. */
+const answers = new Map<string, Promise<boolean>>();
+
+/**
+ * Whether this browser will encode a clip of this size, at this rate, at this bitrate.
+ *
+ * The question `ClipEncoder.open` is about to ask, asked early enough to grey out a control
+ * instead of failing an export somebody already chose. It walks the same ladder `open` walks, so
+ * the two cannot drift; a gate built from a copied codec string offered ten sizes the export
+ * would refuse, which is the fault this exists to make unrepeatable.
+ *
+ * Memoised on the whole request, because the answer is a property of the machine rather than of
+ * the moment: a panel asking about nine sizes at two rates costs eighteen probes at boot and
+ * nothing afterwards. The promise is stored rather than the result, so eighteen concurrent asks
+ * about one size are one probe.
+ *
+ * False when WebCodecs is absent, which is the same answer from the caller's point of view. What
+ * it does **not** answer: whether the frames arrive once encoding starts. See `framesReachEncoder`.
+ */
+export async function clipEncodingSupported(request: ClipEncodeRequest): Promise<boolean> {
+  const { width, height, fps, bitrate } = request;
+  const key = `${width}x${height}@${fps}/${bitrate}`;
+  const known = answers.get(key);
+  if (known !== undefined) return known;
+  const asking = ask(request);
+  answers.set(key, asking);
+  return asking;
+}
+
+async function ask({ width, height, fps, bitrate }: ClipEncodeRequest): Promise<boolean> {
+  if (typeof VideoEncoder !== 'function') return false;
+  for (const codec of clipCodecs(width, height)) {
+    try {
+      const support = await VideoEncoder.isConfigSupported({
+        codec,
+        width,
+        height,
+        bitrate,
+        framerate: fps,
+      });
+      if (support.supported === true) return true;
+    } catch {
+      // A codec string this build will not parse is one it cannot encode. Try the next rung.
+    }
+  }
+  return false;
+}

package/src/frameDelivery.ts

@@ -0,0 +1,191 @@
+/**
+ * Whether the pictures this browser encodes are the pictures it was given.
+ *
+ * Every other capability call asks whether the browser *says* it can do something. This one asks
+ * whether it did, and it is the only one that has caught a file going out wrong.
+ *
+ * **The fault it exists for.** Chrome 149 with `chrome://flags#enable-vulkan` on, under Wayland,
+ * composites through Vulkan while ANGLE stays on GL, and in that arrangement a `VideoFrame` built
+ * from a canvas reaches the encoder empty. Nothing reports it: `VideoEncoder.error` never fires,
+ * `encodeQueueSize` drains, `flush` resolves, the muxer finalises, and the app hands somebody a
+ * clip that is solid green from end to end with its audio intact. Four went out that way from a
+ * consuming app on 2026-08-14 before anybody opened one.
+ *
+ * Reproduced here from this repository's own harness, on an RX 9070 XT on RADV, with the flags as
+ * the only variable: twelve frames of 1920x1080 encoded to 114,157 bytes with them off and 8,747
+ * bytes with them on, and `ffprobe` read every frame of the second file back as YAVG 0, UAVG 0,
+ * VAVG 0. All-zero YUV is green rather than black once a decoder applies the limited range.
+ * `--headless=new` does not reproduce it at all, with or without Vulkan, which is consistent with
+ * it taking the compositor and the ozone platform together.
+ *
+ * **So the check is a round trip rather than an inspection**, and three things that look like
+ * witnesses are not: `getImageData` on the same canvas returns the right pixels in every run,
+ * `VideoFrame.copyTo` reported full buffers for a case that went on to encode green, and every
+ * capability call answers yes. What would make this module wrong is a browser that fails delivery
+ * for some frames and not others, in which case one probe at the start is not enough; the fault
+ * measured here is a property of the browser's configuration and does not vary frame to frame.
+ */
+import { clipCodecs } from './clipSupport.ts';
+
+/** What the probe found. `unknown` is the answer that changes nothing. */
+export type FrameDelivery = 'carries' | 'empty' | 'unknown';
+
+/** Side of the probe frame. The smallest thing worth asking; it encodes to 39 bytes. */
+const PROBE_SIZE = 64;
+
+/**
+ * The colour the probe paints: full red and full blue, no green.
+ *
+ * Chosen to be the opposite of the failure. An all-zero frame decodes to green with no red and no
+ * blue in either colour space a browser might tag it with, BT.709 putting it at `0,77,0` and
+ * BT.601 at `0,135,0`, so a picture that survived and a picture that did not cannot be confused
+ * by a decoder's choice of matrix. A grey probe would have to tell them apart by brightness,
+ * which is a threshold somebody has to guess at.
+ */
+const PROBE_COLOR = 'rgb(255 0 255)';
+
+/** How long the round trip gets before it is abandoned. Far longer than it has ever taken. */
+const PROBE_TIMEOUT_MS = 2000;
+
+/**
+ * What a decoded probe colour means.
+ *
+ * **Only a positive reading of an empty frame refuses anything.** A probe that could not run, a
+ * decoder that returned nothing, a colour this does not recognise: all `unknown`, and a caller
+ * lets the export through on all of them. The two mistakes are not equal. A false negative costs
+ * somebody a file they can already see is wrong; a false positive costs them every clip they were
+ * going to make, on a machine where nothing was ever broken.
+ */
+export function deliveryVerdict(decoded: readonly [number, number, number] | null): FrameDelivery {
+  if (decoded === null) return 'unknown';
+  const [red, , blue] = decoded;
+  /* Both channels the probe painted came back. Generous, because the round trip goes through a
+     4:2:0 chroma subsample and a colour space conversion and neither is lossless. */
+  if (red > 128 && blue > 128) return 'carries';
+  /* Neither did, which no encode of this colour can produce. */
+  if (red < 32 && blue < 32) return 'empty';
+  return 'unknown';
+}
+
+/** One answer per session. See `framesReachEncoder`. */
+let asked: Promise<FrameDelivery> | null = null;
+
+/**
+ * Paint a known colour, encode it, decode it back, and report what came out.
+ *
+ * Memoised for the session: the fault is a property of how the browser was started, so a second
+ * answer cannot differ from the first, and an export path that asks before every attempt should
+ * pay for one encode rather than one per press.
+ *
+ * Every failure path answers `unknown` rather than throwing, including the timeout. This runs in
+ * front of an export, and a capability probe that can itself stop one has become a liability
+ * rather than a check.
+ */
+export function framesReachEncoder(): Promise<FrameDelivery> {
+  asked ??= run();
+  return asked;
+}
+
+async function run(): Promise<FrameDelivery> {
+  if (
+    typeof document === 'undefined' ||
+    typeof VideoEncoder !== 'function' ||
+    typeof VideoDecoder !== 'function' ||
+    typeof VideoFrame !== 'function'
+  ) {
+    return 'unknown';
+  }
+  try {
+    return await Promise.race([
+      roundTrip(),
+      new Promise<FrameDelivery>((resolve) => {
+        setTimeout(() => resolve('unknown'), PROBE_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    return 'unknown';
+  }
+}
+
+async function roundTrip(): Promise<FrameDelivery> {
+  const codec = clipCodecs(PROBE_SIZE, PROBE_SIZE)[0];
+  if (codec === undefined) return 'unknown';
+
+  const canvas = document.createElement('canvas');
+  canvas.width = PROBE_SIZE;
+  canvas.height = PROBE_SIZE;
+  const ctx = canvas.getContext('2d', { alpha: false });
+  if (ctx === null) return 'unknown';
+  ctx.fillStyle = PROBE_COLOR;
+  ctx.fillRect(0, 0, PROBE_SIZE, PROBE_SIZE);
+
+  const chunks: EncodedVideoChunk[] = [];
+  /* The type the decoder's own config field takes, which is wider than `BufferSource`: it
+     accommodates a `SharedArrayBuffer`, and narrowing it here would only be a cast back. */
+  let description: AllowSharedBufferSource | undefined;
+  let failed = false;
+  const config = {
+    codec,
+    width: PROBE_SIZE,
+    height: PROBE_SIZE,
+    bitrate: 1_000_000,
+    framerate: 30,
+  };
+  const support = await VideoEncoder.isConfigSupported(config);
+  if (support.supported !== true) return 'unknown';
+
+  const encoder = new VideoEncoder({
+    output: (chunk, meta) => {
+      if (description === undefined && meta?.decoderConfig?.description !== undefined) {
+        description = meta.decoderConfig.description;
+      }
+      chunks.push(chunk);
+    },
+    error: () => {
+      failed = true;
+    },
+  });
+  encoder.configure(config);
+  const frame = new VideoFrame(canvas, { timestamp: 0, duration: 33_333 });
+  try {
+    encoder.encode(frame, { keyFrame: true });
+  } finally {
+    frame.close();
+  }
+  await encoder.flush();
+  encoder.close();
+  if (failed || chunks.length === 0) return 'unknown';
+
+  let decoded: [number, number, number] | null = null;
+  const decoder = new VideoDecoder({
+    output: (picture) => {
+      try {
+        const read = document.createElement('canvas');
+        read.width = PROBE_SIZE;
+        read.height = PROBE_SIZE;
+        const readCtx = read.getContext('2d', { alpha: false });
+        if (readCtx !== null) {
+          readCtx.drawImage(picture, 0, 0);
+          const px = readCtx.getImageData(PROBE_SIZE / 2, PROBE_SIZE / 2, 1, 1).data;
+          decoded = [px[0] ?? 0, px[1] ?? 0, px[2] ?? 0];
+        }
+      } finally {
+        picture.close();
+      }
+    },
+    error: () => {
+      failed = true;
+    },
+  });
+  decoder.configure({
+    codec,
+    codedWidth: PROBE_SIZE,
+    codedHeight: PROBE_SIZE,
+    ...(description === undefined ? {} : { description }),
+  });
+  for (const chunk of chunks) decoder.decode(chunk);
+  await decoder.flush();
+  decoder.close();
+  if (failed) return 'unknown';
+  return deliveryVerdict(decoded);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Recording what the engine draws: encoding a clip, and delivering frames to it.
+ *
+ * The muxer dependency lives here rather than in core, which is the point — a game that
+ * records nothing installs no muxer.
+ */
+
+export { ClipEncoder, frameTimestampUs } from './clipEncoder.ts';
+export type { ClipAudioCodec, ClipEncoderOptions } from './clipEncoder.ts';
+export { clipEncodingSupported, offlineEncodingSupported } from './clipSupport.ts';
+export type { ClipEncodeRequest } from './clipSupport.ts';
+export { framesReachEncoder } from './frameDelivery.ts';
+export type { FrameDelivery } from './frameDelivery.ts';