@1agh/maude 0.58.2 → 0.58.3

package/apps/studio/exporters/_browser-bundles.ts

@@ -88,7 +88,6 @@ export function getEncodeLibBundle(): Promise<string> {
   // binary the latter is the virtual `/$bunfs/root`, so `Bun.build` fails with
   // "failed to open root directory: /$bunfs/root" (the mp4/gif export bug).
   const entry = path.join(DEV_SERVER_ROOT, 'exporters', 'video-encode-lib.ts');
-  const cachePath = path.join(tmpdir(), 'maude-video-encode-lib.mjs');
   encodeLibReady = (async () => {
     const built = await Bun.build({
       entrypoints: [entry],
@@ -102,8 +101,7 @@ export function getEncodeLibBundle(): Promise<string> {
     }
     const first = built.outputs[0];
     if (!first) throw new Error('encode-lib bundle produced no outputs');
-    await Bun.write(cachePath, await first.text());
-    return cachePath;
+    return writeHashedBundle(await first.text(), 'maude-video-encode-lib');
   })();
   return encodeLibReady;
 }
@@ -128,7 +126,6 @@ let webRendererLibReady: Promise<string> | null = null;
 export function getWebRendererBundle(): Promise<string> {
   if (webRendererLibReady) return webRendererLibReady;
   const entry = path.join(DEV_SERVER_ROOT, 'exporters', 'video-render-lib.ts');
-  const cachePath = path.join(tmpdir(), 'maude-video-render-lib.mjs');
   webRendererLibReady = (async () => {
     // Bun's `external` field is package-name PREFIX matched (runtime-bundle.ts's
     // comment on the same gotcha) — listing 'remotion' also externalizes deep
@@ -179,12 +176,29 @@ export function getWebRendererBundle(): Promise<string> {
     }
     const first = built.outputs[0];
     if (!first) throw new Error('web-renderer bundle produced no outputs');
-    await Bun.write(cachePath, await first.text());
-    return cachePath;
+    return writeHashedBundle(await first.text(), 'maude-video-render-lib');
   })();
   return webRendererLibReady;
 }
 
+/**
+ * Write a built browser bundle to a CONTENT-ADDRESSED temp path.
+ *
+ * These used to go to a fixed name (`maude-video-encode-lib.mjs`). Two Maude
+ * servers at different versions is a documented normal state in this repo — the
+ * desktop app and a terminal dev server — and they share one OS temp dir, so
+ * they raced to write that single path. The loser then injected the winner's
+ * bundle: an old shim could hand bytes to a newer lib, or vice versa. Nothing
+ * about that failure is legible from the outside; it looks like a corrupt
+ * export. Hashing the content makes a mismatched pair impossible to construct.
+ */
+async function writeHashedBundle(code: string, stem: string): Promise<string> {
+  const hash = new Bun.CryptoHasher('sha256').update(code).digest('hex').slice(0, 12);
+  const cachePath = path.join(tmpdir(), `${stem}.${hash}.mjs`);
+  if (!existsSync(cachePath)) await Bun.write(cachePath, code);
+  return cachePath;
+}
+
 /**
  * Returns the path to an IIFE bundle for the given npm package, attaching its
  * exports under `window[globalName]`. Caches under the OS temp dir so a long-

package/apps/studio/exporters/_runtime.ts

@@ -75,6 +75,12 @@ export interface SpawnShimOptions {
   signal?: AbortSignal;
   /** Fired for each `MAUDE_PROGRESS {"current":N,"total":M}` stdout line. */
   onProgress?: (update: { current: number; total: number }) => void;
+  /**
+   * Fired for the single `MAUDE_TIMING {…}` line a shim emits at the end.
+   * Per-stage costs, so "the export is slow" can be answered with a
+   * measurement instead of a guess about which stage owns the time.
+   */
+  onTiming?: (timing: Record<string, unknown>) => void;
 }
 
 export interface SpawnShimResult {
@@ -85,6 +91,10 @@ export interface SpawnShimResult {
 }
 
 const PROGRESS_LINE = /^MAUDE_PROGRESS (.+)$/;
+// Filtered here rather than in the adapters for a load-bearing reason: every
+// video adapter parses `stdoutLines.at(-1)` as its summary JSON, so a trailing
+// diagnostic line on stdout would break EVERY video export.
+const TIMING_LINE = /^MAUDE_TIMING (.+)$/;
 
 /**
  * Spawn a render shim (`bin/_{png,pdf,svg,html,pptx,video}-playwright.mjs`)
@@ -121,6 +131,15 @@ export async function spawnShim(args: string[], opts: SpawnShimOptions): Promise
   let buffer = '';
   const consumeLine = (line: string) => {
     if (!line) return;
+    const timing = TIMING_LINE.exec(line);
+    if (timing) {
+      try {
+        opts.onTiming?.(JSON.parse(timing[1]) as Record<string, unknown>);
+      } catch {
+        /* malformed timing line — diagnostics must never break an export */
+      }
+      return;
+    }
     const match = PROGRESS_LINE.exec(line);
     if (!match) {
       stdoutLines.push(line);

package/apps/studio/exporters/degraded.ts

@@ -0,0 +1,92 @@
+// A produced-but-lesser export result, and the remedy for it when one exists.
+//
+// Its own module rather than living in `index.ts`, because `index.ts` re-exports
+// every adapter (including `video.ts`) — so a test that wants `remedyFor` alone
+// would pull the whole adapter graph and hit a circular-init ReferenceError.
+//
+// RCA `issue-mp4-audio-export-html5audio-silent-degrade`.
+
+/**
+ * The file is real and the job is `done` — but it is NOT what was asked for,
+ * and saying so is the whole point.
+ *
+ * An mp4 export of a comp using `remotion`'s `<Audio>` (= `<Html5Audio>`, which
+ * `@remotion/web-renderer` rejects outright) degrades to the video-only
+ * frame-step path and ships MUTED. Before this type existed, the job reported
+ * `done`, the history entry looked clean, `GET /_api/export-jobs` had no field
+ * for it, and the only trace was one `console.error` in the desktop app's
+ * stderr — so the artifact and its ledger entry were indistinguishable from a
+ * good export. This is what makes them distinguishable.
+ */
+export interface ExportDegradation {
+  /** The requested audio track is absent from the produced file. */
+  audioDropped: boolean;
+  /** Human-readable cause, already newline-collapsed by the shim (DDR-054). */
+  reason: string;
+  /** One-line remedy — present only when the cause is a fixable authoring mistake. */
+  remedy?: string;
+}
+
+/**
+ * Turn a renderer failure into a one-line fix, when the failure IS fixable.
+ *
+ * `renderMediaOnWeb` supports ONLY `@remotion/media` media elements; `remotion`'s
+ * `Audio` (= `Html5Audio`) and `OffthreadVideo` are both rejected with a typed
+ * error that already names the remedy. This carries that remedy to where a user
+ * will actually read it — the job row and the toast — instead of leaving it in a
+ * log nobody opens.
+ *
+ * Returns undefined for causes with no honest one-liner (e.g. the DDR-157
+ * recursion overflow, which is data-dependent and not the author's to fix).
+ * Inventing a remedy there would be worse than silence.
+ */
+/**
+ * Does this container actually carry an audio track?
+ *
+ * The last line of defence, and deliberately independent of whether the shim
+ * noticed anything: the RCA's whole shape was that every OTHER signal said the
+ * export was fine. If audio was asked for and the bytes don't have it, the
+ * result is degraded — full stop, no matter what the renderer reported.
+ *
+ * Byte-scan rather than a demuxer, because the question is binary and a parser
+ * dependency (or a native `ffprobe`) would cost far more than it buys:
+ *  • MP4/ISOBMFF — a track's `hdlr` box names its handler type; audio is `soun`.
+ *  • WebM/Matroska — audio tracks carry an `A_*` CodecID string (`A_OPUS`, …).
+ *
+ * Conservative by construction: an unrecognized container returns `true` (assume
+ * fine) so this can never invent a degradation it cannot prove.
+ */
+export function hasAudioStream(body: Uint8Array, container: string): boolean {
+  const ascii = (bytes: Uint8Array, needle: string): boolean => {
+    const pat = new TextEncoder().encode(needle);
+    outer: for (let i = 0; i + pat.length <= bytes.length; i += 1) {
+      for (let j = 0; j < pat.length; j += 1) {
+        if (bytes[i + j] !== pat[j]) continue outer;
+      }
+      return true;
+    }
+    return false;
+  };
+  if (container === 'mp4') return ascii(body, 'soun');
+  if (container === 'webm') {
+    return ['A_OPUS', 'A_VORBIS', 'A_AAC', 'A_MPEG'].some((c) => ascii(body, c));
+  }
+  return true;
+}
+
+export function remedyFor(reason: string): string | undefined {
+  if (/Html5Audio/i.test(reason)) {
+    return (
+      "This comp imports `Audio` from 'remotion', which IS <Html5Audio> — the audio " +
+      "renderer can't render it. Import { Audio } from '@remotion/media' instead."
+    );
+  }
+  if (/OffthreadVideo/i.test(reason)) {
+    return (
+      'This comp uses <OffthreadVideo>, which the audio renderer rejects. Import ' +
+      "{ Video } from '@remotion/media' instead — only @remotion/media elements " +
+      'carry audio through the export.'
+    );
+  }
+  return undefined;
+}

package/apps/studio/exporters/index.ts

@@ -9,6 +9,7 @@
 import path from 'node:path';
 
 import * as canva from './canva.ts';
+import type { ExportDegradation } from './degraded.ts';
 import * as html from './html.ts';
 import * as pdf from './pdf.ts';
 import * as png from './png.ts';
@@ -72,8 +73,12 @@ export interface ExportResult {
   contentType: string;
   /** Payload bytes. T1 stubs return zero-byte placeholders. */
   body: Uint8Array;
+  /** Set when the export succeeded but produced less than was asked for. */
+  degraded?: ExportDegradation;
 }
 
+export type { ExportDegradation } from './degraded.ts';
+
 /** Progress + cancellation hooks threaded through to the shim-spawning layer. */
 export interface ExportHooks {
   onProgress?: (update: { current: number; total: number }) => void;

package/apps/studio/exporters/jobs.ts

@@ -30,6 +30,7 @@ import path from 'node:path';
 import type { Bus } from '../context.ts';
 import {
   type ExportContext,
+  type ExportDegradation,
   type ExportOptions,
   type ExportResult,
   type Format,
@@ -50,6 +51,8 @@ export interface ExportHistoryEntry {
   startedAt?: string;
   finishedAt?: string;
   error?: string;
+  /** Present when the export produced less than was asked for (e.g. muted mp4). */
+  degraded?: ExportDegradation;
 }
 
 export type ExportJobStatus = 'queued' | 'running' | 'done' | 'failed';
@@ -67,6 +70,13 @@ export interface ExportJob {
   filename?: string;
   contentType?: string;
   error?: string;
+  /**
+   * Set when the export finished but produced less than was asked for. `status`
+   * stays `done` (the file is real); this is what tells the UI, the WS
+   * subscriber and the history ledger that it is not a clean result.
+   * RCA `issue-mp4-audio-export-html5audio-silent-degrade`.
+   */
+  degraded?: ExportDegradation;
 }
 
 export interface EnqueueArgs {
@@ -252,6 +262,9 @@ export function createExportJobQueue(bus: Bus, designRoot: string): ExportJobQue
         startedAt: j.startedAt,
         finishedAt: j.finishedAt,
         error: j.error,
+        // A muted mp4 must not look like a clean one in the ledger either — the
+        // history entry is what a later session (or an agent) reads back.
+        degraded: j.degraded,
       }));
   }
 
