@1agh/maude 0.28.0 → 0.29.0

package/{plugins/design/dev-server → apps/studio}/bin/scenario-report.mjs

@@ -21,7 +21,7 @@
 //
 // Output: <run-dir>/report.md (or --out), zero external dependencies (node:fs only).
 
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 
 const PLATFORM_ORDER = ['web-desktop', 'web-mobile', 'ios-phone', 'ios-tablet', 'android-phone'];

package/{plugins/design/dev-server → apps/studio}/bin/screenshot.sh

@@ -213,6 +213,55 @@ capture() {
   fi
 }
 
+# ---------- port-bounce recovery (P2.1 / DDR-094) ----------
+# The dev server can respawn on a DIFFERENT port (the prior port got taken, a
+# Tailscale/mDNS hiccup bounced it, a stale _server.json was cleared). A capture
+# launched against the OLD port then fails with ERR_CONNECTION_REFUSED. The
+# running server keeps _server.json current, so on any capture failure we re-read
+# the LIVE port and, if it changed, rewrite $URL and retry once.
+RELIVE_REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+RELIVE_STATE="$RELIVE_REPO/.design/_server.json"
+RELIVED=0
+
+read_state_port() {
+  [ -f "$RELIVE_STATE" ] || return 1
+  if command -v jq >/dev/null 2>&1; then
+    jq -r .port "$RELIVE_STATE" 2>/dev/null
+  else
+    sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$RELIVE_STATE" 2>/dev/null | head -n1
+  fi
+}
+
+# Re-read the live port; if it differs from the one in $URL, rewrite $URL and
+# return 0 (a retry is warranted). Returns 1 when nothing changed (don't retry).
+# Only fires ONCE per run (RELIVED guard) so a genuinely-down server still fails.
+relive_url() {
+  [ "$RELIVED" -eq 0 ] || return 1
+  local cur new
+  cur=$(printf '%s' "$URL" | sed -nE 's#https?://[^:/]+:([0-9]+).*#\1#p')
+  new=$(read_state_port)
+  [ -n "$new" ] || return 1
+  if [ -n "$cur" ] && [ "$cur" != "$new" ]; then
+    URL=$(printf '%s' "$URL" | sed -E "s#(://[^:/]+:)[0-9]+#\1${new}#")
+    RELIVED=1
+    echo "→ dev-server bounced ports ($cur → $new); re-reading _server.json and retrying at $URL" >&2
+    return 0
+  fi
+  return 1
+}
+
+# capture(), but on failure re-read the live port and retry once if it bounced.
+capture_resilient() {
+  local css="$1"
+  local out="$2"
+  capture "$css" "$out" && return 0
+  if relive_url; then
+    navigate_once
+    capture "$css" "$out" && return 0
+  fi
+  return 1
+}
+
 # ---------- --all-screens loop ----------
 if [ $ALL_SCREENS -eq 1 ]; then
   mkdir -p "$OUT_DIR"
@@ -227,6 +276,17 @@ if [ $ALL_SCREENS -eq 1 ]; then
     # Strip surrounding quotes, then split on comma.
     IDS=$(printf '%s' "$raw" | sed 's/^"//; s/"$//' | tr ',' '\n')
   fi
+  # No screens enumerated may mean the page never loaded (port bounce) — try a
+  # live-port re-read + one re-navigate before giving up.
+  if [ -z "$IDS" ] && relive_url; then
+    navigate_once
+    if [ "$ENGINE" = "agent-browser" ]; then
+      raw=$(agent-browser eval \
+        "Array.from(document.querySelectorAll('[data-dc-screen],[data-dc-slot]')).map(e => e.getAttribute('data-dc-screen') || e.getAttribute('data-dc-slot')).filter(Boolean).join(',')" \
+        2>/dev/null)
+      IDS=$(printf '%s' "$raw" | sed 's/^"//; s/"$//' | tr ',' '\n')
+    fi
+  fi
   if [ -z "$IDS" ]; then
     echo "✗ no [data-dc-screen]/[data-dc-slot] elements found (or eval unavailable on this engine)" >&2
     exit 3
