@penpair/core 0.2.0 → 0.3.1

package/dist/kit.js

@@ -3,88 +3,156 @@ import { coreKitSource } from "./kit-source.js";
 import { compiles, snippet } from "./snippet.js";
 import { loadAdapters } from "./adapters.js";
 import { loadOptionalConfig } from "./instance/config.js";
-export const coreKit = { include: "@kit", source: coreKitSource, recipes: [{ name: "hello-card", description: "A neutral text-in-board example, with explicit token styles" }] };
+export const coreKit = {
+    include: "@kit",
+    source: coreKitSource,
+    recipes: [
+        {
+            name: "hello-card",
+            description: "A neutral text-in-board example, with explicit token styles",
+        },
+    ],
+};
 /** Plain JavaScript to concatenate into a reviewed plugin body; defines the pp namespace. */
 export const kit = () => coreKitSource;
 export function checkKits(kits) {
-    const problems = [], names = new Set(), recipeNames = new Set();
+    const problems = [];
+    const names = new Set();
+    const recipeNames = new Set();
     const sources = kits.map((value, index) => {
-        if (!value || typeof value !== "object" || typeof value.include !== "string" || typeof value.source !== "string") {
+        if (!value ||
+            typeof value !== "object" ||
+            typeof value.include !== "string" ||
+            typeof value.source !== "string") {
             problems.push("Malformed kit at index " + index);
-            return { include: "invalid", bytes: 0, sha256: "" };
+            return {
+                include: "invalid",
+                bytes: 0,
+                sha256: "",
+            };
         }
-        if (!/^@[a-z][a-z0-9-]*$/.test(value.include) || names.has(value.include))
+        if (!/^@[a-z][a-z0-9-]*$/.test(value.include) || names.has(value.include)) {
             problems.push("Invalid or duplicate kit include: " + value.include);
-        if (value.requires !== undefined && (!Array.isArray(value.requires) || value.requires.some(name => typeof name !== "string")))
+        }
+        if (value.requires !== undefined &&
+            (!Array.isArray(value.requires) || value.requires.some((name) => typeof name !== "string"))) {
             problems.push("Invalid kit dependencies: " + value.include);
-        else
-            for (const dependency of value.requires ?? [])
-                if (!names.has(dependency))
+        }
+        else {
+            for (const dependency of value.requires ?? []) {
+                if (!names.has(dependency)) {
                     problems.push(`${value.include} requires earlier include ${dependency}`);
+                }
+            }
+        }
         names.add(value.include);
-        if (!value.source.startsWith("// penpair: read\n"))
+        if (!value.source.startsWith("// penpair: read\n")) {
             problems.push(`${value.include} must declare read-only top-level inclusion`);
+        }
         const bytes = Buffer.byteLength(value.source);
-        if (bytes > 32768)
+        if (bytes > 32768) {
             problems.push(`${value.include} exceeds the 32 KiB source budget`);
+        }
         const error = compiles(value.source);
-        if (error)
+        if (error) {
             problems.push(`${value.include}: ${error}`);
-        if (!Array.isArray(value.recipes))
+        }
+        if (!Array.isArray(value.recipes)) {
             problems.push(`${value.include} has invalid recipe metadata`);
-        else
+        }
+        else {
             for (const recipe of value.recipes) {
-                if (!recipe || typeof recipe.name !== "string" || !/^[a-z][a-z0-9-]*$/.test(recipe.name) || typeof recipe.description !== "string")
+                if (!recipe ||
+                    typeof recipe.name !== "string" ||
+                    !/^[a-z][a-z0-9-]*$/.test(recipe.name) ||
+                    typeof recipe.description !== "string") {
                     problems.push(`${value.include} has invalid recipe metadata`);
-                else if (recipeNames.has(recipe.name))
+                }
+                else if (recipeNames.has(recipe.name)) {
                     problems.push("Duplicate recipe: " + recipe.name);
-                else
+                }
+                else {
                     recipeNames.add(recipe.name);
+                }
             }
-        return { include: value.include, bytes, sha256: createHash("sha256").update(value.source).digest("hex") };
+        }
+        return {
+            include: value.include,
+            bytes,
+            sha256: createHash("sha256").update(value.source).digest("hex"),
+        };
     });
     let bytes = sources.reduce((sum, source) => sum + source.bytes, 0);
     try {
-        const combined = snippet("kit-check", kits.filter(value => value && typeof value.source === "string").map(value => value.source).join("\n") + "\nreturn {ok:true};");
+        const combined = snippet("kit-check", kits
+            .filter((value) => value && typeof value.source === "string")
+            .map((value) => value.source)
+            .join("\n") + "\nreturn {ok:true};");
         bytes = Buffer.byteLength(combined.code);
         const error = compiles(combined.code);
-        if (error)
+        if (error) {
             problems.push(error);
+        }
     }
     catch (error) {
         problems.push(String(error.message));
     }
-    if (bytes > 49152)
+    if (bytes > 49152) {
         problems.push("Combined kit exceeds the 48 KiB budget reserved before project code");
-    return { valid: problems.length === 0, bytes, sources, problems };
+    }
+    return {
+        valid: problems.length === 0,
+        bytes,
+        sources,
+        problems,
+    };
 }
 /** Adapter imports happen only when an explicitly requested alias cannot be supplied by the core. */
-export async function loadKits(root, includes = ["@kit"]) {
+export async function loadKits(root, includes = [
+    "@kit",
+]) {
     const config = await loadOptionalConfig(root);
-    if (includes.length > 20 || new Set(includes).size !== includes.length)
+    if (includes.length > 20 || new Set(includes).size !== includes.length) {
         throw new Error("Use at most 20 distinct kit includes");
-    const available = new Map([["@kit", coreKit]]);
-    if (includes.some(name => name !== "@kit")) {
+    }
+    const available = new Map([
+        [
+            "@kit",
+            coreKit,
+        ],
+    ]);
+    if (includes.some((name) => name !== "@kit")) {
         const loaded = await loadAdapters(root, config?.adapters);
         for (const adapter of loaded.adapters) {
-            if (adapter.kits !== undefined && !Array.isArray(adapter.kits))
+            if (adapter.kits !== undefined && !Array.isArray(adapter.kits)) {
                 throw new Error("Adapter kits must be an array: " + adapter.name);
+            }
             for (const value of adapter.kits ?? []) {
-                if (!value || typeof value.include !== "string")
+                if (!value || typeof value.include !== "string") {
                     throw new Error("Malformed adapter kit: " + adapter.name);
-                if (available.has(value.include))
+                }
+                if (available.has(value.include)) {
                     throw new Error("Ambiguous kit alias: " + value.include);
+                }
                 available.set(value.include, value);
             }
         }
-        for (const name of includes)
-            if (!available.has(name))
+        for (const name of includes) {
+            if (!available.has(name)) {
                 throw new Error(`Unknown kit ${name}${loaded.problems.length ? ": " + loaded.problems.join("; ") : "; configure an adapter that supplies it"}`);
+            }
+        }
     }
-    const selected = includes.map(name => { const value = available.get(name); if (!value)
-        throw new Error("Unknown kit: " + name); return value; });
+    const selected = includes.map((name) => {
+        const value = available.get(name);
+        if (!value) {
+            throw new Error("Unknown kit: " + name);
+        }
+        return value;
+    });
     const report = checkKits(selected);
-    if (!report.valid)
+    if (!report.valid) {
         throw new Error(report.problems.join("; "));
+    }
     return selected;
 }

package/dist/layout-policy.d.ts

@@ -0,0 +1,2 @@
+/** Trusted, dependency-free sandbox policy shared by the host observer and shipped kit. */
+export declare const layoutPolicySource: string;

package/dist/layout-policy.js

@@ -0,0 +1,86 @@
+/** Trusted, dependency-free sandbox policy shared by the host observer and shipped kit. */
+export const layoutPolicySource = String.raw `
+const observeLayout = async (penpot, root, options) => {
+ if (!Number.isInteger(options.maxNodes === undefined ? 10000 : options.maxNodes) || (options.maxNodes !== undefined && (options.maxNodes < 1 || options.maxNodes > 10000))) throw new Error("Invalid settling node budget");
+ const fileId = penpot.currentFile.id, pageId = penpot.currentPage.id;
+ 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");
+ };
+ if (!root) throw new Error("layout target does not exist");
+ let nativeOutcome = "skipped", nativeError;
+ const target = typeof root.waitForLayoutUpdate === "function" ? root : penpot;
+ if (options.nativeMs > 0) {
+  nativeOutcome = "unsupported";
+  if (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); })]);
+    nativeOutcome = "completed";
+   } catch (error) { nativeOutcome = "failed"; nativeError = String(error && error.message || error); }
+   finally { clearTimeout(timer); }
+  }
+ }
+ validTarget();
+ // Keep hierarchy and sibling order as well as geometry; repeated IDs include cycles.
+ const geometry = [], stack = [[root, null, 0]], seen = new Set();
+ while (stack.length) {
+  if (geometry.length >= (options.maxNodes || 10000)) throw new Error("Layout sample exceeded node budget");
+  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]);
+ }
+ validTarget();
+ return { ok: true, fileId, pageId, native: nativeOutcome === "completed", nativeOutcome, nativeError, geometry, truncated: false };
+};
+const settleLayout = async (observe, options) => {
+ const { timeoutMs, intervalMs, strategy = "auto", sleep } = options;
+ if (!["auto", "native", "geometry"].includes(strategy) || !Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || !Number.isFinite(intervalMs) || intervalMs <= 0 || Math.ceil(timeoutMs / intervalMs) + 1 > 1000) throw new Error("Invalid layout strategy or settling budgets");
+ const started = Date.now(), deadline = started + timeoutMs;
+ let samples = 0, nativeOutcome = "skipped", fallbackReason, identity, previous, equal = 0;
+ const result = (stable, method, reason) => ({ stable, method, samples, strategy, nativeOutcome, ...(fallbackReason ? { fallbackReason } : {}), elapsedMs: Date.now() - started, ...(reason ? { reason } : {}) });
+ for (let count = 0; count < Math.ceil(timeoutMs / intervalMs) + 1; count++) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) return result(false, strategy === "native" ? "native" : "geometry", "Layout observation exceeded its deadline");
+  const nativeMs = count === 0 && strategy !== "geometry" ? strategy === "native" ? remaining : Math.max(1, Math.min(500, Math.floor(remaining / 4))) : 0;
+  const state = await observe(nativeMs, remaining);
+  samples++;
+  if (!state || state.ok !== true || typeof state.fileId !== "string" || !state.fileId || typeof state.pageId !== "string" || !state.pageId) throw new Error("Layout returned no target identity evidence");
+  if (typeof state.native !== "boolean" || typeof state.truncated !== "boolean" || state.nativeOutcome !== undefined && !["skipped", "unsupported", "completed", "failed"].includes(state.nativeOutcome)) throw new Error("Malformed layout attempt evidence");
+  const nextIdentity = JSON.stringify([state.fileId, state.pageId, state.geometry?.[0]?.[0]]);
+  if (identity && identity !== nextIdentity) throw new Error("Layout target changed between samples");
+  identity = nextIdentity;
+  if (state.truncated || !Array.isArray(state.geometry) || !state.geometry.length || state.geometry.length > 10000) throw new Error("Incomplete layout geometry evidence");
+  const ids = new Set(), childIndices = new Map();
+  for (const row of state.geometry) {
+   if (!Array.isArray(row) || row.length !== 7 || typeof row[0] !== "string" || !row[0] || ids.has(row[0]) || !row.slice(1,5).every(value => typeof value === "number" && Number.isFinite(value)) ||  ((row[5] !== null && !ids.has(row[5])) || !Number.isInteger(row[6]) || row[6] < 0)) throw new Error("Layout API returned no geometry evidence or malformed hierarchy");
+   if (!ids.size ? row[5] !== null || row[6] !== 0 : row[5] === null || typeof row[5] !== "string") throw new Error("Malformed layout root hierarchy");
+   if (row[5] !== null) {
+    const expectedIndex = childIndices.get(row[5]) || 0;
+    if (row[6] !== expectedIndex) throw new Error("Malformed layout sibling order");
+    childIndices.set(row[5], expectedIndex + 1);
+   }
+   ids.add(row[0]);
+  }
+  if (count === 0) {
+   nativeOutcome = state.nativeOutcome || (state.native ? state.error ? "failed" : "completed" : strategy === "geometry" ? "skipped" : "unsupported");
+   if (Date.now() >= deadline) return result(false, strategy === "native" || state.native ? "native" : "geometry", "Layout observation exceeded its deadline");
+   if (nativeOutcome === "completed") return result(true, "native");
+   if (strategy === "native") return result(false, "native", state.nativeError || state.error || "Native layout API unavailable");
+   if (strategy === "auto") fallbackReason = state.nativeError || state.error || "Native layout API unavailable";
+  }
+  if (Date.now() >= deadline) return result(false, "geometry", "Layout observation exceeded its deadline");
+  const current = JSON.stringify(state.geometry);
+  equal = current === previous ? equal + 1 : 1;
+  if (equal >= 3) return result(true, "geometry");
+  previous = current;
+  await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+ }
+ return result(false, "geometry", "Layout did not settle within its bounded samples");
+};
+`;

package/dist/layout.d.ts

@@ -1,6 +1,8 @@
 import type { PenpotToolClient } from "./client.js";
+export type LayoutStrategy = "auto" | "native" | "geometry";
 export interface LayoutOptions {
     shapeId?: string;
+    strategy?: LayoutStrategy;
     timeoutMs?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
@@ -10,6 +12,10 @@ export interface LayoutResult {
     method: "native" | "geometry" | "unavailable";
     samples: number;
     reason?: string;
+    strategy?: LayoutStrategy;
+    nativeOutcome?: "skipped" | "unsupported" | "completed" | "failed";
+    fallbackReason?: string;
+    elapsedMs?: number;
 }
-/** Native completion is preferred. Older APIs fall back to bounded geometry samples; pixel verification stays separate. */
+/** Layout evidence is independent of render equality and visual approval. Transport failures propagate without fallback. */
 export declare function waitForStableLayout(client: PenpotToolClient, options?: LayoutOptions): Promise<LayoutResult>;

package/dist/layout.js

@@ -1,79 +1,36 @@
-import { commandSleep } from "./command-result.js";
 import { PenpairError } from "./errors.js";
+import { commandSleep } from "./command-result.js";
 import { runSnippet, snippet } from "./snippet.js";
-const layoutState = `
-const fileId = penpot.currentFile.id, pageId = penpot.currentPage.id;
-const shape = CFG.shapeId ? penpot.currentPage.getShapeById(CFG.shapeId) : penpot.currentPage.root;
-if (!shape) return { ok: false, message: "layout target does not exist" };
-const target = CFG.shapeId && typeof shape.waitForLayoutUpdate === "function" ? shape : penpot;
-let native = false;
-if (CFG.native && typeof target.waitForLayoutUpdate === "function") {
-  try { await target.waitForLayoutUpdate(CFG.timeout); native = true; }
-  catch (error) { return { ok: true, fileId, pageId, native: true, error: String(error && error.message || error) }; }
-}
-if (penpot.currentFile.id !== fileId || penpot.currentPage.id !== pageId) return { ok: false, message: "layout target changed while waiting" };
-const geometry = [], stack = [shape];
-while (stack.length && geometry.length < 10000) {
-  const s = stack.pop(); geometry.push([s.id, s.x, s.y, s.width, s.height]);
-  for (const child of s.children || []) stack.push(child);
-}
-return { ok: true, fileId, pageId, native, geometry, truncated: stack.length > 0 };`;
-/** Native completion is preferred. Older APIs fall back to bounded geometry samples; pixel verification stays separate. */
+import { layoutPolicySource } from "./layout-policy.js";
+// This evaluates only the static policy above, never project or transport content.
+const settle = new Function(`${layoutPolicySource}\nreturn settleLayout;`)();
+/** Layout evidence is independent of render equality and visual approval. Transport failures propagate without fallback. */
 export async function waitForStableLayout(client, options = {}) {
-    const { timeoutMs = 30_000, intervalMs = 200, shapeId, sleep = commandSleep } = options;
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000 || !Number.isFinite(intervalMs) || intervalMs <= 0)
-        throw new Error("Layout timeout must be in (0, 30000] ms and the interval must be positive");
-    if (Math.ceil(timeoutMs / intervalMs) + 1 > 1000)
-        throw new Error("Layout polling must stay within 1000 samples");
-    const deadline = Date.now() + timeoutMs;
-    const sample = (native) => runSnippet(client, snippet("layout-state", layoutState, { shapeId, native, timeout: Math.max(1, deadline - Date.now()) }, "read"), { retries: 0, timeoutMs: Math.max(1, deadline - Date.now()) });
-    const validGeometry = (value) => Array.isArray(value) && value.length > 0 && value.every((row) => Array.isArray(row) && row.length === 5 && typeof row[0] === "string" && !!row[0] && row.slice(1).every((entry) => typeof entry === "number" && Number.isFinite(entry)));
-    let first;
+    const { timeoutMs = 30000, intervalMs = 200, strategy = "auto", sleep = commandSleep, shapeId, } = options;
     try {
-        first = await sample(true);
+        return await settle(async (nativeMs, remaining) => runSnippet(client, snippet("layout-state", `${layoutPolicySource}\nconst shape = CFG.shapeId ? penpot.currentPage.getShapeById(CFG.shapeId) : penpot.currentPage.root;\nreturn await observeLayout(penpot, shape, CFG);`, {
+            shapeId,
+            nativeMs,
+        }, "read"), {
+            retries: 0,
+            timeoutMs: remaining,
+        }), {
+            timeoutMs,
+            intervalMs,
+            strategy,
+            sleep,
+        });
     }
     catch (error) {
-        if (error instanceof PenpairError && error.code === "mcp-unavailable")
-            return { stable: false, method: "unavailable", samples: 0, reason: "Layout observation did not complete within its request budget" };
-        throw error;
-    }
-    if (first.ok !== true || typeof first.fileId !== "string" || !first.fileId || typeof first.pageId !== "string" || !first.pageId)
-        throw new Error("Layout returned no target identity evidence");
-    if (first.error)
-        return { stable: false, method: "native", samples: 1, reason: String(first.error) };
-    if (Date.now() > deadline)
-        return { stable: false, method: first.native ? "native" : "geometry", samples: 1, reason: "Layout observation exceeded its deadline" };
-    if (first.truncated)
-        return { stable: false, method: first.native ? "native" : "geometry", samples: 1, reason: "Layout sample exceeded 10000 nodes" };
-    if (typeof first.native !== "boolean" || typeof first.truncated !== "boolean" || !validGeometry(first.geometry))
-        throw new Error("Layout API returned no geometry evidence");
-    if (first.native)
-        return { stable: true, method: "native", samples: 1 };
-    let previous = JSON.stringify(first.geometry);
-    const maxSamples = Math.ceil(timeoutMs / intervalMs) + 1;
-    let samples = 1;
-    for (let count = 2; count <= maxSamples && Date.now() <= deadline; count++) {
-        await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
-        let next;
-        try {
-            next = await sample(false);
+        if (error instanceof PenpairError && error.code === "mcp-unavailable") {
+            return {
+                stable: false,
+                method: "unavailable",
+                samples: 0,
+                strategy,
+                reason: "Layout observation did not complete within its request budget",
+            };
         }
-        catch (error) {
-            if (error instanceof PenpairError && error.code === "mcp-unavailable")
-                return { stable: false, method: "geometry", samples, reason: "Layout did not settle within its request budget" };
-            throw error;
-        }
-        samples = count;
-        if (Date.now() > deadline)
-            return { stable: false, method: "geometry", samples, reason: "Layout did not settle before its deadline" };
-        if (next.fileId !== first.fileId || next.pageId !== first.pageId)
-            throw new Error("Layout target changed between samples");
-        if (next.ok !== true || !validGeometry(next.geometry) || next.truncated)
-            return { stable: false, method: "geometry", samples: count, reason: "Incomplete layout sample" };
-        const current = JSON.stringify(next.geometry);
-        if (current === previous)
-            return { stable: true, method: "geometry", samples: count };
-        previous = current;
+        throw error;
     }
-    return { stable: false, method: "geometry", samples, reason: "Layout did not settle within its bounded samples" };
 }

package/dist/live-smoke.js

@@ -3,12 +3,21 @@ import { runDeepCheck } from "./deep-check.js";
 import { guardFile } from "./file-guard.js";
 /** A live write probe is never scheduled blindly: the caller explicitly identifies a disposable file and tested version. */
 export async function runLiveSmoke(client, options) {
-    if (!options.confirmedScratch || !options.scratchFileId.trim() || !/^\d+\.\d+\.\d+$/.test(options.expectedVersion))
+    if (!options.confirmedScratch ||
+        !options.scratchFileId.trim() ||
+        !/^\d+\.\d+\.\d+$/.test(options.expectedVersion)) {
         throw new Error("Live smoke requires an explicitly confirmed scratch file ID and expected Penpot version");
-    const guarded = guardFile(client, { id: options.scratchFileId });
-    const { result } = await executeCode(guarded, "return { version: penpot.version, fileId: penpot.currentFile.id };", { effect: "read", retries: 0 });
+    }
+    const guarded = guardFile(client, {
+        id: options.scratchFileId,
+    });
+    const { result } = await executeCode(guarded, "return { version: penpot.version, fileId: penpot.currentFile.id };", {
+        effect: "read",
+        retries: 0,
+    });
     const actual = result;
-    if (actual?.version !== options.expectedVersion || actual?.fileId !== options.scratchFileId)
+    if (actual?.version !== options.expectedVersion || actual?.fileId !== options.scratchFileId) {
         throw new Error("Live smoke target/version differs from the pinned expectation. No probe was applied.");
+    }
     return runDeepCheck(guarded, options);
 }

package/dist/local-profile.js

@@ -2,7 +2,8 @@ import { ConfigError } from "./instance/config.js";
 /** The commands that run Penpot on this computer exist only when a package provides a profile for them. */
 export const needsLocalProfile = "Running Penpot on this computer is not part of this install. It comes with `@penpair/docker`: install it with `npm i -D @penpair/docker` and run `npx penpair …` (or, once, `npx @penpair/docker <command>`). Penpot on the web needs nothing extra.";
 export function requireLocalProfile(local) {
-    if (!local)
+    if (!local) {
         throw new ConfigError(needsLocalProfile);
+    }
     return local;
 }