@aethervtt/shard-verify 0.0.0-stage → 0.2.0

package/dist/plan.js

@@ -0,0 +1,250 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { validateJson } from "./record.js";
+const tolerance = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    deltaE: { type: "number", exclusiveMinimum: 0 },
+    maxShare: { type: "number", minimum: 0 },
+    minSsim: { type: "number", minimum: 0 }
+  }
+};
+const shot = {
+  type: "object",
+  additionalProperties: false,
+  required: ["name"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    state: { type: "object" },
+    scope: { enum: ["canvas", "page"] },
+    canvas: { type: "string", minLength: 1 },
+    tolerance
+  }
+};
+const matcher = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    equals: {},
+    includes: { type: "array" },
+    excludes: { type: "array" },
+    min: { type: "number" },
+    max: { type: "number" },
+    sameAs: { type: "string", minLength: 1 }
+  }
+};
+const strings = { type: "array", items: { type: "string", minLength: 1 } };
+const step = {
+  type: "object",
+  additionalProperties: false,
+  required: ["name"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    run: { type: "string", minLength: 1 },
+    args: {},
+    clients: strings,
+    trace: { type: "boolean" },
+    expect: {
+      type: "object",
+      additionalProperties: { type: "object", additionalProperties: matcher }
+    },
+    capture: {}
+  }
+};
+function capturePlanJsonSchema() {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://shard.dev/schemas/capture-plan.schema.json",
+    title: "Shard capture plan",
+    description: "Browser captures, host steps with checks, and measured scenarios with pass thresholds (spec 0062).",
+    type: "object",
+    additionalProperties: false,
+    required: ["url"],
+    properties: {
+      $schema: { type: "string" },
+      url: { type: "string", minLength: 1 },
+      browsers: { type: "array", items: { enum: ["chromium", "webkit", "firefox"] }, minItems: 1 },
+      dpr: { type: "array", items: { type: "number", exclusiveMinimum: 0 }, minItems: 1 },
+      viewport: { type: "array", items: { type: "integer", minimum: 1 }, minItems: 2, maxItems: 2 },
+      scope: { enum: ["canvas", "page"] },
+      canvas: { type: "string", minLength: 1 },
+      fixture: { type: "string", minLength: 1 },
+      renderer: { type: "string", minLength: 1 },
+      backend: { enum: ["auto", "webgpu", "webgl2"] },
+      conditions: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          renderScale: {
+            type: "object",
+            additionalProperties: false,
+            required: ["mode", "scale"],
+            properties: {
+              mode: { const: "fixed" },
+              scale: { type: "number", exclusiveMinimum: 0 }
+            }
+          }
+        }
+      },
+      tolerance,
+      clients: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name"],
+          properties: {
+            name: { type: "string", minLength: 1 },
+            role: { type: "string", minLength: 1 },
+            query: { type: "object", additionalProperties: { type: "string" } },
+            shots: { type: "array", items: shot }
+          }
+        }
+      },
+      shots: { type: "array", items: shot },
+      steps: { type: "array", items: step },
+      scenarios: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name", "seconds"],
+          properties: {
+            name: { type: "string", minLength: 1 },
+            steps: { type: "array", items: step },
+            seconds: { type: "number", minimum: 0 },
+            clients: strings
+          }
+        }
+      },
+      thresholds: {
+        type: "object",
+        additionalProperties: {
+          type: "object",
+          properties: {
+            spans: {
+              type: "array",
+              description: `Span budgets on records' breakdown (spec 0074): { "span": "partition/spawn", "p95": 2 }.`,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["span"],
+                properties: {
+                  span: { type: "string", minLength: 1 },
+                  p50: { type: "number", minimum: 0 },
+                  p95: { type: "number", minimum: 0 },
+                  max: { type: "number", minimum: 0 }
+                }
+              }
+            }
+          },
+          additionalProperties: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              max: { type: "number" },
+              min: { type: "number" },
+              maxRatioTo: { type: "string", minLength: 1 },
+              ratio: { type: "number", exclusiveMinimum: 0 }
+            }
+          }
+        }
+      },
+      timeoutMs: { type: "number", exclusiveMinimum: 0 }
+    }
+  };
+}
+function parsePlan(json, file) {
+  const errors = validateJson(capturePlanJsonSchema(), json);
+  const raw = json;
+  if (errors.length === 0) errors.push(...referenceErrors(raw));
+  if (errors.length > 0) {
+    throw new ShardError(
+      "verify/invalid-plan",
+      `${file ?? "The plan"} has ${errors.length} problem${errors.length === 1 ? "" : "s"}: ${errors[0].message} at ${errors[0].path}`,
+      {
+        path: file,
+        details: errors,
+        hint: "Plans follow .shard/schemas/capture-plan.schema.json."
+      }
+    );
+  }
+  const url = new URL(raw.url, "http://localhost/");
+  return {
+    url: raw.url,
+    browsers: raw.browsers ?? ["chromium"],
+    dpr: raw.dpr ?? [1],
+    viewport: raw.viewport ?? [1280, 720],
+    scope: raw.scope ?? "canvas",
+    canvas: raw.canvas ?? "canvas",
+    fixture: raw.fixture ?? `${url.pathname}${url.hash}`,
+    renderer: raw.renderer,
+    backend: raw.backend,
+    conditions: raw.conditions ?? {},
+    tolerance: raw.tolerance ?? {},
+    clients: raw.clients ?? [{ name: "main" }],
+    shots: raw.shots ?? [],
+    steps: raw.steps ?? [],
+    scenarios: raw.scenarios ?? [],
+    thresholds: raw.thresholds ?? {},
+    timeoutMs: raw.timeoutMs ?? 6e4
+  };
+}
+function referenceErrors(plan) {
+  const errors = [];
+  const clients = new Set((plan.clients ?? [{ name: "main" }]).map((c) => c.name));
+  const problem = (message, path) => errors.push(new ShardError("verify/invalid-json", message, { path }));
+  const unique = (names, path, what) => {
+    const seen = /* @__PURE__ */ new Set();
+    names.forEach((name, i) => {
+      if (seen.has(name)) problem(`Two ${what} are named "${name}"`, `${path}/${i}/name`);
+      seen.add(name);
+    });
+  };
+  unique(
+    (plan.clients ?? []).map((c) => c.name),
+    "/clients",
+    "clients"
+  );
+  unique(
+    (plan.shots ?? []).map((s) => s.name),
+    "/shots",
+    "shots"
+  );
+  unique(
+    (plan.steps ?? []).map((s) => s.name),
+    "/steps",
+    "steps"
+  );
+  unique(
+    (plan.scenarios ?? []).map((s) => s.name),
+    "/scenarios",
+    "scenarios"
+  );
+  const known = (names, path) => {
+    names?.forEach((name, i) => {
+      if (!clients.has(name)) problem(`No client is named "${name}"`, `${path}/${i}`);
+    });
+  };
+  const steps = (list, path) => {
+    list?.forEach((s, i) => {
+      known(s.clients, `${path}/${i}/clients`);
+      known(Object.keys(s.expect ?? {}), `${path}/${i}/expect`);
+    });
+  };
+  steps(plan.steps, "/steps");
+  plan.scenarios?.forEach((s, i) => {
+    known(s.clients, `/scenarios/${i}/clients`);
+    steps(s.steps, `/scenarios/${i}/steps`);
+  });
+  return errors;
+}
+function shotId(browser, client, shot2, dpr) {
+  return `${browser}/${client}/${shot2}@${dpr}x`;
+}
+export {
+  capturePlanJsonSchema,
+  parsePlan,
+  shotId
+};