@@ -241,7 +301,7 @@ if [ $ALL_SCREENS -eq 1 ]; then
       agent-browser eval "document.querySelector('[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]').scrollIntoView({block:'center'})" >/dev/null 2>&1
       sleep 0.6
     fi
-    if capture "[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]" "$OUT_FILE"; then
+    if capture_resilient "[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]" "$OUT_FILE"; then
       echo "$OUT_FILE"
     else
       echo "✗ failed: $ID" >&2
@@ -254,7 +314,7 @@ fi
 
 # ---------- single-shot ----------
 navigate_once
-if capture "$CSS_SEL" "$OUT"; then
+if capture_resilient "$CSS_SEL" "$OUT"; then
   echo "$OUT"
   exit 0
 fi

package/apps/studio/bin/server-up.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# server-up.sh — ensure the design dev server is running for the given repo.
+# Canonical recipe (was inline in `edit.md` step 2, `new.md` step 2, etc.).
+#
+# Usage:
+#   server-up.sh [--root <repo>] [--timeout 10] [--allow-legacy]
+#
+# Reads / writes:
+#   $DESIGN_ROOT/_server.json   (PID + port the running server wrote)
+#   $DESIGN_ROOT/_server.log    (stdout/stderr of the spawned server)
+#
+# Runtime selection (DDR-020 / DDR-009 / DDR-084), in priority order:
+#   - --allow-legacy: opt-in node + server.mjs (debug only; no TSX pipeline, no HMR).
+#   - compiled platform binary: the PRODUCTION runtime — embeds yjs + every dep, so
+#     it boots on a global @1agh/maude install where `bun server.ts` from source
+#     cannot. Path comes from MAUDE_DEV_SERVER_BIN (set by `maude design <verb>`) or
+#     the postinstall side-channel <pkgRoot>/cli/.platform-binary-path.
+#   - bun + server.ts: dev tree / fallback. MAUDE_FORCE_SOURCE=1 forces this.
+#
+# Output: prints the port on stdout. Diagnostic lines go to stderr.
+# Exit:   0 = server ready / 1 = start timeout or missing runtime / 2 = bad args /
+#         3 = dev-server runtime deps missing (yjs/y-protocols/lib0 — see preflight).
+
+REPO=""
+TIMEOUT=10
+ALLOW_LEGACY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)    REPO="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --allow-legacy) ALLOW_LEGACY=1; shift ;;
+    --help|-h)
+      sed -n '2,21p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "server-up.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Resolve repo root.
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+
+# Resolve plugin root + pick a server runtime.
+#   --allow-legacy → node + server.mjs (debug-only — no TSX pipeline, no HMR).
+#   compiled platform binary → the PRODUCTION runtime (DDR-009/DDR-084). It embeds
+#     yjs + every dev-server dep, so it boots on a global `@1agh/maude` install
+#     where `bun server.ts` from source CANNOT (the deps live in a nested
+#     package.json the npm tarball excludes — the historic yjs-at-boot crash).
+#     `maude design <verb>` resolves it and passes MAUDE_DEV_SERVER_BIN; a direct
+#     `bash server-up.sh` falls back to the postinstall side-channel.
+#   bun + server.ts → dev tree / fallback (DDR-020 made bun authoritative for source).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# PLUGIN_ROOT is a 2-levels-under-pkgRoot anchor: plugins/design when `maude
+# design <verb>` sets CLAUDE_PLUGIN_ROOT, else apps/studio ($SCRIPT_DIR/.. — the
+# studio root, also 2-deep) for a direct `bash server-up.sh`. Both keep
+# `$PLUGIN_ROOT/../../cli` = <pkgRoot>/cli. The dev-server tree itself is always
+# $SCRIPT_DIR/.. (apps/studio) — DDR-095 moved it out of plugins/design.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+SERVER_TS="$PLUGIN_ROOT/dev-server/server.ts"
+SERVER_MJS="$PLUGIN_ROOT/dev-server/server.mjs"
+if [ ! -f "$SERVER_TS" ]; then SERVER_TS="$SCRIPT_DIR/../server.ts"; fi
+if [ ! -f "$SERVER_MJS" ]; then SERVER_MJS="$SCRIPT_DIR/../server.mjs"; fi
+
+# Resolve the compiled binary: env (set by `maude design <verb>`) wins; else the
+# postinstall side-channel at <pkgRoot>/cli/.platform-binary-path (covers a direct
+# `bash server-up.sh` on a production install). MAUDE_FORCE_SOURCE=1 forces source.
+SERVER_BIN="${MAUDE_DEV_SERVER_BIN:-}"
+if [ -z "$SERVER_BIN" ] && [ "${MAUDE_FORCE_SOURCE:-0}" != "1" ]; then
+  # PLUGIN_ROOT is 2-deep under pkgRoot (plugins/design or apps/studio), so the
+  # side-channel is ../../cli either way.
+  # `head -n1` (parity with the Node readers' `.trim()`) tolerates a trailing newline.
+  SC="$PLUGIN_ROOT/../../cli/.platform-binary-path"
+  if [ -f "$SC" ]; then
+    CAND="$(head -n1 "$SC" 2>/dev/null)"
+    [ -n "$CAND" ] && [ -x "$CAND" ] && SERVER_BIN="$CAND"
+  fi
+fi
+# Structural allowlist (DDR-084 hardening): only spawn a path that LOOKS like the
+# compiled platform binary — basename `maude`/`maude.exe` inside a `maude-<slug>/`
+# dir. A poisoned side-channel file or an injected MAUDE_DEV_SERVER_BIN pointing
+# elsewhere is ignored (fall back to source), so the env/file can only DENY the
+# binary, never redirect the spawn to an arbitrary executable. Mirrors
+# isPlausiblePlatformBinary() in cli/commands/design.mjs.
+if [ -n "$SERVER_BIN" ]; then
+  _sbase="$(basename "$SERVER_BIN")"
+  _sparent="$(basename "$(dirname "$SERVER_BIN")")"
+  case "$_sbase:$_sparent" in
+    maude:maude-* | maude.exe:maude-*) : ;;
+    *)
+      echo "server-up.sh: ignoring dev-server binary outside the expected maude-<slug>/ layout ($SERVER_BIN) — falling back to source" >&2
+      SERVER_BIN=""
+      ;;
+  esac
+fi
+
+RUNTIME=""
+RUNTIME_CMD=""
+if [ $ALLOW_LEGACY -eq 1 ]; then
+  if [ ! -f "$SERVER_MJS" ]; then
+    echo "server-up.sh: --allow-legacy requested but server.mjs not found at $SERVER_MJS" >&2
+    exit 1
+  fi
+  RUNTIME="node"
+  RUNTIME_CMD="node $SERVER_MJS"
+  echo "server-up.sh: WARNING — running legacy server.mjs (no TSX canvas pipeline, no HMR). DDR-020 sunsets this in Phase B." >&2
+elif [ -n "$SERVER_BIN" ] && [ -x "$SERVER_BIN" ] && [ "${MAUDE_FORCE_SOURCE:-0}" != "1" ]; then
+  RUNTIME="binary"
+  RUNTIME_CMD="$SERVER_BIN"
+  echo "server-up.sh: using compiled dev-server binary ($SERVER_BIN)" >&2
+elif command -v bun >/dev/null 2>&1 && [ -f "$SERVER_TS" ]; then
+  RUNTIME="bun"
+  RUNTIME_CMD="bun $SERVER_TS"
+else
+  echo "server-up.sh: bun not on \$PATH — install via https://bun.sh/install" >&2
+  echo "server-up.sh: DDR-020 made bun authoritative; the node fallback is opt-in via --allow-legacy (debug only)." >&2
+  exit 1
+fi
+
+DESIGN_ROOT="$REPO/.design"
+STATE="$DESIGN_ROOT/_server.json"
+
+read_port() {
+  if command -v jq >/dev/null 2>&1; then
+    jq -r .port "$STATE" 2>/dev/null
+  else
+    # Best-effort grep — jq is in repo deps but be defensive.
+    sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" 2>/dev/null | head -n1
+  fi
+}
+read_pid() {
+  if command -v jq >/dev/null 2>&1; then
+    jq -r .pid "$STATE" 2>/dev/null
+  else
+    sed -nE 's/.*"pid"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" 2>/dev/null | head -n1
+  fi
+}
+
+# Step 1 — check existing.
+NEEDS_START=1
+if [ -f "$STATE" ]; then
+  PID=$(read_pid)
+  PORT=$(read_port)
+  if [ -n "$PID" ] && [ -n "$PORT" ] \
+     && kill -0 "$PID" 2>/dev/null \
+     && curl -fs "http://localhost:$PORT/_health" >/dev/null 2>&1; then
+    echo "✓ server alive pid=$PID port=$PORT" >&2
+    echo "$PORT"
+    exit 0
+  else
+    echo "→ stale _server.json — clearing and respawning" >&2
+    rm -f "$STATE"
+  fi
+fi
+
+# Step 1.5 — dependency preflight (source `bun server.ts` path ONLY; runs on cold
+# start). The compiled binary embeds its deps, so this is skipped when RUNTIME=binary
+# — it only guards the source fallback. The dev-server's runtime deps live in a
+# NESTED package.json (apps/studio/) that a global `@1agh/maude` npm
+# install or a fresh `git worktree` does NOT populate; a missing `yjs` (imported at
+# boot by sync/index.ts) crashes `bun server.ts` AFTER spawn → without this guard we
+# poll the full ${TIMEOUT}s and report a generic "start timeout", burying the cause
+# in _server.log and silently degrading the mandatory visual-sanity gate. Fail loud
+# NOW with a context-correct hint. No auto-install: boot-self-heal.ts (DDR-044)
+# dropped that, and the durable production fix is booting the compiled binary
+# (DDR-009/DDR-084), not a boot-time install. setup-ds Round-2 / DDR-083 + DDR-084.
+if [ "$RUNTIME" = "bun" ]; then
+  DEV_SERVER_DIR="$(cd "$(dirname "$SERVER_TS")" && pwd)"
+  _resolve_dep() {
+    # Mirror node/bun bare-specifier resolution: walk node_modules up to /.
+    # Handles both the dev-server-local install and a workspace-hoisted one.
+    local dep="$1" d="$DEV_SERVER_DIR"
+    while [ -n "$d" ] && [ "$d" != "/" ]; do
+      [ -e "$d/node_modules/$dep/package.json" ] && return 0
+      d="$(dirname "$d")"
+    done
+    return 1
+  }
+  MISSING_DEPS=""
+  for dep in yjs y-protocols lib0; do
+    _resolve_dep "$dep" || MISSING_DEPS="$MISSING_DEPS $dep"
+  done
+  if [ -n "$MISSING_DEPS" ]; then
+    {
+      echo "✗ dev-server runtime deps not installed:$MISSING_DEPS"
+      if [ -f "$DEV_SERVER_DIR/package.json" ]; then
+        # A manifest is present (local dev tree / checkout) — install resolves it.
+        echo "  → run: (cd \"$DEV_SERVER_DIR\" && bun install)   # or: pnpm install at the repo root"
+      else
+        # No manifest beside server.ts AND no compiled binary resolved → the
+        # '@1agh/maude' install is incomplete. The platform binary (which embeds
+        # these deps) is the production runtime — reinstall to get it.
+        echo "  (no dev-server package.json here and no compiled binary resolved — the"
+        echo "   '@1agh/maude' install is incomplete; the platform binary embeds these deps)"
+        echo "  → reinstall:  npm i -g @1agh/maude     (or: npm rebuild -g @1agh/maude)"
+      fi
+    } >&2
+    exit 3
+  fi
+fi
+
+# Step 2 — spawn.
+mkdir -p "$DESIGN_ROOT"
+echo "→ starting dev server: $RUNTIME_CMD --root $REPO" >&2
+if [ "$RUNTIME" = "binary" ]; then
+  nohup "$SERVER_BIN" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &
+elif [ "$RUNTIME" = "bun" ]; then
+  nohup bun "$SERVER_TS" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &
+elif [ "$RUNTIME" = "node" ]; then
+  nohup node "$SERVER_MJS" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &
+fi
+disown 2>/dev/null || true
+
+# Step 3 — poll.
+i=0
+while [ $i -lt "$TIMEOUT" ]; do
+  sleep 1
+  i=$((i + 1))
+  if [ -f "$STATE" ]; then
+    PORT=$(read_port)
+    if [ -n "$PORT" ] && curl -fs "http://localhost:$PORT/_health" >/dev/null 2>&1; then
+      echo "✓ server started port=$PORT after ${i}s" >&2
+      echo "$PORT"
+      exit 0
+    fi
+  fi
+done
+
+echo "✗ server start timeout after ${TIMEOUT}s; check $DESIGN_ROOT/_server.log" >&2
+exit 1

