@1agh/maude 0.41.0 → 0.43.0

package/apps/studio/bin/_probe-footage-playwright.mjs

@@ -0,0 +1,269 @@
+// _probe-footage-playwright.mjs — keyframe extraction for the footage director
+// (feature-footage-analysis-director, Task 4). The READ counterpart to
+// _ingest-footage.mjs: given ONE content-addressed clip, decode it in headless
+// Chromium and dump N evenly-spaced keyframe PNGs the `footage-analyst` agent
+// then WATCHES (vision) to characterize the clip.
+//
+// WHY A BROWSER, NOT ffmpeg: DDR-148's posture is "no native renderer binaries".
+// Chromium already decodes video (it's the capture spine's engine). We don't even
+// need Remotion here — a plain HTML5 <video>, seeked frame-by-frame and
+// screenshotted, is the whole mechanism. No dev server is required either: the
+// page is navigated as file:// and the clip is a file:// subresource (same
+// scheme; `--allow-file-access-from-files` permits the load), so probing works
+// offline / pre-server, unlike the export capture (which drives the live Player).
+//
+// Determinism note (DDR-094 — freeze-frames lie): the frames are evenly spaced
+// midpoints across the clip, so a downstream reader gets genuine motion samples,
+// not one repeated frame.
+//
+// OUTPUT: keyframe PNGs are THROWAWAY SCRATCH → written under --out-dir (a /tmp
+// scratch path, DDR-115: capture scratch never gets a new `_*` dir, never lands
+// in the VERSIONED assets/). stdout = a JSON manifest
+//   { asset, durationSec, width, height, frames:[{index,t,png}] }
+//
+// Reached via `maude design probe-footage`, never a raw path.
+// Exit: 0 ok · 2 usage · 3 no browser (via _pw-launch) · 4 decode/probe error · 1 other.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { launchChromium } from './_pw-launch.mjs';
+
+const DEFAULT_FRAMES = 12;
+// Cap the longest side of a keyframe PNG — vision only needs legible frames, and
+// small PNGs keep the analyst's context lean. 960px is ample.
+const MAX_FRAME_EDGE = 960;
+
+function parseArgv(argv) {
+  const out = {
+    asset: null,
+    root: null,
+    designRoot: '.design',
+    frames: DEFAULT_FRAMES,
+    outDir: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    switch (a) {
+      case '--asset':
+        out.asset = argv[++i];
+        break;
+      case '--root':
+        out.root = argv[++i];
+        break;
+      case '--design-root':
+        out.designRoot = argv[++i];
+        break;
+      case '--frames':
+        out.frames = Number(argv[++i]);
+        break;
+      case '--out-dir':
+        out.outDir = argv[++i];
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      default:
+        if (a.startsWith('-')) throw usage(`unknown flag ${a}`);
+        if (out.asset === null) out.asset = a;
+        else throw usage(`unexpected extra arg ${a}`);
+    }
+  }
+  return out;
+}
+
+function usage(msg) {
+  const e = new Error(msg);
+  e.code = 2;
+  return e;
+}
+function probeError(msg) {
+  const e = new Error(msg);
+  e.code = 4;
+  return e;
+}
+
+const HELP = `probe-footage — extract keyframe PNGs from one clip for vision analysis
+(reached via \`maude design probe-footage\`)
+
+Usage:
+  maude design probe-footage <assets/<sha8>.<ext>> --root <repo>
+                             [--design-root .design] [--frames N] [--out-dir DIR]
+
+Decodes the clip in headless Chromium, seeks to N evenly-spaced frames, writes a
+PNG per frame to --out-dir (a /tmp scratch dir — NOT assets/), and prints a JSON
+manifest { asset, durationSec, width, height, frames }.
+
+Exit: 0 ok · 2 usage · 3 no browser · 4 decode/probe error · 1 other.`;
+
+/** Resolve the clip to an absolute path inside <designRoot>/assets and assert containment. */
+function resolveAsset(root, designRootRel, asset) {
+  const rel = String(asset).replace(/^\/+/, ''); // tolerate a leading slash
+  if (isAbsolute(rel) || rel.includes('..'))
+    throw usage(`asset must be a relative assets/ path: ${asset}`);
+  const assetsDir = resolve(root, designRootRel, 'assets');
+  // Accept both `assets/<name>` and a bare `<name>`.
+  const name = rel.startsWith('assets/') ? rel.slice('assets/'.length) : rel;
+  if (!/^[a-z0-9]{8}\.[a-z0-9]{2,4}$/.test(name))
+    throw usage(`asset name must be content-addressed <sha8>.<ext>: ${name}`);
+  const abs = resolve(assetsDir, name);
+  if (abs !== join(assetsDir, name) || !abs.startsWith(assetsDir + sep))
+    throw usage(`asset path escapes assets dir: ${abs}`);
+  return { abs, name, rel: `assets/${name}` };
+}
+
+async function probe({ asset, root, designRootRel, frames, outDir }) {
+  const { abs, name, rel } = resolveAsset(root, designRootRel, asset);
+  const nFrames = Number.isInteger(frames) && frames > 0 ? Math.min(frames, 64) : DEFAULT_FRAMES;
+  const dir =
+    outDir || join(process.env.TMPDIR || '/tmp', `maude-footage-${name.replace(/\./g, '_')}`);
+  mkdirSync(dir, { recursive: true });
+
+  const browser = await launchChromium({
+    headless: true,
+    // file:// page loading a file:// video subresource needs this flag.
+    args: ['--allow-file-access-from-files', '--autoplay-policy=no-user-gesture-required'],
+  });
+  try {
+    const page = await browser.newPage();
+    // A real file:// host page (NOT about:blank — its opaque origin can't load a
+    // file:// subresource even with --allow-file-access-from-files). With a
+    // file:// page + the flag, the clip loads as a same-scheme cross-dir resource.
+    const hostHtml = join(dir, '_probe.html');
+    writeFileSync(hostHtml, '<!doctype html><meta charset="utf-8"><body style="margin:0"></body>');
+    await page.goto(pathToFileURL(hostHtml).href);
+
+    // Load metadata: duration + intrinsic dimensions.
+    const fileUrl = pathToFileURL(abs).href;
+    const meta = await page.evaluate(async (url) => {
+      const v = document.createElement('video');
+      v.id = 'probe-v';
+      v.muted = true;
+      v.playsInline = true;
+      v.preload = 'auto';
+      v.style.position = 'fixed';
+      v.style.left = '0';
+      v.style.top = '0';
+      v.style.margin = '0';
+      document.body.style.margin = '0';
+      document.body.appendChild(v);
+      const done = new Promise((res, rej) => {
+        v.addEventListener('loadedmetadata', () => res(true), { once: true });
+        v.addEventListener('error', () => rej(new Error('video error while loading metadata')), {
+          once: true,
+        });
+        setTimeout(() => rej(new Error('timed out loading metadata (15s)')), 15000);
+      });
+      v.src = url;
+      await done;
+      return { duration: v.duration, width: v.videoWidth, height: v.videoHeight };
+    }, fileUrl);
+
+    if (!Number.isFinite(meta.duration) || meta.duration <= 0 || !meta.width || !meta.height) {
+      throw probeError(
+        `clip has no seekable video track (duration=${meta.duration}, ${meta.width}x${meta.height})`
+      );
+    }
+
+    // Size the <video> element to its intrinsic size, capped, and set the viewport
+    // to match so an element screenshot captures the whole frame at 1:1-ish.
+    const scale = Math.min(1, MAX_FRAME_EDGE / Math.max(meta.width, meta.height));
+    const drawW = Math.max(1, Math.round(meta.width * scale));
+    const drawH = Math.max(1, Math.round(meta.height * scale));
+    await page.setViewportSize({ width: drawW, height: drawH });
+    await page.evaluate(
+      ({ w, h }) => {
+        const v = document.getElementById('probe-v');
+        v.style.width = `${w}px`;
+        v.style.height = `${h}px`;
+        // Expose a promise-returning seek helper for the frame loop.
+        window.__seekTo = (t) =>
+          new Promise((res, rej) => {
+            const onSeeked = () => {
+              v.removeEventListener('seeked', onSeeked);
+              res(true);
+            };
+            v.addEventListener('seeked', onSeeked);
+            setTimeout(() => {
+              v.removeEventListener('seeked', onSeeked);
+              rej(new Error(`seek to ${t}s timed out`));
+            }, 8000);
+            v.currentTime = t;
+          });
+      },
+      { w: drawW, h: drawH }
+    );
+
+    const video = page.locator('#probe-v');
+    const outFrames = [];
+    for (let i = 0; i < nFrames; i += 1) {
+      // Even midpoints across (0, duration) — avoids the exact-0 / exact-end
+      // frames some codecs won't decode cleanly.
+      const t = (meta.duration * (i + 0.5)) / nFrames;
+      try {
+        await page.evaluate((tt) => window.__seekTo(tt), t);
+      } catch (e) {
+        // A single flaky seek shouldn't abort the whole probe — skip this frame.
+        outFrames.push({
+          index: i,
+          t: Number(t.toFixed(3)),
+          png: null,
+          error: String(e?.message ?? e),
+        });
+        continue;
+      }
+      const png = join(dir, `frame-${String(i).padStart(2, '0')}.png`);
+      await video.screenshot({ path: png });
+      outFrames.push({ index: i, t: Number(t.toFixed(3)), png });
+    }
+
+    return {
+      asset: rel,
+      durationSec: Number(meta.duration.toFixed(3)),
+      width: meta.width,
+      height: meta.height,
+      outDir: dir,
+      frames: outFrames,
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgv(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`probe-footage: ${err.message}\n`);
+    process.exit(err.code ?? 2);
+  }
+  if (opts.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  if (!opts.asset) {
+    process.stderr.write('probe-footage: <assets/<sha8>.<ext>> required\n');
+    process.exit(2);
+  }
+  const root = opts.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    const r = await probe({
+      asset: opts.asset,
+      root,
+      designRootRel: opts.designRoot,
+      frames: opts.frames,
+      outDir: opts.outDir,
+    });
+    process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  } catch (err) {
+    process.stderr.write(`probe-footage: ${err.message}\n`);
+    process.exit(err.code ?? 1);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

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

@@ -5,7 +5,7 @@
 //
 // Invocation (called by screenshot.sh — not directly by users):
 //   npm exec --package=playwright -- node _screenshot-playwright.mjs \
-//     --url <url> [--selector <css>] --out <path> [--timeout 8]
+//     --url <url> [--selector <css>] --out <path> [--timeout 8] [--theme <name>]
 //
 // First invocation may install chromium (~150 MB). Subsequent runs reuse cache.
 
@@ -20,7 +20,7 @@ const args = Object.fromEntries(
   }, [])
 );
 
-const { url, selector, out, timeout = '8' } = args;
+const { url, selector, out, timeout = '8', theme } = args;
 if (!url || !out) {
   console.error(
     'usage: _screenshot-playwright.mjs --url <url> [--selector <css>] --out <path> [--timeout 8]'
@@ -37,6 +37,21 @@ try {
   const page = await ctx.newPage();
   await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
 
+  if (theme) {
+    // Dual-theme reality check (/design:new step 9): force every DS artboard
+    // theme wrapper to `theme` before capture, deterministically, instead of
+    // relying on whatever the canvas is pinned to. No-op if the canvas has no
+    // `[data-theme]` elements (e.g. a single-theme DS).
+    const n = await page.evaluate((t) => {
+      const els = document.querySelectorAll('[data-theme]');
+      els.forEach((el) => {
+        el.setAttribute('data-theme', t);
+      });
+      return els.length;
+    }, theme);
+    console.error(`→ theme override: forced data-theme="${theme}" on ${n} element(s)`);
+  }
+
   if (selector) {
     const loc = page.locator(selector).first();
     await loc.waitFor({ state: 'visible', timeout: timeoutMs });

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

@@ -70,10 +70,6 @@ try {
       world.style.zoom = '1';
       world.style.transform = 'none';
     }
-    for (const el of document.querySelectorAll('[data-dc-screen]')) {
-      el.style.left = '0px';
-      el.style.top = '0px';
-    }
   });
   // Inject dom-to-svg into the page. Bundle attaches its exports under
   // `window.domToSvg`.
@@ -81,6 +77,27 @@ try {
 
   const written = [];
 
+  // Pin one artboard to (0,0) for its capture, returning a restore function.
+  // Per-target rather than a one-shot reset of every `[data-dc-screen]` — a
+  // multi-target loop must not leave an already-captured artboard sitting at
+  // the origin, overlapping the next target's geometry (the scatter bug).
+  const pinArtboard = async (handle) => {
+    const saved = await handle.evaluate((el) => {
+      const ab = el.closest('[data-dc-screen]') ?? el;
+      const prev = { left: ab.style.left, top: ab.style.top };
+      ab.style.left = '0px';
+      ab.style.top = '0px';
+      return prev;
+    });
+    return async () => {
+      await handle.evaluate((el, prev) => {
+        const ab = el.closest('[data-dc-screen]') ?? el;
+        ab.style.left = prev.left;
+        ab.style.top = prev.top;
+      }, saved);
+    };
+  };
+
   // Single in-page serializer used by BOTH branches (single + multi) so they
   // can't drift again (the `formatXML` 500 bug came from a divergent copy).
   // Note: dom-to-svg exports only elementToSVG / inlineResources /
@@ -228,11 +245,14 @@ try {
     for (let i = 0; i < screens.length; i += 1) {
       const handle = screens[i];
       const id = (await handle.getAttribute('data-dc-screen')) ?? `artboard-${i + 1}`;
+      const restore = await pinArtboard(handle);
       // Each multi handle is already a `[data-dc-screen]` artboard — no widen.
       const svg = await serializeOne(handle, false);
+      await restore();
       const target = join(outDir, `${id}.svg`);
       writeFileSync(target, svg, 'utf8');
       written.push(target);
+      console.log(`MAUDE_PROGRESS {"current":${i + 1},"total":${screens.length}}`);
     }
   } else {
     if (!out) {
@@ -242,7 +262,9 @@ try {
     mkdirSync(dirname(out), { recursive: true });
     const handle = page.locator(selector ?? '[data-dc-screen]:first-of-type').first();
     await handle.waitFor({ state: 'visible', timeout: timeoutMs });
+    const restore = await pinArtboard(handle);
     const svg = await serializeOne(handle, widen);
+    await restore();
     writeFileSync(out, svg, 'utf8');
     written.push(out);
   }

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

@@ -126,84 +126,132 @@ try {
   // — both fall through to the frame-step path below.
   const useRenderer = !!renderLib && format !== 'gif' && !!compId;
 
+  // When the whole-comp renderer path throws we DON'T fail the export. The most
+  // common cause is a `RangeError: Maximum call stack size exceeded` from
+  // @remotion/web-renderer's guardless recursive DOM precompositing on a
+  // deeply-nested comp (RCA issue-video-mp4-rendermediaonweb-stack-overflow):
+  // one native recursion level per nested opacity/transform/filter/mask layer,
+  // no depth cap. Instead we degrade to the frame-step screenshot + mediabunny
+  // path below, which goes through Chromium's native compositor and is immune to
+  // that recursion. The one cost is audio — the frame-step path is video-only —
+  // so a comp that overflows the audio renderer still exports, just muted. That
+  // beats a hard failure with no file. `video.ts` always passes --encode-lib
+  // (only --render-lib is conditional), so the fallback has all it needs here.
+  let renderFallbackReason = null;
+
   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,
-    });
+    try {
+      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 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,
+      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,
-        });
-      },
-      {
-        compId,
-        container: format,
-        scale: deviceScaleFactor,
-        muted: !wantAudio,
-        frameRange,
-        licenseKey,
-      }
-    );
+        }
+      );
 
