@penpair/core 0.3.4 → 0.3.5

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/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.4";
+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.4";
+export const version = "0.3.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.3.4",
+  "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": {