package/dist/record.d.ts

@@ -0,0 +1,93 @@
+import type { JsonSchema, SpanStats } from '@aethervtt/shard-core';
+import { ShardError } from '@aethervtt/shard-core';
+/**
+ * One measured run of one scenario on one renderer (0062). Shard's `metrics.record` writes it, and
+ * so can any other renderer's page (Aether's three.js path) by the same definitions. Times are ms,
+ * sizes bytes.
+ */
+export interface PerfRecord {
+    /** 2 adds `breakdown` (0074); version 1 records still read. */
+    version: 1 | 2;
+    /** `shard@<sha>`, `three@0.160.1`: the part before `@` names the renderer in thresholds. */
+    renderer: string;
+    fixture: string;
+    scenario: string;
+    device: PerfDevice;
+    /** The render scale every frame of the window ran at (0051). A pinned run has min = max. */
+    renderScale: {
+        mode: 'fixed' | 'auto' | 'none';
+        min: number;
+        max: number;
+    };
+    /**
+     * `total`: navigation start to `app.init()` resolved; `modules`: navigation start to `init()`
+     * called. The rest are wall time that kind of work was in flight until the first usable frame:
+     * the GPU device request, pipeline compiles, asset loads. They overlap each other.
+     */
+    coldStart: {
+        total: number;
+        modules: number;
+        device: number;
+        pipelines: number;
+        assets: number;
+    };
+    /** Navigation start to the first frame presented after `app.markUsable()`. */
+    firstUsableFrame: number;
+    /** A host write (`app.trace`) to the frame that shows it being presented. */
+    patchToFrame: {
+        p50: number;
+        p95: number;
+        n: number;
+    };
+    /** Intervals between consecutive frames over the window; GPU time where timestamps exist. */
+    frameTime: {
+        p50: number;
+        p95: number;
+        p99: number;
+        n: number;
+        gpuP95?: number;
+    };
+    longTasks: {
+        count: number;
+        totalMs: number;
+        maxMs: number;
+    };
+    /** Every buffer and texture the renderer made, by what it's for. */
+    gpuMemory: {
+        bytes: number;
+        byCategory: Record<string, number>;
+    };
+    /** The page's downloads: the document, scripts, WASM, and assets. */
+    download: {
+        transferred: number;
+        decoded: number;
+    };
+    /**
+     * Where the time went (0074, version 2): the 10 spans with the highest p95, CPU (systems,
+     * schedules, render encodes, workers) and GPU passes, over the profiler's window.
+     */
+    breakdown?: {
+        cpu: SpanStats[];
+        gpu: SpanStats[];
+    };
+}
+export interface PerfDevice {
+    ua: string;
+    /** The adapter: vendor, architecture, description, whichever the browser reports. */
+    gpu: string;
+    dpr: number;
+    /** CSS pixels. */
+    viewport: [number, number];
+}
+/** JSON Schema for `PerfRecord` (shipped as `.shard/schemas/perf-record.schema.json`). */
+export declare function perfRecordJsonSchema(): JsonSchema;
+/**
+ * Checks `value` against a JSON Schema, for the keywords Shard's own schemas use: type, const,
+ * enum, required, properties, additionalProperties, items, min/maxItems, minLength, minimum,
+ * exclusiveMinimum. Returns every problem, each with its JSON path.
+ */
+export declare function validateJson(schema: JsonSchema, value: unknown, path?: string): ShardError[];
+/** Reads a record, or throws `verify/invalid-record` listing every problem. */
+export declare function parsePerfRecord(json: unknown, file?: string): PerfRecord;
+/** The renderer's name without its version: `three@0.160.1` → `three`. */
+export declare function rendererName(record: Pick<PerfRecord, 'renderer'>): string;

