@1agh/maude 0.42.0 → 0.44.0

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,258 @@
+#!/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).
+#
+# Security hardening (fix-photo-editor-followup-debt, Stage A): `--asset` is
+# validated against the strict `assets/<sha8>.<ext>` shape (mirrors
+# photo-store.ts's SHA_RE) rather than a loose glob — a permissive check
+# previously let a crafted `--asset` value splice unescaped content into the
+# generated harness `.tsx`. The harness-file write is symlink-safe (write to a
+# freshly O_EXCL-created tmp path, then atomic `mv` into place — `mv`/rename(2)
+# replaces a destination symlink's OWN dirent rather than following it, so even
+# a pre-planted symlink at the harness path can't redirect the write into a
+# real reviewed canvas file). The stdout deliverable is shape-validated before
+# print. `--slug` failure hard-fails instead of downgrading to an unsanitized
+# fallback. Concurrent invocations against the SAME asset serialize via a
+# `mkdir`-based lock (portable — `flock` isn't available on macOS by default).
+#
+# 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
+#         (or produced a malformed result) / 5 timed out waiting for the ML
+#         pass to finish / 6 another run is already in progress for this asset
+
+set -uo pipefail
+
+ASSET="" SLUG="" REPO="" TIMEOUT=150
+# Mirrors photo-store.ts's SHA_RE shape: lowercase hex sha8 (8-64 chars),
+# case-insensitive extension. Shared between --asset validation (Task 1) and
+# the stdout-deliverable validation (Task 3) so the two checks can't drift.
+ASSET_SHAPE_RE='^assets/[0-9a-f]{8,64}\.[a-zA-Z0-9]+$'
+
+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,39p' "$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#/}"
+# Strict shape check (Task 1) — replaces the old `case "$ASSET" in assets/*)`
+# glob, which only checked the PREFIX and let anything after it (quotes,
+# backticks, `../`, JSX-breaking sequences) ride unescaped into the generated
+# harness .tsx below. `[[ =~ ]]` against a character-class regex is the bash
+# equivalent of photo-store.ts's `SHA_RE` hex check — `..`, `/`, quotes, and
+# any non-hex/non-alnum content can never match, so nothing but a clean
+# `assets/<sha8>.<ext>` reference survives validation. Captures the bare sha8
+# for reuse as a filesystem-safe lock key (Task 6).
+if [[ "$ASSET" =~ ^assets/([0-9a-f]{8,64})\.[a-zA-Z0-9]+$ ]]; then
+  ASSET_KEY="${BASH_REMATCH[1]}"
+else
+  echo "photo-bg-remove.sh: --asset must look like assets/<sha8>.<ext> (lowercase hex, 8-64 chars), got '$ASSET'" >&2
+  exit 2
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+[ -n "$SLUG" ] || SLUG=$(basename "$ASSET" | sed -E 's/\.[^.]+$//')
+# Hard-fail (Task 4) instead of downgrading to a lowercased-but-unstripped
+# fallback on slug.sh failure — a safety subprocess's failure must never
+# silently continue with a less-safe code path. This repo has documented
+# history (DDR-045) of sibling-script resolution breaking specifically in
+# packaged/compiled distributions, so this failure mode is realistic.
+# (SLUG_INPUT is captured separately so a failed substitution — which still
+# assigns its, here empty, stdout to $SLUG — doesn't blank the diagnostic.)
+SLUG_INPUT="$SLUG"
+if ! SLUG="$(bash "$SCRIPT_DIR/slug.sh" "$SLUG_INPUT" 2>/dev/null)"; then
+  echo "photo-bg-remove.sh: slug.sh failed to normalize slug '$SLUG_INPUT' — refusing to fall back to an unsanitized value" >&2
+  exit 1
+fi
+# Assigned this early (not just before the agent-browser open call below) so
+# it's always bound by the time `trap cleanup EXIT` is installed — a security
+# review of this plan found that `cleanup()` unconditionally reads $SESSION,
+# and under `set -u` an exit on one of the harness-write failure paths (before
+# SESSION used to be assigned) would abort mid-cleanup on the unbound
+# variable, skipping the `rmdir "$LOCK_DIR"` below it and leaking the lock.
+SESSION="photo-bgremove-$SLUG-$$"
+
+# ---------- 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
+
+# ---------- per-asset concurrency guard (Task 6) ----------
+# `mkdir` is atomic on every POSIX filesystem and needs no extra binary —
+# `flock` isn't available on macOS by default, so this is the portable choice.
+# Keyed on the asset's sha8 (already validated hex — safe as a path segment),
+# NOT global, so two different assets still run concurrently. Fail-fast rather
+# than queue/wait: a full job queue is out of scope for this backstop, whose
+# only job is refusing to let a runaway loop spawn unbounded concurrent
+# browser+WASM processes against the same asset.
+PHOTO_DIR="$DESIGN_ROOT/_photo"
+mkdir -p "$PHOTO_DIR"
+LOCK_DIR="$PHOTO_DIR/.lock.$ASSET_KEY"
+TMP_HARNESS=""
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  echo "photo-bg-remove.sh: another photo-bg-remove run is already in progress for asset '$ASSET' — refusing to run concurrently against the same asset (lock: ${LOCK_DIR#$REPO/})" >&2
+  exit 6
+fi
+
+cleanup() {
+  "$AB" --session "$SESSION" close >/dev/null 2>&1 || true
+  [ -n "$TMP_HARNESS" ] && rm -f "$TMP_HARNESS" 2>/dev/null
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ---------- generate the harness canvas (symlink-safe — Task 2) ----------
+# Write to a freshly O_CREAT|O_EXCL-created tmp path in the SAME directory
+# (same filesystem, so the rename below is atomic), then `mv` into place.
+# `mv`/rename(2) replaces the destination NAME, never dereferences it — so
+# even a pre-planted symlink at $HARNESS_TSX gets its dirent swapped out
+# rather than followed, unlike the bare `{ ... } > "$HARNESS_TSX"` truncating
+# redirect this replaces (which WOULD follow a symlink and could splice
+# attacker-controlled JSX into whatever real file it pointed at). `set -C`
+# (noclobber) makes bash open the tmp path with O_EXCL, so a pre-existing tmp
+# path (including a dangling symlink) fails the write instead of following it
+# — the bash equivalent of sync/atomic-write.ts's Node `wx` flag (DDR-054 §2c).
+HARNESS_TSX="$PHOTO_DIR/$SLUG.bgremove.tsx"
+TMP_HARNESS="$PHOTO_DIR/.$SLUG.bgremove.tsx.tmp.$$.$RANDOM$RANDOM"
+if ! (
+  set -C
+  {
+    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 "}"
+  } > "$TMP_HARNESS"
+); then
+  echo "photo-bg-remove.sh: failed to create harness scratch file (possible pre-existing path at $TMP_HARNESS)" >&2
+  exit 1
+fi
+if ! mv "$TMP_HARNESS" "$HARNESS_TSX"; then
+  echo "photo-bg-remove.sh: atomic rename of harness file failed" >&2
+  exit 1
+fi
+TMP_HARNESS="" # renamed away — nothing left for cleanup() to remove
+echo "→ harness canvas: ${HARNESS_TSX#$REPO/}" >&2
+
+REL="_photo/$SLUG.bgremove.tsx"
+URL="http://localhost:$PORT/_canvas-shell.html?canvas=$REL"
+SEL="[data-photo-bgremove-status]"
+
+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; }
+# Shape-validate the deliverable (Task 3) before it's ever trusted as far as
+# stdout — the harness runs inside the (untrusted, DDR-054) canvas origin, so
+# a malformed/crafted `data-photo-bgremove-result` value is treated exactly
+# like the empty-result case above rather than printed verbatim.
+if [[ ! "$RESULT" =~ $ASSET_SHAPE_RE ]]; then
+  echo "photo-bg-remove.sh: harness reported a malformed result asset '$RESULT'" >&2
+  exit 4
+fi
+
+echo "→ background removed → $RESULT" >&2
+# Last stdout line = the new matte asset path, for $(maude design photo-bg-remove ...) capture.
+printf '%s\n' "$RESULT"
+
+# Clean up the harness scratch file on the SUCCESS path only (Task 5) — left
+# in place on any error exit above, where it's useful for debugging.
+rm -f "$HARNESS_TSX"

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

