@1agh/maude 0.15.0

package/plugins/design/dev-server/bin/_screenshot-playwright.mjs

@@ -0,0 +1,50 @@
+// _screenshot-playwright.mjs — playwright fallback for screenshot.sh.
+// Element-scoped form (playwright CLI has no --selector flag, so we drive
+// chromium via the API for that case). Full-page form is also implemented
+// here so screenshot.sh has a single fallback entrypoint regardless of mode.
+//
+// Invocation (called by screenshot.sh — not directly by users):
+//   npm exec --package=playwright -- node _screenshot-playwright.mjs \
+//     --url <url> [--selector <css>] --out <path> [--timeout 8]
+//
+// First invocation may install chromium (~150 MB). Subsequent runs reuse cache.
+
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { chromium } from 'playwright';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, cur, i, all) => {
+    if (cur.startsWith('--')) acc.push([cur.slice(2), all[i + 1]]);
+    return acc;
+  }, [])
+);
+
+const { url, selector, out, timeout = '8' } = args;
+if (!url || !out) {
+  console.error(
+    'usage: _screenshot-playwright.mjs --url <url> [--selector <css>] --out <path> [--timeout 8]'
+  );
+  process.exit(2);
+}
+
+const timeoutMs = Number(timeout) * 1000;
+mkdirSync(dirname(out), { recursive: true });
+
+const browser = await chromium.launch();
+try {
+  const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  const page = await ctx.newPage();
+  await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+
+  if (selector) {
+    const loc = page.locator(selector).first();
+    await loc.waitFor({ state: 'visible', timeout: timeoutMs });
+    await loc.screenshot({ path: out });
+  } else {
+    await page.screenshot({ path: out, fullPage: true });
+  }
+  console.error(`✓ playwright wrote ${out}`);
+} finally {
+  await browser.close();
+}

package/plugins/design/dev-server/bin/bootstrap-check.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# bootstrap-check.sh — detect whether the project has a usable design system.
+# Canonical recipe (was inline in `commands/new.md` step 0 + `commands/edit.md` step 0).
+#
+# Usage:
+#   bootstrap-check.sh                # human-readable next-step on stdout, exit 0/10/11
+#   bootstrap-check.sh --json         # JSON on stdout, exit 0/10/11
+#   bootstrap-check.sh --shell-export # `export FOO=bar` lines on stdout, eval-friendly
+#
+# Exit codes:
+#   0  — ready (config + at least one DS in system/)
+#   10 — needs `/design:init` (no .design/config.json)
+#   11 — needs `/design:setup-ds` (config present, no DS folders)
+
+MODE="default"
+case "$1" in
+  --json)         MODE="json" ;;
+  --shell-export) MODE="shell" ;;
+  --help|-h)
+    sed -n '2,16p' "$0" | sed 's/^# \?//'
+    exit 0
+    ;;
+  "") ;;
+  *)
+    echo "bootstrap-check.sh: unknown arg '$1' (try --help)" >&2
+    exit 2
+    ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+CFG="$REPO_ROOT/.design/config.json"
+
+CONFIG_PRESENT="false"
+[ -f "$CFG" ] && CONFIG_PRESENT="true"
+
+HAS_DS="false"
+if [ -d "$REPO_ROOT/.design/system" ]; then
+  if find "$REPO_ROOT/.design/system" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | grep -q .; then
+    HAS_DS="true"
+  fi
+fi
+
+KNOWN_DS=""
+DEFAULT_DS="project"
+if [ "$CONFIG_PRESENT" = "true" ] && command -v jq >/dev/null 2>&1; then
+  KNOWN_DS=$(jq -r '.designSystems[]?.name // empty' "$CFG" 2>/dev/null | tr '\n' ' ' | sed 's/ $//')
+  ds_default=$(jq -r '.defaultDesignSystem // empty' "$CFG" 2>/dev/null)
+  [ -n "$ds_default" ] && DEFAULT_DS="$ds_default"
+fi
+
+# Decide exit code
+EXIT_CODE=0
+if [ "$CONFIG_PRESENT" = "false" ]; then
+  EXIT_CODE=10
+elif [ "$HAS_DS" = "false" ]; then
+  EXIT_CODE=11
+fi
+
+case "$MODE" in
+  json)
+    printf '{"has_ds":%s,"config_present":%s,"repo_root":"%s","known_ds":[%s],"default_ds":"%s","exit_code":%d}\n' \
+      "$HAS_DS" "$CONFIG_PRESENT" "$REPO_ROOT" \
+      "$(printf '%s' "$KNOWN_DS" | awk 'NF{for(i=1;i<=NF;i++) printf "%s\"%s\"",(i>1?",":""),$i}')" \
+      "$DEFAULT_DS" "$EXIT_CODE"
+    ;;
+  shell)
+    printf 'export HAS_DS=%s\n' "$HAS_DS"
+    printf 'export CONFIG_PRESENT=%s\n' "$CONFIG_PRESENT"
+    printf 'export REPO_ROOT=%s\n' "$REPO_ROOT"
+    printf 'export KNOWN_DS=%s\n' "\"$KNOWN_DS\""
+    printf 'export DEFAULT_DS=%s\n' "$DEFAULT_DS"
+    printf 'export BOOTSTRAP_EXIT=%d\n' "$EXIT_CODE"
+    ;;
+  default)
+    case "$EXIT_CODE" in
+      0)  echo "✓ ready — design system(s): ${KNOWN_DS:-$DEFAULT_DS}" ;;
+      10) echo "→ Run /design:init first (no .design/config.json found at $REPO_ROOT)" ;;
+      11) echo "→ Run /design:setup-ds <name> first (no DS in $REPO_ROOT/.design/system/)" ;;
+    esac
+    ;;
+esac
+
+exit $EXIT_CODE

