@treeseed/sdk 0.11.0 → 0.12.4

package/dist/scenes/types.js

@@ -0,0 +1,8 @@
+const TREESEED_SCENE_SCHEMA_VERSION = "treeseed.scene/v1";
+const TREESEED_SCENE_ENVIRONMENTS = ["local", "staging", "prod"];
+const TREESEED_SCENE_BROWSERS = ["chromium", "firefox", "webkit"];
+export {
+  TREESEED_SCENE_BROWSERS,
+  TREESEED_SCENE_ENVIRONMENTS,
+  TREESEED_SCENE_SCHEMA_VERSION
+};

package/dist/scenes/visual-audit-contact-sheets.d.ts

@@ -0,0 +1,6 @@
+import type { TreeseedSceneVisualAuditManifest, TreeseedSceneVisualAuditPaths, TreeseedSceneVisualAuditReview } from './types.js';
+export declare function writeTreeseedSceneVisualAuditContactSheets(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    review: TreeseedSceneVisualAuditReview;
+    paths: TreeseedSceneVisualAuditPaths;
+}): void;

package/dist/scenes/visual-audit-contact-sheets.js

@@ -0,0 +1,119 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+function esc(value) {
+  return String(value ?? "").replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}
+function slug(value) {
+  return value === "/" ? "root" : value.replace(/^\/+|\/+$/gu, "").replace(/[^a-z0-9]+/giu, "-").toLowerCase() || "root";
+}
+function rel(from, path) {
+  return path ? relative(from, path) : "";
+}
+function styles() {
+  return `<style>
+body{margin:0;background:#0f172a;color:#e2e8f0;font:14px/1.45 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+a{color:#38bdf8}
+header{position:sticky;top:0;background:#111827f2;border-bottom:1px solid #334155;padding:16px 22px;z-index:2}
+h1{margin:0 0 8px;font-size:22px} h2{margin:28px 22px 12px;font-size:18px}
+.meta{color:#cbd5e1}.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:16px;padding:0 22px 24px}
+.card{background:#1e293b;border:1px solid #334155;border-radius:8px;overflow:hidden;box-shadow:0 12px 30px #0004}
+.shot{display:block;background:#020617;aspect-ratio:16/10;overflow:hidden}.shot img{width:100%;height:100%;object-fit:contain;display:block}
+.body{padding:12px}.path{font-weight:700;color:#f8fafc}.sub{color:#cbd5e1;font-size:12px;margin-top:4px}.badges{display:flex;gap:6px;flex-wrap:wrap;margin-top:8px}
+.badge{font-size:11px;border-radius:999px;padding:3px 8px;background:#334155;color:#e2e8f0}.blocking,.high{background:#7f1d1d;color:#fecaca}.medium{background:#78350f;color:#fde68a}.low{background:#164e63;color:#bae6fd}.info{background:#365314;color:#d9f99d}
+.finding{font-size:12px;margin-top:8px;color:#f8fafc}.empty{padding:22px;color:#cbd5e1}
+.action{font-size:12px;margin-top:8px;color:#cbd5e1}.rank{background:#0f766e;color:#ccfbf1}.owner{background:#312e81;color:#ddd6fe}
+nav{display:flex;gap:10px;flex-wrap:wrap;margin-top:8px}
+nav a{border:1px solid #334155;border-radius:999px;padding:4px 10px;text-decoration:none;color:#e2e8f0}
+</style>`;
+}
+function renderPage(input) {
+  const reviewRoot = input.paths.reviewRoot;
+  const findingsByCapture = /* @__PURE__ */ new Map();
+  for (const finding of input.findings) {
+    const list = findingsByCapture.get(finding.captureId) ?? [];
+    list.push(finding);
+    findingsByCapture.set(finding.captureId, list);
+  }
+  const nav = [
+    `<a href="index.html">All</a>`,
+    `<a href="flagged.html">Flagged</a>`,
+    ...input.allRoots.map((root) => `<a href="${slug(root)}.html">${esc(root)}</a>`)
+  ].join("");
+  const cards = input.captures.map((capture) => {
+    const list = findingsByCapture.get(capture.id) ?? [];
+    const image = capture.screenshotPath ? rel(reviewRoot, capture.screenshotPath) : "";
+    const badges = list.slice(0, 5).map((finding) => `<span class="badge ${esc(finding.severity)}">${esc(finding.severity)} ${esc(finding.code.replace(/^visual\./u, ""))}</span>`).join("");
+    const findingText = list[0] ? `<div class="finding">${esc(list[0].message)}</div>` : "";
+    return `<article class="card">
+${image ? `<a class="shot" href="${esc(image)}"><img src="${esc(image)}" alt="${esc(capture.path)} ${esc(capture.role)} ${esc(capture.device)}"></a>` : '<div class="shot empty">No screenshot</div>'}
+<div class="body">
+<div class="path">${esc(capture.path)}</div>
+<div class="sub">${esc(capture.role)} / ${esc(capture.device)} / ${esc(capture.status)} / ${esc(capture.finalUrl ?? capture.url)}</div>
+${badges ? `<div class="badges">${badges}</div>` : ""}
+${findingText}
+</div>
+</article>`;
+  }).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(input.title)}</title>${styles()}</head>
+<body>
+<header>
+<h1>${esc(input.title)}</h1>
+<div class="meta">Scene ${esc(input.manifest.sceneId)} / audit ${esc(input.manifest.auditId)} / captures ${input.captures.length} / findings ${input.findings.length}</div>
+<nav>${nav}</nav>
+</header>
+${cards ? `<main class="grid">${cards}</main>` : '<main class="empty">No captures in this sheet.</main>'}
+</body>
+</html>
+`;
+}
+function renderRootCausePage(input) {
+  const reviewRoot = input.paths.reviewRoot;
+  const nav = `<a href="index.html">All</a><a href="flagged.html">Flagged</a><a href="root-causes.html">Root causes</a>`;
+  const cards = input.rootCauses.map((entry) => {
+    const image = entry.exampleScreenshotPath ? rel(reviewRoot, entry.exampleScreenshotPath) : "";
+    return `<article class="card" id="${esc(entry.id)}">
+${image ? `<a class="shot" href="${esc(image)}"><img src="${esc(image)}" alt="${esc(entry.title)}"></a>` : '<div class="shot empty">No screenshot</div>'}
+<div class="body">
+<div class="path">#${esc(entry.priorityRank)} ${esc(entry.title)}</div>
+<div class="sub">${esc(entry.suspectedOwner)} / ${esc(entry.severity)} / score ${esc(entry.priorityScore)} / count ${esc(entry.count)}</div>
+<div class="badges"><span class="badge rank">rank ${esc(entry.priorityRank)}</span><span class="badge owner">${esc(entry.suspectedOwner)}</span><span class="badge ${esc(entry.severity)}">${esc(entry.severity)}</span></div>
+<div class="finding">${esc(entry.paths.slice(0, 8).join(", "))}</div>
+<div class="action">${esc(entry.recommendedAction)}</div>
+</div>
+</article>`;
+  }).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Visual Audit Root Causes</title>${styles()}</head>
+<body>
+<header>
+<h1>Visual Audit Root Causes</h1>
+<div class="meta">Scene ${esc(input.manifest.sceneId)} / audit ${esc(input.manifest.auditId)} / root causes ${input.rootCauses.length}</div>
+<nav>${nav}</nav>
+</header>
+${cards ? `<main class="grid">${cards}</main>` : '<main class="empty">No root causes.</main>'}
+</body>
+</html>
+`;
+}
+function writeTreeseedSceneVisualAuditContactSheets(input) {
+  if (!input.paths.reviewRoot) return;
+  const root = `${input.paths.reviewRoot}/contact-sheets`;
+  mkdirSync(root, { recursive: true });
+  const roots = [...new Set(input.manifest.routes.map((route) => route.pathRoot))].sort();
+  const write = (name, title, captures, findings = input.review.findings) => {
+    writeFileSync(`${root}/${name}.html`, renderPage({ title, manifest: input.manifest, paths: input.paths, captures, findings, allRoots: roots }), "utf8");
+  };
+  write("index", "Visual Audit Contact Sheets", input.manifest.captures);
+  const flaggedIds = new Set(input.review.findings.map((finding) => finding.captureId));
+  write("flagged", "Flagged Visual Audit Captures", input.manifest.captures.filter((capture) => flaggedIds.has(capture.id)));
+  writeFileSync(`${root}/root-causes.html`, renderRootCausePage({ manifest: input.manifest, paths: input.paths, rootCauses: input.review.rootCauses }), "utf8");
+  for (const pathRoot of roots) {
+    write(slug(pathRoot), `Visual Audit ${pathRoot}`, input.manifest.captures.filter((capture) => capture.pathRoot === pathRoot));
+  }
+}
+export {
+  writeTreeseedSceneVisualAuditContactSheets
+};

