@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/report/data.ts

@@ -0,0 +1,475 @@
+import type { QualityReport } from "../quality/budgets.ts"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { CaseResult, CaseStatus, Cost, WriteBack } from "../cases/types.ts"
+import type { ReportEnv } from "./html.ts"
+import { addCost } from "../usage.ts"
+import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
+
+/** Something that went wrong in the browser during a step: a console error, an uncaught exception, a failed or slow request. */
+export type BrowserProblem = {
+  kind: "console" | "exception" | "network" | "slow"
+  level: "error" | "warning"
+  text: string
+  url?: string
+  status?: number
+  ms?: number
+  line?: number
+  count?: number
+}
+
+/** One entry of a run's steps.json: a step replayed from memory or taken by the agent. */
+export type TimelineStep = {
+  n: number
+  source: "agent" | "memory"
+  url: string
+  title?: string
+  goal?: string
+  evaluation?: string
+  memory?: string
+  /** `box`: where the action's element sat on the screenshot, as fractions of its width and height. */
+  actions: { text: string; ok: boolean; error?: string; done?: boolean; box?: { x: number; y: number; w: number; h: number } }[]
+  /** Start (epoch seconds), duration, and the part of it spent waiting for the model. */
+  t0?: number
+  ms?: number
+  model_ms?: number
+  screenshot?: string
+  problems?: BrowserProblem[]
+  more_problems?: number
+}
+
+/** The console errors, uncaught exceptions, and failed requests of a run, in order. */
+export function browserErrors(runDir?: string): BrowserProblem[] {
+  return readTimeline(runDir).flatMap((t) => (t.problems || []).filter((p) => p.level === "error"))
+}
+
+export function problemLine(p: BrowserProblem): string {
+  const times = p.count && p.count > 1 ? ` (×${p.count})` : ""
+  if (p.kind === "network") return `Request failed${p.status ? ` (${p.status})` : ""}: ${p.url || p.text}${times}`
+  if (p.kind === "exception") return `Uncaught error: ${p.text.split("\n")[0]}${p.url ? ` at ${p.url}${p.line ? `:${p.line}` : ""}` : ""}${times}`
+  if (p.kind === "slow") return `Slow request (${((p.ms || 0) / 1000).toFixed(1)}s): ${p.url}${times}`
+  return `Console ${p.level}: ${p.text}${times}`
+}
+
+/** A memory step whose recorded locators no longer matched the page; `used` is the one that still worked. */
+export type Heal = { step: number; line: string; label?: string; stale: string[]; used?: string }
+
+/** What page memory did in a run (run.json "memory"), plus the last full agent run of the case to compare with. */
+export type CaseMemory = {
+  mode: string
+  replayed: number
+  replayTotal: number
+  agentSteps: number
+  flow?: string
+  stopped?: string
+  repaired?: { step: number; reason: string; agentSteps: number }
+  heals?: Heal[]
+  baseline?: { runId: string; at: string; ms: number; tokens: number }
+}
+
+export type Diagnostics = {
+  consoleErrors: number
+  consoleWarnings: number
+  failedRequests: number
+  slowRequests: number
+  pagesChecked: number
+  accessibilityIssues: number
+}
+
+export type A11yIssue = {
+  rule: string
+  wcag?: string
+  impact: string
+  help: string
+  count: number
+  examples?: { html?: string; text?: string; role?: string }[]
+}
+export type A11yPage = { url: string; title?: string; checked?: number; issues: A11yIssue[] }
+
+/** The same case's last passing run: its screenshot of the page this run failed on, and what it did. */
+export type LastGood = { runId: string; at: string; href?: string; shot?: string; step?: number; url?: string; steps: string[] }
+
+/** Mirrors report-ui/src/types.ts; the UI reads it from window.__FORGEQE_REPORT__. */
+export type CaseVisual = { page: string; url: string; title?: string; status: string; diffPercent?: number; limit?: number; over?: boolean; resized?: string; current: string; baseline?: string; diff?: string }
+export type CaseQuality = { standard: string; engine: string; passed: string[]; failed: number; performance: QualityReport["performance"]["pages"]; budgets: QualityReport["budgets"]; breaches: QualityReport["breaches"]; visual?: CaseVisual[] }
+
+export type ReportData = {
+  kind: "suite" | "run"
+  title: string
+  id: string
+  startedAt: string
+  ms: number
+  stopped: boolean
+  generatedAt: string
+  env?: ReportEnv
+  cases: ReportCase[]
+  posted: WriteBack[]
+  history: HistoryRun[]
+}
+
+export type ReportCase = {
+  id: string
+  title: string
+  source: string
+  url?: string
+  description?: string
+  preconditions?: string[]
+  tags?: string[]
+  group?: string
+  requirements?: string[]
+  startUrl?: string
+  status: CaseStatus
+  summary: string
+  startedAt: string
+  finishedAt: string
+  ms: number
+  /** Browser agent and coding agent together. */
+  tokens: number
+  usage?: { input: number; output: number }
+  /** What the case cost in all: the browser run and, when one ran, the coding agent's job. */
+  cost?: Cost
+  /** The two parts of cost, when the coding agent ran. */
+  browserCost?: Cost
+  codeCost?: Cost
+  codeTokens?: number
+  finalUrl?: string
+  memory?: CaseMemory
+  diagnostics?: Diagnostics
+  accessibility?: A11yPage[]
+  /** WCAG rules passed and failed, each page's Core Web Vitals, and the budgets exceeded (quality.json). */
+  quality?: CaseQuality
+  lastGood?: LastGood
+  steps: { n: number; action: string; data?: string; expected?: string; status?: "passed" | "failed" | "not_run"; actual?: string }[]
+  timeline: (Omit<TimelineStep, "screenshot"> & { shot?: string })[]
+  agentSteps?: { text: string; ok: boolean }[]
+  posted: WriteBack[]
+  code?: CaseResult["code"]
+  /** What kind of failure it was and what happened because of it (src/cases/failure.ts). */
+  failure?: CaseResult["failure"] & { label: string; action: string }
+  bug?: CaseResult["bug"]
+  retried?: boolean
+  /** Skills the browser agent followed in this run (run.json "skills"). */
+  skills?: string[]
+  lastShot?: string
+  files: { name: string; href: string; text?: string; truncated?: boolean }[]
+  runDir?: string
+}
+
+export type HistoryRun = {
+  id: string
+  title: string
+  at: string
+  ms: number
+  total: number
+  passed: number
+  failed: number
+  error: number
+  stopped: number
+  tokens: number
+  cost?: Cost
+  current?: boolean
+  href?: string
+  cases: { id: string; title: string; status: CaseStatus; ms: number; tokens: number; cost?: number }[]
+}
+
+export type DataInput = {
+  kind: "suite" | "run"
+  title: string
+  startedAt: string
+  ms: number
+  stopped?: boolean
+  dir: string
+  results: CaseResult[]
+  posted: WriteBack[]
+  env?: ReportEnv
+}
+
+export type DataOptions = {
+  /** Screenshot bytes embedded in the page; later screenshots are linked by relative path instead. */
+  embedBytes?: number
+  /** Largest text file embedded for the Files tab. */
+  textBytes?: number
+  /** Earlier suite runs read for trends and flaky tests. */
+  historyRuns?: number
+}
+
+const TEXT_FILES = ["trace.md", "workflow.yaml", "handoff.md"]
+const LINK_FILES = ["steps.json", "run.json", "accessibility.json", "performance.json", "quality.json", "code.json", "testcase.json"]
+const MIME: Record<string, string> = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp", ".gif": "image/gif" }
+
+/** Visual results with their images embedded (changed pages first, as they matter most). */
+function visualPages(pages: NonNullable<QualityReport["visual"]>["pages"], image: (file: string) => string): CaseVisual[] {
+  const img = (file?: string) => (file && existsSync(file) ? image(file) : undefined)
+  return [...pages]
+    .sort((a, b) => Number(b.status === "changed") - Number(a.status === "changed") || (b.diffPercent || 0) - (a.diffPercent || 0))
+    .map((p) => ({ page: p.page, url: p.url, title: p.title, status: p.status, diffPercent: p.diffPercent, limit: p.limit, over: p.over, resized: p.resized, current: img(p.current) || "", baseline: p.status === "new" ? undefined : img(p.baseline), diff: img(p.diff) }))
+}
+
+export function buildReportData(p: DataInput, opts: DataOptions = {}): ReportData {
+  const rel = (file: string) => path.relative(p.dir, file).split(path.sep).map(encodeURIComponent).join("/") || "."
+  let budget = opts.embedBytes ?? 40 * 1024 * 1024
+  const textBytes = opts.textBytes ?? 100 * 1024
+
+  const image = (file: string): string => {
+    const size = statSync(file).size
+    const mime = MIME[path.extname(file).toLowerCase()]
+    if (!mime || size > budget) return rel(file)
+    budget -= size
+    return `data:${mime};base64,${readFileSync(file).toString("base64")}`
+  }
+
+  const earlier = p.kind === "suite" ? savedSuites(p).filter((s) => s.startedAt < p.startedAt).slice(-(opts.historyRuns ?? 30)) : []
+
+  // Failed cases claim the embedding budget first: their screenshots matter most.
+  const order = p.results.map((r, i) => ({ r, i })).sort((a, b) => Number(a.r.status === "passed") - Number(b.r.status === "passed") || a.i - b.i)
+  const cases: ReportCase[] = new Array(p.results.length)
+  for (const { r, i } of order) {
+    const c = reportCase(r, p.posted, rel, image, textBytes)
+    if (c.memory?.replayed) c.memory.baseline = fullAgentRun(r, earlier)
+    if (r.status === "failed" || r.status === "error") c.lastGood = lastGood(r, c, earlier, image)
+    cases[i] = c
+  }
+
+  const data: ReportData = {
+    kind: p.kind,
+    title: p.title,
+    id: path.basename(p.dir),
+    startedAt: p.startedAt,
+    ms: p.ms,
+    stopped: Boolean(p.stopped),
+    generatedAt: new Date().toISOString(),
+    env: p.env,
+    cases,
+    posted: p.posted.filter((w) => !w.caseId),
+    history: [],
+  }
+  if (p.kind === "suite") {
+    data.history = [
+      ...earlier.map((s) => historyRun(s.name, s.title, s.startedAt, s.ms, s.results, s.href)),
+      { ...historyRun(path.basename(p.dir), p.title, p.startedAt, p.ms, p.results), current: true },
+    ]
+  }
+  return data
+}
+
+function reportCase(r: CaseResult, posted: WriteBack[], rel: (f: string) => string, image: (f: string) => string, textBytes: number): ReportCase {
+  const tc = r.case
+  const inRun = (name: string) => (r.runDir && existsSync(path.join(r.runDir, name)) ? path.join(r.runDir, name) : null)
+  const verdicts = new Map((r.stepResults || []).map((v) => [v.step, v]))
+  const timeline = readTimeline(r.runDir).map(({ screenshot, ...t }) => {
+    const file = screenshot ? inRun(screenshot) : null
+    return { ...t, shot: file ? image(file) : undefined }
+  })
+  const failure = inRun("failure.png")
+  const files: ReportCase["files"] = []
+  for (const name of TEXT_FILES) {
+    const file = inRun(name)
+    if (!file) continue
+    const buf = readFileSync(file)
+    files.push({ name, href: rel(file), text: buf.subarray(0, textBytes).toString("utf8"), truncated: buf.length > textBytes || undefined })
+  }
+  for (const name of LINK_FILES) {
+    const file = inRun(name)
+    if (file) files.push({ name, href: rel(file) })
+  }
+  if (failure) files.push({ name: "failure.png", href: rel(failure) })
+  const run = readJson<RunJson>(inRun("run.json"))
+  const a11y = readJson<A11yPage[]>(inRun("accessibility.json"))
+  const q = readJson<QualityReport>(inRun("quality.json"))
+
+  return {
+    id: tc.id,
+    title: tc.title,
+    source: tc.source,
+    url: tc.url,
+    description: tc.description?.trim() || undefined,
+    preconditions: tc.preconditions?.length ? tc.preconditions : undefined,
+    tags: tc.tags?.length ? tc.tags : undefined,
+    group: tc.group,
+    requirements: tc.requirements?.length ? tc.requirements : undefined,
+    startUrl: tc.startUrl,
+    status: r.status,
+    summary: r.summary,
+    startedAt: r.startedAt,
+    finishedAt: r.finishedAt,
+    ms: r.ms,
+    tokens: r.tokens,
+    usage: r.usage,
+    cost: addCost(r.cost, r.codeCost),
+    ...(r.codeCost || r.codeUsage ? { browserCost: r.cost, codeCost: r.codeCost, codeTokens: r.codeUsage ? r.codeUsage.input + r.codeUsage.output : undefined } : {}),
+    finalUrl: r.finalUrl,
+    memory: caseMemory(run?.memory),
+    diagnostics: diagnostics(run?.diagnostics),
+    accessibility: Array.isArray(a11y) && a11y.length ? a11y : undefined,
+    ...(q ? { quality: { standard: q.standard, engine: q.engine, passed: q.accessibility.passed, failed: q.accessibility.failed.length, performance: q.performance.pages, budgets: q.budgets, breaches: q.breaches, ...(q.visual?.pages.length ? { visual: visualPages(q.visual.pages, image) } : {}) } } : {}),
+    steps: tc.steps.map((s, i) => {
+      const v = verdicts.get(i + 1)
+      return { n: i + 1, action: s.action, data: s.data, expected: s.expected, status: v?.status, actual: v?.actual }
+    }),
+    timeline,
+    agentSteps: !timeline.length && r.steps?.length ? r.steps.map((s) => ({ text: s.text, ok: s.ok })) : undefined,
+    posted: posted.filter((w) => w.caseId === tc.id),
+    code: r.code,
+    ...(r.failure ? { failure: { ...r.failure, label: FAILURE_LABEL[r.failure.type], action: FAILURE_ACTION[r.failure.type] } } : {}),
+    ...(r.bug ? { bug: r.bug } : {}),
+    ...(r.retried ? { retried: true } : {}),
+    skills: Array.isArray(run?.skills) && run.skills.length ? run.skills.map(String) : undefined,
+    lastShot: failure ? image(failure) : undefined,
+    files,
+    runDir: r.runDir ? rel(r.runDir) : undefined,
+  }
+}
+
+export function readTimeline(runDir?: string): TimelineStep[] {
+  const file = runDir && path.join(runDir, "steps.json")
+  if (!file || !existsSync(file)) return []
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8"))
+    return Array.isArray(data) ? data : []
+  } catch {
+    return []
+  }
+}
+
+type RunJson = {
+  memory?: {
+    mode?: string
+    replayed?: number
+    replay_total?: number
+    llm_steps?: number
+    flow?: string | null
+    replay_stopped?: string
+    repaired?: { step?: number; reason?: string; agent_steps?: number }
+    heals?: Heal[]
+  }
+  diagnostics?: Record<string, number>
+  skills?: unknown[]
+}
+
+function readJson<T>(file: string | null | undefined): T | undefined {
+  if (!file || !existsSync(file)) return undefined
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T
+  } catch {
+    return undefined
+  }
+}
+
+function caseMemory(m: RunJson["memory"]): CaseMemory | undefined {
+  if (!m) return undefined
+  return {
+    mode: m.mode || "verify",
+    replayed: m.replayed || 0,
+    replayTotal: m.replay_total || 0,
+    agentSteps: m.llm_steps || 0,
+    flow: m.flow || undefined,
+    stopped: m.replay_stopped || undefined,
+    repaired: m.repaired ? { step: m.repaired.step || 0, reason: m.repaired.reason || "", agentSteps: m.repaired.agent_steps || 0 } : undefined,
+    heals: m.heals?.length ? m.heals : undefined,
+  }
+}
+
+function diagnostics(d: RunJson["diagnostics"]): Diagnostics | undefined {
+  if (!d) return undefined
+  return {
+    consoleErrors: d.console_errors || 0,
+    consoleWarnings: d.console_warnings || 0,
+    failedRequests: d.failed_requests || 0,
+    slowRequests: d.slow_requests || 0,
+    pagesChecked: d.pages_checked || 0,
+    accessibilityIssues: d.accessibility_issues || 0,
+  }
+}
+
+type Saved = { name: string; title: string; startedAt: string; ms: number; results: CaseResult[]; dir: string; href?: string }
+
+/** Earlier suite runs saved next to this one (out/suites/<time>/suite.json), oldest first. */
+function savedSuites(p: DataInput): Saved[] {
+  const parent = path.dirname(p.dir)
+  const self = path.basename(p.dir)
+  let names: string[] = []
+  try {
+    names = readdirSync(parent).filter((n) => n !== self && existsSync(path.join(parent, n, "suite.json")))
+  } catch {}
+  const out: Saved[] = []
+  for (const name of names) {
+    const s = readJson<{ name?: string; startedAt?: string; ms?: number; results?: CaseResult[] }>(path.join(parent, name, "suite.json"))
+    if (!s?.startedAt || !Array.isArray(s.results)) continue
+    const html = path.join(parent, name, "report.html")
+    const href = existsSync(html) ? `../${encodeURIComponent(name)}/report.html` : undefined
+    out.push({ name, title: s.name || name, startedAt: s.startedAt, ms: s.ms || 0, results: s.results, dir: path.join(parent, name), href })
+  }
+  return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt))
+}
+
+/** A saved result's run folder: next to its suite.json if the runs were moved, else where it was written. */
+function runDirOf(r: CaseResult, s: Saved): string | undefined {
+  if (!r.runDir) return undefined
+  const moved = path.join(s.dir, path.basename(r.runDir))
+  return existsSync(moved) ? moved : existsSync(r.runDir) ? r.runDir : undefined
+}
+
+/** The newest earlier passing run of this case where the agent took every step (no page memory replay). */
+function fullAgentRun(r: CaseResult, earlier: Saved[]): CaseMemory["baseline"] {
+  for (const s of [...earlier].reverse()) {
+    const old = s.results.find((o) => o.case.id === r.case.id && o.status === "passed")
+    if (!old) continue
+    const dir = runDirOf(old, s)
+    if (readJson<RunJson>(dir && path.join(dir, "run.json"))?.memory?.replayed) continue
+    return { runId: s.name, at: s.startedAt, ms: old.ms, tokens: old.tokens }
+  }
+  return undefined
+}
+
+const urlPath = (u?: string) => {
+  try {
+    return u ? new URL(u).pathname : undefined
+  } catch {
+    return u
+  }
+}
+
+function lastGood(r: CaseResult, c: ReportCase, earlier: Saved[], image: (f: string) => string): LastGood | undefined {
+  const passed = [...earlier].reverse().flatMap((s) => {
+    const old = s.results.find((o) => o.case.id === r.case.id && o.status === "passed")
+    return old ? [{ s, dir: runDirOf(old, s) }] : []
+  })
+  // The newest passing run whose folder is still there; else just the newest passing run.
+  const pick = passed.find((p) => p.dir) || passed[0]
+  if (!pick) return undefined
+  const { s, dir } = pick
+  const steps = readTimeline(dir)
+  const failedAt = urlPath(c.timeline[c.timeline.length - 1]?.url || r.finalUrl)
+  const shots = steps.filter((t) => t.screenshot && dir && existsSync(path.join(dir, t.screenshot)))
+  const match = [...shots].reverse().find((t) => urlPath(t.url) === failedAt) || shots[shots.length - 1]
+  return {
+    runId: s.name,
+    at: s.startedAt,
+    href: s.href,
+    shot: match && dir ? image(path.join(dir, match.screenshot!)) : undefined,
+    step: match?.n,
+    url: match?.url,
+    steps: steps.map((t) => t.actions.map((a) => a.text).join("; ") || t.goal || t.url),
+  }
+}
+
+function historyRun(id: string, title: string, at: string, ms: number, results: CaseResult[], href?: string): HistoryRun {
+  const n = (s: CaseStatus) => results.filter((r) => r.status === s).length
+  const costs = results.map((r) => addCost(r.cost, r.codeCost)).filter((c): c is Cost => !!c)
+  return {
+    id,
+    title,
+    at,
+    ms,
+    total: results.length,
+    passed: n("passed"),
+    failed: n("failed"),
+    error: n("error"),
+    stopped: n("stopped"),
+    tokens: results.reduce((a, r) => a + (r.tokens || 0), 0),
+    cost: costs.reduce<Cost | undefined>((sum, c) => addCost(sum, c), undefined),
+    href,
+    cases: results.map((r) => ({ id: r.case.id, title: r.case.title, status: r.status, ms: r.ms, tokens: r.tokens || 0, cost: addCost(r.cost, r.codeCost)?.amount })),
+  }
+}

