@penpair/core 0.3.3 → 0.3.4

package/dist/baseline-coverage.js

@@ -63,6 +63,7 @@ export function baselineCoverage(config, results = []) {
             return (evidence?.approval?.kind !== "forced-reference" &&
                 ![
                     "missing",
+                    "renamed",
                     "unstable",
                     "case-mismatch",
                 ].includes(result.status) &&
@@ -199,6 +200,7 @@ export async function readBaselineCoverage(root, config, expectedFileId) {
                 "same",
                 "changed",
                 "missing",
+                "renamed",
                 "unstable",
                 "case-mismatch",
             ].includes(value.status) ||

package/dist/baselines-config.d.ts

@@ -22,8 +22,10 @@ export interface CoverageConfig {
 }
 /** 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;
+    /** Exact top-level frame name, or an expected name when frameId is supplied. */
+    frame?: string;
+    /** Stable board UUID, resolved at any depth on the configured page. */
+    frameId?: 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. */

package/dist/baselines-config.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+const frameIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const idPattern = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 export function validateBaselines(value, fail) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -18,13 +19,27 @@ export function validateBaselines(value, fail) {
         fail("baselines.frames must list at least one frame, at most 1000");
     }
     const seen = new Set();
+    const seenFrameIds = 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 (f.frame === undefined && f.frameId === undefined) {
+            fail("every baselines.frames entry needs frame or frameId");
+        }
+        if (f.frame !== undefined && (typeof f.frame !== "string" || f.frame.length === 0)) {
+            fail("baselines.frames frame must be a non-empty name");
+        }
+        if (f.frameId !== undefined) {
+            if (typeof f.frameId !== "string" || !frameIdPattern.test(f.frameId)) {
+                fail("baselines.frames frameId must be a UUID");
+            }
+            const frameId = f.frameId.toLowerCase();
+            if (seenFrameIds.has(frameId)) {
+                fail(`baselines.frames frameId ${JSON.stringify(f.frameId)} is used twice`);
+            }
+            seenFrameIds.add(frameId);
         }
         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`);

package/dist/baselines.d.ts

@@ -14,8 +14,10 @@ export type BaselineStatus =
  | "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" | "case-mismatch";
+/** No board matches the configured ID, or no top-level frame matches the name. */
+ | "missing"
+/** An ID-resolved board no longer has its configured expected name. */
+ | "renamed" | "case-mismatch";
 export interface ArtifactProvenance extends CaptureIdentity {
     approval?: {
         kind: "owner-words";

package/dist/baselines.js

@@ -45,6 +45,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     });
     const listing = await runOnPage(client, frames({
         page: config.page,
+        recursive: config.frames.some((entry) => entry.frameId !== undefined),
     }), config.page, options);
     if (listing.ok !== true ||
         typeof listing.fileId !== "string" ||
@@ -55,6 +56,9 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         !Array.isArray(listing.frames)) {
         throw new Error("Baseline listing lacks file/page/revision evidence");
     }
+    if (listing.truncated === true) {
+        throw new Error("Baseline frame search truncated at the page shape budget; nothing was captured");
+    }
     const found = listing.frames;
     const results = [];
     const wrote = [];
@@ -79,7 +83,9 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         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);
+        const matches = found.filter((frame) => wanted.frameId
+            ? frame.id.toLowerCase() === wanted.frameId.toLowerCase()
+            : frame.topLevel !== false && frame.name === wanted.frame);
         if (!matches.length) {
             results.push({
                 ...(wanted.case
@@ -88,7 +94,8 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                     }
                     : {}),
                 id: wanted.id,
-                frame: wanted.frame,
+                frame: wanted.frame ?? wanted.frameId,
+                frameId: wanted.frameId,
                 file,
                 status: "missing",
                 written: false,
@@ -99,7 +106,22 @@ export async function exportBaselines(client, projectRoot, config, options = {})
             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}`);
+        if (wanted.frameId && wanted.frame !== undefined && wanted.frame !== frame.name) {
+            results.push({
+                id: wanted.id,
+                frame: wanted.frame,
+                frameId: frame.id,
+                case: wanted.case,
+                file,
+                status: "renamed",
+                problems: [
+                    `Expected frame name ${JSON.stringify(wanted.frame)}; current name is ${JSON.stringify(frame.name)}`,
+                ],
+                written: false,
+            });
+            continue;
+        }
+        options.onStep?.(`exporting ${frame.name}`);
         const exported = await exportShapePng(client, frame.id, {
             ...options,
             page: config.page,
@@ -112,7 +134,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 }
                 : {}),
             id: wanted.id,
-            frame: wanted.frame,
+            frame: frame.name,
             frameId: frame.id,
             width: frame.width,
             height: frame.height,
@@ -253,6 +275,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     }
     const after = await runOnPage(client, frames({
         page: config.page,
+        recursive: config.frames.some((entry) => entry.frameId !== undefined),
     }), config.page, options);
     const source = (value) => ({
         fileId: value.fileId,
@@ -260,11 +283,14 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         revision: value.revn,
         frames: value.frames,
     });
