@penpair/core 0.4.0 → 0.4.1

package/dist/adapters.d.ts

@@ -51,7 +51,7 @@ export interface Adapter {
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export declare const defineAdapter: <T extends Adapter>(adapter: T) => T;
 /** The commands of the core itself; an adapter cannot take one of these names. */
-export declare const reservedCommands: readonly ["journey-map", "integration-map", "design-release", "formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
+export declare const reservedCommands: readonly ["journey-map", "integration-map", "design-release", "formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "wake", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
 export interface LoadedAdapters {
     adapters: Adapter[];
     problems: string[];

package/dist/adapters.js

@@ -38,6 +38,7 @@ export const reservedCommands = [
     "open",
     "status",
     "doctor",
+    "wake",
     "backup",
     "restore",
     "baselines",

package/dist/browser-wake.d.ts

@@ -0,0 +1,22 @@
+export interface BrowserTargetOptions {
+    origin: string;
+    fileId: string;
+    port: number;
+    timeoutMs?: number;
+    allowLoopbackAlias?: boolean;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}
+export interface BrowserWakeResult {
+    activated: true;
+    targetId: string;
+    keepAlive: "none";
+}
+export interface BrowserInspectionResult {
+    targetId: string;
+    keepAlive: "unknown";
+}
+/** Activate only the existing page for the pinned file; never reload or evaluate page code. */
+export declare function wakeBrowserTarget(options: BrowserTargetOptions): Promise<BrowserWakeResult>;
+/** Read debugging metadata only; a listed tab does not establish plugin readiness or keep-alive. */
+export declare function inspectBrowserTarget(options: BrowserTargetOptions): Promise<BrowserInspectionResult>;

package/dist/browser-wake.js

@@ -0,0 +1,241 @@
+const maxTargetBytes = 1024 * 1024;
+const maxTargetCount = 1000;
+/** Activate only the existing page for the pinned file; never reload or evaluate page code. */
+export async function wakeBrowserTarget(options) {
+    return withBrowserDeadline(options, async (request) => {
+        const targetId = await findBrowserTarget(request);
+        const response = await browserRequest(request, `/json/activate/${encodeURIComponent(targetId)}`);
+        void response.body?.cancel().catch(() => undefined);
+        request.signal.throwIfAborted();
+        return {
+            activated: true,
+            targetId,
+            keepAlive: "none",
+        };
+    });
+}
+/** Read debugging metadata only; a listed tab does not establish plugin readiness or keep-alive. */
+export async function inspectBrowserTarget(options) {
+    return withBrowserDeadline(options, async (request) => ({
+        targetId: await findBrowserTarget(request),
+        keepAlive: "unknown",
+    }));
+}
+async function withBrowserDeadline(options, work) {
+    const origin = validateBrowserOptions(options);
+    if (options.signal?.aborted) {
+        throw new Error("Browser debugging cancelled");
+    }
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? 5000;
+    let timedOut = false;
+    const externalAbort = () => controller.abort();
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    options.signal?.addEventListener("abort", externalAbort, {
+        once: true,
+    });
+    let abort = () => undefined;
+    const interrupted = new Promise((_resolve, reject) => {
+        abort = () => reject(new Error(timedOut ? "Browser debugging deadline exceeded" : "Browser debugging cancelled"));
+        controller.signal.addEventListener("abort", abort, {
+            once: true,
+        });
+    });
+    try {
+        if (options.signal?.aborted) {
+            controller.abort();
+        }
+        controller.signal.throwIfAborted();
+        return await Promise.race([
+            interrupted,
+            work({
+                origin,
+                fileId: options.fileId,
+                allowLoopbackAlias: options.allowLoopbackAlias === true,
+                endpoint: `http://127.0.0.1:${options.port}`,
+                fetch: options.fetch ?? fetch,
+                signal: controller.signal,
+            }),
+        ]);
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new Error(timedOut ? "Browser debugging deadline exceeded" : "Browser debugging cancelled");
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", externalAbort);
+        controller.signal.removeEventListener("abort", abort);
+    }
+}
+function validateBrowserOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+        throw new Error("Browser debugging port must be an integer from 1 to 65535");
+    }
+    const timeoutMs = options.timeoutMs ?? 5000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 30000) {
+        throw new Error("Browser debugging timeout must be an integer from 1000 to 30000 ms");
+    }
+    if (typeof options.fileId !== "string" ||
+        !options.fileId.trim() ||
+        options.fileId.length > 256 ||
+        /[\u0000-\u0020\u007f]/.test(options.fileId)) {
+        throw new Error("Browser activation requires a pinned file ID");
+    }
+    let origin;
+    try {
+        origin = new URL(options.origin);
+    }
+    catch {
+        throw new Error("Browser activation requires a valid Penpot origin");
+    }
+    if (![
+        "http:",
+        "https:",
+    ].includes(origin.protocol) ||
+        origin.username ||
+        origin.password ||
+        origin.pathname !== "/" ||
+        origin.search ||
+        origin.hash) {
+        throw new Error("Browser activation requires a Penpot origin without credentials, path or query");
+    }
+    if (options.allowLoopbackAlias && !isHttpLoopback(origin)) {
+        throw new Error("Browser loopback aliases require an HTTP localhost or 127.0.0.1 origin");
+    }
+    return origin.origin;
+}
+async function browserRequest(request, path) {
+    request.signal.throwIfAborted();
+    let response;
+    try {
+        response = await request.fetch(`${request.endpoint}${path}`, {
+            method: "GET",
+            redirect: "error",
+            signal: request.signal,
+        });
+    }
+    catch {
+        throw new Error("Cannot reach the local browser debugging endpoint; start a dedicated browser with a loopback debugging port");
+    }
+    request.signal.throwIfAborted();
+    if (!response.ok || response.redirected) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new Error("The local browser debugging endpoint refused the request");
+    }
+    return response;
+}
+async function findBrowserTarget(request) {
+    const response = await browserRequest(request, "/json/list");
+    const text = await readTargetList(response);
+    request.signal.throwIfAborted();
+    let targets;
+    try {
+        targets = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Invalid browser debugging target list");
+    }
+    if (!Array.isArray(targets) ||
+        targets.length > maxTargetCount ||
+        !targets.every(isBrowserTarget)) {
+        throw new Error("Invalid browser debugging target list");
+    }
+    const matching = targets.filter((target) => target.type === "page" && matchesFile(target.url, request));
+    if (matching.length !== 1) {
+        throw new Error(matching.length === 0
+            ? "No browser page matches the project's Penpot origin and pinned file ID"
+            : "Multiple browser pages match the pinned file; close duplicate tabs before waking");
+    }
+    const targetId = matching[0].id;
+    if (!/^[A-Za-z0-9_-]{1,256}$/.test(targetId)) {
+        throw new Error("Invalid browser debugging target ID");
+    }
+    return targetId;
+}
+function isBrowserTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const target = value;
+    return (typeof target.id === "string" &&
+        typeof target.type === "string" &&
+        typeof target.url === "string");
+}
+function isHttpLoopback(url) {
+    return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+function matchesOrigin(target, request) {
+    if (target.origin === request.origin) {
+        return true;
+    }
+    if (!request.allowLoopbackAlias || !isHttpLoopback(target)) {
+        return false;
+    }
+    const expected = new URL(request.origin);
+    return isHttpLoopback(expected) && target.port === expected.port;
+}
+function matchesFile(targetUrl, request) {
+    let url;
+    try {
+        url = new URL(targetUrl);
+    }
+    catch {
+        return false;
+    }
+    if (!matchesOrigin(url, request) || url.username || url.password) {
+        return false;
+    }
+    const hashRoute = url.hash.slice(1);
+    const hashQuery = hashRoute.indexOf("?");
+    const parameters = hashQuery >= 0 && hashRoute.slice(0, hashQuery) === "/workspace"
+        ? new URLSearchParams(hashRoute.slice(hashQuery + 1))
+        : url.pathname === "/workspace" && !url.hash
+            ? url.searchParams
+            : undefined;
+    const fileIds = parameters?.getAll("file-id");
+    return fileIds?.length === 1 && fileIds[0] === request.fileId;
+}
+async function readTargetList(response) {
+    const declaredBytes = Number(response.headers.get("content-length"));
+    if (declaredBytes > maxTargetBytes) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new Error("Browser debugging target list exceeds the size limit");
+    }
+    if (!response.body) {
+        throw new Error("Invalid browser debugging target list");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                break;
+            }
+            bytes += next.value.byteLength;
+            if (bytes > maxTargetBytes) {
+                throw new Error("Browser debugging target list exceeds the size limit");
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        void reader.cancel().catch(() => undefined);
+        if (error instanceof Error &&
+            error.message === "Browser debugging target list exceeds the size limit") {
+            throw error;
+        }
+        throw new Error("Cannot read browser debugging target list");
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, bytes).toString("utf8");
+}

