@aethervtt/shard-verify 0.0.0-stage → 0.2.0

package/dist/metrics/metrics.js

@@ -0,0 +1,246 @@
+import { AssetServerResource } from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  defineSchema,
+  defineSystem,
+  First,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { Gpu, Graph, RenderScale, Window } from "@aethervtt/shard-render";
+import {
+  AppControlResource,
+  definePlugin,
+  FrameDemand,
+  perfBreakdown
+} from "@aethervtt/shard-runtime";
+import { distribution, percentile, round, SampleRing } from "../stats.js";
+const FRAME_SAMPLES = 1 << 15;
+const EVENT_SAMPLES = 1 << 12;
+class Metrics {
+  windowMs;
+  renderer;
+  app;
+  now;
+  navigationStart;
+  performance;
+  frames = new SampleRing(FRAME_SAMPLES);
+  gpuFrames = new SampleRing(FRAME_SAMPLES);
+  traces = new SampleRing(EVENT_SAMPLES);
+  longTasks = new SampleRing(EVENT_SAMPLES);
+  windowStart = Number.NEGATIVE_INFINITY;
+  lastStart = Number.NaN;
+  /** The last frame asked for the next one, so the interval between them is a frame time. */
+  continued = false;
+  gpuSamples = 0;
+  scaleMin = Number.POSITIVE_INFINITY;
+  scaleMax = Number.NEGATIVE_INFINITY;
+  scaleAuto = false;
+  scaled = false;
+  pipelinesMs = Number.NaN;
+  assetsMs = Number.NaN;
+  constructor(app, options = {}) {
+    this.app = app;
+    this.windowMs = options.windowMs ?? 3e4;
+    this.renderer = options.renderer ?? "shard";
+    this.now = options.now ?? (() => performance.now());
+    this.navigationStart = options.navigationStart ?? 0;
+    this.performance = options.performance;
+  }
+  /** Starts a new window: what was measured so far no longer counts (startup numbers stay). */
+  reset() {
+    this.windowStart = this.now();
+    this.frames.clear();
+    this.gpuFrames.clear();
+    this.traces.clear();
+    this.longTasks.clear();
+    this.lastStart = Number.NaN;
+    this.scaleMin = Number.POSITIVE_INFINITY;
+    this.scaleMax = Number.NEGATIVE_INFINITY;
+    this.scaleAuto = false;
+    this.scaled = false;
+  }
+  /** @internal As a frame starts: the interval since the last one, if that one asked for this. */
+  frameStart() {
+    const now = this.now();
+    if (this.continued && !Number.isNaN(this.lastStart)) this.frames.push(now, now - this.lastStart);
+    this.lastStart = now;
+  }
+  /** @internal As a frame ends: GPU time, render scale, and whether another frame follows. */
+  frameEnd() {
+    const world = this.app.world;
+    const now = this.now();
+    const demand = world.resource(FrameDemand);
+    this.continued = demand.mode !== "on-demand" || demand.active || world.resource(AppControlResource).pendingSteps > 0;
+    const timer = world.tryResource(Graph)?.timer;
+    if (timer && timer.frameSamples !== this.gpuSamples) {
+      this.gpuSamples = timer.frameSamples;
+      this.gpuFrames.push(now, timer.frameMs);
+    }
+    const scale = world.tryResource(RenderScale);
+    if (scale) {
+      this.scaled = true;
+      if (scale.scale < this.scaleMin) this.scaleMin = scale.scale;
+      if (scale.scale > this.scaleMax) this.scaleMax = scale.scale;
+      if (scale.mode === "auto") this.scaleAuto = true;
+    }
+  }
+  /** @internal */
+  trace(ms) {
+    this.traces.push(this.now(), ms);
+  }
+  /** @internal */
+  longTask(start, duration) {
+    this.longTasks.push(start, duration);
+  }
+  /** @internal The first usable frame was presented: startup work in flight until now counts. */
+  usable(at) {
+    const world = this.app.world;
+    this.pipelinesMs = world.tryResource(Gpu)?.pipelines.busyMs(at) ?? 0;
+    this.assetsMs = world.tryResource(AssetServerResource)?.busyMs(at) ?? 0;
+  }
+  /**
+   * The record of this app so far: startup, and the current window (since `reset()`, at most
+   * `windowMs`). Throws `verify/not-usable` before the first usable frame.
+   */
+  record(meta) {
+    const startup = this.app.startup;
+    if (Number.isNaN(startup.usable) || Number.isNaN(this.pipelinesMs)) {
+      throw new ShardError("verify/not-usable", "The app has no usable frame to measure from yet", {
+        hint: "The host calls app.markUsable() once the scene is interactive; records start after the frame that follows."
+      });
+    }
+    const now = this.now();
+    const since = Math.max(this.windowStart, now - this.windowMs);
+    const nav = this.navigationStart;
+    const frames = this.frames.since(since);
+    const gpu = this.gpuFrames.since(since);
+    const traces = this.traces.since(this.windowStart);
+    const tasks = this.longTasks.since(since);
+    let totalMs = 0;
+    let maxMs = 0;
+    for (const d of tasks) {
+      totalMs += d;
+      if (d > maxMs) maxMs = d;
+    }
+    const frameTime = {
+      ...roundAll(distribution(frames)),
+      n: frames.length
+    };
+    if (gpu.length > 0) frameTime.gpuP95 = round(percentile(gpu, 0.95));
+    const device = this.app.world.tryResource(Gpu);
+    const memory = device?.memory() ?? { bytes: 0, byCategory: {} };
+    return {
+      version: 2,
+      renderer: meta.renderer ?? this.renderer,
+      fixture: meta.fixture,
+      scenario: meta.scenario,
+      device: this.device(),
+      renderScale: this.scaled ? { mode: this.scaleAuto ? "auto" : "fixed", min: this.scaleMin, max: this.scaleMax } : { mode: "none", min: 1, max: 1 },
+      coldStart: {
+        total: round(startup.initEnd - nav),
+        modules: round(startup.initStart - nav),
+        device: round(device?.deviceMs ?? 0),
+        pipelines: round(this.pipelinesMs),
+        assets: round(this.assetsMs)
+      },
+      firstUsableFrame: round(startup.usable - nav),
+      patchToFrame: {
+        p50: round(percentile(traces, 0.5)),
+        p95: round(percentile(traces, 0.95)),
+        n: traces.length
+      },
+      frameTime,
+      longTasks: { count: tasks.length, totalMs: round(totalMs), maxMs: round(maxMs) },
+      gpuMemory: { bytes: memory.bytes, byCategory: memory.byCategory },
+      download: this.performance?.downloads?.() ?? { transferred: 0, decoded: 0 },
+      breakdown: perfBreakdown(this.app.world)
+    };
+  }
+  device() {
+    const gpu = this.app.world.tryResource(Gpu);
+    const info = gpu?.adapter.info;
+    const name = info ? [info.vendor, info.architecture, info.description].filter(Boolean).join(" ") : "";
+    const page = globalThis;
+    const target = this.app.world.tryResource(Window);
+    const dpr = page.devicePixelRatio ?? target?.pixelRatio ?? 1;
+    const viewport = page.innerWidth !== void 0 ? [page.innerWidth, page.innerHeight ?? 0] : [Math.round((target?.width ?? 0) / dpr), Math.round((target?.height ?? 0) / dpr)];
+    return { ua: this.performance?.userAgent ?? "unknown", gpu: name || "unknown", dpr, viewport };
+  }
+}
+function roundAll(d) {
+  return { p50: round(d.p50), p95: round(d.p95), p99: round(d.p99) };
+}
+const MetricsResource = defineResource("verify/Metrics", {
+  description: "What the app measured for performance records (0062): metricsPlugin's."
+});
+const frameStart = defineSystem({
+  name: "verify/frame-start",
+  description: "Times the interval since the last frame, when that frame asked for this one.",
+  setup: (world) => ({ metrics: world.resource(MetricsResource) }),
+  run: ({ metrics }) => metrics.frameStart()
+});
+const metricsMethods = [
+  {
+    name: "metrics.record",
+    description: "A performance record (spec 0062) of the running app: cold start, first usable frame, patch-to-frame latency, frame times, long tasks, GPU memory, downloads, and the breakdown (0074: the 10 CPU and GPU spans with the highest p95), over the window since metrics.reset (at most 30 s).",
+    params: defineSchema("verify/MetricsRecordParams", {
+      fixture: t.string({ required: true, description: 'What was loaded, e.g. "tabletop-small".' }),
+      scenario: t.string({ required: true, description: 'What ran, e.g. "tabletop-pan".' }),
+      renderer: t.string({ description: 'Overrides the renderer name, e.g. "shard@1a2b3c4".' })
+    }),
+    handler: ({ world }, p) => metricsOf(world).record({
+      fixture: p.fixture,
+      scenario: p.scenario,
+      renderer: p.renderer || void 0
+    })
+  },
+  {
+    name: "metrics.reset",
+    description: "Starts a new measurement window: frame times, traces and long tasks so far no longer count.",
+    params: defineSchema("verify/MetricsResetParams", {}),
+    handler: ({ world }) => {
+      metricsOf(world).reset();
+      return null;
+    }
+  }
+];
+function metricsOf(world) {
+  const metrics = world.tryResource(MetricsResource);
+  if (!metrics) {
+    throw new ShardError("verify/no-metrics", "This app has no metrics", {
+      hint: "Add metricsPlugin() from @aethervtt/shard-verify/metrics."
+    });
+  }
+  return metrics;
+}
+function metricsPlugin(options = {}) {
+  const off = [];
+  return definePlugin({
+    name: "verify/metrics",
+    provides: [MetricsResource],
+    dependencies: ["core/time"],
+    build(app) {
+      const metrics = new Metrics(app, options);
+      app.insertResource(MetricsResource, metrics);
+      app.addSystems(First, frameStart);
+      app.addMethod(...metricsMethods);
+      off.push(
+        app.onFrame(() => metrics.frameEnd()),
+        app.onTrace((_, ms) => metrics.trace(ms))
+      );
+      const longTasks = options.performance?.onLongTask?.((start, d) => metrics.longTask(start, d));
+      if (longTasks) off.push(longTasks);
+      void app.whenUsable().then((at) => metrics.usable(at));
+    },
+    dispose() {
+      for (const fn of off.splice(0)) fn();
+    }
+  });
+}
+export {
+  Metrics,
+  MetricsResource,
+  metricsMethods,
+  metricsPlugin
+};

