@1agh/maude 0.23.0 → 0.24.0

package/plugins/design/dev-server/api.ts

@@ -135,6 +135,15 @@ export interface Api {
   loadCommentsForFile(file: string): Promise<Comment[]>;
   saveCommentsForFile(file: string, list: Comment[]): Promise<void>;
   loadAllComments(): Promise<Record<string, Comment[]>>;
+  /**
+   * Resolve a canvas URL slug back to its repo-relative `file` path by scanning
+   * the ACTUAL canvas files under each canvas group — independent of whether the
+   * canvas has any comments yet. The inverse of `fileSlug`. Returns null when no
+   * canvas matches. Load-bearing for collab: a peer that has not yet received any
+   * comment for a canvas must still resolve the file to MATERIALIZE the first
+   * hub-pushed comment to disk (the receiving-peer projection gap, DDR-064).
+   */
+  fileForSlug(slug: string): Promise<string | null>;
   commentsAdd(payload: Partial<Comment> & { file: string; text: string }): Promise<Comment | null>;
   commentsPatch(id: string, patch: Partial<Comment>): Promise<Comment | null>;
   commentsDelete(id: string): Promise<boolean>;
@@ -173,6 +182,68 @@ export interface ApiHooks {
   onAnnotationsChanged?: (file: string, svg: string) => void;
 }
 
+/**
+ * Elements the annotation tool legitimately emits (`strokesToSvg` in
+ * annotations-layer.tsx). This is the WHOLE vocabulary — purely presentational.
+ */
+const ANNOTATION_SVG_ELEMENTS = new Set([
+  'svg',
+  'g',
+  'path',
+  'rect',
+  'ellipse',
+  'line',
+  'polyline',
+  'text',
+]);
+
+/**
+ * A3 (DDR-060 F1 re-audit) — sanitize an annotation SVG before it is persisted /
+ * synced / mirrored into the collab Y.Map. ALLOWLIST, not denylist (the F1
+ * confirming pass showed a denylist loses the race: `<svg:script>` via namespace,
+ * `javascript&#58;` via HTML entity, `<style>@import url()>`, CSS `url(javascript:)`
+ * all slipped a tag-name denylist). Two rules, both keyed to the fixed legit
+ * vocabulary so they're zero-regression on real annotations:
+ *
+ *   1. Element allowlist — drop the markup of any tag whose LOCAL name (namespace
+ *      stripped, so `svg:script` → `script`) isn't in ANNOTATION_SVG_ELEMENTS.
+ *      Dropped-tag text content survives as inert text (not in a script/style
+ *      context), which is harmless.
+ *   2. Attribute denylist on survivors — the legit vocabulary uses none of
+ *      `on*=`, `style=`, or any `href`, so stripping them closes inline handlers,
+ *      CSS `url(javascript:)`, and entity-encoded `xlink:href` in one pass.
+ *
+ * The current consumer (`svgToStrokes` → DOMParser image/svg+xml → structured
+ * strokes → React) never raw-renders this string, so the live XSS risk is already
+ * nil; this keeps "inert" TRUE for any future raw-render consumer and for the
+ * synced file a peer / Claude-context ingests (defense-in-depth, DDR-054 §3).
+ */
+export function sanitizeAnnotationSvg(svg: string): string {
+  return (
+    svg
+      // 1. Remove the CONTENT of executable / instruction-bearing elements (not
+      //    just their tags) so an injected script body / `@import` / prompt-
+      //    injection string can't survive as inert text a future raw-renderer or
+      //    Claude-context read might act on. Namespace-tolerant (`svg:script`),
+      //    non-greedy to the first matching dangerous close tag.
+      .replace(
+        /<\s*(?:[\w-]+:)?(?:script|style|foreignObject|title|desc)\b[\s\S]*?<\s*\/\s*(?:[\w-]+:)?(?:script|style|foreignObject|title|desc)\s*>/gi,
+        ''
+      )
+      // 2. Element allowlist — drop the markup of any tag whose LOCAL name isn't
+      //    in the fixed annotation vocabulary. `[^>]*` stops at the first `>`;
+      //    annotation attrs never contain a literal `>`.
+      .replace(/<\/?\s*([a-zA-Z][\w:-]*)\b[^>]*>/g, (match, rawName: string) => {
+        const local = String(rawName).split(':').pop()?.toLowerCase() ?? '';
+        return ANNOTATION_SVG_ELEMENTS.has(local) ? match : '';
+      })
+      // 3. Attribute denylist on the surviving allowlisted elements — the legit
+      //    vocabulary uses no on*= / style= / *href=, so stripping them closes
+      //    inline handlers, CSS url(javascript:), and entity-encoded hrefs.
+      .replace(/\s(?:on[a-z]+|style|(?:[\w-]+:)?href)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+  );
+}
+
 export function createApi(ctx: Context, hooks: ApiHooks): Api {
   const onCommentsChanged = hooks.onCommentsChanged;
   const onAnnotationsChanged = hooks.onAnnotationsChanged;
@@ -195,6 +266,28 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       .toLowerCase();
   }
 
+  async function fileForSlug(slug: string): Promise<string | null> {
+    // Authoritative slug → canvas-file resolver: enumerate the real canvas
+    // files under each canvas group and match by the canonical slug. Unlike a
+    // comments-file scan, this resolves even when the canvas has NO comments yet
+    // — the fix for the receiving-peer projection gap where a fresh peer could
+    // not locate the file to write the first hub-pushed comment (DDR-064).
+    for (const g of cfg.canvasGroups) {
+      const groupAbs = path.join(paths.designRoot, g.path);
+      const groupRel = path.posix.join(paths.designRel, g.path);
+      let files: string[];
+      try {
+        files = await findHtmlFiles(groupAbs, groupRel);
+      } catch {
+        continue;
+      }
+      for (const rel of files) {
+        if (fileSlug(rel) === slug) return rel;
+      }
+    }
+    return null;
+  }
+
   function commentsPath(file: string): string {
     return path.join(paths.commentsDir, `${fileSlug(file)}.json`);
   }
@@ -586,11 +679,22 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (typeof svg !== 'string') return false;
     if (svg.length > 1024 * 1024) return false;
     // Cheap content gate — must look like an <svg> document. Avoids accidental
-    // writes of arbitrary blobs through this endpoint. The client controls the
-    // content fully, so we don't try to sanitize beyond a tag check.
+    // writes of arbitrary blobs through this endpoint.
     if (!/^\s*<svg[\s>]/i.test(svg)) return false;
-    await Bun.write(annotationsPath(file), svg);
-    onAnnotationsChanged?.(file, svg);
+    // A3 (DDR-060 F1 re-audit) — sanitize active content before persisting.
+    // This endpoint is on the canvas-origin allowlist (DDR-054 "inert collab
+    // write") and accepts ANY `file`, so a hub-pushed canvas can write a
+    // sibling's `.annotations.svg`. The persisted SVG is currently consumed only
+    // via `svgToStrokes` (DOMParser image/svg+xml → structured strokes → React
+    // re-render), so a `<script>`/`on*` payload is parsed inertly and discarded
+    // — the stored-XSS chain is LATENT today, not live. We sanitize anyway so
+    // "inert" stays true for any future raw-render consumer and for the synced
+    // file a peer/Claude-context ingests. The legit annotation vocabulary
+    // (strokesToSvg) is purely presentational — path/rect/ellipse/g/line/
+    // polyline/text — so stripping executable constructs is zero-regression.
+    const clean = sanitizeAnnotationSvg(svg);
+    await Bun.write(annotationsPath(file), clean);
+    onAnnotationsChanged?.(file, clean);
     return true;
   }
 
@@ -946,6 +1050,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     loadCommentsForFile,
     saveCommentsForFile,
     loadAllComments,
+    fileForSlug,
     commentsAdd,
     commentsPatch,
     commentsDelete,

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

@@ -13,9 +13,16 @@
 #   preflight.sh --warn-only        # same as --quiet (SessionStart hook)
 #
 # Resolution (DDR-045): never compute paths from `dirname $0` inside a
-# `bun --compile` standalone binary — that maps to /$bunfs/root. The CLI
-# entry stays Node, so we resolve via $CLAUDE_PLUGIN_ROOT first, with the
-# script-dir fallback only used when running uncompiled from the repo.
+# `bun --compile` standalone binary — that maps to /$bunfs/root.
+#
+# Resolution (DDR-061): in a MARKETPLACE install the plugin is copied alone into
+# `cache/<marketplace>/<plugin>/<version>/` — there is NO sibling `$PKG_ROOT/cli/`.
+# So: use the sibling `cli/lib` when it exists (running uncompiled from the repo
+# or an npm package, where cli/ is present); otherwise reach the check through
+# the on-PATH `maude` binary (a declared plugin dependency), which resolves the
+# manifest from its own package root. Fixing a straggler — the relative-path
+# crash (`Cannot find module …/cache/maude/cli/lib/preflight.mjs`) that the cache
+# steps already avoid by calling on-PATH `maude`.
 #
 # Exit: 0 if all hard deps pass; 1 otherwise.
 
@@ -23,10 +30,14 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 PKG_ROOT="$(cd "$PLUGIN_ROOT/../.." && pwd)"
 
-# The Node lib needs cwd to be the package root (it resolves dependencies.json
-# via `plugins/<plugin>/dependencies.json`). Subshell so we don't mutate the
-# caller's cwd.
-(
-  cd "$PKG_ROOT" || exit 1
-  exec node "$PKG_ROOT/cli/lib/preflight.mjs" --plugin design "$@"
-)
+if [ -f "$PKG_ROOT/cli/lib/preflight.mjs" ]; then
+  # Sibling cli/ present (repo / npm package). The Node lib needs cwd = package
+  # root (it resolves `plugins/<plugin>/dependencies.json`). Subshell preserves
+  # the caller's cwd.
+  ( cd "$PKG_ROOT" || exit 1; exec node "$PKG_ROOT/cli/lib/preflight.mjs" --plugin design "$@" )
+elif command -v maude >/dev/null 2>&1; then
+  exec maude preflight --plugin design "$@"
+else
+  echo "preflight: no cli/lib beside the plugin and 'maude' not on PATH — install maude (npm i -g @1agh/maude)." >&2
+  exit 1
+fi

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

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# prep.sh — one-shot pre-flight context for the design slash commands.
+#
+# Collapses the 4–8 sequential bash invocations that /design:new, /design:edit
+# and /design:setup-ds each ran in their step-0/step-1 (bootstrap-check + config
+# jq reads + _active.json read + _preflight read + _server.json PID probe + slug
+# compute) into a SINGLE call that emits one structured blob. Same shape family
+# as bootstrap-check.sh / server-up.sh.
+#
+# Reads (all optional — missing files degrade gracefully, never error):
+#   .design/config.json          → NAME, DESIGN_ROOT, ROOT_CLASS, THEME, TOKENS_REL,
+#                                   NEW_CANVAS_DIR, NEW_COMPONENT_DIR, TEAM_ACCENT,
+#                                   DEFAULT_DS, KNOWN_DS, ACCENT_STRATEGY, COLOR_SPACE
+#   <designRoot>/_active.json     → ACTIVE_CANVAS, SELECTED_ELEMENT, SELECTED_FILE,
+#                                   SEL_VALID, OPEN_TABS, ACTIVE_SLUG
+#   <designRoot>/_preflight.json  → DEPS_OK, DEPS_MISSING   (Phase A cache)
+#   <designRoot>/_server.json     → SERVER_UP, SERVER_PORT  (PID liveness + /_health)
+#
+# Usage:
+#   prep.sh                       # JSON on stdout (default)
+#   prep.sh --json                # JSON on stdout
+#   prep.sh --shell-export        # `export FOO=bar` lines, eval-friendly
+#   prep.sh --shape <new|edit|setup-ds>   # emit only the subset that command needs
+#   prep.sh --root <repo>         # override repo root (else git root → $CLAUDE_PROJECT_DIR → pwd)
+#
+# Resolution (DDR-045): resolve the repo root from args/env/git — never from
+# `dirname $0`, which maps to /$bunfs/root inside a bun --compile binary.
+#
+# Exit: 0 always (this is a context gatherer; callers branch on the fields).
+
+MODE="json"
+SHAPE="all"
+REPO=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json)         MODE="json"; shift ;;
+    --shell-export) MODE="shell"; shift ;;
+    --shape)        SHAPE="$2"; shift 2 ;;
+    --root)         REPO="$2"; shift 2 ;;
+    --help|-h)
+      sed -n '2,33p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "prep.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+case "$SHAPE" in
+  all|new|edit|setup-ds) ;;
+  *) echo "prep.sh: --shape must be one of new|edit|setup-ds (got '$SHAPE')" >&2; exit 2 ;;
+esac
+
+# ---- repo root ----------------------------------------------------------------
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+
+HAVE_JQ=0
+command -v jq >/dev/null 2>&1 && HAVE_JQ=1
+
+# ---- config -------------------------------------------------------------------
+CFG="$REPO/.design/config.json"
+CONFIG_PRESENT="false"; [ -f "$CFG" ] && CONFIG_PRESENT="true"
+
+NAME="Project"
+DESIGN_ROOT=".design"
+ROOT_CLASS="app"
+THEME="dark"
+TOKENS_REL="system/colors_and_type.css"
+NEW_CANVAS_DIR="ui/project"
+NEW_COMPONENT_DIR="ui/project/components"
+TEAM_ACCENT=""
+DEFAULT_DS="project"
+KNOWN_DS=""
+ACCENT_STRATEGY="single"
+COLOR_SPACE="oklch"
+
+if [ "$CONFIG_PRESENT" = "true" ] && [ "$HAVE_JQ" = "1" ]; then
+  NAME=$(jq -r '.name // "Project"' "$CFG")
+  DESIGN_ROOT=$(jq -r '.designRoot // ".design"' "$CFG")
+  ROOT_CLASS=$(jq -r '.rootClass // "app"' "$CFG")
+  THEME=$(jq -r '.themeDefault // "dark"' "$CFG")
+  TOKENS_REL=$(jq -r '.tokensCssRel // "system/colors_and_type.css"' "$CFG")
+  NEW_CANVAS_DIR=$(jq -r '.newCanvasDir // "ui/project"' "$CFG")
+  NEW_COMPONENT_DIR=$(jq -r '.newComponentDir // "ui/project/components"' "$CFG")
+  TEAM_ACCENT=$(jq -r '.teamAccentDefault // empty' "$CFG")
+  DEFAULT_DS=$(jq -r '.defaultDesignSystem // "project"' "$CFG")
+  KNOWN_DS=$(jq -r '.designSystems[]?.name // empty' "$CFG" 2>/dev/null | tr '\n' ' ' | sed 's/ $//')
+  ACCENT_STRATEGY=$(jq -r '.accentStrategy // "single"' "$CFG")
+  COLOR_SPACE=$(jq -r '.colorSpace // "oklch"' "$CFG")
+fi
+
+DR_ABS="$REPO/$DESIGN_ROOT"
+
+# ---- active canvas / selection ------------------------------------------------
+ACTIVE_FILE="$DR_ABS/_active.json"
+ACTIVE_CANVAS=""
+SELECTED_ELEMENT=""
+SELECTED_FILE=""
+SEL_VALID="0"
+OPEN_TABS="0"
+ACTIVE_SLUG=""
+if [ -f "$ACTIVE_FILE" ] && [ "$HAVE_JQ" = "1" ]; then
+  ACTIVE_CANVAS=$(jq -r '.active // empty' "$ACTIVE_FILE" 2>/dev/null)
+  [ "$ACTIVE_CANVAS" = "null" ] && ACTIVE_CANVAS=""
+  SELECTED_ELEMENT=$(jq -rc '.selected // empty' "$ACTIVE_FILE" 2>/dev/null)
+  SELECTED_FILE=$(jq -r '.selected.file // empty' "$ACTIVE_FILE" 2>/dev/null)
+  OPEN_TABS=$(jq -r '(.open_tabs // []) | length' "$ACTIVE_FILE" 2>/dev/null || echo 0)
+  if [ -n "$SELECTED_ELEMENT" ] && [ -n "$ACTIVE_CANVAS" ] && [ "$SELECTED_FILE" = "$ACTIVE_CANVAS" ]; then
+    SEL_VALID="1"
+  fi
+  if [ -n "$ACTIVE_CANVAS" ]; then
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+    ACTIVE_SLUG=$(bash "$SCRIPT_DIR/slug.sh" "${ACTIVE_CANVAS#"$DESIGN_ROOT"/}" 2>/dev/null)
+  fi
+fi
+
+# ---- deps preflight cache -----------------------------------------------------
+PREFLIGHT_FILE="$DR_ABS/_preflight.json"
+DEPS_OK="unknown"
+DEPS_MISSING=""
+if [ -f "$PREFLIGHT_FILE" ] && [ "$HAVE_JQ" = "1" ]; then
+  DEPS_OK=$(jq -r 'if .ok == true then "true" elif .ok == false then "false" else "unknown" end' "$PREFLIGHT_FILE" 2>/dev/null || echo unknown)
+  DEPS_MISSING=$(jq -r '(.missing // []) | join(",")' "$PREFLIGHT_FILE" 2>/dev/null || echo "")
+fi
+
+# ---- server liveness ----------------------------------------------------------
+SERVER_FILE="$DR_ABS/_server.json"
+SERVER_UP="false"
+SERVER_PORT=""
+if [ -f "$SERVER_FILE" ] && [ "$HAVE_JQ" = "1" ]; then
+  SERVER_PORT=$(jq -r '.port // empty' "$SERVER_FILE" 2>/dev/null)
+  SERVER_PID=$(jq -r '.pid // empty' "$SERVER_FILE" 2>/dev/null)
+  if [ -n "$SERVER_PID" ] && [ -n "$SERVER_PORT" ] \
+     && kill -0 "$SERVER_PID" 2>/dev/null \
+     && curl -fs "http://localhost:$SERVER_PORT/_health" >/dev/null 2>&1; then
+    SERVER_UP="true"
+  fi
+fi
+
+# ---- emit ---------------------------------------------------------------------
+# Shape membership: `new`/`setup-ds` omit the active-canvas/selection block
+# (those commands don't act on an open canvas); `edit`/`all` emit everything.
+if [ "$MODE" = "shell" ]; then
+  printf 'export REPO_ROOT=%q\n'         "$REPO"
+  printf 'export CONFIG_PRESENT=%s\n'    "$CONFIG_PRESENT"
+  printf 'export NAME=%q\n'              "$NAME"
+  printf 'export DESIGN_ROOT=%q\n'       "$DESIGN_ROOT"
+  printf 'export ROOT_CLASS=%q\n'        "$ROOT_CLASS"
+  printf 'export THEME=%q\n'             "$THEME"
+  printf 'export TOKENS_REL=%q\n'        "$TOKENS_REL"
+  printf 'export NEW_CANVAS_DIR=%q\n'    "$NEW_CANVAS_DIR"
+  printf 'export NEW_COMPONENT_DIR=%q\n' "$NEW_COMPONENT_DIR"
+  printf 'export TEAM_ACCENT=%q\n'       "$TEAM_ACCENT"
+  printf 'export DEFAULT_DS=%q\n'        "$DEFAULT_DS"
+  printf 'export KNOWN_DS=%q\n'          "$KNOWN_DS"
+  printf 'export ACCENT_STRATEGY=%q\n'   "$ACCENT_STRATEGY"
+  printf 'export COLOR_SPACE=%q\n'       "$COLOR_SPACE"
+  printf 'export DEPS_OK=%s\n'           "$DEPS_OK"
+  printf 'export DEPS_MISSING=%q\n'      "$DEPS_MISSING"
+  printf 'export SERVER_UP=%s\n'         "$SERVER_UP"
+  printf 'export SERVER_PORT=%q\n'       "$SERVER_PORT"
+  if [ "$SHAPE" = "edit" ] || [ "$SHAPE" = "all" ]; then
+    printf 'export ACTIVE_CANVAS=%q\n'   "$ACTIVE_CANVAS"
+    printf 'export SELECTED_FILE=%q\n'   "$SELECTED_FILE"
+    printf 'export SEL_VALID=%s\n'       "$SEL_VALID"
+    printf 'export OPEN_TABS=%s\n'       "$OPEN_TABS"
+    printf 'export ACTIVE_SLUG=%q\n'     "$ACTIVE_SLUG"
+  fi
+  exit 0
+fi
+
+# JSON mode — emit via jq when available for correct escaping; fall back to printf.
+if [ "$HAVE_JQ" = "1" ]; then
+  jq -n \
+    --arg repo "$REPO" --arg cfg "$CONFIG_PRESENT" --arg name "$NAME" \
+    --arg dr "$DESIGN_ROOT" --arg rc "$ROOT_CLASS" --arg th "$THEME" \
+    --arg tok "$TOKENS_REL" --arg ncd "$NEW_CANVAS_DIR" --arg ncm "$NEW_COMPONENT_DIR" \
+    --arg acc "$TEAM_ACCENT" --arg dds "$DEFAULT_DS" --arg kds "$KNOWN_DS" \
+    --arg astrat "$ACCENT_STRATEGY" --arg cspace "$COLOR_SPACE" \
+    --arg depsok "$DEPS_OK" --arg depsmiss "$DEPS_MISSING" \
+    --arg sup "$SERVER_UP" --arg sport "$SERVER_PORT" \
+    --arg act "$ACTIVE_CANVAS" --arg selfile "$SELECTED_FILE" \
+    --arg selv "$SEL_VALID" --arg tabs "$OPEN_TABS" --arg slug "$ACTIVE_SLUG" \
+    --argjson sel "${SELECTED_ELEMENT:-null}" \
+    '{
+      repo_root: $repo,
+      config_present: ($cfg == "true"),
+      config: {
+        name: $name, design_root: $dr, root_class: $rc, theme: $th,
+        tokens_rel: $tok, new_canvas_dir: $ncd, new_component_dir: $ncm,
+        team_accent: $acc, default_ds: $dds,
+        known_ds: ($kds | if . == "" then [] else split(" ") end),
+        accent_strategy: $astrat, color_space: $cspace
+      },
+      active: {
+        canvas: $act, selected: $sel, selected_file: $selfile,
+        sel_valid: ($selv == "1"), open_tabs: ($tabs | tonumber? // 0), slug: $slug
+      },
+      deps: { ok: $depsok, missing: ($depsmiss | if . == "" then [] else split(",") end) },
+      server: { up: ($sup == "true"), port: ($sport | if . == "" then null else (tonumber? // .) end) }
+    }'
+else
+  printf '{"repo_root":"%s","config_present":%s,"jq":false,"note":"jq unavailable — install jq for full prep.sh output"}\n' \
+    "$REPO" "$CONFIG_PRESENT"
+fi
+
+exit 0

package/plugins/design/dev-server/bin/scenario-report.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// scenario-report.mjs — deterministic cross-platform scenario report generator.
+//
+// Phase C / DDR-061. Resolves the long-standing "report generator" TODO in
+// plugins/flow/skills/scenario/SKILL.md. Walks a scenario run directory and
+// emits the mechanical sections of report.md (TL;DR table, counter-delta table,
+// per-step pivot, collapsed path-listing). The LLM authors ONLY the prose
+// sections ("What surprised us", "Recommended follow-ups") — they're left as
+// marked placeholders for it to fill in.
+//
+// Invoked from flow markdown via the on-PATH `maude` binary (DDR-062):
+//   maude scenario-report <run-dir> [--out <path>]
+// or directly:
+//   node scenario-report.mjs <run-dir> [--out <path>]
+//
+// Input layout (produced by the scenario runners — see scenario SKILL.md):
+//   <run-dir>/
+//   ├── <platform>/result.txt          # "pass" | "fail: <reason>" | "skipped: <reason>"
+//   ├── <platform>/step-<N>-<desc>.png  # per-step screenshots
+//   └── <platform>/counters.json        # OPTIONAL { "mastered": "+3", "remaining": "-3" }
+//
+// Output: <run-dir>/report.md (or --out), zero external dependencies (node:fs only).
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const PLATFORM_ORDER = ['web-desktop', 'web-mobile', 'ios-phone', 'ios-tablet', 'android-phone'];
+
+const toolingFor = (platform) => (platform.startsWith('web-') ? 'agent-browser' : 'agent-device');
+
+// Parse "pass" / "fail: reason" / "skipped: reason" → { result, reason }.
+function parseResult(text) {
+  const t = (text || '').trim();
+  if (!t) return { result: 'UNKNOWN', reason: 'no result.txt' };
+  const lower = t.toLowerCase();
+  if (lower.startsWith('pass')) return { result: 'PASS', reason: '' };
+  if (lower.startsWith('fail')) return { result: 'FAIL', reason: t.replace(/^fail[:\s]*/i, '') };
+  if (lower.startsWith('skip'))
+    return { result: 'SKIPPED', reason: t.replace(/^skip(ped)?[:\s]*/i, '') };
+  return { result: 'UNKNOWN', reason: t.slice(0, 80) };
+}
+
+const SYM = { PASS: '✅', FAIL: '❌', SKIPPED: '⏭️', UNKNOWN: '❓' };
+
+// Extract the numeric step index from "step-7-card-1-back.png" → 7.
+function stepIndex(file) {
+  const m = /^step-(\d+)/.exec(file);
+  return m ? Number(m[1]) : Number.POSITIVE_INFINITY;
+}
+
+function readPlatform(runDir, platform) {
+  const dir = join(runDir, platform);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
+  const resultPath = join(dir, 'result.txt');
+  const { result, reason } = parseResult(
+    existsSync(resultPath) ? readFileSync(resultPath, 'utf8') : ''
+  );
+  const steps = readdirSync(dir)
+    .filter((f) => /^step-\d+.*\.png$/.test(f))
+    .sort((a, b) => stepIndex(a) - stepIndex(b) || a.localeCompare(b));
+  let counters = null;
+  const countersPath = join(dir, 'counters.json');
+  if (existsSync(countersPath)) {
+    try {
+      counters = JSON.parse(readFileSync(countersPath, 'utf8'));
+    } catch {
+      /* malformed counters — treated as absent */
+    }
+  }
+  return { platform, result, reason, steps, counters };
+}
+
+export function generateReport(runDir) {
+  if (!existsSync(runDir) || !statSync(runDir).isDirectory()) {
+    throw new Error(`scenario-report: run dir not found: ${runDir}`);
+  }
+  // Discover platforms: known order first, then any extra subdirs present.
+  const present = readdirSync(runDir).filter((n) => {
+    const p = join(runDir, n);
+    return statSync(p).isDirectory() && existsSync(join(p, 'result.txt'));
+  });
+  const ordered = [
+    ...PLATFORM_ORDER.filter((p) => present.includes(p)),
+    ...present.filter((p) => !PLATFORM_ORDER.includes(p)),
+  ];
+  const platforms = ordered.map((p) => readPlatform(runDir, p)).filter(Boolean);
+
+  const scenarioName =
+    basename(join(runDir, '..', '..')) === '.' ? 'scenario' : basename(join(runDir, '..'));
+  const out = [];
+  out.push(`# Scenario report — ${scenarioName}`);
+  out.push('');
+  out.push(`_generated ${new Date().toISOString()} · run: \`${runDir}\`_`);
+  out.push('');
+
+  // ── TL;DR ──────────────────────────────────────────────────────────────
+  out.push('## TL;DR');
+  out.push('');
+  out.push('| Platform | Result | Steps reached | Tooling |');
+  out.push('| --- | --- | --- | --- |');
+  for (const p of platforms) {
+    const detail = p.reason ? ` — ${p.reason}` : '';
+    out.push(
+      `| ${p.platform} | ${SYM[p.result]} ${p.result}${detail} | ${p.steps.length} | ${toolingFor(p.platform)} |`
+    );
+  }
+  out.push('');
+
+  // ── Counter-delta ──────────────────────────────────────────────────────
+  const counterKeys = [
+    ...new Set(platforms.flatMap((p) => (p.counters ? Object.keys(p.counters) : []))),
+  ];
+  out.push('## Counter delta (cross-platform parity)');
+  out.push('');
+  if (counterKeys.length === 0) {
+    out.push(
+      '_No `counters.json` recorded for any platform. Add `<platform>/counters.json` ' +
+        '(e.g. `{"mastered":"+3","remaining":"-3"}`) in the runners to enable the parity check._'
+    );
+  } else {
+    out.push(`| Platform | ${counterKeys.map((k) => `\`${k}\` Δ`).join(' | ')} |`);
+    out.push(`| --- | ${counterKeys.map(() => '---').join(' | ')} |`);
+    for (const p of platforms) {
+      const cells = counterKeys.map((k) =>
+        p.counters && p.counters[k] != null ? p.counters[k] : '—'
+      );
+      out.push(`| ${p.platform} | ${cells.join(' | ')} |`);
+    }
+    out.push('');
+    // Parity verdict: identical non-skipped rows = verified.
+    const nonSkipped = platforms.filter((p) => p.result !== 'SKIPPED' && p.counters);
+    const sigs = new Set(nonSkipped.map((p) => counterKeys.map((k) => p.counters[k]).join('|')));
+    out.push(
+      sigs.size <= 1
+        ? '**Parity: ✅ identical counter deltas across all non-skipped platforms.**'
+        : '**Parity: ❌ counter deltas diverge across platforms — investigate (a divergence needs a DDR or a fix).**'
+    );
+  }
+  out.push('');
+
+  // ── Per-step pivot ─────────────────────────────────────────────────────
+  const allStepIdx = [
+    ...new Set(platforms.flatMap((p) => p.steps.map(stepIndex)).filter(Number.isFinite)),
+  ].sort((a, b) => a - b);
+  out.push('## Per-step screenshots (pivot)');
+  out.push('');
+  if (allStepIdx.length === 0) {
+    out.push('_No `step-*.png` screenshots found in any platform directory._');
+  } else {
+    out.push(`| Platform | ${allStepIdx.map((n) => `Step ${n}`).join(' | ')} |`);
+    out.push(`| --- | ${allStepIdx.map(() => '---').join(' | ')} |`);
+    for (const p of platforms) {
+      const cells = allStepIdx.map((n) => {
+        const file = p.steps.find((f) => stepIndex(f) === n);
+        return file ? `![](${p.platform}/${file})` : '';
+      });
+      out.push(`| ${p.platform} | ${cells.join(' | ')} |`);
+    }
+  }
+  out.push('');
+
+  // ── LLM prose placeholders ─────────────────────────────────────────────
+  out.push('## What surprised us');
+  out.push('');
+  out.push(
+    '<!-- LLM-AUTHORED: replace this line with non-obvious findings — UX divergence, broken expectations, unexpected counter math, mid-run state changes. Delete this comment. -->'
+  );
+  out.push('');
+  out.push('## Recommended follow-ups');
+  out.push('');
+  out.push(
+    '<!-- LLM-AUTHORED: replace this line with a prioritized list of codebase changes that would make this scenario more reliable (missing testIDs, fragile selectors, parity gaps). Delete this comment. -->'
+  );
+  out.push('');
+
+  // ── Collapsed path listing ─────────────────────────────────────────────
+  out.push('<details>');
+  out.push('<summary>All screenshot paths (per platform)</summary>');
+  out.push('');
+  for (const p of platforms) {
+    out.push(`**${p.platform}** (${p.result})`);
+    for (const f of p.steps) out.push(`- \`${p.platform}/${f}\``);
+    out.push('');
+  }
+  out.push('</details>');
+  out.push('');
+
+  return out.join('\n');
+}
+
+// ── CLI entrypoint ───────────────────────────────────────────────────────
+function main(argv) {
+  const args = argv.slice(2);
+  const runDir = args.find((a) => !a.startsWith('--'));
+  if (!runDir) {
+    process.stderr.write('usage: scenario-report <run-dir> [--out <path>]\n');
+    process.exit(2);
+  }
+  const outIdx = args.indexOf('--out');
+  const outPath = outIdx >= 0 ? args[outIdx + 1] : join(runDir, 'report.md');
+  const md = generateReport(runDir);
+  writeFileSync(outPath, md, 'utf8');
+  process.stdout.write(`${outPath}\n`);
+}
+
+// Run as a script (not when imported). `import.meta.main` is Bun; the argv[1]
+// check covers Node.
+const invokedDirectly = import.meta.main || process.argv[1]?.endsWith('scenario-report.mjs');
+if (invokedDirectly) main(process.argv);

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

@@ -64,6 +64,19 @@ else
   [ -z "$OUT" ]     && { echo "screenshot.sh: --out required for single-shot modes" >&2; exit 2; }
 fi
 
+# agent-browser ignores RELATIVE screenshot paths (it writes to its own
+# ~/.agent-browser/tmp instead), which strands the PNG and trips the
+# missing-file guard below. Canonicalize OUT / OUT_DIR to absolute up front so
+# captures land where the caller asked.
+if [ -n "$OUT" ]; then
+  mkdir -p "$(dirname "$OUT")" 2>/dev/null || true
+  OUT="$(cd "$(dirname "$OUT")" 2>/dev/null && pwd)/$(basename "$OUT")"
+fi
+if [ -n "$OUT_DIR" ]; then
+  mkdir -p "$OUT_DIR" 2>/dev/null || true
+  OUT_DIR="$(cd "$OUT_DIR" 2>/dev/null && pwd)"
+fi
+
 # TSX specimens cannot be opened via file:// — the browser would see raw JSX.
 # They must go through the dev-server route (http://localhost:PORT/<rel>),
 # which transpiles via _canvas-shell.html?canvas=<rel>. Phase 19 / DDR-044.
@@ -97,7 +110,11 @@ if [ -z "$URL" ]; then
 
   # URL-encode spaces (rough); leave other chars alone.
   ACTIVE_ENC=$(printf '%s' "$ACTIVE" | sed 's/ /%20/g')
-  URL="http://localhost:${PORT}/${ACTIVE_ENC}"
+  # Canvases mount through the canvas shell. The bare `/<rel>` route 404s when
+  # the canvas-origin sandbox is on (default since phase-9.1); only
+  # `/_canvas-shell.html?canvas=<rel>` renders the canvas (valid in both
+  # split-on and legacy same-origin modes).
+  URL="http://localhost:${PORT}/_canvas-shell.html?canvas=${ACTIVE_ENC}"
 fi
 
 # ---------- selector mapping ----------