@aethervtt/shard-verify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/compare.d.ts

@@ -0,0 +1,45 @@
+/** 8-bit RGBA with straight (not premultiplied) alpha, rows top to bottom: a decoded PNG. */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+}
+/** How different a capture may be from its approved image (per shot, in the plan). */
+export interface Tolerance {
+    /** ΔE2000 over which a pixel counts as changed. Default 2.3, about one just-noticeable difference. */
+    deltaE?: number;
+    /** Share of pixels (0 to 1) allowed to change. Default 0.001. */
+    maxShare?: number;
+    /** Lowest structural similarity allowed. Default 0.98. */
+    minSsim?: number;
+}
+export declare const DEFAULT_TOLERANCE: Required<Tolerance>;
+export interface ImageDiff {
+    pass: boolean;
+    /** Why it failed, in a sentence; undefined when it passed. */
+    reason: string | undefined;
+    /** Pixels over the ΔE threshold. */
+    changed: number;
+    /** `changed` over all pixels. */
+    share: number;
+    maxDeltaE: number;
+    /** Mean SSIM over 8×8 windows of luminance. */
+    ssim: number;
+    /** ΔE2000 of every pixel, row by row (for the heatmap). */
+    deltaE: Float32Array;
+    tolerance: Required<Tolerance>;
+}
+/**
+ * A perceptual diff (0062): each pixel's ΔE2000 in Lab, and SSIM over luminance. Dithering and
+ * driver noise stay under a just-noticeable difference, so they don't count; a shifted grid line
+ * or a lost shadow does. Alpha counts too: pixels are compared composited over black and over
+ * white, and the larger difference wins, so a transparent surface that turns opaque is a change.
+ */
+export declare function compareImages(approved: RgbaImage, capture: RgbaImage, tolerance?: Tolerance): ImageDiff;
+/**
+ * A heatmap of a diff as RGBA: unchanged pixels are a dim gray copy of the approved image's
+ * luminance, changes go from yellow (just over the threshold) to red (ΔE 20 and up).
+ */
+export declare function diffHeatmap(approved: RgbaImage, diff: ImageDiff): Uint8Array;
+/** CIEDE2000 color difference (Sharma, Wu and Dalal's formulation), kL = kC = kH = 1. */
+export declare function deltaE2000(L1: number, a1: number, b1: number, L2: number, a2: number, b2: number): number;

package/dist/compare.js