package/plugins/design/dev-server/bin/canvas-edit.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# canvas-edit.sh — AST-aware single-attribute edit on a canvas .tsx file.
+# Wraps `plugins/design/dev-server/canvas-edit.ts` so /design:edit Step 3a can
+# shell out without booting a Bun module loader inline. Phase 3.6 Task 5.
+#
+# Usage:  canvas-edit.sh <canvas-abs-path> <data-cd-id> <attr> <value>
+#
+#   <canvas-abs-path>  absolute path of the .tsx canvas file
+#   <data-cd-id>       8-hex id from the inspector / _locator.json
+#   <attr>             "className" | "style.<prop>" | any JSX attribute name
+#   <value>            new value (bare string for className / plain attrs;
+#                      a JS expression for style.<prop> — e.g. '"#facc15"',
+#                      `14`, `"calc(100% - 2px)"`)
+#
+# Exit codes:
+#   0   edit applied (or no-op when source already matched)
+#   1   bad usage / missing file
+#   2   AST edit failed (id not found, parse error, unsupported attribute shape)
+#
+# Output:
+#   On success, prints one JSON line: {"canvas": "...", "id": "...", "delta": <int>}
+#   On failure, prints the underlying error to stderr.
+#
+# This script intentionally has no fallback path — Bun is the only supported
+# runtime (DDR-009). Callers should pre-flight `mdcc --version` if the
+# environment is uncertain.
+
+set -euo pipefail
+
+if [ $# -lt 4 ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+  echo "Usage: canvas-edit.sh <canvas-abs-path> <data-cd-id> <attr> <value>" >&2
+  [ "$1" = "--help" ] || [ "$1" = "-h" ] && exit 0
+  exit 1
+fi
+
+CANVAS="$1"
+ID="$2"
+ATTR="$3"
+VALUE="$4"
+
+if [ ! -f "$CANVAS" ]; then
+  echo "canvas-edit: file not found: $CANVAS" >&2
+  exit 1
+fi
+
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+
+bun --silent run "$HERE/canvas-edit.ts" --invoke "$CANVAS" "$ID" "$ATTR" "$VALUE" 2>&1 || exit 2

package/plugins/design/dev-server/bin/handoff.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# /design:handoff CLI wrapper — emits <Slug>.registry.json sidecar next to a
+# canvas TSX. Thin shell-out so /design:handoff doesn't have to spin up Bun
+# from the orchestrator side.
+#
+# Usage:
+#   bin/handoff.sh <canvas-abs-path> [designRoot]
+#
+# Output (stdout, line 1): JSON {"dest":"...","files":N,"deps":M}
+# Exit code 0 on success, 2 on any failure (with reason on stderr).
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "usage: handoff.sh <canvas-abs-path> [designRoot]" >&2
+  exit 2
+fi
+
+CANVAS="$1"
+DESIGN_ROOT="${2:-}"
+
+DIR="$(cd "$(dirname "$0")/.." && pwd)"
+if [ -n "$DESIGN_ROOT" ]; then
+  exec bun run "$DIR/handoff.ts" --emit "$CANVAS" "$DESIGN_ROOT"
+else
+  exec bun run "$DIR/handoff.ts" --emit "$CANVAS"
+fi

package/plugins/design/dev-server/bin/screenshot.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# screenshot.sh — canonical screenshot helper for the design plugin.
+# Wraps agent-browser (preferred) or playwright (fallback). Replaces the
+# inline `agent-browser navigate + screenshot` bash blocks previously
+# duplicated across new.md / edit.md / setup-ds.md / screenshot.md / critics.
+#
+# Usage:
+#   screenshot.sh [--port N | --url URL]
+#                 [--screen <id> | --element <id> | --selector <css> | --full]
+#                 [--all-screens] [--out <path>] [--out-dir <dir>]
+#                 [--timeout 8] [--engine auto|agent-browser|playwright]
+#                 [--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.
+#   - 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.
+#   - Exit: 0 success / 1 missing dependency / 2 bad args / 3 capture failed.
+
+MODE=""
+SEL=""
+URL=""
+PORT=""
+OUT=""
+OUT_DIR=""
+TIMEOUT=8
+ENGINE="auto"
+ALL_SCREENS=0
+ROOT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --screen)   MODE="screen";   SEL="$2"; shift 2 ;;
+    --element)  MODE="element";  SEL="$2"; shift 2 ;;
+    --selector) MODE="selector"; SEL="$2"; shift 2 ;;
+    --full)     MODE="full"; shift ;;
+    --all-screens) ALL_SCREENS=1; shift ;;
+    --url)      URL="$2"; shift 2 ;;
+    --port)     PORT="$2"; shift 2 ;;
+    --out)      OUT="$2"; shift 2 ;;
+    --out-dir)  OUT_DIR="$2"; shift 2 ;;
+    --timeout)  TIMEOUT="$2"; shift 2 ;;
+    --engine)   ENGINE="$2"; shift 2 ;;
+    --root)     ROOT="$2"; shift 2 ;;
+    --help|-h)
+      sed -n '2,22p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "screenshot.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# ---------- arg validation ----------
+if [ $ALL_SCREENS -eq 1 ]; then
+  [ -z "$OUT_DIR" ] && { echo "screenshot.sh: --all-screens needs --out-dir" >&2; exit 2; }
+else
+  [ -z "$MODE" ]    && { echo "screenshot.sh: pick one of --full/--screen/--element/--selector or --all-screens" >&2; exit 2; }
+  [ -z "$OUT" ]     && { echo "screenshot.sh: --out required for single-shot modes" >&2; exit 2; }
+fi
+
+# ---------- url resolution ----------
+if [ -z "$URL" ]; then
+  REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+  STATE="$REPO/.design/_server.json"
+  ACTIVE_JSON="$REPO/.design/_active.json"
+  if [ -z "$PORT" ] && [ -f "$STATE" ]; then
+    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
+  fi
+  [ -z "$PORT" ] && { echo "screenshot.sh: no --url/--port given and _server.json not found (run server-up.sh)" >&2; exit 1; }
+
+  if [ -f "$ACTIVE_JSON" ] && command -v jq >/dev/null 2>&1; then
+    ACTIVE=$(jq -r '.active // empty' "$ACTIVE_JSON" 2>/dev/null)
+  fi
+  [ -z "$ACTIVE" ] && { echo "screenshot.sh: no active canvas in _active.json (open one in browser first)" >&2; exit 1; }
+
+  # URL-encode spaces (rough); leave other chars alone.
+  ACTIVE_ENC=$(printf '%s' "$ACTIVE" | sed 's/ /%20/g')
+  URL="http://localhost:${PORT}/${ACTIVE_ENC}"
+fi
+
+# ---------- selector mapping ----------
+case "$MODE" in
+  screen)   CSS_SEL="[data-dc-screen=\"$SEL\"], [data-dc-slot=\"$SEL\"]" ;;
+  element)  CSS_SEL="[data-dc-element=\"$SEL\"]" ;;
+  selector) CSS_SEL="$SEL" ;;
+  full|"")  CSS_SEL="" ;;
+esac
+
+# ---------- engine resolution ----------
+if [ "$ENGINE" = "auto" ]; then
+  if command -v agent-browser >/dev/null 2>&1; then
+    ENGINE="agent-browser"
+  else
+    ENGINE="playwright"
+  fi
+fi
+echo "→ screenshot engine: $ENGINE | url: $URL" >&2
+
+# ---------- engine: agent-browser ----------
+ab_screenshot() {
+  local css="$1"
+  local out="$2"
+  if [ -n "$css" ]; then
+    agent-browser screenshot "$css" "$out" >&2 || return 1
+  else
+    agent-browser screenshot --full "$out" >&2 || return 1
+  fi
+  # agent-browser sometimes reports success without writing — verify size.
+  if [ ! -s "$out" ]; then
+    echo "✗ agent-browser reported success but output file missing/empty: $out" >&2
+    return 1
+  fi
+  return 0
+}
+
+# ---------- engine: playwright ----------
+pw_screenshot() {
+  local css="$1"
+  local out="$2"
+  local script_dir
+  script_dir="$(cd "$(dirname "$0")" && pwd)"
+  local pw_script="$script_dir/_screenshot-playwright.mjs"
+  if [ ! -f "$pw_script" ]; then
+    echo "✗ playwright fallback shim missing at $pw_script" >&2
+    return 1
+  fi
+  echo "→ playwright engine; first invocation may install chromium (~150MB, one-off)" >&2
+  if [ -n "$css" ]; then
+    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --selector "$css" --out "$out" --timeout "$TIMEOUT" >&2 || return 1
+  else
+    npm exec --yes --package=playwright -- node "$pw_script" --url "$URL" --out "$out" --timeout "$TIMEOUT" >&2 || return 1
+  fi
+  [ -s "$out" ] || { echo "✗ playwright wrote no file: $out" >&2; return 1; }
+  return 0
+}
+
+navigate_once() {
+  if [ "$ENGINE" = "agent-browser" ]; then
+    agent-browser open "$URL" >&2
+    # Wait for canvas to mount — Babel/React canvases take 2–4s to settle.
+    # Poll for [data-dc-screen] or [data-dc-slot] up to $TIMEOUT seconds; fall
+    # through to a fixed sleep when the page isn't a DC canvas.
+    local poll=0
+    local got=0
+    while [ $poll -lt "$TIMEOUT" ]; do
+      sleep 1
+      poll=$((poll + 1))
+      local raw
+      raw=$(agent-browser eval "document.querySelectorAll('[data-dc-screen],[data-dc-slot]').length" 2>/dev/null)
+      # raw is a plain number on success — strip whitespace, validate.
+      local has=$(printf '%s' "$raw" | tr -d '[:space:]')
+      case "$has" in
+        ''|*[!0-9]*) continue ;;
+        0) continue ;;
+        *) got=1; break ;;
+      esac
+    done
+    if [ $got -eq 0 ]; then
+      # Fallback: give static pages (specimens, non-canvas HTMLs) a chance.
+      echo "→ no DC mount detected after ${TIMEOUT}s — proceeding (may be a non-canvas page)" >&2
+      sleep 1
+    fi
+  fi
+}
+
+capture() {
+  local css="$1"
+  local out="$2"
+  mkdir -p "$(dirname "$out")"
+  if [ "$ENGINE" = "agent-browser" ]; then
+    ab_screenshot "$css" "$out"
+  else
+    pw_screenshot "$css" "$out"
+  fi
+}
+
+# ---------- --all-screens loop ----------
+if [ $ALL_SCREENS -eq 1 ]; then
+  mkdir -p "$OUT_DIR"
+  navigate_once
+  IDS=""
+  if [ "$ENGINE" = "agent-browser" ]; then
+    # agent-browser wraps string results in quotes and escapes newlines as
+    # literal `\n`; comma-join + tr is simpler than parsing JSON for IDs.
+    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)
+    # Strip surrounding quotes, then split on comma.
+    IDS=$(printf '%s' "$raw" | sed 's/^"//; s/"$//' | tr ',' '\n')
+  fi
+  if [ -z "$IDS" ]; then
+    echo "✗ no [data-dc-screen]/[data-dc-slot] elements found (or eval unavailable on this engine)" >&2
+    exit 3
+  fi
+  N=0
+  FAILED=0
+  for ID in $IDS; do
+    N=$((N + 1))
+    NN=$(printf "%03d" "$N")
+    OUT_FILE="$OUT_DIR/${NN}-screen-${ID}.png"
+    if [ "$ENGINE" = "agent-browser" ]; 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
+      echo "$OUT_FILE"
+    else
+      echo "✗ failed: $ID" >&2
+      FAILED=$((FAILED + 1))
+    fi
+  done
+  [ $FAILED -gt 0 ] && exit 3
+  exit 0
+fi
+
+# ---------- single-shot ----------
+navigate_once
+if capture "$CSS_SEL" "$OUT"; then
+  echo "$OUT"
+  exit 0
+fi
+exit 3

