@penpair/reflection-check 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,10 @@
 # @penpair/reflection-check
 
-An optional adapter for explicit implementation-case evidence against approved penpair baselines. Add it to `adapters` and install it alongside one command package at the same reviewed version. It depends on the neutral core; the core does not load or depend on this adapter.
+The recommended companion when you implement a frontend from Penpot and want repeatable visual checks against approved designs. It is an optional package installed alongside one command package at the same reviewed version and registered in `adapters`.
+
+**Penpot design → approved reference and handoff → frontend code → browser capture → comparison → owner review.** Start with the [companion setup guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md#check-the-frontend-against-the-design) for installation, registration and the readiness checklist. Installing the package does not configure application state or supply a browser provider.
+
+It depends on the neutral core; the core does not load or depend on this adapter.
 
 The existing generated Reflection `visualSmoke` configuration remains the simple route for legacy cases. This adapter addresses the missing setup hook for rich theme/state/fixture/font cases. It does not bundle a browser or assume a version-specific Reflection API. A trusted project provider owns actual application activation, capture and comparison using the project's pinned browser/checker stack.
 

package/dist/capture-validation.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserCaptureMetadata, ImplementationCase } from "./types.js";
+export declare function validateCaptureMetadata(capture: BrowserCaptureMetadata, implementationCase: ImplementationCase): void;

package/dist/capture-validation.js

@@ -0,0 +1,65 @@
+function hasValidGeometry(capture, implementationCase) {
+    const rootBox = capture.rootBox;
+    const clip = capture.clip;
+    if (!rootBox || !clip) {
+        return false;
+    }
+    if (![
+        rootBox.x,
+        rootBox.y,
+        rootBox.width,
+        rootBox.height,
+        clip.x,
+        clip.y,
+        clip.width,
+        clip.height,
+    ].every(Number.isFinite)) {
+        return false;
+    }
+    return (rootBox.x >= 0 &&
+        rootBox.y >= 0 &&
+        rootBox.width > 0 &&
+        rootBox.height > 0 &&
+        clip.x === Math.floor(rootBox.x) &&
+        clip.y === Math.floor(rootBox.y) &&
+        clip.width === Math.ceil(rootBox.x + rootBox.width) - clip.x &&
+        clip.height === Math.ceil(rootBox.y + rootBox.height) - clip.y &&
+        clip.width === implementationCase.intent.viewport.width &&
+        clip.height === implementationCase.intent.viewport.height);
+}
+function hasStableUnobstructedLayout(capture) {
+    const pointer = capture.pointer;
+    const scroll = capture.scroll;
+    const occlusion = capture.occlusion;
+    return (pointer?.outsideRoot === true &&
+        pointer.hoveredControls === 0 &&
+        Number.isFinite(pointer.x) &&
+        Number.isFinite(pointer.y) &&
+        Boolean(scroll) &&
+        [
+            scroll.x,
+            scroll.y,
+        ].every(Number.isFinite) &&
+        Number.isInteger(capture.layoutSamples) &&
+        capture.layoutSamples >= 3 &&
+        (!occlusion ||
+            (Number.isInteger(occlusion.samples) && occlusion.samples >= 1 && occlusion.blocked === 0)));
+}
+function hasLoadedFonts(capture, expectedFonts) {
+    return (Array.isArray(capture.fonts) &&
+        capture.fonts.every((font) => Boolean(font.family && font.weight && font.style && font.status === "loaded")) &&
+        expectedFonts.every((expectedFont) => capture.fonts.some((font) => font.family === expectedFont)));
+}
+export function validateCaptureMetadata(capture, implementationCase) {
+    if (capture.schemaVersion !== 1 ||
+        !capture.root ||
+        capture.rounding !== "outward-css-pixels" ||
+        capture.deviceScaleFactor !== implementationCase.baseline.scale ||
+        !capture.browser?.name ||
+        !capture.browser.version ||
+        !hasValidGeometry(capture, implementationCase) ||
+        !hasStableUnobstructedLayout(capture) ||
+        !hasLoadedFonts(capture, implementationCase.intent.fonts ?? [])) {
+        throw new Error("Invalid browser capture geometry, font or pointer evidence");
+    }
+}

