@penpair/core 0.3.3 → 0.3.5

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/layout-policy.d.ts

@@ -1,2 +1 @@
-/** Trusted, dependency-free sandbox policy shared by the host observer and shipped kit. */
 export declare const layoutPolicySource: string;

package/dist/layout-policy.js

@@ -1,5 +1,6 @@
-/** Trusted, dependency-free sandbox policy shared by the host observer and shipped kit. */
-export const layoutPolicySource = String.raw `
+import { settleLayout } from "./layout-settling.js";
+/** Trusted, dependency-free observation source for the Penpot sandbox. */
+const layoutObservationSource = String.raw `
 const observeLayout = async (penpot, root, options) => {
  if (!Number.isInteger(options.maxNodes === undefined ? 10000 : options.maxNodes) || (options.maxNodes !== undefined && (options.maxNodes < 1 || options.maxNodes > 10000))) throw new Error("Invalid settling node budget");
  const fileId = penpot.currentFile.id, pageId = penpot.currentPage.id;
@@ -38,49 +39,5 @@ const observeLayout = async (penpot, root, options) => {
  validTarget();
  return { ok: true, fileId, pageId, native: nativeOutcome === "completed", nativeOutcome, nativeError, geometry, truncated: false };
 };
-const settleLayout = async (observe, options) => {
- const { timeoutMs, intervalMs, strategy = "auto", sleep } = options;
- if (!["auto", "native", "geometry"].includes(strategy) || !Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || !Number.isFinite(intervalMs) || intervalMs <= 0 || Math.ceil(timeoutMs / intervalMs) + 1 > 1000) throw new Error("Invalid layout strategy or settling budgets");
- const started = Date.now(), deadline = started + timeoutMs;
- let samples = 0, nativeOutcome = "skipped", fallbackReason, identity, previous, equal = 0;
- const result = (stable, method, reason) => ({ stable, method, samples, strategy, nativeOutcome, ...(fallbackReason ? { fallbackReason } : {}), elapsedMs: Date.now() - started, ...(reason ? { reason } : {}) });
- for (let count = 0; count < Math.ceil(timeoutMs / intervalMs) + 1; count++) {
-  const remaining = deadline - Date.now();
-  if (remaining <= 0) return result(false, strategy === "native" ? "native" : "geometry", "Layout observation exceeded its deadline");
-  const nativeMs = count === 0 && strategy !== "geometry" ? strategy === "native" ? remaining : Math.max(1, Math.min(500, Math.floor(remaining / 4))) : 0;
-  const state = await observe(nativeMs, remaining);
-  samples++;
-  if (!state || state.ok !== true || typeof state.fileId !== "string" || !state.fileId || typeof state.pageId !== "string" || !state.pageId) throw new Error("Layout returned no target identity evidence");
-  if (typeof state.native !== "boolean" || typeof state.truncated !== "boolean" || state.nativeOutcome !== undefined && !["skipped", "unsupported", "completed", "failed"].includes(state.nativeOutcome)) throw new Error("Malformed layout attempt evidence");
-  const nextIdentity = JSON.stringify([state.fileId, state.pageId, state.geometry?.[0]?.[0]]);
-  if (identity && identity !== nextIdentity) throw new Error("Layout target changed between samples");
-  identity = nextIdentity;
-  if (state.truncated || !Array.isArray(state.geometry) || !state.geometry.length || state.geometry.length > 10000) throw new Error("Incomplete layout geometry evidence");
-  const ids = new Set(), childIndices = new Map();
-  for (const row of state.geometry) {
-   if (!Array.isArray(row) || row.length !== 7 || typeof row[0] !== "string" || !row[0] || ids.has(row[0]) || !row.slice(1,5).every(value => typeof value === "number" && Number.isFinite(value)) ||  ((row[5] !== null && !ids.has(row[5])) || !Number.isInteger(row[6]) || row[6] < 0)) throw new Error("Layout API returned no geometry evidence or malformed hierarchy");
-   if (!ids.size ? row[5] !== null || row[6] !== 0 : row[5] === null || typeof row[5] !== "string") throw new Error("Malformed layout root hierarchy");
-   if (row[5] !== null) {
-    const expectedIndex = childIndices.get(row[5]) || 0;
-    if (row[6] !== expectedIndex) throw new Error("Malformed layout sibling order");
-    childIndices.set(row[5], expectedIndex + 1);
-   }
-   ids.add(row[0]);
-  }
-  if (count === 0) {
-   nativeOutcome = state.nativeOutcome || (state.native ? state.error ? "failed" : "completed" : strategy === "geometry" ? "skipped" : "unsupported");
-   if (Date.now() >= deadline) return result(false, strategy === "native" || state.native ? "native" : "geometry", "Layout observation exceeded its deadline");
-   if (nativeOutcome === "completed") return result(true, "native");
-   if (strategy === "native") return result(false, "native", state.nativeError || state.error || "Native layout API unavailable");
-   if (strategy === "auto") fallbackReason = state.nativeError || state.error || "Native layout API unavailable";
-  }
-  if (Date.now() >= deadline) return result(false, "geometry", "Layout observation exceeded its deadline");
-  const current = JSON.stringify(state.geometry);
-  equal = current === previous ? equal + 1 : 1;
-  if (equal >= 3) return result(true, "geometry");
-  previous = current;
-  await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
- }
- return result(false, "geometry", "Layout did not settle within its bounded samples");
-};
 `;
+export const layoutPolicySource = `${layoutObservationSource}\nconst settleLayout = ${settleLayout.toString()};`;

package/dist/layout-settling.d.ts

@@ -0,0 +1,10 @@
+import type { LayoutResult, LayoutStrategy } from "./layout.js";
+interface LayoutSettlingOptions {
+    timeoutMs: number;
+    intervalMs: number;
+    strategy: LayoutStrategy;
+    sleep: (ms: number) => Promise<void>;
+}
+/** Self-contained policy: its JavaScript source also runs inside the Penpot sandbox. */
+export declare function settleLayout(observe: (nativeMs: number, remaining: number) => Promise<unknown>, options: LayoutSettlingOptions): Promise<LayoutResult>;
+export {};

package/dist/layout-settling.js

@@ -0,0 +1,155 @@
+/** Self-contained policy: its JavaScript source also runs inside the Penpot sandbox. */
+export async function settleLayout(observe, options) {
+    const { timeoutMs, intervalMs, strategy = "auto", sleep } = options;
+    if (![
+        "auto",
+        "native",
+        "geometry",
+    ].includes(strategy) ||
+        !Number.isFinite(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > 30000 ||
+        !Number.isFinite(intervalMs) ||
+        intervalMs <= 0 ||
+        Math.ceil(timeoutMs / intervalMs) + 1 > 1000) {
+        throw new Error("Invalid layout strategy or settling budgets");
+    }
+    const started = Date.now();
+    const deadline = started + timeoutMs;
+    let samples = 0;
+    let nativeOutcome = "skipped";
+    let fallbackReason;
+    let targetIdentity;
+    let previousGeometry;
+    let matchingSamples = 0;
+    const createResult = (stable, method, reason) => ({
+        stable,
+        method,
+        samples,
+        strategy,
+        nativeOutcome,
+        ...(fallbackReason
+            ? {
+                fallbackReason,
+            }
+            : {}),
+        elapsedMs: Date.now() - started,
+        ...(reason
+            ? {
+                reason,
+            }
+            : {}),
+    });
+    for (let sampleIndex = 0; sampleIndex < Math.ceil(timeoutMs / intervalMs) + 1; sampleIndex++) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            return createResult(false, strategy === "native" ? "native" : "geometry", "Layout observation exceeded its deadline");
+        }
+        const nativeMs = sampleIndex === 0 && strategy !== "geometry"
+            ? strategy === "native"
+                ? remaining
+                : Math.max(1, Math.min(500, Math.floor(remaining / 4)))
+            : 0;
+        const observation = (await observe(nativeMs, remaining));
+        samples++;
+        if (!observation ||
+            observation.ok !== true ||
+            typeof observation.fileId !== "string" ||
+            !observation.fileId ||
+            typeof observation.pageId !== "string" ||
+            !observation.pageId) {
+            throw new Error("Layout returned no target identity evidence");
+        }
+        if (typeof observation.native !== "boolean" ||
+            typeof observation.truncated !== "boolean" ||
+            (observation.nativeOutcome !== undefined &&
+                ![
+                    "skipped",
+                    "unsupported",
+                    "completed",
+                    "failed",
+                ].includes(observation.nativeOutcome))) {
+            throw new Error("Malformed layout attempt evidence");
+        }
+        const nextTargetIdentity = JSON.stringify([
+            observation.fileId,
+            observation.pageId,
+            observation.geometry?.[0]?.[0],
+        ]);
+        if (targetIdentity && targetIdentity !== nextTargetIdentity) {
+            throw new Error("Layout target changed between samples");
+        }
+        targetIdentity = nextTargetIdentity;
+        if (observation.truncated ||
+            !Array.isArray(observation.geometry) ||
+            !observation.geometry.length ||
+            observation.geometry.length > 10000) {
+            throw new Error("Incomplete layout geometry evidence");
+        }
+        const observedShapeIds = new Set();
+        const siblingCountByParent = new Map();
+        for (const geometryRow of observation.geometry) {
+            if (!Array.isArray(geometryRow) ||
+                geometryRow.length !== 7 ||
+                typeof geometryRow[0] !== "string" ||
+                !geometryRow[0] ||
+                observedShapeIds.has(geometryRow[0]) ||
+                !geometryRow
+                    .slice(1, 5)
+                    .every((value) => typeof value === "number" && Number.isFinite(value)) ||
+                (geometryRow[5] !== null && !observedShapeIds.has(geometryRow[5])) ||
+                !Number.isInteger(geometryRow[6]) ||
+                geometryRow[6] < 0) {
+                throw new Error("Layout API returned no geometry evidence or malformed hierarchy");
+            }
+            if (!observedShapeIds.size
+                ? geometryRow[5] !== null || geometryRow[6] !== 0
+                : geometryRow[5] === null || typeof geometryRow[5] !== "string") {
+                throw new Error("Malformed layout root hierarchy");
+            }
+            if (geometryRow[5] !== null) {
+                const expectedIndex = siblingCountByParent.get(geometryRow[5]) || 0;
+                if (geometryRow[6] !== expectedIndex) {
+                    throw new Error("Malformed layout sibling order");
+                }
+                siblingCountByParent.set(geometryRow[5], expectedIndex + 1);
+            }
+            observedShapeIds.add(geometryRow[0]);
+        }
+        if (sampleIndex === 0) {
+            nativeOutcome =
+                observation.nativeOutcome ||
+                    (observation.native
+                        ? observation.error
+                            ? "failed"
+                            : "completed"
+                        : strategy === "geometry"
+                            ? "skipped"
+                            : "unsupported");
+            if (Date.now() >= deadline) {
+                return createResult(false, strategy === "native" || observation.native ? "native" : "geometry", "Layout observation exceeded its deadline");
+            }
+            if (nativeOutcome === "completed") {
+                return createResult(true, "native");
+            }
+            if (strategy === "native") {
+                return createResult(false, "native", observation.nativeError || observation.error || "Native layout API unavailable");
+            }
+            if (strategy === "auto") {
+                fallbackReason =
+                    observation.nativeError || observation.error || "Native layout API unavailable";
+            }
+        }
+        if (Date.now() >= deadline) {
+            return createResult(false, "geometry", "Layout observation exceeded its deadline");
+        }
+        const currentGeometry = JSON.stringify(observation.geometry);
+        matchingSamples = currentGeometry === previousGeometry ? matchingSamples + 1 : 1;
+        if (matchingSamples >= 3) {
+            return createResult(true, "geometry");
+        }
+        previousGeometry = currentGeometry;
+        await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+    }
+    return createResult(false, "geometry", "Layout did not settle within its bounded samples");
+}

package/dist/layout.js

@@ -2,13 +2,12 @@ import { PenpairError } from "./errors.js";
 import { commandSleep } from "./command-result.js";
 import { runSnippet, snippet } from "./snippet.js";
 import { layoutPolicySource } from "./layout-policy.js";
-// This evaluates only the static policy above, never project or transport content.
-const settle = new Function(`${layoutPolicySource}\nreturn settleLayout;`)();
+import { settleLayout } from "./layout-settling.js";
 /** Layout evidence is independent of render equality and visual approval. Transport failures propagate without fallback. */
 export async function waitForStableLayout(client, options = {}) {
     const { timeoutMs = 30000, intervalMs = 200, strategy = "auto", sleep = commandSleep, shapeId, } = options;
     try {
-        return await settle(async (nativeMs, remaining) => runSnippet(client, snippet("layout-state", `${layoutPolicySource}\nconst shape = CFG.shapeId ? penpot.currentPage.getShapeById(CFG.shapeId) : penpot.currentPage.root;\nreturn await observeLayout(penpot, shape, CFG);`, {
+        return await settleLayout(async (nativeMs, remaining) => runSnippet(client, snippet("layout-state", `${layoutPolicySource}\nconst shape = CFG.shapeId ? penpot.currentPage.getShapeById(CFG.shapeId) : penpot.currentPage.root;\nreturn await observeLayout(penpot, shape, CFG);`, {
             shapeId,
             nativeMs,
         }, "read"), {

package/dist/mcp-server.js

@@ -21,6 +21,12 @@ const integer = (max) => ({
 const definitions = [
     {
         name: "pages",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "List pages in the pinned project file",
         properties: {},
         required: [],
@@ -30,6 +36,12 @@ const definitions = [
     },
     {
         name: "tree",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Bounded tree preview; omitted nodes are explicit",
         properties: {
             page: string,
@@ -48,6 +60,12 @@ const definitions = [
     },
     {
         name: "audit",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Inspect layout/token findings with documented heuristic limits",
         properties: {
             page: string,
@@ -63,6 +81,12 @@ const definitions = [
     },
     {
         name: "inspect",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "One bounded structured inspection chunk; use returned cursor for continuation",
         properties: {
             page: string,
@@ -88,6 +112,12 @@ const definitions = [
     },
     {
         name: "tokens_dump",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Bounded token capture; completeness is explicit",
         properties: {},
         required: [],
@@ -100,6 +130,12 @@ const definitions = [
     },
     {
         name: "run_status",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: "Inspect an explicit local recovery journal",
         properties: {
             id: string,
@@ -114,6 +150,12 @@ const definitions = [
     },
     {
         name: "baselines_status",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: "Offline coverage/evidence status; no capture or approval",
         properties: {},
         required: [],
@@ -124,6 +166,12 @@ const definitions = [
     },
     {
         name: "project_status",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Project health with explicit unknowns; no adapter imports",
         properties: {},
         required: [],
@@ -133,6 +181,12 @@ const definitions = [
     },
     {
         name: "doctor",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Project connection/file identity diagnostics",
         properties: {},
         required: [],
@@ -142,6 +196,12 @@ const definitions = [
     },
     {
         name: "design_spec",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: "Derived handoff for an exact frame ID; unknown semantics remain explicit",
         properties: {
             page: string,
@@ -161,6 +221,12 @@ const definitions = [
     },
     {
         name: "export",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: "Capture stable PNG to a relative path inside the project; creates a local file",
         properties: {
             page: string,
@@ -183,6 +249,12 @@ const definitions = [
     },
     {
         name: "run_registered",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: "Execute a trusted registered operation: inspect by default, explicit apply and recovery for writes. Not a sandbox.",
         properties: {
             name: string,
@@ -324,12 +396,7 @@ export async function createMcpServer(options) {
             required: d.required,
             additionalProperties: false,
         },
-        annotations: {
-            readOnlyHint: !d.write && !d.localWrite,
-            destructiveHint: Boolean(d.write || d.localWrite),
-            idempotentHint: !d.write && !d.localWrite,
-            openWorldHint: true,
-        },
+        annotations: d.annotations,
     }));
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools,

package/dist/snippet.js

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import { parse } from "acorn";
 import { executeCode, maxSnippetBytes, UncertainExecutionError, } from "./client.js";
 import { PenpairError } from "./errors.js";
 /**
@@ -25,8 +26,21 @@ export function snippet(name, body, params = {}, effect = "unknown") {
 /** Whether the plugin source is valid JavaScript for an async function. Catches typos without a Penpot connection. */
 export function compiles(code) {
     try {
-        const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
-        new AsyncFunction("penpot", code);
+        const prefix = "(async function (penpot) {\n";
+        const source = `${prefix}${code}\n})`;
+        const parsed = parse(source, {
+            ecmaVersion: "latest",
+            sourceType: "script",
+        });
+        const statement = parsed.body[0];
+        // Keep the input inside the function body, even when it contains closing braces.
+        if (parsed.body.length !== 1 ||
+            statement?.type !== "ExpressionStatement" ||
+            statement.expression.type !== "FunctionExpression" ||
+            statement.expression.body.start !== prefix.indexOf("{") ||
+            statement.expression.body.end !== source.length - 1) {
+            return "Snippet must be a single async function body";
+        }
         return undefined;
     }
     catch (error) {

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.5";

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.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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": {
@@ -44,6 +44,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.0",
+    "acorn": "8.19.0",
     "yaml": "2.9.1"
   },
   "scripts": {