@penpair/core 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @penpair/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The library and engine behind [penpair](https://github.com/niklas-westman/penpair): connect AI agents and people to a Penpot design file, safely.**
+
+This package has no command of its own. For the command, install one of:
+
+- [`@penpair/web`](https://www.npmjs.com/package/@penpair/web): Penpot on the web (design.penpot.app or your team's own). The default.
+- [`@penpair/docker`](https://www.npmjs.com/package/@penpair/docker): the same, plus Penpot in Docker on your computer.
+
+Both include everything in this package. Install this one directly only to use the library from your own code: the connection, the safe write runner, the snippet registry, `defineSnippet`, the skills and `runCli`.
+
+```ts
+import { defineSnippet } from "@penpair/core";
+```
+
+The guide is in the [repository](https://github.com/niklas-westman/penpair#readme).

package/dist/baselines-config.d.ts

@@ -0,0 +1,19 @@
+/** 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. */
+    frame: string;
+    /** Names the image file (`<id>.png`) and the check that uses it. Lowercase letters, digits, hyphens and underscores. */
+    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;
+}
+/** What `penpair baselines` exports: the frames of one page, as images in a folder of the project. */
+export interface BaselinesConfig {
+    page: string;
+    /** Folder for the images, relative to the project. */
+    root: string;
+    frames: BaselineFrame[];
+    /** Allowed share of differing pixels in the generated checks (default 0.05). */
+    threshold?: number;
+}
+export declare function validateBaselines(value: unknown, fail: (message: string) => never): BaselinesConfig;

package/dist/baselines-config.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+const idPattern = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export function validateBaselines(value, fail) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return fail("baselines must be an object");
+    const v = value;
+    if (typeof v.page !== "string" || v.page.length === 0)
+        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");
+    const seen = new Set();
+    for (const entry of v.frames) {
+        const f = entry;
+        if (typeof f !== "object" || f === null)
+            fail("every entry in baselines.frames must be an object");
+        if (typeof f.frame !== "string" || f.frame.length === 0)
+            fail("every baselines.frames entry needs a frame name");
+        if (typeof f.id !== "string" || !idPattern.test(f.id))
+            fail(`baselines.frames id ${JSON.stringify(f.id)} must be lowercase letters, digits, hyphens or underscores`);
+        if (seen.has(f.id))
+            fail(`baselines.frames id ${JSON.stringify(f.id)} is used twice`);
+        seen.add(f.id);
+        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))
+        fail("baselines.threshold must be a number from 0 to 1");
+    return v;
+}

package/dist/baselines.d.ts

@@ -0,0 +1,72 @@
+import type { PenpotToolClient } from "./client.js";
+import type { BaselinesConfig } from "./baselines-config.js";
+import { type ExportOptions } from "./export.js";
+export * from "./baselines-config.js";
+export type BaselineStatus = 
+/** No image in the folder yet. */
+"new"
+/** The image in the folder is byte-identical to the design now. */
+ | "same"
+/** The design differs from the image in the folder. Replaced only with `update`. */
+ | "changed"
+/** 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";
+export interface BaselineResult {
+    id: string;
+    frame: string;
+    frameId?: string;
+    width?: number;
+    height?: number;
+    file: string;
+    status: BaselineStatus;
+    /** Whether the image was written to the folder in this run. */
+    written: boolean;
+    /** The image now in the folder: its hash, size in bytes and pixel size. For a design that changed and was not updated this is the old image. */
+    sha256?: string;
+    bytes?: number;
+    imageWidth?: number;
+    imageHeight?: number;
+}
+export interface BaselinesReport {
+    page: string;
+    penpotFile: string;
+    revn: number;
+    results: BaselineResult[];
+    /** Files written: images, the manifest and the generated checks. */
+    wrote: string[];
+}
+export interface BaselinesOptions extends ExportOptions {
+    /** 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;
+}
+/** 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
+ * the design never silently becomes the new reference.
+ */
+export declare function exportBaselines(client: PenpotToolClient, projectRoot: string, config: BaselinesConfig, options?: BaselinesOptions): Promise<BaselinesReport>;
+/**
+ * Visual cases for Reflection, one per frame that names a route: the image's exact size is the viewport (so the capture and the
+ * reference have the same dimensions), the image is the baseline, and `ref` joins the check back to the frame.
+ * Review-only (`strict: false`): a difference is shown to a person, not failed.
+ */
+export declare function reflectionCases(config: BaselinesConfig, results: BaselineResult[]): {
+    note: string;
+    routes: Record<string, {
+        viewports: {
+            name: string;
+            width: number;
+            height: number;
+        }[];
+    }>;
+    visualSmoke: Record<string, unknown>[];
+};

package/dist/baselines.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+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;
+    }
+}
+/**
+ * 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
+ * the design never silently becomes the new reference.
+ */
+export async function exportBaselines(client, projectRoot, config, options = {}) {
+    const listing = await runOnPage(client, frames({ page: config.page }), config.page, options);
+    const found = listing.frames ?? [];
+    const results = [];
+    const wrote = [];
+    const folder = path.join(projectRoot, config.root);
+    for (const wanted of config.frames) {
+        const file = `${wanted.id}.png`;
+        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 });
+            continue;
+        }
+        if (matches.length > 1)
+            throw new Error(`more than one top-level frame on ${config.page} is named ${JSON.stringify(wanted.frame)}; rename one so the design reference is unambiguous`);
+        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 };
+        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));
+        }
+        // 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 });
+    }
+    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"));
+        }
+    }
+    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 })),
+    };
+}
+/**
+ * Visual cases for Reflection, one per frame that names a route: the image's exact size is the viewport (so the capture and the
+ * reference have the same dimensions), the image is the baseline, and `ref` joins the check back to the frame.
+ * Review-only (`strict: false`): a difference is shown to a person, not failed.
+ */
+export function reflectionCases(config, results) {
+    const routes = {};
+    const visualSmoke = [];
+    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;
+        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))
+            entry.viewports.push(viewport);
+        visualSmoke.push({
+            id: wanted.id,
+            route: wanted.route,
+            viewport: viewport.name,
+            baselineRoot: config.root,
+            baseline: `${wanted.id}.png`,
+            threshold: { maxDiffPixelRatio: config.threshold ?? 0.05 },
+            strict: false,
+            ref: `penpair:${wanted.id}`,
+        });
+    }
+    return {
+        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,
+    };
+}

package/dist/cli-main.d.ts

@@ -0,0 +1,7 @@
+import { type LocalProfile } from "./local-profile.js";
+export interface CliOptions {
+    /** 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 runCli(argv: string[], options?: CliOptions): Promise<number>;