package/dist/scenes/visual-audit-fixtures.d.ts

@@ -0,0 +1,25 @@
+import type { TreeseedSceneDiagnostic, TreeseedSceneVisualAuditRole } from './types.js';
+export declare const TREESEED_VISUAL_AUDIT_PASSWORD = "TreeSeedVisualAudit!2026";
+export declare const TREESEED_VISUAL_AUDIT_USERS: Record<string, {
+    email: string;
+    password: string;
+    label: string;
+}>;
+export declare function treeseedSceneVisualAuditUserForRole(role: TreeseedSceneVisualAuditRole): {
+    email: string;
+    password: string;
+    label: string;
+};
+export declare function validateTreeseedSceneVisualAuditRoles(roles: TreeseedSceneVisualAuditRole[]): TreeseedSceneDiagnostic[];
+export declare function ensureTreeseedSceneVisualAuditRoleFixtures(input: {
+    baseUrl: string;
+    roles: TreeseedSceneVisualAuditRole[];
+    projectRoot?: string;
+    environment?: string;
+}): Promise<TreeseedSceneDiagnostic[]>;
+export declare function signInTreeseedSceneVisualAuditRole(input: {
+    page: any;
+    baseUrl: string;
+    apiBaseUrl?: string | null;
+    role: TreeseedSceneVisualAuditRole;
+}): Promise<TreeseedSceneDiagnostic[]>;