package/plugins/design/dev-server/bin/server-up.sh

@@ -0,0 +1,135 @@
+#!/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):
+#   - Default: bun + server.ts. Hard-fails when bun is not on $PATH.
+#   - --allow-legacy: opt-in fallback to node + server.mjs (debug only;
+#     no TSX canvas pipeline, no HMR). Sunset in DDR-020 Phase B.
+#
+# Output: prints the port on stdout. Diagnostic lines go to stderr.
+# Exit:   0 = server ready / 1 = start timeout or missing runtime / 2 = bad args.
+
+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. DDR-020: bun + server.ts is
+# authoritative. Legacy node + server.mjs is sunset; available only behind
+# --allow-legacy (debug-only — no TSX canvas pipeline, no HMR).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+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
+
+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 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 2 — spawn.
+mkdir -p "$DESIGN_ROOT"
+echo "→ starting dev server: $RUNTIME_CMD --root $REPO" >&2
+if [ "$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/plugins/design/dev-server/bin/slug.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# slug.sh — normalize a canvas relative-path into a filesystem-safe slug.
+# Canonical recipe for `_history/<slug>/` path computation. Sourced from
+# `commands/edit.md` step 3 originally; now the single source of truth.
+#
+# Usage:  slug.sh "<path-relative-to-designRoot>"
+# Output: lowercase kebab slug — e.g. "ui/showcase/Match Recap.tsx" -> "ui-showcase-match_recap"
+
+if [ $# -lt 1 ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+  echo "Usage: slug.sh <relative-path>" >&2
+  echo "Example: slug.sh 'ui/showcase/Match Recap.tsx' -> ui-showcase-match_recap" >&2
+  [ "$1" = "--help" ] || [ "$1" = "-h" ] && exit 0
+  exit 1
+fi
+
+printf '%s' "${1#./}" \
+  | tr '/' '-' \
+  | tr ' ' '_' \
+  | tr '[:upper:]' '[:lower:]' \
+  | sed -E 's/\.(tsx|jsx|html?|css|json|md)$//' \
+  | sed 's/^\.\+//'
+echo