package/dist/case-plan.d.ts

@@ -0,0 +1,3 @@
+import { type BaselineResult, type BaselinesConfig } from "@penpair/core";
+import type { CasePlan, ImplementationMapping } from "./types.js";
+export declare function planImplementationCases(config: BaselinesConfig, results: BaselineResult[], mapping: ImplementationMapping): CasePlan;

package/dist/case-plan.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import { observationHash, validateBaselineCase, } from "@penpair/core";
+function validateMapping(mapping) {
+    if (!mapping ||
+        mapping.schemaVersion !== 1 ||
+        !Array.isArray(mapping.cases) ||
+        mapping.cases.length > 1000) {
+        throw new Error("Unsupported implementation mapping");
+    }
+    const mappedIds = new Set();
+    for (const entry of mapping.cases) {
+        if (!entry ||
+            typeof entry.id !== "string" ||
+            !entry.id ||
+            mappedIds.has(entry.id) ||
+            typeof entry.setup !== "string" ||
+            !/^[a-zA-Z][\w.-]{0,100}$/.test(entry.setup)) {
+            throw new Error("Duplicate/invalid explicit setup mapping");
+        }
+        mappedIds.add(entry.id);
+    }
+}
+function matchingCaseApproval(result, intent) {
+    const approved = result?.approved && !("legacy" in result.approved) ? result.approved : undefined;
+    if (!result ||
+        !approved?.case ||
+        !result.captured ||
+        approved.approval?.kind === "forced-reference") {
+        return undefined;
+    }
+    if (![
+        "same",
+        "new",
+        "changed",
+    ].includes(result.status)) {
+        return undefined;
+    }
+    const matchesCase = observationHash(approved.case) === observationHash(intent);
+    const matchesCapture = approved.sha256 === result.captured.sha256 &&
+        approved.frameId === result.frameId &&
+        approved.fileId === result.captured.fileId &&
+        approved.pageId === result.captured.pageId &&
+        approved.revision === result.captured.revision &&
+        approved.file === result.file;
+    return matchesCase && matchesCapture ? approved : undefined;
+}
+export function planImplementationCases(config, results, mapping) {
+    validateMapping(mapping);
+    const cases = [];
+    const pending = [];
+    for (const frame of config.frames) {
+        if (!frame.route) {
+            continue;
+        }
+        const result = results.find((baselineResult) => baselineResult.id === frame.id);
+        const setup = mapping.cases.find((entry) => entry.id === frame.id)?.setup;
+        const approved = frame.case && result && setup ? matchingCaseApproval(result, frame.case) : undefined;
+        if (!frame.case || !result || !approved || !setup) {
+            pending.push({
+                id: frame.id,
+                reason: "Requires current exact approved case provenance and an explicit implementation setup; legacy cases keep the existing generated Reflection path",
+            });
+            continue;
+        }
+        validateBaselineCase(frame.case, (message) => {
+            throw new Error(message);
+        });
+        cases.push({
+            id: frame.id,
+            route: frame.route,
+            intent: structuredClone(frame.case),
+            setup,
+            baseline: {
+                path: path.join(config.root, result.file),
+                sha256: approved.sha256,
+                scale: approved.scale,
+            },
+            threshold: config.threshold ?? 0.05,
+        });
+    }
+    for (const entry of mapping.cases) {
+        if (!config.frames.some((frame) => frame.id === entry.id)) {
+            pending.push({
+                id: entry.id,
+                reason: "Mapping refers to no configured baseline",
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        kind: "implementation-case-plan",
+        cases,
+        pending,
+        complete: pending.length === 0 && cases.length > 0,
+        visualApproval: false,
+    };
+}

package/dist/command.d.ts

@@ -0,0 +1,2 @@
+import { type AdapterContext } from "@penpair/core";
+export declare function runReflectionCommand(context: AdapterContext, commandArguments: string[]): Promise<number>;

package/dist/command.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createJiti } from "jiti";
+import { parseCommandArgs, readDesignJson, resolveProjectInput, } from "@penpair/core";
+import { planImplementationCases } from "./case-plan.js";
+import { runImplementationCases } from "./run-cases.js";
+export async function runReflectionCommand(context, commandArguments) {
+    const [subcommand, ...subcommandArguments] = commandArguments;
+    const { values, positionals } = parseCommandArgs({
+        args: subcommandArguments,
+        allowPositionals: true,
+        options: {
+            map: {
+                type: "string",
+            },
+            provider: {
+                type: "string",
+            },
+            json: {
+                type: "boolean",
+            },
+        },
+    });
+    if (![
+        "plan",
+        "check",
+    ].includes(subcommand ?? "") ||
+        positionals.length ||
+        !values.map ||
+        (subcommand === "plan" && values.provider) ||
+        (subcommand === "check" && !values.provider)) {
+        throw new Error("Usage: reflection plan --map FILE | reflection check --map FILE --provider FILE");
+    }
+    const baselinesConfig = context.config.baselines;
+    if (!baselinesConfig) {
+        throw new Error("Configure baselines first");
+    }
+    const manifest = (await readDesignJson(context.root, path.join(baselinesConfig.root, "penpair-baselines.json")));
+    if (manifest.schemaVersion !== 2 ||
+        !Array.isArray(manifest.frames) ||
+        !context.config.file ||
+        manifest.fileId !== context.config.file.id) {
+        throw new Error("A schema-2 baseline manifest matching the configured file pin is required");
+    }
+    const plan = planImplementationCases(baselinesConfig, manifest.frames, (await readDesignJson(context.root, values.map, 1024 * 1024)));
+    let report = plan;
+    let exitCode = plan.complete ? 0 : 3;
+    if (subcommand === "check") {
+        const providerFile = await resolveProjectInput(context.root, values.provider);
+        const provider = (await createJiti(providerFile, {
+            moduleCache: false,
+            tryNative: false,
+        }).evalModule(await readFile(providerFile, "utf8"), {
+            filename: providerFile,
+            async: true,
+            forceTranspile: true,
+        }));
+        if (typeof provider.runCase !== "function") {
+            throw new Error("Trusted project provider must export async runCase(test)");
+        }
+        const result = await runImplementationCases(context.root, plan, provider);
+        report = result;
+        exitCode = !result.complete
+            ? 3
+            : result.cases.some((caseReport) => caseReport.withinThreshold === false)
+                ? 2
+                : 0;
+    }
+    context.output?.result(report);
+    (context.output?.log ?? console.log)(JSON.stringify(report, null, 2));
+    return exitCode;
+}

package/dist/evidence-validation.d.ts

@@ -0,0 +1,2 @@
+import type { ImplementationCase, ProviderEvidence } from "./types.js";
+export declare function validateProviderEvidence(evidence: ProviderEvidence, implementationCase: ImplementationCase): void;

package/dist/evidence-validation.js

@@ -0,0 +1,34 @@
+import { observationHash } from "@penpair/core";
+import { validateCaptureMetadata } from "./capture-validation.js";
+export function validateProviderEvidence(evidence, implementationCase) {
+    const requestedObservation = {
+        viewport: implementationCase.intent.viewport,
+        theme: implementationCase.intent.theme,
+        state: implementationCase.intent.state,
+        fixture: implementationCase.intent.fixture,
+    };
+    if (!evidence ||
+        evidence.schemaVersion !== 1 ||
+        evidence.id !== implementationCase.id ||
+        evidence.route !== implementationCase.route ||
+        evidence.setup !== implementationCase.setup ||
+        observationHash(evidence.observed) !== observationHash(requestedObservation) ||
+        evidence.baselineHash !== implementationCase.baseline.sha256 ||
+        evidence.fontsReady !== true ||
+        !Array.isArray(evidence.fonts) ||
+        (implementationCase.intent.fonts ?? []).some((font) => !evidence.fonts.includes(font)) ||
+        !evidence.provider?.name ||
+        !evidence.provider.version ||
+        !Number.isFinite(evidence.diffPixelRatio) ||
+        evidence.diffPixelRatio < 0 ||
+        evidence.diffPixelRatio > 1) {
+        throw new Error("Provider did not independently observe the exact requested state, fixture, viewport, fonts and baseline");
+    }
+    if (evidence.provider.name === "penpair-browser-starter-rgba-exact" &&
+        (!evidence.capture || !evidence.capture.occlusion)) {
+        throw new Error("Browser starter requires complete capture metadata");
+    }
+    if (evidence.capture) {
+        validateCaptureMetadata(evidence.capture, implementationCase);
+    }
+}

package/dist/index.d.ts

@@ -1,82 +1,14 @@
-import { type AdapterContext, type BaselineCase, type BaselineResult, type BaselinesConfig } from "@penpair/core";
-export interface ImplementationMapping {
-    schemaVersion: 1;
-    cases: Array<{
-        id: string;
-        setup: string;
-    }>;
-}
-export interface ImplementationCase {
-    id: string;
-    route: string;
-    intent: BaselineCase;
-    setup: string;
-    baseline: {
-        path: string;
-        sha256: string;
-        scale: number;
-    };
-    threshold: number;
-}
-export interface CasePlan {
-    schemaVersion: 1;
-    kind: "implementation-case-plan";
-    cases: ImplementationCase[];
-    pending: Array<{
-        id: string;
-        reason: string;
-    }>;
-    complete: boolean;
-    visualApproval: false;
-}
-export interface ProviderEvidence {
-    schemaVersion: 1;
-    id: string;
-    route: string;
-    setup: string;
-    observed: Pick<BaselineCase, "viewport" | "theme" | "state" | "fixture">;
-    fonts: string[];
-    fontsReady: boolean;
-    baselineHash: string;
-    screenshot: string;
-    diffPixelRatio: number;
-    provider: {
-        name: string;
-        version: string;
-    };
-}
-export interface ImplementationProvider {
-    runCase(test: ImplementationCase): Promise<ProviderEvidence>;
-}
-export declare function planImplementationCases(config: BaselinesConfig, results: BaselineResult[], mapping: ImplementationMapping): CasePlan;
-export declare function runImplementationCases(root: string, plan: CasePlan, provider: ImplementationProvider): Promise<{
-    schemaVersion: number;
-    kind: string;
-    complete: boolean;
-    cases: {
-        id: string;
-        complete: boolean;
-        withinThreshold?: boolean;
-        evidence?: ProviderEvidence;
-        screenshotHash?: string;
-        reason?: string;
-    }[];
-    pending: {
-        id: string;
-        reason: string;
-    }[];
-    visualApproval: boolean;
-    verdict: string;
-    accessibility: string;
-}>;
-declare function command(context: AdapterContext, args: string[]): Promise<number>;
+import { runReflectionCommand } from "./command.js";
+export { planImplementationCases } from "./case-plan.js";
+export { runImplementationCases } from "./run-cases.js";
+export type { ImplementationMapping, ImplementationCase, CasePlan, BrowserCaptureMetadata, ProviderEvidence, ImplementationProvider, ImplementationCaseReport, ImplementationReport, } from "./types.js";
 declare const _default: {
     name: string;
     commands: {
         name: string;
         summary: string;
         usage: string[];
-        run: typeof command;
+        run: typeof runReflectionCommand;
     }[];
 };
 export default _default;

package/dist/index.js

@@ -1,97 +1,18 @@
-import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
-import path from "node:path";
-import { createJiti } from "jiti";
-import { defineAdapter, observationHash, parseCommandArgs, readDesignJson, resolveProjectInput, validateBaselineCase } from "@penpair/core";
-const sha = (b) => createHash("sha256").update(b).digest("hex");
-export function planImplementationCases(config, results, mapping) {
-    if (!mapping || mapping.schemaVersion !== 1 || !Array.isArray(mapping.cases) || mapping.cases.length > 1000)
-        throw new Error("Unsupported implementation mapping");
-    const names = new Set();
-    for (const entry of mapping.cases)
-        if (!entry || typeof entry.id !== "string" || !entry.id || names.has(entry.id) || typeof entry.setup !== "string" || !/^[a-zA-Z][\w.-]{0,100}$/.test(entry.setup))
-            throw new Error("Duplicate/invalid explicit setup mapping");
-        else
-            names.add(entry.id);
-    const cases = [], pending = [];
-    for (const wanted of config.frames) {
-        if (!wanted.route)
-            continue;
-        const result = results.find(r => r.id === wanted.id), setup = mapping.cases.find(c => c.id === wanted.id)?.setup;
-        const approved = result?.approved && !("legacy" in result.approved) ? result.approved : undefined;
-        if (approved?.approval?.kind === "forced-reference" || !wanted.case || !result || !approved?.case || !setup || !["same", "new", "changed"].includes(result.status) || !result.captured || approved.sha256 !== result.captured.sha256 || observationHash(approved.case) !== observationHash(wanted.case) || approved.frameId !== result.frameId || approved.fileId !== result.captured.fileId || approved.pageId !== result.captured.pageId || approved.revision !== result.captured.revision || approved.file !== result.file) {
-            pending.push({ id: wanted.id, reason: "Requires current exact approved case provenance and an explicit implementation setup; legacy cases keep the existing generated Reflection path" });
-            continue;
-        }
-        validateBaselineCase(wanted.case, message => { throw new Error(message); });
-        cases.push({ id: wanted.id, route: wanted.route, intent: structuredClone(wanted.case), setup, baseline: { path: path.join(config.root, result.file), sha256: approved.sha256, scale: approved.scale }, threshold: config.threshold ?? 0.05 });
-    }
-    for (const entry of mapping.cases)
-        if (!config.frames.some(f => f.id === entry.id))
-            pending.push({ id: entry.id, reason: "Mapping refers to no configured baseline" });
-    return { schemaVersion: 1, kind: "implementation-case-plan", cases, pending, complete: pending.length === 0 && cases.length > 0, visualApproval: false };
-}
-async function png(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) };
-}
-export async function runImplementationCases(root, plan, provider) {
-    const reports = [];
-    for (const c of plan.cases) {
-        try {
-            if (!(Number.isFinite(c.baseline.scale) && c.baseline.scale > 0))
-                throw new Error("Missing capture scale");
-            const before = await png(root, c.baseline.path);
-            if (sha(before.bytes) !== c.baseline.sha256)
-                throw new Error("Approved baseline bytes changed");
-            const evidence = await provider.runCase(structuredClone(c));
-            const desired = { viewport: c.intent.viewport, theme: c.intent.theme, state: c.intent.state, fixture: c.intent.fixture };
-            if (!evidence || evidence.schemaVersion !== 1 || evidence.id !== c.id || evidence.route !== c.route || evidence.setup !== c.setup || observationHash(evidence.observed) !== observationHash(desired) || evidence.baselineHash !== c.baseline.sha256 || evidence.fontsReady !== true || !Array.isArray(evidence.fonts) || (c.intent.fonts ?? []).some(font => !evidence.fonts.includes(font)) || !evidence.provider?.name || !evidence.provider.version || !Number.isFinite(evidence.diffPixelRatio) || evidence.diffPixelRatio < 0 || evidence.diffPixelRatio > 1)
-                throw new Error("Provider did not independently observe the exact requested state, fixture, viewport, fonts and baseline");
-            const shot = await png(root, evidence.screenshot);
-            if (await resolveProjectInput(root, evidence.screenshot) === await resolveProjectInput(root, c.baseline.path))
-                throw new Error("Screenshot must be independently captured, not the baseline path");
-            if (shot.width !== Math.round(c.intent.viewport.width * c.baseline.scale) || shot.height !== Math.round(c.intent.viewport.height * c.baseline.scale) || before.width !== shot.width || before.height !== shot.height)
-                throw new Error("Provider PNG scale/viewport differs from the design case");
-            if (sha((await png(root, c.baseline.path)).bytes) !== c.baseline.sha256)
-                throw new Error("Baseline changed during provider execution");
-            reports.push({ id: c.id, complete: true, withinThreshold: evidence.diffPixelRatio <= c.threshold, evidence, screenshotHash: sha(shot.bytes) });
-        }
-        catch (error) {
-            reports.push({ id: c.id, complete: false, reason: String(error.message) });
-        }
-    }
-    return { schemaVersion: 1, kind: "implementation-case-evidence", complete: plan.complete && reports.length > 0 && reports.every(r => r.complete), cases: reports, pending: plan.pending, visualApproval: false, verdict: "owner-review-required", accessibility: "not-assessed" };
-}
-async function command(context, args) {
-    const [sub, ...rest] = args;
-    const { values, positionals } = parseCommandArgs({ args: rest, allowPositionals: true, options: { map: { type: "string" }, provider: { type: "string" }, json: { type: "boolean" } } });
-    if (!["plan", "check"].includes(sub ?? "") || positionals.length || !values.map || sub === "plan" && values.provider || sub === "check" && !values.provider)
-        throw new Error("Usage: reflection plan --map FILE | reflection check --map FILE --provider FILE");
-    const config = context.config.baselines;
-    if (!config)
-        throw new Error("Configure baselines first");
-    const manifest = await readDesignJson(context.root, path.join(config.root, "penpair-baselines.json"));
-    if (manifest.schemaVersion !== 2 || !Array.isArray(manifest.frames) || !context.config.file || manifest.fileId !== context.config.file.id)
-        throw new Error("A schema-2 baseline manifest matching the configured file pin is required");
-    const plan = planImplementationCases(config, manifest.frames, await readDesignJson(context.root, values.map, 1024 * 1024));
-    let report = plan, code = plan.complete ? 0 : 3;
-    if (sub === "check") {
-        const file = await resolveProjectInput(context.root, values.provider);
-        const provider = await createJiti(file, { moduleCache: false, tryNative: false }).evalModule(await readFile(file, "utf8"), { filename: file, async: true, forceTranspile: true });
-        if (typeof provider.runCase !== "function")
-            throw new Error("Trusted project provider must export async runCase(test)");
-        const result = await runImplementationCases(context.root, plan, provider);
-        report = result;
-        code = !result.complete ? 3 : result.cases.some(c => c.withinThreshold === false) ? 2 : 0;
-    }
-    context.output?.result(report);
-    (context.output?.log ?? console.log)(JSON.stringify(report, null, 2));
-    return code;
-}
-export default defineAdapter({ name: "@penpair/reflection-check", commands: [{ name: "reflection", summary: "Plan explicit implementation cases and collect provider evidence", usage: ["penpair reflection plan --map FILE", "penpair reflection check --map FILE --provider FILE"], run: command }] });
+import { defineAdapter } from "@penpair/core";
+import { runReflectionCommand } from "./command.js";
+export { planImplementationCases } from "./case-plan.js";
+export { runImplementationCases } from "./run-cases.js";
+export default defineAdapter({
+    name: "@penpair/reflection-check",
+    commands: [
+        {
+            name: "reflection",
+            summary: "Plan explicit implementation cases and collect provider evidence",
+            usage: [
+                "penpair reflection plan --map FILE",
+                "penpair reflection check --map FILE --provider FILE",
+            ],
+            run: runReflectionCommand,
+        },
+    ],
+});

