@1agh/maude 0.39.0 → 0.40.0

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

@@ -45,7 +45,15 @@ const browser = await launchChromium();
 try {
   const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
   const page = await ctx.newPage();
-  await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+  await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
+  await page.evaluate(() => document.fonts.ready);
+  // `load` fires before React mounts (and a video comp never reaches
+  // `networkidle`), so gate on the artboard rendering before we query it —
+  // otherwise a multi `.all()` can run against an empty page.
+  await page
+    .locator(selector ?? '[data-dc-screen]')
+    .first()
+    .waitFor({ state: 'visible', timeout: timeoutMs });
   // Reset the world plane's CSS zoom + transform so the captured artboard
   // outerHTML carries 1440×900 dimensions instead of the pan-zoomed thumb.
   await page.evaluate(() => {

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

@@ -43,13 +43,20 @@ const browser = await launchChromium();
 try {
   const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
   const page = await ctx.newPage();
-  await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+  await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
   // Wait for web fonts so `@font-face` glyphs land in the PDF instead of
   // fallback Latin (puppeteer #3183 / playwright equivalent).
   await page.evaluate(() => document.fonts.ready);
   // Print-media emulation — Chromium's PDF output otherwise applies *screen*
   // CSS and ignores `@media print` rules entirely.
   await page.emulateMedia({ media: 'print' });
+  // `load` fires before React mounts (and a video comp never reaches
+  // `networkidle`), so gate on the artboard rendering before we query it —
+  // otherwise a multi `.all()` can run against an empty page.
+  await page
+    .locator(selector ?? '[data-dc-screen]')
+    .first()
+    .waitFor({ state: 'visible', timeout: timeoutMs });
 
   const written = [];
   const screens = multi

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

@@ -46,8 +46,15 @@ try {
     deviceScaleFactor,
   });
   const page = await ctx.newPage();
-  await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+  await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
   await page.evaluate(() => document.fonts.ready);
+  // `load` fires before React mounts (and a video comp never reaches
+  // `networkidle`), so gate on the artboard element actually rendering before we
+  // query/capture — otherwise a multi `.all()` can run against an empty page.
+  await page
+    .locator(selector ?? '[data-dc-screen]')
+    .first()
+    .waitFor({ state: 'visible', timeout: timeoutMs });
 
   const written = [];
 

package/apps/studio/bin/_pw-launch.mjs

@@ -14,6 +14,10 @@
 //
 // See `.ai/logs/rca/issue-nefunguji-exporty.md`.
 
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright';
 
 /** Exit code the shims surface for "Chromium browser binary not installed". */
@@ -23,6 +27,43 @@ export const NO_BROWSER_EXIT = 3;
 export const INSTALL_HINT =
   "Playwright's Chromium browser isn't installed. Run:  npx playwright install chromium";
 
+/**
+ * Resolve a Chrome-family executable to fall back on when Playwright's OWN
+ * bundled browser is absent — the packaged desktop case (RCA
+ * issue-desktop-export-failures): the app ships the `playwright` JS closure but
+ * NOT its ~150 MB browser, so `chromium.launch()` with no `executablePath` finds
+ * nothing. Priority: explicit env override → the shared `_ensure-browser.mjs`
+ * resolver (the same Chrome / provisioned chrome-headless-shell the screenshot
+ * path uses; `--no-download` so an export never silently triggers a 94 MB
+ * fetch). Returns `undefined` when nothing is found — the caller then surfaces
+ * the install hint. Reachable at runtime because the shim runs under real `node`
+ * (its `import.meta.url` is a genuine disk path, unlike the compiled server).
+ */
+function resolveBrowserExecutable() {
+  for (const env of [
+    process.env.MAUDE_BROWSER_EXECUTABLE,
+    process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+    process.env.AGENT_BROWSER_EXECUTABLE_PATH,
+  ]) {
+    if (env && existsSync(env)) return env;
+  }
+  try {
+    const ensure = join(dirname(fileURLToPath(import.meta.url)), '_ensure-browser.mjs');
+    if (!existsSync(ensure)) return undefined;
+    const out = execFileSync(process.execPath, [ensure, '--no-download', '--quiet'], {
+      encoding: 'utf8',
+    });
+    const path = out
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .pop();
+    return path && existsSync(path) ? path : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * True when a `chromium.launch()` rejection is the "browser binary not
  * downloaded" case (as opposed to a sandbox / port / crash failure). Pure +
@@ -51,6 +92,19 @@ export async function launchChromium(opts) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (isMissingBrowserError(msg)) {
+      // Playwright's own browser isn't present (packaged desktop app, or a fresh
+      // machine that never ran `playwright install`). Retry once against a
+      // resolved Chrome-family engine — system Chrome / a provisioned
+      // chrome-headless-shell — before giving up. This is what makes render
+      // export work in the bundled app, where only the playwright JS ships.
+      const executablePath = resolveBrowserExecutable();
+      if (executablePath) {
+        try {
+          return await chromium.launch({ ...opts, executablePath });
+        } catch {
+          /* fall through to the install hint */
+        }
+      }
       // Single clean line — the export endpoint pipes shim stderr into the 500
       // body, so this is what the user reads. No stack trace.
       console.error(INSTALL_HINT);

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

@@ -53,8 +53,15 @@ const browser = await launchChromium();
 try {
   const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
   const page = await ctx.newPage();
-  await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+  await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
   await page.evaluate(() => document.fonts.ready);
+  // `load` fires before React mounts (and a video comp never reaches
+  // `networkidle`), so gate on the artboard rendering before we query it —
+  // otherwise a multi `.all()` can run against an empty page.
+  await page
+    .locator(selector ?? '[data-dc-screen]')
+    .first()
+    .waitFor({ state: 'visible', timeout: timeoutMs });
   // Reset the world plane's CSS zoom + transform so artboards render at
   // declared dimensions before dom-to-svg walks the layout.
   await page.evaluate(() => {

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

@@ -0,0 +1,452 @@
+// _video-playwright.mjs — DDR-148 deterministic video/animation capture shim.
+//
+// The export counterpart to _png-playwright.mjs. Two capture strategies:
+//
+//   1. WHOLE-COMP RENDER (DDR-148 addendum, audio export) — mp4/webm export of
+//      an artboard with a registered VideoComp goes through
+//      window.__maude_render_video__ (video-comp.tsx bridge → the injected
+//      render-lib's renderMediaOnWeb). Remotion renders video+audio in ONE
+//      pass, owning the TransitionSeries offset math and <Audio volume={fn}>
+//      closures internally — no hand-rolled frame loop, no separate mixing.
+//   2. FRAME-STEP CAPTURE (original DDR-148 spine) — everything else: gif
+//      (no audio, no renderMediaOnWeb container support), ordinary
+//      (non-comp/CSS-WAAPI) artboards, and the fallback when no VideoComp is
+//      registered on the target artboard. Steps the artboard frame-by-frame
+//      via window.__maude_seek__, screenshots each frame, encodes in-page via
+//      mediabunny/gifenc (video-encode-lib.ts). A video-comp is deterministic
+//      BY CONSTRUCTION (Remotion's useCurrentFrame + the seek bridge), so two
+//      capture runs to frame N are pixel-identical.
+//
+// Seek model (path 2 only):
+//   • video-comp artboard → window.__maude_seek__(frame) (Player frame prop).
+//   • ordinary artboard  → time-based: document.getAnimations() currentTime +
+//     every <video>.currentTime, awaiting `seeked`. Selected by --mode.
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { launchChromium } from './_pw-launch.mjs';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, cur, i, all) => {
+    if (cur.startsWith('--')) acc.push([cur.slice(2), all[i + 1] ?? '1']);
+    return acc;
+  }, [])
+);
+
+const {
+  url,
+  artboard, // data-dc-screen id to capture (default: first artboard)
+  selector: selectorArg, // explicit CSS selector (overrides --artboard); from the export target
+  fps: fpsArg,
+  frames: framesArg,
+  'dump-frames': dumpDir,
+  'encode-lib': encodeLib, // path to the bundled in-page frame encoder (mediabunny/gifenc)
+  'render-lib': renderLib, // path to the bundled in-page whole-comp renderer (renderMediaOnWeb)
+  format, // 'mp4' | 'webm' | 'gif' — enables the encode sink (with --out)
+  out, // encoded file destination
+  mode = 'comp', // 'comp' | 'ordinary'
+  audio, // '1' | '0' — include audio in the render-lib path (default on; presence-checked below)
+  'license-key': licenseKeyArg,
+  timeout = '60',
+  scale = '1',
+} = args;
+
+if (!url) {
+  console.error(
+    'usage: _video-playwright.mjs --url <shell-url> [--artboard <id>] [--fps N] [--frames N] --dump-frames <dir>'
+  );
+  process.exit(2);
+}
+
+const timeoutMs = Number(timeout) * 1000;
+const deviceScaleFactor = Math.max(1, Math.min(4, Number(scale) || 1));
+// `--audio` is presence-checked (Object.fromEntries maps a bare flag to '1'), so
+// absence of the flag entirely (not passed) still defaults to audio ON — video.ts
+// always passes an explicit '0'/'1'.
+const wantAudio = audio !== '0';
+const licenseKey = licenseKeyArg || 'free-license';
+
+/** Wait a real turn of the event loop + a frame so a seek settles before shot. */
+const SETTLE_MS = 16;
+
+const browser = await launchChromium();
+try {
+  const ctx = await browser.newContext({
+    viewport: { width: 1440, height: 900 },
+    deviceScaleFactor,
+  });
+  const page = await ctx.newPage();
+  await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
+  await page.evaluate(() => document.fonts.ready);
+
+  // Resolve the target artboard handle. Priority: explicit --selector (from the
+  // export scope Target) → --artboard id → first artboard. `--widen` climbs to
+  // the enclosing [data-dc-screen] (the descendant-selector export case).
+  const widen = args.widen !== undefined;
+  const selector = selectorArg
+    ? selectorArg
+    : artboard
+      ? `[data-dc-screen="${cssEscape(artboard)}"]`
+      : '[data-dc-screen]';
+  const located = page.locator(selector).first();
+  await located.waitFor({ state: 'visible', timeout: timeoutMs });
+  const handle = widen
+    ? await located.evaluateHandle((el) => el.closest('[data-dc-screen]') ?? el)
+    : located;
+
+  // DDR-041 world-plane reset + pin the target artboard to (0,0) — needed by
+  // both capture strategies: the frame-step path screenshots this rect; the
+  // whole-comp path still benefits from a settled, non-panned layout when it
+  // reads the comp's registered width/height (defensive, cheap).
+  await page.evaluate(() => {
+    const world = document.querySelector('.dc-world');
+    if (world) {
+      world.style.zoom = '1';
+      world.style.transform = 'none';
+    }
+  });
+  await handle.evaluate((el) => {
+    const ab = el.closest('[data-dc-screen]') ?? el;
+    ab.style.left = '0px';
+    ab.style.top = '0px';
+  });
+
+  // Resolve the compId of the nearest VideoComp mounted inside the target
+  // artboard (the artboard's `data-dc-screen` id and the comp's own `id` prop
+  // are independent — an author rarely sets the latter — so we resolve by DOM
+  // containment). Null for an ordinary/CSS artboard with no registered comp.
+  const compId = await handle.evaluate(
+    (el) => el.querySelector('[data-comp-id]')?.getAttribute('data-comp-id') ?? null
+  );
+
+  // Whole-comp render path: mp4/webm export of a registered video-comp. GIF has
+  // no renderMediaOnWeb container support (and no audio need); an artboard with
+  // no registered comp (ordinary/CSS) has nothing for renderMediaOnWeb to render
+  // — both fall through to the frame-step path below.
+  const useRenderer = !!renderLib && format !== 'gif' && !!compId;
+
+  if (useRenderer) {
+    const t0 = Date.now();
+    const libSrc = readFileSync(renderLib, 'utf8');
+    await page.addScriptTag({ content: libSrc, type: 'module' });
+    await page.waitForFunction(() => typeof window.__maudeRenderVideo__ === 'function', {
+      timeout: timeoutMs,
+    });
+
+    const explicitFrames = Number(framesArg);
+    const frameRange =
+      Number.isFinite(explicitFrames) && explicitFrames > 0 ? [0, explicitFrames - 1] : null;
+
+    const rendered = await page.evaluate(
+      async ({ compId, container, scale, muted, frameRange, licenseKey }) => {
+        return window.__maude_render_video__(compId, {
+          container,
+          scale,
+          muted,
+          frameRange,
+          licenseKey,
+        });
+      },
+      {
+        compId,
+        container: format,
+        scale: deviceScaleFactor,
+        muted: !wantAudio,
+        frameRange,
+        licenseKey,
+      }
+    );
+
+    writeFileSync(out, Buffer.from(rendered.b64, 'base64'));
+
+    // Comp meta for the summary (diagnostic only — video.ts reads `container`).
+    const compMeta = await page.evaluate(
+      (id) =>
+        (typeof window.__maude_comps__ === 'function' ? window.__maude_comps__() : []).find(
+          (c) => c.id === id
+        ) ?? null,
+      compId
+    );
+    const frameCount = frameRange
+      ? frameRange[1] - frameRange[0] + 1
+      : (compMeta?.durationInFrames ?? 0);
+
+    const result = {
+      fps: compMeta?.fps ?? null,
+      frameCount,
+      width: Math.round((compMeta?.width ?? 0) * deviceScaleFactor),
+      height: Math.round((compMeta?.height ?? 0) * deviceScaleFactor),
+      out,
+      bytes: rendered.bytes,
+      container: rendered.container,
+      codec: rendered.videoCodec,
+      audioCodec: rendered.audioCodec,
+    };
+    const ms = Date.now() - t0;
+    console.error(
+      `✓ rendered ${rendered.container}/${rendered.videoCodec}` +
+        `${rendered.audioCodec ? `+${rendered.audioCodec}` : ' (muted)'} → ${out} (${rendered.bytes} B) in ${ms}ms`
+    );
+    console.log(JSON.stringify(result));
+  } else {
+    await frameStepCapture({
+      page,
+      handle,
+      compId,
+      fpsArg,
+      framesArg,
+      dumpDir,
+      encodeLib,
+      format,
+      out,
+      mode,
+      deviceScaleFactor,
+      timeoutMs,
+    });
+  }
+} finally {
+  await browser.close();
+}
+
+/**
+ * Original DDR-148 frame-step + mediabunny/gifenc capture (gif, ordinary
+ * artboards, and the no-registered-comp fallback). Unchanged behavior from the
+ * pre-addendum shim.
+ */
+async function frameStepCapture({
+  page,
+  handle,
+  compId,
+  fpsArg,
+  framesArg,
+  dumpDir,
+  encodeLib,
+  format,
+  out,
+  mode,
+  deviceScaleFactor,
+  timeoutMs,
+}) {
+  const rect0 = await handle.evaluate((el) => {
+    const r = el.getBoundingClientRect();
+    return { width: r.width, height: r.height };
+  });
+  await page.setViewportSize({
+    width: Math.max(1, Math.ceil(rect0.width)),
+    height: Math.max(1, Math.ceil(rect0.height)),
+  });
+  await handle.evaluate((el) => {
+    el.scrollIntoView({ block: 'start', inline: 'start' });
+    window.scrollTo(0, 0);
+  });
+  const clip = await handle.evaluate((el) => {
+    const r = el.getBoundingClientRect();
+    return {
+      x: Math.max(0, Math.floor(r.left)),
+      y: Math.max(0, Math.floor(r.top)),
+      width: Math.max(1, Math.ceil(r.width)),
+      height: Math.max(1, Math.ceil(r.height)),
+    };
+  });
+
+  // Resolve fps + frame count. Prefer explicit args (the exporter computes them
+  // from comp meta / options); fall back to the registered comp meta in-page —
+  // matched by the RESOLVED compId when the target has one (not just "the
+  // first comp on the page", which mis-hit on multi-comp canvases).
+  const compMeta = await page.evaluate((id) => {
+    try {
+      const comps = typeof window.__maude_comps__ === 'function' ? window.__maude_comps__() : [];
+      if (id) return comps.find((c) => c.id === id) ?? comps[0] ?? null;
+      return comps[0] ?? null;
+    } catch {
+      return null;
+    }
+  }, compId);
+  const fps = Number(fpsArg) || compMeta?.fps || 30;
+  // Cap at 900 frames (30 s @ 30 fps) so a runaway/huge comp can't spawn an
+  // unbounded screenshot loop — matches exporters/video.ts MAX_FRAMES.
+  const frameCount = Math.min(
+    900,
+    Number(framesArg) || compMeta?.durationInFrames || Math.round(fps * 3) // 3 s default
+  );
+  if (!Number.isFinite(fps) || fps <= 0 || !Number.isFinite(frameCount) || frameCount <= 0) {
+    console.error('_video-playwright: could not resolve fps/frameCount (no comp meta, no args)');
+    process.exit(2);
+  }
+
+  // For ordinary artboards, prime the <video> elements (await first seeked).
+  if (mode === 'ordinary') {
+    await page.evaluate(async () => {
+      const vids = Array.from(document.querySelectorAll('video'));
+      await Promise.all(
+        vids.map(
+          (v) =>
+            new Promise((res) => {
+              if (v.readyState >= 2) return res(undefined);
+              v.addEventListener('loadeddata', () => res(undefined), { once: true });
+              // safety timeout
+              setTimeout(() => res(undefined), 2000);
+            })
+        )
+      );
+    });
+  }
+
+  const dump = dumpDir ? (mkdirSync(dumpDir, { recursive: true }), dumpDir) : null;
+  const framePaths = [];
+  const t0 = Date.now();
+
+  // Output resolution = the artboard's CSS clip × deviceScaleFactor. `clip` is in
+  // CSS px, but `page.screenshot` emits deviceScaleFactor× device pixels, so the
+  // encoder canvas must match the SCREENSHOT's real pixel size — otherwise every
+  // 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).
+  const outW = Math.max(2, Math.round((clip.width * deviceScaleFactor) / 2) * 2);
+  const outH = Math.max(2, Math.round((clip.height * deviceScaleFactor) / 2) * 2);
+
+  // Encode sink (Task 6) — inject the in-page mediabunny/gifenc lib and start it.
+  const encoding = !!(encodeLib && format && out);
+  const isGif = format === 'gif';
+  if (encoding) {
+    const libSrc = readFileSync(encodeLib, 'utf8');
+    await page.addScriptTag({ content: libSrc, type: 'module' });
+    await page.waitForFunction(() => typeof window.__maudeEnc === 'object', { timeout: timeoutMs });
+    const started = await page.evaluate(
+      async ({ width, height, fps, isGif, gifColors, fmt }) => {
+        if (isGif) {
+          window.__maudeEnc.startGif({ width, height, fps, maxColors: gifColors });
+          return { container: 'gif', codec: 'gif' };
+        }
+        return window.__maudeEnc.startVideo({ width, height, fps, format: fmt });
+      },
+      {
+        width: outW,
+        height: outH,
+        fps,
+        isGif,
+        gifColors: Number(args.gifColors) || 256,
+        fmt: format,
+      }
+    );
+    console.error(`encoder: ${started.container} / ${started.codec} @ ${outW}×${outH}`);
+  }
+
+  for (let f = 0; f < frameCount; f += 1) {
+    await seekFrame(page, f, fps, mode);
+    await page.waitForTimeout(SETTLE_MS);
+    const shot = await page.screenshot({ clip });
+    if (dump) {
+      const p = join(dump, `frame-${String(f).padStart(5, '0')}.png`);
+      writeFileSync(p, shot);
+      framePaths.push(p);
+    }
+    if (encoding) {
+      const b64 = shot.toString('base64');
+      await page.evaluate(
+        async ({ b64, isGif }) => {
+          if (isGif) return window.__maudeEnc.addGifFrame(b64);
+          return window.__maudeEnc.addVideoFrame(b64);
+        },
+        { b64, isGif }
+      );
+    }
+    if (f % 30 === 0) console.error(`frame ${f + 1}/${frameCount}`);
+  }
+
+  let result = { fps, frameCount, width: outW, height: outH, framePaths };
+  if (encoding) {
+    const enc = await page.evaluate(
+      async ({ isGif }) =>
+        isGif ? window.__maudeEnc.finishGif() : window.__maudeEnc.finishVideo(),
+      { isGif }
+    );
+    writeFileSync(out, Buffer.from(enc.b64, 'base64'));
+    result = { ...result, out, bytes: enc.bytes, container: enc.container, codec: enc.codec };
+    console.error(`✓ encoded ${enc.container}/${enc.codec} → ${out} (${enc.bytes} B)`);
+  }
+
+  const ms = Date.now() - t0;
+  console.error(
+    `✓ captured ${frameCount} frames @ ${fps}fps (${clip.width}×${clip.height}) in ${ms}ms`
+  );
+  // stdout = machine-readable summary for the exporter.
+  console.log(JSON.stringify(result));
+}
+
+/** Seek one frame via the right bridge. Resolves after the frame has painted. */
+async function seekFrame(page, frame, fps, mode) {
+  if (mode === 'ordinary') {
+    await page.evaluate(
+      async ({ frame, fps }) => {
+        const ms = (frame / fps) * 1000;
+        for (const a of document.getAnimations()) {
+          try {
+            a.pause();
+            a.currentTime = ms;
+          } catch {
+            /* unseekable */
+          }
+        }
+        const vids = Array.from(document.querySelectorAll('video'));
+        await Promise.all(
+          vids.map(
+            (v) =>
+              new Promise((res) => {
+                const target = ms / 1000;
+                if (Math.abs(v.currentTime - target) < 1e-3) return res(undefined);
+                v.addEventListener('seeked', () => res(undefined), { once: true });
+                v.currentTime = target;
+                setTimeout(() => res(undefined), 500);
+              })
+          )
+        );
+        await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+      },
+      { frame, fps }
+    );
+    return;
+  }
+  // comp mode — the seek bridge pauses + seeks the Player and resolves post-paint.
+  // 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
+  // is caught. @remotion/media's <Video> decodes to a <canvas> (no <video> tag),
+  // and empirically settles within the same 2-rAF window this wait already ends
+  // 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);
+    }
+    const vids = Array.from(document.querySelectorAll('video'));
+    if (vids.length) {
+      await Promise.all(
+        vids.map(
+          (v) =>
+            new Promise((res) => {
+              if (v.readyState >= 2 && !v.seeking) return res(undefined);
+              let done = false;
+              const finish = () => {
+                if (done) return;
+                done = true;
+                clearInterval(iv);
+                res(undefined);
+              };
+              const iv = setInterval(() => {
+                if (v.readyState >= 2 && !v.seeking) finish();
+              }, 16);
+              v.addEventListener('seeked', finish, { once: true });
+              setTimeout(finish, 1500); // never hang a frame
+            })
+        )
+      );
+      await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+    }
+  }, frame);
+}
+
+/** Minimal CSS.escape for the data-dc-screen attribute selector. */
+function cssEscape(s) {
+  return String(s).replace(/["\\\]]/g, '\\$&');
+}

package/apps/studio/bin/prep.sh

@@ -77,6 +77,7 @@ DEFAULT_DS="project"
 KNOWN_DS=""
 ACCENT_STRATEGY="single"
 COLOR_SPACE="oklch"
+MOODBOARD_VARIANTS="3"
 
 if [ "$CONFIG_PRESENT" = "true" ] && [ "$HAVE_JQ" = "1" ]; then
   NAME=$(jq -r '.name // "Project"' "$CFG")
@@ -91,6 +92,9 @@ if [ "$CONFIG_PRESENT" = "true" ] && [ "$HAVE_JQ" = "1" ]; then
   KNOWN_DS=$(jq -r '.designSystems[]?.name // empty' "$CFG" 2>/dev/null | tr '\n' ' ' | sed 's/ $//')
   ACCENT_STRATEGY=$(jq -r '.accentStrategy // "single"' "$CFG")
   COLOR_SPACE=$(jq -r '.colorSpace // "oklch"' "$CFG")
+  # Type-coerce + clamp in jq: config.json is untrusted input (a poisoned repo
+  # could put a string here) and --shell-export output gets eval'd by callers.
+  MOODBOARD_VARIANTS=$(jq -r '.moodboard.variants // 3 | if type=="number" then floor else 3 end | if . < 1 then 1 elif . > 3 then 3 else . end' "$CFG")
 fi
 
 DR_ABS="$REPO/$DESIGN_ROOT"
@@ -159,6 +163,7 @@ if [ "$MODE" = "shell" ]; then
   printf 'export KNOWN_DS=%q\n'          "$KNOWN_DS"
   printf 'export ACCENT_STRATEGY=%q\n'   "$ACCENT_STRATEGY"
   printf 'export COLOR_SPACE=%q\n'       "$COLOR_SPACE"
+  printf 'export MOODBOARD_VARIANTS=%q\n' "$MOODBOARD_VARIANTS"
   printf 'export DEPS_OK=%s\n'           "$DEPS_OK"
   printf 'export DEPS_MISSING=%q\n'      "$DEPS_MISSING"
   printf 'export SERVER_UP=%s\n'         "$SERVER_UP"
@@ -181,6 +186,7 @@ if [ "$HAVE_JQ" = "1" ]; then
     --arg tok "$TOKENS_REL" --arg ncd "$NEW_CANVAS_DIR" --arg ncm "$NEW_COMPONENT_DIR" \
     --arg acc "$TEAM_ACCENT" --arg dds "$DEFAULT_DS" --arg kds "$KNOWN_DS" \
     --arg astrat "$ACCENT_STRATEGY" --arg cspace "$COLOR_SPACE" \
+    --arg mbvar "$MOODBOARD_VARIANTS" \
     --arg depsok "$DEPS_OK" --arg depsmiss "$DEPS_MISSING" \
     --arg sup "$SERVER_UP" --arg sport "$SERVER_PORT" \
     --arg act "$ACTIVE_CANVAS" --arg selfile "$SELECTED_FILE" \
@@ -194,7 +200,8 @@ if [ "$HAVE_JQ" = "1" ]; then
         tokens_rel: $tok, new_canvas_dir: $ncd, new_component_dir: $ncm,
         team_accent: $acc, default_ds: $dds,
         known_ds: ($kds | if . == "" then [] else split(" ") end),
-        accent_strategy: $astrat, color_space: $cspace
+        accent_strategy: $astrat, color_space: $cspace,
+        moodboard_variants: ($mbvar | tonumber? // 3)
       },
       active: {
         canvas: $act, selected: $sel, selected_file: $selfile,