@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/bin/_perf-shared.mjs

@@ -0,0 +1,345 @@
+// _perf-shared.mjs — the measurement contract shared by every `maude design perf`
+// engine lane (Chromium via agent-browser, WebKit via safaridriver).
+//
+// It lives in one file on purpose. Two lanes with two copies of the gesture
+// script would drift, and the moment they drift the engines stop being
+// comparable — which is the only thing this benchmark is for.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+// ── The in-page harness ──────────────────────────────────────────────────────
+//
+// Synthesizes the same wheel events the viewport controller listens for
+// (`canvas-lib.tsx` onWheel: plain wheel = 2D pan, ctrlKey wheel = pinch-zoom —
+// a macOS trackpad pinch arrives as ctrlKey:true, so this is the real gesture
+// path, not a side door).
+//
+// Runs async and parks its result on `window.__maudePerfResult`, which the
+// caller polls: both driver protocols return one synchronous value per eval and
+// cannot await.
+export function harnessSource({ pan, zoom, injectCss, fitAll, setFlags }) {
+  const flagBlock = (setFlags || []).map((f) => `\n  win[${JSON.stringify(f)}] = true;`).join('');
+  const cssBlock = injectCss
+    ? `
+  {
+    const st = doc.createElement('style');
+    st.id = 'maude-perf-variant';
+    st.textContent = ${JSON.stringify(injectCss)};
+    doc.head.appendChild(st);
+  }`
+    : '';
+  return `(() => {
+  const host = document.querySelector('.dc-canvas') ||
+               (document.querySelector('iframe') &&
+                document.querySelector('iframe').contentDocument &&
+                document.querySelector('iframe').contentDocument.querySelector('.dc-canvas'));
+  if (!host) return 'NO_HOST';
+  const doc = host.ownerDocument;
+  const win = doc.defaultView;
+  win.__maudePerfResult = null;${flagBlock}${cssBlock}
+
+  // Render counter, installed by canvas-lib when this object exists. Absent
+  // instrumentation reports null rather than zero — "not measured" and
+  // "measured zero" must never look alike in a baseline.
+  win.__dcPerf = { artboardRenders: 0, annotationRenders: 0 };
+
+  const frames = [];
+  let longtasks = 0;
+  let po = null;
+  try {
+    po = new win.PerformanceObserver((list) => { longtasks += list.getEntries().length; });
+    po.observe({ entryTypes: ['longtask'] });
+  } catch { /* longtask unsupported (WebKit) — count stays 0, frames still tell the story */ }
+
+  let last = 0;
+  let running = true;
+  const tick = (t) => {
+    if (last) frames.push(t - last);
+    last = t;
+    if (running) win.requestAnimationFrame(tick);
+  };
+  win.requestAnimationFrame(tick);
+
+  const rect = host.getBoundingClientRect();
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+
+  const wheel = (dx, dy, ctrl) => host.dispatchEvent(new win.WheelEvent('wheel', {
+    deltaX: dx, deltaY: dy, ctrlKey: !!ctrl,
+    clientX: cx, clientY: cy, bubbles: true, cancelable: true,
+  }));
+
+  const nextFrame = () => new Promise((r) => win.requestAnimationFrame(() => r()));
+
+  // The world transform is the ground truth that the gesture LANDED. Without
+  // this check a probe whose synthetic events get swallowed reports a beautiful
+  // 60fps idle page as a baseline — the exact way a benchmark lies.
+  const world = doc.querySelector('.dc-world');
+  const transformOf = () => (world ? win.getComputedStyle(world).transform + '|' + (world.style.zoom || '') : '');
+
+  (async () => {
+    // Warm-up: one frame so the first measured delta isn't the install cost.
+    await nextFrame();
+
+    // FIT-ALL first when asked. This is the state the moodboard RCA identified
+    // as the painful one and the state a probe most easily misses: at the
+    // canvas's stored viewport only a handful of boards are on screen, so
+    // content-visibility culls the rest and the measurement flatters the
+    // engine. Zoomed out to the whole plane nothing culls, every board paints,
+    // and that is where the user says it stops being usable. Cmd+0 is the
+    // canvas's own fit shortcut (canvas-lib keydown, case 0).
+    // NB: no backticks in this comment — it lives inside a template literal.
+    if (${fitAll ? 'true' : 'false'}) {
+      doc.dispatchEvent(new win.KeyboardEvent('keydown', {
+        key: '0', code: 'Digit0', metaKey: true, bubbles: true, cancelable: true,
+      }));
+      host.dispatchEvent(new win.KeyboardEvent('keydown', {
+        key: '0', code: 'Digit0', metaKey: true, bubbles: true, cancelable: true,
+      }));
+      // Let the fit animation finish before the measured gesture starts.
+      await new Promise((r) => win.setTimeout(r, 800));
+    }
+    // Baseline for the did-it-move check is taken HERE, after any fit, not at
+    // harness install. Repeated passes are deterministic: pass N ends exactly
+    // where "fit + the same pan" lands, so an install-time baseline compares two
+    // identical states and rejects a gesture that ran perfectly.
+    const t0 = transformOf();
+    const panStart = frames.length;
+    for (let i = 0; i < ${pan}; i++) { wheel(-12, -9, false); await nextFrame(); }
+    const panEnd = frames.length;
+    const tPan = transformOf();
+
+    // Zoom: alternate in/out so the run neither drifts to the zoom clamp nor
+    // ends somewhere a follow-up run would start from differently.
+    // Zoom IN first, then back out — symmetric (net scale change ~0) but it
+    // starts in the direction that always has headroom. Starting outward dies
+    // at fit-all, where the viewport already sits on ZOOM_MIN: the clamp makes
+    // the first half a no-op, the transform never moves, and the validity gate
+    // correctly rejects the whole run.
+    // Sampled at the TURNAROUND, not at the end: the run is symmetric, so its
+    // endpoint transform equals its start. Comparing endpoints would report
+    // "zoom never happened" for a zoom that happened twice.
+    let tZoomMid = '';
+    for (let i = 0; i < ${zoom}; i++) {
+      wheel(0, i < ${zoom} / 2 ? -8 : 8, true);
+      await nextFrame();
+      if (i === Math.floor(${zoom} / 2) - 1) tZoomMid = transformOf();
+    }
+    const zoomEnd = frames.length;
+    const tZoom = tZoomMid;
+
+    // Settle window — the tail spike after the gesture is its own symptom
+    // ("seká po dojezdu"), so it is measured separately, not averaged away.
+    const settleStart = frames.length;
+    await new Promise((r) => win.setTimeout(r, 900));
+    running = false;
+    if (po) { try { po.disconnect(); } catch {} }
+
+    const slice = (a, b) => frames.slice(a, b).filter((n) => n > 0);
+    const pct = (arr, p) => {
+      if (!arr.length) return null;
+      const s = arr.slice().sort((a, b) => a - b);
+      return Math.round(s[Math.min(s.length - 1, Math.floor(s.length * p))] * 100) / 100;
+    };
+    const stat = (arr) => ({
+      frames: arr.length,
+      p50: pct(arr, 0.5),
+      p95: pct(arr, 0.95),
+      max: arr.length ? Math.round(Math.max(...arr) * 100) / 100 : null,
+    });
+
+    const gestureFrames = slice(panStart, zoomEnd);
+    win.__maudePerfResult = {
+      pan: stat(slice(panStart, panEnd)),
+      zoom: stat(slice(panEnd, zoomEnd)),
+      gesture: stat(gestureFrames),
+      settle: stat(slice(settleStart, frames.length)),
+      longtasks,
+      artboardRenders: win.__dcPerf ? win.__dcPerf.artboardRenders : null,
+      annotationRenders: win.__dcPerf ? win.__dcPerf.annotationRenders : null,
+      instrumented: !!(win.__dcPerf && win.__dcPerf.instrumented),
+      panApplied: tPan !== t0,
+      zoomApplied: tZoom !== tPan,
+    };
+  })();
+  return 'STARTED';
+})()`;
+}
+
+/**
+ * Shape check behind `parseAndValidateResult` — validates a harness result
+ * before ANY of it is printed or recorded.
+ *
+ * The harness parks its result on `window.__maudePerfResult` — a global inside
+ * the canvas origin, which DDR-054 treats as untrusted. A canvas from a cloned
+ * repo can define that global itself, ahead of our IIFE, and hand back whatever
+ * shape it likes. The numbers would be laundered downstream by Math.round, but
+ * the per-pass progress line and the refusal message print fields verbatim, so
+ * without this gate a hostile canvas gets attacker-authored text into the
+ * invoking agent's transcript wearing a first-party tool's voice.
+ *
+ * Returns the value only when every leaf is the primitive it claims to be.
+ */
+export function parseAndValidateResult(raw) {
+  let decoded;
+  try {
+    decoded = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    // The PARSE is part of the trust boundary, not a step before it. A canvas
+    // owns its window and can replace JSON.stringify, so `raw` is arbitrary
+    // text — and a JSON.parse SyntaxError quotes a snippet of its input, which
+    // would carry attacker-authored text into the invoking agent's transcript
+    // through the generic error handler.
+    return null;
+  }
+  return validateResult(decoded);
+}
+
+function validateResult(r) {
+  const num = (v) => v === null || (typeof v === 'number' && Number.isFinite(v));
+  const stat = (o) => o && typeof o === 'object' && num(o.p50) && num(o.p95) && num(o.max);
+  if (!r || typeof r !== 'object') return null;
+  if (!stat(r.gesture) || !stat(r.pan) || !stat(r.zoom) || !stat(r.settle)) return null;
+  if (!num(r.longtasks) || !num(r.artboardRenders) || !num(r.annotationRenders)) return null;
+  if (typeof r.panApplied !== 'boolean' || typeof r.zoomApplied !== 'boolean') return null;
+  if (typeof r.instrumented !== 'boolean') return null;
+  return r;
+}
+
+/** Median across kept passes — robust to the one pass that hit a GC. */
+export function medianOf(passes) {
+  const med = (pick) => {
+    const vals = passes.map(pick).filter((v) => v != null);
+    if (!vals.length) return null;
+    const s = vals.slice().sort((a, b) => a - b);
+    return Math.round(s[Math.floor(s.length / 2)] * 100) / 100;
+  };
+  return {
+    pan: { p95: med((p) => p.pan.p95) },
+    zoom: { p95: med((p) => p.zoom.p95) },
+    gesture: {
+      p50: med((p) => p.gesture.p50),
+      p95: med((p) => p.gesture.p95),
+      max: med((p) => p.gesture.max),
+    },
+    settle: { max: med((p) => p.settle.max) },
+    longtasks: med((p) => p.longtasks),
+    artboardRenders: med((p) => p.artboardRenders),
+    annotationRenders: med((p) => p.annotationRenders),
+    instrumented: passes.some((p) => p.instrumented),
+    passes: passes.length,
+    // The spread across kept passes IS a result: a delta smaller than this is
+    // noise, and the report says so rather than leaving the reader to guess.
+    p95Spread:
+      passes.length > 1
+        ? Math.round(
+            (Math.max(...passes.map((p) => p.gesture.p95)) -
+              Math.min(...passes.map((p) => p.gesture.p95))) *
+              100
+          ) / 100
+        : null,
+  };
+}
+
+export function buildRow({ result, label, engineTag, opts }) {
+  return {
+    date: new Date().toISOString(),
+    canvas: label,
+    engine: engineTag,
+    url: opts.url,
+    panFrames: opts.pan,
+    zoomFrames: opts.zoom,
+    p50FrameMs: result.gesture.p50,
+    p95FrameMs: result.gesture.p95,
+    maxFrameMs: result.gesture.max,
+    panP95Ms: result.pan.p95,
+    zoomP95Ms: result.zoom.p95,
+    settleMaxMs: result.settle.max,
+    longtasks: result.longtasks,
+    artboardRenders: result.artboardRenders,
+    annotationRenders: result.annotationRenders,
+    instrumented: result.instrumented,
+    passes: result.passes,
+    p95SpreadMs: result.p95Spread,
+  };
+}
+
+/** Delta vs the previous run of the same (canvas, engine) pair. */
+export function deltaLine(label, cur, prev, unit = 'ms') {
+  if (cur == null) return `  ${label.padEnd(22)} —`;
+  if (prev == null) return `  ${label.padEnd(22)} ${cur}${unit}   (no prior run)`;
+  const d = Math.round((cur - prev) * 100) / 100;
+  const pctChange = prev === 0 ? null : Math.round((d / prev) * 1000) / 10;
+  const arrow = d === 0 ? '=' : d < 0 ? '▼' : '▲';
+  const pctTxt = pctChange == null ? '' : ` ${pctChange > 0 ? '+' : ''}${pctChange}%`;
+  return `  ${label.padEnd(22)} ${cur}${unit}   ${arrow} ${d > 0 ? '+' : ''}${d}${unit}${pctTxt}  (was ${prev}${unit})`;
+}
+
+export function readHistory(path, label, engineTag) {
+  if (!path || !existsSync(path)) return null;
+  let prev = null;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.canvas === label && row.engine === engineTag) prev = row;
+    } catch {
+      /* a corrupt line must not sink the run — history is a convenience, not a source of truth */
+    }
+  }
+  return prev;
+}
+
+/**
+ * One-line, control-character-free rendering of a caller-supplied string.
+ * A canvas filename comes from the repo and POSIX allows newlines in it, so
+ * echoing one raw lets a hostile repo inject its own line into a report an
+ * agent reads.
+ */
+function safeLabel(v) {
+  let out = '';
+  for (const ch of String(v).slice(0, 200)) {
+    const code = ch.codePointAt(0);
+    const unsafe =
+      code < 0x20 || // C0 — newline and friends: the line-injection case
+      code === 0x7f || // DEL
+      (code >= 0x80 && code <= 0x9f) || // C1 — some terminals still act on these
+      (code >= 0x202a && code <= 0x202e) || // bidi embedding / override
+      (code >= 0x2066 && code <= 0x2069); // bidi isolates
+    // Bidi controls can't break a line, but they can visually reorder one, so a
+    // filename could make a report read differently than it is.
+    out += unsafe ? ' ' : ch;
+  }
+  return out;
+}
+
+export function renderReport({ row, prev, opts, label, engineTag }) {
+  const out = [];
+  out.push(`\n  canvas: ${safeLabel(label)}    engine: ${safeLabel(engineTag)}`);
+  out.push(`  gesture: ${opts.pan} pan frames + ${opts.zoom} zoom frames\n`);
+  out.push(deltaLine('frame p50', row.p50FrameMs, prev?.p50FrameMs));
+  out.push(deltaLine('frame p95', row.p95FrameMs, prev?.p95FrameMs));
+  out.push(deltaLine('frame max', row.maxFrameMs, prev?.maxFrameMs));
+  out.push(deltaLine('pan p95', row.panP95Ms, prev?.panP95Ms));
+  out.push(deltaLine('zoom p95', row.zoomP95Ms, prev?.zoomP95Ms));
+  out.push(deltaLine('settle max', row.settleMaxMs, prev?.settleMaxMs));
+  out.push(deltaLine('long tasks', row.longtasks, prev?.longtasks, ''));
+  out.push(deltaLine('artboard renders', row.artboardRenders, prev?.artboardRenders, ''));
+  out.push(deltaLine('annotation renders', row.annotationRenders, prev?.annotationRenders, ''));
+  if (!row.instrumented) {
+    out.push(
+      '\n  note: render counters are not instrumented in this build — frame timings are still valid.'
+    );
+  }
+  if (row.p95SpreadMs != null) {
+    out.push(
+      `\n  p95 spread across ${row.passes} kept passes: ${row.p95SpreadMs}ms ` +
+        '— treat any delta smaller than this as noise.'
+    );
+  }
+  if (opts.history) out.push(`\n  history: ${opts.history}`);
+  out.push(
+    `  ${prev ? 'compared against the previous run' : 'first run — this IS the baseline'}\n`
+  );
+  return out.join('\n');
+}

