@1agh/maude 0.53.0 → 0.53.2

package/apps/studio/bin/_import-asset.mjs

@@ -360,12 +360,7 @@ export function sanitizeSvgAllowlist(svgText) {
   const window = new Window();
   const doc = new window.DOMParser().parseFromString(svgText, 'image/svg+xml');
   const root = doc.documentElement;
-  if (
-    !root ||
-    root.tagName !== 'svg' ||
-    root.namespaceURI !== SVG_NS ||
-    doc.querySelector('parsererror')
-  ) {
+  if (root?.tagName !== 'svg' || root.namespaceURI !== SVG_NS || doc.querySelector('parsererror')) {
     throw new ImportAssetError(3, 'SVG failed to parse');
   }
   walkAllowlist(root);

package/apps/studio/bin/_import-brand.mjs

@@ -355,7 +355,7 @@ export function hardenBrandLogoSvg(sanitizedSvgText) {
   const window = new Window();
   const doc = new window.DOMParser().parseFromString(sanitizedSvgText, 'image/svg+xml');
   const root = doc.documentElement;
-  if (!root || root.tagName !== 'svg' || root.namespaceURI !== SVG_NS) {
+  if (root?.tagName !== 'svg' || root.namespaceURI !== SVG_NS) {
     throw new ImportBrandError(3, 'input is not a valid sanitized SVG document');
   }
 

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

@@ -354,7 +354,11 @@ async function frameStepCapture({
     });
   }
 
-  const dump = dumpDir ? (mkdirSync(dumpDir, { recursive: true }), dumpDir) : null;
+  // A comma operator hid the side effect here; the directory has to exist
+  // before anything writes a frame into it, so the effect is the point and
+  // deserves its own line.
+  if (dumpDir) mkdirSync(dumpDir, { recursive: true });
+  const dump = dumpDir ?? null;
   const framePaths = [];
   const t0 = Date.now();
 

package/apps/studio/bin/screenshot.sh

@@ -6,14 +6,29 @@
 #
 # Usage:
 #   screenshot.sh [--port N | --url URL]
-#                 [--screen <id> | --element <id> | --selector <css> | --full]
+#                 [--screen <id> | --element <id> | --selector <css> | --full | --shell]
 #                 [--all-screens] [--out <path>] [--out-dir <dir>]
 #                 [--timeout 8] [--engine auto|agent-browser|playwright]
-#                 [--theme <name>] [--root <repo>]
+#                 [--theme <name>] [--root <repo>] [--canvas <rel|"">]
 #
 # Notes:
-#   - Exactly one of --screen / --element / --selector / --full is required
-#     (or --all-screens which loops over every [data-dc-screen]/[data-dc-slot]).
+#   - Exactly one of --screen / --element / --selector / --full / --shell is
+#     required (or --all-screens, which loops over every
+#     [data-dc-screen]/[data-dc-slot]).
+#   - --shell captures the STUDIO ITSELF, not a canvas: it points at the server
+#     root (`/`) instead of `_canvas-shell.html`, so Maude's own chrome —
+#     menubar, sidebar, status bar, toasts — is in frame. That chrome is where
+#     most reported UI bugs actually live, and no canvas-scoped capture can ever
+#     show it. Open tabs are `useState([])` in the client (never restored from
+#     `_active.json` or localStorage), so a bare load lands on "Nothing open
+#     yet"; shell mode therefore clicks the active canvas's file-tree row first
+#     to bring the shot back in line with what the user is looking at.
+#   - --canvas says WHICH canvas shell mode opens, overriding `_active.json`.
+#     Passing it EMPTY means "open nothing" — that's not the same as omitting
+#     it. `_active.json` is global and sticky (it outlives every closed tab and
+#     any session can write it), so a caller that knows the truth — the studio
+#     client knows its own open tab — must be able to say "nothing is open"
+#     instead of having a stale path resolved behind its back.
 #   - --out required for single-shot modes; --out-dir required for --all-screens.
 #   - --theme <name> forces every `[data-theme]` element (DS artboard wrappers)
 #     to that value BEFORE capture, via a DOM eval — does not touch the actual
@@ -37,6 +52,11 @@ ENGINE="auto"
 ALL_SCREENS=0
 ROOT=""
 THEME=""
+ACTIVE=""
+# Tri-state for --canvas: unset → resolve from _active.json (the CLI default);
+# set to a path → open that; set to "" → open nothing. The empty case is
+# load-bearing, so it can't collapse into "unset".
+CANVAS_SET=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -44,6 +64,8 @@ while [ $# -gt 0 ]; do
     --element)  MODE="element";  SEL="$2"; shift 2 ;;
     --selector) MODE="selector"; SEL="$2"; shift 2 ;;
     --full)     MODE="full"; shift ;;
+    --shell)    MODE="shell"; shift ;;
+    --canvas)   CANVAS_SET=1; ACTIVE="$2"; shift 2 ;;
     --all-screens) ALL_SCREENS=1; shift ;;
     --url)      URL="$2"; shift 2 ;;
     --port)     PORT="$2"; shift 2 ;;
