@penpair/core 0.4.0 → 0.5.0

package/dist/layout-settling.js

@@ -1,11 +1,14 @@
 /** 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) ||
+    const { timeoutMs, intervalMs, strategy = "auto", maxNodes = 10000, sleep } = options;
+    if (!Number.isInteger(maxNodes) ||
+        maxNodes < 1 ||
+        maxNodes > 100000 ||
+        ![
+            "auto",
+            "native",
+            "geometry",
+        ].includes(strategy) ||
         !Number.isFinite(timeoutMs) ||
         timeoutMs < 1 ||
         timeoutMs > 30000 ||
@@ -17,6 +20,9 @@ export async function settleLayout(observe, options) {
     const started = Date.now();
     const deadline = started + timeoutMs;
     let samples = 0;
+    let nodeCount = 0;
+    let rootIds = [];
+    let truncated = false;
     let nativeOutcome = "skipped";
     let fallbackReason;
     let targetIdentity;
@@ -24,8 +30,12 @@ export async function settleLayout(observe, options) {
     let matchingSamples = 0;
     const createResult = (stable, method, reason) => ({
         stable,
-        method,
+        method: truncated ? "partial" : method,
         samples,
+        rootIds,
+        nodeCount,
+        maxNodes,
+        truncated,
         strategy,
         nativeOutcome,
         ...(fallbackReason
@@ -34,9 +44,10 @@ export async function settleLayout(observe, options) {
             }
             : {}),
         elapsedMs: Date.now() - started,
-        ...(reason
+        ...(reason || truncated
             ? {
-                reason,
+                reason: reason ??
+                    "Only the bounded layout sample was observed; independent readback is required",
             }
             : {}),
     });
@@ -74,20 +85,34 @@ export async function settleLayout(observe, options) {
         const nextTargetIdentity = JSON.stringify([
             observation.fileId,
             observation.pageId,
-            observation.geometry?.[0]?.[0],
+            observation.rootIds ?? [
+                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) ||
+        if (!Array.isArray(observation.geometry) ||
             !observation.geometry.length ||
-            observation.geometry.length > 10000) {
+            observation.geometry.length > maxNodes) {
             throw new Error("Incomplete layout geometry evidence");
         }
+        const observedRoots = observation.rootIds ?? [
+            observation.geometry[0][0],
+        ];
+        if (!Array.isArray(observedRoots) ||
+            !observedRoots.length ||
+            observedRoots.some((id) => typeof id !== "string" || !id) ||
+            new Set(observedRoots).size !== observedRoots.length) {
+            throw new Error("Malformed layout root evidence");
+        }
+        rootIds = observedRoots;
+        nodeCount = observation.geometry.length;
+        truncated = observation.truncated;
         const observedShapeIds = new Set();
         const siblingCountByParent = new Map();
+        let rootIndex = 0;
         for (const geometryRow of observation.geometry) {
             if (!Array.isArray(geometryRow) ||
                 geometryRow.length !== 7 ||
@@ -102,9 +127,12 @@ export async function settleLayout(observe, options) {
                 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") {
+            if (geometryRow[5] === null) {
+                if (geometryRow[0] !== rootIds[rootIndex++] || geometryRow[6] !== 0) {
+                    throw new Error("Malformed layout root hierarchy");
+                }
+            }
+            else if (typeof geometryRow[5] !== "string") {
                 throw new Error("Malformed layout root hierarchy");
             }
             if (geometryRow[5] !== null) {
@@ -116,6 +144,9 @@ export async function settleLayout(observe, options) {
             }
             observedShapeIds.add(geometryRow[0]);
         }
+        if (!truncated && rootIndex !== rootIds.length) {
+            throw new Error("Incomplete layout root evidence");
+        }
         if (sampleIndex === 0) {
             nativeOutcome =
                 observation.nativeOutcome ||
@@ -143,7 +174,10 @@ export async function settleLayout(observe, options) {
         if (Date.now() >= deadline) {
             return createResult(false, "geometry", "Layout observation exceeded its deadline");
         }
-        const currentGeometry = JSON.stringify(observation.geometry);
+        const currentGeometry = JSON.stringify([
+            observation.geometry,
+            observation.truncated,
+        ]);
         matchingSamples = currentGeometry === previousGeometry ? matchingSamples + 1 : 1;
         if (matchingSamples >= 3) {
             return createResult(true, "geometry");

package/dist/layout.d.ts

@@ -2,6 +2,8 @@ import type { PenpotToolClient } from "./client.js";
 export type LayoutStrategy = "auto" | "native" | "geometry";
 export interface LayoutOptions {
     shapeId?: string;
+    shapeIds?: string[];
+    maxNodes?: number;
     strategy?: LayoutStrategy;
     timeoutMs?: number;
     intervalMs?: number;
@@ -9,7 +11,11 @@ export interface LayoutOptions {
 }
 export interface LayoutResult {
     stable: boolean;
-    method: "native" | "geometry" | "unavailable";
+    method: "native" | "geometry" | "partial" | "unavailable";
+    rootIds?: string[];
+    nodeCount?: number;
+    maxNodes?: number;
+    truncated?: boolean;
     samples: number;
     reason?: string;
     strategy?: LayoutStrategy;

package/dist/layout.js

@@ -5,10 +5,25 @@ import { layoutPolicySource } from "./layout-policy.js";
 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;
+    const { timeoutMs = 30000, intervalMs = 200, strategy = "auto", sleep = commandSleep, shapeId, shapeIds, maxNodes = 10000, } = options;
+    const roots = shapeIds ??
+        (shapeId
+            ? [
+                shapeId,
+            ]
+            : []);
+    if (!Array.isArray(roots) ||
+        roots.some((id) => typeof id !== "string" || !id.trim()) ||
+        new Set(roots).size !== roots.length) {
+        throw new Error("Layout roots must be distinct nonempty shape IDs");
+    }
+    if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 100000) {
+        throw new Error("Layout node budget must be an integer from 1 to 100000");
+    }
     try {
-        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,
+        return await settleLayout(async (nativeMs, remaining) => runSnippet(client, snippet("layout-state", `${layoutPolicySource}\nconst roots = CFG.shapeIds.length ? CFG.shapeIds.map(id => penpot.currentPage.getShapeById(id)) : [penpot.currentPage.root];\nreturn await observeLayout(penpot, roots, CFG);`, {
+            shapeIds: roots,
+            maxNodes,
             nativeMs,
         }, "read"), {
             retries: 0,
@@ -17,6 +32,7 @@ export async function waitForStableLayout(client, options = {}) {
             timeoutMs,
             intervalMs,
             strategy,
+            maxNodes,
             sleep,
         });
     }

package/dist/mcp-server.js

@@ -13,9 +13,9 @@ const string = {
     minLength: 1,
     maxLength: 1000,
 };
-const integer = (max) => ({
+const integer = (max, min = 0) => ({
     type: "integer",
-    minimum: 0,
+    minimum: min,
     maximum: max,
 });
 const definitions = [
@@ -247,6 +247,83 @@ const definitions = [
         ],
         localWrite: true,
     },
+    {
+        name: "design_release_copy",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: "Experimental same-file native board copy to release/<version>, preview by default. Requires a configured project, pinned file and connected Penpot plugin; advertised only with --allow-writes. Applying also requires an already enabled loopback browser debugging port, existing clipboard read/write access and focused editor canvas. Does not start a browser or grant permissions. Host-independent CLI/MCP operation; no automatic fallback to the assistant's computer-control tools. The successful native-UI trial used an injected test driver; bundled CDP/Penpot qualification remains pending. Preserves originals, changes focus/clipboard, never blindly replays an uncertain paste and does not approve a release.",
+        properties: {
+            sourcePage: {
+                ...string,
+                description: "Exact source page name or ID within the project's pinned Penpot file.",
+            },
+            frameIds: {
+                type: "array",
+                items: string,
+                minItems: 1,
+                maxItems: 100,
+                uniqueItems: true,
+                description: "Observed native board IDs on the source page; selections must not overlap.",
+            },
+            releaseVersion: {
+                ...string,
+                pattern: "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+                description: "Version naming the new or existing destination page: release/<version>.",
+            },
+            debugPort: {
+                ...integer(65535, 1),
+                description: "Required for apply: an existing loopback CDP port. This does not enable debugging or grant clipboard access.",
+            },
+            apply: {
+                type: "boolean",
+                default: false,
+                description: "False previews only. True explicitly authorizes native copying and requires debugPort plus existing browser clipboard read/write access.",
+            },
+            resume: {
+                ...string,
+                description: "Original run ID for explicit reconciliation with apply=true and the same inputs; never blindly repeats a paste.",
+            },
+        },
+        required: [
+            "sourcePage",
+            "frameIds",
+            "releaseVersion",
+        ],
+        write: true,
+        command: (a) => [
+            "design-release",
+            "copy",
+            "--source-page",
+            String(a.sourcePage),
+            ...a.frameIds.flatMap((frameId) => [
+                "--frame",
+                frameId,
+            ]),
+            "--release",
+            String(a.releaseVersion),
+            ...(a.debugPort !== undefined
+                ? [
+                    "--debug-port",
+                    String(a.debugPort),
+                ]
+                : []),
+            ...(a.apply
+                ? [
+                    "--apply",
+                ]
+                : []),
+            ...(a.resume
+                ? [
+                    "--resume",
+                    String(a.resume),
+                ]
+                : []),
+        ],
+    },
     {
         name: "run_registered",
         annotations: {
@@ -329,6 +406,7 @@ function validate(def, raw) {
                 !value ||
                 value.startsWith("-") ||
                 value.length > (schema.maxLength ?? 1000) ||
+                (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) ||
                 /[\x00-\x1f]/.test(value))) {
             throw new Error(`Invalid ${key}`);
         }
@@ -336,7 +414,22 @@ function validate(def, raw) {
             throw new Error(`Invalid ${key}`);
         }
         if (schema.type === "integer" &&
-            (!Number.isInteger(value) || Number(value) < 0 || Number(value) > schema.maximum)) {
+            (!Number.isInteger(value) ||
+                Number(value) < (schema.minimum ?? 0) ||
+                Number(value) > schema.maximum)) {
+            throw new Error(`Invalid ${key}`);
+        }
+        if (schema.type === "array" &&
+            (!Array.isArray(value) ||
+                value.length < (schema.minItems ?? 0) ||
+                value.length > (schema.maxItems ?? 100) ||
+                (schema.uniqueItems && new Set(value).size !== value.length) ||
+                value.some((item) => schema.items?.type !== "string" ||
+                    typeof item !== "string" ||
+                    !item.trim() ||
+                    item.startsWith("-") ||
+                    item.length > (schema.items.maxLength ?? 1000) ||
+                    /[\x00-\x1f]/.test(item)))) {
             throw new Error(`Invalid ${key}`);
         }
         if (key === "params" &&
@@ -351,6 +444,9 @@ function validate(def, raw) {
     if ((a.resume || a.checkpoint) && !a.apply) {
         throw new Error("Explicit resume requires apply");
     }
+    if (def.name === "design_release_copy" && a.apply && a.debugPort === undefined) {
+        throw new Error("Native copy apply requires debugPort");
+    }
     return a;
 }
 /** Long-lived server with an immutable explicit root and no process.chdir or raw-code tool. */

package/dist/native-editor-clipboard.d.ts

@@ -0,0 +1,17 @@
+import { type BrowserTargetOptions } from "./browser-wake.js";
+export interface NativeClipboard {
+    copy(expectedPageId: string, expectedFrameIds: string[]): Promise<void>;
+    paste(expectedPageId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface ClipboardSocket extends EventTarget {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+}
+export interface NativeClipboardOptions extends BrowserTargetOptions {
+    /** Tests may substitute the protocol transport; ordinary commands use Node's WebSocket. */
+    createSocket?: (url: string) => ClipboardSocket;
+}
+/** Holds a short exclusive clipboard session; closing releases control, never the browser. */
+export declare function connectNativeClipboard(options: NativeClipboardOptions): Promise<NativeClipboard>;