package/apps/studio/bin/to-lottie-verify.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<!-- to-lottie-verify.html — self-verify harness for `maude design to-lottie --verify`.
+     Renders ANY Lottie JSON through the REAL lottie-web runtime (NOT cairo — cairo
+     can't render masks; lottie-web must — DDR-094 rule 5). Generalized from the POC
+     verify.html: the Lottie source + the seek frame are query params.
+
+     Serve this dir (file:// blocks fetch):  python3 -m http.server 8200
+     Usage:  to-lottie-verify.html?src=<file.json>&f=<frame>   (omit ?f to autoplay)
+             &bg=<css color>  — backdrop (default dark)  ·  &w=&h= — stage size px -->
+<html>
+  <head>
+    <meta charset="utf8" />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+      #stage {
+        margin: 20px auto;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="stage"></div>
+    <script>
+      const p = new URLSearchParams(location.search);
+      const src = p.get('src');
+      const f = p.get('f');
+      const bg = p.get('bg') || '#0a0a14';
+      const w = p.get('w') || '400';
+      const h = p.get('h') || '400';
+      document.body.style.background = bg;
+      const stage = document.getElementById('stage');
+      stage.style.width = `${w}px`;
+      stage.style.height = `${h}px`;
+
+      if (!src) {
+        document.title = 'error-no-src';
+      } else {
+        fetch(`./${src}`)
+          .then((r) => {
+            if (!r.ok) throw new Error(`fetch ${src} → ${r.status}`);
+            return r.json();
+          })
+          .then((data) => {
+            const anim = lottie.loadAnimation({
+              container: stage,
+              renderer: 'svg',
+              loop: true,
+              autoplay: f === null,
+              animationData: data,
+            });
+            anim.addEventListener('DOMLoaded', () => {
+              if (f !== null) anim.goToAndStop(parseInt(f, 10), true);
+              document.title = `ready${f !== null ? `-${f}` : ''}`;
+            });
+            anim.addEventListener('error', () => {
+              document.title = 'error-render';
+            });
+          })
+          .catch((e) => {
+            document.title = `error-${String(e.message || e).slice(0, 40)}`;
+          });
+      }
+    </script>
+  </body>
+</html>

package/apps/studio/bin/to-lottie.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# to-lottie.sh — emit ONE Lottie from CODE (the maude motion handoff, DDR-094).
+#
+# This is the production-delivery counterpart to draw-build.sh: where draw-build
+# runs an agent-authored *engine* script to emit static SVG/JSX, to-lottie runs an
+# agent-authored *python-lottie generator* to emit ONE `.lottie`/`.json` that
+# renders 1:1 on web (lottie-web / dotlottie-react) AND mobile
+# (lottie-react-native) — same renderer family, 1:1 by construction. It is an
+# EMITTER from the keyframe data, NOT a converter of rendered SVG/SMIL (no reliable
+# one exists — DDR-094 research). The generator encodes the 8 conversion rules; see
+# `plugins/design/commands/to-lottie.md` + `_draw-motion-rules.md`.
+#
+# Reached via `maude design to-lottie` (DDR-062), never a raw bin path.
+#
+# Usage:
+#   to-lottie.sh --script <gen.py> --out <mark.json>
+#                [--verify] [--frames "0,33,66"] [--root <repo>] [--timeout 12]
+#
+# The generator (gen.py) builds the Lottie via python-lottie and writes it to the
+# path in $MAUDE_LOTTIE_OUT (= --out). python-lottie owns format correctness
+# (beziers, keyframes, gradients, masks, parenting); the agent encodes the
+# conversion rules (per-segment easing incl. overshoot, arc parsing via
+# parse_svg_file, layers[0]=top + reverse, masks, baked sub-loops, coord offset,
+# gradient opacity stops).
+#
+# --verify renders frames through HEADLESS lottie-web (cairo can't render masks —
+# lottie-web must) using the shipped harness + the screenshot helper, so you can
+# read the PNGs and compare to the web reference.
+#
+# Stdout (last line): the output .json path (capturable in $(...)).
+# Exit: 0 ok / 1 missing input or runtime / 2 bad args / 3 generate failed
+#       / 4 verify render failed.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GEN=""
+OUT=""
+VERIFY=0
+FRAMES="0,33,66"
+REPO=""
+TIMEOUT=12
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --script)  GEN="$2"; shift 2 ;;
+    --out)     OUT="$2"; shift 2 ;;
+    --verify)  VERIFY=1; shift ;;
+    --frames)  FRAMES="$2"; shift 2 ;;
+    --root)    REPO="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --help|-h) sed -n '2,33p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "to-lottie.sh: unknown arg '$1' (try --help)" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$GEN" ] || { echo "to-lottie.sh: --script <gen.py> required" >&2; exit 2; }
+[ -n "$OUT" ] || { echo "to-lottie.sh: --out <mark.json> required" >&2; exit 2; }
+[ -f "$GEN" ] || { echo "to-lottie.sh: generator not found: $GEN" >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "to-lottie.sh: python3 is required." >&2; exit 1; }
+
+# ---------- python-lottie venv (cached, idempotent) ----------
+VENV="${MAUDE_LOTTIE_VENV:-${XDG_CACHE_HOME:-$HOME/.cache}/maude/lottie-venv}"
+PY="$VENV/bin/python"
+if [ ! -x "$PY" ]; then
+  echo "→ bootstrapping python-lottie venv at $VENV (one-off) …" >&2
+  python3 -m venv "$VENV" || { echo "to-lottie.sh: venv create failed" >&2; exit 1; }
+  "$VENV/bin/pip" install --quiet --disable-pip-version-check lottie cairosvg pillow \
+    || { echo "to-lottie.sh: pip install lottie failed (needs network on first run)" >&2; exit 1; }
+fi
+# Sanity: the `lottie` module must import.
+"$PY" -c 'import lottie' 2>/dev/null || {
+  echo "→ (re)installing python-lottie into $VENV …" >&2
+  "$VENV/bin/pip" install --quiet --disable-pip-version-check lottie cairosvg pillow \
+    || { echo "to-lottie.sh: python-lottie unavailable" >&2; exit 1; }
+}
+
+# ---------- generate ----------
+mkdir -p "$(dirname "$OUT")"
+echo "→ generating Lottie: $GEN → $OUT" >&2
+MAUDE_LOTTIE_OUT="$OUT" "$PY" "$GEN" >&2
+GRC=$?
+if [ "$GRC" -ne 0 ] || [ ! -s "$OUT" ]; then
+  echo "to-lottie.sh: generator failed (rc=$GRC) or wrote no output to $OUT" >&2
+  exit 3
+fi
+# Validity gate: the output must be parseable JSON with the Lottie shape keys.
+"$PY" - "$OUT" <<'PYEOF' >&2 || { echo "to-lottie.sh: output is not a valid Lottie JSON" >&2; exit 3; }
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert isinstance(d, dict) and 'layers' in d and 'op' in d, 'missing Lottie keys (layers/op)'
+print(f"  ✓ valid Lottie: {len(d.get('layers', []))} layers, {d.get('op')} frames @ {d.get('fr')}fps")
+PYEOF
+
+# ---------- self-verify through headless lottie-web ----------
+if [ "$VERIFY" -eq 1 ]; then
+  HARNESS="$SCRIPT_DIR/to-lottie-verify.html"
+  [ -f "$HARNESS" ] || { echo "to-lottie.sh: verify harness missing at $HARNESS — reinstall maude." >&2; exit 1; }
+  OUT_DIR_ABS="$(cd "$(dirname "$OUT")" && pwd)"
+  OUT_BASE="$(basename "$OUT")"
+  cp "$HARNESS" "$OUT_DIR_ABS/_to-lottie-verify.html"
+  FRAMES_DIR="$OUT_DIR_ABS/_verify-frames"
+  mkdir -p "$FRAMES_DIR"
+
+  # Serve the dir (file:// blocks fetch of the JSON). Pick a free-ish port.
+  PORT=$(( ( RANDOM % 2000 ) + 8200 ))
+  ( cd "$OUT_DIR_ABS" && "$PY" -m http.server "$PORT" >/dev/null 2>&1 ) &
+  SRV_PID=$!
+  trap 'kill "$SRV_PID" 2>/dev/null; rm -f "$OUT_DIR_ABS/_to-lottie-verify.html"' EXIT
+  sleep 1
+
+  FAIL=0
+  IFS=',' read -r -a FRAME_ARR <<< "$FRAMES"
+  for F in "${FRAME_ARR[@]}"; do
+    F_TRIM="$(printf '%s' "$F" | tr -d '[:space:]')"
+    URL="http://localhost:$PORT/_to-lottie-verify.html?src=$OUT_BASE&f=$F_TRIM"
+    PNG="$FRAMES_DIR/frame-$F_TRIM.png"
+    echo "→ verify frame $F_TRIM ($URL)" >&2
+    bash "$SCRIPT_DIR/screenshot.sh" --url "$URL" --full --out "$PNG" --timeout "$TIMEOUT" >&2 \
+      || { echo "✗ verify frame $F_TRIM failed" >&2; FAIL=$((FAIL + 1)); }
+  done
+  if [ "$FAIL" -gt 0 ]; then
+    echo "to-lottie.sh: $FAIL verify frame(s) failed to render" >&2
+    exit 4
+  fi
+  echo "→ verify frames in $FRAMES_DIR — READ them and compare to the web reference (masks render on lottie-web, NOT cairo)" >&2
+fi
+
+# Last stdout line = the output path, for $(maude design to-lottie ...) capture.
+printf '%s\n' "$OUT"