package/dist/scenes/visual-audit-fixtures.js

@@ -0,0 +1,210 @@
+import { sceneErrorDiagnostic, sceneWarningDiagnostic } from "./diagnostics.js";
+import { MarketClient, MarketClientError } from "../market-client.js";
+import { resolveTreeseedMachineEnvironmentValues } from "../operations/services/config-runtime.js";
+const TREESEED_VISUAL_AUDIT_PASSWORD = "TreeSeedVisualAudit!2026";
+const TREESEED_VISUAL_AUDIT_USERS = {
+  owner: { email: "visual.owner@treeseed.io", password: TREESEED_VISUAL_AUDIT_PASSWORD, label: "Visual Audit Owner" },
+  admin: { email: "visual.admin@treeseed.io", password: TREESEED_VISUAL_AUDIT_PASSWORD, label: "Visual Audit Admin" },
+  member: { email: "visual.member@treeseed.io", password: TREESEED_VISUAL_AUDIT_PASSWORD, label: "Visual Audit Member" }
+};
+function treeseedSceneVisualAuditUserForRole(role) {
+  return TREESEED_VISUAL_AUDIT_USERS[role] ?? null;
+}
+function validateTreeseedSceneVisualAuditRoles(roles) {
+  const diagnostics = [];
+  for (const role of roles) {
+    if (role === "anonymous") continue;
+    if (!treeseedSceneVisualAuditUserForRole(role)) {
+      diagnostics.push(sceneWarningDiagnostic("scene.visual_audit_role_unknown", `Visual audit role "${role}" has no built-in fixture login. Routes for this role will be skipped unless a future fixture provider supplies it.`, "roles"));
+    }
+  }
+  return diagnostics;
+}
+function usernameForRole(role) {
+  return `visual-${role}`;
+}
+function clientFor(baseUrl, accessToken) {
+  return new MarketClient({
+    profile: {
+      id: "visual-audit-local",
+      label: "Visual audit local",
+      baseUrl,
+      kind: "specialized"
+    },
+    accessToken: accessToken ?? void 0,
+    userAgent: "treeseed-scene-visual-audit"
+  });
+}
+function isAuthFailure(error) {
+  if (error instanceof MarketClientError) return error.status === 400 || error.status === 401 || error.status === 403 || error.status === 409;
+  return false;
+}
+function configuredValue(input, name) {
+  const envValue = process.env[name];
+  if (typeof envValue === "string" && envValue.trim()) return envValue.trim();
+  if (!input?.projectRoot || !input.environment) return null;
+  try {
+    const values = resolveTreeseedMachineEnvironmentValues(input.projectRoot, input.environment);
+    const value = values?.[name];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+  } catch {
+    return null;
+  }
+}
+function serviceHeaders(input) {
+  return {
+    "content-type": "application/json",
+    "x-treeseed-service-id": configuredValue(input, "TREESEED_API_WEB_SERVICE_ID") ?? configuredValue(input, "TREESEED_WEB_SERVICE_ID") ?? "web",
+    "x-treeseed-service-secret": configuredValue(input, "TREESEED_API_WEB_SERVICE_SECRET") ?? configuredValue(input, "TREESEED_WEB_SERVICE_SECRET") ?? "treeseed-web-service-dev-secret"
+  };
+}
+function seedActorsForRoles(roles) {
+  const actors = {};
+  for (const role of roles) {
+    const user = treeseedSceneVisualAuditUserForRole(role);
+    if (!user) continue;
+    actors[role] = {
+      email: user.email,
+      username: usernameForRole(role),
+      displayName: user.label,
+      siteRoles: role === "admin" ? ["member"] : ["member"],
+      teamRole: role === "owner" ? "team_owner" : role === "admin" ? "project_lead" : "contributor"
+    };
+  }
+  return actors;
+}
+async function seedVisualAuditFixtures(input) {
+  const actors = seedActorsForRoles(input.roles);
+  if (Object.keys(actors).length === 0) return [];
+  try {
+    const response = await fetch(new URL("/v1/acceptance/seed", input.baseUrl).toString(), {
+      method: "POST",
+      headers: serviceHeaders(input),
+      body: JSON.stringify({
+        namespace: "visual-audit",
+        password: TREESEED_VISUAL_AUDIT_PASSWORD,
+        actors
+      })
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      return [sceneWarningDiagnostic(
+        "scene.visual_audit_fixture_unavailable",
+        `Visual audit API fixture seed failed with HTTP ${response.status}: ${text.slice(0, 500)}`,
+        "roles"
+      )];
+    }
+    return [];
+  } catch (error) {
+    return [sceneWarningDiagnostic(
+      "scene.visual_audit_fixture_unavailable",
+      `Visual audit API fixture seed failed against ${input.baseUrl}: ${error instanceof Error ? error.message : String(error ?? "local fixture API is unavailable")}.`,
+      "roles"
+    )];
+  }
+}
+async function ensureTreeseedSceneVisualAuditRoleFixtures(input) {
+  const diagnostics = [];
+  const roles = [...new Set(input.roles)].filter((role) => role !== "anonymous");
+  diagnostics.push(...await seedVisualAuditFixtures({
+    baseUrl: input.baseUrl,
+    roles,
+    projectRoot: input.projectRoot,
+    environment: input.environment
+  }));
+  for (const role of roles) {
+    const user = treeseedSceneVisualAuditUserForRole(role);
+    if (!user) continue;
+    const client = clientFor(input.baseUrl);
+    try {
+      await client.webSignIn({ login: user.email, password: user.password });
+      continue;
+    } catch (error) {
+      if (!isAuthFailure(error)) {
+        diagnostics.push(sceneWarningDiagnostic(
+          "scene.visual_audit_fixture_unavailable",
+          `Visual audit fixture setup for ${role} failed against ${input.baseUrl}: ${error instanceof Error ? error.message : String(error ?? "local fixture API is unavailable")}. Authenticated screenshots require the local API and database to be healthy.`,
+          "roles"
+        ));
+        continue;
+      }
+    }
+    try {
+      const [firstName = "Visual", lastName = String(role)] = user.label.split(/\s+/u);
+      const signup = await client.webSignUp({
+        email: user.email,
+        username: usernameForRole(role),
+        password: user.password,
+        firstName,
+        lastName,
+        name: user.label
+      });
+      const payload = signup.payload;
+      if (payload.confirmationToken) {
+        await client.confirmWebEmail({ token: payload.confirmationToken });
+      } else if (payload.confirmationRequired) {
+        diagnostics.push(sceneWarningDiagnostic("scene.visual_audit_fixture_unavailable", `Visual audit fixture user ${user.email} requires email confirmation, but the local API did not return a confirmation token.`, "roles"));
+      }
+    } catch (error) {
+      try {
+        await client.webSignIn({ login: user.email, password: user.password });
+      } catch {
+        diagnostics.push(sceneWarningDiagnostic(
+          "scene.visual_audit_fixture_unavailable",
+          `Visual audit fixture setup for ${role} failed against ${input.baseUrl}: ${error instanceof Error ? error.message : String(error ?? "local fixture API is unavailable")}. Authenticated screenshots require the local API and database to be healthy.`,
+          "roles"
+        ));
+      }
+    }
+  }
+  return diagnostics;
+}
+async function signInTreeseedSceneVisualAuditRole(input) {
+  const user = treeseedSceneVisualAuditUserForRole(input.role);
+  if (!user) {
+    return [sceneErrorDiagnostic("scene.visual_audit_role_unknown", `Visual audit role "${input.role}" has no fixture login.`, "role")];
+  }
+  const apiBaseUrl = input.apiBaseUrl?.trim() || input.baseUrl;
+  try {
+    const session = await clientFor(apiBaseUrl).webSignIn({ login: user.email, password: user.password });
+    const accessToken = session.payload.accessToken;
+    if (accessToken) {
+      const webUrl = new URL(input.baseUrl);
+      await input.page.context().addCookies([{
+        name: "ts_market_api_access",
+        value: accessToken,
+        domain: webUrl.hostname,
+        path: "/",
+        httpOnly: true,
+        secure: webUrl.protocol === "https:",
+        sameSite: "Lax",
+        expires: Math.floor(Date.now() / 1e3) + Number(session.payload.expiresInSeconds ?? 900)
+      }]);
+      await input.page.goto(new URL("/app/", input.baseUrl).toString(), { waitUntil: "networkidle", timeout: 2e4 });
+      if (!/\/auth\/sign-in/u.test(input.page.url())) return [];
+    }
+  } catch {
+  }
+  try {
+    await input.page.goto(new URL("/auth/sign-in", input.baseUrl).toString(), { waitUntil: "networkidle", timeout: 2e4 });
+    await input.page.locator('input[name="login"], input[name="email"], input[name="emailOrUsername"], input[name="username"]').first().fill(user.email, { timeout: 5e3 });
+    await input.page.locator('input[name="password"]').first().fill(user.password, { timeout: 5e3 });
+    await input.page.getByRole("button", { name: /sign in/i }).click({ timeout: 5e3 });
+    await input.page.waitForLoadState("networkidle", { timeout: 5e3 }).catch(() => void 0);
+    const url = input.page.url();
+    if (/\/auth\/sign-in/u.test(url)) {
+      return [sceneWarningDiagnostic("scene.visual_audit_role_login_failed", `Visual audit login for ${input.role} did not leave the sign-in page. Ensure deterministic fixture user ${user.email} exists.`, "roles")];
+    }
+    return [];
+  } catch (error) {
+    return [sceneWarningDiagnostic("scene.visual_audit_role_login_failed", error instanceof Error ? error.message : String(error ?? `Visual audit login for ${input.role} failed.`), "roles")];
+  }
+}
+export {
+  TREESEED_VISUAL_AUDIT_PASSWORD,
+  TREESEED_VISUAL_AUDIT_USERS,
+  ensureTreeseedSceneVisualAuditRoleFixtures,
+  signInTreeseedSceneVisualAuditRole,
+  treeseedSceneVisualAuditUserForRole,
+  validateTreeseedSceneVisualAuditRoles
+};

package/dist/scenes/visual-audit-report.d.ts

@@ -0,0 +1,11 @@
+import type { TreeseedSceneVisualAuditManifest, TreeseedSceneVisualAuditPaths, TreeseedSceneVisualAuditReview } from './types.js';
+export declare function formatTreeseedSceneVisualAuditMarkdown(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    paths: TreeseedSceneVisualAuditPaths;
+    review?: TreeseedSceneVisualAuditReview | null;
+}): string;
+export declare function writeTreeseedSceneVisualAuditReport(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    paths: TreeseedSceneVisualAuditPaths;
+    review?: TreeseedSceneVisualAuditReview | null;
+}): void;