package/dist/cli-main.js

@@ -1,5 +1,7 @@
 import { auditDesignRules } from "./audit-rules.js";
 import { projectStatus, projectFileUrl, openProject } from "./project-status.js";
+import { wakeBrowserTarget } from "./browser-wake.js";
+import { pluginHealthFromError } from "./plugin-health.js";
 import { artifactSchemas, migrateProjectConfig } from "./formats.js";
 import { importDtcg, exportDtcg } from "./portable-tokens.js";
 import { captureStructuralSnapshot, writeStructuralSnapshot, readStructuralSnapshot, diffStructuralSnapshots, renderStructuralDiff, } from "./structure-snapshot.js";
@@ -44,7 +46,7 @@ import { askHidden, askLine, openInBrowser } from "./instance/tty.js";
 import { validateSkillAgent } from "./skill-hosts.js";
 import { loadAdapters, readRawConfig, reservedCommands, } from "./adapters.js";
 import { requireLocalProfile } from "./local-profile.js";
-import { assertEndpointIsInstance, doctorExternal, LifecycleError, } from "./instance/connection.js";
+import { assertEndpointIsInstance, doctorExternal, doctorEditor, frontendUrl, LifecycleError, } from "./instance/connection.js";
 import { nodeRunner } from "./instance/runner.js";
 import { version } from "./version.js";
 import { guardFile } from "./file-guard.js";