package/{plugins/design/dev-server → apps/studio}/bin/visual-sanity.sh

@@ -41,6 +41,9 @@
 #   2  bad args
 #   3  one or more specimen screenshots failed
 #   4  no specimens existed on disk (DS not scaffolded? typo?)
+#   5  dev-server runtime deps missing (yjs/y-protocols/lib0) — recovery is
+#      `bun install`, NOT skip-or-retry; distinct from a generic boot failure
+#      so the caller routes to the right hint (server-up.sh exit 3). DDR-083.
 
 DS=""
 SPECIMENS=""
@@ -142,18 +145,31 @@ echo "→ booting dev-server (timeout ${BOOT_TIMEOUT}s)" >&2
 PORT=$(bash "$SCRIPT_DIR/server-up.sh" --root "$ROOT_ABS" --timeout "$BOOT_TIMEOUT")
 SERVER_RC=$?
 if [ $SERVER_RC -ne 0 ] || [ -z "$PORT" ]; then
-  echo "✗ dev-server boot failed (server-up.sh exit $SERVER_RC); see $DESIGN_ROOT/_server.log" >&2
+  # server-up.sh exit 3 = the dev-server's runtime deps aren't installed. That's
+  # a distinct failure from a generic boot crash/timeout: the fix is `bun install`,
+  # not "skip or retry". Surface a dedicated status + exit code (5) so the caller
+  # routes to the right remediation instead of the boot-failed AskUserQuestion.
+  # The actionable hint already went to stderr from server-up.sh. DDR-083.
+  if [ $SERVER_RC -eq 3 ]; then
+    echo "✗ dev-server runtime deps missing — run \`bun install\` in the dev-server dir (see hint above)" >&2
+    VS_STATUS="server-deps-missing"
+    VS_EXIT=5
+  else
+    echo "✗ dev-server boot failed (server-up.sh exit $SERVER_RC); see $DESIGN_ROOT/_server.log" >&2
+    VS_STATUS="server-boot-failed"
+    VS_EXIT=1
+  fi
   cat > "$OUT_DIR/_manifest.json" <<EOF
 {
   "ds": "$DS",
   "ts": "$TS",
-  "status": "server-boot-failed",
+  "status": "$VS_STATUS",
   "server_up_rc": $SERVER_RC,
   "specimens_requested": $(printf '%s\n' "${SPEC_ARR[@]}" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sed '/^$/d' | sed 's/.*/"&"/' | paste -sd, -),
   "specimens_captured": []
 }
 EOF