@@ -82,7 +104,7 @@ fi
 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 "$MODE" ]    && { echo "screenshot.sh: pick one of --full/--shell/--screen/--element/--selector or --all-screens" >&2; exit 2; }
   [ -z "$OUT" ]     && { echo "screenshot.sh: --out required for single-shot modes" >&2; exit 2; }
 fi
 
@@ -125,26 +147,58 @@ if [ -z "$URL" ]; then
   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
+  if [ $CANVAS_SET -eq 0 ] && [ -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')
-  # 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}"
+  # Shell mode targets the studio root, and an active canvas is a NICE-TO-HAVE
+  # (it decides which file-tree row we click) rather than a precondition — a
+  # chrome bug is worth capturing even with nothing open.
+  if [ "$MODE" = "shell" ]; then
+    URL="http://localhost:${PORT}/"
+  else
+    [ -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')
+    # 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
+fi
+
+# Shell mode still wants the active canvas even when the caller passed --url
+# outright (the URL says WHERE to look; the active canvas says WHAT to open).
+if [ "$MODE" = "shell" ] && [ $CANVAS_SET -eq 0 ] && [ -z "$ACTIVE" ]; then
+  SHELL_REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+  if [ -f "$SHELL_REPO/.design/_active.json" ] && command -v jq >/dev/null 2>&1; then
+    ACTIVE=$(jq -r '.active // empty' "$SHELL_REPO/.design/_active.json" 2>/dev/null)
+  fi
 fi
 
+# The file-tree row testid the client stamps (app.jsx `pathTestIdSlug`):
+# designRoot dot-folder stripped, extension stripped, non-alphanumerics folded
+# to single dashes, lowercased, dashes trimmed. Lowercasing happens BEFORE the
+# extension strip so we don't need sed's non-portable `I` flag for `.TSX`.
+# Output is [a-z0-9-] only, which is what makes it safe to splice into the JS
+# selector string eval'd below.
+shell_row_testid() {
+  printf '%s' "$1" \
+    | sed -E 's#^\.[^/]+/##' \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/\.(tsx|html?)$//' \
+    | sed -E 's/[^a-z0-9]+/-/g' \
+    | sed -E 's/^-+//; s/-+$//'
+}
+
 # ---------- 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="" ;;
+  full|shell|"")  CSS_SEL="" ;;
 esac
 
 # ---------- engine resolution ----------
@@ -153,6 +207,15 @@ esac
 # would let a same-user attacker shadow node/chrome in the app dir), else the one
 # on PATH.
 AB="${MAUDE_AGENT_BROWSER:-agent-browser}"
+
+# agent-browser sessions are SHARED by name (default: "default"). Shell mode is
+# fired automatically by the Report-a-Bug dialog, so on the shared session it
+# would navigate whatever browser an agent has mid-task out from under it. Pin
+# it to its own session; the canvas modes keep the shared one deliberately, so
+# an agent's `/design:*` captures stay in the session it is already driving.
+if [ "$MODE" = "shell" ] && [ -z "$AGENT_BROWSER_SESSION" ]; then
+  export AGENT_BROWSER_SESSION="maude-shell-shot"
+fi
 if [ "$ENGINE" = "auto" ]; then
   if command -v "$AB" >/dev/null 2>&1; then
     ENGINE="agent-browser"
@@ -222,9 +285,62 @@ pw_screenshot() {
   return 0
 }
 
+# ---------- shell mode: open the active canvas in the studio ----------
+# The studio root always boots to "Nothing open yet" (tabs are `useState([])`,
+# never rehydrated), so a bare shell shot would show chrome over an empty
+# canvas area. Click the active canvas's file-tree row and wait for the canvas
+# iframe to appear. Every leg is best-effort — chrome is the point of this mode,
+# so a missing row or a slow mount degrades to "chrome, nothing open" rather
+# than failing the capture.
+open_active_in_shell() {
+  [ "$ENGINE" = "agent-browser" ] || return 0
+  [ -n "$ACTIVE" ] || { echo "→ shell: no active canvas — capturing chrome as-is" >&2; return 0; }
+  local slug
+  slug=$(shell_row_testid "$ACTIVE")
+  [ -n "$slug" ] || return 0
+  # The file tree is React-rendered, so the row does not exist at load — poll
+  # for it (a single probe 1 s after navigate reliably misses) and click the
+  # moment it appears.
+  local clicked=""
+  local wait=0
+  while [ $wait -lt "$TIMEOUT" ]; do
+    clicked=$("$AB" eval "(function(){var r=document.querySelector('[data-testid=\"canvas-row-$slug\"]');if(!r)return 'miss';r.click();return 'hit'})()" 2>/dev/null | tr -d '[:space:]"')
+    [ "$clicked" = "hit" ] && break
+    sleep 1
+    wait=$((wait + 1))
+  done
+  if [ "$clicked" != "hit" ]; then
+    echo "→ shell: no file-tree row for '$slug' after ${TIMEOUT}s — capturing chrome as-is" >&2
+    return 0
+  fi
+  # Wait for the canvas iframe to attach; it renders cross-origin, so the parent
+  # can only observe the element, never its contents. A short settle follows so
+  # the iframe has painted before we capture.
+  local poll=0
+  while [ $poll -lt "$TIMEOUT" ]; do
+    sleep 1
+    poll=$((poll + 1))
+    local n
+    n=$("$AB" eval "document.querySelectorAll('iframe').length" 2>/dev/null | tr -d '[:space:]')
+    case "$n" in
+      ''|*[!0-9]*|0) continue ;;
+      *) sleep 2; echo "→ shell: opened '$ACTIVE'" >&2; return 0 ;;
+    esac
+  done
+  echo "→ shell: canvas iframe never attached after ${TIMEOUT}s — capturing chrome as-is" >&2
+}
+
 navigate_once() {
   if [ "$ENGINE" = "agent-browser" ]; then
     "$AB" open "$URL" >&2
+    # Shell mode lands on the studio root, which has no DC mount to poll for —
+    # the canvas arrives only after we click a row.
+    if [ "$MODE" = "shell" ]; then
+      sleep 1
+      open_active_in_shell
+      apply_theme_override
+      return 0
+    fi
     # 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.

package/apps/studio/canvas-build-sandbox.ts

@@ -0,0 +1,385 @@
+// The sandbox HOST — Cloud Phase 25 A1 + A1b, moved into the studio by
+// Cloud Phase 27 / DDR-209 A′2.
+//
+// Owns everything ABOUT a canvas build that must not live inside it: the
+// ceilings, the empty environment, the content-hash cache, and the counters the
+// cost surface reads. The build itself is `canvas-build-worker.ts`, running
+// under Bun in its own process.
+//
+// WHY THIS EXISTS AT ALL, given `buildCanvasModule` is one import away. On a
+// desktop, "the process that parses your canvas" and "the process you own" are
+// the same process, so an in-process build costs nothing. In a cell they are
+// not: the server process holds HUB_SECRET, MAUDE_PROJECT_TOKEN_KEY and the
+// tenant's storage credentials, and the source being parsed is written by
+// somebody who is not us. Same engine either way — a different host.
+//
+// THE CACHE IS AN ECONOMIC CONTROL, NOT AN OPTIMISATION (A1b). Rebuilding per
+// page view makes cost scale with VIEWS; keying the built module by the hash
+// of its inputs makes it scale with EDITS. That is the difference between a
+// €19 plan that works and one that does not, which is why the counters below
+// exist from day one rather than being retrofitted after the first invoice.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+
+import { DEV_SERVER_ROOT } from './paths.ts';
+
+/** Wall clock a single canvas build may take. */
+export const BUILD_TIMEOUT_MS = Number(process.env.MAUDE_CANVAS_BUILD_TIMEOUT_MS ?? 20_000);
+/** Resident memory a build process may reach before it is killed. */
+export const BUILD_RSS_LIMIT_MB = Number(process.env.MAUDE_CANVAS_BUILD_RSS_MB ?? 768);
+/** How many built modules to keep. Each is a string; canvases are ~100–400 kB. */
+export const CACHE_MAX_ENTRIES = Number(process.env.MAUDE_CANVAS_CACHE_ENTRIES ?? 64);
+
+export interface SandboxBuildOk {
+  ok: true;
+  js: string;
+  locator: unknown;
+  etag: string;
+  cached: boolean;
+}
+export interface SandboxBuildFail {
+  ok: false;
+  error: string;
+  kind: 'build' | 'timeout' | 'memory' | 'runtime';
+}
+export type SandboxBuildResult = SandboxBuildOk | SandboxBuildFail;
+
+const counters = {
+  builds: 0,
+  cacheHits: 0,
+  cacheMisses: 0,
+  failures: 0,
+  timeouts: 0,
+  memoryKills: 0,
+  /** Every completed build's wall-clock, newest last, capped. */
+  durationsMs: [] as number[],
+};
+
+/** A snapshot for the operator surface + the cost lane. */
+export function buildStats() {
+  const d = [...counters.durationsMs].sort((a, b) => a - b);
+  const p = (q: number) =>
+    d.length === 0 ? null : d[Math.min(d.length - 1, Math.floor(d.length * q))];
+  const total = counters.cacheHits + counters.cacheMisses;
+  return {
+    builds: counters.builds,
+    cacheHits: counters.cacheHits,
+    cacheMisses: counters.cacheMisses,
+    cacheHitRatio: total === 0 ? null : Number((counters.cacheHits / total).toFixed(3)),
+    failures: counters.failures,
+    timeouts: counters.timeouts,
+    memoryKills: counters.memoryKills,
+    p50Ms: p(0.5),
+    p95Ms: p(0.95),
+  };
+}
+
+/** Test seam. */
+export function _resetBuildStats(): void {
+  counters.builds = 0;
+  counters.cacheHits = 0;
+  counters.cacheMisses = 0;
+  counters.failures = 0;
+  counters.timeouts = 0;
+  counters.memoryKills = 0;
+  counters.durationsMs = [];
+  cache.clear();
+}
+
+/** key → { js, locator, etag } */
+const cache = new Map<string, { js: string; locator: unknown; etag: string }>();
+
+/**
+ * The cache key: the canvas source plus every sibling source it could pull in.
+ *
+ * Hashing only the entry file would serve a stale bundle after an edit to an
+ * imported component — the exact bug the desktop's mtime-keyed cache had to
+ * grow a watcher for. Here the inputs are cheap to enumerate (the design root
+ * is small and local), so the key is honest by construction.
+ */
+export function cacheKeyFor(designRoot: string, canvasAbs: string): string {
+  const h = createHash('sha256');
+  h.update(canvasAbs);
+  for (const file of relevantSources(designRoot, canvasAbs)) {
+    try {
+      const st = statSync(file);
+      h.update(`\0${file}\0${st.size}\0${st.mtimeMs}`);
+    } catch {
+      h.update(`\0${file}\0missing`);
+    }
+  }
+  return h.digest('hex');
+}
+
+/**
+ * Files whose content can change a canvas's bundle: the canvas itself, and
+ * every `.tsx`/`.ts`/`.css` file it can reach by relative import inside the
+ * design root (transitively). The allowlist guarantees nothing outside can be
+ * reached, so nothing outside can invalidate.
+ */
+function relevantSources(designRoot: string, canvasAbs: string): string[] {
+  const seen = new Set<string>();
+  const root = resolve(designRoot);
+  const stack = [resolve(canvasAbs)];
+  while (stack.length > 0) {
+    const file = stack.pop();
+    if (!file || seen.has(file) || !existsSync(file)) continue;
+    if (file !== root && !file.startsWith(root + sep)) continue;
+    seen.add(file);
+    let src = '';
+    try {
+      src = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(/(?:from|import)\s*["'](\.[^"']+)["']/g)) {
+      for (const candidate of resolveCandidates(dirname(file), m[1])) stack.push(candidate);
+    }
+  }
+  return [...seen].sort();
+}
+
+function resolveCandidates(fromDir: string, spec: string): string[] {
+  const base = resolve(fromDir, spec);
+  return [
+    base,
+    `${base}.tsx`,
+    `${base}.ts`,
+    `${base}.jsx`,
+    `${base}.js`,
+    join(base, 'index.tsx'),
+    join(base, 'index.ts'),
+  ];
+}
+
+function remember(key: string, value: { js: string; locator: unknown; etag: string }): void {
+  cache.set(key, value);
+  while (cache.size > CACHE_MAX_ENTRIES) {
+    const oldest = cache.keys().next().value as string;
+    cache.delete(oldest);
+  }
+}
+
+/**
+ * Resolve the runtime that runs the worker.
+ *
+ * In the cell image this is the Bun binary staged next to the bundle; in a dev
+ * checkout it is whatever `bun` is on PATH — and inside a compiled sidecar it is
+ * this very executable re-entered with `BUN_BE_BUN=1` (DDR-177: the packaged app
+ * must not need a user-installed runtime). A missing runtime is a configuration
+ * error the caller must surface — never a silent fallback to "no rendering",
+ * which would look to a member exactly like an empty project.
+ */
+export function resolveBunPath(env: NodeJS.ProcessEnv = process.env): string {
+  return env.MAUDE_BUN_PATH || 'bun';
+}
+
+/** Absolute path to the worker script, resolved per DDR-045 (never a bunfs path). */
+export function workerScript(env: NodeJS.ProcessEnv = process.env): string {
+  const staged = env.MAUDE_CANVAS_WORKERS
+    ? join(env.MAUDE_CANVAS_WORKERS, 'canvas-build-worker.ts')
+    : null;
+  if (staged && existsSync(staged)) return staged;
+  return join(DEV_SERVER_ROOT, 'canvas-build-worker.ts');
+}
+
+/**
+ * The child's environment: a PATH to exec with, a HOME for Bun's cache, and
+ * the two PATHS that tell it where our own code lives. Nothing else — every
+ * secret in a cell is an env var, and a build that cannot read them cannot
+ * leak them, whatever a tenant's source manages to import.
+ */
+export function workerEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  return {
+    PATH: env.PATH ?? '/usr/local/bin:/usr/bin:/bin',
+    HOME: env.HOME ?? '/tmp',
+    // Where the engine lives. Defaulted to this install's own root so a cell
+    // that stages the studio somewhere unusual still resolves it, and a dev
+    // checkout needs no configuration at all.
+    MAUDE_STUDIO_SRC: env.MAUDE_STUDIO_SRC ?? DEV_SERVER_ROOT,
+    // NAPI_RS_NATIVE_LIBRARY_PATH is forwarded ONLY when it names a real file.
+    //
+    // Inside a `bun --compile` binary this variable is set at runtime by the
+    // DDR-042 compile entry, to a path in that binary's OWN virtual filesystem
+    // (`/$bunfs/root/…`). Handing that to a child is handing it an address that
+    // exists in a different process's imagination: the child resolves
+    // oxc-parser, finds the override, cannot open it, and reports "Cannot find
+    // native binding" — while the very same command run by hand with a clean
+    // environment works, because it then finds the real binding on disk.
+    // (Which is exactly how this was diagnosed.)
+    ...(env.NAPI_RS_NATIVE_LIBRARY_PATH && !isVirtualPath(env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      ? { NAPI_RS_NATIVE_LIBRARY_PATH: env.NAPI_RS_NATIVE_LIBRARY_PATH }
+      : {}),
+    // DDR-177 — when the "bun" we spawn is the compiled sidecar itself, this is
+    // what makes it behave as a JS runtime instead of re-launching the server.
+    ...(env.MAUDE_BUN_PATH && env.MAUDE_BUN_PATH === process.execPath ? { BUN_BE_BUN: '1' } : {}),
+  };
+}
+
+/** A path inside a compiled binary's embedded filesystem — real to that process
+ *  and to nothing else. Mirrors `paths.ts`'s own bunfs test. */
+function isVirtualPath(p: string): boolean {
+  return p.startsWith('/$bunfs') || p.startsWith('B:/~BUN');
+}
+
+/**
+ * Whether the sandbox is actually wired in this install.
+ *
+ * This is the `sandboxArmed` input to the containment boot-assert (DDR-209 A′1):
+ * a cell may serve `/_canvas-shell` and `/_canvas-runtime` only while a real,
+ * runnable, out-of-process build exists. Both halves are checked because either
+ * one missing means the same thing in practice — the server would fall back to
+ * building tenant source in the process that holds the secrets.
+ *
+ * Reported rather than thrown so the boot-assert owns the refusal and its
+ * wording; this function has no opinion about what a caller does with `false`.
+ */
+export function isSandboxArmed(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (!existsSync(workerScript(env))) return false;
+  const bun = resolveBunPath(env);
+  // A bare `bun` means "whatever is on PATH" and we cannot cheaply prove it is
+  // there; an absolute path we can. Both are accepted — the spawn's own failure
+  // is the backstop, and refusing to boot because PATH lookup is unverifiable
+  // would make a dev checkout unable to test workspace mode at all.
+  return bun === 'bun' || existsSync(bun);
+}
+
+/**
+ * Build one canvas, sandboxed.
+ */
+export async function buildCanvasSandboxed({
+  designRoot,
+  canvasAbs,
+  env = process.env,
+}: {
+  designRoot: string;
+  canvasAbs: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<SandboxBuildResult> {
+  const key = cacheKeyFor(designRoot, canvasAbs);
+  const hit = cache.get(key);
+  if (hit) {
+    counters.cacheHits++;
+    return { ...hit, ok: true, cached: true };
+  }
+  counters.cacheMisses++;
+
+  const started = Date.now();
+  const result = await runWorker({ designRoot, canvasAbs, env });
+  const elapsed = Date.now() - started;
+  counters.durationsMs.push(elapsed);
+  if (counters.durationsMs.length > 200) counters.durationsMs.shift();
+
+  if (result.ok) {
+    counters.builds++;
+    const value = { js: result.js, locator: result.locator, etag: result.etag };
+    remember(key, value);
+    return { ...value, ok: true, cached: false };
+  }
+  counters.failures++;
+  if (result.kind === 'timeout') counters.timeouts++;
+  if (result.kind === 'memory') counters.memoryKills++;
+  return result;
+}
+
+async function runWorker({
+  designRoot,
+  canvasAbs,
+  env,
+}: {
+  designRoot: string;
+  canvasAbs: string;
+  env: NodeJS.ProcessEnv;
+}): Promise<SandboxBuildResult> {
+  const bun = resolveBunPath(env);
+  let child: Bun.Subprocess<'ignore', 'pipe', 'pipe'>;
+  try {
+    child = Bun.spawn([bun, workerScript(env), designRoot, canvasAbs], {
+      // THE EMPTY ENVIRONMENT IS THE POINT — see workerEnv().
+      env: workerEnv(env),
+      cwd: designRoot,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      kind: 'runtime',
+      error: `could not start the build: ${(err as Error).message}`,
+    };
+  }
+
+  let outcome: SandboxBuildFail | null = null;
+
+  const deadline = setTimeout(() => {
+    outcome = {
+      ok: false,
+      kind: 'timeout',
+      error: `this canvas took longer than ${Math.round(BUILD_TIMEOUT_MS / 1000)}s to build and was stopped.`,
+    };
+    child.kill('SIGKILL');
+  }, BUILD_TIMEOUT_MS);
+
+  // RSS ceiling. A hard `ulimit -v` is the obvious alternative and does not
+  // work: JS runtimes reserve enormous virtual address space and would die
+  // at boot. Polling resident size is honest about what is actually being
+  // consumed on our bill.
+  const rssPoll = setInterval(() => {
+    const mb = rssMb(child.pid);
+    if (mb !== null && mb > BUILD_RSS_LIMIT_MB) {
+      outcome = {
+        ok: false,
+        kind: 'memory',
+        error: `this canvas needed more than ${BUILD_RSS_LIMIT_MB} MB to build and was stopped.`,
+      };
+      child.kill('SIGKILL');
+    }
+  }, 500);
+  rssPoll.unref?.();
+
+  let out = '';
+  let errOut = '';
+  try {
+    [out, errOut] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    await child.exited;
+  } catch (err) {
+    return { ok: false, kind: 'runtime', error: `the build failed: ${(err as Error).message}` };
+  } finally {
+    clearTimeout(deadline);
+    clearInterval(rssPoll);
+  }
+
+  if (outcome) return outcome;
+
+  try {
+    const parsed = JSON.parse(out);
+    if (parsed.ok) {
+      return { ok: true, js: parsed.js, locator: parsed.locator, etag: parsed.etag, cached: false };
+    }
+    return { ok: false, kind: 'build', error: String(parsed.error) };
+  } catch {
+    return {
+      ok: false,
+      kind: 'runtime',
+      error: `the build produced no result${errOut ? `: ${errOut.trim().slice(0, 500)}` : ''}`,
+    };
+  }
+}
+
+/** Resident set size of a pid in MB, or null when it cannot be read. */
+function rssMb(pid: number | undefined): number | null {
+  if (!pid) return null;
+  try {
+    // Linux (the cell). /proc/<pid>/statm reports pages; page size is 4 KiB.
+    const statm = readFileSync(`/proc/${pid}/statm`, 'utf8').split(' ');
+    return (Number(statm[1]) * 4096) / (1024 * 1024);
+  } catch {
+    return null; // macOS dev boxes: the wall-clock ceiling still applies
+  }
+}