@penpair/reflection-check 0.3.6 → 0.4.0

package/README.md

@@ -15,19 +15,19 @@ penpair reflection check --map design/implementation-cases.json --provider desig
 
 Mapping: `{"schemaVersion":1,"cases":[{"id":"dashboard-empty-dark","setup":"dark-empty"}]}`. A case must have current exact approved provenance, matching file pin and an explicit setup name. Missing mappings, legacy approvals and changed case metadata remain pending. No setup is silently replaced by the default route state. Baselines remain owned by the core; this adapter neither captures nor approves design references.
 
-The provider module exports `async runCase(test)` and receives the immutable case ID, route, setup key, declared intent, baseline relative path/hash/scale and threshold. It must activate the route/theme/state/data fixture, verify actual browser state and fonts independently, capture a new PNG at the requested scale, and use the installed checker to compare it with the approved image. It returns:
+The provider module exports `async runCase(test)` and receives the immutable case ID, route, setup key, declared intent, baseline relative path/hash/scale and threshold. It must activate the route/theme/state/data fixture, verify actual browser state and fonts independently, capture a new static lossless WebP at the requested scale (legacy PNG evidence remains supported), and use the installed checker to compare it with the approved image. It returns:
 
 ```json
 {
   "schemaVersion":1,"id":"dashboard-empty-dark","route":"/dashboard","setup":"dark-empty",
   "observed":{"viewport":{"width":1280,"height":900},"theme":"dark","state":"empty","fixture":"no-items"},
   "fonts":["Expected Font"],"fontsReady":true,"baselineHash":"EXACT_SHA256",
-  "screenshot":".penpair/comparison/dashboard.png","diffPixelRatio":0.01,
+  "screenshot":".penpair/comparison/dashboard.webp","diffPixelRatio":0.01,
   "provider":{"name":"PROJECT_PINNED_CHECKER","version":"ACTUAL_VERSION"}
 }
 ```
 
-Observed context must come from browser readback, not copied test inputs. The adapter checks context/font evidence, independent screenshot path, PNG dimensions, byte hashes and unchanged baseline bytes. A trusted provider can lie: this interface is an evidence contract, not a sandbox or cryptographic attestation of browser work. Modules and transitive imports execute project code. Pixel ratios are checker evidence, never a visual verdict, accessibility assessment or owner approval. Exit 0 means complete evidence within thresholds; 2 means measured drift; 3 means missing/incomplete evidence. Every result still says `owner-review-required`.
+Observed context must come from browser readback, not copied test inputs. The adapter checks context/font evidence, independent screenshot path, exact image dimensions, byte hashes and unchanged baseline bytes. A trusted provider can lie: this interface is an evidence contract, not a sandbox or cryptographic attestation of browser work. Modules and transitive imports execute project code. Pixel ratios are checker evidence, never a visual verdict, accessibility assessment or owner approval. Exit 0 means complete evidence within thresholds; 2 means measured drift; 3 means missing/incomplete evidence. Every result still says `owner-review-required`.
 
 The shipped browser starter has been exercised against local fixture routes; the
 adapter's offline integration test uses a named stub. Neither establishes parity
@@ -35,3 +35,18 @@ for a consumer's implementation. Use the shipped `penpair-verify` skill, run the
 consumer's real provider against approved references and retain the resulting
 images before claiming comparison readiness. Owner review remains separate.
 Release/publishing is the owner's act and all six packages remain in lockstep.
+
+Evidence formats are detected from bytes, not filenames: PNG and static lossless
+WebP (`VP8L`, including a matching `VP8X` canvas) are accepted. Lossy or animated
+WebP and malformed/truncated containers are rejected. The adapter inspects image
+metadata and hashes; the project provider owns actual decoding and pixel comparison.
+Existing PNG baseline approvals retain their exact bytes and hashes. New core
+baseline/approval images default to lossless WebP; public Penpot PNG exports remain
+PNG. Existing approved references are never silently converted.
+
+The browser starter saves `.webp` evidence by default. Supply `encodeLosslessWebp`
+from the project's pinned codec, for example Sharp with `lossless: true` and
+`exact: true` to preserve transparent-pixel RGB. The starter independently checks
+that encoding preserves decoded pixels before saving. Use `imageFormat: "png"`
+for an explicit legacy provider path. Neither the adapter nor core gains a native
+image-codec runtime dependency.

package/dist/image-evidence.d.ts

@@ -0,0 +1,6 @@
+export declare function hashImageBytes(bytes: Buffer): string;
+export declare function readImageEvidence(root: string, file: string): Promise<{
+    bytes: Buffer;
+    width: number;
+    height: number;
+}>;