package/src/report/html.ts

@@ -0,0 +1,106 @@
+import { readFileSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import type { RunResult } from "../types.ts"
+import { costOf, type CaseResult, type WriteBack } from "../cases/types.ts"
+import type { AppConfig } from "../config.ts"
+import { packageVersion } from "../tui/theme.ts"
+import { buildReportData, type DataOptions } from "./data.ts"
+
+export { readTimeline, type TimelineStep } from "./data.ts"
+
+/** Where and how the run happened, shown at the top of the report. */
+export type ReportEnv = {
+  model: string
+  browser: string
+  startUrl?: string
+  version: string
+  machine: string
+  ci?: { name: string; url?: string }
+  commit?: string
+  branch?: string
+  /** Price per million tokens of the browser agent's model, when set in llms.json. */
+  price?: { input: number; output: number; currency: string; cachedInput?: number; note?: string; estimate?: boolean }
+}
+
+export function ciInfo(env = process.env): Pick<ReportEnv, "ci" | "commit" | "branch"> {
+  if (env.GITHUB_ACTIONS === "true") {
+    const url = env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined
+    return { ci: { name: `GitHub Actions${env.GITHUB_WORKFLOW ? ` · ${env.GITHUB_WORKFLOW}` : ""}`, url }, commit: env.GITHUB_SHA, branch: env.GITHUB_REF_NAME }
+  }
+  if ((env.TF_BUILD || "").toLowerCase() === "true") {
+    const url = env.SYSTEM_COLLECTIONURI && env.SYSTEM_TEAMPROJECT && env.BUILD_BUILDID ? `${env.SYSTEM_COLLECTIONURI}${encodeURIComponent(env.SYSTEM_TEAMPROJECT)}/_build/results?buildId=${env.BUILD_BUILDID}` : undefined
+    return { ci: { name: `Azure Pipelines${env.BUILD_DEFINITIONNAME ? ` · ${env.BUILD_DEFINITIONNAME}` : ""}`, url }, commit: env.BUILD_SOURCEVERSION, branch: env.BUILD_SOURCEBRANCHNAME }
+  }
+  if (env.CI_JOB_URL) return { ci: { name: "GitLab CI", url: env.CI_JOB_URL }, commit: env.CI_COMMIT_SHA, branch: env.CI_COMMIT_REF_NAME }
+  if (env.BUILD_URL) return { ci: { name: "CI", url: env.BUILD_URL }, commit: env.GIT_COMMIT, branch: env.GIT_BRANCH }
+  return {}
+}
+
+export function reportEnv(config: AppConfig, opts: { url?: string; headed?: boolean } = {}): ReportEnv {
+  const llm = config.llm
+  return {
+    model: `${config.activeProfile} (${llm.provider}/${llm.deployment || llm.model})`,
+    browser: llm.provider === "mock" ? "synthetic page (mock profile)" : `Chrome, ${opts.headed || !config.browser.headless ? "visible" : "headless"}, ${config.browser.width}×${config.browser.height}`,
+    startUrl: opts.url || config.browser.startUrl,
+    version: packageVersion(),
+    machine: `${os.hostname()} · ${process.platform}`,
+    ...(llm.price ? { price: llm.price } : {}),
+    ...ciInfo(),
+  }
+}
+
+export function duration(ms: number): string {
+  const s = Math.round(ms / 1000)
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`
+}
+
+export type ReportInput = {
+  title: string
+  startedAt: string
+  ms: number
+  stopped?: boolean
+  /** Folder the report is written to; links are relative to it. */
+  dir: string
+  results: CaseResult[]
+  posted: WriteBack[]
+  env?: ReportEnv
+  /** "run" opens on the case itself; "suite" (the default) on the overview. */
+  kind?: "suite" | "run"
+}
+
+/** Built from report-ui/ by `bun run build:report`: one HTML file with the whole React app inlined. */
+const TEMPLATE = new URL("./template.html", import.meta.url)
+
+/** A self-contained report page: the report-ui app with this run's data (and screenshots) embedded. */
+export function renderReport(p: ReportInput, opts?: DataOptions): string {
+  const data = buildReportData({ kind: p.kind || "suite", ...p }, opts)
+  const json = JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")
+  const title = p.title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+  return readFileSync(TEMPLATE, "utf8")
+    .replace(/<title>[^<]*<\/title>/, () => `<title>${title}</title>`)
+    .replace("<head>", () => `<head>\n<script>window.__FORGEQE_REPORT__=${json}</script>`)
+}
+
+/** report.html for one browser run, next to its other files. */
+export function writeRunReport(dir: string, run: RunResult, env?: ReportEnv, t0 = Date.now()): string {
+  const status = run.status === "complete" ? "passed" : run.status === "fail" ? "failed" : "stopped"
+  const finished = new Date().toISOString()
+  const result: CaseResult = {
+    case: { id: "run", title: run.goal.split("\n")[0].slice(0, 200), source: "text", description: run.goal.includes("\n") ? run.goal : undefined, steps: [] },
+    status,
+    summary: run.summary,
+    startedAt: new Date(t0).toISOString(),
+    finishedAt: finished,
+    ms: Date.now() - t0,
+    tokens: run.usage.input + run.usage.output,
+    usage: run.usage,
+    cost: costOf(run.usage, env?.price),
+    runDir: dir,
+    finalUrl: run.finalUrl || undefined,
+  }
+  const file = path.join(dir, "report.html")
+  writeFileSync(file, renderReport({ title: "ForgeQE run", startedAt: result.startedAt, ms: result.ms, dir, results: [result], posted: [], env, kind: "run" }))
+  return file
+}