-  exit 1
+  exit $VS_EXIT
 fi
 echo "✓ dev-server on port $PORT" >&2
 

package/{plugins/design/dev-server → apps/studio}/build.ts

@@ -66,8 +66,8 @@ function ensureDist() {
 }
 
 async function readPluginVersion(): Promise<{ version: string }> {
-  // plugins/design/dev-server/ → plugins/design/.claude-plugin/plugin.json
-  const manifest = join(ROOT, '..', '.claude-plugin', 'plugin.json');
+  // apps/studio/ → ../../plugins/design/.claude-plugin/plugin.json (DDR-095)
+  const manifest = join(ROOT, '..', '..', 'plugins', 'design', '.claude-plugin', 'plugin.json');
   try {
     const parsed = JSON.parse(await Bun.file(manifest).text()) as { version?: unknown };
     if (typeof parsed.version === 'string') return { version: parsed.version };
@@ -257,7 +257,9 @@ async function ensureBindingForTarget(oxcSlug: string): Promise<void> {
   let oxcVersion = '0.131.0';
   const candidates = [
     join(ROOT, 'node_modules', 'oxc-parser', 'package.json'),
-    join(ROOT, '..', '..', '..', 'node_modules', 'oxc-parser', 'package.json'),
+    // apps/studio → ../../ = repo root → node_modules (DDR-095: was ../../../ at
+    // the old plugins/design/dev-server depth).
+    join(ROOT, '..', '..', 'node_modules', 'oxc-parser', 'package.json'),
   ];
   for (const c of candidates) {
     if (existsSync(c)) {

package/{plugins/design/dev-server → apps/studio}/canvas-arrowheads.ts

@@ -1,6 +1,6 @@
 /**
  * @file       canvas-arrowheads.ts — Phase 24 arrow shaft + head geometry
- * @scope      plugins/design/dev-server/canvas-arrowheads.ts
+ * @scope      apps/studio/canvas-arrowheads.ts
  * @purpose    Single source of truth for arrow rendering. An ArrowStroke is
  *             reduced to an ordered list of `SvgPrimitive`s (the shaft, then
  *             the start head, then the end head). The serializer formats each

package/{plugins/design/dev-server → apps/studio}/canvas-comment-mount.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       canvas-comment-mount.tsx — shell-owned comment layer + mountCanvas
- * @scope      plugins/design/dev-server/canvas-comment-mount.tsx
+ * @scope      apps/studio/canvas-comment-mount.tsx
  * @purpose    The canvas mount harness (`_shell.html`) calls `mountCanvas`
  *             instead of rendering the canvas default-export raw. mountCanvas
  *             wraps ANY default export — a `DesignCanvas` UI canvas OR a bare
@@ -29,9 +29,9 @@
 import {
   Component,
   type ComponentType,
+  createElement,
   Fragment,
   type ReactNode,
-  createElement,
   useCallback,
   useEffect,
   useMemo,