package/dist/image-evidence.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+import { readImageEvidence as readCoreImageEvidence } from "@penpair/core";
+export function hashImageBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export async function readImageEvidence(root, file) {
+    const { bytes, width, height } = await readCoreImageEvidence(root, file);
+    return {
+        bytes,
+        width,
+        height,
+    };
+}

package/dist/run-cases.js

@@ -1,17 +1,17 @@
 import { resolveProjectInput } from "@penpair/core";
 import { validateProviderEvidence } from "./evidence-validation.js";
-import { hashPngBytes, readPngEvidence } from "./png-evidence.js";
+import { hashImageBytes, readImageEvidence } from "./image-evidence.js";
 async function collectCaseEvidence(root, implementationCase, provider) {
     if (!(Number.isFinite(implementationCase.baseline.scale) && implementationCase.baseline.scale > 0)) {
         throw new Error("Missing capture scale");
     }
-    const baselineImage = await readPngEvidence(root, implementationCase.baseline.path);
-    if (hashPngBytes(baselineImage.bytes) !== implementationCase.baseline.sha256) {
+    const baselineImage = await readImageEvidence(root, implementationCase.baseline.path);
+    if (hashImageBytes(baselineImage.bytes) !== implementationCase.baseline.sha256) {
         throw new Error("Approved baseline bytes changed");
     }
     const evidence = await provider.runCase(structuredClone(implementationCase));
     validateProviderEvidence(evidence, implementationCase);
-    const implementationImage = await readPngEvidence(root, evidence.screenshot);
+    const implementationImage = await readImageEvidence(root, evidence.screenshot);
     const screenshotPath = await resolveProjectInput(root, evidence.screenshot);
     const baselinePath = await resolveProjectInput(root, implementationCase.baseline.path);
     if (screenshotPath === baselinePath) {
@@ -23,10 +23,10 @@ async function collectCaseEvidence(root, implementationCase, provider) {
         implementationImage.height !== Math.round(viewport.height * scale) ||
         baselineImage.width !== implementationImage.width ||
         baselineImage.height !== implementationImage.height) {
-        throw new Error("Provider PNG scale/viewport differs from the design case");
+        throw new Error("Provider image scale/viewport differs from the design case");
     }
-    const baselineAfterCapture = await readPngEvidence(root, implementationCase.baseline.path);
-    if (hashPngBytes(baselineAfterCapture.bytes) !== implementationCase.baseline.sha256) {
+    const baselineAfterCapture = await readImageEvidence(root, implementationCase.baseline.path);
+    if (hashImageBytes(baselineAfterCapture.bytes) !== implementationCase.baseline.sha256) {
         throw new Error("Baseline changed during provider execution");
     }
     return {
@@ -34,7 +34,7 @@ async function collectCaseEvidence(root, implementationCase, provider) {
         complete: true,
         withinThreshold: evidence.diffPixelRatio <= implementationCase.threshold,
         evidence,
-        screenshotHash: hashPngBytes(implementationImage.bytes),
+        screenshotHash: hashImageBytes(implementationImage.bytes),
     };
 }
 export async function runImplementationCases(root, plan, provider) {

package/dist/types.d.ts

@@ -82,6 +82,7 @@ export interface ProviderEvidence {
     fontsReady: boolean;
     baselineHash: string;
     capture?: BrowserCaptureMetadata;
+    /** Independently captured static lossless WebP (preferred) or legacy PNG evidence. */
     screenshot: string;
     diffPixelRatio: number;
     provider: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/reflection-check",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Explicit design case planning and verified implementation evidence for penpair baselines.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "jiti": "^2.4.2",
-    "@penpair/core": "0.3.6"
+    "@penpair/core": "0.4.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/dist/png-evidence.d.ts

@@ -1,6 +0,0 @@
-export declare function hashPngBytes(bytes: Buffer): string;
-export declare function readPngEvidence(root: string, file: string): Promise<{
-    bytes: Buffer;
-    width: number;
-    height: number;
-}>;

package/dist/png-evidence.js

@@ -1,23 +0,0 @@
-import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
-import { resolveProjectInput } from "@penpair/core";
-export function hashPngBytes(bytes) {
-    return createHash("sha256").update(bytes).digest("hex");
-}
-export async function readPngEvidence(root, file) {
-    const input = await resolveProjectInput(root, file);
-    if ((await stat(input)).size > 64 * 1024 * 1024) {
-        throw new Error("Image exceeds 64 MiB");
-    }
-    const bytes = await readFile(input);
-    if (bytes.length < 24 ||
-        bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a" ||
-        bytes.subarray(12, 16).toString() !== "IHDR") {
-        throw new Error("Provider evidence must reference PNG bytes");
-    }
-    return {
-        bytes,
-        width: bytes.readUInt32BE(16),
-        height: bytes.readUInt32BE(20),
-    };
-}