package/dist/node/capture.d.ts

@@ -0,0 +1,48 @@
+import type { LaunchOptions } from 'playwright';
+import { type CheckFailure } from '../expect.js';
+import { type BrowserName, type CapturePlan, type PlanClient } from '../plan.js';
+import type { PerfRecord } from '../record.js';
+import type { CaptureManifest } from '../run.js';
+export interface CaptureOptions {
+    /** Where PNGs, records and `manifest.json` go. */
+    out: string;
+    /** Show the browser windows (also `SHARD_BROWSER_HEADED=1`). Default false. */
+    headed?: boolean;
+    /** Extra browser flags (also `SHARD_BROWSER_ARGS`, space-separated). */
+    browserArgs?: string[];
+    /**
+     * Chromium's release channel (also `SHARD_BROWSER_CHANNEL`): `chrome` runs the installed Chrome,
+     * headed at the display's refresh rate for frame-interval records. Default Playwright's Chromium.
+     */
+    channel?: string;
+    /** Progress lines. */
+    log?: (message: string) => void;
+}
+export interface CaptureRun {
+    manifest: CaptureManifest;
+    /** Every failed check, naming the step and the client. */
+    failures: CheckFailure[];
+    records: PerfRecord[];
+    pass: boolean;
+}
+/**
+ * How `shard capture` launches a browser at a DPR, for anything that has to start it the same way
+ * (tests probing for an adapter). Chromium runs as the full browser in its new headless mode: the
+ * headless shell has no GPU process. It also gets a real device scale: its DPR emulation alone
+ * reports `devicePixelRatio` 2 with a device-pixel box of CSS size, so a canvas would render at 1×
+ * and be scaled up. On Linux, WebGPU goes through Vulkan (Mesa's software driver on CI runners, as
+ * three.js runs its tests), drawing without a Vulkan surface. `SHARD_BROWSER_HEADED=1` shows the
+ * window (CI runs it under `xvfb-run`), and `SHARD_BROWSER_ARGS` adds flags.
+ */
+export declare function browserLaunch(browser: BrowserName, dpr: number, options?: Pick<CaptureOptions, 'headed' | 'browserArgs' | 'channel'>): LaunchOptions;
+/** Runs a capture plan in real browsers (0062). Checks that fail don't stop the run. */
+export declare function runCapture(plan: CapturePlan, options: CaptureOptions): Promise<CaptureRun>;
+/** The plan's URL with the backend it asks for, and the client's role and query parameters. */
+export declare function clientUrl(url: string, client: PlanClient, backend?: string): string;
+/**
+ * Headers for pages Shard serves to measure (0074): cross-origin isolation, so `performance.now()`
+ * steps 5 µs instead of 100 µs (`credentialless` COEP keeps cross-origin loads working without
+ * CORP headers), and `Document-Policy: js-profiling` for the JS Self-Profiling API. `shard dev`,
+ * the playground and the capture server send them.
+ */
+export declare const ISOLATION_HEADERS: Readonly<Record<string, string>>;