package/dist/scenes/visual-audit-report.js

@@ -0,0 +1,85 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+function md(value) {
+  return String(value ?? "").replace(/\|/gu, "\\|").replace(/\n/gu, " ");
+}
+function rel(root, path) {
+  return path ? relative(root, path) : "";
+}
+function firstDiagnostic(capture) {
+  return capture.diagnostics[0] ?? null;
+}
+function formatTreeseedSceneVisualAuditMarkdown(input) {
+  const { manifest, paths } = input;
+  const failed = manifest.captures.filter((capture) => capture.status === "failed");
+  const skipped = manifest.captures.filter((capture) => capture.status === "skipped");
+  const captured = manifest.captures.filter((capture) => capture.status === "captured");
+  const roots = [...new Set(manifest.routes.map((route) => route.pathRoot))].sort();
+  const lines = [
+    "# TreeSeed Scene Visual Audit",
+    "",
+    `Scene: ${manifest.sceneId ?? "(unknown)"}`,
+    `Audit: ${manifest.auditId}`,
+    `Base URL: ${manifest.baseUrl ?? "(unresolved)"}`,
+    `Generated: ${manifest.generatedAt}`,
+    "",
+    "## Summary",
+    "",
+    `- Roles: ${manifest.roles.join(", ") || "(none)"}`,
+    `- Devices: ${manifest.devices.join(", ") || "(none)"}`,
+    `- Routes: ${manifest.routes.length}`,
+    `- Captures: ${captured.length}`,
+    `- Failed: ${failed.length}`,
+    `- Skipped: ${skipped.length}`,
+    `- Review findings: ${input.review?.summary.findingCount ?? 0}`,
+    `- Root causes: ${input.review?.summary.rootCauseCount ?? 0}`,
+    `- Incidents: ${input.review?.summary.incidentCount ?? 0}`,
+    `- Raw client errors: ${input.review?.summary.clientErrorCount ?? 0}`,
+    ""
+  ];
+  if (input.review && paths.reviewRoot) {
+    lines.push("## Review", "");
+    lines.push(`- Agent brief: [review/agent-brief.md](${md(rel(paths.auditRoot, paths.reviewAgentBriefPath))})`);
+    lines.push(`- Issue index: [review/issue-index.json](${md(rel(paths.auditRoot, `${paths.reviewRoot}/issue-index.json`))})`);
+    lines.push(`- Top priority: [review/query/top-priority.json](${md(rel(paths.auditRoot, `${paths.reviewRoot}/query/top-priority.json`))})`);
+    lines.push(`- Root causes: [review/root-causes.json](${md(rel(paths.auditRoot, `${paths.reviewRoot}/root-causes.json`))})`);
+    lines.push(`- Incidents: [review/incidents.json](${md(rel(paths.auditRoot, `${paths.reviewRoot}/incidents.json`))})`);
+    lines.push(`- Findings JSON: [review/findings.json](${md(rel(paths.auditRoot, paths.reviewFindingsPath))})`);
+    lines.push(`- Contact sheets: [review/contact-sheets/index.html](${md(rel(paths.auditRoot, `${paths.reviewRoot}/contact-sheets/index.html`))})`);
+    lines.push(`- Flagged contact sheet: [review/contact-sheets/flagged.html](${md(rel(paths.auditRoot, `${paths.reviewRoot}/contact-sheets/flagged.html`))})`);
+    lines.push(`- Root-cause contact sheet: [review/contact-sheets/root-causes.html](${md(rel(paths.auditRoot, `${paths.reviewRoot}/contact-sheets/root-causes.html`))})`);
+    lines.push("");
+  }
+  lines.push("## By Path Root", "");
+  for (const root of roots) {
+    lines.push(`### ${root}`, "");
+    lines.push("| Role | Device | Path | Status | Screenshot |");
+    lines.push("| --- | --- | --- | --- | --- |");
+    const captures = manifest.captures.filter((capture) => capture.pathRoot === root).sort((a, b) => `${a.role}:${a.device}:${a.path}`.localeCompare(`${b.role}:${b.device}:${b.path}`));
+    for (const capture of captures) {
+      const screenshot = capture.screenshotPath ? `[view](${md(rel(paths.auditRoot, capture.screenshotPath))})` : "";
+      lines.push(`| ${md(capture.role)} | ${md(capture.device)} | ${md(capture.path)} | ${md(capture.status)} | ${screenshot} |`);
+    }
+    lines.push("");
+  }
+  lines.push("## Failures", "");
+  lines.push("| Role | Device | Path | Code | Message |");
+  lines.push("| --- | --- | --- | --- | --- |");
+  for (const capture of [...failed, ...skipped]) {
+    const diagnostic = firstDiagnostic(capture);
+    lines.push(`| ${md(capture.role)} | ${md(capture.device)} | ${md(capture.path)} | ${md(diagnostic?.code ?? capture.status)} | ${md(diagnostic?.message ?? capture.status)} |`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
+function writeTreeseedSceneVisualAuditReport(input) {
+  mkdirSync(input.paths.auditRoot, { recursive: true });
+  writeFileSync(input.paths.manifestPath, `${JSON.stringify(input.manifest, null, 2)}
+`, "utf8");
+  writeFileSync(input.paths.reportPath, formatTreeseedSceneVisualAuditMarkdown(input), "utf8");
+}
+export {
+  formatTreeseedSceneVisualAuditMarkdown,
+  writeTreeseedSceneVisualAuditReport
+};

package/dist/scenes/visual-audit-review.d.ts

@@ -0,0 +1,23 @@
+import type { TreeseedSceneVisualAuditClientError, TreeseedSceneVisualAuditManifest, TreeseedSceneVisualAuditPaths, TreeseedSceneVisualAuditReview, TreeseedSceneVisualAuditReviewDetail } from './types.js';
+export declare function isTreeseedSceneVisualAuditIgnoredClientError(error: Pick<TreeseedSceneVisualAuditClientError, 'url' | 'message'>): boolean;
+export declare function buildTreeseedSceneVisualAuditReview(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    paths: TreeseedSceneVisualAuditPaths;
+    detail?: TreeseedSceneVisualAuditReviewDetail;
+    maxFindings?: number;
+}): TreeseedSceneVisualAuditReview;
+export declare function formatTreeseedSceneVisualAuditFindingsMarkdown(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    review: TreeseedSceneVisualAuditReview;
+    paths: TreeseedSceneVisualAuditPaths;
+}): string;
+export declare function formatTreeseedSceneVisualAuditAgentBrief(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    review: TreeseedSceneVisualAuditReview;
+    paths: TreeseedSceneVisualAuditPaths;
+}): string;
+export declare function writeTreeseedSceneVisualAuditReview(input: {
+    manifest: TreeseedSceneVisualAuditManifest;
+    review: TreeseedSceneVisualAuditReview;
+    paths: TreeseedSceneVisualAuditPaths;
+}): void;