package/apps/studio/bin/_video-playwright.mjs

@@ -25,7 +25,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { launchChromium } from './_pw-launch.mjs';
+import { assertRenderOutputSizeOk, launchChromium } from './_pw-launch.mjs';
 
 const args = Object.fromEntries(
   process.argv.slice(2).reduce((acc, cur, i, all) => {
@@ -47,6 +47,7 @@ const {
   out, // encoded file destination
   mode = 'comp', // 'comp' | 'ordinary'
   audio, // '1' | '0' — include audio in the render-lib path (default on; presence-checked below)
+  'frame-format': frameFormatArg, // 'jpeg' | 'png' (default) — the frame-step screenshot intermediate, Task 9
   'license-key': licenseKeyArg,
   timeout = '60',
   scale = '1',
@@ -67,11 +68,32 @@ const deviceScaleFactor = Math.max(1, Math.min(4, Number(scale) || 1));
 // always passes an explicit '0'/'1'.
 const wantAudio = audio !== '0';
 const licenseKey = licenseKeyArg || 'free-license';
+// Task 9 — opt-in JPEG frame-step intermediate; unrecognized/absent value is PNG.
+const frameFormat = frameFormatArg === 'jpeg' ? 'jpeg' : 'png';
 
 /** Wait a real turn of the event loop + a frame so a seek settles before shot. */
 const SETTLE_MS = 16;
 
-const browser = await launchChromium();
+// GPU opt-in, measured not assumed (2026-08-09, M-series mac, 1920x1080):
+//
+//   config                        h264 prefer-hardware   png        jpeg q90
+//   headless-shell (default)      FALSE                  51ms/187KB 33ms/43KB
+//   headless-shell --enable-gpu   true                   34ms/84KB  33ms/43KB
+//   full chromium / real Chrome   true                   34-49ms    17-33ms
+//
+// So today's engine is the ONE configuration that cannot reach a hardware
+// encoder at all — `chrome-headless-shell` forces ANGLE/SwiftShader, and
+// Chromium then reports ACCELERATED_VIDEO_ENCODE as disabled. `--enable-gpu`
+// flips that.
+//
+// It is NOT on by default, deliberately: with the GPU the same page rasterizes
+// to a materially different PNG (84KB vs 187KB), i.e. it is a VISUAL change to
+// every export, and encode is not the bottleneck anyway (~50ms of a ~1050ms
+// frame — see the MAUDE_TIMING line). Changing how a design tool renders is not
+// something to smuggle in behind a perf flag. Opt in with MAUDE_CAPTURE_GPU=1.
+const gpuArgs =
+  process.env.MAUDE_CAPTURE_GPU === '1' ? ['--enable-gpu', '--ignore-gpu-blocklist'] : [];
+const browser = await launchChromium(gpuArgs.length ? { args: gpuArgs } : undefined);
 try {
   const ctx = await browser.newContext({
     viewport: { width: 1440, height: 900 },
@@ -199,6 +221,19 @@ try {
         audioCodec: rendered.audioCodec,
       };
       const ms = Date.now() - t0;
+      // Same shape as the frame-step line, so the two paths are directly
+      // comparable — that comparison is the whole speed story (~45 s vs ~37 min
+      // on the same canvas, per RCA issue-mp4-audio-export-html5audio-silent-degrade).
+      console.log(
+        `MAUDE_TIMING ${JSON.stringify({
+          path: 'renderer',
+          frames: frameCount,
+          totalMs: ms,
+          msPerFrame: Math.round((ms / Math.max(1, frameCount)) * 10) / 10,
+          scale: deviceScaleFactor,
+          audioCodec: rendered.audioCodec,
+        })}`
+      );
       console.error(
         `✓ rendered ${rendered.container}/${rendered.videoCodec}` +
           `${rendered.audioCodec ? `+${rendered.audioCodec}` : ' (muted)'} → ${out} (${rendered.bytes} B) in ${ms}ms`
@@ -235,6 +270,7 @@ try {
         mode,
         deviceScaleFactor,
         timeoutMs,
+        frameFormat,
         fallbackReason: renderFallbackReason,
       });
     } catch (fallbackErr) {
@@ -276,6 +312,10 @@ async function frameStepCapture({
   mode,
   deviceScaleFactor,
   timeoutMs,
+  // Task 9 — 'jpeg' | 'png' (default). Only ever affects the encode transport,
+  // never a --dump-frames debug dump (that always stays lossless PNG) and
+  // never gif (video.ts refuses to pass 'jpeg' through for gif).
+  frameFormat = 'png',
   // Set (to the renderer's error message) only when this run is the
   // graceful-degradation fallback for a failed renderMediaOnWeb path; stamps
   // `degraded`/`audioDropped` onto the stdout summary so video.ts can warn.
@@ -368,6 +408,11 @@ async function frameStepCapture({
   // frame is drawn down to the native artboard size (the "tiny resolution" bug:
   // scale was accepted but never applied to the encode). scale=2 → 960×540 comp
   // exports at 1920×1080. Even dims (H.264 requires width/height divisible by 2).
+  // The video path is the ONE capture path that holds a full-resolution surface
+  // across thousands of frames, and it was the only one with no output-size
+  // guard — _pdf-playwright.mjs has enforced this since it existed. A scale-3
+  // 1080p comp allocates ~74MB per frame here.
+  assertRenderOutputSizeOk(clip.width, clip.height, deviceScaleFactor, '_video-playwright');
   const outW = Math.max(2, Math.round((clip.width * deviceScaleFactor) / 2) * 2);
   const outH = Math.max(2, Math.round((clip.height * deviceScaleFactor) / 2) * 2);
 
@@ -398,24 +443,45 @@ async function frameStepCapture({
     console.error(`encoder: ${started.container} / ${started.codec} @ ${outW}×${outH}`);
   }
 
+  // Per-stage accumulators. "The export takes 15 minutes" was, for a long time,
+  // answerable only by guessing which stage owned the second — so every
+  // optimization was aimed at a suspicion. One line at the end fixes that.
+  // Task 9 — a debug dump must stay lossless (it's for human inspection), and
+  // gif never gets a lossy intermediate stacked under its own quantization —
+  // so the knob only actually applies to a plain video encode.
+  const useJpeg = frameFormat === 'jpeg' && !isGif && !dump;
+  const shotFormat = useJpeg ? 'jpeg' : 'png';
+  const stageMs = { seek: 0, settle: 0, screenshot: 0, encode: 0 };
   for (let f = 0; f < frameCount; f += 1) {
+    const tSeek = Date.now();
     await seekFrame(page, f, fps, mode);
+    stageMs.seek += Date.now() - tSeek;
+    const tSettle = Date.now();
     await page.waitForTimeout(SETTLE_MS);
-    const shot = await page.screenshot({ clip });
+    stageMs.settle += Date.now() - tSettle;
+    const tShot = Date.now();
+    const shot = await page.screenshot(useJpeg ? { clip, type: 'jpeg', quality: 90 } : { clip });
+    stageMs.screenshot += Date.now() - tShot;
     if (dump) {
       const p = join(dump, `frame-${String(f).padStart(5, '0')}.png`);
       writeFileSync(p, shot);
       framePaths.push(p);
     }
     if (encoding) {
+      const tEnc = Date.now();
       const b64 = shot.toString('base64');
       await page.evaluate(
-        async ({ b64, isGif }) => {
+        async ({ b64, isGif, format }) => {
           if (isGif) return window.__maudeEnc.addGifFrame(b64);
-          return window.__maudeEnc.addVideoFrame(b64);
+          return window.__maudeEnc.addVideoFrame(b64, format);
         },
-        { b64, isGif }
+        { b64, isGif, format: shotFormat }
       );
+      // NB: this stage is the double CDP crossing — the screenshot bytes go out
+      // to node as base64 and straight back into the same page, to an encoder
+      // that lives in that page. Its share of the total is what decides whether
+      // transport work is worth doing at all.
+      stageMs.encode += Date.now() - tEnc;
     }
     // Machine-readable progress (stdout) — spawnShim parses `MAUDE_PROGRESS`
     // lines → onProgress → job.progress → the live bar in the Exports panel, so
@@ -426,6 +492,18 @@ async function frameStepCapture({
     if (f % 30 === 0) console.error(`frame ${f + 1}/${frameCount}`);
   }
 
+  // A seek that never landed means at least one encoded frame shows the wrong
+  // content. There is no way to tell WHICH from the outside and no way for the
+  // user to notice, so the export dies here rather than shipping a file that
+  // looks fine. Counted in-page by the seek bridge (video-comp.tsx).
+  const seekFailures = await page.evaluate(() => window.__maude_seek_failures__ ?? 0);
+  if (seekFailures > 0) {
+    throw new Error(
+      `${seekFailures} frame seek(s) never landed — the capture would contain stale ` +
+        'frames. Refusing to encode. This usually means the comp failed to mount.'
+    );
+  }
+
   let result = { fps, frameCount, width: outW, height: outH, framePaths };
   // Degradation marker — this run only encodes video (no audio), so when we're
   // standing in for a failed audio renderer, tell the exporter the export is
@@ -448,6 +526,19 @@ async function frameStepCapture({
   console.error(
     `✓ captured ${frameCount} frames @ ${fps}fps (${clip.width}×${clip.height}) in ${ms}ms`
   );
+  // Machine-readable, filtered out of stdoutLines by _runtime.ts (the adapters
+  // parse the LAST stdout line as their summary, so this must never be it).
+  console.log(
+    `MAUDE_TIMING ${JSON.stringify({
+      path: 'frame-step',
+      frames: frameCount,
+      totalMs: ms,
+      msPerFrame: Math.round((ms / Math.max(1, frameCount)) * 10) / 10,
+      stageMs,
+      scale: deviceScaleFactor,
+      out: { width: outW, height: outH },
+    })}`
+  );
   // stdout = machine-readable summary for the exporter.
   console.log(JSON.stringify(result));
 }
@@ -486,6 +577,10 @@ async function seekFrame(page, frame, fps, mode) {
     return;
   }
   // comp mode — the seek bridge pauses + seeks the Player and resolves post-paint.
+  // It now REJECTS when a seek never lands (video-comp.tsx), instead of resolving
+  // as if it had; that rejection propagates out of this evaluate and fails the
+  // export, which is the point — a stale frame is a valid-looking file with the
+  // wrong pixels, and no downstream check would ever catch it.
   // A comp with classic remotion <Video>/<OffthreadVideo> renders a real <video>
   // whose seek is ASYNC — 2 rAF isn't enough, so wait for every video to land on
   // its frame (`seeked` / readyState) before the screenshot, else a stale frame
@@ -494,7 +589,8 @@ async function seekFrame(page, frame, fps, mode) {
   // on (verified across mid-clip + mid-transition frames — DDR-148 addendum).
   await page.evaluate(async (frame) => {
     if (typeof window.__maude_seek__ === 'function') {
-      await window.__maude_seek__(frame);
+      // strict: a capture must never proceed on a seek that did not land.
+      await window.__maude_seek__(frame, { strict: true });
     }
     const vids = Array.from(document.querySelectorAll('video'));
     if (vids.length) {

package/apps/studio/bin/import-figma.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# import-figma.sh — Figma / FigJam import (REST door). Thin shim over
+# _import-figma.mjs; reached via `maude design import-figma` (DDR-062), never a
+# raw bin path. See _import-figma.mjs + DDR-216 for the full architecture +
+# security rationale. Requires bun — _import-figma.mjs imports the `.ts`
+# annotation model and figma modules directly, same constraint as
+# import-tokens.sh.
+#
+# All args are forwarded quoted ("$@") — never unquoted or eval-expanded. This
+# matters more than usual here: a Figma URL is caller-supplied and a node id
+# rides in its query string. The charset/shape validation itself happens in
+# figma/url.ts, not in this shell (DDR-216 D4); the wrapper's ONLY job is safe
+# argv passthrough.
+#
+# Usage:
+#   import-figma.sh --board  <figjam-url> --root <repo> [--design-root .design]
+#                   [--slug <name>] [--dry-run] [--json]
+#   import-figma.sh --pages  <figma-url>  --root <repo> [--folder <name>] [--editable]
+#   import-figma.sh --frames <figma-url>  --root <repo>   (Phase 3)
+#   import-figma.sh --tokens <figma-url>  --root <repo>   (Phase 4)
+#   import-figma.sh --explode <artboard-id> --canvas <rel-path> --root <repo>
+#                   [--confirm-document] [--dry-run] [--json]      (Phase 7)
+#
+# Needs a Figma personal access token with the `file_content:read` scope, added
+# once in Settings.
+#
+# `--explode` needs NO token — it reads the Figma DESKTOP app's local Dev Mode
+# MCP server over loopback (DDR-219 D2) rather than the REST API. It does need
+# that app running, in Dev Mode, with the same file as the active tab, on a Dev
+# or Full seat. It is not an import route: the artboard must already exist on an
+# imported canvas.
+#
+# Exit: 0 ok · 1 other · 2 usage · 3 validation reject · 4 fetch/parse error ·
+#       5 no token configured · 6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,34p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-figma.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+exec bun run "$SCRIPT_DIR/_import-figma.mjs" "$@"