@1agh/maude 0.58.3 → 0.59.0

package/apps/studio/bin/_perf-shared.mjs

@@ -0,0 +1,345 @@
+// _perf-shared.mjs — the measurement contract shared by every `maude design perf`
+// engine lane (Chromium via agent-browser, WebKit via safaridriver).
+//
+// It lives in one file on purpose. Two lanes with two copies of the gesture
+// script would drift, and the moment they drift the engines stop being
+// comparable — which is the only thing this benchmark is for.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+// ── The in-page harness ──────────────────────────────────────────────────────
+//
+// Synthesizes the same wheel events the viewport controller listens for
+// (`canvas-lib.tsx` onWheel: plain wheel = 2D pan, ctrlKey wheel = pinch-zoom —
+// a macOS trackpad pinch arrives as ctrlKey:true, so this is the real gesture
+// path, not a side door).
+//
+// Runs async and parks its result on `window.__maudePerfResult`, which the
+// caller polls: both driver protocols return one synchronous value per eval and
+// cannot await.
+export function harnessSource({ pan, zoom, injectCss, fitAll, setFlags }) {
+  const flagBlock = (setFlags || []).map((f) => `\n  win[${JSON.stringify(f)}] = true;`).join('');
+  const cssBlock = injectCss
+    ? `
+  {
+    const st = doc.createElement('style');
+    st.id = 'maude-perf-variant';
+    st.textContent = ${JSON.stringify(injectCss)};
+    doc.head.appendChild(st);
+  }`
+    : '';
+  return `(() => {
+  const host = document.querySelector('.dc-canvas') ||
+               (document.querySelector('iframe') &&
+                document.querySelector('iframe').contentDocument &&
+                document.querySelector('iframe').contentDocument.querySelector('.dc-canvas'));
+  if (!host) return 'NO_HOST';
+  const doc = host.ownerDocument;
+  const win = doc.defaultView;
+  win.__maudePerfResult = null;${flagBlock}${cssBlock}
+
+  // Render counter, installed by canvas-lib when this object exists. Absent
+  // instrumentation reports null rather than zero — "not measured" and
+  // "measured zero" must never look alike in a baseline.
+  win.__dcPerf = { artboardRenders: 0, annotationRenders: 0 };
+
+  const frames = [];
+  let longtasks = 0;
+  let po = null;
+  try {
+    po = new win.PerformanceObserver((list) => { longtasks += list.getEntries().length; });
+    po.observe({ entryTypes: ['longtask'] });
+  } catch { /* longtask unsupported (WebKit) — count stays 0, frames still tell the story */ }
+
+  let last = 0;
+  let running = true;
+  const tick = (t) => {
+    if (last) frames.push(t - last);
+    last = t;
+    if (running) win.requestAnimationFrame(tick);
+  };
+  win.requestAnimationFrame(tick);
+
+  const rect = host.getBoundingClientRect();
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+
+  const wheel = (dx, dy, ctrl) => host.dispatchEvent(new win.WheelEvent('wheel', {
+    deltaX: dx, deltaY: dy, ctrlKey: !!ctrl,
+    clientX: cx, clientY: cy, bubbles: true, cancelable: true,
+  }));
+
+  const nextFrame = () => new Promise((r) => win.requestAnimationFrame(() => r()));
+
+  // The world transform is the ground truth that the gesture LANDED. Without
+  // this check a probe whose synthetic events get swallowed reports a beautiful
+  // 60fps idle page as a baseline — the exact way a benchmark lies.
+  const world = doc.querySelector('.dc-world');
+  const transformOf = () => (world ? win.getComputedStyle(world).transform + '|' + (world.style.zoom || '') : '');
+
+  (async () => {
+    // Warm-up: one frame so the first measured delta isn't the install cost.
+    await nextFrame();
+
+    // FIT-ALL first when asked. This is the state the moodboard RCA identified
+    // as the painful one and the state a probe most easily misses: at the
+    // canvas's stored viewport only a handful of boards are on screen, so
+    // content-visibility culls the rest and the measurement flatters the
+    // engine. Zoomed out to the whole plane nothing culls, every board paints,
+    // and that is where the user says it stops being usable. Cmd+0 is the
+    // canvas's own fit shortcut (canvas-lib keydown, case 0).
+    // NB: no backticks in this comment — it lives inside a template literal.
+    if (${fitAll ? 'true' : 'false'}) {
+      doc.dispatchEvent(new win.KeyboardEvent('keydown', {
+        key: '0', code: 'Digit0', metaKey: true, bubbles: true, cancelable: true,
+      }));
+      host.dispatchEvent(new win.KeyboardEvent('keydown', {
+        key: '0', code: 'Digit0', metaKey: true, bubbles: true, cancelable: true,
+      }));
+      // Let the fit animation finish before the measured gesture starts.
+      await new Promise((r) => win.setTimeout(r, 800));
+    }
+    // Baseline for the did-it-move check is taken HERE, after any fit, not at
+    // harness install. Repeated passes are deterministic: pass N ends exactly
+    // where "fit + the same pan" lands, so an install-time baseline compares two
+    // identical states and rejects a gesture that ran perfectly.
+    const t0 = transformOf();
+    const panStart = frames.length;
+    for (let i = 0; i < ${pan}; i++) { wheel(-12, -9, false); await nextFrame(); }
+    const panEnd = frames.length;
+    const tPan = transformOf();
+
+    // Zoom: alternate in/out so the run neither drifts to the zoom clamp nor
+    // ends somewhere a follow-up run would start from differently.
+    // Zoom IN first, then back out — symmetric (net scale change ~0) but it
+    // starts in the direction that always has headroom. Starting outward dies
+    // at fit-all, where the viewport already sits on ZOOM_MIN: the clamp makes
+    // the first half a no-op, the transform never moves, and the validity gate
+    // correctly rejects the whole run.
+    // Sampled at the TURNAROUND, not at the end: the run is symmetric, so its
+    // endpoint transform equals its start. Comparing endpoints would report
+    // "zoom never happened" for a zoom that happened twice.
+    let tZoomMid = '';
+    for (let i = 0; i < ${zoom}; i++) {
+      wheel(0, i < ${zoom} / 2 ? -8 : 8, true);
+      await nextFrame();
+      if (i === Math.floor(${zoom} / 2) - 1) tZoomMid = transformOf();
+    }
+    const zoomEnd = frames.length;
+    const tZoom = tZoomMid;
+
+    // Settle window — the tail spike after the gesture is its own symptom
+    // ("seká po dojezdu"), so it is measured separately, not averaged away.
+    const settleStart = frames.length;
+    await new Promise((r) => win.setTimeout(r, 900));
+    running = false;
+    if (po) { try { po.disconnect(); } catch {} }
+
+    const slice = (a, b) => frames.slice(a, b).filter((n) => n > 0);
+    const pct = (arr, p) => {
+      if (!arr.length) return null;
+      const s = arr.slice().sort((a, b) => a - b);
+      return Math.round(s[Math.min(s.length - 1, Math.floor(s.length * p))] * 100) / 100;
+    };
+    const stat = (arr) => ({
+      frames: arr.length,
+      p50: pct(arr, 0.5),
+      p95: pct(arr, 0.95),
+      max: arr.length ? Math.round(Math.max(...arr) * 100) / 100 : null,
+    });
+
+    const gestureFrames = slice(panStart, zoomEnd);
+    win.__maudePerfResult = {
+      pan: stat(slice(panStart, panEnd)),
+      zoom: stat(slice(panEnd, zoomEnd)),
+      gesture: stat(gestureFrames),
+      settle: stat(slice(settleStart, frames.length)),
+      longtasks,
+      artboardRenders: win.__dcPerf ? win.__dcPerf.artboardRenders : null,
+      annotationRenders: win.__dcPerf ? win.__dcPerf.annotationRenders : null,
+      instrumented: !!(win.__dcPerf && win.__dcPerf.instrumented),
+      panApplied: tPan !== t0,
+      zoomApplied: tZoom !== tPan,
+    };
+  })();
+  return 'STARTED';
+})()`;
+}
+
+/**
+ * Shape check behind `parseAndValidateResult` — validates a harness result
+ * before ANY of it is printed or recorded.
+ *
+ * The harness parks its result on `window.__maudePerfResult` — a global inside
+ * the canvas origin, which DDR-054 treats as untrusted. A canvas from a cloned
+ * repo can define that global itself, ahead of our IIFE, and hand back whatever
+ * shape it likes. The numbers would be laundered downstream by Math.round, but
+ * the per-pass progress line and the refusal message print fields verbatim, so
+ * without this gate a hostile canvas gets attacker-authored text into the
+ * invoking agent's transcript wearing a first-party tool's voice.
+ *
+ * Returns the value only when every leaf is the primitive it claims to be.
+ */
+export function parseAndValidateResult(raw) {
+  let decoded;
+  try {
+    decoded = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    // The PARSE is part of the trust boundary, not a step before it. A canvas
+    // owns its window and can replace JSON.stringify, so `raw` is arbitrary
+    // text — and a JSON.parse SyntaxError quotes a snippet of its input, which
+    // would carry attacker-authored text into the invoking agent's transcript
+    // through the generic error handler.
+    return null;
+  }
+  return validateResult(decoded);
+}
+
+function validateResult(r) {
+  const num = (v) => v === null || (typeof v === 'number' && Number.isFinite(v));
+  const stat = (o) => o && typeof o === 'object' && num(o.p50) && num(o.p95) && num(o.max);
+  if (!r || typeof r !== 'object') return null;
+  if (!stat(r.gesture) || !stat(r.pan) || !stat(r.zoom) || !stat(r.settle)) return null;
+  if (!num(r.longtasks) || !num(r.artboardRenders) || !num(r.annotationRenders)) return null;
+  if (typeof r.panApplied !== 'boolean' || typeof r.zoomApplied !== 'boolean') return null;
+  if (typeof r.instrumented !== 'boolean') return null;
+  return r;
+}
+
+/** Median across kept passes — robust to the one pass that hit a GC. */
+export function medianOf(passes) {
+  const med = (pick) => {
+    const vals = passes.map(pick).filter((v) => v != null);
+    if (!vals.length) return null;
+    const s = vals.slice().sort((a, b) => a - b);
+    return Math.round(s[Math.floor(s.length / 2)] * 100) / 100;
+  };
+  return {
+    pan: { p95: med((p) => p.pan.p95) },
+    zoom: { p95: med((p) => p.zoom.p95) },
+    gesture: {
+      p50: med((p) => p.gesture.p50),
+      p95: med((p) => p.gesture.p95),
+      max: med((p) => p.gesture.max),
+    },
+    settle: { max: med((p) => p.settle.max) },
+    longtasks: med((p) => p.longtasks),
+    artboardRenders: med((p) => p.artboardRenders),
+    annotationRenders: med((p) => p.annotationRenders),
+    instrumented: passes.some((p) => p.instrumented),
+    passes: passes.length,
+    // The spread across kept passes IS a result: a delta smaller than this is
+    // noise, and the report says so rather than leaving the reader to guess.
+    p95Spread:
+      passes.length > 1
+        ? Math.round(
+            (Math.max(...passes.map((p) => p.gesture.p95)) -
+              Math.min(...passes.map((p) => p.gesture.p95))) *
+              100
+          ) / 100
+        : null,
+  };
+}
+
+export function buildRow({ result, label, engineTag, opts }) {
+  return {
+    date: new Date().toISOString(),
+    canvas: label,
+    engine: engineTag,
+    url: opts.url,
+    panFrames: opts.pan,
+    zoomFrames: opts.zoom,
+    p50FrameMs: result.gesture.p50,
+    p95FrameMs: result.gesture.p95,
+    maxFrameMs: result.gesture.max,
+    panP95Ms: result.pan.p95,
+    zoomP95Ms: result.zoom.p95,
+    settleMaxMs: result.settle.max,
+    longtasks: result.longtasks,
+    artboardRenders: result.artboardRenders,
+    annotationRenders: result.annotationRenders,
+    instrumented: result.instrumented,
+    passes: result.passes,
+    p95SpreadMs: result.p95Spread,
+  };
+}
+
+/** Delta vs the previous run of the same (canvas, engine) pair. */
+export function deltaLine(label, cur, prev, unit = 'ms') {
+  if (cur == null) return `  ${label.padEnd(22)} —`;
+  if (prev == null) return `  ${label.padEnd(22)} ${cur}${unit}   (no prior run)`;
+  const d = Math.round((cur - prev) * 100) / 100;
+  const pctChange = prev === 0 ? null : Math.round((d / prev) * 1000) / 10;
+  const arrow = d === 0 ? '=' : d < 0 ? '▼' : '▲';
+  const pctTxt = pctChange == null ? '' : ` ${pctChange > 0 ? '+' : ''}${pctChange}%`;
+  return `  ${label.padEnd(22)} ${cur}${unit}   ${arrow} ${d > 0 ? '+' : ''}${d}${unit}${pctTxt}  (was ${prev}${unit})`;
+}
+
+export function readHistory(path, label, engineTag) {
+  if (!path || !existsSync(path)) return null;
+  let prev = null;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.canvas === label && row.engine === engineTag) prev = row;
+    } catch {
+      /* a corrupt line must not sink the run — history is a convenience, not a source of truth */
+    }
+  }
+  return prev;
+}
+
+/**
+ * One-line, control-character-free rendering of a caller-supplied string.
+ * A canvas filename comes from the repo and POSIX allows newlines in it, so
+ * echoing one raw lets a hostile repo inject its own line into a report an
+ * agent reads.
+ */
+function safeLabel(v) {
+  let out = '';
+  for (const ch of String(v).slice(0, 200)) {
+    const code = ch.codePointAt(0);
+    const unsafe =
+      code < 0x20 || // C0 — newline and friends: the line-injection case
+      code === 0x7f || // DEL
+      (code >= 0x80 && code <= 0x9f) || // C1 — some terminals still act on these
+      (code >= 0x202a && code <= 0x202e) || // bidi embedding / override
+      (code >= 0x2066 && code <= 0x2069); // bidi isolates
+    // Bidi controls can't break a line, but they can visually reorder one, so a
+    // filename could make a report read differently than it is.
+    out += unsafe ? ' ' : ch;
+  }
+  return out;
+}
+
+export function renderReport({ row, prev, opts, label, engineTag }) {
+  const out = [];
+  out.push(`\n  canvas: ${safeLabel(label)}    engine: ${safeLabel(engineTag)}`);
+  out.push(`  gesture: ${opts.pan} pan frames + ${opts.zoom} zoom frames\n`);
+  out.push(deltaLine('frame p50', row.p50FrameMs, prev?.p50FrameMs));
+  out.push(deltaLine('frame p95', row.p95FrameMs, prev?.p95FrameMs));
+  out.push(deltaLine('frame max', row.maxFrameMs, prev?.maxFrameMs));
+  out.push(deltaLine('pan p95', row.panP95Ms, prev?.panP95Ms));
+  out.push(deltaLine('zoom p95', row.zoomP95Ms, prev?.zoomP95Ms));
+  out.push(deltaLine('settle max', row.settleMaxMs, prev?.settleMaxMs));
+  out.push(deltaLine('long tasks', row.longtasks, prev?.longtasks, ''));
+  out.push(deltaLine('artboard renders', row.artboardRenders, prev?.artboardRenders, ''));
+  out.push(deltaLine('annotation renders', row.annotationRenders, prev?.annotationRenders, ''));
+  if (!row.instrumented) {
+    out.push(
+      '\n  note: render counters are not instrumented in this build — frame timings are still valid.'
+    );
+  }
+  if (row.p95SpreadMs != null) {
+    out.push(
+      `\n  p95 spread across ${row.passes} kept passes: ${row.p95SpreadMs}ms ` +
+        '— treat any delta smaller than this as noise.'
+    );
+  }
+  if (opts.history) out.push(`\n  history: ${opts.history}`);
+  out.push(
+    `  ${prev ? 'compared against the previous run' : 'first run — this IS the baseline'}\n`
+  );
+  return out.join('\n');
+}

