@datarails-ai/dr-appspace-cli 0.12.32 → 0.12.34

package/README.md

@@ -325,6 +325,47 @@ lives in dr-assets-service, attached to the agent by id — see the repo's
 command calls a model: the builders write `contract.json` themselves and run
 `app-space compile`.
 
+### A picture of every page, as every role: `test --screenshot`
+
+`app-space test --screenshot` draws, after the usual checks, every page of the
+pushed package once per declared role in headless Google Chrome, and writes
+`<out>/<page>.<role>.png` plus an `index.json` that a judge can read (page,
+role, file, size, which handlers the page called, which had no fixture). It
+judges nothing yet; the `look-*` findings come later.
+
+| Flag | What it does | Default |
+| --- | --- | --- |
+| `--screenshot` | take the pictures after the checks | off |
+| `--out <dir>` | where the PNGs and `index.json` go | `<dir>/.screenshots` |
+| `--role <name>` | only this declared role (repeatable, or `a,b`) | every declared role (`default` for an app with none) |
+| `--width <px>` / `--height <px>` | the window | `1400` × `900` |
+| `--full` | grow the window to the page's full height (one extra load per picture) | off |
+| `--shelf <path>` | serve `vendor/` and `ui-kit/` from this dr-app-space checkout | the server the app is pushed to |
+| `--screenshot-budget <ms>` | the whole phase's ceiling; each picture is capped at 60 s | `180000` |
+
+```
+dr-appspace app-space test ./my-app --skip-handlers --interact never --screenshot -s DEV-1
+dr-appspace app-space test ./my-app --screenshot --role approver --full --shelf ~/dr-app-space -s DEV-1
+```
+
+The pages load from a stub on `127.0.0.1` (an ephemeral port), never from
+the app's server, so taking pictures writes no row. The stub answers
+`/access` as each role (the manifest's page and handler gates, under the
+server's own answer for that role), each handler with its `tests.json`
+fixture (the first `expect`, else a value built from the first `shape`),
+`[]` when no fixture names it, and 403 when the role's gate refuses the
+call. A page a role may not open is listed as skipped, not drawn. The shelf
+comes from the server the app is pushed to (its public `/vendor/*` and
+`/ui-kit/*`, fetched once per run). Use `--shelf` with a checkout to work
+offline.
+
+Chrome is found through `CHROME_PATH`, then `google-chrome`, `chromium` or
+`chrome` on `PATH`, then the macOS app bundle and the usual Linux paths. With
+none, the command exits 2 before anything runs. No browser is ever
+downloaded. Each Chrome gets its own temporary profile, which is removed
+afterwards, and its process group is killed once the file is written,
+because Chrome 154 does not always exit after `--screenshot`.
+
 ## Development
 
 This package lives inside the dr-app-space repo but is independent of the

package/dist/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-appspace-cli",
-  version: "0.12.32",
+  version: "0.12.34",
   description: "Datarails App Space CLI \u2014 build, try, push and publish App Space apps",
   type: "module",
   engines: {
@@ -57,7 +57,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-26T10:14:34.045Z";
+var BUILD_TIME = "2026-10-26T12:43:18.858Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -776,12 +776,12 @@ async function requestDeviceCode(host, options) {
     interval: typeof obj4.interval === "number" ? obj4.interval : 0
   };
 }
