@1agh/maude 0.37.0 → 0.38.0

package/apps/studio/bin/_ensure-browser.mjs

@@ -0,0 +1,305 @@
+// _ensure-browser.mjs — resolve (and if needed download) a headless Chromium for
+// screenshots. Prints the resolved browser executable path to stdout.
+//
+// Screenshots (agent-browser preferred, playwright fallback) need a Chrome-family
+// engine. On a fresh desktop machine there's no globally-installed browser, so we
+// provision `chrome-headless-shell` — the ~94 MB headless-ONLY Chrome-for-Testing
+// build (vs ~172 MB full Chrome) — on first need into a machine-global Maude
+// cache, and screenshot.sh points `AGENT_BROWSER_EXECUTABLE_PATH` at it. Verified
+// end-to-end: agent-browser + a headless-shell renders a Maude canvas faithfully.
+//
+// Resolution priority (first hit wins):
+//   1. MAUDE_BROWSER_EXECUTABLE / AGENT_BROWSER_EXECUTABLE_PATH override (if valid)
+//   2. a Maude-cached chrome-headless-shell (previous provision)
+//   3. a Playwright chromium-headless-shell already on disk (~/.cache/ms-playwright)
+//   4. system Google Chrome / Chromium
+//   5. download chrome-headless-shell → cache  (skipped under --no-download)
+//
+// Flags: --no-download (resolve only — for readiness probes, never triggers a
+// 94 MB fetch) · --json · --quiet.
+
+import { execFileSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const NO_DOWNLOAD = args.includes('--no-download');
+const JSON_OUT = args.includes('--json');
+const QUIET = args.includes('--quiet') || JSON_OUT;
+
+const log = (m) => {
+  if (!QUIET) process.stderr.write(`${m}\n`);
+};
+
+const CDN_VERSIONS =
+  'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json';
+
+// The download URL comes from a remote manifest and its bytes are chmod +x'd and
+// executed — pin the scheme + host so a tampered/redirecting manifest can't point
+// us at http:// or a foreign host (defender F2). Chrome-for-Testing artifacts live
+// on storage.googleapis.com; the manifest on googlechromelabs.github.io.
+export const CDN_HOSTS = new Set(['storage.googleapis.com', 'googlechromelabs.github.io']);
+// The CfT version string flows into cache paths and (on Windows) a PowerShell
+// `-Command` string, so validate it before ANY use (defender F3).
+export const CFT_VERSION_RE = /^[0-9]+(?:\.[0-9]+)*$/;
+
+/** True when a resolved download URL is https + an allowlisted CDN host (defender F2). */
+export function isTrustedDownloadUrl(url) {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' && CDN_HOSTS.has(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Machine-global cache (shared across projects) — NOT the per-project .ai/cache. */
+function browsersDir() {
+  return process.env.MAUDE_BROWSERS_DIR || join(homedir(), '.maude', 'browsers');
+}
+
+/** node/bun platform → Chrome-for-Testing platform slug (null = no CfT build). */
+function cftPlatform() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') return a === 'arm64' ? 'mac-arm64' : 'mac-x64';
+  if (p === 'win32') return a === 'arm64' ? null : 'win64';
+  if (p === 'linux') return a === 'arm64' ? null : 'linux64'; // CfT ships no linux-arm64
+  return null;
+}
+
+/** The headless-shell executable's basename for this platform. */
+function shellExeName() {
+  return process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+}
+
+function isRunnable(p) {
+  try {
+    return !!p && existsSync(p) && statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Recursively find the first `chrome-headless-shell[.exe]` under dir. */
+function findShell(dir) {
+  if (!existsSync(dir)) return null;
+  const want = shellExeName();
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = join(cur, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.name === want && isRunnable(full)) return full;
+    }
+  }
+  return null;
+}
+
+/** (2) A previously-provisioned headless-shell in the Maude cache. */
+function cachedShell() {
+  return findShell(browsersDir());
+}
+
+/** (3) A Playwright chromium-headless-shell already installed. */
+function playwrightShell() {
+  const roots = [
+    process.env.PLAYWRIGHT_BROWSERS_PATH,
+    join(homedir(), 'Library', 'Caches', 'ms-playwright'), // macOS
+    join(homedir(), '.cache', 'ms-playwright'), // linux
+    join(process.env.LOCALAPPDATA || '', 'ms-playwright'), // windows
+  ].filter(Boolean);
+  for (const r of roots) {
+    const hit = findShell(r);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** (4) System Chrome / Chromium — a full browser is fine for headless capture. */
+function systemChrome() {
+  const candidates =
+    process.platform === 'darwin'
+      ? [
+          '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+          '/Applications/Chromium.app/Contents/MacOS/Chromium',
+          '/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        ]
+      : process.platform === 'win32'
+        ? [
+            join(
+              process.env.PROGRAMFILES || 'C:/Program Files',
+              'Google/Chrome/Application/chrome.exe'
+            ),
+            join(
+              process.env['PROGRAMFILES(X86)'] || 'C:/Program Files (x86)',
+              'Google/Chrome/Application/chrome.exe'
+            ),
+          ]
+        : [];
+  for (const c of candidates) if (isRunnable(c)) return c;
+  // PATH lookup (linux `google-chrome` / `chromium`, or any platform).
+  for (const bin of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']) {
+    try {
+      const p = execFileSync(process.platform === 'win32' ? 'where' : 'command', ['-v', bin], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+        .split('\n')[0]
+        .trim();
+      if (isRunnable(p)) return p;
+    } catch {
+      /* not on PATH */
+    }
+  }
+  return null;
+}
+
+function unzip(zipPath, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  // Prefer `unzip` (macOS/Linux); fall back to bsdtar (`tar -xf` handles zip on
+  // macOS + Windows 10+), then PowerShell on Windows.
+  const attempts =
+    process.platform === 'win32'
+      ? [
+          ['tar', ['-xf', zipPath, '-C', destDir]],
+          [
+            'powershell',
+            [
+              '-NoProfile',
+              '-Command',
+              `Expand-Archive -Force -Path '${zipPath}' -DestinationPath '${destDir}'`,
+            ],
+          ],
+        ]
+      : [
+          ['unzip', ['-q', '-o', zipPath, '-d', destDir]],
+          ['tar', ['-xf', zipPath, '-C', destDir]],
+        ];
+  let lastErr;
+  for (const [cmd, a] of attempts) {
+    try {
+      execFileSync(cmd, a, { stdio: 'ignore' });
+      return;
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw new Error(`unzip failed (${lastErr?.message ?? 'no extractor'})`);
+}
+
+/** (5) Download chrome-headless-shell for this platform into the Maude cache. */
+async function downloadShell() {
+  const plat = cftPlatform();
+  if (!plat) {
+    log(`ensure-browser: no Chrome-for-Testing build for ${process.platform}/${process.arch}`);
+    return null;
+  }
+  log('ensure-browser: no browser found — downloading chrome-headless-shell (~94 MB, one-time)…');
+  const versions = await fetch(CDN_VERSIONS).then((r) => r.json());
+  const stable = versions.channels?.Stable;
+  const version = stable?.version;
+  // F3 — reject a suspicious version before it reaches a path or a shell string.
+  if (typeof version !== 'string' || !CFT_VERSION_RE.test(version)) {
+    log(`ensure-browser: refusing malformed Chrome-for-Testing version ${JSON.stringify(version)}`);
+    return null;
+  }
+  const url = (stable?.downloads?.['chrome-headless-shell'] || []).find(
+    (d) => d.platform === plat
+  )?.url;
+  if (!url) {
+    log(`ensure-browser: CDN has no chrome-headless-shell for ${plat}`);
+    return null;
+  }
+  // F2 — the resolved URL is remote-controlled + its bytes get executed. Pin
+  // https + an allowlisted host so a tampered manifest/redirect can't land a
+  // foreign or plaintext-fetched binary. (CDN-of-record compromise is the
+  // accepted residual — same trust anchor Playwright/Puppeteer rely on.)
+  if (!isTrustedDownloadUrl(url)) {
+    log(`ensure-browser: refusing non-allowlisted download URL ${url}`);
+    return null;
+  }
+  // F3 — the cache is exec-forever, so keep it 0700 (only this user can plant a
+  // binary that later runs as the screenshot engine). Created before the download.
+  mkdirSync(browsersDir(), { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(browsersDir(), 0o700);
+  } catch {
+    /* pre-existing dir owned by another mode — best-effort */
+  }
+  const dest = join(browsersDir(), `chrome-headless-shell-${version}-${plat}`);
+  if (findShell(dest)) return findShell(dest); // concurrent provision won the race
+  const tmp = join(tmpdir(), `maude-hshell-${version}-${plat}.zip`);
+  // F1 — do NOT follow redirects: the host allowlist above validated THIS url, but
+  // a 3xx would bounce us to an unvalidated host. The CfT CDN serves the artifact
+  // directly (200), so redirect:'error' fails safe instead of chasing a redirect.
+  const buf = Buffer.from(await fetch(url, { redirect: 'error' }).then((r) => r.arrayBuffer()));
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(tmp, buf);
+  // Extract to a sibling temp dir, then atomically rename into place.
+  const staging = `${dest}.staging-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  unzip(tmp, staging);
+  rmSync(tmp, { force: true });
+  rmSync(dest, { recursive: true, force: true });
+  renameSync(staging, dest);
+  const exe = findShell(dest);
+  if (exe && process.platform !== 'win32') chmodSync(exe, 0o755);
+  log(`ensure-browser: installed → ${exe}`);
+  return exe;
+}
+
+/**
+ * Resolve a screenshot browser executable. `download:false` resolves an EXISTING
+ * browser only (for readiness probes — never fetches ~94 MB). Exported so the
+ * dev-server readiness probe can resolve in-process without spawning.
+ */
+export async function resolveBrowser({ download = true } = {}) {
+  // (1) explicit override
+  const override =
+    process.env.MAUDE_BROWSER_EXECUTABLE || process.env.AGENT_BROWSER_EXECUTABLE_PATH;
+  if (isRunnable(override)) return { path: override, source: 'override' };
+  // (2) Maude cache
+  const cached = cachedShell();
+  if (cached) return { path: cached, source: 'cache' };
+  // (3) Playwright headless-shell
+  const pw = playwrightShell();
+  if (pw) return { path: pw, source: 'playwright' };
+  // (4) system Chrome
+  const sys = systemChrome();
+  if (sys) return { path: sys, source: 'system' };
+  // (5) download (unless probing)
+  if (!download) return { path: null, source: 'none' };
+  const dl = await downloadShell();
+  return { path: dl, source: dl ? 'downloaded' : 'none' };
+}
+
+// CLI entry — only when invoked directly (not when imported by readiness.ts).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = await resolveBrowser({ download: !NO_DOWNLOAD });
+  if (JSON_OUT) {
+    process.stdout.write(
+      `${JSON.stringify({ ...result, name: result.path ? basename(result.path) : null })}\n`
+    );
+  } else if (result.path) {
+    process.stdout.write(`${result.path}\n`);
+  }
+  process.exit(result.path ? 0 : 1);
+}

package/apps/studio/bin/ensure-browser.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# ensure-browser.sh — resolve (and if needed download) a headless Chromium for
+# screenshots; prints the browser executable path to stdout. Reached via
+# `maude design ensure-browser` (DDR-062), never a raw bin path.
+#
+# Usage:
+#   ensure-browser.sh [--no-download] [--json] [--quiet]
+#
+# --no-download resolves an already-present browser only (never fetches ~94 MB) —
+# use it from readiness probes. Default may download chrome-headless-shell into
+# the Maude browsers cache (~/.maude/browsers, override MAUDE_BROWSERS_DIR).
+# Exit 0 with the path on stdout when a browser is available; exit 1 otherwise.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,12p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if command -v node >/dev/null 2>&1; then
+  exec node "$SCRIPT_DIR/_ensure-browser.mjs" "$@"
+elif command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT_DIR/_ensure-browser.mjs" "$@"
+else
+  echo "ensure-browser.sh: node or bun is required to resolve/download the screenshot browser." >&2
+  exit 1
+fi

package/apps/studio/bin/screenshot.sh

@@ -126,13 +126,38 @@ case "$MODE" in
 esac
 
 # ---------- engine resolution ----------
+# Prefer the bundled agent-browser the desktop sidecar pins via MAUDE_AGENT_BROWSER
+# (DDR-144 attacker-F4: an explicit single-binary pointer, NOT a PATH prepend that
+# would let a same-user attacker shadow node/chrome in the app dir), else the one
+# on PATH.
+AB="${MAUDE_AGENT_BROWSER:-agent-browser}"
 if [ "$ENGINE" = "auto" ]; then
-  if command -v agent-browser >/dev/null 2>&1; then
+  if command -v "$AB" >/dev/null 2>&1; then
     ENGINE="agent-browser"
   else
     ENGINE="playwright"
   fi
 fi
+
+# ---------- browser resolution for agent-browser (DDR — bundled screenshots) ----------
+# agent-browser needs a Chrome-family engine. On a fresh desktop machine there's
+# no system Chrome, so resolve (or, on the desktop path only, one-time download)
+# `chrome-headless-shell` and point agent-browser at it via
+# AGENT_BROWSER_EXECUTABLE_PATH. Honor a caller-set value; leave the web/CLI path
+# untouched (--no-download → resolve an EXISTING browser only, never a surprise
+# ~94 MB fetch; agent-browser keeps its own system-Chrome default if nothing's
+# found). The desktop bundle sets MAUDE_DEV_SERVER_ROOT (sidecar.rs) — the signal
+# that a one-time provisioning download is wanted for the zero-install experience.
+if [ "$ENGINE" = "agent-browser" ] && [ -z "$AGENT_BROWSER_EXECUTABLE_PATH" ]; then
+  ES_DIR="$(cd "$(dirname "$0")" && pwd)"
+  ES_FLAGS="--quiet"
+  [ -z "$MAUDE_DEV_SERVER_ROOT" ] && ES_FLAGS="--quiet --no-download"
+  BROWSER_PATH="$(bash "$ES_DIR/ensure-browser.sh" $ES_FLAGS 2>/dev/null)"
+  if [ -n "$BROWSER_PATH" ] && [ -x "$BROWSER_PATH" ]; then
+    export AGENT_BROWSER_EXECUTABLE_PATH="$BROWSER_PATH"
+    echo "→ agent-browser browser: $BROWSER_PATH" >&2
+  fi
+fi
 echo "→ screenshot engine: $ENGINE | url: $URL" >&2
 
 # ---------- engine: agent-browser ----------
@@ -140,9 +165,9 @@ ab_screenshot() {
   local css="$1"
   local out="$2"
   if [ -n "$css" ]; then
-    agent-browser screenshot "$css" "$out" >&2 || return 1
+    "$AB" screenshot "$css" "$out" >&2 || return 1
   else
-    agent-browser screenshot --full "$out" >&2 || return 1
+    "$AB" screenshot --full "$out" >&2 || return 1
   fi
   # agent-browser sometimes reports success without writing — verify size.
   if [ ! -s "$out" ]; then
@@ -175,7 +200,7 @@ pw_screenshot() {
 
 navigate_once() {
   if [ "$ENGINE" = "agent-browser" ]; then
-    agent-browser open "$URL" >&2
+    "$AB" 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.
@@ -185,7 +210,7 @@ navigate_once() {
       sleep 1
       poll=$((poll + 1))
       local raw
-      raw=$(agent-browser eval "document.querySelectorAll('[data-dc-screen],[data-dc-slot]').length" 2>/dev/null)
+      raw=$("$AB" 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
@@ -270,7 +295,7 @@ if [ $ALL_SCREENS -eq 1 ]; then
   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 \
+    raw=$("$AB" 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.
@@ -281,7 +306,7 @@ if [ $ALL_SCREENS -eq 1 ]; then
   if [ -z "$IDS" ] && relive_url; then
     navigate_once
     if [ "$ENGINE" = "agent-browser" ]; then
-      raw=$(agent-browser eval \
+      raw=$("$AB" 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')
@@ -298,7 +323,7 @@ if [ $ALL_SCREENS -eq 1 ]; then
     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
+      "$AB" eval "document.querySelector('[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]').scrollIntoView({block:'center'})" >/dev/null 2>&1
       sleep 0.6
     fi
     if capture_resilient "[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]" "$OUT_FILE"; then

package/apps/studio/bin/smoke.sh

@@ -12,6 +12,11 @@
 # else the canvas's import graph lost the token CSS and every var()-driven rule
 # is dead — the specimen mounts with content but renders unstyled).
 #
+# Also runs an ADVISORY artboard-isolation lint over ui/ canvases: `@media`
+# width queries + viewport units (vw/vh/*-screen) resolve against the studio
+# canvas stage, not the fixed artboard box, so they reflow the mock when the
+# panel/sidebar/window resizes. Warns only — never fails the exit code.
+#
 # Usage:
 #   smoke.sh [--root <repo>]
 #            [--out-dir <dir>]
@@ -237,6 +242,41 @@ lint_specimen_imports() {
   fi
 }
 
+# Static artboard-isolation lint (advisory). An artboard is a fixed-size design
+# surface, but `@media` width queries + viewport units (vh/vw/vmin/vmax + the
+# dynamic svh/dvh/lvh family, incl. Tailwind's *-screen utilities) resolve
+# against the IFRAME VIEWPORT — i.e. the studio's canvas stage — not the
+# artboard box. So a ui/ mock that uses them reflows when the Assistant panel /
+# sidebar / window resizes, even at a fixed zoom. `container-type` on
+# .dc-artboard-body (canvas-lib ENGINE_CSS) gives an isolated responsive path
+# via @container + cqw/cqh; viewport units still escape by spec. This warns —
+# it never fails the exit code (existing DS canvases legitimately use vw/vh in
+# full-bleed specimens, and the fix is an author rewrite, not a smoke gate).
+# Scopes ui/ canvases + their sibling .css only (preview specimens render
+# standalone, so viewport units there are fine). Sets ISO_WARN.
+ISO_WARN=0
+lint_artboard_isolation() {
+  local f n=0 hits total=0 pat
+  # Length units (vh/vw/…), Tailwind *-screen utilities, raw viewport @media.
+  pat='[0-9.]+(vh|vw|vmin|vmax|dvh|svh|lvh|dvw|svw|lvw)([^a-z]|$)|(min-|max-)?[hw]-screen|@media[[:space:]]*\((min|max)-width'
+  [ -d "$DESIGN_ROOT/ui" ] || { echo "→ artboard-isolation lint: no ui/ dir — skipped" >&2; return; }
+  while IFS= read -r f; do
+    [ -e "$f" ] || continue
+    case "$(basename "$f")" in _*) continue ;; esac
+    hits=$(grep -cnE "$pat" "$f" 2>/dev/null || true)
+    [ "${hits:-0}" -gt 0 ] || continue
+    n=$((n + 1)); total=$((total + hits))
+    printf 'ISO-WARN   %s — %s viewport-escape(s) (@media/vw/vh/*-screen leak to the studio stage)\n' "${f#$DESIGN_ROOT/}" "$hits" >&2
+    printf '| ⚠ ISO | `%s` | — | %s viewport-escape(s) — use %%%%/px or @container+cqw |\n' "${f#$DESIGN_ROOT/}" "$hits" >> "$MD"
+  done < <(find "$DESIGN_ROOT/ui" -type f \( -name '*.tsx' -o -name '*.css' \) 2>/dev/null | sort)
+  ISO_WARN=$n
+  if [ "$n" -eq 0 ]; then
+    echo "→ artboard-isolation lint: clean" >&2
+  else
+    echo "⚠ artboard-isolation lint: $n file(s), $total viewport-escape(s) — advisory, see report" >&2
+  fi
+}
+
 # Probe a canvas via agent-browser. Returns three lines on stdout:
 #   <status>   one of OK / BLANK / ERROR
 #   <detail>   short summary string
@@ -371,6 +411,8 @@ printf 'status\tfile\tscreenshot\tdetail\n' > "$TSV"
 if [ "$INCLUDE_SYSTEM" = "1" ] && [ -d "$DESIGN_ROOT/system" ]; then
   lint_specimen_imports
 fi
+# Artboard-isolation lint always runs (ui/ canvases are always in scope). Advisory.
+lint_artboard_isolation
 
 FAILED=0
 N=0
@@ -435,6 +477,10 @@ TOTAL_FAIL=$((FAILED + LINT_FAILED))
   else
     echo "**Result:** ✗ $FAILED / $COUNT canvases failed render/style; $LINT_FAILED import-graph lint violation(s)."
   fi
+  if [ "${ISO_WARN:-0}" -gt 0 ]; then
+    echo
+    echo "> ⚠ **Artboard isolation:** $ISO_WARN ui/ file(s) use viewport-escaping CSS (\`@media\`/\`vw\`/\`vh\`/\`*-screen\`) that reflows with the studio chrome. Advisory — not a failure. Replace with fixed px / \`%\` / \`@container\`+\`cqw\`."
+  fi
 } >> "$MD"
 
 echo "→ report: $MD" >&2