@1agh/maude 0.42.0 → 0.43.0

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

package/apps/studio/bin/photo-adjust.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# photo-adjust.sh — feature-photo-editor (Stage G, Task 19). Headless PARAMETRIC
+# photo edit: assemble a PhotoEdit from flags and PUT it to the running dev
+# server's /_api/photo-edit route so an agent (or a human) can tune a photo
+# without opening a browser or clicking a slider.
+#
+# Deliberately the THIN, NON-BROWSER sibling of photo-bg-remove.sh. Background
+# removal needs a browser round-trip because @imgly runs the ML model client-
+# side; parametric edits are pure JSON, so a direct curl to the already-validated
+# route (the photo-store cap stack — validatePhotoEdit + sha8 + containment +
+# size cap — is the gate) is the whole job. DO NOT "fix" this asymmetry by making
+# this verb heavier: there is no inference step here, so a harness canvas +
+# agent-browser would be pure overhead.
+#
+# Reached via `maude design photo-adjust` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   photo-adjust.sh --asset <assets/<sha8>.<ext> | <sha8>> [--root <repo>]
+#     [--brightness N] [--contrast N] [--saturation N] [--exposure N]
+#     [--hue N] [--sepia N] [--grayscale N] [--invert N]
+#     [--duotone "#aabbcc,#ddeeff[,intensity]"]
+#     [--grain "amount[,size]"]
+#     [--pattern "type[,scale,opacity,blend]"]
+#     [--mask "preset[,strength]"]
+#     [--replace]   (overwrite the sidecar instead of merging onto it)
+#     [--reset]     (clear the sidecar to neutral / unedited)
+#
+# Adjustment ranges (normalized, 0 = neutral): brightness/contrast/saturation/
+# exposure ∈ −1..1, hue ∈ −180..180 (deg), sepia/grayscale/invert ∈ 0..1.
+# Merges onto the existing sidecar by default (successive calls accumulate).
+#
+# Requires a running dev server (caller runs `maude design server-up` first);
+# reads the port from <designRoot>/_server.json.
+#
+# Stdout (last line): the sidecar path `assets/<sha8>.photo.json` (for $(...)).
+# Stderr: progress / diagnostics.
+# Exit:   0 ok / 1 server or asset problem / 2 bad args / 3 server rejected edit.
+
+set -euo pipefail
+
+ASSET="" REPO="" REPLACE=0 RESET=0
+BRIGHTNESS="" CONTRAST="" SATURATION="" EXPOSURE="" HUE="" SEPIA="" GRAYSCALE="" INVERT=""
+DUOTONE="" GRAIN="" PATTERN="" MASK=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --asset)      ASSET="$2"; shift 2 ;;
+    --root)       REPO="$2"; shift 2 ;;
+    --brightness) BRIGHTNESS="$2"; shift 2 ;;
+    --contrast)   CONTRAST="$2"; shift 2 ;;
+    --saturation) SATURATION="$2"; shift 2 ;;
+    --exposure)   EXPOSURE="$2"; shift 2 ;;
+    --hue)        HUE="$2"; shift 2 ;;
+    --sepia)      SEPIA="$2"; shift 2 ;;
+    --grayscale)  GRAYSCALE="$2"; shift 2 ;;
+    --invert)     INVERT="$2"; shift 2 ;;
+    --duotone)    DUOTONE="$2"; shift 2 ;;
+    --grain)      GRAIN="$2"; shift 2 ;;
+    --pattern)    PATTERN="$2"; shift 2 ;;
+    --mask)       MASK="$2"; shift 2 ;;
+    --replace)    REPLACE=1; shift ;;
+    --reset)      RESET=1; shift ;;
+    --help|-h)    sed -n '2,39p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "photo-adjust.sh: unknown arg '$1'" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$ASSET" ] || { echo "photo-adjust.sh: --asset is required" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "photo-adjust.sh: jq is required" >&2; exit 1; }
+
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+DESIGN_ROOT="$REPO/.design"
+[ -d "$DESIGN_ROOT" ] || { echo "photo-adjust.sh: no .design/ under $REPO" >&2; exit 1; }
+
+STATE="$DESIGN_ROOT/_server.json"
+[ -f "$STATE" ] || { echo "photo-adjust.sh: no _server.json (start the dev server first)" >&2; exit 1; }
+PORT=$(jq -r '.port // empty' "$STATE" 2>/dev/null)
+[ -n "$PORT" ] || { echo "photo-adjust.sh: could not read port from $STATE" >&2; exit 1; }
+
+BASE_URL="http://127.0.0.1:$PORT/_api/photo-edit"
+# URL-encode the asset param minimally (slashes are safe as a query value here).
+ENC_ASSET=$(printf '%s' "$ASSET" | jq -sRr @uri)
+URL="$BASE_URL?asset=$ENC_ASSET"
+
+# --reset short-circuits: write a neutral sidecar.
+if [ "$RESET" -eq 1 ]; then
+  RESP=$(curl -s -X PUT -H 'Content-Type: application/json' -d '{}' "$URL")
+  OK=$(printf '%s' "$RESP" | jq -r '.ok // false' 2>/dev/null || echo false)
+  [ "$OK" = "true" ] || { echo "photo-adjust.sh: reset rejected: $RESP" >&2; exit 3; }
+  printf '%s\n' "$(printf '%s' "$RESP" | jq -r '.path')"
+  exit 0
+fi
+
+# Assemble the patch from set flags (unset flags are omitted entirely).
+PATCH=$(jq -n \
+  --arg brightness "$BRIGHTNESS" --arg contrast "$CONTRAST" --arg saturation "$SATURATION" \
+  --arg exposure "$EXPOSURE" --arg hue "$HUE" --arg sepia "$SEPIA" \
+  --arg grayscale "$GRAYSCALE" --arg invert "$INVERT" \
+  --arg duotone "$DUOTONE" --arg grain "$GRAIN" --arg pattern "$PATTERN" --arg mask "$MASK" '
+  def n($s): if $s == "" then null else ($s | tonumber) end;
+  def adj:
+    { brightness: n($brightness), contrast: n($contrast), saturation: n($saturation),
+      exposure: n($exposure), hue: n($hue), sepia: n($sepia),
+      grayscale: n($grayscale), invert: n($invert) }
+    | with_entries(select(.value != null));
+  def duo:
+    if $duotone == "" then null
+    else ($duotone | split(",")) as $p
+      | { enabled: true, colorA: $p[0], colorB: $p[1] }
+        + (if ($p | length) > 2 then { intensity: ($p[2] | tonumber) } else {} end)
+    end;
+  def gr:
+    if $grain == "" then null
+    else ($grain | split(",")) as $p
+      | { enabled: true, amount: ($p[0] | tonumber) }
+        + (if ($p | length) > 1 then { size: ($p[1] | tonumber) } else {} end)
+    end;
+  def pat:
+    if $pattern == "" then null
+    else ($pattern | split(",")) as $p
+      | { enabled: true, type: $p[0] }
+        + (if ($p | length) > 1 then { scale: ($p[1] | tonumber) } else {} end)
+        + (if ($p | length) > 2 then { opacity: ($p[2] | tonumber) } else {} end)
+        + (if ($p | length) > 3 then { blend: $p[3] } else {} end)
+    end;
+  def msk:
+    if $mask == "" then null
+    else ($mask | split(",")) as $p
+      | { preset: $p[0] }
+        + (if ($p | length) > 1 then { strength: ($p[1] | tonumber) } else {} end)
+    end;
+  ({}
+    + (adj as $a | if ($a | length) > 0 then { adjustments: $a } else {} end)
+    + (duo as $d | if $d then { duotone: $d } else {} end)
+    + (gr  as $g | if $g then { grain: $g } else {} end)
+    + (pat as $p | if $p then { pattern: $p } else {} end)
+    + (msk as $m | if $m then { mask: $m } else {} end))
+')
+
+if [ "$(printf '%s' "$PATCH" | jq -r 'keys | length')" = "0" ]; then
+  echo "photo-adjust.sh: no edit flags given (nothing to do)" >&2
+  exit 2
+fi
+
+if [ "$REPLACE" -eq 1 ]; then
+  BODY="$PATCH"
+else
+  # Merge onto the current sidecar (deep object merge via jq's `*`), dropping the
+  # server-stamped `version` (it's re-stamped on write).
+  BASE=$(curl -s "$URL" 2>/dev/null || echo '{}')
+  printf '%s' "$BASE" | jq -e . >/dev/null 2>&1 || BASE='{}'
+  BODY=$(jq -n --argjson base "$BASE" --argjson patch "$PATCH" '($base | del(.version)) * $patch')
+fi
+
+RESP=$(curl -s -X PUT -H 'Content-Type: application/json' -d "$BODY" "$URL")
+OK=$(printf '%s' "$RESP" | jq -r '.ok // false' 2>/dev/null || echo false)
+if [ "$OK" != "true" ]; then
+  echo "photo-adjust.sh: server rejected the edit: $RESP" >&2
+  exit 3
+fi
+printf '%s\n' "$(printf '%s' "$RESP" | jq -r '.path')"

package/apps/studio/bin/photo-bg-remove.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# photo-bg-remove.sh — feature-photo-editor (Stage G, Task 18). Headless
+# background removal: mirrors draw-proof.sh's structure (throwaway harness
+# canvas + agent-browser drive) but the "proof" here isn't a screenshot ladder
+# — it's the client-side @imgly ML pass actually running and reporting back
+# through DOM attributes agent-browser polls, since there's no other channel
+# to cross the process boundary out of a headless browser.
+#
+# Design note (the decision this task was originally deferred on): the harness
+# canvas runs inside the split-origin (DDR-054) canvas iframe, but BOTH
+# `/_api/asset` and `/_api/photo-edit` are already canvas-safe routes (see
+# their CANVAS_SAFE_API comments in http.ts) — so the harness component
+# (`PhotoBgRemoveHarness`, canvas-lib.tsx) posts the matte and the updated
+# PhotoEdit sidecar directly from the canvas origin. No cross-origin relay,
+# no base64-through-a-DOM-attribute round-trip needed.
+#
+# Reached via `maude design photo-bg-remove` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   photo-bg-remove.sh --asset <assets/<sha8>.<ext>> [--root <repo>]
+#                       [--slug <name>] [--timeout <secs>]
+#
+# Requires a running dev server (caller runs `maude design server-up` first);
+# reads the port from <designRoot>/_server.json. Requires agent-browser (the
+# ML pass needs a real WASM/WebGPU-capable browser driving real DOM state —
+# there is no non-browser path, unlike photo-adjust.sh's plain curl).
+#
+# Stdout (last line): the new matte asset path `assets/<sha8>.png` (for $(...)).
+# Stderr: progress / diagnostics.
+# Exit:   0 success / 1 missing input, server, or agent-browser / 2 bad args
+#         / 3 drive/navigation failed / 4 the harness itself reported an error
+#         / 5 timed out waiting for the ML pass to finish.
+
+set -uo pipefail
+
+ASSET="" SLUG="" REPO="" TIMEOUT=150
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --asset)   ASSET="$2"; shift 2 ;;
+    --slug)    SLUG="$2"; shift 2 ;;
+    --root)    REPO="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --help|-h)
+      sed -n '2,29p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "photo-bg-remove.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+[ -n "$ASSET" ] || { echo "photo-bg-remove.sh: --asset <assets/<sha8>.<ext>> required" >&2; exit 2; }
+# Strip a leading designRoot-relative slash/prefix if the caller passed one.
+ASSET="${ASSET#/}"
+case "$ASSET" in
+  assets/*) : ;;
+  *) echo "photo-bg-remove.sh: --asset must look like assets/<sha8>.<ext>, got '$ASSET'" >&2; exit 2 ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+[ -n "$SLUG" ] || SLUG=$(basename "$ASSET" | sed -E 's/\.[^.]+$//')
+SLUG=$(bash "$SCRIPT_DIR/slug.sh" "$SLUG" 2>/dev/null || printf '%s' "$SLUG" | tr '[:upper:]' '[:lower:]')
+
+# ---------- resolve repo + design root + port ----------
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+DESIGN_ROOT="$REPO/.design"
+[ -d "$DESIGN_ROOT" ] || { echo "photo-bg-remove.sh: no .design/ under $REPO" >&2; exit 1; }
+[ -f "$DESIGN_ROOT/$ASSET" ] || { echo "photo-bg-remove.sh: asset not found: $DESIGN_ROOT/$ASSET" >&2; exit 1; }
+
+STATE="$DESIGN_ROOT/_server.json"
+[ -f "$STATE" ] || { echo "photo-bg-remove.sh: $STATE missing — run \`maude design server-up\` first" >&2; exit 1; }
+if command -v jq >/dev/null 2>&1; then
+  PORT=$(jq -r .port "$STATE" 2>/dev/null)
+else
+  PORT=$(sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" | head -n1)
+fi
+[ -n "$PORT" ] || { echo "photo-bg-remove.sh: no port in $STATE" >&2; exit 1; }
+
+# ---------- resolve agent-browser (hard dependency — see header) ----------
+# Mirrors screenshot.sh's MAUDE_AGENT_BROWSER override (DDR-144 attacker-F4 — an
+# explicit single-binary pointer, never a PATH prepend a same-user attacker
+# could shadow) and its ensure-browser.sh chrome resolution.
+AB="${MAUDE_AGENT_BROWSER:-agent-browser}"
+command -v "$AB" >/dev/null 2>&1 || {
+  echo "photo-bg-remove.sh: agent-browser not found (required — the ML pass needs a real WASM/WebGPU browser, there is no non-browser fallback here)" >&2
+  exit 1
+}
+if [ -z "${AGENT_BROWSER_EXECUTABLE_PATH:-}" ]; then
+  ES_FLAGS="--quiet"
+  [ -z "${MAUDE_DEV_SERVER_ROOT:-}" ] && ES_FLAGS="--quiet --no-download"
+  BROWSER_PATH="$(bash "$SCRIPT_DIR/ensure-browser.sh" $ES_FLAGS 2>/dev/null)"
+  [ -n "$BROWSER_PATH" ] && export AGENT_BROWSER_EXECUTABLE_PATH="$BROWSER_PATH"
+fi
+
+# ---------- generate the harness canvas ----------
+PHOTO_DIR="$DESIGN_ROOT/_photo"
+mkdir -p "$PHOTO_DIR"
+HARNESS_TSX="$PHOTO_DIR/$SLUG.bgremove.tsx"
+{
+  echo "import { PhotoBgRemoveHarness } from '@maude/canvas-lib';"
+  echo
+  echo "// AUTO-GENERATED by \`maude design photo-bg-remove\` — headless bg-removal proof"
+  echo "// harness. Lives under _photo/ (gitignored); safe to delete + regenerate."
+  echo "export default function PhotoBgRemoveCanvas() {"
+  printf '  return <PhotoBgRemoveHarness source=%s />;\n' "\"$ASSET\""
+  echo "}"
+} > "$HARNESS_TSX"
+echo "→ harness canvas: ${HARNESS_TSX#$REPO/}" >&2
+
+REL="_photo/$SLUG.bgremove.tsx"
+URL="http://localhost:$PORT/_canvas-shell.html?canvas=$REL"
+SESSION="photo-bgremove-$SLUG-$$"
+SEL="[data-photo-bgremove-status]"
+
+cleanup() { "$AB" --session "$SESSION" close >/dev/null 2>&1 || true; }
+trap cleanup EXIT
+
+echo "→ driving $URL (session $SESSION)" >&2
+if ! "$AB" --session "$SESSION" open "$URL" >&2; then
+  echo "photo-bg-remove.sh: agent-browser failed to open the harness canvas" >&2
+  exit 3
+fi
+
+# ---------- poll the harness's status attribute ----------
+# The ML pass includes a first-use ~40 MB model-weight fetch (Task 11/12) —
+# this can dominate the wait far more than inference itself, hence the
+# generous default timeout.
+ELAPSED=0
+STATUS="pending"
+while [ "$ELAPSED" -lt "$TIMEOUT" ]; do
+  STATUS="$("$AB" --session "$SESSION" get attr "$SEL" data-photo-bgremove-status 2>/dev/null | tr -d '"')"
+  case "$STATUS" in
+    done|error) break ;;
+  esac
+  sleep 2
+  ELAPSED=$((ELAPSED + 2))
+done
+
+if [ "$STATUS" = "error" ]; then
+  ERR="$("$AB" --session "$SESSION" get attr "$SEL" data-photo-bgremove-error 2>/dev/null | tr -d '"')"
+  echo "photo-bg-remove.sh: harness reported an error: ${ERR:-unknown}" >&2
+  exit 4
+fi
+
+if [ "$STATUS" != "done" ]; then
+  echo "photo-bg-remove.sh: timed out after ${TIMEOUT}s waiting for the ML pass (still '$STATUS')" >&2
+  exit 5
+fi
+
+RESULT="$("$AB" --session "$SESSION" get attr "$SEL" data-photo-bgremove-result 2>/dev/null | tr -d '"')"
+[ -n "$RESULT" ] || { echo "photo-bg-remove.sh: harness reported done but no result asset" >&2; exit 4; }
+
+echo "→ background removed → $RESULT" >&2
+# Last stdout line = the new matte asset path, for $(maude design photo-bg-remove ...) capture.
+printf '%s\n' "$RESULT"

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

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# probe-footage.sh — thin shim over _probe-footage-playwright.mjs; reached via
+# `maude design probe-footage` (DDR-062), never a raw bin path. Extracts keyframe
+# PNGs from one clip in headless Chromium for the footage-analyst's vision pass
+# (feature-footage-analysis-director, Task 4). See the .mjs for the rationale.
+#
+# Usage:
+#   probe-footage.sh <assets/<sha8>.<ext>> --root <repo> [--design-root .design]
+#                    [--frames N] [--out-dir DIR]
+#
+# stdout on success = a JSON manifest { asset, durationSec, width, height, frames }.
+# Exit: 0 ok · 2 usage · 3 no browser · 4 decode/probe error · 1 other.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,14p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+# The probe imports `playwright` (Chromium). Prefer node (the runtime the other
+# playwright shims run under); fall back to bun in a dev tree.
+if command -v node >/dev/null 2>&1; then
+  exec node "$SCRIPT_DIR/_probe-footage-playwright.mjs" "$@"
+elif command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT_DIR/_probe-footage-playwright.mjs" "$@"
+else
+  echo "probe-footage.sh: node or bun is required." >&2
+  exit 1
+fi