-    if (observationHash(source(listing)) !== observationHash(source(after))) {
+    if (after.ok !== true ||
+        after.truncated === true ||
+        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 !== "renamed" &&
             result.status !== "unstable" &&
             result.status !== "case-mismatch");
     if (options.apply && complete) {

package/dist/cli-main.js

@@ -1914,9 +1914,16 @@ async function main(argv, cli) {
                 if (!wanted?.case || baseline?.page !== values.page) {
                     throw new Error("Approval case must reference an explicitly configured frame on this page");
                 }
-                const found = await findShapesByName(client, wanted.frame, values.page);
-                if (found.matches.length !== 1 || found.matches[0].id !== values.frame) {
-                    throw new Error("Approval frame ID does not match the configured case");
+                if (wanted.frameId) {
+                    if (wanted.frameId.toLowerCase() !== values.frame.toLowerCase()) {
+                        throw new Error("Approval frame ID does not match the configured case");
+                    }
+                }
+                else {
+                    const found = await findShapesByName(client, wanted.frame, values.page);
+                    if (found.matches.length !== 1 || found.matches[0].id !== values.frame) {
+                        throw new Error("Approval frame ID does not match the configured case");
+                    }
                 }
                 intent = wanted.case;
             }

package/dist/instance/config-schema.d.ts

@@ -285,7 +285,12 @@ export declare const projectConfigSchema: {
                     readonly maxItems: 1000;
                     readonly items: {
                         readonly type: "object";
-                        readonly required: readonly ["frame", "id"];
+                        readonly required: readonly ["id"];
+                        readonly anyOf: readonly [{
+                            readonly required: readonly ["frame"];
+                        }, {
+                            readonly required: readonly ["frameId"];
+                        }];
                         readonly dependentRequired: {
                             readonly case: readonly ["route"];
                         };
@@ -294,6 +299,10 @@ export declare const projectConfigSchema: {
                                 readonly type: "string";
                                 readonly minLength: 1;
                             };
+                            readonly frameId: {
+                                readonly type: "string";
+                                readonly pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
+                            };
                             readonly id: {
                                 readonly type: "string";
                                 readonly pattern: "^[a-z0-9][a-z0-9_-]{0,63}$";

package/dist/instance/config-schema.js

@@ -333,9 +333,20 @@ export const projectConfigSchema = {
                     items: {
                         type: "object",
                         required: [
-                            "frame",
                             "id",
                         ],
+                        anyOf: [
+                            {
+                                required: [
+                                    "frame",
+                                ],
+                            },
+                            {
+                                required: [
+                                    "frameId",
+                                ],
+                            },
+                        ],
                         dependentRequired: {
                             case: [
                                 "route",
@@ -346,6 +357,10 @@ export const projectConfigSchema = {
                                 type: "string",
                                 minLength: 1,
                             },
+                            frameId: {
+                                type: "string",
+                                pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+                            },
                             id: {
                                 type: "string",
                                 pattern: "^[a-z0-9][a-z0-9_-]{0,63}$",

package/dist/snippets/read.d.ts

@@ -4,8 +4,10 @@ export declare function pages(): Snippet;
 export declare function switchPage(name: string): Snippet;
 export interface FramesParams {
     page: string;
+    /** Include nested boards with a bounded whole-page search. */
+    recursive?: boolean;
 }
-/** The top-level frames of a page: id, name and size, so they can be found by name and exported. */
+/** List top-level frames by default; opt in to a bounded search of every board on the page. */
 export declare function frames(params: FramesParams): Snippet;
 export interface TreeParams {
     page: string;

package/dist/snippets/read.js

@@ -14,11 +14,36 @@ return { ok: true, switched: true };`, {
         name,
     });
 }
-/** The top-level frames of a page: id, name and size, so they can be found by name and exported. */
+/** List top-level frames by default; opt in to a bounded search of every board on the page. */
 export function frames(params) {
     return readSnippet("frames", `${requirePage}
+if (!CFG.recursive) {
+  return { ok: true, readOnly: true, file: penpot.currentFile.name, fileId: penpot.currentFile.id, revn: penpot.currentFile.revn, page: penpot.currentPage.name, pageId: penpot.currentPage.id,
+    frames: penpot.currentPage.root.children.filter((shape) => shape.type === "board").map((shape) => ({ id: shape.id, name: shape.name, width: Math.round(shape.width), height: Math.round(shape.height) })) };
+}
+const boards = [];
+const budget = 10000;
+const stack = [];
+let visited = 0;
+let truncated = false;
+const enqueue = (children, parentBoardId, topLevel) => {
+  const take = Math.min(children.length, Math.max(0, budget - visited - stack.length));
+  if (take < children.length) { truncated = true; }
+  for (let index = take - 1; index >= 0; index--) {
+    stack.push({ shape: children[index], parentBoardId, topLevel });
+  }
+};
+enqueue(penpot.currentPage.root.children, null, true);
+while (stack.length) {
+  const { shape, parentBoardId, topLevel } = stack.pop();
+  visited++;
+  if (shape.type === "board") {
+    boards.push({ id: shape.id, name: shape.name, width: Math.round(shape.width), height: Math.round(shape.height), parentBoardId, topLevel });
+  }
+  enqueue(shape.children || [], shape.type === "board" ? shape.id : parentBoardId, false);
+}
 return { ok: true, readOnly: true, file: penpot.currentFile.name, fileId: penpot.currentFile.id, revn: penpot.currentFile.revn, page: penpot.currentPage.name, pageId: penpot.currentPage.id,
-  frames: penpot.currentPage.root.children.filter((c) => c.type === "board").map((c) => ({ id: c.id, name: c.name, width: Math.round(c.width), height: Math.round(c.height) })) };`, params);
+  frames: boards, visited, truncated, complete: !truncated };`, params);
 }
 /** One line per shape: type, name, size, position on the page, layout and sizing, the text it carries. */
 export function tree(params) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export declare const version = "0.3.3";
+export declare const version = "0.3.4";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export const version = "0.3.3";
+export const version = "0.3.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Design together. Build together. The library and engine behind penpair: connect AI agents and people to a Penpot design file, safely. Install @penpair/web or @penpair/docker for the command.",
   "license": "MIT",
   "repository": {