@@ -329,6 +342,12 @@ export function createExportJobQueue(bus: Bus, designRoot: string): ExportJobQue
         job.finishedAt = new Date().toISOString();
         job.filename = res.filename;
         job.contentType = res.contentType;
+        // `done` + `degraded` is a real, deliberate combination: the file exists
+        // and is downloadable, but it is missing something that was asked for.
+        // Before this, the ONLY trace of a muted mp4 was a console.error line in
+        // the desktop app's stderr — see RCA
+        // issue-mp4-audio-export-html5audio-silent-degrade.
+        if (res.degraded) job.degraded = res.degraded;
         if (res.body.byteLength) {
           const dir = path.join(jobsDir, id);
           await mkdir(dir, { recursive: true });

package/apps/studio/exporters/unsupported-media.ts

@@ -0,0 +1,170 @@
+// Pre-flight for the two media elements the audio renderer rejects.
+//
+// RCA `issue-mp4-audio-export-html5audio-silent-degrade`: `renderMediaOnWeb` —
+// the ONLY export path that can mux an audio track — supports only
+// `@remotion/media` media elements. `remotion`'s `Audio` (which IS
+// `Html5Audio`) and `OffthreadVideo` are both rejected at render time. The shim
+// catches the throw and degrades to the video-only frame-step path, so the
+// export "succeeds" muted — and ~40x slower (measured: ~37 min vs ~45 s on the
+// sibling artboard).
+//
+// DDR-157's blanket "degrade on ANY renderer failure" is right for the class it
+// was built for: the recursion overflow is data-dependent, manifests late, and
+// the author cannot fix it. `<Html5Audio>` is the opposite — decidable from
+// source before a browser is ever launched, always fails, one-line remedy stated
+// in the error itself. Swallowing THAT into a generic fallback turns a fixable
+// mistake into a mysterious one, so we decide it here instead.
+//
+// Deliberately a regex-over-known-vocabulary scan rather than a real parser,
+// matching the house style of `bin/_canvas-rects-static.mjs`: the vocabulary is
+// fixed (two symbols, one module specifier) and a parser dependency for this
+// would cost more than it buys.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The elements `@remotion/web-renderer` refuses, and what to do about each. */
+export type UnsupportedElement = 'Audio' | 'OffthreadVideo';
+
+export interface UnsupportedFinding {
+  element: UnsupportedElement;
+  /** Where the `from 'remotion'` import actually lives — the canvas, or a barrel it re-exports through. */
+  sourceFile: string;
+  /** True when the canvas reached it through a re-export barrel rather than directly. */
+  viaBarrel: boolean;
+  /** The name the JSX mounts it under — differs from `element` when aliased. */
+  localName: string;
+}
+
+const CANDIDATE_EXTS = ['.tsx', '.ts', '.jsx', '.js'];
+
+/**
+ * Named bindings imported from the bare `remotion` specifier.
+ *
+ * Matches `import { A, B as C } from 'remotion'` and the `export { A } from
+ * 'remotion'` re-export form, single or double quoted. Deliberately anchored to
+ * the EXACT specifier: `@remotion/media` and `@remotion/transitions` are the
+ * supported packages and must never match.
+ */
+function bindingsFromRemotion(src: string): Map<string, string> {
+  // originalName -> localName. Both halves matter and they are NOT
+  // interchangeable: the ORIGINAL name identifies which element this is, but the
+  // LOCAL name is what the JSX actually mounts. `import { Audio as Sound }`
+  // renders `<Sound>`, so checking for `<Audio>` would miss it entirely.
+  const found = new Map<string, string>();
+  const re = /(?:import|export)\s*\{([^}]*)\}\s*from\s*['"]remotion['"]/g;
+  for (const m of src.matchAll(re)) {
+    for (const raw of m[1].split(',')) {
+      const [orig, alias] = raw.split(/\s+as\s+/).map((s) => s.trim());
+      if (!orig) continue;
+      found.set(orig, alias || orig);
+    }
+  }
+  return found;
+}
+
+/** Relative-specifier imports, with their resolved absolute paths where they exist. */
+function localImports(src: string, fromFile: string): string[] {
+  const out: string[] = [];
+  const re = /(?:import|export)\s*(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)?\s*from\s*['"](\.[^'"]*)['"]/g;
+  for (const m of src.matchAll(re)) {
+    const resolved = resolveLocal(m[1], fromFile);
+    if (resolved) out.push(resolved);
+  }
+  return out;
+}
+
+function resolveLocal(spec: string, fromFile: string): string | null {
+  const base = path.resolve(path.dirname(fromFile), spec);
+  const candidates = [
+    base,
+    ...CANDIDATE_EXTS.map((e) => base + e),
+    ...CANDIDATE_EXTS.map((e) => path.join(base, `index${e}`)),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c) && !c.endsWith(path.sep)) {
+      try {
+        if (readFileSync(c, 'utf8')) return c;
+      } catch {
+        /* directory or unreadable — keep looking */
+      }
+    }
+  }
+  return null;
+}
+
+/** True when the canvas actually MOUNTS the element (not merely imports it). */
+function mounts(src: string, name: string): boolean {
+  return new RegExp(`<${name}[\\s/>]`).test(src);
+}
+
+/**
+ * Scan a canvas for media elements the audio renderer will reject.
+ *
+ * Follows relative imports ONE hop, because that is the real shape of the bug:
+ * `_broadcast.tsx` re-exports `Audio` from `'remotion'`, and every social canvas
+ * imports `Audio` from `_broadcast`. A scanner that reads only the canvas file
+ * sees a clean local import and misses it entirely.
+ *
+ * Returns only elements that are both reachable from `'remotion'` AND mounted in
+ * the canvas — an unused import is not worth refusing an export over.
+ */
+export function scanUnsupportedMedia(canvasAbsPath: string): UnsupportedFinding[] {
+  let src: string;
+  try {
+    src = readFileSync(canvasAbsPath, 'utf8');
+  } catch {
+    // Unreadable canvas is not this check's business to report — the export
+    // itself will fail loudly a moment later with a better message.
+    return [];
+  }
+
+  const findings: UnsupportedFinding[] = [];
+  const seen = new Set<UnsupportedElement>();
+
+  const consider = (names: Map<string, string>, sourceFile: string, viaBarrel: boolean) => {
+    for (const el of ['Audio', 'OffthreadVideo'] as const) {
+      if (seen.has(el)) continue;
+      const localName = names.get(el);
+      if (!localName) continue;
+      // Mounted under whatever name this file bound it to — see bindingsFromRemotion.
+      if (!mounts(src, localName)) continue;
+      seen.add(el);
+      findings.push({ element: el, sourceFile, viaBarrel, localName });
+    }
+  };
+
+  consider(bindingsFromRemotion(src), canvasAbsPath, false);
+
+  for (const dep of localImports(src, canvasAbsPath)) {
+    if (seen.size === 2) break;
+    try {
+      consider(bindingsFromRemotion(readFileSync(dep, 'utf8')), dep, true);
+    } catch {
+      /* unreadable dependency — nothing to assert */
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * The refusal message for a mounted `<Audio>` from `remotion`.
+ *
+ * Refuse rather than warn: a music bed silently vanishing from a finished cut is
+ * worse than an export that did not run, and the remedy is one word. This
+ * mirrors the existing "refused with remediation, never silently truncated"
+ * posture of `resolveMaxFrames`.
+ */
+export function audioRefusalMessage(f: UnsupportedFinding, canvasRel: string): string {
+  const where = f.viaBarrel
+    ? `${canvasRel} imports it from ${path.basename(f.sourceFile)}, which re-exports it from 'remotion'`
+    : `${canvasRel} imports it from 'remotion'`;
+  return (
+    `this comp mounts <Audio> from 'remotion' — which IS <Html5Audio>, and ` +
+    `@remotion/web-renderer rejects it, so the export would silently lose its audio ` +
+    `(and run ~40x slower on the frame-step fallback). ${where}. ` +
+    `Fix: import { Audio } from '@remotion/media' instead — same props, drop-in. ` +
+    `To export muted anyway, pass options.allowUnsupportedMedia.`
+  );
+}

package/apps/studio/exporters/video-encode-lib.ts

@@ -121,7 +121,18 @@ const api: MaudeEnc = {
     if (!codec) throw new Error('no encodable video codec available in this browser');
 
     const output = new Output({ format: outFormat, target: new BufferTarget() });
-    const source = new CanvasSource(canvas, { codec, bitrate: QUALITY_HIGH });
+    // `latencyMode: 'quality'` is pinned, not left to the default. Per WebCodecs
+    // §7.11 `realtime` explicitly permits the encoder to DROP frames to hit a
+    // bitrate/framerate target, while `quality` MUST NOT — and mediabunny flips
+    // MediaStream-driven sources to `realtime` automatically. We push frames
+    // through a CanvasSource so we are not in that case today, but a future
+    // refactor that routes through a stream would silently start dropping
+    // frames from an export with no error anywhere.
+    const source = new CanvasSource(canvas, {
+      codec,
+      bitrate: QUALITY_HIGH,
+      latencyMode: 'quality',
+    });
     output.addVideoTrack(source, { frameRate: fps });
     await output.start();
     const container = outFormat instanceof Mp4OutputFormat ? 'mp4' : 'webm';
@@ -132,6 +143,21 @@ const api: MaudeEnc = {
   async addVideoFrame(b64png) {
     if (!vstate) throw new Error('startVideo not called');
     const bmp = await decodeToBitmap(b64png);
+    // REJECT a mismatched frame instead of rescaling it. `drawImage` with
+    // explicit dimensions silently resamples anything that does not match the
+    // encoder canvas, so a capture whose clip drifted by a pixel produced an
+    // invisible resample seam rather than an error — the kind of defect that
+    // survives every check we have and shows up as "the export looks slightly
+    // off". Loud is the only useful behaviour here.
+    if (bmp.width !== vstate.canvas.width || bmp.height !== vstate.canvas.height) {
+      const got = `${bmp.width}×${bmp.height}`;
+      const want = `${vstate.canvas.width}×${vstate.canvas.height}`;
+      if ('close' in bmp) bmp.close();
+      throw new Error(
+        `frame ${vstate.frame} is ${got} but the encoder canvas is ${want} — ` +
+          'refusing to resample. The capture clip changed mid-export.'
+      );
+    }
     vstate.ctx.drawImage(bmp, 0, 0, vstate.canvas.width, vstate.canvas.height);
     if ('close' in bmp) bmp.close();
     await vstate.source.add(vstate.frame / vstate.fps, 1 / vstate.fps);

package/apps/studio/exporters/video-render-lib.ts

@@ -92,6 +92,12 @@ async function renderVideo(opts: RenderVideoOpts): Promise<RenderVideoResult> {
     isProduction: true,
     licenseKey: opts.licenseKey ?? 'free-license',
     logLevel: 'error',
+    // Remotion defaults this to 'medium', which yields the event loop every
+    // ~33 ms to keep a page interactive while it renders. Nobody is looking at
+    // this page — it is a headless capture Chromium with no UI — so the courtesy
+    // is pure overhead. 'disabled' is Remotion's documented setting for exactly
+    // this case (client-side rendering / page-responsiveness).
+    pageResponsiveness: 'disabled',
   });
   const blob = await result.getBlob();
   const buf = new Uint8Array(await blob.arrayBuffer());

package/apps/studio/exporters/video.ts

@@ -21,6 +21,7 @@ import path from 'node:path';
 
 import { getEncodeLibBundle, getWebRendererBundle } from './_browser-bundles.ts';
 import { exportShimPath, runShim } from './_runtime.ts';
+import { type ExportDegradation, hasAudioStream, remedyFor } from './degraded.ts';
 import {
   canvasShellUrl,
   type ExportContext,
@@ -29,6 +30,7 @@ import {
   type ExportResult,
 } from './index.ts';
 import type { Target } from './scope.ts';
+import { audioRefusalMessage, scanUnsupportedMedia } from './unsupported-media.ts';
 
 // DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
 const VIDEO_PLAYWRIGHT = exportShimPath('_video-playwright.mjs');
@@ -67,6 +69,30 @@ async function runVideo(
     );
   }
 
+  // Pre-flight the two elements the audio renderer rejects, BEFORE launching a
+  // browser (RCA issue-mp4-audio-export-html5audio-silent-degrade). This is
+  // decidable from source and always fails, so discovering it 37 minutes later
+  // via a muted file is pure waste. GIF is silent by format, so it is exempt.
+  let preStamped: ExportDegradation | undefined;
+  if (format !== 'gif' && options.allowUnsupportedMedia !== true) {
+    const canvasAbs = path.resolve(ctx.repoRoot, el.file);
+    for (const finding of scanUnsupportedMedia(canvasAbs)) {
+      if (finding.element === 'Audio' && options.audio !== false) {
+        // Refuse. A vanished music bed is worse than an export that did not run.
+        throw new Error(audioRefusalMessage(finding, el.file));
+      }
+      if (finding.element === 'OffthreadVideo') {
+        // Warn, don't refuse — <OffthreadVideo> is often legitimately silent
+        // b-roll, so blocking the export would be the wrong trade.
+        preStamped = {
+          audioDropped: true,
+          reason: `<OffthreadVideo> in ${el.file} is not supported by @remotion/web-renderer`,
+          remedy: remedyFor('OffthreadVideo'),
+        };
+      }
+    }
+  }
+
   // gif has no renderMediaOnWeb container support (and no audio need — GIF is a
   // silent format), so it never needs the render-lib bundle; mp4/webm build it
   // alongside the frame-step encode-lib (the shim decides per-target at runtime
@@ -150,6 +176,13 @@ async function runVideo(
       // the fast one-pass renderer finishes before progress matters and reports
       // none until done (it exposes no per-frame hook) — acceptable.
       onProgress: hooks?.onProgress,
+      // One line per export naming where the time actually went, and which of
+      // the two capture paths ran. Previously neither was recoverable after the
+      // fact — "which path did this take?" needed a dig through the desktop
+      // app's stderr, if it was still there.
+      onTiming: (timing) => {
+        console.error(`⏱ ${format} export: ${JSON.stringify(timing)}`);
+      },
     });
     const body = new Uint8Array(readFileSync(outPath));
     // The container can differ from the request (mp4 → webm fallback when the
@@ -159,6 +192,9 @@ async function runVideo(
     // issue-video-mp4-rendermediaonweb-stack-overflow) — surfaced here so the
     // dropped audio isn't silent (job stderr / logs; a UI toast is a follow-up).
     let ext: string = format;
+    // A pre-flight finding stands unless the shim reports its own, more specific
+    // cause below — never let a clean-looking summary erase a known defect.
+    let degraded: ExportDegradation | undefined = preStamped;
     try {
       const lastLine = stdoutLines.at(-1) ?? '{}';
       const summary = JSON.parse(lastLine) as {
@@ -169,19 +205,44 @@ async function runVideo(
       };
       if (summary.container) ext = summary.container;
       if (summary.degraded) {
+        const reason = summary.fallbackReason ?? 'unknown';
         console.error(
           `⚠ ${format} export degraded: the audio renderer failed ` +
-            `(${summary.fallbackReason ?? 'unknown'}), so this file was captured ` +
+            `(${reason}), so this file was captured ` +
             'frame-by-frame and has no audio.'
         );
+        // This used to stop at the console.error above — the flags were parsed
+        // and then dropped on the floor, so `jobs.ts` set `done` with nothing to
+        // say otherwise and the user got a muted file with a green checkmark.
+        // RCA issue-mp4-audio-export-html5audio-silent-degrade.
+        degraded = {
+          audioDropped: summary.audioDropped !== false,
+          reason,
+          remedy: remedyFor(reason),
+        };
       }
     } catch {
       /* keep the requested ext */
     }
+    // Artifact-level backstop. Everything above trusts a report; this checks the
+    // bytes. The RCA's defining property was that every other signal said the
+    // export was fine — so the last word belongs to the file itself.
+    if (!degraded && wantAudio && format !== 'gif' && !hasAudioStream(body, ext)) {
+      degraded = {
+        audioDropped: true,
+        reason: `the produced ${ext} has no audio track, though audio was requested`,
+        remedy:
+          'Check that the comp mounts <Audio>/<Video> from @remotion/media — ' +
+          "elements imported from 'remotion' are dropped by the audio renderer.",
+      };
+      console.error(`⚠ ${format} export produced no audio track despite audio being requested.`);
+    }
+
     return {
       filename: `${el.canvasSlug}.${ext}`,
       contentType: CONTENT_TYPE[ext] ?? 'application/octet-stream',
       body,
+      degraded,
     };
   } finally {
     rmSync(tmp, { recursive: true, force: true });