package/apps/studio/bin/_video-playwright.mjs

@@ -47,6 +47,7 @@ const {
   out, // encoded file destination
   mode = 'comp', // 'comp' | 'ordinary'
   audio, // '1' | '0' — include audio in the render-lib path (default on; presence-checked below)
+  'frame-format': frameFormatArg, // 'jpeg' | 'png' (default) — the frame-step screenshot intermediate, Task 9
   'license-key': licenseKeyArg,
   timeout = '60',
   scale = '1',
@@ -67,6 +68,8 @@ const deviceScaleFactor = Math.max(1, Math.min(4, Number(scale) || 1));
 // always passes an explicit '0'/'1'.
 const wantAudio = audio !== '0';
 const licenseKey = licenseKeyArg || 'free-license';
+// Task 9 — opt-in JPEG frame-step intermediate; unrecognized/absent value is PNG.
+const frameFormat = frameFormatArg === 'jpeg' ? 'jpeg' : 'png';
 
 /** Wait a real turn of the event loop + a frame so a seek settles before shot. */
 const SETTLE_MS = 16;
@@ -267,6 +270,7 @@ try {
         mode,
         deviceScaleFactor,
         timeoutMs,
+        frameFormat,
         fallbackReason: renderFallbackReason,
       });
     } catch (fallbackErr) {
@@ -308,6 +312,10 @@ async function frameStepCapture({
   mode,
   deviceScaleFactor,
   timeoutMs,
+  // Task 9 — 'jpeg' | 'png' (default). Only ever affects the encode transport,
+  // never a --dump-frames debug dump (that always stays lossless PNG) and
+  // never gif (video.ts refuses to pass 'jpeg' through for gif).
+  frameFormat = 'png',
   // Set (to the renderer's error message) only when this run is the
   // graceful-degradation fallback for a failed renderMediaOnWeb path; stamps
   // `degraded`/`audioDropped` onto the stdout summary so video.ts can warn.
@@ -438,6 +446,11 @@ async function frameStepCapture({
   // Per-stage accumulators. "The export takes 15 minutes" was, for a long time,
   // answerable only by guessing which stage owned the second — so every
   // optimization was aimed at a suspicion. One line at the end fixes that.
+  // Task 9 — a debug dump must stay lossless (it's for human inspection), and
+  // gif never gets a lossy intermediate stacked under its own quantization —
+  // so the knob only actually applies to a plain video encode.
+  const useJpeg = frameFormat === 'jpeg' && !isGif && !dump;
+  const shotFormat = useJpeg ? 'jpeg' : 'png';
   const stageMs = { seek: 0, settle: 0, screenshot: 0, encode: 0 };
   for (let f = 0; f < frameCount; f += 1) {
     const tSeek = Date.now();
@@ -447,7 +460,7 @@ async function frameStepCapture({
     await page.waitForTimeout(SETTLE_MS);
     stageMs.settle += Date.now() - tSettle;
     const tShot = Date.now();
-    const shot = await page.screenshot({ clip });
+    const shot = await page.screenshot(useJpeg ? { clip, type: 'jpeg', quality: 90 } : { clip });
     stageMs.screenshot += Date.now() - tShot;
     if (dump) {
       const p = join(dump, `frame-${String(f).padStart(5, '0')}.png`);
@@ -458,11 +471,11 @@ async function frameStepCapture({
       const tEnc = Date.now();
       const b64 = shot.toString('base64');
       await page.evaluate(
-        async ({ b64, isGif }) => {
+        async ({ b64, isGif, format }) => {
           if (isGif) return window.__maudeEnc.addGifFrame(b64);
-          return window.__maudeEnc.addVideoFrame(b64);
+          return window.__maudeEnc.addVideoFrame(b64, format);
         },
-        { b64, isGif }
+        { b64, isGif, format: shotFormat }
       );
       // NB: this stage is the double CDP crossing — the screenshot bytes go out
       // to node as base64 and straight back into the same page, to an encoder

package/apps/studio/bin/import-figma.sh

@@ -15,18 +15,27 @@
 # Usage:
 #   import-figma.sh --board  <figjam-url> --root <repo> [--design-root .design]
 #                   [--slug <name>] [--dry-run] [--json]
+#   import-figma.sh --pages  <figma-url>  --root <repo> [--folder <name>] [--editable]
 #   import-figma.sh --frames <figma-url>  --root <repo>   (Phase 3)
 #   import-figma.sh --tokens <figma-url>  --root <repo>   (Phase 4)
+#   import-figma.sh --explode <artboard-id> --canvas <rel-path> --root <repo>
+#                   [--confirm-document] [--dry-run] [--json]      (Phase 7)
 #
 # Needs a Figma personal access token with the `file_content:read` scope, added
 # once in Settings.
 #
+# `--explode` needs NO token — it reads the Figma DESKTOP app's local Dev Mode
+# MCP server over loopback (DDR-219 D2) rather than the REST API. It does need
+# that app running, in Dev Mode, with the same file as the active tab, on a Dev
+# or Full seat. It is not an import route: the artboard must already exist on an
+# imported canvas.
+#
 # Exit: 0 ok · 1 other · 2 usage · 3 validation reject · 4 fetch/parse error ·
 #       5 no token configured · 6 write/containment error.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 case "$1" in
-  --help|-h) sed -n '2,25p' "$0" | sed 's/^# \?//'; exit 0 ;;
+  --help|-h) sed -n '2,34p' "$0" | sed 's/^# \?//'; exit 0 ;;
 esac
 
 if ! command -v bun >/dev/null 2>&1; then

package/apps/studio/bin/perf.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# perf.sh — render-performance benchmark for a canvas (`maude design perf`).
+#
+# Drives a scripted pan + zoom against a live canvas and reports frame-time
+# percentiles, long-task count and the React render count during the gesture,
+# with a DELTA against the previous run of the same (canvas, engine) pair. The
+# history file makes "before and after" a property of the tool rather than
+# something the operator has to remember to write down.
+#
+# Deliberately NOT a CI gate. Headless frame timings swing with GPU load and
+# machine state, so an absolute threshold would go red for reasons unrelated to
+# the code and train everyone to ignore it. The gate is the delta, read by a
+# human, on one machine. (Plan: .ai/plans/feature-canvas-render-performance.md)
+#
+# Usage:
+#   perf.sh [--root <repo>] [--canvas <rel-path>] [--fixture]
+#           [--boards N] [--strokes N]
+#           [--pan N] [--zoom N] [--timeout S] [--repeat N]
+#           [--engine chromium|safari]
+#           [--history <path>] [--json]
+#
+#   --engine safari measures WebKit through safaridriver (one-time
+#   `safaridriver --enable`, needs admin auth). Use it for anything the Tauri
+#   desktop shell has to be fast at: the desktop is WKWebView, and Chromium does
+#   NOT reproduce WebKit's compositing / re-raster behaviour — a canvas can sit
+#   at a warm 60fps in headless Chromium while being unusable in the .app.
+#
+#   --canvas   Canvas to measure, relative to <designRoot> (default: _active.json).
+#   --fixture  Generate + measure the synthetic fixture instead (--boards/--strokes).
+#   --json     Raw JSON (current + previous run) instead of the human report.
+#
+# Reads:  $DESIGN_ROOT/_server.json  (must exist — run `maude design server-up` first)
+# Writes: $DESIGN_ROOT/_smoke/perf/history.jsonl   (append-only, per-machine runtime state)
+#         $DESIGN_ROOT/ui/perf-fixture.tsx         (only with --fixture)
+#
+# Exit: 0 measured / 1 missing dep or capture failure / 2 bad args.
+
+REPO=""
+CANVAS=""
+FIXTURE=0
+BOARDS=128
+STROKES=150
+PAN=60
+ZOOM=40
+REPEAT=3
+PROBE_ENGINE="chromium"
+FIT_ALL=0
+STUDIO=0
+TIMEOUT=30
+HISTORY=""
+JSON=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)     REPO="$2"; shift 2 ;;
+    --canvas)   CANVAS="$2"; shift 2 ;;
+    --fixture)  FIXTURE=1; shift ;;
+    --boards)   BOARDS="$2"; shift 2 ;;
+    --strokes)  STROKES="$2"; shift 2 ;;
+    --pan)      PAN="$2"; shift 2 ;;
+    --zoom)     ZOOM="$2"; shift 2 ;;
+    --timeout)  TIMEOUT="$2"; shift 2 ;;
+    --repeat)   REPEAT="$2"; shift 2 ;;
+    --engine)   PROBE_ENGINE="$2"; shift 2 ;;
+    --fit-all)  FIT_ALL=1; shift ;;
+    --studio)   STUDIO=1; shift ;;
+    --history)  HISTORY="$2"; shift 2 ;;
+    --json)     JSON=1; shift ;;
+    --help|-h)
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "perf.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# JS runtime. The packaged desktop app ships no user `node` (DDR-177) but always
+# has a `bun` on PATH (real, or the compiled-sidecar shim `maude` stages), so
+# prefer bun and keep node as the developer-machine fallback.
+if command -v bun >/dev/null 2>&1; then JS_RUNTIME="bun"; else JS_RUNTIME="node"; fi
+
+# ---------- resolve repo + design root (mirrors smoke.sh) ----------
+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 "perf.sh: no .design/ under $REPO" >&2; exit 1; }
+
+STATE="$DESIGN_ROOT/_server.json"
+[ -f "$STATE" ] || { echo "perf.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 "perf.sh: no port in $STATE" >&2; exit 1; }
+
+# ---------- fixture generation ----------
+if [ "$FIXTURE" = "1" ]; then
+  # Counts are validated as plain integers and paths travel via argv, never
+  # interpolated into the script body: `--boards "1); <js>; ("` or a design root
+  # containing a quote would otherwise execute inside this node process, which
+  # runs with the user's full privileges. `maude design perf` is reachable from
+  # an agent session, so its arguments are not automatically trustworthy.
+  case "$BOARDS" in ''|*[!0-9]*) echo "perf.sh: --boards must be a positive integer" >&2; exit 2 ;; esac
+  case "$STROKES" in ''|*[!0-9]*) echo "perf.sh: --strokes must be a non-negative integer" >&2; exit 2 ;; esac
+  # Upper bound too: the guards above accept any magnitude, and `--boards 99999999`
+  # is a cheap way to make an auto-approved verb fill a disk.
+  [ "$BOARDS" -le 2000 ] || { echo "perf.sh: --boards must be <= 2000" >&2; exit 2; }
+  [ "$STROKES" -le 5000 ] || { echo "perf.sh: --strokes must be <= 5000" >&2; exit 2; }
+  "$JS_RUNTIME" -e '
+    const [modPath, designRoot, boards, strokes] = process.argv.slice(1);
+    import(modPath).then((m) => {
+      const r = m.writePerfCanvas({
+        designRoot,
+        boards: Number(boards),
+        strokes: Number(strokes),
+      });
+      console.error("→ fixture written: " + r.canvasPath);
+    }).catch((e) => {
+      console.error("perf.sh: fixture generation failed: " + e.message);
+      process.exit(1);
+    });
+  ' "$SCRIPT_DIR/../test/fixtures/perf-canvas.mjs" "$DESIGN_ROOT" "$BOARDS" "$STROKES" || exit 1
+  CANVAS="ui/perf-fixture.tsx"
+fi
+
+# ---------- resolve canvas ----------
+if [ -z "$CANVAS" ]; then
+  ACTIVE_FILE="$DESIGN_ROOT/_active.json"
+  if [ -f "$ACTIVE_FILE" ] && command -v jq >/dev/null 2>&1; then
+    CANVAS=$(jq -r '.active // empty' "$ACTIVE_FILE" 2>/dev/null)
+  fi
+fi
+[ -n "$CANVAS" ] || { echo "perf.sh: no --canvas and no active canvas in _active.json" >&2; exit 2; }
+
+# `_active.json` stores the path relative to the REPO (".design/ui/x.tsx"); the
+# canvas-shell query param wants it the same way, so normalize either input
+# shape to the repo-relative form rather than guessing at call sites.
+DESIGN_REL="${DESIGN_ROOT#"$REPO"/}"
+case "$CANVAS" in
+  "$DESIGN_REL"/*) REL_FULL="$CANVAS" ;;
+  *)               REL_FULL="$DESIGN_REL/$CANVAS" ;;
+esac
+# Containment: an existence check alone would accept `--canvas ../../../x.tsx`
+# and leave the boundary entirely to the dev-server route. A benchmark has no
+# business probing that gate.
+case "$REL_FULL" in
+  *..*) echo "perf.sh: --canvas must not contain '..'" >&2; exit 2 ;;
+esac
+[ -f "$REPO/$REL_FULL" ] || { echo "perf.sh: canvas not found: $REPO/$REL_FULL" >&2; exit 2; }
+
+# Percent-encode the whole value, not just spaces: a canvas named with `#`, `&`
+# or `%` would otherwise truncate or rewrite the query string.
+REL_ENC=$("$JS_RUNTIME" -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$REL_FULL")
+URL="http://localhost:${PORT}/_canvas-shell.html?canvas=${REL_ENC}"
+
+# ---------- history path ----------
+# `_smoke/` is already IGNORED runtime state (DDR-115), so the benchmark log
+# inherits the right gitignore posture without touching any of the three lists.
+if [ -z "$HISTORY" ]; then
+  HISTORY="$DESIGN_ROOT/_smoke/perf/history.jsonl"
+fi
+# Containment: `perf` is auto-approved in ACP sessions (`Bash(maude:*)`), so an
+# unconstrained --history would be an arbitrary mkdir + append outside every
+# write-scope gate. The default already lives under the design root; require it.
+HISTORY_ABS=$("$JS_RUNTIME" -e 'const p=require("path");process.stdout.write(p.resolve(process.argv[1]))' "$HISTORY")
+DESIGN_ABS=$("$JS_RUNTIME" -e 'const p=require("path");process.stdout.write(p.resolve(process.argv[1]))' "$DESIGN_ROOT")
+case "$HISTORY_ABS" in
+  "$DESIGN_ABS"/*) ;;
+  *) echo "perf.sh: --history must resolve under $DESIGN_ABS (got $HISTORY_ABS)" >&2; exit 2 ;;
+esac
+HISTORY="$HISTORY_ABS"
+mkdir -p "$(dirname "$HISTORY")"
+
+# ---------- engine tag ----------
+# The tag is part of the history KEY, not decoration: a WKWebView number and a
+# headless-Chromium number are not comparable, and silently averaging them would
+# make every delta meaningless.
+ENGINE_TAG="${MAUDE_PERF_ENGINE_TAG:-}"
+if [ -z "$ENGINE_TAG" ]; then
+  if [ -n "$MAUDE_DESKTOP" ]; then ENGINE_TAG="webkit-desktop"; else ENGINE_TAG="blink-headless"; fi
+fi
+
+if [ "$PROBE_ENGINE" = "safari" ]; then
+  command -v safaridriver >/dev/null 2>&1 || {
+    echo "perf.sh: safaridriver not found (macOS only)" >&2
+    exit 1
+  }
+  PROBE_URL="$URL"
+  if [ "$STUDIO" = "1" ]; then
+    # Studio mode drives the real app shell (root URL + a file-tree click),
+    # not the bare canvas page — see _perf-probe-safari.mjs for why that
+    # difference changes the numbers.
+    PROBE_URL="http://localhost:${PORT}/"
+    SLUG=$(printf '%s' "${REL_FULL#"$DESIGN_REL"/}" \
+      | sed -E 's/\.[A-Za-z]+$//' | tr '[:upper:]' '[:lower:]' \
+      | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g')
+  fi
+  echo "→ perf: $REL_FULL | port: $PORT | engine: webkit-safari${STUDIO:+ | studio}" >&2
+  ARGS=(--url "$PROBE_URL" --label "$REL_FULL$([ "$STUDIO" = "1" ] && echo " (studio)")" --history "$HISTORY"
+        --timeout "$TIMEOUT" --pan "$PAN" --zoom "$ZOOM" --repeat "$REPEAT")
+  [ "$STUDIO" = "1" ] && ARGS+=(--studio "$SLUG")
+  [ "$FIT_ALL" = "1" ] && ARGS+=(--fit-all)
+  [ "$JSON" = "1" ] && ARGS+=(--json)
+  exec "$JS_RUNTIME" "$SCRIPT_DIR/_perf-probe-safari.mjs" "${ARGS[@]}"
+fi
+
+AB="${MAUDE_AGENT_BROWSER:-agent-browser}"
+command -v "$AB" >/dev/null 2>&1 || {
+  echo "perf.sh: agent-browser not on PATH (required — the probe needs scripted gestures + rAF timing)" >&2
+  exit 1
+}
+
+echo "→ perf: $REL_FULL | port: $PORT | engine: $ENGINE_TAG" >&2
+
+ARGS=(--url "$URL" --label "$REL_FULL" --history "$HISTORY" --engine-tag "$ENGINE_TAG"
+      --timeout "$TIMEOUT" --pan "$PAN" --zoom "$ZOOM" --repeat "$REPEAT")
+[ "$FIT_ALL" = "1" ] && ARGS+=(--fit-all)
+[ "$JSON" = "1" ] && ARGS+=(--json)
+
+exec "$JS_RUNTIME" "$SCRIPT_DIR/_perf-probe.mjs" "${ARGS[@]}"