-var defaultSleep = (ms, signal) => new Promise((resolve15, reject) => {
+var defaultSleep = (ms, signal) => new Promise((resolve17, reject) => {
   if (signal?.aborted) {
     reject(signal.reason ?? new Error("aborted"));
     return;
   }
-  const t = setTimeout(resolve15, ms);
+  const t = setTimeout(resolve17, ms);
   signal?.addEventListener(
     "abort",
     () => {
@@ -827,7 +827,7 @@ async function pollForToken(host, deviceCode, options = {}) {
   const interval = options.interval ?? 2e3;
   const maxWait = options.maxWait ?? 6e5;
   const now = options.now ?? Date.now;
-  const sleep2 = options.sleep ?? defaultSleep;
+  const sleep3 = options.sleep ?? defaultSleep;
   const signal = options.signal;
   const base = host.replace(/\/+$/, "");
   const deadline = now() + maxWait;
@@ -859,7 +859,7 @@ async function pollForToken(host, deviceCode, options = {}) {
     }
     const errCode = tryParseErrorCode(text3);
     if (errCode === "authorization_pending" || errCode === "slow_down") {
-      await sleep2(interval, signal);
+      await sleep3(interval, signal);
       continue;
     }
     if (errCode) {
@@ -1407,19 +1407,19 @@ async function openBrowser(url) {
 
 // src/commands/_serverPicker.ts
 async function readLine(stdin) {
-  return new Promise((resolve15, reject) => {
+  return new Promise((resolve17, reject) => {
     let data = "";
     const onData = (chunk) => {
       data += chunk.toString();
       const i = data.indexOf("\n");
       if (i >= 0) {
         cleanup();
-        resolve15(data.slice(0, i + 1));
+        resolve17(data.slice(0, i + 1));
       }
     };
     const onEnd = () => {
       cleanup();
-      resolve15(data);
+      resolve17(data);
     };
     const onError = (err) => {
       cleanup();
@@ -8636,10 +8636,10 @@ function pageCode(html, path3, modules, pageSource) {
       continue;
     }
     if (/^(?:[a-z]+:)?\/\//i.test(src) || src.startsWith("/") || src.startsWith("../")) continue;
-    const relative3 = src.replace(/^\.\//, "");
-    if (modules.has(`${path3}|${relative3}`)) continue;
+    const relative4 = src.replace(/^\.\//, "");
+    if (modules.has(`${path3}|${relative4}`)) continue;
     const dir = path3.includes("/") ? path3.slice(0, path3.lastIndexOf("/") + 1) : "";
-    const body = pageSource(`${dir}${relative3}`);
+    const body = pageSource(`${dir}${relative4}`);
     if (typeof body !== "string") return null;
     out.push(body);
   }
@@ -15696,9 +15696,9 @@ function whereProblems(where2, table, pointer2, who, { platform = false, noColum
   const problems = [];
   const say = (key, message, code = "app_model_mismatch") => problems.push({ code, pointer: pointer2(key), message: `${who} ${message}` });
   for (const key of Object.keys(where2).sort()) {
-    const sep6 = key.indexOf("__");
-    const column = sep6 < 0 ? key : key.slice(0, sep6);
-    const op = sep6 < 0 ? "eq" : key.slice(sep6 + 2);
+    const sep7 = key.indexOf("__");
+    const column = sep7 < 0 ? key : key.slice(0, sep7);
+    const op = sep7 < 0 ? "eq" : key.slice(sep7 + 2);
     const value = where2[key];
     if (!WHERE_OPS.includes(op)) {
       say(key, `filters with "${key}", and "${op}" is no operator a where knows: ${WHERE_OPS.join(", ")}`);
@@ -21590,7 +21590,7 @@ var LiveContractMissing = class extends Error {
 };
 async function pullInto(client, appId, dir, {
   onWait,
-  sleep: sleep2 = (ms) => new Promise((done) => setTimeout(done, ms))
+  sleep: sleep3 = (ms) => new Promise((done) => setTimeout(done, ms))
 } = {}) {
   for (let pull = 1; ; pull += 1) {
     let pkg;
@@ -21612,7 +21612,7 @@ async function pullInto(client, appId, dir, {
     if (pull >= contractWait.pulls) throw new LiveContractMissing(appId, pkg.revision, pull, read.missing);
     const ms = contractWaitMs(pull);
     onWait?.(pull, ms, read.missing);
-    await sleep2(ms);
+    await sleep3(ms);
   }
 }
 async function runGet(appId, opts) {
@@ -26576,10 +26576,10 @@ function pageCode2(html, path3, modules, pageSource) {
       continue;
     }
     if (/^(?:[a-z]+:)?\/\//i.test(src) || src.startsWith("/") || src.startsWith("../")) continue;
-    const relative3 = src.replace(/^\.\//, "");
-    if (modules.has(`${path3}|${relative3}`)) continue;
+    const relative4 = src.replace(/^\.\//, "");
+    if (modules.has(`${path3}|${relative4}`)) continue;
     const dir = path3.includes("/") ? path3.slice(0, path3.lastIndexOf("/") + 1) : "";
-    const body = pageSource(`${dir}${relative3}`);
+    const body = pageSource(`${dir}${relative4}`);
     if (typeof body !== "string") return null;
     out.push(body);
   }
@@ -30351,7 +30351,7 @@ async function runShipOntoLive(dir, opts) {
     return { code, lost: code === 3 ? await lostRaceOf(dir) : null, creating: pulled === null };
   }, opts);
 }
-async function landWithRetries(tryOnce, opts, sleep2 = (ms) => new Promise((done) => setTimeout(done, ms))) {
+async function landWithRetries(tryOnce, opts, sleep3 = (ms) => new Promise((done) => setTimeout(done, ms))) {
   let createGuarded = true;
   for (let attempt = 1; attempt <= ONTO_LIVE_ATTEMPTS; attempt += 1) {
     const { code, lost, creating } = await tryOnce(createGuarded);
@@ -30372,7 +30372,7 @@ async function landWithRetries(tryOnce, opts, sleep2 = (ms) => new Promise((done
 `
       );
     }
-    await sleep2(ontoLiveBackoff(attempt));
+    await sleep3(ontoLiveBackoff(attempt));
   }
   process.stderr.write(
     `ship --onto-live: ${String(ONTO_LIVE_ATTEMPTS)} attempts, and another landing got there first every time. Nothing of this pass is live; run the same command again.
@@ -30865,8 +30865,8 @@ function registerLogsCommand(parent) {
 }
 
 // src/commands/appspace/test.ts
-import { readFile as readFile12 } from "fs/promises";
-import { join as join17 } from "path";
+import { readFile as readFile13 } from "fs/promises";
+import { join as join18, resolve as resolve16 } from "path";
 
 // src/commands/appspace/_files.ts
 import { readFile as readFile11, realpath } from "fs/promises";
@@ -31431,15 +31431,15 @@ function planInteractions(components, model, page, uidOf) {
       for (const child of components) {
         if (child.props.field === void 0 || child.props.field === "") continue;
         if (!FORM_CONTROL_TAGS.has(child.tag)) continue;
-        let inside = false;
+        let inside2 = false;
         let hops = 0;
         for (let up = child.parent === null ? void 0 : byIndex.get(child.parent); up !== void 0 && hops <= components.length; up = up.parent === null ? void 0 : byIndex.get(up.parent), hops += 1) {
           if (up.n === component.n) {
-            inside = true;
+            inside2 = true;
             break;
           }
         }
-        if (!inside) continue;
+        if (!inside2) continue;
         const field = child.props.field;
         const column = columnOf(model, component.props.entity, field);
         const control = controlFor(column);
@@ -32372,13 +32372,13 @@ var defaultBlobReader = async (blob) => {
 function blobReaderFor(window) {
   const ctor = window?.FileReader;
   if (typeof ctor !== "function") return defaultBlobReader;
-  return (blob) => new Promise((resolve15, reject) => {
+  return (blob) => new Promise((resolve17, reject) => {
     const reader = new ctor();
     reader.onload = () => {
       const result = reader.result;
-      if (result === null || result === void 0) resolve15(Buffer.alloc(0));
-      else if (typeof result === "string") resolve15(Buffer.from(result, "utf8"));
-      else resolve15(Buffer.from(result));
+      if (result === null || result === void 0) resolve17(Buffer.alloc(0));
+      else if (typeof result === "string") resolve17(Buffer.from(result, "utf8"));
+      else resolve17(Buffer.from(result));
     };
     reader.onerror = () => reject(new Error("the attached file could not be read"));
     reader.onabort = () => reject(new Error("reading the attached file was aborted"));
@@ -32665,7 +32665,7 @@ async function loadJsdom() {
     );
   }
 }
-var sleep = (ms) => new Promise((resolve15) => setTimeout(resolve15, ms));
+var sleep = (ms) => new Promise((resolve17) => setTimeout(resolve17, ms));
 var DRAW_GRACE_MS = 3e3;
 async function runUiSmoke(opts) {
   const timeoutMs = opts.timeoutMs ?? 15e3;
@@ -33168,6 +33168,649 @@ async function runUiSmoke(opts) {
   };
 }
 
+// src/commands/appspace/_screenshot.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync3, statSync as statSync3 } from "fs";
+import { mkdir as mkdir8, mkdtemp as mkdtemp4, readFile as readFile12, readdir as readdir3, rm as rm5, stat as stat2, writeFile as writeFile9 } from "fs/promises";
+import { createServer } from "http";
+import { tmpdir as tmpdir5 } from "os";
+import { delimiter, extname as extname2, join as join17, relative as relative3, resolve as resolve15, sep as sep6 } from "path";
+var SHOT_TIMEOUT_MS = 6e4;
+var SHOT_BUDGET_MS = 18e4;
+var SHOT_CONCURRENCY = 4;
+var VIRTUAL_TIME_MS = 8e3;
+var ATTEMPT_MS = 25e3;
+var MEASURE_MS = 15e3;
+var FULL_HEIGHT_CAP = 8e3;
+var NO_ROLE = "default";
+var CHROME_MISSING = "app-space test --screenshot needs Google Chrome: install Google Chrome or set CHROME_PATH to a Chrome or Chromium binary. Nothing is downloaded.";
+var CHROME_APP_PATHS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser"
+];
+var CHROME_NAMES = ["google-chrome", "chromium", "chrome"];
+function isFile(path3) {
+  try {
+    return statSync3(path3).isFile();
+  } catch {
+    return false;
+  }
+}
+function findChrome(env = process.env, exists = isFile, appPaths = CHROME_APP_PATHS) {
+  const pinned = env["CHROME_PATH"]?.trim();
+  if (pinned) return pinned;
+  const dirs = (env["PATH"] ?? "").split(delimiter).filter((dir) => dir !== "");
+  for (const name of CHROME_NAMES) {
+    for (const dir of dirs) {
+      const path3 = join17(dir, name);
+      if (exists(path3)) return path3;
+    }
+  }
+  return appPaths.find((path3) => exists(path3)) ?? null;
+}
+function rolesOf6(manifest) {
+  if (!Array.isArray(manifest?.roles)) return [];
+  return manifest.roles.filter(
+    (one) => typeof one === "object" && one !== null && typeof one.name === "string"
+  );
+}
+function pageGates(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  if (!Array.isArray(manifest?.pages)) return out;
+  for (const page of manifest.pages) {
+    if (typeof page !== "object" || page === null) continue;
+    const { path: path3, roles } = page;
+    if (typeof path3 !== "string" || !Array.isArray(roles)) continue;
+    const names = roles.filter((r) => typeof r === "string");
+    if (names.length > 0) out.set(path3, names);
+  }
+  return out;
+}
+function handlerGates(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  const raw = manifest?.handlers;
+  if (typeof raw !== "object" || raw === null) return out;
+  for (const [name, row] of Object.entries(raw)) {
+    const gate = typeof row === "object" && row !== null ? row.requiresRole : void 0;
+    out.set(name, Array.isArray(gate) ? gate.filter((r) => typeof r === "string") : null);
+  }
+  return out;
+}
+function shotRoles(manifest, only = []) {
+  const declared = rolesOf6(manifest).map((role) => role.name);
+  const all = declared.length === 0 ? [NO_ROLE] : declared;
+  if (only.length === 0) return all;
+  const unknown = only.filter((role) => !all.includes(role));
+  if (unknown.length > 0) {
+    throw new Error(
+      `--role ${unknown.join(", ")}: this app ${declared.length === 0 ? 'declares no roles (its one render is "default")' : `declares ${declared.join(", ")}`}.`
+    );
+  }
+  return all.filter((role) => only.includes(role));
+}
+function seesOf(roles, role) {
+  const declared = new Set(roles.map((r) => r.name));
+  const raw = roles.find((r) => r.name === role)?.sees;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((s) => typeof s === "string" && declared.has(s) && s !== role);
+}
+function maySeePage(manifest, role, entry) {
+  const roles = rolesOf6(manifest);
+  const gate = pageGates(manifest).get(`ui/${entry}`);
+  if (gate === void 0 || roles.length === 0) return true;
+  const visible = /* @__PURE__ */ new Set([role, ...seesOf(roles, role)]);
+  return gate.some((r) => visible.has(r));
+}
+function accessFor(manifest, role, overlay, sources = []) {
+  const roles = rolesOf6(manifest);
+  const names = roles.map((r) => r.name);
+  const held = names.length === 0 ? null : role;
+  const visible = new Set(held === null ? [] : [held, ...seesOf(roles, held)]);
+  const allowed = {};
+  for (const name of names) allowed[name] = visible.has(name);
+  const gates = pageGates(manifest);
+  for (const [path3, gate] of gates) {
+    allowed[gate.join(" ")] = maySeePage(manifest, role, path3.replace(/^ui\//, ""));
+  }
+  for (const source of sources) allowed[source] = true;
+  for (const [handler, gate] of handlerGates(manifest)) {
+    allowed[handler] = gate === null || gate.length === 0 || held === null || gate.includes(held);
+  }
+  Object.assign(allowed, overlay ?? {});
+  const payload = {
+    role: held,
+    asRole: null,
+    defaultRole: roles.find((r) => r.default === true)?.name ?? null,
+    roles: names,
+    allowed,
+    user: { email: "screenshot@app-space.test" }
+  };
+  if (gates.size > 0 || roles.some((r) => typeof r.home === "string")) {
+    payload.pages = Object.fromEntries(
+      [...gates.keys()].sort().map((path3) => [path3, maySeePage(manifest, role, path3.replace(/^ui\//, ""))])
+    );
+    const home = roles.find((r) => r.name === held)?.home;
+    payload.home = typeof home === "string" && /^ui\/[A-Za-z0-9_-]+\.html$/.test(home) ? home : null;
+  }
+  return payload;
+}
+function valueOfShape(shape) {
+  if (typeof shape === "string") {
+    const want = shape.endsWith("?") ? shape.slice(0, -1) : shape;
+    switch (want) {
+      case "string":
+        return "";
+      case "number":
+        return 0;
+      case "boolean":
+        return false;
+      case "object":
+        return {};
+      case "array":
+        return [];
+      default:
+        return null;
+    }
+  }
+  if (Array.isArray(shape)) return [];
+  if (typeof shape === "object" && shape !== null) {
+    return Object.fromEntries(Object.entries(shape).map(([key, sub]) => [key, valueOfShape(sub)]));
+  }
+  return null;
+}
+function fixtureAnswers(cases) {
+  const out = /* @__PURE__ */ new Map();
+  for (const kase of cases) {
+    if (kase.error !== void 0 || kase.expect === void 0) continue;
+    if (!out.has(kase.handler)) out.set(kase.handler, { body: kase.expect, from: "expect" });
+  }
+  for (const kase of cases) {
+    if (kase.error !== void 0 || kase.shape === void 0 || out.has(kase.handler)) continue;
+    out.set(kase.handler, { body: valueOfShape(kase.shape), from: "shape" });
+  }
+  return out;
+}
+var TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".map": "application/json"
+};
+function contentType(path3) {
+  return TYPES[extname2(path3).toLowerCase()] ?? "application/octet-stream";
+}
+function inside(root, rel) {
+  const base = resolve15(root);
+  const full = resolve15(base, rel);
+  return full === base || !full.startsWith(base + sep6) ? null : full;
+}
+var Shelf = class {
+  constructor(source, fetchImpl = fetch) {
+    this.source = source;
+    this.fetchImpl = fetchImpl;
+  }
+  source;
+  fetchImpl;
+  cache = /* @__PURE__ */ new Map();
+  misses = /* @__PURE__ */ new Set();
+  get(path3) {
+    let hit = this.cache.get(path3);
+    if (hit === void 0) {
+      hit = this.load(path3).then((served) => {
+        if (served.status !== 200) this.misses.add(path3);
+        return served;
+      });
+      this.cache.set(path3, hit);
+    }
+    return hit;
+  }
+  async load(path3) {
+    const missing = { status: 404, type: "text/plain", body: Buffer.from("not on the shelf") };
+    if (this.source.kind === "server") {
+      try {
+        const res = await this.fetchImpl(`${this.source.baseUrl.replace(/\/+$/, "")}/${path3}`, {
+          signal: AbortSignal.timeout(3e4)
+        });
+        if (!res.ok) return { ...missing, status: res.status };
+        return {
+          status: 200,
+          type: res.headers.get("content-type") ?? contentType(path3),
+          body: Buffer.from(await res.arrayBuffer())
+        };
+      } catch {
+        return { ...missing, status: 502 };
+      }
+    }
+    const candidates = path3.startsWith("ui-kit/") ? [path3, `appspace/ui_kit/${path3.slice("ui-kit/".length)}`] : [path3];
+    for (const rel of candidates) {
+      const full = inside(this.source.root, rel);
+      if (full === null) continue;
+      try {
+        return { status: 200, type: contentType(full), body: await readFile12(full) };
+      } catch {
+      }
+    }
+    return missing;
+  }
+};
+var MEASURE_SCRIPT = '<script>addEventListener("load",function(){setTimeout(function(){var d=document.documentElement,b=document.body||d,extra=0;document.querySelectorAll("*").forEach(function(e){var s=getComputedStyle(e).overflowY;if((s==="auto"||s==="scroll")&&e.scrollHeight>e.clientHeight)extra=Math.max(extra,e.scrollHeight-e.clientHeight)});var h=Math.max(d.scrollHeight,b.scrollHeight,innerHeight+extra);var m=document.createElement("meta");m.id="dr-shot-height";m.content=String(h);document.head.appendChild(m)},3000)})</script>';
+function injectMeasure(html) {
+  const head = /<head\b[^>]*>/i.exec(html);
+  if (head === null) return MEASURE_SCRIPT + html;
+  return html.slice(0, head.index + head[0].length) + MEASURE_SCRIPT + html.slice(head.index + head[0].length);
+}
+function send(res, status, type, body) {
+  res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store" });
+  res.end(body);
+}
+function sendJson(res, status, value) {
+  send(res, status, "application/json", JSON.stringify(value));
+}
+function drain(req) {
+  return new Promise((done) => {
+    req.on("data", () => void 0);
+    req.on("end", () => done());
+    req.on("error", () => done());
+  });
+}
+async function startStubServer(opts) {
+  const shots = /* @__PURE__ */ new Map();
+  const logs = /* @__PURE__ */ new Map();
+  const logOf = (id) => {
+    let log = logs.get(id);
+    if (log === void 0) {
+      log = { called: [], answered: [], noFixture: [], refused: [] };
+      logs.set(id, log);
+    }
+    return log;
+  };
+  const note = (list3, name) => {
+    if (!list3.includes(name)) list3.push(name);
+  };
+  const appPrefix = /^apps\/[^/]+\//;
+  const handle = async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    let path3;
+    try {
+      path3 = decodeURIComponent(url.pathname);
+    } catch {
+      return send(res, 400, "text/plain", "bad path");
+    }
+    const match = /^\/s\/(\d+)\/(.*)$/.exec(path3);
+    const id = match === null ? -1 : Number(match[1]);
+    const rest = match === null ? path3.replace(/^\/+/, "") : match[2] ?? "";
+    const shot = shots.get(id);
+    if (req.method === "GET" && (rest.startsWith("vendor/") || rest.startsWith("ui-kit/"))) {
+      const served = await opts.shelf.get(rest);
+      return send(res, served.status, served.type, served.body);
+    }
+    const prefix = appPrefix.exec(rest);
+    if (shot === void 0 || prefix === null) {
+      await drain(req);
+      return send(res, 404, "text/plain", "not found");
+    }
+    const inApp = rest.slice(prefix[0].length);
+    if (req.method === "GET" && inApp === "access") {
+      return sendJson(
+        res,
+        200,
+        accessFor(opts.manifest, shot.role, opts.allowedByRole?.[shot.role], opts.sources ?? [])
+      );
+    }
+    if (req.method === "GET" && inApp.startsWith("ui/")) {
+      const entry = inApp.slice("ui/".length);
+      const body = Object.prototype.hasOwnProperty.call(opts.files, entry) ? opts.files[entry] : void 0;
+      if (body === void 0) return send(res, 404, "text/plain", "no such UI file");
+      const type = contentType(entry);
+      if (shot.measure === true && type.startsWith("text/html")) {
+        return send(res, 200, type, injectMeasure(body.toString()));
+      }
+      return send(res, 200, type, body);
+    }
+    if (req.method === "POST" && /^[^/]+$/.test(inApp)) {
+      await drain(req);
+      if (inApp === "uploads") return sendJson(res, 200, { upload: "screenshot-stub" });
+      const log = logOf(id);
+      note(log.called, inApp);
+      const access = accessFor(opts.manifest, shot.role, opts.allowedByRole?.[shot.role], opts.sources ?? []);
+      if (access.allowed[inApp] === false) {
+        note(log.refused, inApp);
+        return sendJson(res, 403, { detail: `role ${shot.role} may not call ${inApp}` });
+      }
+      const answer = opts.answers.get(inApp);
+      if (answer === void 0) {
+        note(log.noFixture, inApp);
+        return sendJson(res, 200, []);
+      }
+      note(log.answered, inApp);
+      return sendJson(res, 200, answer.body);
+    }
+    await drain(req);
+    return send(res, 404, "text/plain", "not found");
+  };
+  const server = createServer((req, res) => {
+    handle(req, res).catch(() => {
+      if (!res.headersSent) send(res, 500, "text/plain", "stub error");
+      else res.end();
+    });
+  });
+  await new Promise((ok, fail) => {
+    server.once("error", fail);
+    server.listen(0, "127.0.0.1", () => ok());
+  });
+  const port = server.address().port;
+  return {
+    port,
+    urlFor: (id, entry) => `http://127.0.0.1:${String(port)}/s/${String(id)}/apps/${encodeURIComponent(opts.appId)}/ui/${entry.split("/").map(encodeURIComponent).join("/")}`,
+    register: (id, shot) => {
+      shots.set(id, shot);
+    },
+    calls: (id) => {
+      const log = logOf(id);
+      return { called: [...log.called], answered: [...log.answered], noFixture: [...log.noFixture], refused: [...log.refused] };
+    },
+    close: () => new Promise((done) => {
+      server.closeAllConnections?.();
+      server.close(() => done());
+    })
+  };
+}
+function killGroup(child) {
+  if (child.pid === void 0) return;
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }
+}
+var sleep2 = (ms) => new Promise((done) => setTimeout(done, ms));
+async function runChrome(run) {
+  const profile = await mkdtemp4(join17(tmpdir5(), "dr-appspace-shot-"));
+  const args = [
+    "--headless=new",
+    "--disable-gpu",
+    "--hide-scrollbars",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-extensions",
+    "--disable-background-networking",
+    "--disable-sync",
+    "--mute-audio",
+    `--user-data-dir=${profile}`,
+    `--window-size=${String(run.width)},${String(run.height)}`,
+    `--virtual-time-budget=${String(VIRTUAL_TIME_MS)}`,
+    run.out === void 0 ? "--dump-dom" : `--screenshot=${run.out}`,
+    run.url
+  ];
+  let stdout = "";
+  let exited = false;
+  let spawnError;
+  const child = spawn(run.chrome, args, {
+    detached: true,
+    stdio: ["ignore", run.out === void 0 ? "pipe" : "ignore", "ignore"]
+  });
+  child.stdout?.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.on("exit", () => {
+    exited = true;
+  });
+  child.on("error", (err) => {
+    exited = true;
+    spawnError = `could not start ${run.chrome}: ${err.message}`;
+  });
+  const deadline = Date.now() + run.timeoutMs;
+  let lastSize = -1;
+  let ok = false;
+  try {
+    while (Date.now() < deadline) {
+      if (spawnError !== void 0) break;
+      if (run.out === void 0) {
+        if (/<\/html>\s*$/i.test(stdout) || exited) {
+          ok = stdout.trim() !== "";
+          break;
+        }
+      } else {
+        let size2 = -1;
+        try {
+          size2 = (await stat2(run.out)).size;
+        } catch {
+          size2 = -1;
+        }
+        if (size2 > 0 && size2 === lastSize) {
+          ok = true;
+          break;
+        }
+        lastSize = size2;
+        if (exited && size2 <= 0) break;
+      }
+      await sleep2(exited ? 50 : 150);
+    }
+  } finally {
+    killGroup(child);
+    await rm5(profile, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }).catch(() => void 0);
+  }
+  if (ok) return { ok, stdout, profile };
+  const error = spawnError ?? (Date.now() >= deadline ? `timed out after ${String(Math.round(run.timeoutMs / 1e3))}s` : run.out === void 0 ? "Chrome printed no DOM" : "Chrome exited without writing the screenshot");
+  return { ok, stdout, profile, error };
+}
+function pngSize(bytes) {
+  if (bytes.length < 24 || bytes.readUInt32BE(0) !== 2303741511 || bytes.toString("ascii", 12, 16) !== "IHDR") {
+    return null;
+  }
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+function pageName(entry) {
+  return entry.replace(/\.html?$/i, "").replace(/\//g, "_");
+}
+function safeRole(role) {
+  return role.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+async function runScreenshots(opts) {
+  const now = opts.now ?? Date.now;
+  const started = now();
+  const budgetUntil = started + opts.budgetMs;
+  const shotTimeout = opts.shotTimeoutMs ?? SHOT_TIMEOUT_MS;
+  await mkdir8(opts.outDir, { recursive: true });
+  const answers = fixtureAnswers(opts.cases);
+  const shelf2 = new Shelf(opts.shelf, opts.fetchImpl);
+  const stub = await startStubServer({
+    appId: opts.appId,
+    files: opts.files,
+    manifest: opts.manifest,
+    ...opts.allowedByRole === void 0 ? {} : { allowedByRole: opts.allowedByRole },
+    ...opts.sources === void 0 ? {} : { sources: opts.sources },
+    answers,
+    shelf: shelf2
+  });
+  const plan = [];
+  for (const entry of opts.pages) for (const role of opts.roles) plan.push({ entry, role });
+  const shots = new Array(plan.length);
+  let nextId = 0;
+  const one = async (index2) => {
+    const { entry, role } = plan[index2];
+    const file = `${pageName(entry)}.${safeRole(role)}.png`;
+    const base = {
+      page: entry,
+      role,
+      path: null,
+      viewport: { width: opts.width, height: opts.height },
+      size: null,
+      bytes: 0,
+      full: opts.full,
+      ms: 0,
+      handlersStubbed: [],
+      handlersWithoutFixture: [],
+      handlersRefused: []
+    };
+    if (role !== NO_ROLE && !maySeePage(opts.manifest, role, entry)) {
+      shots[index2] = { ...base, skipped: `${role} may not open this page` };
+      return;
+    }
+    const remaining = budgetUntil - now();
+    if (remaining <= 1e3) {
+      shots[index2] = { ...base, skipped: "the screenshot budget ran out" };
+      return;
+    }
+    const t0 = now();
+    const pageUntil = Math.min(t0 + shotTimeout, budgetUntil);
+    const attemptMs = () => Math.max(500, Math.min(ATTEMPT_MS, Math.ceil(shotTimeout / 2), pageUntil - now()));
+    let height = opts.height;
+    if (opts.full) {
+      const mid = nextId++;
+      stub.register(mid, { role, measure: true });
+      const measured = await runChrome({
+        chrome: opts.chrome,
+        url: stub.urlFor(mid, entry),
+        width: opts.width,
+        height: opts.height,
+        timeoutMs: Math.min(MEASURE_MS, attemptMs())
+      });
+      const found = /id="dr-shot-height"[^>]*content="(\d+)"|content="(\d+)"[^>]*id="dr-shot-height"/.exec(
+        measured.stdout
+      );
+      const tall = Number(found?.[1] ?? found?.[2] ?? NaN);
+      if (Number.isFinite(tall)) height = Math.min(FULL_HEIGHT_CAP, Math.max(opts.height, tall));
+    }
+    const out = join17(opts.outDir, file);
+    let id = -1;
+    let result;
+    for (let attempt = 0; attempt < 2 && now() < pageUntil - 500; attempt++) {
+      id = nextId++;
+      stub.register(id, { role });
+      await rm5(out, { force: true });
+      result = await runChrome({
+        chrome: opts.chrome,
+        url: stub.urlFor(id, entry),
+        width: opts.width,
+        height,
+        timeoutMs: attemptMs(),
+        out
+      });
+      if (result.ok) break;
+    }
+    if (result === void 0) {
+      shots[index2] = { ...base, skipped: "the screenshot budget ran out" };
+      return;
+    }
+    const calls = stub.calls(id);
+    const entryOut = {
+      ...base,
+      viewport: { width: opts.width, height },
+      ms: now() - t0,
+      handlersStubbed: calls.answered,
+      handlersWithoutFixture: calls.noFixture,
+      handlersRefused: calls.refused
+    };
+    if (!result.ok) {
+      shots[index2] = { ...entryOut, error: result.error ?? "no picture" };
+      return;
+    }
+    const bytes = await readFile12(out);
+    shots[index2] = { ...entryOut, path: file, size: pngSize(bytes), bytes: bytes.length };
+  };
+  try {
+    let cursor = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(opts.concurrency ?? SHOT_CONCURRENCY, plan.length)) }, async () => {
+      while (cursor < plan.length) {
+        const index2 = cursor++;
+        await one(index2);
+      }
+    });
+    await Promise.all(workers);
+  } finally {
+    await stub.close();
+  }
+  const index = {
+    version: 1,
+    app: opts.appId,
+    pagesFrom: opts.pagesFrom,
+    shelf: opts.shelf.kind === "server" ? { kind: "server", url: opts.shelf.baseUrl } : { kind: "local", path: opts.shelf.root },
+    shelfMisses: [...shelf2.misses].sort(),
+    chrome: opts.chrome,
+    roles: opts.roles,
+    fixtures: Object.fromEntries([...answers].map(([name, answer]) => [name, answer.from])),
+    createdAt: new Date(started).toISOString(),
+    ms: now() - started,
+    shots
+  };
+  await writeFile9(join17(opts.outDir, "index.json"), JSON.stringify(index, null, 2) + "\n");
+  return index;
+}
+async function readLocalUi(dir) {
+  const root = join17(dir, "ui");
+  const out = {};
+  const walk5 = async (folder) => {
+    let names;
+    try {
+      names = await readdir3(folder, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const one of names) {
+      const full = join17(folder, one.name);
+      if (one.isDirectory()) await walk5(full);
+      else if (one.isFile()) out[relative3(root, full).split(sep6).join("/")] = await readFile12(full);
+    }
+  };
+  await walk5(root);
+  return out;
+}
+function looksLikeShelf(root) {
+  return existsSync3(join17(root, "vendor"));
+}
+function renderShotTable(index, outDir) {
+  const rows2 = index.shots.map((shot) => [
+    shot.page,
+    shot.role,
+    shot.path === null ? "-" : shot.size === null ? "?" : `${String(shot.size.width)}x${String(shot.size.height)}`,
+    shot.path === null ? "" : `${(shot.ms / 1e3).toFixed(1)}s`,
+    shot.path ?? (shot.skipped !== void 0 ? `skipped: ${shot.skipped}` : `failed: ${shot.error ?? "?"}`)
+  ]);
+  const head = ["page", "role", "size", "time", "file"];
+  const widths = head.map((h, i) => Math.max(h.length, ...rows2.map((row) => (row[i] ?? "").length)));
+  const line2 = (cells) => "  " + cells.map((cell, i) => i === cells.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)).join("  ") + "\n";
+  const written = index.shots.filter((shot) => shot.path !== null).length;
+  let out = `
+screenshots \u2192 ${outDir}  (${String(written)} of ${String(index.shots.length)} written in ${(index.ms / 1e3).toFixed(1)}s; pages from the ${index.pagesFrom === "pushed" ? "pushed package" : "local ui/ folder"})
+`;
+  out += line2(head);
+  for (const row of rows2) out += line2(row);
+  const noFixture = [...new Set(index.shots.flatMap((shot) => shot.handlersWithoutFixture))].sort();
+  if (noFixture.length > 0) {
+    out += `  no tests.json fixture (answered []): ${noFixture.join(", ")}
+`;
+  }
+  if (index.shelfMisses.length > 0) {
+    out += `  not on the shelf (${index.shelf.kind === "server" ? index.shelf.url : index.shelf.path}): ${index.shelfMisses.slice(0, 5).join(", ")}${index.shelfMisses.length > 5 ? ", \u2026" : ""}
+`;
+  }
+  out += `  index: ${join17(outDir, "index.json")}
+`;
+  return out;
+}
+
 // src/commands/appspace/_roles.ts
 var PREVIEW_ROLE_HEADER = "x-app-space-preview-role";
 function asAllowed(raw) {
@@ -33588,16 +34231,15 @@ var SEE = {
 };
 var NO_COMPONENTS = "This page did not load dr-components; compile it again with the current CLI.";
 var NO_PART = (type) => `${type} is not a part this page's dr-components draws.`;
-var EMBEDDED = /<script\b[^>]*\bid\s*=\s*["']dr-contract["'][^>]*>([\s\S]*?)<\/script>/i;
 function pushedContract(bundle, pages) {
   const order2 = [...pages, ...Object.keys(bundle).filter((path3) => !pages.includes(path3))];
   for (const path3 of order2) {
     const html = bundle[path3];
     if (typeof html !== "string") continue;
-    const found = EMBEDDED.exec(html);
+    const found = contractBlockText(html);
     if (found === null) continue;
     try {
-      const parsed = JSON.parse(found[1] ?? "");
+      const parsed = JSON.parse(found);
       if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
         return parsed;
       }
@@ -34720,6 +35362,23 @@ function formatFindings(findings) {
 }
 
 // src/commands/appspace/test.ts
+function positiveInt(raw, fallback, flag) {
+  const value = raw === void 0 ? fallback : Number.parseInt(raw, 10);
+  if (!Number.isFinite(value) || value <= 0 || raw !== void 0 && !/^\d+$/.test(raw.trim())) {
+    throw new Error(`${flag} must be a positive whole number.`);
+  }
+  return value;
+}
+function collectRoles(value, previous = []) {
+  return [...previous, ...value.split(",").map((one) => one.trim()).filter((one) => one !== "")];
+}
+async function readLocalManifest(dir) {
+  try {
+    return JSON.parse(await readFile13(join18(dir, "manifest.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
 var DEFAULT_FIXTURES = "tests.json";
 function orderPages(paths) {
   const html = paths.filter((path3) => /\.html?$/i.test(path3) && isUiEntry(path3));
@@ -34766,7 +35425,8 @@ async function readAppFacts(client, appId) {
     pages: orderPages(files),
     bundle,
     handlerCode,
-    handlers
+    handlers,
+    ...pkg.manifest === void 0 ? {} : { manifest: pkg.manifest }
   };
 }
 var UI_BUDGET_MS = 21e4;
@@ -34854,10 +35514,10 @@ function evaluateCase(kase, res) {
   return problems;
 }
 async function loadFixtures(dir, explicit) {
-  const path3 = explicit ?? join17(dir, DEFAULT_FIXTURES);
+  const path3 = explicit ?? join18(dir, DEFAULT_FIXTURES);
   let raw;
   try {
-    raw = await readFile12(path3, "utf8");
+    raw = await readFile13(path3, "utf8");
   } catch {
     if (explicit !== void 0) throw new Error(`no fixtures file at ${path3}.`);
     return { fixtures: { cases: [], ui: { entry: "index.html" } } };
@@ -34878,7 +35538,7 @@ async function runHandlerCases(cases, dir, appId, client, roleOf = () => void 0)
     if (!code.has(kase.handler)) {
       code.set(
         kase.handler,
-        await readFile12(join17(dir, "handlers", `${kase.handler}.py`), "utf8").catch(() => null)
+        await readFile13(join18(dir, "handlers", `${kase.handler}.py`), "utf8").catch(() => null)
       );
     }
     const source = code.get(kase.handler);
@@ -35133,7 +35793,7 @@ function contractUid(contract, page, component) {
 }
 async function isDashboardFolder2(dir) {
   try {
-    const doc = JSON.parse(await readFile12(join17(dir, "contract.json"), "utf8"));
+    const doc = JSON.parse(await readFile13(join18(dir, "contract.json"), "utf8"));
     return doc.app?.kind === "dashboard";
   } catch {
     return false;
@@ -35334,7 +35994,7 @@ function mergeDomComponents(contract, components, page) {
 async function writeMergedContract(dir, page, components) {
   let contract;
   try {
-    contract = JSON.parse(await readFile12(contractPath(dir), "utf8"));
+    contract = JSON.parse(await readFile13(contractPath(dir), "utf8"));
   } catch {
     contract = await extractContract(dir);
   }
@@ -35344,7 +36004,7 @@ async function writeMergedContract(dir, page, components) {
 async function uiIsStale(dir, entry, stored) {
   if (stored === void 0) return false;
   try {
-    const local = await readFile12(join17(dir, "ui", entry));
+    const local = await readFile13(join18(dir, "ui", entry));
     return !local.equals(Buffer.from(stored, "utf8"));
   } catch {
     return false;
@@ -35432,7 +36092,7 @@ function untouchedHandlers(declared, cases, interactions, runs = []) {
 async function readSeed(dir) {
   let parsed;
   try {
-    parsed = JSON.parse(await readFile12(join17(dir, "seed.json"), "utf8"));
+    parsed = JSON.parse(await readFile13(join18(dir, "seed.json"), "utf8"));
   } catch {
     return null;
   }
@@ -35448,7 +36108,7 @@ async function readSeed(dir) {
 }
 async function handlerOwnership(dir, pushed) {
   try {
-    const local = JSON.parse(await readFile12(join17(dir, "contract.json"), "utf8"));
+    const local = JSON.parse(await readFile13(join18(dir, "contract.json"), "utf8"));
     const handlers2 = local.data?.app?.handlers;
     if (typeof handlers2 === "object" && handlers2 !== null) return handlers2;
   } catch {
@@ -35564,6 +36224,20 @@ function registerTestCommand(parent) {
       ).option("--keep-test-rows", "Keep the rows this run wrote, even on a draft.").option(
         "--contract",
         "Fold the rendered page's data-dr-* components into .appspace/contract.json, so the record says what the app DREW as well as what it declares."
+      ).option(
+        "--screenshot",
+        "After the checks, draw every pushed page once per declared role in headless Google Chrome and write <out>/<page>.<role>.png plus index.json. The pages load from a local stub (127.0.0.1) that answers /access as each role and every handler from its tests.json fixture ([] when none): no row is written. Needs Chrome on PATH or CHROME_PATH; nothing is downloaded."
+      ).option("--out <dir>", "Where --screenshot writes (default: <dir>/.screenshots).").option(
+        "--role <name>",
+        "With --screenshot: draw only this declared role (repeatable, or comma-separated). Default: every declared role.",
+        collectRoles
+      ).option("--width <px>", "With --screenshot: the window width.", "1400").option("--height <px>", "With --screenshot: the window height.", "900").option("--full", "With --screenshot: grow the window to the page\u2019s full height (one extra load per picture).").option(
+        "--shelf <path>",
+        "With --screenshot: serve vendor/ and ui-kit/ from this dr-app-space checkout instead of the server the app is pushed to (for offline use)."
+      ).option(
+        "--screenshot-budget <ms>",
+        `With --screenshot: the most the whole screenshot phase may take; each picture is capped at 60s.`,
+        String(SHOT_BUDGET_MS)
       )
     )
   ).action(async (dirArg, opts) => {
@@ -35580,10 +36254,30 @@ function registerTestCommand(parent) {
     }
     const mode = parseInteractMode(opts.interact);
     const as = opts.as === void 0 ? void 0 : opts.as.trim();
+    let chrome = null;
+    let shotSize = { width: 0, height: 0, budget: 0 };
+    if (opts.screenshot === true) {
+      chrome = findChrome();
+      if (chrome === null) {
+        process.stderr.write(`error: ${CHROME_MISSING}
+`);
+        process.exitCode = 2;
+        return;
+      }
+      shotSize = {
+        width: positiveInt(opts.width, 1400, "--width"),
+        height: positiveInt(opts.height, 900, "--height"),
+        budget: positiveInt(opts.screenshotBudget, SHOT_BUDGET_MS, "--screenshot-budget")
+      };
+      if (opts.shelf !== void 0 && !looksLikeShelf(opts.shelf)) {
+        throw new Error(`--shelf ${opts.shelf}: no vendor/ folder there; point it at a dr-app-space checkout.`);
+      }
+    }
     const client = await connect(opts);
     try {
       const view = await readRoleView(client, appId);
       if (as !== void 0) requireDeclaredRole(as, view);
+      if (chrome !== null && view.roles.length > 0) shotRoles({ roles: view.roles.map((name) => ({ name })) }, opts.role ?? []);
       const roleOf = (handler) => as ?? roleForHandler(handler, view);
       const clock = await readServerClock(client, appId);
       const outcomes = opts.skipHandlers === true ? [] : await runHandlerCases(fixtures.cases, dir, appId, client, roleOf);
@@ -35718,6 +36412,33 @@ function registerTestCommand(parent) {
       skipped.push(...findingsNotChecked(facts !== void 0, pushed));
       skipped.push(...leversNotChecked(opts.skipUi === true && !await isDashboardFolder2(dir), runs, pushed));
       const parts = facts === void 0 ? null : partsSummary(pushed, facts.bundle, facts.handlerCode);
+      let shots;
+      if (chrome !== null) {
+        const pushedPages = store.problem === void 0 && store.pages.length > 0;
+        const files = pushedPages ? store.bundle : await readLocalUi(dir);
+        const pages = pushedPages ? store.pages : orderPages(Object.keys(files));
+        const manifest = pushedPages && typeof store.manifest === "object" && store.manifest !== null ? store.manifest : await readLocalManifest(dir);
+        const outDir = resolve16(opts.out ?? join18(dir, ".screenshots"));
+        const index = await runScreenshots({
+          appId,
+          pages: choosePages(opts.pages, pages, fixtures.ui.entry).load,
+          files,
+          pagesFrom: pushedPages ? "pushed" : "local",
+          manifest,
+          roles: shotRoles(manifest, opts.role ?? []),
+          allowedByRole: view.allowed,
+          sources: Object.keys(pushed?.data?.sources ?? {}),
+          cases: fixtures.cases,
+          shelf: opts.shelf === void 0 ? { kind: "server", baseUrl: client.baseUrl } : { kind: "local", root: resolve16(opts.shelf) },
+          chrome,
+          outDir,
+          width: shotSize.width,
+          height: shotSize.height,
+          full: opts.full === true,
+          budgetMs: shotSize.budget
+        });
+        shots = { index, outDir };
+      }
       const handlerFailures = outcomes.filter((o) => !o.ok).length;
       const smokeFailures = runs.reduce(
         (total, run) => total + failedCalls(run.report).length + run.report.consoleErrors.length + run.report.pageErrors.length + (run.report.interactions ?? []).filter((one) => one.problems.length > 0).length,
@@ -35773,6 +36494,8 @@ function registerTestCommand(parent) {
           parts,
           // The test rows the run found, removed, and left (`_testRows.ts`).
           rows: rows2,
+          // `--screenshot`: the same document as <out>/index.json, or null.
+          screenshots: shots === void 0 ? null : { ...shots.index, outDir: shots.outDir },
           strict: opts.strict === true,
           passed: outcomes.length - handlerFailures,
           failed,
@@ -35800,6 +36523,7 @@ ${String(failed)} failure(s).
       out += rowsLine(rows2);
       out += formatSkipped(skipped);
       if (facts !== void 0) out += formatPartsSummary(parts);
+      if (shots !== void 0) out += renderShotTable(shots.index, shots.outDir);
       out += formatFindings(findings);
       process.stdout.write(out);
       if (exitCodeFor(failed, findings, opts.strict === true) !== 0) process.exitCode = 1;
@@ -35810,12 +36534,12 @@ ${String(failed)} failure(s).
 }
 
 // src/commands/appspace/try.ts
-import { readFile as readFile13 } from "fs/promises";
-import { join as join18 } from "path";
+import { readFile as readFile14 } from "fs/promises";
+import { join as join19 } from "path";
 function collect2(value, previous = []) {
   return [...previous, value];
 }
-async function readPayloadOption(raw, read = (path3) => readFile13(path3, "utf8")) {
+async function readPayloadOption(raw, read = (path3) => readFile14(path3, "utf8")) {
   if (raw.startsWith("@")) {
     const path3 = raw.slice(1);
     if (path3 === "") throw new Error("--payload @ names no file; write --payload @./payload.json.");
@@ -35890,8 +36614,8 @@ function registerTryCommand(parent) {
   ).action(async (handler, opts) => {
     requirePlainName("handler", handler, "read");
     const appId = await readManifestId(opts.dir);
-    const code = await readFile13(
-      join18(opts.dir, "handlers", `${handler}.py`),
+    const code = await readFile14(
+      join19(opts.dir, "handlers", `${handler}.py`),
       "utf8"
     ).catch(() => {
       throw new Error(
@@ -36012,8 +36736,8 @@ function registerPublishCommands(parent) {
 }
 
 // src/commands/appspace/scaffold.ts
-import { mkdir as mkdir8, readdir as readdir3, stat as stat2, writeFile as writeFile9 } from "fs/promises";
-import { dirname as dirname9, join as join19 } from "path";
+import { mkdir as mkdir9, readdir as readdir4, stat as stat3, writeFile as writeFile10 } from "fs/promises";
+import { dirname as dirname9, join as join20 } from "path";
 
 // src/commands/appspace/starters.ts
 var STARTER_KINDS = ["dashboard", "app"];
@@ -36350,7 +37074,7 @@ async function checkTarget(dir, force) {
   if (force) return;
   let entries;
   try {
-    entries = await readdir3(dir);
+    entries = await readdir4(dir);
   } catch (err) {
     if (err.code === "ENOENT") return;
     throw new Error(
@@ -36370,7 +37094,7 @@ async function existingFiles(dir, relPaths) {
   const present = [];
   for (const rel of relPaths) {
     try {
-      await stat2(join19(dir, rel));
+      await stat3(join20(dir, rel));
       present.push(rel);
     } catch {
     }
@@ -36409,13 +37133,13 @@ function registerScaffoldCommand(parent) {
       const table = ownsData ? (opts.table ?? DEFAULT_TABLE).trim() : void 0;
       const record2 = ownsData ? ((opts.record ?? "").trim() || singularize(table ?? DEFAULT_TABLE)).trim() : void 0;
       checkNames({ id, table, record: record2 });
-      const dir = (dirArg ?? "").trim() || join19(".", id);
+      const dir = (dirArg ?? "").trim() || join20(".", id);
       await checkTarget(dir, opts.force === true);
       const contract = starterContract(kind, { id, name, table, record: record2 });
       const overwritten = opts.force === true ? await existingFiles(dir, [CONTRACT_FILE]) : [];
-      const target = join19(dir, CONTRACT_FILE);
-      await mkdir8(dirname9(target), { recursive: true });
-      await writeFile9(target, `${JSON.stringify(contract, null, 2)}
+      const target = join20(dir, CONTRACT_FILE);
+      await mkdir9(dirname9(target), { recursive: true });
+      await writeFile10(target, `${JSON.stringify(contract, null, 2)}
 `);
       if (opts.json === true) {
         printJson({ id, name, dir, kind, table, record: record2, files: [CONTRACT_FILE], overwritten });
@@ -36528,40 +37252,40 @@ function registerAppSpaceCommand(root) {
 }
 
 // src/commands/update.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 var REGISTRY = "https://datarails.jfrog.io/artifactory/api/npm/dr-cli-virtual";
 var PACKAGE = "@datarails-ai/dr-appspace-cli";
 function spawnInherit(command, args) {
-  return new Promise((resolve15) => {
-    const child = spawn(command, args, {
+  return new Promise((resolve17) => {
+    const child = spawn2(command, args, {
       stdio: "inherit",
       // Windows resolves `npm` as `npm.cmd`; `shell: true` lets cmd.exe do
       // the resolution without us having to special-case the suffix.
       shell: true
     });
     child.on("close", (code) => {
-      resolve15(code ?? 1);
+      resolve17(code ?? 1);
     });
     child.on("error", () => {
-      resolve15(1);
+      resolve17(1);
     });
   });
 }
 function captureVersion() {
-  return new Promise((resolve15) => {
-    const child = spawn("dr-appspace", ["--version"], { shell: true });
+  return new Promise((resolve17) => {
+    const child = spawn2("dr-appspace", ["--version"], { shell: true });
     let out = "";
     child.stdout.on("data", (chunk) => {
       out += chunk.toString();
     });
     child.on("close", (code) => {
       if (code !== 0) {
-        resolve15(null);
+        resolve17(null);
         return;
       }
-      resolve15(out.trim());
+      resolve17(out.trim());
     });
-    child.on("error", () => resolve15(null));
+    child.on("error", () => resolve17(null));
   });
 }
 async function runUpdate() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-appspace-cli",
-  "version": "0.12.32",
+  "version": "0.12.34",
   "description": "Datarails App Space CLI — build, try, push and publish App Space apps",
   "type": "module",
   "engines": {