package/dist/record.js

@@ -0,0 +1,226 @@
+import { ShardError } from "@aethervtt/shard-core";
+const ms = { type: "number", minimum: 0 };
+const count = { type: "integer", minimum: 0 };
+const spanStats = {
+  type: "array",
+  items: {
+    type: "object",
+    additionalProperties: false,
+    required: ["span", "track", "calls", "total", "p50", "p95", "max"],
+    properties: {
+      span: { type: "string", minLength: 1 },
+      track: { enum: ["main", "gpu", "async", "gc", "worker"] },
+      calls: count,
+      total: ms,
+      p50: ms,
+      p95: ms,
+      max: ms
+    }
+  }
+};
+function perfRecordJsonSchema() {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://shard.dev/schemas/perf-record.schema.json",
+    title: "Shard performance record",
+    description: "One measured run of one scenario on one renderer (spec 0062). Times are milliseconds, sizes bytes.",
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "version",
+      "renderer",
+      "fixture",
+      "scenario",
+      "device",
+      "renderScale",
+      "coldStart",
+      "firstUsableFrame",
+      "patchToFrame",
+      "frameTime",
+      "longTasks",
+      "gpuMemory",
+      "download"
+    ],
+    properties: {
+      $schema: { type: "string" },
+      version: { enum: [1, 2] },
+      renderer: {
+        type: "string",
+        minLength: 1,
+        description: "'shard@<sha>' or 'three@0.160.1': the name before '@' is what thresholds use."
+      },
+      fixture: { type: "string", minLength: 1 },
+      scenario: { type: "string", minLength: 1 },
+      device: {
+        type: "object",
+        additionalProperties: false,
+        required: ["ua", "gpu", "dpr", "viewport"],
+        properties: {
+          ua: { type: "string" },
+          gpu: { type: "string" },
+          dpr: { type: "number", exclusiveMinimum: 0 },
+          viewport: {
+            type: "array",
+            items: { type: "number", minimum: 0 },
+            minItems: 2,
+            maxItems: 2,
+            description: "Width and height in CSS pixels."
+          }
+        }
+      },
+      renderScale: {
+        type: "object",
+        additionalProperties: false,
+        required: ["mode", "min", "max"],
+        description: "The render scale over the window. Pinned runs have min = max.",
+        properties: {
+          mode: { enum: ["fixed", "auto", "none"] },
+          min: { type: "number", exclusiveMinimum: 0 },
+          max: { type: "number", exclusiveMinimum: 0 }
+        }
+      },
+      coldStart: {
+        type: "object",
+        additionalProperties: false,
+        required: ["total", "modules", "device", "pipelines", "assets"],
+        properties: { total: ms, modules: ms, device: ms, pipelines: ms, assets: ms }
+      },
+      firstUsableFrame: ms,
+      patchToFrame: {
+        type: "object",
+        additionalProperties: false,
+        required: ["p50", "p95", "n"],
+        properties: { p50: ms, p95: ms, n: count }
+      },
+      frameTime: {
+        type: "object",
+        additionalProperties: false,
+        required: ["p50", "p95", "p99", "n"],
+        properties: { p50: ms, p95: ms, p99: ms, n: count, gpuP95: ms }
+      },
+      longTasks: {
+        type: "object",
+        additionalProperties: false,
+        required: ["count", "totalMs", "maxMs"],
+        properties: { count, totalMs: ms, maxMs: ms }
+      },
+      gpuMemory: {
+        type: "object",
+        additionalProperties: false,
+        required: ["bytes", "byCategory"],
+        properties: { bytes: count, byCategory: { type: "object", additionalProperties: count } }
+      },
+      download: {
+        type: "object",
+        additionalProperties: false,
+        required: ["transferred", "decoded"],
+        properties: { transferred: count, decoded: count }
+      },
+      breakdown: {
+        type: "object",
+        additionalProperties: false,
+        required: ["cpu", "gpu"],
+        description: "Version 2 (spec 0074): the 10 CPU and 10 GPU spans with the highest p95 over the window.",
+        properties: { cpu: spanStats, gpu: spanStats }
+      }
+    }
+  };
+}
+function validateJson(schema, value, path = "") {
+  const errors = [];
+  check(schema, value, path, errors);
+  return errors;
+}
+function check(schema, value, path, out) {
+  const fail = (message) => out.push(new ShardError("verify/invalid-json", message, { path: path || "/" }));
+  if ("const" in schema && value !== schema.const) {
+    return void fail(`Expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+  }
+  const options = schema.enum;
+  if (options && !options.includes(value)) {
+    return void fail(`Expected one of ${options.map((o) => JSON.stringify(o)).join(", ")}`);
+  }
+  const type = schema.type;
+  if (type && !isType(value, type)) return void fail(`Expected ${type}, got ${typeName(value)}`);
+  if (typeof value === "number") {
+    const min = schema.minimum;
+    const above = schema.exclusiveMinimum;
+    if (min !== void 0 && value < min) fail(`Expected at least ${min}, got ${value}`);
+    if (above !== void 0 && value <= above) fail(`Expected more than ${above}, got ${value}`);
+  }
+  if (typeof value === "string" && value.length < (schema.minLength ?? 0)) {
+    fail("Expected a non-empty string");
+  }
+  if (Array.isArray(value)) {
+    const min = schema.minItems;
+    const max = schema.maxItems;
+    if (min !== void 0 && value.length < min) fail(`Expected at least ${min} items`);
+    if (max !== void 0 && value.length > max) fail(`Expected at most ${max} items`);
+    const items = schema.items;
+    if (items) for (let i = 0; i < value.length; i++) check(items, value[i], `${path}/${i}`, out);
+  }
+  if (type !== "object" || !isType(value, "object")) return;
+  const object = value;
+  for (const key of schema.required ?? []) {
+    if (!(key in object))
+      out.push(
+        new ShardError("verify/invalid-json", `Missing "${key}"`, { path: `${path}/${key}` })
+      );
+  }
+  const properties = schema.properties ?? {};
+  const extra = schema.additionalProperties;
+  for (const [key, item] of Object.entries(object)) {
+    const own = properties[key];
+    if (own) check(own, item, `${path}/${key}`, out);
+    else if (extra === false) {
+      out.push(
+        new ShardError("verify/invalid-json", `Unknown field "${key}"`, { path: `${path}/${key}` })
+      );
+    } else if (extra && typeof extra === "object") check(extra, item, `${path}/${key}`, out);
+  }
+}
+function isType(value, type) {
+  switch (type) {
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    case "integer":
+      return Number.isInteger(value);
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    default:
+      return typeof value === type;
+  }
+}
+function typeName(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+  return typeof value;
+}
+function parsePerfRecord(json, file) {
+  const errors = validateJson(perfRecordJsonSchema(), json);
+  if (errors.length > 0) {
+    throw new ShardError(
+      "verify/invalid-record",
+      `${file ?? "The record"} isn't a valid performance record: ${errors[0].message} at ${errors[0].path}`,
+      {
+        path: file,
+        details: errors,
+        hint: "Records follow .shard/schemas/perf-record.schema.json."
+      }
+    );
+  }
+  return json;
+}
+function rendererName(record) {
+  const at = record.renderer.indexOf("@");
+  return at === -1 ? record.renderer : record.renderer.slice(0, at);
+}
+export {
+  parsePerfRecord,
+  perfRecordJsonSchema,
+  rendererName,
+  validateJson
+};

