@penpair/core 0.1.3 → 0.2.0

package/dist/baseline-coverage.js

@@ -0,0 +1,114 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveProjectOutput } from "./project-input.js";
+import { pngSize } from "./png.js";
+import { validateBaselines } from "./baselines-config.js";
+import { observationHash } from "./journal.js";
+export const designCaseKey = (route, value) => observationHash({ route, viewport: { width: value.viewport.width, height: value.viewport.height }, theme: value.theme, state: value.state, fixture: value.fixture });
+export function baselineCoverage(config, results = []) {
+    const rows = [];
+    for (const requirement of config.coverage?.required ?? []) {
+        const key = designCaseKey(requirement.route, requirement);
+        const unsupported = config.coverage?.unsupported?.find(value => designCaseKey(value.route, value) === key);
+        const frames = config.frames.filter(frame => frame.route && frame.case && designCaseKey(frame.route, frame.case) === key);
+        const frameIds = frames.map(frame => frame.id);
+        if (unsupported) {
+            rows.push({ requirement, status: "unsupported", frameIds, reason: unsupported.reason });
+            continue;
+        }
+        if (!frames.length) {
+            rows.push({ requirement, status: "missing-case", frameIds });
+            continue;
+        }
+        const captures = frames.flatMap(frame => { const found = results.find(result => result.id === frame.id); return found ? [{ frame, result: found }] : []; });
+        if (!captures.length || captures.every(({ result }) => !result.approved)) {
+            rows.push({ requirement, status: "missing-capture", frameIds });
+            continue;
+        }
+        const approved = captures.some(({ frame, result }) => {
+            const evidence = result.approved && "case" in result.approved ? result.approved : undefined;
+            return evidence?.approval?.kind !== "forced-reference" && !["missing", "unstable", "case-mismatch"].includes(result.status) && evidence?.case && observationHash(evidence.case) === observationHash(frame.case) && result.sha256 === evidence.sha256 && evidence.frameId === result.frameId && evidence.file === result.file && (!result.captured || evidence.fileId === result.captured.fileId && evidence.pageId === result.captured.pageId) && evidence.designSize?.width === frame.case.viewport.width && evidence.designSize?.height === frame.case.viewport.height && result.imageWidth === Math.round(frame.case.viewport.width * evidence.scale) && result.imageHeight === Math.round(frame.case.viewport.height * evidence.scale) && (!frame.case.activeThemeIds || evidence.activeThemeIds && observationHash([...frame.case.activeThemeIds].sort()) === observationHash([...evidence.activeThemeIds].sort()));
+        });
+        const changed = approved && captures.some(({ result }) => result.status === "changed" && result.captured && result.approved && result.captured.sha256 !== result.approved.sha256);
+        rows.push({ requirement, status: changed ? "changed-unapproved" : approved ? "approved-design-intent" : "unapproved-metadata", frameIds, ...(!approved ? { reason: captures.flatMap(({ result }) => result.problems ?? []).join("; ") || "Approved case/viewport/theme evidence is absent or mismatched" } : {}) });
+    }
+    const unknown = config.frames.flatMap(frame => {
+        const fields = [];
+        if (!frame.case)
+            fields.push("viewport", "theme", "state", "fixture", "font environment");
+        else {
+            if (frame.case.fonts === undefined)
+                fields.push("declared fonts absent");
+            else if (frame.case.fonts.length)
+                fields.push("font loading/version not observed");
+            if (frame.case.activeThemeIds === undefined)
+                fields.push("theme activation not asserted; label is design intent");
+        }
+        const result = results.find(result => result.id === frame.id);
+        if (frame.case && !result?.captured?.renderEnvironment)
+            fields.push("renderer environment not observed");
+        return fields.length ? [{ id: frame.id, fields }] : [];
+    });
+    return { schemaVersion: 1, kind: "baseline-coverage", configured: Boolean(config.coverage), designCasesComplete: rows.length > 0 && rows.every(row => row.status === "approved-design-intent"), rows, unknown, browserVerification: "not-run", accessibility: "not-assessed" };
+}
+async function boundedRead(file, maximum) {
+    const handle = await open(file, "r");
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maximum)
+            throw new Error("Artifact exceeds the coverage read budget or is not a regular file");
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Offline coverage validates the approved image bytes, never only a manifest's claims. */
+export async function readBaselineCoverage(root, config, expectedFileId) {
+    config = structuredClone(config);
+    validateBaselines(config, message => { throw new Error(message); });
+    const file = await resolveProjectOutput(root, path.join(config.root, "penpair-baselines.json"));
+    let manifest;
+    try {
+        manifest = JSON.parse((await boundedRead(file, 16 * 1024 * 1024)).toString("utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (!manifest)
+        return baselineCoverage(config);
+    if (manifest.schemaVersion !== 2 || !Array.isArray(manifest.frames) || manifest.frames.length > 1000)
+        throw new Error("Coverage needs a bounded schema-2 baseline manifest; regenerate a reviewed capture");
+    if (expectedFileId && manifest.fileId !== expectedFileId)
+        throw new Error("Coverage manifest belongs to a different pinned file");
+    const ids = new Set();
+    for (const value of manifest.frames) {
+        if (!value || typeof value.id !== "string" || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(value.id) || ids.has(value.id) || !["new", "same", "changed", "missing", "unstable", "case-mismatch"].includes(value.status) || typeof value.file !== "string" || !value.file)
+            throw new Error("Malformed baseline frame records");
+        ids.add(value.id);
+    }
+    const results = manifest.frames.map(value => ({ ...value }));
+    for (const result of results) {
+        if (!result.approved)
+            continue;
+        try {
+            if (typeof result.file !== "string" || path.isAbsolute(result.file) || result.file.split(/[\\/]/).includes(".."))
+                throw new Error("Approved image path leaves its baseline folder");
+            if ("fileId" in result.approved && result.approved.fileId !== manifest.fileId)
+                throw new Error("Approved image provenance belongs to a different file");
+            const target = await resolveProjectOutput(root, path.join(config.root, result.file));
+            const bytes = await boundedRead(target, 64 * 1024 * 1024), size = pngSize(bytes);
+            if (!size || size.width < 1 || size.height < 1 || createHash("sha256").update(bytes).digest("hex") !== result.approved.sha256 || result.sha256 !== result.approved.sha256)
+                throw new Error("Approved PNG bytes do not match their manifest");
+            result.imageWidth = size.width;
+            result.imageHeight = size.height;
+        }
+        catch (error) {
+            result.status = "case-mismatch";
+            result.problems = [error instanceof Error ? error.message : String(error)];
+        }
+    }
+    return baselineCoverage(config, results);
+}

package/dist/baselines-config.d.ts

@@ -1,3 +1,25 @@
+/** Declared design intent. It does not switch themes or establish browser behavior. */
+export interface BaselineCase {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    theme: string;
+    state: string;
+    fixture: string;
+    fonts?: string[];
+    /** Optional exact active native theme IDs expected during capture. */
+    activeThemeIds?: string[];
+}
+export interface CoverageRequirement extends Pick<BaselineCase, "viewport" | "theme" | "state" | "fixture"> {
+    route: string;
+}
+export interface CoverageConfig {
+    required: CoverageRequirement[];
+    unsupported?: (CoverageRequirement & {
+        reason: string;
+    })[];
+}
 /** One frame of a Penpot page that becomes an approved reference image. */
 export interface BaselineFrame {
     /** The exact name of a top-level frame on the page. */
@@ -6,6 +28,7 @@ export interface BaselineFrame {
     id: string;
     /** The route in the implementation this frame is the design of. Frames without one are exported but not given a check. */
     route?: string;
+    case?: BaselineCase;
 }
 /** What `penpair baselines` exports: the frames of one page, as images in a folder of the project. */
 export interface BaselinesConfig {
@@ -15,5 +38,7 @@ export interface BaselinesConfig {
     frames: BaselineFrame[];
     /** Allowed share of differing pixels in the generated checks (default 0.05). */
     threshold?: number;
+    coverage?: CoverageConfig;
 }
 export declare function validateBaselines(value: unknown, fail: (message: string) => never): BaselinesConfig;
+export declare function validateBaselineCase(value: unknown, fail: (message: string) => never, extraKeys?: string[]): BaselineCase;

package/dist/baselines-config.js

@@ -8,8 +8,8 @@ export function validateBaselines(value, fail) {
         fail("baselines.page must be the name of a page");
     if (typeof v.root !== "string" || v.root.length === 0 || path.isAbsolute(v.root) || v.root.split(/[\\/]/).includes(".."))
         fail("baselines.root must be a relative folder that stays inside the project");
-    if (!Array.isArray(v.frames) || v.frames.length === 0)
-        fail("baselines.frames must list at least one frame");
+    if (!Array.isArray(v.frames) || v.frames.length === 0 || v.frames.length > 1000)
+        fail("baselines.frames must list at least one frame, at most 1000");
     const seen = new Set();
     for (const entry of v.frames) {
         const f = entry;
@@ -22,10 +22,59 @@ export function validateBaselines(value, fail) {
         if (seen.has(f.id))
             fail(`baselines.frames id ${JSON.stringify(f.id)} is used twice`);
         seen.add(f.id);
+        if (f.case !== undefined) {
+            validateBaselineCase(f.case, fail);
+            if (typeof f.route !== "string" || !f.route)
+                fail("baseline case metadata requires an implementation route");
+        }
         if (f.route !== undefined && (typeof f.route !== "string" || f.route.length === 0))
             fail("baselines.frames route must be a non-empty string");
     }
-    if (v.threshold !== undefined && (typeof v.threshold !== "number" || v.threshold < 0 || v.threshold > 1))
+    if (v.coverage !== undefined) {
+        const coverage = v.coverage;
+        if (!coverage || typeof coverage !== "object" || Array.isArray(coverage) || !Array.isArray(coverage.required) || !coverage.required.length || coverage.required.length > 1000 || coverage.unsupported !== undefined && (!Array.isArray(coverage.unsupported) || coverage.unsupported.length > 1000))
+            fail("baselines.coverage needs 1–1000 required cases and bounded unsupported cases");
+        const required = new Set();
+        const key = (value) => JSON.stringify([value.route, value.viewport.width, value.viewport.height, value.theme, value.state, value.fixture]);
+        for (const value of coverage.required) {
+            validateBaselineCase(value, fail, ["route"]);
+            if (typeof value.route !== "string" || !value.route)
+                fail("coverage cases need a route");
+            if (required.has(key(value)))
+                fail("Duplicate required coverage case");
+            required.add(key(value));
+        }
+        const unsupported = new Set();
+        for (const value of coverage.unsupported ?? []) {
+            validateBaselineCase(value, fail, ["route", "reason"]);
+            if (typeof value.route !== "string" || !value.route || typeof value.reason !== "string" || !value.reason.trim())
+                fail("unsupported cases need route and reason");
+            if (!required.has(key(value)) || unsupported.has(key(value)))
+                fail("unsupported cases must uniquely reference required cases");
+            unsupported.add(key(value));
+        }
+    }
+    if (v.threshold !== undefined && (typeof v.threshold !== "number" || !Number.isFinite(v.threshold) || v.threshold < 0 || v.threshold > 1))
         fail("baselines.threshold must be a number from 0 to 1");
     return v;
 }
+export function validateBaselineCase(value, fail, extraKeys = []) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return fail("baseline case must be an object");
+    const entry = value;
+    const allowed = new Set(["viewport", "theme", "state", "fixture", ...(extraKeys.length ? [] : ["fonts", "activeThemeIds"]), ...extraKeys]);
+    if (Object.keys(entry).some(key => !allowed.has(key)))
+        fail("Unknown baseline case field; capture constraints belong on frame cases");
+    if (entry.viewport && Object.keys(entry.viewport).some(key => !["width", "height"].includes(key)))
+        fail("Viewport accepts width and height only");
+    for (const key of ["theme", "state", "fixture"])
+        if (typeof entry[key] !== "string" || !entry[key].trim() || entry[key].length > 200 || /[\x00-\x1f]/.test(entry[key]))
+            fail(`baseline case ${key} needs a short explicit label`);
+    for (const key of ["width", "height"])
+        if (!entry.viewport || !Number.isInteger(entry.viewport[key]) || entry.viewport[key] < 1 || entry.viewport[key] > 16384)
+            fail("baseline case viewport dimensions must be integers from 1 to 16384");
+    for (const key of ["fonts", "activeThemeIds"])
+        if (entry[key] !== undefined && (!Array.isArray(entry[key]) || entry[key].length > 100 || entry[key].some(value => typeof value !== "string" || !value.trim()) || new Set(entry[key]).size !== entry[key].length))
+            fail(`baseline case ${key} must contain at most 100 unique nonempty strings`);
+    return entry;
+}

package/dist/baselines.d.ts

@@ -1,6 +1,9 @@
+export { pngSize } from "./png.js";
 import type { PenpotToolClient } from "./client.js";
-import type { BaselinesConfig } from "./baselines-config.js";
-import { type ExportOptions } from "./export.js";
+import { type BaselineCoverage } from "./baseline-coverage.js";
+import { type BaselineCase, type BaselinesConfig } from "./baselines-config.js";
+import type { LayoutResult } from "./layout.js";
+import { type CaptureIdentity, type ExportOptions } from "./export.js";
 export * from "./baselines-config.js";
 export type BaselineStatus = 
 /** No image in the folder yet. */
@@ -12,8 +15,31 @@ export type BaselineStatus =
 /** The export never settled (two identical renders in a row), so it is not trusted. */
  | "unstable"
 /** The page has no top-level frame with that name. */
- | "missing";
+ | "missing" | "case-mismatch";
+export interface ArtifactProvenance extends CaptureIdentity {
+    approval?: {
+        kind: "owner-words";
+        id: string;
+        recordHash: string;
+    } | {
+        kind: "forced-reference";
+        reason: string;
+    };
+    case?: BaselineCase;
+    layout?: LayoutResult;
+    sha256: string;
+    capturedAt: string;
+    toolVersion: string;
+    file: string;
+}
 export interface BaselineResult {
+    case?: BaselineCase;
+    problems?: string[];
+    captured?: ArtifactProvenance;
+    approved?: ArtifactProvenance | {
+        legacy: true;
+        sha256: string;
+    };
     id: string;
     frame: string;
     frameId?: string;
@@ -30,6 +56,10 @@ export interface BaselineResult {
     imageHeight?: number;
 }
 export interface BaselinesReport {
+    coverage: BaselineCoverage;
+    complete: boolean;
+    fileId: string;
+    pageId: string;
     page: string;
     penpotFile: string;
     revn: number;
@@ -38,16 +68,14 @@ export interface BaselinesReport {
     wrote: string[];
 }
 export interface BaselinesOptions extends ExportOptions {
+    signal?: AbortSignal;
     /** Write images that are new. Without it nothing is written, whatever is found. */
     apply?: boolean;
     /** Also replace images whose design has changed. This is the act of approving the new design as the reference; it is the owner's call. */
     update?: boolean;
+    /** Explicit waiver for a changed baseline; retained as a forced reference, never an owner approval. */
+    forceReason?: string;
 }
-/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
-export declare function pngSize(buffer: Buffer): {
-    width: number;
-    height: number;
-} | undefined;
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of
@@ -69,4 +97,5 @@ export declare function reflectionCases(config: BaselinesConfig, results: Baseli
         }[];
     }>;
     visualSmoke: Record<string, unknown>[];
+    pendingCases: Record<string, unknown>[];
 };

package/dist/baselines.js

@@ -1,24 +1,28 @@
-import { createHash } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { matchingApproval } from "./approvals.js";
+import { pngSize } from "./png.js";
+export { pngSize } from "./png.js";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
 import path from "node:path";
+import { baselineCoverage } from "./baseline-coverage.js";
+import { resolveProjectOutput } from "./project-input.js";
+import { validateBaselines } from "./baselines-config.js";
+import { version } from "./version.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { observationHash } from "./journal.js";
 import { exportShapePng } from "./export.js";
 import { runOnPage } from "./operation.js";
 import { frames } from "./snippets/read.js";
 export * from "./baselines-config.js";
 const sha = (buffer) => createHash("sha256").update(buffer).digest("hex");
-/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
-export function pngSize(buffer) {
-    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-    if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature) || buffer.subarray(12, 16).toString("ascii") !== "IHDR")
-        return undefined;
-    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
-}
 async function readIfExists(file) {
     try {
         return await readFile(file);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
     }
 }
 /**
@@ -27,16 +31,34 @@ async function readIfExists(file) {
  * the design never silently becomes the new reference.
  */
 export async function exportBaselines(client, projectRoot, config, options = {}) {
+    if (options.forceReason !== undefined && (!options.update || !options.apply || !options.forceReason.trim() || options.forceReason.length > 2000))
+        throw new Error("A nonempty force reason requires apply and update");
+    config = structuredClone(config);
+    validateBaselines(config, message => { throw new Error(message); });
     const listing = await runOnPage(client, frames({ page: config.page }), config.page, options);
-    const found = listing.frames ?? [];
+    if (listing.ok !== true || typeof listing.fileId !== "string" || !listing.fileId || typeof listing.pageId !== "string" || !listing.pageId || !Number.isInteger(listing.revn) || !Array.isArray(listing.frames))
+        throw new Error("Baseline listing lacks file/page/revision evidence");
+    const found = listing.frames;
     const results = [];
     const wrote = [];
-    const folder = path.join(projectRoot, config.root);
+    const folder = await resolveProjectOutput(projectRoot, config.root);
+    const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
+    const previousBytes = await readIfExists(manifestPath);
+    const previous = previousBytes ? JSON.parse(previousBytes.toString("utf8")) : undefined;
+    if (previous && (previous.schemaVersion !== undefined && previous.schemaVersion !== 2 || !Array.isArray(previous.frames)))
+        throw new Error("Existing baseline manifest is invalid; preserve and inspect it");
+    const runId = randomUUID();
+    const generation = `captures/${runId}`;
+    const captures = new Map();
     for (const wanted of config.frames) {
-        const file = `${wanted.id}.png`;
+        options.signal?.throwIfAborted();
+        const old = previous?.frames?.find((entry) => entry.id === wanted.id);
+        const file = old?.file ?? `${wanted.id}.png`;
+        if (path.isAbsolute(file) || file.split(/[\\/]/).includes(".."))
+            throw new Error("Existing baseline path leaves its folder");
         const matches = found.filter((f) => f.name === wanted.frame);
-        if (matches.length === 0) {
-            results.push({ id: wanted.id, frame: wanted.frame, file, status: "missing", written: false });
+        if (!matches.length) {
+            results.push({ ...(wanted.case ? { case: wanted.case } : {}), id: wanted.id, frame: wanted.frame, file, status: "missing", written: false });
             continue;
         }
         if (matches.length > 1)
@@ -44,48 +66,99 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         const frame = matches[0];
         options.onStep?.(`exporting ${wanted.frame}`);
         const exported = await exportShapePng(client, frame.id, { ...options, page: config.page, stable: true });
-        const base = { id: wanted.id, frame: wanted.frame, frameId: frame.id, width: frame.width, height: frame.height, file };
+        const base = { ...(wanted.case ? { case: wanted.case } : {}), id: wanted.id, frame: wanted.frame, frameId: frame.id, width: frame.width, height: frame.height, file };
+        if (exported.capture.fileId !== listing.fileId || exported.capture.pageId !== listing.pageId || exported.capture.revision !== listing.revn)
+            throw new Error("Baseline source changed during capture; nothing was published");
         if (!exported.stable) {
             results.push({ ...base, status: "unstable", written: false });
             continue;
         }
-        const target = path.join(folder, file);
-        const existing = await readIfExists(target);
-        const status = existing === undefined ? "new" : sha(existing) === sha(exported.png) ? "same" : "changed";
-        let written = false;
-        if (options.apply && (status === "new" || (status === "changed" && options.update))) {
-            await mkdir(folder, { recursive: true });
-            await writeFile(target, exported.png);
-            written = true;
-            wrote.push(path.join(config.root, file));
+        if (!pngSize(exported.png))
+            throw new Error("Baseline export is not a PNG with dimensions");
+        const existing = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
+        if (old && (!existing || old.sha256 !== sha(existing) || old.approved && old.approved.sha256 !== old.sha256))
+            throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
+        const captured = { ...(wanted.case ? { case: wanted.case } : {}), layout: exported.layout, ...exported.capture, sha256: sha(exported.png), capturedAt: new Date().toISOString(), toolVersion: version, file: `${generation}/${wanted.id}.png` };
+        const caseProblems = [];
+        if (wanted.case) {
+            const viewport = wanted.case.viewport, size = pngSize(exported.png);
+            if (!exported.capture.designSize || exported.capture.designSize.width !== viewport.width || exported.capture.designSize.height !== viewport.height)
+                caseProblems.push("Observed frame dimensions do not match the declared viewport");
+            if (size.width !== Math.round(viewport.width * exported.capture.scale) || size.height !== Math.round(viewport.height * exported.capture.scale))
+                caseProblems.push("PNG dimensions do not match declared viewport and capture scale");
+            if (wanted.case.activeThemeIds && (!exported.capture.activeThemeIds || observationHash([...wanted.case.activeThemeIds].sort()) !== observationHash([...exported.capture.activeThemeIds].sort())))
+                caseProblems.push("Active native theme IDs do not match the capture assertion");
+        }
+        if (caseProblems.length) {
+            results.push({ ...base, status: "case-mismatch", written: false, captured, approved: old?.approved, sha256: old?.sha256, problems: caseProblems });
+            continue;
         }
-        // A new image that was not written (a look, without --apply) is described by the export; a changed one that was not updated by what is on disk.
-        const onDisk = written || status === "same" || status === "new" ? exported.png : existing;
-        const size = pngSize(onDisk);
-        results.push({ ...base, status, written, sha256: sha(onDisk), bytes: onDisk.length, imageWidth: size?.width, imageHeight: size?.height });
+        const oldCase = old?.approved && "case" in old.approved ? old.approved.case : undefined;
+        const status = !existing ? "new" : sha(existing) === captured.sha256 && observationHash(oldCase ?? null) === observationHash(wanted.case ?? null) && (!old?.approved || "legacy" in old.approved || old.approved.fileId === captured.fileId && old.approved.pageId === captured.pageId && old.approved.frameId === captured.frameId) ? "same" : "changed";
+        const promoteWaiver = status === "same" && old?.approved && "approval" in old.approved && old.approved.approval?.kind === "forced-reference" && options.update === true;
+        if ((status === "changed" || promoteWaiver) && options.update && options.apply) {
+            const record = await matchingApproval(projectRoot, exported.capture, captured.sha256, wanted.case);
+            if (record)
+                captured.approval = { kind: "owner-words", id: record.id, recordHash: record.hash };
+            else if (options.forceReason)
+                captured.approval = { kind: "forced-reference", reason: options.forceReason };
+            else
+                throw new Error("Changed baseline requires matching exact-artifact owner words (penpair approve), or an explicit --force-reason waiver; previous artifacts preserved");
+        }
+        const approve = status === "new" || status === "changed" && options.update === true || Boolean(promoteWaiver);
+        const approved = approve ? captured : old?.approved ?? { legacy: true, sha256: sha(existing) };
+        const image = approve ? exported.png : existing;
+        const size = pngSize(image);
+        results.push({ ...base, file: approve && options.apply ? captured.file : file, status, written: false, captured,
+            approved: options.apply || !approve ? approved : undefined, sha256: sha(image), bytes: image.length, imageWidth: size?.width, imageHeight: size?.height });
+        captures.set(wanted.id, exported.png);
     }
-    if (options.apply) {
-        const onDisk = results.filter((r) => r.status !== "missing" && r.status !== "unstable" && (r.written || r.status === "same" || r.status === "changed"));
-        if (onDisk.length > 0) {
-            await mkdir(folder, { recursive: true });
-            const manifest = path.join(folder, "penpair-baselines.json");
-            await writeFile(manifest, `${JSON.stringify(manifestOf(config, listing, onDisk), null, 2)}\n`);
-            wrote.push(path.join(config.root, "penpair-baselines.json"));
-            const cases = path.join(folder, "reflection-cases.json");
-            await writeFile(cases, `${JSON.stringify(reflectionCases(config, onDisk), null, 2)}\n`);
-            wrote.push(path.join(config.root, "reflection-cases.json"));
+    const after = await runOnPage(client, frames({ page: config.page }), config.page, options);
+    const source = (value) => ({ fileId: value.fileId, pageId: value.pageId, revision: value.revn, frames: value.frames });
+    if (observationHash(source(listing)) !== observationHash(source(after)))
+        throw new Error("Baseline source changed before publication; previous artifacts were preserved");
+    const complete = results.length === config.frames.length && results.every((result) => result.status !== "missing" && result.status !== "unstable" && result.status !== "case-mismatch");
+    if (options.apply && complete) {
+        const evidence = JSON.stringify({ config, results, forceReason: options.forceReason });
+        if (options.redact && options.redact(evidence) !== evidence)
+            throw new Error("Baseline evidence requires credential redaction; previous artifacts preserved");
+        options.signal?.throwIfAborted();
+        options.onStep?.("publishing complete capture");
+        options.signal?.throwIfAborted();
+        const captureFolder = await resolveProjectOutput(projectRoot, path.join(config.root, "captures"));
+        await mkdir(captureFolder, { recursive: true });
+        const staged = path.join(folder, `.stage-${runId}`);
+        await mkdir(staged);
+        try {
+            for (const [id, bytes] of captures) {
+                options.signal?.throwIfAborted();
+                await atomicWriteFile(path.join(staged, `${id}.png`), bytes);
+                options.onStep?.(`staging ${id}`);
+            }
+            const cases = reflectionCases(config, results);
+            await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({ ...cases, captureId: runId }, null, 2)}\n`, { flag: "wx" });
+            options.signal?.throwIfAborted();
+            await rename(staged, path.join(captureFolder, runId));
+            // Immutable generation first. The canonical manifest is the commit point and is published last.
+            await atomicWriteFile(path.join(folder, "reflection-cases.json"), `${JSON.stringify({ ...cases, captureId: runId }, null, 2)}\n`, { replace: true });
+            options.signal?.throwIfAborted();
+            for (const result of results)
+                result.written = result.file === result.captured?.file && (result.status === "new" || options.update === true);
+            const manifest = { schemaVersion: 2, complete: true, captureId: runId, penpotFile: listing.file, fileId: listing.fileId, page: config.page, pageId: listing.pageId,
+                coverage: baselineCoverage(config, results), capturedRevision: listing.revn, casesFile: `${generation}/reflection-cases.json`, note: "Capture provenance and approved provenance are separate. Changed references require exact-artifact owner words or a recorded forced-reference waiver.", frames: results };
+            await atomicWriteFile(path.join(folder, "penpair-baselines.json"), `${JSON.stringify(manifest, null, 2)}\n`, { replace: true });
+            for (const result of results) {
+                result.written = result.file === result.captured?.file && (result.status === "new" || options.update === true);
+                if (result.written)
+                    wrote.push(path.join(config.root, result.file));
+            }
+            wrote.push(path.join(config.root, "reflection-cases.json"), path.join(config.root, "penpair-baselines.json"));
+        }
+        finally {
+            await rm(staged, { recursive: true, force: true });
         }
     }
-    return { page: config.page, penpotFile: String(listing.file ?? ""), revn: Number(listing.revn ?? 0), results, wrote };
-}
-function manifestOf(config, listing, results) {
-    return {
-        note: "Written by `penpair baselines`. The images are the approved design for each frame; change one only on purpose (`penpair baselines --apply --update`).",
-        penpotFile: listing.file,
-        page: config.page,
-        revn: listing.revn,
-        frames: results.map((r) => ({ id: r.id, frame: r.frame, frameId: r.frameId, width: r.imageWidth, height: r.imageHeight, file: r.file, sha256: r.sha256, bytes: r.bytes })),
-    };
+    return { coverage: baselineCoverage(config, results), complete, fileId: listing.fileId, pageId: listing.pageId, page: config.page, penpotFile: String(listing.file), revn: Number(listing.revn), results, wrote };
 }
 /**
  * Visual cases for Reflection, one per frame that names a route: the image's exact size is the viewport (so the capture and the
@@ -93,12 +166,18 @@ function manifestOf(config, listing, results) {
  * Review-only (`strict: false`): a difference is shown to a person, not failed.
  */
 export function reflectionCases(config, results) {
-    const routes = {};
+    const routes = Object.create(null);
     const visualSmoke = [];
+    const pendingCases = [];
     for (const wanted of config.frames) {
         const result = results.find((r) => r.id === wanted.id);
         if (!wanted.route || !result || result.imageWidth === undefined || result.imageHeight === undefined)
             continue;
+        if (wanted.case) {
+            const approvedCase = result.approved && "case" in result.approved ? result.approved.case : undefined;
+            pendingCases.push({ id: wanted.id, route: wanted.route, case: approvedCase ?? wanted.case, baseline: result.file, ref: `penpair:${wanted.id}`, approvedProvenance: result.approved ?? null, captured: result.captured ?? null, approvedMetadata: Boolean(approvedCase && observationHash(approvedCase) === observationHash(wanted.case)), reason: "Explicit theme/state/fixture/font setup requires an implementation provider mapping", browserVerification: "not-run" });
+            continue;
+        }
         const viewport = { name: `design-${result.imageWidth}x${result.imageHeight}`, width: result.imageWidth, height: result.imageHeight };
         const entry = (routes[wanted.route] ??= { viewports: [] });
         if (!entry.viewports.some((v) => v.name === viewport.name))
@@ -108,7 +187,7 @@ export function reflectionCases(config, results) {
             route: wanted.route,
             viewport: viewport.name,
             baselineRoot: config.root,
-            baseline: `${wanted.id}.png`,
+            baseline: result.file,
             threshold: { maxDiffPixelRatio: config.threshold ?? 0.05 },
             strict: false,
             ref: `penpair:${wanted.id}`,
@@ -118,5 +197,6 @@ export function reflectionCases(config, results) {
         note: "Generated by `penpair baselines`. Add each route's viewports to that route in your Reflection config and spread `visualSmoke` into the browser contract; baselineRoot is relative to the Reflection config's folder.",
         routes,
         visualSmoke,
+        pendingCases,
     };
 }

package/dist/cli-arguments.d.ts

@@ -0,0 +1,7 @@
+import { parseArgs, type ParseArgsConfig } from "node:util";
+export declare class CommandArgumentError extends Error {
+    readonly code = "invalid-arguments";
+    readonly remedy = "Use the command's supported flags and required values; see penpair --help.";
+}
+/** Suggestions are explanatory only; never reinterpret a supplied option. */
+export declare function parseCommandArgs<T extends ParseArgsConfig>(config: T): ReturnType<typeof parseArgs<T>>;

package/dist/cli-arguments.js

@@ -0,0 +1,35 @@
+import { parseArgs } from "node:util";
+export class CommandArgumentError extends Error {
+    code = "invalid-arguments";
+    remedy = "Use the command's supported flags and required values; see penpair --help.";
+}
+function distance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min(next[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = next;
+    }
+    return previous[b.length];
+}
+/** Suggestions are explanatory only; never reinterpret a supplied option. */
+export function parseCommandArgs(config) {
+    try {
+        return parseArgs(config);
+    }
+    catch (error) {
+        const value = error;
+        if (!value.code?.startsWith("ERR_PARSE_ARGS"))
+            throw error;
+        const unknown = /Unknown option ['"]--([^'"]+)['"]/.exec(value.message ?? "")?.[1];
+        let hint = "";
+        if (unknown && unknown.length <= 100) {
+            const candidates = Object.keys(config.options ?? {}).map((name) => ({ name, distance: distance(unknown.toLowerCase(), name.toLowerCase()) })).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+            const best = candidates[0];
+            if (best && best.distance <= Math.max(2, Math.ceil(unknown.length / 2)))
+                hint = ` Did you mean --${best.name}?`;
+        }
+        throw new CommandArgumentError((value.message ?? "Invalid command arguments") + hint);
+    }
+}

package/dist/cli-main.d.ts

@@ -1,10 +1,22 @@
+import { type CommandResult } from "./command-result.js";
+import { type ProjectConfig } from "./instance/config.js";
 import { type Adapter } from "./adapters.js";
 import { type LocalProfile } from "./local-profile.js";
 export interface CliOptions {
+    /** Explicit request-scoped project root; never changes the process working directory. */
+    root?: string;
+    /** Refuse unrelated global client endpoint fallback (used by the stdio server). */
+    projectEndpointOnly?: boolean;
+    /** Immutable server target: every loaded project configuration must still match. */
+    pinnedConfig?: ProjectConfig;
+    strictFileGuard?: boolean;
     /** Adapters already loaded (the command loads the project's own from penpair.config.json). */
     adapters?: Adapter[];
+    configuredAdapters?: string[];
     /** A way to run Penpot on this computer, from a package that provides one (`@penpair/docker`). Without it those commands explain where they come from. */
     local?: LocalProfile;
 }
-/** Runs the command line and returns the exit code. The `penpair` command calls it with nothing extra; a package that adds a way to run Penpot calls it with its profile. */
+export declare function runCommand(argv: string[], options?: CliOptions & {
+    signal?: AbortSignal;
+}): Promise<CommandResult>;
 export declare function runCli(argv: string[], options?: CliOptions): Promise<number>;