@1agh/maude 0.41.0 → 0.43.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,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

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/screenshot.sh

@@ -9,12 +9,18 @@
 #                 [--screen <id> | --element <id> | --selector <css> | --full]
 #                 [--all-screens] [--out <path>] [--out-dir <dir>]
 #                 [--timeout 8] [--engine auto|agent-browser|playwright]
-#                 [--root <repo>]
+#                 [--theme <name>] [--root <repo>]
 #
 # Notes:
 #   - Exactly one of --screen / --element / --selector / --full is required
 #     (or --all-screens which loops over every [data-dc-screen]/[data-dc-slot]).
 #   - --out required for single-shot modes; --out-dir required for --all-screens.
+#   - --theme <name> forces every `[data-theme]` element (DS artboard wrappers)
+#     to that value BEFORE capture, via a DOM eval — does not touch the actual
+#     canvas file or the running server's state. Used to capture a DS's
+#     alternate theme deterministically for the dual-theme reality check
+#     (/design:new step 9) instead of relying on whatever the canvas is pinned
+#     to. No-op if the canvas has no `[data-theme]` elements.
 #   - URL resolution: --url > --port + _active.json > _server.json + _active.json.
 #   - Stdout: written PNG paths, one per line (composable in for-loops).
 #   - Stderr: diagnostic, engine choice, timing.
@@ -30,6 +36,7 @@ TIMEOUT=8
 ENGINE="auto"
 ALL_SCREENS=0
 ROOT=""
+THEME=""
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -44,9 +51,10 @@ while [ $# -gt 0 ]; do
     --out-dir)  OUT_DIR="$2"; shift 2 ;;
     --timeout)  TIMEOUT="$2"; shift 2 ;;
     --engine)   ENGINE="$2"; shift 2 ;;
+    --theme)    THEME="$2"; shift 2 ;;
     --root)     ROOT="$2"; shift 2 ;;
     --help|-h)
-      sed -n '2,22p' "$0" | sed 's/^# \?//'
+      sed -n '2,27p' "$0" | sed 's/^# \?//'
       exit 0
       ;;
     *)
@@ -57,6 +65,20 @@ while [ $# -gt 0 ]; do
 done
 
 # ---------- arg validation ----------
+# --theme ultimately traces back to config.json's designSystems[].themes[]
+# (untrusted, same posture as prep.sh's MOODBOARD_VARIANTS). Callers (e.g.
+# new.md step 9) build an --out-dir path from this value — reject anything
+# outside a safe slug charset here too, at the shared sink, rather than
+# trusting every caller to re-derive this guard.
+if [ -n "$THEME" ]; then
+  case "$THEME" in
+    *[!A-Za-z0-9._-]*|"")
+      echo "screenshot.sh: --theme '$THEME' contains unsafe characters (allowed: A-Za-z0-9._-)" >&2
+      exit 2
+      ;;
+  esac
+fi
+
 if [ $ALL_SCREENS -eq 1 ]; then
   [ -z "$OUT_DIR" ] && { echo "screenshot.sh: --all-screens needs --out-dir" >&2; exit 2; }
 else
@@ -189,10 +211,12 @@ pw_screenshot() {
     return 1
   fi
   echo "→ playwright engine; first invocation may install chromium (~150MB, one-off)" >&2
+  local theme_args=()
+  [ -n "$THEME" ] && theme_args=(--theme "$THEME")
   if [ -n "$css" ]; then
-    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --selector "$css" --out "$out" --timeout "$TIMEOUT" >&2 || return 1
+    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --selector "$css" --out "$out" --timeout "$TIMEOUT" "${theme_args[@]}" >&2 || return 1
   else
-    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --out "$out" --timeout "$TIMEOUT" >&2 || return 1
+    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --out "$out" --timeout "$TIMEOUT" "${theme_args[@]}" >&2 || return 1
   fi
   [ -s "$out" ] || { echo "✗ playwright wrote no file: $out" >&2; return 1; }
   return 0
@@ -224,9 +248,34 @@ navigate_once() {
       echo "→ no DC mount detected after ${TIMEOUT}s — proceeding (may be a non-canvas page)" >&2
       sleep 1
     fi
+    apply_theme_override
   fi
 }
 
+# ---------- --theme override (dual-theme reality check) ----------
+# Forces every element carrying a `data-theme` attribute (DS artboard theme
+# wrappers) to $THEME, so the caller can deterministically capture a DS's
+# alternate theme instead of whatever the canvas happens to be pinned to.
+# agent-browser only — the playwright path applies it inside
+# _screenshot-playwright.mjs (passed via --theme) since that shim owns its own
+# page.evaluate. No-op when --theme wasn't passed or no [data-theme] elements
+# exist (e.g. a single-theme DS or a non-canvas page).
+apply_theme_override() {
+  [ -z "$THEME" ] && return 0
+  [ "$ENGINE" = "agent-browser" ] || return 0
+  # THEME ultimately traces back to config.json's designSystems[].themes[]
+  # array — treated as untrusted input elsewhere in this codebase (see
+  # prep.sh's MOODBOARD_VARIANTS clamp). JSON-encode it via jq so it lands as
+  # a properly-escaped JS string literal in the eval'd expression below,
+  # instead of naively splicing the raw value into a JS string (which a
+  # crafted config value could break out of).
+  local theme_json
+  theme_json=$(jq -Rn --arg t "$THEME" '$t' 2>/dev/null) || return 0
+  local n
+  n=$("$AB" eval "(function(t){var els=document.querySelectorAll('[data-theme]');els.forEach(function(el){el.setAttribute('data-theme',t)});return els.length})($theme_json)" 2>/dev/null)
+  echo "→ theme override: forced data-theme=\"$THEME\" on $(printf '%s' "$n" | tr -d '[:space:]') element(s)" >&2
+}
+
 capture() {
   local css="$1"
   local out="$2"