package/dist/report.d.ts

@@ -0,0 +1,20 @@
+import type { Approval } from './run.js';
+/** One shot's line in the compare report. Image paths are relative to the report. */
+export interface ReportShot {
+    id: string;
+    status: 'pass' | 'fail' | 'new';
+    reason?: string;
+    approved?: string;
+    capture: string;
+    heatmap?: string;
+    share?: number;
+    maxDeltaE?: number;
+    ssim?: number;
+    /** The latest approval of this shot, if any. */
+    approval?: Approval;
+}
+/**
+ * The compare report (0062): per shot, the approved image, the capture, and a heatmap of what
+ * changed, with the numbers and the reason it was last approved. Failures first.
+ */
+export declare function renderReport(title: string, shots: readonly ReportShot[]): string;

package/dist/report.js

@@ -0,0 +1,43 @@
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+function renderReport(title, shots) {
+  const order = { fail: 0, new: 1, pass: 2 };
+  const sorted = [...shots].sort(
+    (a, b) => order[a.status] - order[b.status] || a.id.localeCompare(b.id)
+  );
+  const count = (s) => shots.filter((x) => x.status === s).length;
+  const figure = (label, src) => src ? `<figure><img src="${escapeHtml(src)}" alt="${label}" loading="lazy"><figcaption>${label}</figcaption></figure>` : `<figure class="none"><div>none</div><figcaption>${label}</figcaption></figure>`;
+  const rows = sorted.map((s) => {
+    const numbers = s.share === void 0 ? "" : `<span>${(s.share * 100).toFixed(3)}% changed</span><span>max \u0394E ${s.maxDeltaE.toFixed(1)}</span><span>SSIM ${s.ssim.toFixed(4)}</span>`;
+    const approval = s.approval ? `<p class="approval">Approved ${escapeHtml(s.approval.date.slice(0, 10))} by ${escapeHtml(s.approval.by)}: ${escapeHtml(s.approval.reason)}</p>` : "";
+    return `<section class="${s.status}">
+<h2><span class="status">${s.status}</span> ${escapeHtml(s.id)}</h2>
+<p class="numbers">${numbers}${s.reason ? `<span class="reason">${escapeHtml(s.reason)}</span>` : ""}</p>${approval}
+<div class="row">${figure("approved", s.approved)}${figure("capture", s.capture)}${figure("changes", s.heatmap)}</div>
+</section>`;
+  });
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>
+body { font: 14px/1.4 system-ui, sans-serif; margin: 24px; background: #15171a; color: #d8dade; }
+h1 { font-size: 20px; } h2 { font-size: 15px; margin: 0 0 4px; font-family: ui-monospace, monospace; }
+section { border-left: 4px solid #3a8f5c; padding: 8px 12px; margin: 16px 0; background: #1c1f23; }
+section.fail { border-color: #d0463b; } section.new { border-color: #d8a93b; }
+.status { text-transform: uppercase; font-size: 11px; padding: 1px 6px; border-radius: 3px; background: #333; }
+.fail .status { background: #7a2620; } .new .status { background: #6d5620; }
+.numbers span { margin-right: 14px; color: #aab; } .reason { color: #f0b0a8 !important; }
+.approval { color: #9fb8a6; margin: 2px 0; }
+.row { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
+figure { margin: 0; } figure img { width: 100%; image-rendering: pixelated;
+  background: repeating-conic-gradient(#2a2d31 0 25%, #202226 0 50%) 0 0 / 16px 16px; }
+figure.none div { aspect-ratio: 16 / 9; display: grid; place-items: center; background: #202226; color: #667; }
+figcaption { color: #889; font-size: 12px; }
+</style></head><body>
+<h1>${escapeHtml(title)}</h1>
+<p>${count("fail")} changed, ${count("new")} new, ${count("pass")} unchanged.</p>
+${rows.join("\n")}
+</body></html>
+`;
+}
+export {
+  renderReport
+};

package/dist/run.d.ts

@@ -0,0 +1,56 @@
+import type { Tolerance } from './compare.js';
+import type { CheckFailure } from './expect.js';
+import type { CaptureScope } from './plan.js';
+/** What `shard capture` wrote: `<out>/manifest.json`, next to the PNGs and records. */
+export interface CaptureManifest {
+    version: 1;
+    url: string;
+    fixture: string;
+    /** ISO time the run started. */
+    date: string;
+    shots: CapturedShot[];
+    /** Record files, relative to the manifest. */
+    records: string[];
+    /** Steps that ran and the checks that failed (a run with failures exits 1). */
+    steps: {
+        name: string;
+        browser: string;
+        dpr: number;
+        failures: CheckFailure[];
+    }[];
+    /** Browsers the plan named that couldn't run it (no WebGPU, not installed), and why. */
+    skipped: {
+        browser: string;
+        reason: string;
+    }[];
+}
+export interface CapturedShot {
+    /** `chromium/main/map-close@2x`: also the PNG's path under the run, less `.png`. */
+    id: string;
+    browser: string;
+    client: string;
+    shot: string;
+    dpr: number;
+    scope: CaptureScope;
+    width: number;
+    height: number;
+    /** SHA-256 of the PNG file. */
+    hash: string;
+    tolerance: Tolerance;
+}
+/** `approvals.json` in the approved directory: why each approved image looks the way it does. */
+export interface ApprovalsFile {
+    version: 1;
+    approvals: Approval[];
+}
+export interface Approval {
+    shot: string;
+    /** SHA-256 of the approved PNG. */
+    hash: string;
+    reason: string;
+    by: string;
+    /** ISO time. */
+    date: string;
+}
+/** Appends an approval. Refuses one without a reason: every visible change is explained. */
+export declare function addApproval(file: ApprovalsFile | undefined, approval: Approval): ApprovalsFile;