package/dist/node/capture.js

@@ -0,0 +1,270 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ShardError } from "@aethervtt/shard-core";
+import { checkExpectations } from "../expect.js";
+import {
+  shotId
+} from "../plan.js";
+import { sha256 } from "./png.js";
+function browserLaunch(browser, dpr, options = {}) {
+  const extra = [
+    ...options.browserArgs ?? [],
+    ...process.env.SHARD_BROWSER_ARGS?.split(" ").filter(Boolean) ?? []
+  ];
+  const headless = !(options.headed ?? process.env.SHARD_BROWSER_HEADED === "1");
+  if (browser !== "chromium") return { headless, args: extra };
+  const args = [
+    "--enable-unsafe-webgpu",
+    "--enable-gpu-rasterization",
+    "--ignore-gpu-blocklist",
+    `--force-device-scale-factor=${dpr}`
+  ];
+  if (process.platform === "linux")
+    args.push("--enable-features=Vulkan", "--disable-vulkan-surface");
+  const channel = options.channel ?? process.env.SHARD_BROWSER_CHANNEL ?? "chromium";
+  return { headless, channel, args: [...args, ...extra] };
+}
+async function runCapture(plan, options) {
+  const playwright = await import("playwright");
+  const log = options.log ?? (() => {
+  });
+  const manifest = {
+    version: 1,
+    url: plan.url,
+    fixture: plan.fixture,
+    date: (/* @__PURE__ */ new Date()).toISOString(),
+    shots: [],
+    records: [],
+    steps: [],
+    skipped: []
+  };
+  const failures = [];
+  const records = [];
+  await mkdir(options.out, { recursive: true });
+  browsers: for (const name of plan.browsers) {
+    for (const dpr of plan.dpr) {
+      let browser;
+      try {
+        browser = await playwright[name].launch(browserLaunch(name, dpr, options));
+      } catch (err) {
+        const reason = err.message.split("\n")[0];
+        manifest.skipped.push({ browser: name, reason });
+        log(`${name}: skipped (${reason})`);
+        continue browsers;
+      }
+      try {
+        const run = await runSession(plan, name, dpr, browser, options.out, log);
+        if (typeof run === "string") {
+          const reason = UNAVAILABLE[run];
+          manifest.skipped.push({ browser: name, reason });
+          log(`${name}: skipped (${reason})`);
+          continue browsers;
+        }
+        manifest.shots.push(...run.shots);
+        manifest.steps.push(...run.steps);
+        manifest.records.push(...run.recordFiles);
+        records.push(...run.records);
+        for (const step of run.steps) failures.push(...step.failures);
+      } finally {
+        await browser.close();
+      }
+    }
+  }
+  if (manifest.shots.length === 0 && manifest.records.length === 0 && manifest.skipped.length > 0) {
+    throw new ShardError("verify/no-browser", "No browser in the plan could run it", {
+      hint: `${manifest.skipped.map((s) => `${s.browser}: ${s.reason}`).join("; ")}. Install one with \`pnpm exec playwright install chromium\`.`
+    });
+  }
+  await writeFile(join(options.out, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+  return { manifest, failures, records, pass: failures.length === 0 };
+}
+const UNAVAILABLE = {
+  "no-webgpu": "no WebGPU in this build",
+  "no-adapter": "no WebGPU adapter",
+  "no-webgl2": "no WebGL2 with float render targets",
+  "no-graphics": "neither WebGPU nor WebGL2"
+};
+async function runSession(plan, browser, dpr, instance, out, log) {
+  const result = { shots: [], steps: [], records: [], recordFiles: [] };
+  const clients = [];
+  try {
+    for (const client of plan.clients) {
+      const context = await instance.newContext({
+        viewport: { width: plan.viewport[0], height: plan.viewport[1] },
+        deviceScaleFactor: dpr
+      });
+      const page = await context.newPage();
+      page.setDefaultTimeout(plan.timeoutMs);
+      clients.push({ plan: client, context, page });
+      const errors = [];
+      page.on("pageerror", (err) => errors.push(err.message));
+      await page.goto(clientUrl(plan.url, client, plan.backend));
+      const gpu = await page.evaluate(async (backend) => {
+        const webgpu = !navigator.gpu ? "no-webgpu" : await navigator.gpu.requestAdapter() ? "ok" : "no-adapter";
+        const gl = document.createElement("canvas").getContext("webgl2");
+        const webgl2 = gl?.getExtension("EXT_color_buffer_float") ? "ok" : "no-webgl2";
+        gl?.getExtension("WEBGL_lose_context")?.loseContext();
+        if (backend === "webgl2") return webgl2;
+        if (backend === "auto") return webgpu === "ok" || webgl2 === "ok" ? "ok" : "no-graphics";
+        return webgpu;
+      }, plan.backend);
+      if (gpu !== "ok") return gpu;
+      await page.waitForFunction(() => window.__shardReady === true, void 0, { timeout: plan.timeoutMs }).catch((err) => {
+        throw new ShardError(
+          "verify/not-ready",
+          `${clientUrl(plan.url, client)} never became ready`,
+          {
+            hint: `The page sets window.__shardReady through installCapturePage once the host calls app.markUsable().${errors.length ? ` Page errors: ${errors.join("; ")}` : ""}`,
+            cause: err
+          }
+        );
+      });
+      await page.evaluate((c) => window.__shardCapture.conditions(c), plan.conditions);
+      log(`${browser}@${dpr}x ${client.name}: ready`);
+    }
+    for (const client of clients) {
+      for (const shot of [...plan.shots, ...client.plan.shots ?? []]) {
+        result.shots.push(await takeShot(plan, browser, dpr, client, shot, out));
+      }
+    }
+    const failures = await runSteps(plan, plan.steps, browser, dpr, clients, out, result);
+    if (failures.length > 0) log(`${browser}@${dpr}x: ${failures.length} failed checks`);
+    for (const scenario of plan.scenarios) {
+      const recording = clients.filter(
+        (c) => !scenario.clients || scenario.clients.includes(c.plan.name)
+      );
+      for (const client of recording)
+        await client.page.evaluate(() => window.__shardCapture.reset());
+      await runSteps(plan, scenario.steps ?? [], browser, dpr, clients, out, result, scenario.name);
+      await new Promise((resolve) => setTimeout(resolve, scenario.seconds * 1e3));
+      for (const client of recording) {
+        const record = await client.page.evaluate((meta) => window.__shardCapture.record(meta), {
+          fixture: plan.fixture,
+          scenario: scenario.name,
+          renderer: plan.renderer
+        });
+        const file = `records/${scenario.name}/${browser}@${dpr}x-${client.plan.name}.json`;
+        await writeOut(join(out, file), `${JSON.stringify(record, null, 2)}
+`);
+        result.records.push(record);
+        result.recordFiles.push(file);
+      }
+      log(`${browser}@${dpr}x: recorded ${scenario.name}`);
+    }
+    return result;
+  } finally {
+    for (const client of clients) await client.context.close();
+  }
+}
+async function runSteps(plan, steps, browser, dpr, clients, out, result, prefix) {
+  const all = [];
+  for (const step of steps) {
+    const name = prefix ? `${prefix}/${step.name}` : step.name;
+    const failures = [];
+    const latency = /* @__PURE__ */ new Map();
+    for (const client of clients) {
+      if (step.clients && !step.clients.includes(client.plan.name)) continue;
+      try {
+        const ran = await client.page.evaluate(
+          ({ run, args, trace }) => window.__shardCapture.step(run, args, trace),
+          { run: step.run ?? step.name, args: step.args ?? null, trace: step.trace ?? false }
+        );
+        latency.set(client.plan.name, ran.latencyMs);
+        if (ran.result !== null && ran.result !== void 0) {
+          const file = join(
+            out,
+            "results",
+            `${browser}@${dpr}x-${client.plan.name}`,
+            `${name}.json`
+          );
+          await writeOut(file, `${JSON.stringify(ran.result, null, 2)}
+`);
+        }
+      } catch (err) {
+        failures.push({ step: name, client: client.plan.name, path: "", message: pageMessage(err) });
+      }
+    }
+    for (const client of clients) {
+      await client.page.evaluate((ms) => window.__shardCapture.idle(ms), plan.timeoutMs);
+      const expectations = step.expect?.[client.plan.name];
+      if (expectations) {
+        const probe = await client.page.evaluate(() => window.__shardCapture.probe());
+        const seen = { ...probe, step: { latencyMs: latency.get(client.plan.name) } };
+        failures.push(...checkExpectations(name, client.plan.name, seen, expectations));
+      }
+      if (step.capture) {
+        const shots = step.capture === true ? [{ name: step.name }] : step.capture;
+        for (const shot of shots) {
+          const named = { ...shot, name: prefix ? `${prefix}-${shot.name}` : shot.name };
+          result.shots.push(await takeShot(plan, browser, dpr, client, named, out));
+        }
+      }
+    }
+    result.steps.push({ name, browser, dpr, failures });
+    all.push(...failures);
+  }
+  return all;
+}
+async function takeShot(plan, browser, dpr, client, shot, out) {
+  const page = client.page;
+  if (shot.state) await page.evaluate((s) => window.__shardCapture.apply(s), shot.state);
+  await page.evaluate((ms) => window.__shardCapture.idle(ms), plan.timeoutMs);
+  const scope = shot.scope ?? plan.scope;
+  let png;
+  let width;
+  let height;
+  if (scope === "page") {
+    png = await page.screenshot({ type: "png", animations: "disabled", caret: "hide" });
+    width = Math.round(plan.viewport[0] * dpr);
+    height = Math.round(plan.viewport[1] * dpr);
+  } else {
+    const snap = await page.evaluate(
+      (s) => window.__shardCapture.snapshot(s),
+      shot.canvas ?? plan.canvas
+    );
+    png = Buffer.from(snap.png, "base64");
+    width = snap.width;
+    height = snap.height;
+  }
+  const id = shotId(browser, client.plan.name, shot.name, dpr);
+  await writeOut(join(out, `${id}.png`), png);
+  return {
+    id,
+    browser,
+    client: client.plan.name,
+    shot: shot.name,
+    dpr,
+    scope,
+    width,
+    height,
+    hash: sha256(png),
+    tolerance: { ...plan.tolerance, ...shot.tolerance }
+  };
+}
+function clientUrl(url, client, backend) {
+  const u = new URL(url);
+  if (backend) u.searchParams.set("backend", backend);
+  if (client.role) u.searchParams.set("role", client.role);
+  for (const [key, value] of Object.entries(client.query ?? {})) u.searchParams.set(key, value);
+  return u.toString();
+}
+async function writeOut(file, data) {
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, data);
+}
+function pageMessage(err) {
+  const message = err.message ?? String(err);
+  return message.replace(/^page\.evaluate: /, "").split("\n")[0];
+}
+const ISOLATION_HEADERS = {
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Cross-Origin-Embedder-Policy": "credentialless",
+  "Document-Policy": "js-profiling"
+};
+export {
+  ISOLATION_HEADERS,
+  browserLaunch,
+  clientUrl,
+  runCapture
+};

package/dist/node/files.d.ts

@@ -0,0 +1,40 @@
+import { type CapturePlan } from '../plan.js';
+import { type PerfRecord } from '../record.js';
+import { type ReportShot } from '../report.js';
+import { type Approval, type CaptureManifest } from '../run.js';
+import { type PerfCheck } from '../thresholds.js';
+export declare function readPlan(file: string): Promise<CapturePlan>;
+export declare function readManifest(captures: string): Promise<CaptureManifest>;
+export interface CompareResult extends ReportShot {
+    hash: string;
+}
+export interface CompareRun {
+    pass: boolean;
+    shots: CompareResult[];
+    report: string;
+}
+/**
+ * Diffs each capture of a run against its approved image (0062) and writes an HTML report with
+ * heatmaps. A shot with no approved image is `new`, and fails until approved.
+ */
+export declare function compareRun(captures: string, approved: string, options?: {
+    report?: string;
+}): Promise<CompareRun>;
+/**
+ * Approves a capture (0062): copies it into `approved/` and appends `{ shot, hash, reason, by,
+ * date }` to `approved/approvals.json`. Refuses without a reason.
+ */
+export declare function approveShot(options: {
+    captures: string;
+    approved: string;
+    shot: string;
+    reason: string | undefined;
+    by: string;
+    date?: Date;
+}): Promise<Approval>;
+/** Every `.json` record under the given files and directories. */
+export declare function readRecords(paths: readonly string[]): Promise<PerfRecord[]>;
+/** `shard perf-check`: a plan's thresholds over records (0062). */
+export declare function perfCheck(planFile: string, paths: readonly string[]): Promise<PerfCheck & {
+    records: number;
+}>;