@penpair/core 0.4.0 → 0.5.0

package/dist/design-releases/copy.js

@@ -0,0 +1,466 @@
+import { randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { commandSleep } from "../command-result.js";
+import { writeCoordinator } from "../coordination.js";
+import { guardFile } from "../file-guard.js";
+import { runJournaledSteps, readJournalTarget, readJournal, listJournals, observationHash, JournalRunError, } from "../journal.js";
+import { withPageSession, selectPage, rememberPage } from "../page-session.js";
+import { runSnippet } from "../snippet.js";
+import { ensureGitignoreEntry } from "../instance/gitignore.js";
+import { atomicWriteFile } from "../atomic-output.js";
+import { readProjectBytes } from "../bounded-file.js";
+import { artifactPath, saveArtifact } from "./artifact-paths.js";
+import { captureReleaseScreen } from "./live.js";
+import { captureCopyEvidence, matchCopiedFrames, compareCopyEvidence, sourceEvidenceHash, } from "./copy-evidence.js";
+import { nativeCopyInspect, nativeCopyCreatePage, nativeCopySelect, nativeCopyObserve, nativeCopyArrange, } from "./copy-snippets.js";
+import { validateCopyRequest, readCopyPreview, copyRequestHash, } from "./copy-plan.js";
+const operation = "design-release-copy";
+async function observedDestination(client, fileId, pageId) {
+    await selectPage(client, {
+        id: pageId,
+    });
+    const result = await runSnippet(client, nativeCopyObserve(fileId, pageId), {
+        effect: "read",
+        retries: 0,
+    });
+    if (result.ok !== true ||
+        result.fileId !== fileId ||
+        result.pageId !== pageId ||
+        !Array.isArray(result.rootIds) ||
+        !Array.isArray(result.selectionIds) ||
+        !Array.isArray(result.rootFrames) ||
+        result.rootIds.some((id) => typeof id !== "string")) {
+        throw new Error("Destination inventory or selection was not independently observed");
+    }
+    return result;
+}
+/** Copy native boards through an explicitly supplied editor transport; preview never touches clipboard or selection. */
+export async function copyReleaseBoards(client, root, request, options = {}) {
+    validateCopyRequest(request);
+    if (options.resume && (!options.apply || !options.runId)) {
+        throw new Error("Copy resume requires --apply and the original run ID");
+    }
+    client = guardFile(client, {
+        id: request.fileId,
+    }, {
+        mode: "strict",
+    });
+    return withPageSession(client, async () => {
+        const inspect = async (ownerKey) => readCopyPreview(await runSnippet(client, nativeCopyInspect(request.fileId, request.sourcePage, request.frameIds, request.releaseVersion, ownerKey), {
+            effect: "read",
+            retries: 0,
+        }), request);
+        const current = await inspect();
+        if (!options.apply) {
+            return {
+                schemaVersion: 1,
+                kind: "native-release-copy",
+                status: "preview",
+                preview: current,
+                problems: [
+                    "Native browser copy/paste is experimental; structural and stable-render verification follow an explicit apply.",
+                ],
+            };
+        }
+        if (!options.clipboard) {
+            throw new Error("Native copy requires an explicitly configured browser clipboard transport");
+        }
+        const runId = options.runId ?? randomUUID();
+        if (!/^[A-Za-z0-9-]{1,100}$/.test(runId)) {
+            throw new Error("Invalid native copy run ID");
+        }
+        const assertNoConflictingRuns = async () => {
+            const records = await listJournals(root);
+            for (const previous of records.filter((record) => record.operation === operation && record.target.fileId === request.fileId)) {
+                if (previous.runId === runId) {
+                    continue;
+                }
+                const record = await readJournal(root, previous.runId);
+                const payload = record.payload;
+                if (previous.state !== "verified" ||
+                    (payload?.kind === "native-release-copy-plan" &&
+                        copyRequestHash(payload.request) === copyRequestHash(request))) {
+                    throw new Error(`Copy run ${previous.runId} already covers this transfer or requires reconciliation; use its explicit --resume before another paste`);
+                }
+            }
+        };
+        await assertNoConflictingRuns();
+        await ensureGitignoreEntry(root, ".penpair", {
+            directory: true,
+            comment: "penpair: private operation evidence",
+        });
+        const prefix = `.penpair/native-copy/${runId}`;
+        const fencePath = await artifactPath(root, `${prefix}/paste-attempt.json`, true);
+        let payload;
+        let attempted = false;
+        let pageAttempted = false;
+        if (options.resume) {
+            const previous = await readJournal(root, runId);
+            pageAttempted = previous.steps.some((step) => step.key === "page" && step.state !== "pending");
+            payload = previous.payload;
+            if (!payload ||
+                payload.kind !== "native-release-copy-plan" ||
+                copyRequestHash(payload.request) !== copyRequestHash(request)) {
+                throw new Error("Copy resume inputs changed; no clipboard operation was dispatched");
+            }
+            // The durable fence is written before the only paste call. A started
+            // journal step may have stopped earlier during page/selection preparation.
+            try {
+                await lstat(fencePath);
+                attempted = true;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        else {
+            const sources = await captureCopyEvidence(client, root, request.fileId, current.sourcePageId, request.frameIds, `${prefix}/source`, options.redact);
+            payload = {
+                kind: "native-release-copy-plan",
+                request,
+                preview: current,
+                sources,
+            };
+            await saveArtifact(root, `${prefix}/plan.json`, `${JSON.stringify(payload)}\n`, options.redact);
+        }
+        if (Buffer.byteLength(JSON.stringify(payload)) > 16 * 1024 * 1024) {
+            throw new Error("Native transfer plan exceeds 16 MiB");
+        }
+        const baseline = payload.preview;
+        let pinnedDestinationId = baseline.destinationPageId;
+        const readSource = async () => {
+            for (const source of payload.sources) {
+                const observed = await captureReleaseScreen(client, request.fileId, baseline.sourcePageId, source.frameId);
+                if (observationHash(observed.nodes) !== observationHash(source.inspection.nodes)) {
+                    throw new Error("Source board content changed; retain the run and make a new reviewed plan");
+                }
+            }
+        };
+        const targetPreview = async () => {
+            const value = await inspect(runId);
+            if (!baseline.destinationPageId &&
+                value.destinationPageId &&
+                value.createdPageOwner !== runId) {
+                throw new Error("A different page appeared at the planned destination");
+            }
+            if (pinnedDestinationId && value.destinationPageId !== pinnedDestinationId) {
+                throw new Error("Pinned destination page was replaced or renamed");
+            }
+            if (value.destinationPageId) {
+                pinnedDestinationId = value.destinationPageId;
+            }
+            if (value.sourcePageId !== baseline.sourcePageId ||
+                (baseline.destinationPageId && value.destinationPageId !== baseline.destinationPageId)) {
+                throw new Error("Pinned copy page identity changed");
+            }
+            return value;
+        };
+        const addedRoots = (value) => value.destinationRootIds.filter((id) => !baseline.destinationRootIds.includes(id));
+        const inventoryComplete = (value) => addedRoots(value).length === request.frameIds.length &&
+            baseline.destinationRootIds.every((id) => value.destinationRootIds.includes(id));
+        const pasteComplete = (value) => attempted &&
+            inventoryComplete(value) &&
+            pairs.length === request.frameIds.length &&
+            pairs.every((pair) => addedRoots(value).includes(pair.targetFrameId));
+        let pairs = [];
+        let placements = [];
+        const mappingPath = `${prefix}/mapping.json`;
+        try {
+            await artifactPath(root, mappingPath);
+            const saved = JSON.parse((await readProjectBytes(root, mappingPath, 1024 * 1024)).toString("utf8"));
+            if (saved.requestHash !== copyRequestHash(request) ||
+                !Array.isArray(saved.pairs) ||
+                saved.pairs.length !== request.frameIds.length ||
+                saved.pairs.some((pair, index) => !pair ||
+                    pair.sourceFrameId !== request.frameIds[index] ||
+                    typeof pair.targetFrameId !== "string") ||
+                new Set(saved.pairs.map((pair) => pair.targetFrameId)).size !==
+                    saved.pairs.length) {
+                throw new Error("Saved native copy mapping is invalid");
+            }
+            pairs = saved.pairs;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const calculatePlacements = () => {
+            let x = 0;
+            const y = Math.max(1000, baseline.destinationBounds.bottom + 160);
+            return pairs.map((pair) => {
+                const source = baseline.sourceFrames.find((frame) => frame.id === pair.sourceFrameId);
+                const placement = {
+                    id: pair.targetFrameId,
+                    x,
+                    y,
+                };
+                x += source.width + 160;
+                return placement;
+            });
+        };
+        const identifyPasted = async () => {
+            const value = await targetPreview();
+            if (!attempted || !inventoryComplete(value) || !value.destinationPageId) {
+                return value;
+            }
+            if (!pairs.length) {
+                const observed = await observedDestination(client, request.fileId, value.destinationPageId);
+                const ids = addedRoots(value);
+                if (observationHash([
+                    ...observed.selectionIds,
+                ].sort()) !==
+                    observationHash([
+                        ...ids,
+                    ].sort())) {
+                    throw new Error("Pasted selection does not uniquely identify the new boards; inspect without replay");
+                }
+                const targets = await captureCopyEvidence(client, root, request.fileId, value.destinationPageId, ids, `${prefix}/pasted-${randomUUID()}`, options.redact);
+                pairs = matchCopiedFrames(payload.sources, targets);
+                await saveArtifact(root, mappingPath, JSON.stringify({
+                    requestHash: copyRequestHash(request),
+                    pairs,
+                }), options.redact);
+            }
+            placements = calculatePlacements();
+            return value;
+        };
+        const arrangementState = async () => {
+            const value = await identifyPasted();
+            if (!value.destinationPageId || !pasteComplete(value)) {
+                return value;
+            }
+            const observed = await observedDestination(client, request.fileId, value.destinationPageId);
+            value.arranged = placements.every((placement) => observed.rootFrames.some((frame) => frame.id === placement.id &&
+                frame.x === placement.x &&
+                frame.y === placement.y &&
+                frame.copyRunId === runId));
+            return value;
+        };
+        const pageStep = {
+            key: "page",
+            label: "Prepare the release destination page",
+            signature: nativeCopyCreatePage(request.fileId, request.releaseVersion, runId).code,
+            inspect: targetPreview,
+            apply: async () => {
+                await readSource();
+                pageAttempted = true;
+                const result = await runSnippet(client, nativeCopyCreatePage(request.fileId, request.releaseVersion, runId), {
+                    effect: "write",
+                    retries: 0,
+                });
+                if (typeof result.pageId !== "string") {
+                    throw new Error("Created release page identity was not acknowledged");
+                }
+                rememberPage(client, {
+                    fileId: request.fileId,
+                    pageId: result.pageId,
+                });
+                return result;
+            },
+            verify: (value) => Boolean(value.destinationPageId) && value.destinationNamed !== false,
+            reconcile: (_before, value) => value.destinationPageId && value.destinationNamed !== false
+                ? "complete"
+                : pageAttempted && !value.destinationPageId
+                    ? "conflict"
+                    : "pending",
+        };
+        const pasteStep = {
+            key: "paste",
+            label: "Copy selected native boards and paste once",
+            signature: "native-clipboard-batch-v1-no-replay",
+            inspect: identifyPasted,
+            apply: async (value) => {
+                if (attempted ||
+                    !value.destinationPageId ||
+                    addedRoots(value).length ||
+                    !baseline.destinationRootIds.every((id) => value.destinationRootIds.includes(id))) {
+                    throw new Error("Paste is fenced or destination changed; inspect without replaying");
+                }
+                await readSource();
+                const clipboard = await options.clipboard();
+                try {
+                    await selectPage(client, {
+                        id: baseline.sourcePageId,
+                    });
+                    await runSnippet(client, nativeCopySelect(request.fileId, baseline.sourcePageId, request.frameIds), {
+                        effect: "write",
+                        retries: 0,
+                    });
+                    const selection = await observedDestination(client, request.fileId, baseline.sourcePageId);
+                    if (observationHash([
+                        ...selection.selectionIds,
+                    ].sort()) !==
+                        observationHash([
+                            ...request.frameIds,
+                        ].sort())) {
+                        throw new Error("Source board selection changed before copy");
+                    }
+                    await clipboard.copy(baseline.sourcePageId, request.frameIds);
+                    await selectPage(client, {
+                        id: value.destinationPageId,
+                    });
+                    await runSnippet(client, nativeCopySelect(request.fileId, value.destinationPageId, []), {
+                        effect: "write",
+                        retries: 0,
+                    });
+                    const destination = await targetPreview();
+                    if (observationHash(destination.destinationRootIds) !==
+                        observationHash(baseline.destinationRootIds)) {
+                        throw new Error("Destination changed before paste");
+                    }
+                    const empty = await observedDestination(client, request.fileId, value.destinationPageId);
+                    if (empty.selectionIds.length) {
+                        throw new Error("Destination selection changed before paste");
+                    }
+                    await atomicWriteFile(fencePath, JSON.stringify({
+                        schemaVersion: 1,
+                        runId,
+                        fileId: request.fileId,
+                        pageId: value.destinationPageId,
+                        requestHash: copyRequestHash(request),
+                    }));
+                    attempted = true;
+                    await clipboard.paste(value.destinationPageId);
+                    for (let poll = 0; poll < 25; poll++) {
+                        if (inventoryComplete(await targetPreview())) {
+                            return {
+                                dispatched: true,
+                            };
+                        }
+                        await (options.sleep ?? commandSleep)(200);
+                    }
+                    throw new Error("Paste acknowledgment did not establish new boards; reconcile without replay");
+                }
+                finally {
+                    await clipboard.close();
+                }
+            },
+            verify: pasteComplete,
+            reconcile: (_before, value) => pasteComplete(value)
+                ? "complete"
+                : attempted || addedRoots(value).length
+                    ? "conflict"
+                    : "pending",
+        };
+        const arrangeStep = {
+            key: "arrange",
+            label: "Identify and arrange only the new native copies",
+            signature: "native-copy-arrange-v1",
+            inspect: arrangementState,
+            apply: async (value) => {
+                if (!value.destinationPageId || !pasteComplete(value)) {
+                    throw new Error("Copied root inventory is incomplete");
+                }
+                placements = calculatePlacements();
+                await readSource();
+                await selectPage(client, {
+                    id: value.destinationPageId,
+                });
+                return runSnippet(client, nativeCopyArrange(request.fileId, value.destinationPageId, placements, runId), {
+                    effect: "write",
+                    retries: 0,
+                });
+            },
+            verify: (value) => pasteComplete(value) && value.arranged === true,
+            reconcile: (_before, value) => pasteComplete(value) ? (value.arranged === true ? "complete" : "pending") : "conflict",
+        };
+        let finalResult;
+        let receiptPersisted = false;
+        try {
+            await runJournaledSteps([
+                pageStep,
+                pasteStep,
+                arrangeStep,
+            ], {
+                root,
+                operation,
+                input: request,
+                payload,
+                runId,
+                resume: options.resume,
+                target: () => readJournalTarget(client),
+                coordinate: async (identity, target) => {
+                    const lease = await writeCoordinator(client, {
+                        root,
+                        operation,
+                        warn: options.onStep,
+                    })(identity, target);
+                    try {
+                        await assertNoConflictingRuns();
+                        return lease;
+                    }
+                    catch (error) {
+                        await lease.release();
+                        throw error;
+                    }
+                },
+                redact: options.redact,
+                onStep: options.onStep,
+                finalVerify: async () => {
+                    const destination = await arrangementState();
+                    if (!destination.destinationPageId ||
+                        !pasteComplete(destination) ||
+                        !destination.arranged) {
+                        return false;
+                    }
+                    const targets = await captureCopyEvidence(client, root, request.fileId, destination.destinationPageId, pairs.map((pair) => pair.targetFrameId), `${prefix}/target-${randomUUID()}`, options.redact);
+                    const verifiedPairs = matchCopiedFrames(payload.sources, targets);
+                    if (observationHash(verifiedPairs) !== observationHash(pairs)) {
+                        throw new Error("Copied identities changed before final readback");
+                    }
+                    const verification = compareCopyEvidence(payload.sources, targets, pairs);
+                    const originals = await captureCopyEvidence(client, root, request.fileId, baseline.sourcePageId, request.frameIds, `${prefix}/source-readback-${randomUUID()}`, options.redact);
+                    if (sourceEvidenceHash(originals) !== sourceEvidenceHash(payload.sources)) {
+                        throw new Error("Original boards changed during transfer; independent reconciliation is required");
+                    }
+                    await selectPage(client, {
+                        id: destination.destinationPageId,
+                    });
+                    finalResult = {
+                        schemaVersion: 1,
+                        kind: "native-release-copy",
+                        status: verification.nativeVerified && verification.pixelsMatch ? "copied" : "incomplete",
+                        preview: destination,
+                        runId,
+                        receiptPath: `${prefix}/receipt.json`,
+                        pairs,
+                        nativeVerified: verification.nativeVerified,
+                        pixelsMatch: verification.pixelsMatch,
+                        problems: verification.problems,
+                    };
+                    const receipt = JSON.stringify({
+                        ...finalResult,
+                        nodeMap: verification.nodeMap,
+                        sourceEvidence: payload.sources.map(({ inspection: _inspection, ...source }) => source),
+                        targetEvidence: targets.map(({ inspection: _inspection, ...target }) => target),
+                    }, null, 2);
+                    const receiptFile = await artifactPath(root, finalResult.receiptPath, true);
+                    if (options.redact && options.redact(receipt) !== receipt) {
+                        throw new Error("Copy receipt requires credential redaction");
+                    }
+                    await atomicWriteFile(receiptFile, `${receipt}\n`, {
+                        replace: true,
+                    });
+                    receiptPersisted = true;
+                    return verification.nativeVerified && verification.pixelsMatch;
+                },
+            });
+        }
+        catch (error) {
+            if (finalResult?.status === "incomplete" &&
+                receiptPersisted &&
+                error instanceof JournalRunError &&
+                error.outcome === "failed") {
+                return finalResult;
+            }
+            throw error;
+        }
+        if (!finalResult) {
+            throw new Error("Native copy final verification did not run");
+        }
+        return finalResult;
+    });
+}

package/dist/design-releases/index.d.ts

@@ -6,3 +6,4 @@ export { finalizeRelease } from "./finalize.js";
 export { checkRelease } from "./check.js";
 export { releaseContext } from "./context.js";
 export { validateDesignRelease, validateReleasePlan, hashDesignRelease, hashDesignRelease as releaseDesignHash, } from "./validation.js";
+export * from "./copy.js";

package/dist/design-releases/index.js

@@ -5,3 +5,4 @@ export { finalizeRelease } from "./finalize.js";
 export { checkRelease } from "./check.js";
 export { releaseContext } from "./context.js";
 export { validateDesignRelease, validateReleasePlan, hashDesignRelease, hashDesignRelease as releaseDesignHash, } from "./validation.js";
+export * from "./copy.js";

package/dist/errors.js

@@ -9,7 +9,7 @@ export const errorRemedies = Object.freeze({
     "mcp-unavailable": "Start the Penpot instance and check the MCP URL. Run `penpair probe` to see what answers.",
     "auth-rejected": "Penpot rejected the MCP key. Use the key from Account, Integrations, MCP Server.",
     "plugin-disconnected": "In the open Penpot file choose File, MCP Server, Connect, and keep that tab visible, then run the command again.",
-    "plugin-suspended": "The browser put the Penpot tab to sleep. Bring it to the foreground and keep it visible while a command runs. A suspended-tab error does not mean nothing was written: read the page before running a write again.",
+    "plugin-suspended": "The browser put the Penpot tab to sleep. Bring it to the foreground, or use penpair wake --debug-port PORT with a dedicated debugging browser, then run penpair doctor. Waking is temporary recovery. A suspended-tab error does not mean nothing was written: read the page and reconcile the run before explicitly replaying a write.",
     "tool-failed": "Penpot's tool reported a failure; the message above says what.",
     "snippet-too-large": "Split the snippet. Penpot's proxy refuses request bodies of about 110 KB, so snippets stay under 90 KB.",
 });

package/dist/instance/connection.d.ts

@@ -1,3 +1,4 @@
+import { type PluginHealth } from "../plugin-health.js";
 import { type ExternalConfig, type InstanceConfig, type ProjectConfig } from "./config.js";
 /** What Penpot itself, the connection and the checks need, whichever way Penpot is run. Nothing here knows about Docker. */
 export declare class LifecycleError extends Error {
@@ -18,6 +19,7 @@ export interface DoctorCheck extends Check {
         pageId?: string;
         apiVersion?: string;
         heartbeat?: "unknown";
+        pluginHealth?: PluginHealth;
     };
     remedy?: string;
     file?: {

package/dist/instance/connection.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { commandSignal, withCommandSignal } from "../command-result.js";
 import { redactEndpoint } from "../endpoint.js";
+import { pluginHealthFromError, responsivePluginHealth, } from "../plugin-health.js";
 import { isExternal, } from "./config.js";
 /** What Penpot itself, the connection and the checks need, whichever way Penpot is run. Nothing here knows about Docker. */
 export class LifecycleError extends Error {
@@ -105,7 +106,7 @@ export async function doctorEditor(config, options) {
             check: "editor and plugin",
             layer: "execution",
             ok: true,
-            detail: `Fresh read from file "${actual.file}"`,
+            detail: `Fresh read from file "${actual.file}"; heartbeat age unavailable; keep-alive unknown`,
             observedAt: new Date().toISOString(),
             durationMs: Date.now() - started,
             evidence: {
@@ -117,11 +118,16 @@ export async function doctorEditor(config, options) {
                     }
                     : {}),
                 heartbeat: "unknown",
+                pluginHealth: responsivePluginHealth(),
             },
         });
         out.push(fileIdentityCheck(config, actual));
     }
     catch (error) {
+        const pluginHealth = pluginHealthFromError(error);
+        const heartbeatDetail = pluginHealth.heartbeatAgeMs === null
+            ? "heartbeat age unavailable"
+            : `last heartbeat ${pluginHealth.heartbeatAgeMs / 1000}s ago (reported by upstream)`;
         if (!connected) {
             out.push({
                 check: "MCP transport",
@@ -136,10 +142,16 @@ export async function doctorEditor(config, options) {
             check: "editor and plugin",
             layer: "execution",
             ok: false,
-            detail: redactEndpoint(error instanceof Error ? error.message : String(error)),
+            detail: `${redactEndpoint(error instanceof Error ? error.message : String(error))}; ${heartbeatDetail}; keep-alive unknown`,
             observedAt: new Date().toISOString(),
             durationMs: Date.now() - started,
-            remedy: "Open the intended file, connect the MCP plugin and keep the editor responsive; rerun doctor for a fresh read.",
+            evidence: {
+                heartbeat: "unknown",
+                pluginHealth,
+            },
+            remedy: pluginHealth.state === "suspended"
+                ? "Bring the intended Penpot tab to the foreground, then rerun doctor for a fresh read. Reconcile any uncertain run before replaying a write."
+                : "Open the intended file, connect the MCP plugin and keep the editor responsive; rerun doctor for a fresh read.",
         });
     }
     finished = true;

package/dist/kit-source.js

@@ -225,7 +225,7 @@ const pp = (() => {
         try { return await settleLayout(async nativeMs => {
             if (penpot.currentFile.id !== fileId || penpot.currentPage.id !== pageId) throw new Error("Layout target changed between samples");
             return observeLayout(penpot, root, { nativeMs, maxNodes: options.maxNodes });
-        }, { timeoutMs: options.timeoutMs === undefined ? 10000 : options.timeoutMs, intervalMs: options.intervalMs === undefined ? 100 : options.intervalMs, strategy: options.strategy === undefined ? "auto" : options.strategy, sleep: wait }); }
+        }, { timeoutMs: options.timeoutMs === undefined ? 10000 : options.timeoutMs, intervalMs: options.intervalMs === undefined ? 100 : options.intervalMs, strategy: options.strategy === undefined ? "auto" : options.strategy, maxNodes: options.maxNodes, sleep: wait }); }
         catch (error) { return { stable: false, method: "unavailable", samples: 0, reason: String(error && error.message || error) }; }
     };
     const flush = async (options = {}) => {

package/dist/layout-policy.js

@@ -2,21 +2,26 @@ 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");
+ if (!Number.isInteger(options.maxNodes === undefined ? 10000 : options.maxNodes) || (options.maxNodes !== undefined && (options.maxNodes < 1 || options.maxNodes > 100000))) throw new Error("Invalid settling node budget");
+ const roots = Array.isArray(root) ? root : [root];
+ if (!roots.length || roots.some(shape => !shape)) throw new Error("layout target does not exist");
  const fileId = penpot.currentFile.id, pageId = penpot.currentPage.id;
  const validTarget = () => {
   if (penpot.currentFile.id !== fileId || penpot.currentPage.id !== pageId) throw new Error("Layout target changed while waiting");
-  if (root.id !== penpot.currentPage.root.id && typeof penpot.currentPage.getShapeById === "function" && !penpot.currentPage.getShapeById(root.id)) throw new Error("Layout target no longer exists");
+  for (const shape of roots) {
+   if (shape.id !== penpot.currentPage.root.id && typeof penpot.currentPage.getShapeById === "function" && !penpot.currentPage.getShapeById(shape.id)) throw new Error("Layout target no longer exists");
+  }
  };
- if (!root) throw new Error("layout target does not exist");
+
  let nativeOutcome = "skipped", nativeError;
- const target = typeof root.waitForLayoutUpdate === "function" ? root : penpot;
+ validTarget();
+ const nativeTargets = roots.every(shape => typeof shape.waitForLayoutUpdate === "function") ? roots : [penpot];
  if (options.nativeMs > 0) {
   nativeOutcome = "unsupported";
-  if (typeof target.waitForLayoutUpdate === "function") {
+  if (nativeTargets.every(target => typeof target.waitForLayoutUpdate === "function")) {
    let timer;
    try {
-    await Promise.race([target.waitForLayoutUpdate(options.nativeMs), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Native layout attempt timed out")), options.nativeMs); })]);
+    await Promise.race([Promise.all(nativeTargets.map(target => target.waitForLayoutUpdate(options.nativeMs))), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Native layout attempt timed out")), options.nativeMs); })]);
     nativeOutcome = "completed";
    } catch (error) { nativeOutcome = "failed"; nativeError = String(error && error.message || error); }
    finally { clearTimeout(timer); }
@@ -24,20 +29,25 @@ const observeLayout = async (penpot, root, options) => {
  }
  validTarget();
  // Keep hierarchy and sibling order as well as geometry; repeated IDs include cycles.
- const geometry = [], stack = [[root, null, 0]], seen = new Set();
+ const geometry = [], stack = roots.map(shape => [shape, null, 0]).reverse(), seen = new Set();
+ let truncated = false;
  while (stack.length) {
-  if (geometry.length >= (options.maxNodes || 10000)) throw new Error("Layout sample exceeded node budget");
+  if (geometry.length >= (options.maxNodes || 10000)) { truncated = true; break; }
   const [shape, parent, index] = stack.pop();
   if (!shape || typeof shape.id !== "string" || !shape.id || seen.has(shape.id) || ![shape.x, shape.y, shape.width, shape.height].every(Number.isFinite)) throw new Error("Malformed layout geometry or duplicate IDs");
   seen.add(shape.id);
   geometry.push([shape.id, shape.x, shape.y, shape.width, shape.height, parent, index]);
   const children = shape.children || [];
   if (!Array.isArray(children)) throw new Error("Malformed layout hierarchy");
-  if (geometry.length + stack.length + children.length > (options.maxNodes || 10000)) throw new Error("Layout sample exceeded node budget");
-  for (let index = children.length - 1; index >= 0; index--) stack.push([children[index], shape.id, index]);
+  const available = (options.maxNodes || 10000) - geometry.length;
+  if (stack.length + children.length > available) truncated = true;
+  // Only retain the bounded depth-first prefix; avoid allocating a page-sized traversal stack.
+  if (children.length >= available) stack.length = 0;
+  else if (stack.length > available - children.length) stack.splice(0, stack.length - (available - children.length));
+  for (let index = Math.min(children.length, available) - 1; index >= 0; index--) stack.push([children[index], shape.id, index]);
  }
  validTarget();
- return { ok: true, fileId, pageId, native: nativeOutcome === "completed", nativeOutcome, nativeError, geometry, truncated: false };
+ return { ok: true, fileId, pageId, native: nativeOutcome === "completed", nativeOutcome, nativeError, geometry, rootIds: roots.map(shape => shape.id), truncated };
 };
 `;
 export const layoutPolicySource = `${layoutObservationSource}\nconst settleLayout = ${settleLayout.toString()};`;

package/dist/layout-settling.d.ts

@@ -1,5 +1,6 @@
 import type { LayoutResult, LayoutStrategy } from "./layout.js";
 interface LayoutSettlingOptions {
+    maxNodes?: number;
     timeoutMs: number;
     intervalMs: number;
     strategy: LayoutStrategy;