@@ -71,6 +73,7 @@ Connect / diagnose:
   penpair config check [--json]                        validate configuration offline
   penpair config schema                               print its JSON Schema
   penpair doctor [--json] [--timeout-ms 5000]           origin, transport, fresh editor read and file pin (1000–30000 ms)
+  penpair wake --debug-port 9222 [--json]              activate the pinned browser tab, then verify the editor; no reload or replay
   penpair status [--adapters]                          observed project health and optional companion readiness
   penpair open [--print]                              open the pinned public file URL, or print it
   penpair probe [--integrity]                          observed APIs and limits
@@ -84,7 +87,7 @@ Build:
   penpair snippets / snippets check                    list or validate configured trusted scripts
   penpair tokens add-set|set|remove|promote             inspect token edits; --apply writes once
   penpair archive --page PAGE --name Archive --keep PREFIX [--apply]
-  (run-file/export/shots accept --layout auto|native|geometry; default auto)
+  (run-file/run/archive/token edits/export/shots accept --layout auto|native|geometry, repeatable --layout-root ID, --layout-max-nodes 1..100000)
   (journaled writes accept --resume RUN_ID --apply, --checkpoint and --trace)
 Inspect / spec:
   penpair pages                                       file identity, revision and pages
@@ -235,9 +238,19 @@ async function main(argv, cli) {
             "timeout-ms": {
                 type: "string",
             },
+            "debug-port": {
+                type: "string",
+            },
             layout: {
                 type: "string",
             },
+            "layout-root": {
+                type: "string",
+                multiple: true,
+            },
+            "layout-max-nodes": {
+                type: "string",
+            },
             page: {
                 type: "string",
             },
@@ -432,6 +445,11 @@ async function main(argv, cli) {
         "max-total-bytes",
         "capture-timeout-ms",
     ];
+    const layoutFlags = [
+        "layout",
+        "layout-root",
+        "layout-max-nodes",
+    ];
     const flags = {
         formats: [
             "out",
@@ -486,6 +504,7 @@ async function main(argv, cli) {
                     "theme",
                 ]
                 : [
+                    ...layoutFlags,
                     "type",
                     "value",
                     "description",
@@ -499,16 +518,17 @@ async function main(argv, cli) {
             "page",
             "scale",
             "name",
-            "layout",
+            ...layoutFlags,
         ],
         shots: [
             "page",
             "prefix",
             "out",
             "scale",
-            "layout",
+            ...layoutFlags,
         ],
         archive: [
+            ...layoutFlags,
             "page",
             "name",
             "keep",
@@ -527,7 +547,7 @@ async function main(argv, cli) {
             "include",
         ],
         "run-file": [
-            "layout",
+            ...layoutFlags,
             "include",
             "inspect",
             "readback",
@@ -540,6 +560,7 @@ async function main(argv, cli) {
             "trace",
         ],
         run: [
+            ...layoutFlags,
             "builtins-only",
             "param",
             "apply",
@@ -594,6 +615,10 @@ async function main(argv, cli) {
         doctor: [
             "timeout-ms",
         ],
+        wake: [
+            "debug-port",
+            "timeout-ms",
+        ],
         up: [],
         down: [],
         open: [
@@ -710,12 +735,31 @@ async function main(argv, cli) {
         ].includes(values.layout)) {
         throw new CommandArgumentError("--layout must be auto, native or geometry");
     }
-    if (command === "doctor" &&
+    if (values["layout-max-nodes"] !== undefined &&
+        (!/^\d+$/.test(values["layout-max-nodes"]) ||
+            Number(values["layout-max-nodes"]) < 1 ||
+            Number(values["layout-max-nodes"]) > 100000)) {
+        throw new CommandArgumentError("--layout-max-nodes must be an integer from 1 to 100000");
+    }
+    if (values["layout-root"] &&
+        (values["layout-root"].some((id) => !id.trim()) ||
+            new Set(values["layout-root"]).size !== values["layout-root"].length)) {
+        throw new CommandArgumentError("--layout-root must name distinct nonempty shape IDs");
+    }
+    if ((command === "doctor" || command === "wake") &&
         values["timeout-ms"] !== undefined &&
         (!/^\d+$/.test(values["timeout-ms"]) ||
             Number(values["timeout-ms"]) < 1000 ||
             Number(values["timeout-ms"]) > 30000)) {
-        throw new CommandArgumentError("doctor --timeout-ms must be an integer from 1000 to 30000");
+        throw new CommandArgumentError(`${command} --timeout-ms must be an integer from 1000 to 30000`);
+    }
+    if (command === "wake" &&
+        (rest.length ||
+            !values["debug-port"] ||
+            !/^\d+$/.test(values["debug-port"]) ||
+            Number(values["debug-port"]) < 1 ||
+            Number(values["debug-port"]) > 65535)) {
+        throw new CommandArgumentError("wake requires --debug-port with an integer from 1 to 65535");
     }
     let tokenEdit;
     if (command === "tokens" &&
@@ -1358,7 +1402,11 @@ async function main(argv, cli) {
                     {
                         check: "editor and plugin",
                         ok: false,
-                        detail: "No resolved project credential/connection; editor identity was not observed",
+                        detail: "No resolved project credential/connection; editor identity was not observed; heartbeat age unavailable; keep-alive unknown",
+                        evidence: {
+                            heartbeat: "unknown",
+                            pluginHealth: pluginHealthFromError(undefined),
+                        },
                         remedy: "Configure the private credential source, connect the intended editor, then rerun doctor.",
                     },
                 ]
@@ -1392,6 +1440,57 @@ async function main(argv, cli) {
         }
         return ok ? 0 : 1;
     }
+    if (command === "wake") {
+        const config = await loadCommandConfig(root);
+        if (!config.file?.id) {
+            throw new CommandArgumentError("Pin the owner-confirmed file before waking its browser tab");
+        }
+        const mcp = await mcpProbeFor();
+        if (!mcp) {
+            throw new Error("Configure the project's MCP connection before waking and verifying its tab");
+        }
+        assertEndpointIsInstance({
+            origin: mcp.origin,
+            source: "project connection",
+        }, config);
+        const timeoutMs = Number(values["timeout-ms"] ?? 5000);
+        const started = Date.now();
+        const activation = await wakeBrowserTarget({
+            origin: isExternal(config) ? config.profile.origin : frontendUrl(config),
+            allowLoopbackAlias: !isExternal(config),
+            fileId: config.file.id,
+            port: Number(values["debug-port"]),
+            timeoutMs,
+            signal: commandSignal(),
+        });
+        const remaining = timeoutMs - (Date.now() - started);
+        const checks = remaining > 0
+            ? await doctorEditor(config, {
+                mcp,
+                timeoutMs: remaining,
+            })
+            : [
+                {
+                    check: "editor and plugin",
+                    ok: false,
+                    detail: "Tab activation exhausted the verification deadline",
+                },
+            ];
+        const ready = checks.length > 0 && checks.every((check) => check.ok);
+        output.result({
+            ...activation,
+            ready,
+            checks,
+        });
+        if (!values.json) {
+            output.log("Browser activation acknowledged; sustained keep-alive: none. No write was replayed.");
+            for (const check of checks) {
+                output.log(`${check.ok ? "ok  " : "FAIL"} ${check.check}: ${check.detail}`);
+            }
+            output.log("Reconcile any uncertain run independently before explicitly resuming it.");
+        }
+        return ready ? 0 : 1;
+    }
     if (command === "open") {
         if (rest.length) {
             throw new CommandArgumentError("open accepts only --print for a URL preview");
@@ -1683,10 +1782,24 @@ async function main(argv, cli) {
     const client = await guarded();
     commandRedactor(endpointRedactor(endpoint));
     const options = {
-        ...(values.layout
+        ...(values.layout || values["layout-root"] || values["layout-max-nodes"]
             ? {
                 layout: {
-                    strategy: values.layout,
+                    ...(values.layout
+                        ? {
+                            strategy: values.layout,
+                        }
+                        : {}),
+                    ...(values["layout-root"]
+                        ? {
+                            shapeIds: values["layout-root"],
+                        }
+                        : {}),
+                    ...(values["layout-max-nodes"]
+                        ? {
+                            maxNodes: Number(values["layout-max-nodes"]),
+                        }
+                        : {}),
                 },
             }
             : {}),
@@ -2391,15 +2504,16 @@ async function runCliBound(argv, options = {}) {
         ...argv,
     ];
     const timeoutAt = args.indexOf("--timeout-ms");
+    const boundedDiagnosis = args[0] === "doctor" || args[0] === "wake";
     let invalidTimeout = false;
     if (timeoutAt !== -1) {
         const milliseconds = Number(args[timeoutAt + 1]);
         invalidTimeout =
             !Number.isInteger(milliseconds) ||
-                milliseconds < (args[0] === "doctor" ? 1000 : 1) ||
-                milliseconds > (args[0] === "doctor" ? 30000 : 1_800_000) ||
+                milliseconds < (boundedDiagnosis ? 1000 : 1) ||
+                milliseconds > (boundedDiagnosis ? 30000 : 1_800_000) ||
                 args.indexOf("--timeout-ms", timeoutAt + 1) !== -1;
-        if (args[0] !== "doctor") {
+        if (!boundedDiagnosis) {
             args.splice(timeoutAt, 2);
         }
         if (!invalidTimeout) {
@@ -2426,8 +2540,8 @@ async function runCliBound(argv, options = {}) {
     try {
         if (invalidTimeout) {
             const result = await collectCommand(args[0] ?? "help", async () => {
-                throw new Error(args[0] === "doctor"
-                    ? "doctor --timeout-ms must be one integer from 1000 to 30000"
+                throw new Error(boundedDiagnosis
+                    ? `${args[0]} --timeout-ms must be one integer from 1000 to 30000`
                     : "--timeout-ms must be one integer from 1 to 1800000");
             });
             if (json) {

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;

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/plugin-health.d.ts

@@ -0,0 +1,13 @@
+export interface PluginHealth {
+    state: "responsive" | "suspended" | "unknown";
+    heartbeatAgeMs: number | null;
+    heartbeatSource: "upstream-error" | "unavailable";
+    keepAlive: {
+        method: "unknown";
+        verified: false;
+    };
+}
+/** Fresh execution proves responsiveness, not the plugin's heartbeat time or browser policy. */
+export declare function responsivePluginHealth(): PluginHealth;
+/** Upstream error text is the only heartbeat telemetry exposed by the current connection. */
+export declare function pluginHealthFromError(error: unknown): PluginHealth;

package/dist/plugin-health.js

@@ -0,0 +1,39 @@
+function health(state, heartbeatAgeMs) {
+    return {
+        state,
+        heartbeatAgeMs,
+        heartbeatSource: heartbeatAgeMs === null ? "unavailable" : "upstream-error",
+        keepAlive: {
+            method: "unknown",
+            verified: false,
+        },
+    };
+}
+/** Fresh execution proves responsiveness, not the plugin's heartbeat time or browser policy. */
+export function responsivePluginHealth() {
+    return health("responsive", null);
+}
+/** Upstream error text is the only heartbeat telemetry exposed by the current connection. */
+export function pluginHealthFromError(error) {
+    const message = error instanceof Error
+        ? error.message.slice(0, 8192)
+        : typeof error === "string"
+            ? error.slice(0, 8192)
+            : "";
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    const suspended = code === "plugin-suspended" || /\bsuspended\b|\bno heartbeat\b/i.test(message);
+    if (!suspended) {
+        return health("unknown", null);
+    }
+    const duration = /\bno heartbeat\s+for\s+([^\s,)]+?)\s*(milliseconds?|ms|seconds?|s)\b/i.exec(message);
+    if (!duration || !/^\d+(?:\.\d+)?$/.test(duration[1])) {
+        return health("suspended", null);
+    }
+    const value = Number(duration[1]);
+    const heartbeatAgeMs = value * (/^(?:ms|milliseconds?)$/i.test(duration[2]) ? 1 : 1000);
+    return health("suspended", Number.isFinite(heartbeatAgeMs) &&
+        heartbeatAgeMs >= 0 &&
+        heartbeatAgeMs <= Number.MAX_SAFE_INTEGER
+        ? heartbeatAgeMs
+        : null);
+}

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.4.0";
+export declare const version = "0.4.1";

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.4.0";
+export const version = "0.4.1";

package/package.json

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