@penpair/core 0.3.7 → 0.4.1

package/dist/image-evidence.js

@@ -0,0 +1,121 @@
+import { open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+export const maximumImageBytes = 64 * 1024 * 1024;
+function losslessWebpSize(bytes) {
+    const malformed = () => new Error("Malformed static lossless WebP evidence");
+    if (bytes.readUInt32LE(4) + 8 !== bytes.length) {
+        throw malformed();
+    }
+    let imageSize;
+    let canvasSize;
+    let offset = 12;
+    while (offset < bytes.length) {
+        if (offset + 8 > bytes.length) {
+            throw malformed();
+        }
+        const chunk = bytes.subarray(offset, offset + 4).toString("latin1");
+        const size = bytes.readUInt32LE(offset + 4);
+        const payload = offset + 8;
+        const end = payload + size;
+        const paddedEnd = end + (size % 2);
+        if (paddedEnd > bytes.length || (size % 2 !== 0 && bytes[end] !== 0)) {
+            throw malformed();
+        }
+        if (chunk === "VP8 " || chunk === "ANIM" || chunk === "ANMF" || chunk === "ALPH") {
+            throw new Error("Provider evidence must reference PNG or static lossless WebP bytes");
+        }
+        if (chunk === "VP8X") {
+            if (offset !== 12 ||
+                canvasSize ||
+                size !== 10 ||
+                (bytes[payload] & 0xc3) !== 0 ||
+                bytes.readUIntLE(payload + 1, 3) !== 0) {
+                throw malformed();
+            }
+            canvasSize = {
+                width: bytes.readUIntLE(payload + 4, 3) + 1,
+                height: bytes.readUIntLE(payload + 7, 3) + 1,
+            };
+        }
+        else if (chunk === "VP8L") {
+            if (imageSize || size <= 5 || bytes[payload] !== 0x2f) {
+                throw malformed();
+            }
+            const dimensions = bytes.readUInt32LE(payload + 1);
+            if (dimensions >>> 29 !== 0) {
+                throw malformed();
+            }
+            imageSize = {
+                width: (dimensions & 0x3fff) + 1,
+                height: ((dimensions >>> 14) & 0x3fff) + 1,
+            };
+        }
+        else if (offset === 12) {
+            throw malformed();
+        }
+        offset = paddedEnd;
+    }
+    if (!imageSize ||
+        (canvasSize && (canvasSize.width !== imageSize.width || canvasSize.height !== imageSize.height))) {
+        throw malformed();
+    }
+    return imageSize;
+}
+/** Header/container assurance only; this does not decode compressed pixels. */
+export function inspectImageEvidence(bytes) {
+    if (bytes.length > maximumImageBytes) {
+        throw new Error("Image exceeds 64 MiB");
+    }
+    if (bytes.length >= 24 &&
+        bytes.subarray(0, 8).toString("hex") === "89504e470d0a1a0a" &&
+        bytes.subarray(12, 16).toString("latin1") === "IHDR") {
+        const width = bytes.readUInt32BE(16);
+        const height = bytes.readUInt32BE(20);
+        if (width > 0 && height > 0) {
+            return {
+                format: "png",
+                width,
+                height,
+            };
+        }
+    }
+    else if (bytes.length >= 12 &&
+        bytes.subarray(0, 4).toString("latin1") === "RIFF" &&
+        bytes.subarray(8, 12).toString("latin1") === "WEBP") {
+        return {
+            format: "webp",
+            ...losslessWebpSize(bytes),
+        };
+    }
+    throw new Error("Provider evidence must reference PNG or static lossless WebP bytes");
+}
+export async function readImageEvidence(root, file) {
+    const input = await resolveProjectInput(root, file);
+    const handle = await open(input, "r");
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maximumImageBytes) {
+            throw new Error("Image exceeds 64 MiB or is not a regular file");
+        }
+        const buffer = Buffer.alloc(info.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+            if (bytesRead === 0) {
+                break;
+            }
+            length += bytesRead;
+        }
+        if (length > info.size) {
+            throw new Error("Image changed during bounded read");
+        }
+        const bytes = buffer.subarray(0, length);
+        return {
+            bytes,
+            ...inspectImageEvidence(bytes),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/index.d.ts

@@ -56,3 +56,8 @@ export * from "./project-status.js";
 export * from "./audit-rules.js";
 export * from "./credentials.js";
 export * from "./token-projection.js";
+export * from "./image-evidence.js";
+export * from "./image-codec.js";
+export * from "./maps/index.js";
+export * from "./map-penpot/index.js";
+export * from "./design-releases/index.js";

package/dist/index.js

@@ -55,3 +55,8 @@ export * from "./project-status.js";
 export * from "./audit-rules.js";
 export * from "./credentials.js";
 export * from "./token-projection.js";
+export * from "./image-evidence.js";
+export * from "./image-codec.js";
+export * from "./maps/index.js";
+export * from "./map-penpot/index.js";
+export * from "./design-releases/index.js";

package/dist/inspection.js

@@ -79,6 +79,7 @@ const clone = (value, unknowns, key) => {
   } catch { unknowns.push(key); return null; }
 };
 const read = (object,key,unknowns,label=key) => { try { return clone(object[key],unknowns,label); } catch { unknowns.push(label); return null; } };
+const optional = (object,key,unknowns,label=key) => { try { const value=object[key]; return value===undefined?null:clone(value,unknowns,label); } catch {unknowns.push(label);return null;} };
 const pick = (object,keys,unknowns,prefix) => Object.fromEntries(keys.map(key=>[key,read(object,key,unknowns,prefix+"."+key)]));
 let estimatedBytes = 1024;
 if (CFG.kind === "shape") {
@@ -97,11 +98,11 @@ if (CFG.kind === "shape") {
     if (item.depth <= CFG.depth) {
       const unknowns = [], row = {id:s.id,parentId:item.parentId,index:item.index,depth:item.depth,type:read(s,"type",unknowns),name:read(s,"name",unknowns),childIds:children.slice(0,CFG.maxNodes).map(c=>c.id),childrenTotal:children.length,unknowns};
       if (children.length > CFG.maxNodes) reasons.add("node-budget");
-      if (CFG.fields.includes("geometry")) row.geometry = pick(s,["x","y","width","height","rotation","hidden","blocked"],unknowns,"geometry");
-      if (CFG.fields.includes("text")) row.text = s.type === "text" ? {characters:read(s,"characters",unknowns),typography:pick(s,["fontId","fontFamily","fontVariantId","fontSize","fontWeight","fontStyle","lineHeight","letterSpacing","growType","direction","align","verticalAlign"],unknowns,"typography")} : null;
+      if (CFG.fields.includes("geometry")) row.geometry = pick(s,["x","y","width","height","rotation","hidden","blocked","flipX","flipY","proportionLock"],unknowns,"geometry");
+      if (CFG.fields.includes("text")) row.text = s.type === "text" ? {characters:read(s,"characters",unknowns),typography:pick(s,["fontId","fontFamily","fontVariantId","fontSize","fontWeight","fontStyle","lineHeight","letterSpacing","growType","direction","align","verticalAlign","textTransform","textDecoration"],unknowns,"typography")} : null;
       if (row.text && Object.values(row.text.typography).includes("mixed")) unknowns.push("text.mixedRangeStyles");
       if (CFG.fields.includes("layout")) {
-        row.layout = {};
+        row.layout = {constraints:pick(s,["constraintsHorizontal","constraintsVertical","fixedWhenScrolling"],unknowns,"layout.constraints")};
         for (const [key,keys] of [["flex",["dir","wrap","alignItems","alignContent","justifyContent","rowGap","columnGap","topPadding","rightPadding","bottomPadding","leftPadding","horizontalSizing","verticalSizing"]],["layoutChild",["absolute","zIndex","horizontalSizing","verticalSizing","alignSelf","topMargin","rightMargin","bottomMargin","leftMargin","minWidth","maxWidth","minHeight","maxHeight"]]]) {
           try { row.layout[key] = s[key] ? pick(s[key],keys,unknowns,"layout."+key) : null; } catch { row.layout[key]=null; unknowns.push("layout."+key); }
         }
@@ -111,10 +112,17 @@ if (CFG.kind === "shape") {
           if(grid)for(const key of ["rows","columns"])row.layout.grid[key]=(grid[key]||[]).map((track,index)=>pick(track,["type","value"],unknowns,"layout.grid."+key+"."+index));
         } catch {row.layout.grid=null;unknowns.push("layout.grid");}
         try {row.layout.cell=s.layoutCell?pick(s.layoutCell,["row","rowSpan","column","columnSpan","areaName","position"],unknowns,"layout.cell"):null;} catch {row.layout.cell=null;unknowns.push("layout.cell");}
-        row.layout.clipContent = read(s,"clipContent",unknowns,"layout.clipContent");
+        row.layout.clipContent = s.type === "board" ? read(s,"clipContent",unknowns,"layout.clipContent") : null;
+        row.layout.showInViewMode = s.type === "board" ? read(s,"showInViewMode",unknowns,"layout.showInViewMode") : null;
+        row.layout.boardSizing = s.type === "board" ? Object.fromEntries(["horizontalSizing","verticalSizing"].map(key=>[key,optional(s,key,unknowns,"layout.boardSizing."+key)])) : null;
       }
       if (CFG.fields.includes("tokens")) row.tokens = read(s,"tokens",unknowns);
-      if (CFG.fields.includes("style")) row.style = pick(s,["fills","strokes","shadows","opacity","blendMode","borderRadiusTopLeft","borderRadiusTopRight","borderRadiusBottomRight","borderRadiusBottomLeft"],unknowns,"style");
+      if (CFG.fields.includes("style")) {
+        row.style = pick(s,["fills","strokes","shadows","opacity","blendMode","borderRadiusTopLeft","borderRadiusTopRight","borderRadiusBottomRight","borderRadiusBottomLeft"],unknowns,"style");
+        for (const key of ["blur","backgroundBlur"]) {
+          row.style[key]=optional(s,key,unknowns,"style."+key);
+        }
+      }
       if (CFG.fields.includes("component")) {
         row.component = {};
         for (const key of ["isComponentInstance","isComponentMainInstance","isComponentCopyInstance","isComponentRoot"]) {

package/dist/instance/config-schema.d.ts

@@ -160,6 +160,10 @@ export declare const projectConfigSchema: {
             readonly type: "object";
             readonly required: readonly ["page", "root", "frames"];
             readonly properties: {
+                readonly format: {
+                    readonly enum: readonly ["png", "webp"];
+                    readonly description: "Format for new references; existing approved formats are preserved unless explicitly migrated.";
+                };
                 readonly page: {
                     readonly type: "string";
                     readonly minLength: 1;

package/dist/instance/config-schema.js

@@ -280,6 +280,13 @@ export const projectConfigSchema = {
                 "frames",
             ],
             properties: {
+                format: {
+                    enum: [
+                        "png",
+                        "webp",
+                    ],
+                    description: "Format for new references; existing approved formats are preserved unless explicitly migrated.",
+                },
                 page: {
                     type: "string",
                     minLength: 1,

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/map-penpot/content-validation.d.ts

@@ -0,0 +1,3 @@
+import type { MapDrawing } from "./types.js";
+/** Reject malformed content geometry before a publication can contact Penpot. */
+export declare function validateMapDrawingContent(drawing: MapDrawing): void;

package/dist/map-penpot/content-validation.js

@@ -0,0 +1,57 @@
+function text(value, maximum) {
+    return value === undefined || (typeof value === "string" && value.length <= maximum);
+}
+function box(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const bounds = value;
+    return ([
+        "x",
+        "y",
+        "width",
+        "height",
+    ].every((key) => Number.isFinite(bounds[key])) &&
+        Number(bounds.x) >= 0 &&
+        Number(bounds.y) >= 0 &&
+        Number(bounds.width) >= 64 &&
+        Number(bounds.height) > 0);
+}
+/** Reject malformed content geometry before a publication can contact Penpot. */
+export function validateMapDrawingContent(drawing) {
+    if (!text(drawing.goal, 8000) ||
+        !text(drawing.summary, 240) ||
+        !text(drawing.description, 8000)) {
+        throw new Error("Map descriptions exceed their supported text budgets");
+    }
+    if (drawing.header &&
+        (!box(drawing.header.titleBox) ||
+            (drawing.header.summaryBox !== undefined && !box(drawing.header.summaryBox)) ||
+            !Number.isFinite(drawing.header.legendY) ||
+            drawing.header.legendY < 0 ||
+            !Number.isFinite(drawing.header.height) ||
+            drawing.header.height <= 0)) {
+        throw new Error("Map header requires finite positive geometry");
+    }
+    if (drawing.annotations === undefined) {
+        return;
+    }
+    const nodeIds = new Set(drawing.nodes.map((node) => node.id));
+    if (!Array.isArray(drawing.annotations) ||
+        drawing.annotations.length > 1001 ||
+        new Set(drawing.annotations.map((annotation) => annotation?.id)).size !==
+            drawing.annotations.length ||
+        drawing.annotations.some((annotation) => !annotation ||
+            typeof annotation.id !== "string" ||
+            !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/.test(annotation.id) ||
+            !box(annotation) ||
+            (annotation.nodeId !== undefined && !nodeIds.has(annotation.nodeId)) ||
+            typeof annotation.title !== "string" ||
+            !annotation.title.trim() ||
+            annotation.title.length > 4000 ||
+            !text(annotation.goal, 8000) ||
+            !text(annotation.summary, 240) ||
+            !text(annotation.description, annotation.nodeId ? 4000 : 8000))) {
+        throw new Error("Map annotations require unique identities, bounded text and finite geometry");
+    }
+}

package/dist/map-penpot/content.d.ts

@@ -0,0 +1,22 @@
+import type { MapDrawing, ProjectionShape } from "./types.js";
+export declare const nativeMapRoles: readonly ["node", "label", "edge", "edge-label", "title", "badge", "legend", "map-summary", "map-full-summary", "map-goal", "map-description", "summary", "full-label", "full-summary", "description", "annotation-panel", "annotation-id", "annotation-heading", "icon-well", "icon", "port-in", "port-out"];
+export interface NativeMapTextEntry {
+    role: ProjectionShape["role"];
+    logicalId: string;
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontSize: number;
+    color: string;
+    strong?: boolean;
+    semantic?: {
+        scope: "map" | "node";
+        field: "title" | "goal" | "label" | "summary" | "description";
+        nodeId?: string;
+        compact?: boolean;
+    };
+}
+export declare function nativeMapTextEntries(drawing: MapDrawing): NativeMapTextEntry[];
+export declare function nativeMapShapeKeys(drawing: MapDrawing): Set<string>;