@1agh/maude 0.42.0 → 0.44.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/audio-search.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# audio-search.sh — feature-ai-media-generation (Task 2.5, DDR-164). Reuse-before-
+# you-pay for AUDIO: before generating a new music/SFX/VO track, search the
+# project's own generated audio + the user's ElevenLabs history and prefer an
+# existing suitable track over spending credits. The search + reuse run
+# server-side (the key is resolved by the sidecar), so this is a pure fetch to
+# the running dev server — mirrors generate.sh.
+#
+# Reached via `maude design audio-search` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   audio-search.sh --query "<text>" [--root <repo>] [--reuse <historyId>] [--json]
+#
+# Requires a running dev server (caller runs `maude design server-up` first).
+#
+# Stdout (last line, --reuse): the localized /assets/<sha8>.mp3 path.
+# Exit: 0 ok / 1 server problem / 2 bad args / 3 search/reuse failed.
+
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "audio-search.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
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bun run "$SCRIPT_DIR/_audio-search.mjs" "$@"

package/apps/studio/bin/generate.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# generate.sh — feature-ai-media-generation (Phase 0, DDR-16x). Headless BYOK
+# AI-media generation: POST a GenRequest to the running dev server's privileged
+# /_api/generate-jobs route, poll the job to completion, and print the produced
+# content-addressed asset path (`/assets/<sha8>.<ext>`).
+#
+# The thin, non-browser sibling of the studio generate dialog — the provider call
+# happens SERVER-SIDE (the sidecar resolves the key from the OS keychain /
+# ~/.config/maude/keys.json and calls the provider directly), so this verb is a
+# pure JSON curl + poll, exactly like photo-adjust.sh. No client-side inference,
+# so a harness canvas + agent-browser would be pure overhead.
+#
+# Reached via `maude design generate` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   generate.sh --prompt "<text>" [--provider gemini|elevenlabs] [--model <id>]
+#     [--modality image|audio|video] [--aspect 16:9] [--source assets/<sha8>.<ext>]
+#     [--kind music|sfx|tts] [--voice <voice_id>] [--duration <seconds>]
+#     [--root <repo>] [--timeout <sec>]
+#
+# --source turns an IMAGE call into a maskless EDIT (Nano Banana): the content-
+# addressed source image is read server-side into the request and the prompt
+# describes the change; a NEW content-addressed asset is produced (the original
+# is never mutated). For --modality video it is the image-to-video SEED (a still
+# → a clip, so a generated clip can match a generated hero's style).
+#
+# --modality audio (provider elevenlabs): --kind music (default) | sfx | tts.
+# tts needs --voice <voice_id>; music/sfx take an optional --duration in seconds.
+# Produces assets/<sha8>.mp3. (Transcription is a separate verb: `maude design
+# transcribe`, which writes SRT/VTT.)
+#
+# --modality video (provider gemini / Veo 3.1): ASYNC — the clip takes ~1–10 min;
+# the poll timeout defaults to 600s for video (180s otherwise). Produces
+# assets/<sha8>.mp4 + a provenance assets/<sha8>.footage.json stub so the clip is
+# reel-ready (see /design:reel Step 1.5).
+#
+# The key is NEVER passed here — it lives server-side. Add it in Settings
+# (⌘,) or drop it into ~/.config/maude/keys.json (mode 0600).
+#
+# Requires a running dev server (caller runs `maude design server-up` first);
+# reads the port from <designRoot>/_server.json.
+#
+# Stdout (last line): the produced asset path `/assets/<sha8>.<ext>` (for $(...)).
+# Stderr: progress / diagnostics.
+# Exit:   0 ok / 1 server problem / 2 bad args / 3 generation failed.
+
+set -euo pipefail
+
+PROMPT="" PROVIDER="gemini" MODEL="" MODALITY="image" ASPECT="" SOURCE="" REPO="" TIMEOUT=""
+# Audio params (Phase 2) — kind = music|sfx|tts; voice = an ElevenLabs voice_id
+# (required for tts); duration = seconds (music/sfx length).
+KIND="" VOICE="" DURATION=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --prompt)   PROMPT="$2"; shift 2 ;;
+    --provider) PROVIDER="$2"; shift 2 ;;
+    --model)    MODEL="$2"; shift 2 ;;
+    --modality) MODALITY="$2"; shift 2 ;;
+    --aspect)   ASPECT="$2"; shift 2 ;;
+    --source)   SOURCE="$2"; shift 2 ;;
+    --kind)     KIND="$2"; shift 2 ;;
+    --voice)    VOICE="$2"; shift 2 ;;
+    --duration) DURATION="$2"; shift 2 ;;
+    --root)     REPO="$2"; shift 2 ;;
+    --timeout)  TIMEOUT="$2"; shift 2 ;;
+    --help|-h)  sed -n '2,41p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "generate.sh: unknown arg '$1'" >&2; exit 2 ;;
+  esac
+done
+
+# generate.sh produces MEDIA (image / audio) from a prompt. Transcription is a
+# different shape (audio → captions) reached via `maude design transcribe`, which
+# writes SRT/VTT files — not this verb, whose contract is "print the produced
+# asset path".
+[ -n "$PROMPT" ] || { echo "generate.sh: --prompt is required" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "generate.sh: jq is required" >&2; exit 1; }
+
+# Async video (Veo) takes minutes — default the poll window wider than the
+# seconds-fast image/audio calls unless the caller pinned --timeout explicitly.
+if [ -z "$TIMEOUT" ]; then
+  if [ "$MODALITY" = "video" ]; then TIMEOUT="600"; else TIMEOUT="180"; fi
+fi
+
+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 "generate.sh: no .design/ under $REPO" >&2; exit 1; }
+
+STATE="$DESIGN_ROOT/_server.json"
+[ -f "$STATE" ] || { echo "generate.sh: no _server.json (start the dev server first)" >&2; exit 1; }
+PORT=$(jq -r '.port // empty' "$STATE" 2>/dev/null)
+[ -n "$PORT" ] || { echo "generate.sh: could not read port from $STATE" >&2; exit 1; }
+
+BASE="http://127.0.0.1:$PORT/_api/generate-jobs"
+
+# Normalize a --source to the `assets/<sha8>.<ext>` form the route validates
+# (strip a leading slash the canvas-relative writers emit).
+SOURCE="${SOURCE#/}"
+
+# Build the audio params object (only the set keys) — audioKind / voice_id /
+# durationSeconds are opaque to the spine; each adapter validates its own subset.
+PARAMS=$(jq -n --arg kind "$KIND" --arg voice "$VOICE" --arg dur "$DURATION" '
+  {}
+  + (if $kind  != "" then { audioKind: $kind }               else {} end)
+  + (if $voice != "" then { voice_id: $voice }               else {} end)
+  + (if $dur   != "" then { durationSeconds: ($dur|tonumber) } else {} end)')
+
+# Build the request body — jq handles all prompt escaping. Omit empty optionals.
+BODY=$(jq -n \
+  --arg modality "$MODALITY" --arg provider "$PROVIDER" --arg model "$MODEL" \
+  --arg prompt "$PROMPT" --arg aspect "$ASPECT" --arg source "$SOURCE" \
+  --argjson params "$PARAMS" '
+  { modality: $modality, provider: $provider }
+  + (if $prompt != "" then { prompt: $prompt }      else {} end)
+  + (if $model  != "" then { model: $model }        else {} end)
+  + (if $aspect != "" then { aspectRatio: $aspect } else {} end)
+  + (if $source != "" then { sourceAsset: $source } else {} end)
+  + (if ($params|length) > 0 then { params: $params } else {} end)')
+
+echo "generate.sh: submitting to $PROVIDER ($MODALITY)…" >&2
+RESP=$(curl -s -X POST -H 'Content-Type: application/json' -d "$BODY" "$BASE")
+JOB_ID=$(printf '%s' "$RESP" | jq -r '.jobId // empty' 2>/dev/null || echo "")
+if [ -z "$JOB_ID" ]; then
+  echo "generate.sh: enqueue rejected: $RESP" >&2
+  exit 3
+fi
+echo "generate.sh: job $JOB_ID queued — polling…" >&2
+
+# Poll the job list until this job is done/failed, or the timeout elapses.
+DEADLINE=$(( $(date +%s) + TIMEOUT ))
+while :; do
+  JOBS=$(curl -s "$BASE" 2>/dev/null || echo '{}')
+  JOB=$(printf '%s' "$JOBS" | jq -c --arg id "$JOB_ID" '.jobs[]? | select(.id == $id)' 2>/dev/null || echo "")
+  STATUS=$(printf '%s' "$JOB" | jq -r '.status // empty' 2>/dev/null || echo "")
+  case "$STATUS" in
+    done)
+      ASSET=$(printf '%s' "$JOB" | jq -r '.assets[0] // empty' 2>/dev/null || echo "")
+      [ -n "$ASSET" ] || { echo "generate.sh: job done but produced no asset" >&2; exit 3; }
+      # Normalize to the leading-slash canvas-relative form writers use.
+      printf '/%s\n' "${ASSET#/}"
+      exit 0 ;;
+    failed)
+      ERR=$(printf '%s' "$JOB" | jq -r '.error // "unknown error"' 2>/dev/null || echo "unknown")
+      echo "generate.sh: generation failed: $ERR" >&2
+      exit 3 ;;
+  esac
+  if [ "$(date +%s)" -ge "$DEADLINE" ]; then
+    echo "generate.sh: timed out after ${TIMEOUT}s (job still $STATUS)" >&2
+    exit 3
+  fi
+  sleep 2
+done

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# import-asset.sh — hardened local-file SVG/PDF ingestion. Thin shim over
+# _import-asset.mjs; reached via `maude design import-asset` (DDR-062), never
+# a raw bin path. See _import-asset.mjs + DDR-167 for the full security
+# rationale. Requires bun (not the node/bun fallback fetch-asset.sh uses) —
+# _import-asset.mjs imports the `.ts` SVGO engine module directly, same
+# constraint as svg-optimize.sh.
+#
+# Usage:
+#   import-asset.sh <local-path> --root <repo> [--design-root .design]
+#                   [--kind svg|pdf|raster] [--json]
+#
+# stdout on success = one reference path per line (e.g. /assets/a44d3d60.svg).
+# PDF import is not yet available (DDR-167 addendum) — the verb accepts a
+# .pdf input and fails loud naming why, rather than silently rejecting it as
+# an unknown flag. `raster` (PNG/JPEG, magic-byte sniffed) content-addresses
+# a local image as-is — added for DDR-174/T15's vision-reconstruction source.
+#
+# Exit: 0 ok · 1 not-yet-available/other · 2 usage · 3 sanitize/validation
+#       reject · 4 read/parse error · 5 unsupported media type ·
+#       6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,17p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-asset.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-asset.mjs" "$@"

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# import-brand.sh — brand-file typed-cue extraction (DDR-173). Thin shim over
+# _import-brand.mjs; reached via `maude design import-brand` (DDR-062), never
+# a raw bin path. Operates ONLY on an already-DDR-167-sanitized SVG asset
+# (as produced by `maude design import-asset`) — never re-reads or
+# re-sanitizes the original brand file (DDR-173 Decision 2: no parallel,
+# ungated read path). Requires bun — _import-brand.mjs imports
+# _import-tokens.mjs's `.mjs` grammar reuse and happy-dom directly.
+#
+# Usage:
+#   import-brand.sh <sanitized-svg-path> --root <repo> [--design-root .design] [--json]
+#
+# stdout on success = the typed payload `{ palette, fonts, logoRef, logoRasterRef }`.
+#
+# Exit: 0 ok · 1 other · 2 usage · 3 validation/hardening reject ·
+#       4 read/parse error · 6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,15p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-brand.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-brand.mjs" "$@"

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# import-tokens.sh — token-file import (W3C design-tokens / Style-Dictionary
+# JSON / raw CSS custom properties -> the DS CSS-variable contract). Thin
+# shim over _import-tokens.mjs; reached via `maude design import-tokens`
+# (DDR-062), never a raw bin path. See _import-tokens.mjs + DDR-172 for the
+# full mapping contract + security rationale. Requires bun — _import-tokens.mjs
+# imports the `.ts` palette/paths modules directly, same constraint as
+# import-asset.sh.
+#
+# All args are forwarded quoted ("$@") — never unquoted or eval-expanded
+# (DDR-172 Decision 8 wrapper-hygiene requirement; the charset/shape
+# validation itself happens in _import-tokens.mjs, not here).
+#
+# Usage:
+#   import-tokens.sh <token-file> --root <repo> [--design-root .design]
+#                    [--ds <name> | --new-ds <name>] [--theme <name>]
+#                    [--force-insert] [--json]
+#
+# Exit: 0 ok · 1 other · 2 usage · 3 validation/mapping reject ·
+#       4 read/parse error · 5 unsupported format · 6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,16p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-tokens.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-tokens.mjs" "$@"

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