package/dist/png-evidence.d.ts

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,23 @@
+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),
+    };
+}

package/dist/run-cases.d.ts

@@ -0,0 +1,2 @@
+import type { CasePlan, ImplementationProvider, ImplementationReport } from "./types.js";
+export declare function runImplementationCases(root: string, plan: CasePlan, provider: ImplementationProvider): Promise<ImplementationReport>;

package/dist/run-cases.js

@@ -0,0 +1,64 @@
+import { resolveProjectInput } from "@penpair/core";
+import { validateProviderEvidence } from "./evidence-validation.js";
+import { hashPngBytes, readPngEvidence } from "./png-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) {
+        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 screenshotPath = await resolveProjectInput(root, evidence.screenshot);
+    const baselinePath = await resolveProjectInput(root, implementationCase.baseline.path);
+    if (screenshotPath === baselinePath) {
+        throw new Error("Screenshot must be independently captured, not the baseline path");
+    }
+    const viewport = implementationCase.intent.viewport;
+    const scale = implementationCase.baseline.scale;
+    if (implementationImage.width !== Math.round(viewport.width * scale) ||
+        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");
+    }
+    const baselineAfterCapture = await readPngEvidence(root, implementationCase.baseline.path);
+    if (hashPngBytes(baselineAfterCapture.bytes) !== implementationCase.baseline.sha256) {
+        throw new Error("Baseline changed during provider execution");
+    }
+    return {
+        id: implementationCase.id,
+        complete: true,
+        withinThreshold: evidence.diffPixelRatio <= implementationCase.threshold,
+        evidence,
+        screenshotHash: hashPngBytes(implementationImage.bytes),
+    };
+}
+export async function runImplementationCases(root, plan, provider) {
+    const reports = [];
+    for (const implementationCase of plan.cases) {
+        try {
+            reports.push(await collectCaseEvidence(root, implementationCase, provider));
+        }
+        catch (error) {
+            reports.push({
+                id: implementationCase.id,
+                complete: false,
+                reason: String(error.message),
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        kind: "implementation-case-evidence",
+        complete: plan.complete && reports.length > 0 && reports.every((report) => report.complete),
+        cases: reports,
+        pending: plan.pending,
+        visualApproval: false,
+        verdict: "owner-review-required",
+        accessibility: "not-assessed",
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+import type { BaselineCase } from "@penpair/core";
+export interface ImplementationMapping {
+    schemaVersion: 1;
+    cases: Array<{
+        id: string;
+        setup: string;
+    }>;
+}
+export interface ImplementationCase {
+    id: string;
+    route: string;
+    intent: BaselineCase;
+    setup: string;
+    baseline: {
+        path: string;
+        sha256: string;
+        scale: number;
+    };
+    threshold: number;
+}
+export interface CasePlan {
+    schemaVersion: 1;
+    kind: "implementation-case-plan";
+    cases: ImplementationCase[];
+    pending: Array<{
+        id: string;
+        reason: string;
+    }>;
+    complete: boolean;
+    visualApproval: false;
+}
+export interface BrowserCaptureMetadata {
+    schemaVersion: 1;
+    root: string;
+    rootBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    clip: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rounding: "outward-css-pixels";
+    deviceScaleFactor: number;
+    browser: {
+        name: string;
+        version: string;
+    };
+    fonts: Array<{
+        family: string;
+        weight: string;
+        style: string;
+        status: "loaded";
+    }>;
+    pointer: {
+        x: number;
+        y: number;
+        outsideRoot: boolean;
+        hoveredControls: number;
+    };
+    occlusion?: {
+        samples: number;
+        blocked: number;
+    };
+    scroll: {
+        x: number;
+        y: number;
+    };
+    layoutSamples: number;
+}
+export interface ProviderEvidence {
+    schemaVersion: 1;
+    id: string;
+    route: string;
+    setup: string;
+    observed: Pick<BaselineCase, "viewport" | "theme" | "state" | "fixture">;
+    fonts: string[];
+    fontsReady: boolean;
+    baselineHash: string;
+    capture?: BrowserCaptureMetadata;
+    screenshot: string;
+    diffPixelRatio: number;
+    provider: {
+        name: string;
+        version: string;
+    };
+}
+export interface ImplementationProvider {
+    runCase(implementationCase: ImplementationCase): Promise<ProviderEvidence>;
+}
+export interface ImplementationCaseReport {
+    id: string;
+    complete: boolean;
+    withinThreshold?: boolean;
+    evidence?: ProviderEvidence;
+    screenshotHash?: string;
+    reason?: string;
+}
+export interface ImplementationReport {
+    schemaVersion: 1;
+    kind: "implementation-case-evidence";
+    complete: boolean;
+    cases: ImplementationCaseReport[];
+    pending: CasePlan["pending"];
+    visualApproval: false;
+    verdict: "owner-review-required";
+    accessibility: "not-assessed";
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/reflection-check",
-  "version": "0.2.0",
+  "version": "0.3.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.2.0"
+    "@penpair/core": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",