@@ -0,0 +1,213 @@
+import { ShardError } from "@aethervtt/shard-core";
+const DEFAULT_TOLERANCE = {
+  deltaE: 2.3,
+  maxShare: 1e-3,
+  minSsim: 0.98
+};
+function compareImages(approved, capture, tolerance = {}) {
+  const tol = { ...DEFAULT_TOLERANCE, ...tolerance };
+  if (approved.width !== capture.width || approved.height !== capture.height) {
+    throw new ShardError(
+      "verify/size-mismatch",
+      `The capture is ${capture.width}\xD7${capture.height}, the approved image ${approved.width}\xD7${approved.height}`,
+      { hint: "Check the viewport and DPR in the plan, or approve the new size with a reason." }
+    );
+  }
+  const n = approved.width * approved.height;
+  const deltaE = new Float32Array(n);
+  const a = approved.data;
+  const b = capture.data;
+  const labA = new Float64Array(6);
+  const labB = new Float64Array(6);
+  let changed = 0;
+  let maxDeltaE = 0;
+  for (let i = 0; i < n; i++) {
+    const o = i * 4;
+    if (a[o] === b[o] && a[o + 1] === b[o + 1] && a[o + 2] === b[o + 2] && a[o + 3] === b[o + 3]) {
+      continue;
+    }
+    composites(a, o, labA);
+    composites(b, o, labB);
+    const onBlack = deltaE2000(labA[0], labA[1], labA[2], labB[0], labB[1], labB[2]);
+    const onWhite = deltaE2000(labA[3], labA[4], labA[5], labB[3], labB[4], labB[5]);
+    const d = onBlack > onWhite ? onBlack : onWhite;
+    deltaE[i] = d;
+    if (d > tol.deltaE) changed++;
+    if (d > maxDeltaE) maxDeltaE = d;
+  }
+  const share = n === 0 ? 0 : changed / n;
+  const ssim = meanSsim(approved, capture);
+  let reason;
+  if (share > tol.maxShare) {
+    reason = `${(share * 100).toFixed(2)}% of pixels changed (\u0394E2000 > ${tol.deltaE}); ${(tol.maxShare * 100).toFixed(2)}% allowed`;
+  } else if (ssim < tol.minSsim) {
+    reason = `SSIM ${ssim.toFixed(4)} is under ${tol.minSsim}`;
+  }
+  return { pass: !reason, reason, changed, share, maxDeltaE, ssim, deltaE, tolerance: tol };
+}
+function diffHeatmap(approved, diff) {
+  const n = approved.width * approved.height;
+  const out = new Uint8Array(n * 4);
+  const src = approved.data;
+  const threshold = diff.tolerance.deltaE;
+  for (let i = 0; i < n; i++) {
+    const o = i * 4;
+    const d = diff.deltaE[i];
+    if (d > threshold) {
+      const t = Math.min(1, (d - threshold) / (20 - threshold));
+      out[o] = 255;
+      out[o + 1] = Math.round(220 * (1 - t));
+      out[o + 2] = 0;
+    } else {
+      const y = (0.2126 * src[o] + 0.7152 * src[o + 1] + 0.0722 * src[o + 2]) * (src[o + 3] / 255);
+      const gray = Math.round(40 + y * 0.25);
+      out[o] = gray;
+      out[o + 1] = gray;
+      out[o + 2] = gray;
+    }
+    out[o + 3] = 255;
+  }
+  return out;
+}
+const LINEAR = new Float64Array(256);
+for (let i = 0; i < 256; i++) {
+  const c = i / 255;
+  LINEAR[i] = c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function composites(data, o, out) {
+  const alpha = data[o + 3] / 255;
+  const r = LINEAR[data[o]] * alpha;
+  const g = LINEAR[data[o + 1]] * alpha;
+  const b = LINEAR[data[o + 2]] * alpha;
+  linearToLab(r, g, b, out, 0);
+  const white = 1 - alpha;
+  linearToLab(r + white, g + white, b + white, out, 3);
+}
+const XN = 0.95047;
+const ZN = 1.08883;
+function linearToLab(r, g, b, out, at) {
+  const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / XN;
+  const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+  const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / ZN;
+  const fx = labF(x);
+  const fy = labF(y);
+  const fz = labF(z);
+  out[at] = 116 * fy - 16;
+  out[at + 1] = 500 * (fx - fy);
+  out[at + 2] = 200 * (fy - fz);
+}
+function labF(t) {
+  return t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116;
+}
+const DEG = Math.PI / 180;
+const POW25_7 = 25 ** 7;
+function deltaE2000(L1, a1, b1, L2, a2, b2) {
+  const C12 = Math.sqrt(a1 * a1 + b1 * b1);
+  const C22 = Math.sqrt(a2 * a2 + b2 * b2);
+  const Cm7 = ((C12 + C22) / 2) ** 7;
+  const G = 0.5 * (1 - Math.sqrt(Cm7 / (Cm7 + POW25_7)));
+  const a1p = (1 + G) * a1;
+  const a2p = (1 + G) * a2;
+  const C1p = Math.sqrt(a1p * a1p + b1 * b1);
+  const C2p = Math.sqrt(a2p * a2p + b2 * b2);
+  const h1p = hueDegrees(b1, a1p);
+  const h2p = hueDegrees(b2, a2p);
+  const dLp = L2 - L1;
+  const dCp = C2p - C1p;
+  const chroma = C1p * C2p;
+  let dhp = 0;
+  if (chroma !== 0) {
+    dhp = h2p - h1p;
+    if (dhp > 180) dhp -= 360;
+    else if (dhp < -180) dhp += 360;
+  }
+  const dHp = 2 * Math.sqrt(chroma) * Math.sin(dhp / 2 * DEG);
+  const Lpm = (L1 + L2) / 2;
+  const Cpm = (C1p + C2p) / 2;
+  let hpm = h1p + h2p;
+  if (chroma !== 0) {
+    if (Math.abs(h1p - h2p) <= 180) hpm = (h1p + h2p) / 2;
+    else hpm = h1p + h2p < 360 ? (h1p + h2p + 360) / 2 : (h1p + h2p - 360) / 2;
+  }
+  const T = 1 - 0.17 * Math.cos((hpm - 30) * DEG) + 0.24 * Math.cos(2 * hpm * DEG) + 0.32 * Math.cos((3 * hpm + 6) * DEG) - 0.2 * Math.cos((4 * hpm - 63) * DEG);
+  const dTheta = 30 * Math.exp(-(((hpm - 275) / 25) ** 2));
+  const Cpm7 = Cpm ** 7;
+  const Rc = 2 * Math.sqrt(Cpm7 / (Cpm7 + POW25_7));
+  const L50 = (Lpm - 50) ** 2;
+  const Sl = 1 + 0.015 * L50 / Math.sqrt(20 + L50);
+  const Sc = 1 + 0.045 * Cpm;
+  const Sh = 1 + 0.015 * Cpm * T;
+  const Rt = -Math.sin(2 * dTheta * DEG) * Rc;
+  const l = dLp / Sl;
+  const c = dCp / Sc;
+  const h = dHp / Sh;
+  return Math.sqrt(l * l + c * c + h * h + Rt * c * h);
+}
+function hueDegrees(b, a) {
+  if (a === 0 && b === 0) return 0;
+  const h = Math.atan2(b, a) / DEG;
+  return h < 0 ? h + 360 : h;
+}
+const WINDOW = 8;
+const STRIDE = 4;
+const C1 = (0.01 * 255) ** 2;
+const C2 = (0.03 * 255) ** 2;
+function luminance(image) {
+  const n = image.width * image.height;
+  const out = new Float32Array(n);
+  const d = image.data;
+  for (let i = 0; i < n; i++) {
+    const o = i * 4;
+    const alpha = d[o + 3] / 255;
+    const y = 0.2126 * d[o] + 0.7152 * d[o + 1] + 0.0722 * d[o + 2];
+    out[i] = y * alpha + 128 * (1 - alpha);
+  }
+  return out;
+}
+function meanSsim(a, b) {
+  const width = a.width;
+  const height = a.height;
+  const x = luminance(a);
+  const y = luminance(b);
+  const w = Math.min(WINDOW, width);
+  const h = Math.min(WINDOW, height);
+  if (w === 0 || h === 0) return 1;
+  let total = 0;
+  let windows = 0;
+  for (let top = 0; top + h <= height; top += STRIDE) {
+    for (let left = 0; left + w <= width; left += STRIDE) {
+      let sx = 0;
+      let sy = 0;
+      let sxx = 0;
+      let syy = 0;
+      let sxy = 0;
+      for (let j = 0; j < h; j++) {
+        const row = (top + j) * width + left;
+        for (let i = 0; i < w; i++) {
+          const p = x[row + i];
+          const q = y[row + i];
+          sx += p;
+          sy += q;
+          sxx += p * p;
+          syy += q * q;
+          sxy += p * q;
+        }
+      }
+      const count = w * h;
+      const mx = sx / count;
+      const my = sy / count;
+      const vx = sxx / count - mx * mx;
+      const vy = syy / count - my * my;
+      const cov = sxy / count - mx * my;
+      total += (2 * mx * my + C1) * (2 * cov + C2) / ((mx * mx + my * my + C1) * (vx + vy + C2));
+      windows++;
+    }
+  }
+  return windows === 0 ? 1 : total / windows;
+}
+export {
+  DEFAULT_TOLERANCE,
+  compareImages,
+  deltaE2000,
+  diffHeatmap
+};

package/dist/expect.d.ts

@@ -0,0 +1,14 @@
+import type { Expectations } from './plan.js';
+/** A check that failed: which step, which client, which probe path, and what was wrong. */
+export interface CheckFailure {
+    step: string;
+    client: string;
+    path: string;
+    message: string;
+}
+/** The value at a dotted path (`owners.scene`, `entities.0`); undefined where it stops. */
+export declare function valueAt(value: unknown, path: string): unknown;
+/** Structural equality over JSON values. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Checks one client's probe after a step. Every failed matcher is its own failure. */
+export declare function checkExpectations(step: string, client: string, probe: unknown, expectations: Expectations): CheckFailure[];

package/dist/expect.js

@@ -0,0 +1,70 @@
+function valueAt(value, path) {
+  let at = value;
+  for (const key of path.split(".")) {
+    if (at === null || typeof at !== "object") return void 0;
+    at = at[key];
+  }
+  return at;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const other = b;
+    return a.length === other.length && a.every((item, i) => deepEqual(item, other[i]));
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every(
+    (k) => deepEqual(a[k], b[k])
+  );
+}
+const show = (value) => value === void 0 ? "nothing" : JSON.stringify(value);
+function checkExpectations(step, client, probe, expectations) {
+  const failures = [];
+  for (const [path, matcher] of Object.entries(expectations)) {
+    for (const message of match(valueAt(probe, path), matcher, probe)) {
+      failures.push({ step, client, path, message });
+    }
+  }
+  return failures;
+}
+function match(value, m, probe) {
+  const out = [];
+  if ("equals" in m && !deepEqual(value, m.equals)) {
+    out.push(`expected ${show(m.equals)}, got ${show(value)}`);
+  }
+  if (m.includes || m.excludes) {
+    if (!Array.isArray(value)) out.push(`expected a list, got ${show(value)}`);
+    else {
+      for (const item of m.includes ?? []) {
+        if (!value.some((v) => deepEqual(v, item))) out.push(`expected it to include ${show(item)}`);
+      }
+      for (const item of m.excludes ?? []) {
+        if (value.some((v) => deepEqual(v, item)))
+          out.push(`expected it not to include ${show(item)}`);
+      }
+    }
+  }
+  if (m.min !== void 0 || m.max !== void 0) {
+    if (typeof value !== "number") out.push(`expected a number, got ${show(value)}`);
+    else {
+      if (m.min !== void 0 && value < m.min) out.push(`expected at least ${m.min}, got ${value}`);
+      if (m.max !== void 0 && value > m.max) out.push(`expected at most ${m.max}, got ${value}`);
+    }
+  }
+  if (m.sameAs !== void 0) {
+    const other = valueAt(probe, m.sameAs);
+    if (!deepEqual(value, other)) {
+      out.push(`expected the same as ${m.sameAs} (${show(other)}), got ${show(value)}`);
+    }
+  }
+  return out;
+}
+export {
+  checkExpectations,
+  deepEqual,
+  valueAt
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { compareImages, DEFAULT_TOLERANCE, deltaE2000, diffHeatmap, type ImageDiff, type RgbaImage, type Tolerance, } from './compare.js';
+export { type CheckFailure, checkExpectations, deepEqual, valueAt } from './expect.js';
+export { type BrowserName, type CapturePlan, type CaptureScope, capturePlanJsonSchema, type Expectations, type Matcher, type PlanClient, type PlanConditions, type PlanScenario, type PlanShot, type PlanStep, parsePlan, shotId, type ThresholdRule, type Thresholds, } from './plan.js';
+export { type PerfDevice, type PerfRecord, parsePerfRecord, perfRecordJsonSchema, rendererName, validateJson, } from './record.js';
+export { type ReportShot, renderReport } from './report.js';
+export { type Approval, type ApprovalsFile, addApproval, type CapturedShot, type CaptureManifest, } from './run.js';
+export { type Breach, checkThresholds, type PerfCheck } from './thresholds.js';

package/dist/index.js

@@ -0,0 +1,42 @@
+import {
+  compareImages,
+  DEFAULT_TOLERANCE,
+  deltaE2000,
+  diffHeatmap
+} from "./compare.js";
+import { checkExpectations, deepEqual, valueAt } from "./expect.js";
+import {
+  capturePlanJsonSchema,
+  parsePlan,
+  shotId
+} from "./plan.js";
+import {
+  parsePerfRecord,
+  perfRecordJsonSchema,
+  rendererName,
+  validateJson
+} from "./record.js";
+import { renderReport } from "./report.js";
+import {
+  addApproval
+} from "./run.js";
+import { checkThresholds } from "./thresholds.js";
+export {
+  DEFAULT_TOLERANCE,
+  addApproval,
+  capturePlanJsonSchema,
+  checkExpectations,
+  checkThresholds,
+  compareImages,
+  deepEqual,
+  deltaE2000,
+  diffHeatmap,
+  parsePerfRecord,
+  parsePlan,
+  perfRecordJsonSchema,
+  renderReport,
+  rendererName,
+  shotId,
+  validateJson,
+  valueAt
+};

package/dist/metrics/index.d.ts

@@ -0,0 +1 @@
+export { Metrics, type MetricsOptions, MetricsResource, metricsMethods, metricsPlugin, type RecordMeta, } from './metrics.js';

package/dist/metrics/index.js

@@ -0,0 +1,12 @@
+import {
+  Metrics,
+  MetricsResource,
+  metricsMethods,
+  metricsPlugin
+} from "./metrics.js";
+export {
+  Metrics,
+  MetricsResource,
+  metricsMethods,
+  metricsPlugin
+};

package/dist/metrics/metrics.d.ts

@@ -0,0 +1,83 @@
+import type { HostPerformance } from '@aethervtt/shard-platform';
+import { type App, type AppMethod, type Plugin } from '@aethervtt/shard-runtime';
+import type { PerfRecord } from '../record.js';
+export interface MetricsOptions {
+    /**
+     * The host's instruments: long tasks and downloads (`createWebPerformance()` from
+     * `@aethervtt/shard-platform-web`, or a platform's `performance`). Without them both read 0.
+     */
+    performance?: HostPerformance;
+    /** How far back `frameTime` and `longTasks` look, in ms. Default 30 s. */
+    windowMs?: number;
+    /** What records name the renderer: `shard@<sha>`. Default `shard`. */
+    renderer?: string;
+    /**
+     * The clock, in ms. Default `performance.now`, which counts from navigation start. It must be
+     * the app's clock too (`AppOptions.now`).
+     */
+    now?: () => number;
+    /** Navigation start on that clock. Default 0. */
+    navigationStart?: number;
+}
+export interface RecordMeta {
+    fixture: string;
+    scenario: string;
+    /** Overrides `MetricsOptions.renderer` for this record. */
+    renderer?: string;
+}
+/**
+ * What an app measured for 0062's performance records: frame intervals, GPU frame times, traced
+ * host writes, and long tasks, each timestamped so a record covers one window. Recording into it
+ * each frame allocates nothing.
+ */
+export declare class Metrics {
+    readonly windowMs: number;
+    readonly renderer: string;
+    private readonly app;
+    private readonly now;
+    private readonly navigationStart;
+    private readonly performance;
+    private readonly frames;
+    private readonly gpuFrames;
+    private readonly traces;
+    private readonly longTasks;
+    private windowStart;
+    private lastStart;
+    /** The last frame asked for the next one, so the interval between them is a frame time. */
+    private continued;
+    private gpuSamples;
+    private scaleMin;
+    private scaleMax;
+    private scaleAuto;
+    private scaled;
+    private pipelinesMs;
+    private assetsMs;
+    constructor(app: App, options?: MetricsOptions);
+    /** Starts a new window: what was measured so far no longer counts (startup numbers stay). */
+    reset(): void;
+    /** @internal As a frame starts: the interval since the last one, if that one asked for this. */
+    frameStart(): void;
+    /** @internal As a frame ends: GPU time, render scale, and whether another frame follows. */
+    frameEnd(): void;
+    /** @internal */
+    trace(ms: number): void;
+    /** @internal */
+    longTask(start: number, duration: number): void;
+    /** @internal The first usable frame was presented: startup work in flight until now counts. */
+    usable(at: number): void;
+    /**
+     * 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: RecordMeta): PerfRecord;
+    private device;
+}
+export declare const MetricsResource: import("@aethervtt/shard-core").ResourceDef<Metrics>;
+/** `metrics.record` and `metrics.reset`, for agents measuring a running app. */
+export declare const metricsMethods: AppMethod[];
+/**
+ * Records 0062's performance metrics: `world.resource(MetricsResource).record(meta)` or the
+ * protocol's `metrics.record`. The host calls `app.markUsable()` once the scene is interactive,
+ * and `app.trace(label)` after writes whose latency counts.
+ */
+export declare function metricsPlugin(options?: MetricsOptions): Plugin;