package/apps/studio/bin/read-annotations.mjs

@@ -105,8 +105,15 @@ Args:
   --json              No-op (JSON is the only output form).
 
 FigJam v3 additive fields per annotation: z (render order), groupIds (deepest →
-shallowest), author ("ai" for annotate-verb strokes), and from/to host ids on
-bound arrows.
+shallowest), author ("ai" for annotate-verb strokes), authorName/authorId
+(human-drawn stickies), and from/to host ids on bound arrows.
+
+Section annotations additionally carry members: an array of every OTHER
+annotation whose center falls inside the section's rect, in SPATIAL reading
+order (top-to-bottom, left-to-right — not paint order), each as
+{ id, tool, order, x, y, w, h, href? }. Answers "what's in this section, and
+in what order" for prompts like "make a video / Instagram carousel from
+this section" without hand-computing containment.
 
 Emits JSON to stdout. A missing annotation file emits [] (exit 0).`;
 
@@ -395,6 +402,31 @@ function readUnknown(tool, attrs, inner) {
 // provenance, render order (z = document position). Applied uniformly after
 // the per-tool extraction; arrows additionally surface bound endpoints as
 // `from`/`to` host ids so a bound diagram reads back as a GRAPH.
+const AUTHOR_NAME_MAX_LEN = 64;
+
+// Phase 3 (whiteboard-improvements) — mirrors annotations-model.ts's
+// sanitizeAuthorName (same code-point ranges: control chars, bidi
+// overrides/isolates, zero-width chars, BOM) so a peer-synced
+// `.annotations.svg`'s authorName/authorId reads identically through
+// either surface. Every string this CLI returns is already treated as DATA
+// by the whiteboard skill's trust model — this additionally strips the
+// characters that could visually spoof an author name.
+function sanitizeAuthorName(raw) {
+  let cleaned = '';
+  for (const ch of raw) {
+    const cp = ch.codePointAt(0) ?? 0;
+    const unsafe =
+      cp <= 0x1f ||
+      (cp >= 0x7f && cp <= 0x9f) ||
+      (cp >= 0x200b && cp <= 0x200f) ||
+      (cp >= 0x202a && cp <= 0x202e) ||
+      (cp >= 0x2066 && cp <= 0x2069) ||
+      cp === 0xfeff;
+    if (!unsafe) cleaned += ch;
+  }
+  return cleaned.trim().slice(0, AUTHOR_NAME_MAX_LEN);
+}
+
 function withShared(o, attrs, z) {
   o.z = z;
   const g = attr(attrs, 'data-group-ids');
@@ -403,6 +435,16 @@ function withShared(o, attrs, z) {
     if (ids.length) o.groupIds = ids;
   }
   if (attr(attrs, 'data-author') === 'ai') o.author = 'ai';
+  const authorName = attr(attrs, 'data-author-name');
+  if (authorName) {
+    const cleaned = sanitizeAuthorName(decodeEntities(authorName));
+    if (cleaned) o.authorName = cleaned;
+  }
+  const authorId = attr(attrs, 'data-author-id');
+  if (authorId) {
+    const cleanedId = sanitizeAuthorName(decodeEntities(authorId));
+    if (cleanedId) o.authorId = cleanedId;
+  }
   if (o.tool === 'arrow') {
     const sb = parseBind(attr(attrs, 'data-start-bind'));
     if (sb) o.from = sb.hostId;
@@ -615,6 +657,85 @@ function anchorToElement(ann, elements) {
   };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Section membership + reading order (Phase 5, feature-whiteboard-
+// annotation-improvements). A common flow: the user drops several media/
+// stickies INTO a section, then asks "make a video from this" / "turn this
+// into an Instagram carousel" — the agent needs to know exactly which
+// annotations live in a given section, and in what visual order, without
+// hand-computing containment or guessing from raw x/y. Mirrors
+// `findElement`'s smallest-containing-rect convention (annotation CENTER
+// inside a rect), applied against SECTION rects instead of DOM element
+// rects.
+
+/**
+ * Spatial reading order — top-to-bottom, then left-to-right — NOT `z`
+ * (paint/document order): a user can drop stickies in any order they like,
+ * and assembling a carousel/video in PAINT order would visibly scramble it.
+ * Rows are bucketed by a Y-tolerance band (half the smallest member's
+ * height, floored at 16 units) so items a few units off from each other
+ * still read as "the same row"; `z` only breaks a true tie (same band, same
+ * x) between two members.
+ */
+function attachSectionMembers(annotations) {
+  const sections = annotations.filter((a) => a.tool === 'section' && a.id);
+  if (!sections.length) return annotations;
+
+  const centerOf = (a) => {
+    if (a.x == null || a.y == null) return null;
+    return { cx: a.x + (a.w || 0) / 2, cy: a.y + (a.h || 0) / 2 };
+  };
+
+  const membersBySection = new Map();
+  for (const section of sections) {
+    const sx1 = section.x;
+    const sy1 = section.y;
+    const sx2 = section.x + (section.w || 0);
+    const sy2 = section.y + (section.h || 0);
+    const candidates = [];
+    for (const a of annotations) {
+      if (a.tool === 'section' || !a.id) continue;
+      const c = centerOf(a);
+      if (!c) continue;
+      if (c.cx < sx1 || c.cx > sx2 || c.cy < sy1 || c.cy > sy2) continue;
+      candidates.push({ ann: a, c });
+    }
+    if (!candidates.length) {
+      membersBySection.set(section.id, []);
+      continue;
+    }
+    const heights = candidates.map((m) => m.ann.h || 0).filter((h) => h > 0);
+    const minHeight = heights.length ? Math.min(...heights) : 40;
+    const band = Math.max(16, minHeight / 2);
+    candidates.sort((m1, m2) => {
+      const dy = m1.c.cy - m2.c.cy;
+      if (Math.abs(dy) > band) return dy;
+      const dx = m1.c.cx - m2.c.cx;
+      if (dx !== 0) return dx;
+      return (m1.ann.z ?? 0) - (m2.ann.z ?? 0);
+    });
+    membersBySection.set(
+      section.id,
+      candidates.map((m, i) => ({
+        id: m.ann.id,
+        tool: m.ann.tool,
+        order: i,
+        x: m.ann.x,
+        y: m.ann.y,
+        w: m.ann.w,
+        h: m.ann.h,
+        ...(m.ann.href ? { href: m.ann.href } : null),
+      }))
+    );
+  }
+
+  return annotations.map((a) =>
+    a.tool === 'section' && membersBySection.has(a.id)
+      ? { ...a, members: membersBySection.get(a.id) }
+      : a
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main
 
@@ -674,6 +795,7 @@ function main() {
   if (artboards.length) {
     annotations = annotations.map((a) => anchorToArtboard(a, artboards));
   }
+  annotations = attachSectionMembers(annotations);
 
   if (args.graph) {
     process.stdout.write(`${JSON.stringify({ annotations, graph: buildGraph(annotations) })}\n`);
@@ -689,6 +811,7 @@ function main() {
 // canvas-rects manifest without a second implementation.
 export {
   anchorToElement,
+  attachSectionMembers,
   buildGraph,
   fileSlug,
   findElement,

package/apps/studio/bin/transcribe.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# transcribe.sh — feature-ai-media-generation (Phase 2, DDR-164). Local, no-key
+# speech-to-text for automatic subtitles: run whisper.cpp on an audio/video file
+# and emit SRT/VTT through the shared captions.ts reflow. The DEFAULT subtitle
+# path — free, offline, private, word-timestamped — with cloud STT (ElevenLabs
+# Scribe / Groq Whisper) as the fallback when whisper.cpp isn't installed.
+#
+# Reached via `maude design transcribe` (never a raw bin path — DDR-062). No dev
+# server needed; the work is a local whisper.cpp spawn (mirrors probe-footage).
+#
+# Usage:
+#   transcribe.sh --source <assets/x.mp4|file> [--root <repo>]
+#     [--provider whisper|elevenlabs|groq]
+#     [--format srt|vtt|both] [--model <id>] [--whisper <bin>]
+#     [--lang <code>] [--segments]
+#
+# The engine is an EXPLICIT user choice (Task 2.6, DDR-164), never an automatic
+# fallback: --provider wins, else the project's generation.transcription.provider
+# config, else local whisper — and it SAYS which it chose. A chosen cloud engine
+# (elevenlabs / groq) needs the dev server running (the key is resolved
+# server-side) and an assets/<sha8> source; whisper is local, free, no key.
+#
+# whisper.cpp is a SOFT dependency (plugins/design/dependencies.json). A ggml
+# model is required (--model / $MAUDE_WHISPER_MODEL); whisper.cpp ships no default
+# and does not auto-download. See _transcribe.mjs for the download pointer.
+#
+# Stdout (last line): the produced .srt path (for $(...) capture).
+# Exit: 0 ok / 1 dependency-or-input problem / 3 transcription failed.
+
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "transcribe.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/_transcribe.mjs" "$@"