@penpair/core 0.1.2 → 0.2.0

package/dist/adapters.d.ts

@@ -1,3 +1,5 @@
+import type { BuildKit } from "./kit.js";
+import type { CommandOutput } from "./command-result.js";
 import type { PenpotToolClient } from "./client.js";
 import { type ProjectConfig } from "./instance/config.js";
 /**
@@ -6,6 +8,9 @@ import { type ProjectConfig } from "./instance/config.js";
  * project and knows nothing about any of them. An adapter keeps its own settings in its own block of the same file.
  */
 export interface AdapterContext {
+    output?: CommandOutput;
+    /** Removes this connection's credentials before recovery evidence is persisted or reported. */
+    redact?(text: string): string;
     /** The project's folder. */
     root: string;
     /** The project's validated configuration. */
@@ -29,14 +34,24 @@ export interface AdapterCommand {
     /** Runs with the arguments after the command's name; returns the exit code. The adapter parses its own flags. */
     run(context: AdapterContext, args: string[]): Promise<number>;
 }
+export interface AdapterStatusLine {
+    id: string;
+    label: string;
+    state: "ok" | "warning" | "failed" | "unknown";
+    detail: string;
+}
 export interface Adapter {
     name: string;
     commands: AdapterCommand[];
+    /** Executed only by an explicit status --adapters request; trusted project code. */
+    status?(context: AdapterContext): Promise<AdapterStatusLine[]>;
+    /** Explicit opt-in plugin-source includes. Built-in commands do not load these unless requested. */
+    kits?: BuildKit[];
 }
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export declare const defineAdapter: <T extends Adapter>(adapter: T) => T;
 /** The commands of the core itself; an adapter cannot take one of these names. */
-export declare const reservedCommands: readonly ["probe", "pages", "tree", "audit", "tokens", "export", "archive", "snippets", "run", "skills", "init", "setup", "connect", "up", "down", "status", "doctor", "backup", "restore", "baselines"];
+export declare const reservedCommands: readonly ["formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
 export interface LoadedAdapters {
     adapters: Adapter[];
     problems: string[];

package/dist/adapters.js

@@ -1,21 +1,23 @@
-import { readFile } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { configFileName } from "./instance/config.js";
+import { readProjectConfig } from "./instance/config.js";
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export const defineAdapter = (adapter) => adapter;
 /** The commands of the core itself; an adapter cannot take one of these names. */
 export const reservedCommands = [
-    "probe", "pages", "tree", "audit", "tokens", "export", "archive", "snippets", "run", "skills", "init", "setup", "connect",
-    "up", "down", "status", "doctor", "backup", "restore", "baselines",
+    "formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect",
+    "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help",
 ];
 /** Resolves an adapter the way the project would: a relative path from the project's folder, or a package installed in the project. */
 export const importFromProject = async (specifier, root) => {
     let file;
     if (specifier.startsWith(".") || path.isAbsolute(specifier))
-        file = path.resolve(root, specifier);
+        file = await resolveProjectInput(root, specifier);
     else {
+        if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+(?:\/[a-z0-9._-]+)*$/i.test(specifier) || specifier.split("/").includes(".."))
+            throw new Error("Adapter must name an installed package or a relative project module");
         try {
             file = createRequire(path.join(root, "package.json")).resolve(specifier);
         }
@@ -61,11 +63,5 @@ export async function loadAdapters(root, specifiers, importer = importFromProjec
 }
 /** The whole penpair.config.json as written (an adapter's own settings live in it). Empty when there is no file. */
 export async function readRawConfig(root) {
-    try {
-        const parsed = JSON.parse(await readFile(path.join(root, configFileName), "utf8"));
-        return typeof parsed === "object" && parsed !== null ? parsed : {};
-    }
-    catch {
-        return {};
-    }
+    return await readProjectConfig(root) ?? {};
 }

package/dist/approvals.d.ts

@@ -0,0 +1,32 @@
+import type { CaptureIdentity, ExportResult } from "./export.js";
+import { type BaselineCase } from "./baselines-config.js";
+export interface ApprovalRecord {
+    schemaVersion: 1;
+    id: string;
+    kind: "owner-words";
+    recordedAt: string;
+    by: string;
+    note: string;
+    capture: CaptureIdentity;
+    case?: BaselineCase;
+    sha256: string;
+    image: string;
+    fingerprint: string;
+    hash: string;
+}
+export interface ApprovalFile {
+    schemaVersion: 1;
+    kind: "design-approvals";
+    records: ApprovalRecord[];
+}
+export declare const approvalFile = "design/approvals.json";
+export declare const artifactSha: (bytes: Buffer) => string;
+export declare function approvalFingerprint(capture: CaptureIdentity, sha256: string, intent?: BaselineCase): string;
+export declare function validateApprovals(raw: unknown): ApprovalFile;
+export declare function readApprovals(root: string): Promise<ApprovalFile>;
+/** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
+export declare function recordApproval(root: string, exported: ExportResult, words: {
+    note: string;
+    by: string;
+}, intent?: BaselineCase, redact?: (text: string) => string): Promise<ApprovalRecord>;
+export declare function matchingApproval(root: string, capture: CaptureIdentity, sha256: string, intent?: BaselineCase): Promise<ApprovalRecord | undefined>;

package/dist/approvals.js

@@ -0,0 +1,99 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile } from "./atomic-output.js";
+import { observationHash } from "./journal.js";
+import { resolveProjectInput, resolveProjectOutput } from "./project-input.js";
+import { validateBaselineCase } from "./baselines-config.js";
+import { pngSize } from "./png.js";
+export const approvalFile = "design/approvals.json";
+export const artifactSha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export function approvalFingerprint(capture, sha256, intent) {
+    if (!capture || typeof capture.fileId !== "string" || !capture.fileId || typeof capture.pageId !== "string" || !capture.pageId || typeof capture.frameId !== "string" || !capture.frameId || !Number.isInteger(capture.revision) || !Number.isFinite(capture.scale) || capture.scale <= 0 || !/^[a-f0-9]{64}$/.test(sha256))
+        throw new Error("Approval requires exact capture identity, revision, scale and SHA-256");
+    if (intent)
+        validateBaselineCase(intent, message => { throw new Error(message); });
+    return observationHash({ capture, sha256, case: intent ?? null });
+}
+export function validateApprovals(raw) {
+    const v = raw;
+    if (!v || v.schemaVersion !== 1 || v.kind !== "design-approvals" || !Array.isArray(v.records) || v.records.length > 10000)
+        throw new Error("Unsupported approval document");
+    const ids = new Set();
+    for (const r of v.records) {
+        if (!r || r.schemaVersion !== 1 || r.kind !== "owner-words" || typeof r.id !== "string" || !r.id || ids.has(r.id) || typeof r.note !== "string" || !r.note.trim() || r.note.length > 4000 || typeof r.by !== "string" || !r.by.trim() || r.by.length > 200 || !Number.isFinite(Date.parse(r.recordedAt)) || typeof r.image !== "string" || !r.image)
+            throw new Error("Malformed owner approval record");
+        ids.add(r.id);
+        const { hash, ...body } = r;
+        if (hash !== observationHash(body) || r.fingerprint !== approvalFingerprint(r.capture, r.sha256, r.case))
+            throw new Error("Approval evidence hash mismatch");
+    }
+    return v;
+}
+export async function readApprovals(root) {
+    try {
+        const file = await resolveProjectInput(root, approvalFile);
+        if ((await stat(file)).size > 16 * 1024 * 1024)
+            throw new Error("Approval file exceeds 16 MiB");
+        return validateApprovals(JSON.parse(await readFile(file, "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { schemaVersion: 1, kind: "design-approvals", records: [] };
+        throw error;
+    }
+}
+/** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
+export async function recordApproval(root, exported, words, intent, redact) {
+    exported = { ...exported, capture: structuredClone(exported.capture), png: Buffer.from(exported.png) };
+    intent = intent ? structuredClone(intent) : undefined;
+    words = { ...words };
+    if (!exported.stable || !pngSize(exported.png))
+        throw new Error("Approval requires a stable independently exported PNG");
+    if (typeof words.note !== "string" || !words.note.trim() || words.note.length > 4000 || typeof words.by !== "string" || !words.by.trim() || words.by.length > 200)
+        throw new Error("Supply the owner's exact nonempty words and identity; an agent cannot invent approval");
+    const sha256 = artifactSha(exported.png), fingerprint = approvalFingerprint(exported.capture, sha256, intent);
+    if (intent && (!exported.capture.designSize || exported.capture.designSize.width !== intent.viewport.width || exported.capture.designSize.height !== intent.viewport.height || intent.activeThemeIds && observationHash([...(exported.capture.activeThemeIds ?? [])].sort()) !== observationHash([...intent.activeThemeIds].sort())))
+        throw new Error("Approval case assertions do not match observed capture");
+    const body = { schemaVersion: 1, id: randomUUID(), kind: "owner-words", recordedAt: new Date().toISOString(), by: words.by, note: words.note, capture: exported.capture, ...(intent ? { case: intent } : {}), sha256, image: `design/approvals/${sha256}.png`, fingerprint };
+    const record = { ...body, hash: observationHash(body) };
+    const serialized = JSON.stringify(record);
+    if (redact && redact(serialized) !== serialized)
+        throw new Error("Approval requires credential redaction; no record was written");
+    const file = await resolveProjectOutput(root, approvalFile);
+    await mkdir(path.dirname(file), { recursive: true });
+    const lock = await open(file + ".lock", "wx", 0o600);
+    try {
+        const previous = await readApprovals(root);
+        if (previous.records.length >= 10000)
+            throw new Error("Approval document record limit reached");
+        const image = await resolveProjectOutput(root, record.image);
+        await mkdir(path.dirname(image), { recursive: true });
+        try {
+            await atomicWriteFile(image, exported.png);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" || artifactSha(await readFile(image)) !== sha256)
+                throw error;
+        }
+        const next = JSON.stringify({ ...previous, records: [...previous.records, record] }, null, 2) + "\n";
+        if (Buffer.byteLength(next) > 16 * 1024 * 1024)
+            throw new Error("Approval document byte limit reached");
+        await atomicWriteFile(file, next, { replace: true });
+        return record;
+    }
+    finally {
+        await lock.close();
+        await unlink(file + ".lock");
+    }
+}
+export async function matchingApproval(root, capture, sha256, intent) {
+    const fingerprint = approvalFingerprint(capture, sha256, intent);
+    const record = [...(await readApprovals(root)).records].reverse().find(r => r.fingerprint === fingerprint);
+    if (!record)
+        return undefined;
+    const image = await resolveProjectInput(root, record.image);
+    if ((await stat(image)).size > 64 * 1024 * 1024 || artifactSha(await readFile(image)) !== sha256)
+        throw new Error("Approved image bytes changed");
+    return record;
+}

package/dist/atomic-output.d.ts

@@ -0,0 +1,5 @@
+/** Stage complete bytes beside the destination; publish once. Exclusive mode never replaces an existing file. */
+export declare function atomicWriteFile(destination: string, data: string | Uint8Array, options?: {
+    replace?: boolean;
+    mode?: number;
+}): Promise<void>;

package/dist/atomic-output.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+import { link, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+/** Stage complete bytes beside the destination; publish once. Exclusive mode never replaces an existing file. */
+export async function atomicWriteFile(destination, data, options = {}) {
+    const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}-${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx", options.mode ?? 0o600);
+    try {
+        await handle.writeFile(data);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+    try {
+        if (options.replace)
+            await rename(temporary, destination);
+        else
+            await link(temporary, destination);
+    }
+    finally {
+        await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+            throw error; });
+    }
+}

package/dist/audit-rules.d.ts

@@ -0,0 +1,60 @@
+import type { InspectionDocument } from "./inspection.js";
+export interface AuditRules {
+    contrast?: boolean;
+    library?: boolean;
+    touchTargets?: boolean;
+    names?: boolean;
+    blankText?: boolean;
+    interactiveIds?: string[];
+    allowBlank?: string[];
+    nameSegments?: number;
+    suppressions?: Array<{
+        rule: string;
+        nodeId: string;
+        reason: string;
+    }>;
+}
+export interface AuditFinding {
+    rule: string;
+    nodeId: string;
+    severity: "warning" | "info";
+    state: "finding" | "unknown";
+    detail: string;
+    evidence?: unknown;
+    suppression?: string;
+}
+export declare function validateAuditRules(raw: unknown): AuditRules;
+/** Opaque sRGB subset only. Alpha/multiple paints/images require a richer compositing model. */
+export declare function opaqueRgb(raw: unknown): number[] | undefined;
+export declare function contrastRatio(a: number[], b: number[]): number;
+export declare function auditDesignRules(raw: InspectionDocument, rawRules: AuditRules, tokenInspection?: InspectionDocument, limit?: number): {
+    schemaVersion: number;
+    kind: string;
+    source: {
+        fileId: string;
+        pageId: string | null;
+        revision: number;
+        hash: string;
+    };
+    advisory: boolean;
+    accessibilityCompliance: string;
+    complete: boolean;
+    totalFindings: number;
+    suppressed: number;
+    findings: AuditFinding[];
+    contrast: {
+        measured: number;
+        unknown: number;
+    };
+    library: {
+        instances: number;
+        knownNodes: number;
+        unknownNodes: number;
+        shareOfKnown: number | null;
+        largestPrimitiveGroups: {
+            id: string;
+            area: number;
+        }[];
+    } | null;
+    assumptions: string[];
+};

package/dist/audit-rules.js

@@ -0,0 +1,177 @@
+import { validateDesignInspection } from "./design-spec.js";
+import { observationHash } from "./journal.js";
+export function validateAuditRules(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("audit must be an object");
+    const v = raw;
+    const keys = ["contrast", "library", "touchTargets", "names", "blankText", "interactiveIds", "allowBlank", "nameSegments", "suppressions"];
+    if (Object.keys(v).some(k => !keys.includes(k)))
+        throw new Error("Unknown audit setting");
+    for (const key of ["contrast", "library", "touchTargets", "names", "blankText"])
+        if (v[key] !== undefined && typeof v[key] !== "boolean")
+            throw new Error("Audit rule toggles must be booleans");
+    for (const entries of [v.interactiveIds, v.allowBlank])
+        if (entries !== undefined && (!Array.isArray(entries) || entries.length > 1000 || entries.some(s => typeof s !== "string" || !s || s.length > 200)))
+            throw new Error("Audit ID lists must have at most 1000 explicit IDs");
+    if (v.nameSegments !== undefined && (!Number.isInteger(v.nameSegments) || v.nameSegments < 1 || v.nameSegments > 10))
+        throw new Error("Audit nameSegments must be 1–10");
+    if (v.suppressions !== undefined && (!Array.isArray(v.suppressions) || v.suppressions.length > 1000 || v.suppressions.some(s => !s || !["contrast", "library", "touch-target", "names", "blank-text"].includes(s.rule) || typeof s.nodeId !== "string" || !s.nodeId || typeof s.reason !== "string" || !s.reason.trim() || s.reason.length > 1000)))
+        throw new Error("Audit suppressions require exact rule/node ID and reason");
+    return structuredClone(v);
+}
+/** Opaque sRGB subset only. Alpha/multiple paints/images require a richer compositing model. */
+export function opaqueRgb(raw) {
+    if (typeof raw !== "string")
+        return;
+    const match = /^#([a-f0-9]{6})(ff)?$/i.exec(raw);
+    if (!match)
+        return;
+    return [0, 2, 4].map(i => parseInt(match[1].slice(i, i + 2), 16) / 255);
+}
+export function contrastRatio(a, b) {
+    const luminance = (rgb) => rgb.map(c => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4).reduce((n, c, i) => n + c * [0.2126, 0.7152, 0.0722][i], 0);
+    const x = luminance(a), y = luminance(b);
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+}
+function resolvedColors(tokens, shapes) {
+    const result = new Map();
+    if (!tokens || tokens.schemaVersion !== 1 || tokens.kind !== "token-inspection" || tokens.complete !== true || tokens.redacted === true || tokens.fileId !== shapes.fileId || tokens.revision !== shapes.revision || !Array.isArray(tokens.sets))
+        return result;
+    for (const set of [...tokens.sets].sort((a, b) => Number(a.order) - Number(b.order))) {
+        if (set.active !== true || !Array.isArray(set.tokens))
+            continue;
+        for (const token of set.tokens) {
+            if (typeof token.name !== "string")
+                continue;
+            result.delete(token.name);
+            if (token.type === "color" && (!Array.isArray(token.unknowns) || !token.unknowns.some(k => k === "resolvedValue" || k === "type"))) {
+                const rgb = opaqueRgb(token.resolvedValue);
+                if (rgb)
+                    result.set(token.name, rgb);
+            }
+        }
+    }
+    return result;
+}
+export function auditDesignRules(raw, rawRules, tokenInspection, limit = 1000) {
+    const source = validateDesignInspection(raw), rules = validateAuditRules(rawRules);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10000)
+        throw new Error("Audit finding limit must be 1–10000");
+    const findings = [];
+    let totalFindings = 0, suppressed = 0, contrastMeasured = 0, contrastUnknown = 0, copies = 0, knownComponents = 0, unknownComponents = 0;
+    const rows = new Map(source.nodes.map(n => [String(n.id), n])), colors = resolvedColors(tokenInspection, source);
+    const add = (finding) => {
+        totalFindings++;
+        const suppression = rules.suppressions?.find(s => s.rule === finding.rule && s.nodeId === finding.nodeId);
+        if (suppression)
+            suppressed++;
+        if (findings.length < limit)
+            findings.push({ ...finding, ...(suppression ? { suppression: suppression.reason } : {}) });
+    };
+    const paint = (node) => {
+        const style = node.style, bindings = node.tokens;
+        if (!style || style.opacity !== 1 && style.opacity !== undefined || style.blendMode !== "normal" && style.blendMode !== undefined)
+            return { reason: "Unknown/transparent/blended node style" };
+        const fills = style.fills;
+        if (!Array.isArray(fills))
+            return { reason: "Fill observation unavailable" };
+        if (!fills.length)
+            return { absent: true };
+        if (fills.length !== 1 || !fills[0] || typeof fills[0] !== "object")
+            return { reason: "Multiple or unsupported paints" };
+        const fill = fills[0];
+        if (fill.fillOpacity !== undefined && fill.fillOpacity !== 1 || fill.fillColorGradient || fill.fillImage || fill.fillType && fill.fillType !== "solid")
+            return { reason: "Gradient/image/alpha paint" };
+        const name = bindings?.fill;
+        if (typeof name !== "string" || !colors.has(name))
+            return { reason: "No independently resolved opaque bound color" };
+        const actual = opaqueRgb(fill.fillColor);
+        if (!actual || observationHash(actual) !== observationHash(colors.get(name)))
+            return { reason: "Observed paint differs from resolved bound color" };
+        return { rgb: colors.get(name) };
+    };
+    const backgroundCache = new Map();
+    const backgroundFor = (parent) => {
+        const visited = [];
+        let result = { reason: "No opaque ancestor background" };
+        while (typeof parent === "string") {
+            if (backgroundCache.has(parent)) {
+                result = backgroundCache.get(parent);
+                break;
+            }
+            const ancestor = rows.get(parent);
+            result = paint(ancestor);
+            visited.push(parent);
+            if (!result.absent)
+                break;
+            parent = ancestor.parentId;
+        }
+        if (result.absent)
+            result = { reason: "No opaque ancestor background" };
+        for (const id of visited)
+            backgroundCache.set(id, result);
+        return result;
+    };
+    const rootId = source.nodes.find(n => n.parentId === null)?.id;
+    const largest = [];
+    const considered = source.nodes.filter(n => n.parentId !== null && n.geometry?.hidden !== true);
+    for (const node of considered) {
+        const id = String(node.id), geometry = node.geometry;
+        if (rules.names) {
+            if (["Board", "Rectangle", "Group"].includes(String(node.name)))
+                add({ rule: "names", nodeId: id, severity: "info", state: "finding", detail: "Default layer name" });
+            if (node.type === "board" && node.parentId === rootId && (String(node.name).split("/").length !== (rules.nameSegments ?? 3) || String(node.name).split("/").some(s => !s.trim())))
+                add({ rule: "names", nodeId: id, severity: "info", state: "finding", detail: "Frame name differs from declared slash-separated page/state/device convention" });
+        }
+        if (rules.blankText && node.type === "text" && !rules.allowBlank?.includes(id)) {
+            const text = node.text?.characters;
+            if (typeof text !== "string")
+                add({ rule: "blank-text", nodeId: id, severity: "info", state: "unknown", detail: "Text not observed" });
+            else if (!text.trim() || /^(?:lorem ipsum|placeholder|todo)(?:\b|$)/i.test(text.trim()))
+                add({ rule: "blank-text", nodeId: id, severity: "info", state: "finding", detail: "Blank or placeholder text" });
+        }
+        if (rules.library) {
+            const component = node.component;
+            if (typeof component?.isComponentCopyInstance !== "boolean")
+                unknownComponents++;
+            else {
+                knownComponents++;
+                if (component.isComponentCopyInstance)
+                    copies++;
+                else if (["board", "group"].includes(String(node.type)) && typeof geometry?.width === "number" && typeof geometry?.height === "number")
+                    largest.push({ id, area: geometry.width * geometry.height });
+            }
+        }
+        if (rules.contrast && node.type === "text") {
+            let foreground = paint(node);
+            const background = backgroundFor(node.parentId);
+            const unknowns = node.unknowns;
+            if (unknowns?.includes("text.mixedRangeStyles"))
+                foreground = { reason: "Mixed text range styles" };
+            if (!foreground.rgb || !background.rgb) {
+                contrastUnknown++;
+                add({ rule: "contrast", nodeId: id, severity: "info", state: "unknown", detail: foreground.reason ?? background.reason ?? "Opaque bound colors unavailable" });
+            }
+            else {
+                contrastMeasured++;
+                const typography = node.text?.typography;
+                const size = Number(typography?.fontSize), weight = Number(typography?.fontWeight), threshold = Number.isFinite(size) && (size >= 24 || size >= 56 / 3 && weight >= 700) ? 3 : 4.5;
+                const ratio = contrastRatio(foreground.rgb, background.rgb);
+                if (ratio < threshold)
+                    add({ rule: "contrast", nodeId: id, severity: "warning", state: "finding", detail: "Observed opaque text/background contrast below the review threshold", evidence: { ratio, threshold, assumption: "Design units treated as CSS px; exceptions and implementation rendering unassessed" } });
+            }
+        }
+    }
+    if (rules.touchTargets)
+        for (const id of rules.interactiveIds ?? []) {
+            const node = rows.get(id), g = node?.geometry;
+            if (!node || typeof g?.width !== "number" || typeof g.height !== "number" || !Number.isFinite(g.width) || !Number.isFinite(g.height) || g.width < 0 || g.height < 0)
+                add({ rule: "touch-target", nodeId: id, severity: "info", state: "unknown", detail: "Explicit interactive target dimensions unavailable" });
+            else if (g.width < 44 || g.height < 44)
+                add({ rule: "touch-target", nodeId: id, severity: g.width < 24 || g.height < 24 ? "warning" : "info", state: "finding", detail: g.width < 24 || g.height < 24 ? "Below 24-unit size signal" : "Below 44-unit preference", evidence: { width: g.width, height: g.height, assessment: "size-signal-only; spacing, exceptions, input semantics and CSS scale unassessed" } });
+        }
+    largest.sort((a, b) => b.area - a.area || a.id.localeCompare(b.id));
+    return { schemaVersion: 1, kind: "design-audit", source: { fileId: source.fileId, pageId: source.pageId, revision: source.revision, hash: observationHash(source.nodes) }, advisory: true, accessibilityCompliance: "not-assessed", complete: totalFindings <= limit, totalFindings, suppressed, findings,
+        contrast: { measured: contrastMeasured, unknown: contrastUnknown }, library: rules.library ? { instances: copies, knownNodes: knownComponents, unknownNodes: unknownComponents, shareOfKnown: knownComponents ? copies / knownComponents : null, largestPrimitiveGroups: largest.slice(0, 10) } : null,
+        assumptions: ["Complete captured subtree only; hidden ancestors and overlapping/composited paints need independent review.", "Interactive IDs are explicit declarations, not inferred clickability or WCAG compliance.", "Unavailable resolved colors and mixed styles remain unknown; rules never mutate or block by default."] };
+}

package/dist/backup-note.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectConfig } from "./instance/config.js";
+import type { DoctorCheck } from "./instance/connection.js";
+/** An optional advisory record, not proof that an archive can be restored. Disabled unless configured. */
+export declare function backupNoteCheck(root: string, config: ProjectConfig, now?: Date): Promise<DoctorCheck | undefined>;

package/dist/backup-note.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/** An optional advisory record, not proof that an archive can be restored. Disabled unless configured. */
+export async function backupNoteCheck(root, config, now = new Date()) {
+    if (!config.backup)
+        return undefined;
+    const warn = (detail) => ({ check: "backup note", ok: true, warning: true, detail, remedy: "Export a current archive, restore it into scratch, then update the backup note; see docs/backup.md." });
+    let note;
+    try {
+        note = JSON.parse(await readFile(path.join(root, config.backup.noteFile), "utf8"));
+    }
+    catch {
+        return warn("No readable backup note; archive/restore status is unknown");
+    }
+    if (!note || note.schemaVersion !== 1 || typeof note.fileId !== "string" || typeof note.recordedAt !== "string" || typeof note.archiveSha256 !== "string" || !/^[a-f0-9]{64}$/i.test(note.archiveSha256))
+        return warn("Backup note is incomplete or invalid; archive/restore status is unknown");
+    if (!config.file || note.fileId !== config.file.id)
+        return warn("Backup note does not match a pinned project file");
+    const timestamp = Date.parse(note.recordedAt);
+    const age = now.getTime() - timestamp;
+    if (!Number.isFinite(timestamp) || age < 0)
+        return warn("Backup note has an invalid or future date");
+    if (age >= config.backup.remindAfterDays * 86_400_000)
+        return warn(`Backup note is ${Math.floor(age / 86_400_000)} days old; refresh the archive and restore evidence`);
+    if (note.restoreVerified !== true)
+        return warn("Archive recorded recently, but its restore is not recorded as verified");
+    return { check: "backup note", ok: true, detail: "Recent owner-maintained backup/restore note matches the pinned file (a note is not independent restore proof)" };
+}

package/dist/baseline-coverage.d.ts

@@ -0,0 +1,25 @@
+import { type BaselineCase, type BaselinesConfig, type CoverageRequirement } from "./baselines-config.js";
+import type { BaselineResult } from "./baselines.js";
+export interface CoverageRow {
+    requirement: CoverageRequirement;
+    status: "missing-case" | "missing-capture" | "unapproved-metadata" | "changed-unapproved" | "approved-design-intent" | "unsupported";
+    frameIds: string[];
+    reason?: string;
+}
+export interface BaselineCoverage {
+    schemaVersion: 1;
+    kind: "baseline-coverage";
+    configured: boolean;
+    designCasesComplete: boolean;
+    rows: CoverageRow[];
+    unknown: {
+        id: string;
+        fields: string[];
+    }[];
+    browserVerification: "not-run";
+    accessibility: "not-assessed";
+}
+export declare const designCaseKey: (route: string, value: BaselineCase) => string;
+export declare function baselineCoverage(config: BaselinesConfig, results?: BaselineResult[]): BaselineCoverage;
+/** Offline coverage validates the approved image bytes, never only a manifest's claims. */
+export declare function readBaselineCoverage(root: string, config: BaselinesConfig, expectedFileId?: string): Promise<BaselineCoverage>;