-    writeFileSync(out, Buffer.from(rendered.b64, 'base64'));
+      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,
-    });
+      // 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));
+    } catch (err) {
+      // Collapse newlines — the message carries an in-page (untrusted canvas,
+      // DDR-054) error + stack, and it flows to console.error / the job's
+      // persisted error, so a forged "\n[FATAL] …" line can't be injected into
+      // the dev-server's stderr or the history ledger.
+      renderFallbackReason = oneLine(err instanceof Error ? err.message : String(err));
+      console.error(
+        `⚠ renderMediaOnWeb failed (${renderFallbackReason}); falling back to ` +
+          'frame-step screenshot capture — video will export WITHOUT audio'
+      );
+    }
+  }
+
+  // Frame-step path: the normal route for gif / ordinary / comp-less artboards
+  // (useRenderer === false), AND the graceful-degradation fallback when the
+  // renderer above threw (renderFallbackReason !== null).
+  if (!useRenderer || renderFallbackReason !== null) {
+    try {
+      await frameStepCapture({
+        page,
+        handle,
+        compId,
+        fpsArg,
+        framesArg,
+        dumpDir,
+        encodeLib,
+        format,
+        out,
+        mode,
+        deviceScaleFactor,
+        timeoutMs,
+        fallbackReason: renderFallbackReason,
+      });
+    } catch (fallbackErr) {
+      // If we only reached the frame-step path because the renderer already
+      // failed, surface BOTH failures so a genuine bug isn't hidden behind the
+      // fallback's own error.
+      if (renderFallbackReason !== null) {
+        const fb = oneLine(
+          fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)
+        );
+        throw new Error(
+          `video export failed on both paths — renderMediaOnWeb: ${renderFallbackReason}; ` +
+            `frame-step fallback: ${fb}`,
+          { cause: fallbackErr }
+        );
+      }
+      throw fallbackErr;
+    }
   }
 } finally {
   await browser.close();
@@ -227,6 +275,10 @@ async function frameStepCapture({
   mode,
   deviceScaleFactor,
   timeoutMs,
+  // 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.
+  fallbackReason = null,
 }) {
   const rect0 = await handle.evaluate((el) => {
     const r = el.getBoundingClientRect();
@@ -352,10 +404,22 @@ async function frameStepCapture({
         { b64, isGif }
       );
     }
+    // Machine-readable progress (stdout) — spawnShim parses `MAUDE_PROGRESS`
+    // lines → onProgress → job.progress → the live bar in the Exports panel, so
+    // a long frame-step render (the renderMediaOnWeb-overflow fallback) shows
+    // "N of M" instead of a static "Exporting…". Filtered out of the summary
+    // stdout the exporter reads. Human log stays throttled on stderr.
+    console.log(`MAUDE_PROGRESS {"current":${f + 1},"total":${frameCount}}`);
     if (f % 30 === 0) console.error(`frame ${f + 1}/${frameCount}`);
   }
 
   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
+  // degraded and audio was dropped (RCA issue-video-mp4-rendermediaonweb-stack-overflow).
+  if (fallbackReason !== null) {
+    result = { ...result, degraded: true, audioDropped: true, fallbackReason };
+  }
   if (encoding) {
     const enc = await page.evaluate(
       async ({ isGif }) =>
@@ -450,3 +514,9 @@ async function seekFrame(page, frame, fps, mode) {
 function cssEscape(s) {
   return String(s).replace(/["\\\]]/g, '\\$&');
 }
+
+/** Collapse CR/LF runs to a single space — used to neutralize log/ledger
+ *  injection from untrusted in-page (canvas-origin, DDR-054) error text. */
+function oneLine(s) {
+  return String(s).replace(/[\r\n]+/g, ' ');
+}

package/apps/studio/bin/ingest-footage.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# ingest-footage.sh — thin shim over _ingest-footage.mjs; reached via
+# `maude design ingest-footage` (DDR-062), never a raw bin path. See
+# _ingest-footage.mjs for the full rationale (feature-footage-analysis-director).
+#
+# Usage:
+#   ingest-footage.sh <dir> --root <repo> [--design-root .design]
+#                     [--recursive] [--max-bytes N]
+#
+# stdout on success = a JSON manifest { clips, skipped, assetsDir }.
+# Exit: 0 ok (even with skips) · 2 usage · 6 write/containment error · 1 other.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,14p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+# Prefer node (always present with a maude install); fall back to bun in a dev
+# tree that has bun but a shimmed node. The module is pure Node ESM — no .ts.
+if command -v node >/dev/null 2>&1; then
+  exec node "$SCRIPT_DIR/_ingest-footage.mjs" "$@"
+elif command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT_DIR/_ingest-footage.mjs" "$@"
+else
+  echo "ingest-footage.sh: node or bun is required." >&2
+  exit 1
+fi