@penpair/core 0.1.3 → 0.3.0

package/dist/kit-source.d.ts

@@ -0,0 +1,2 @@
+/** Plain plugin-sandbox JavaScript. Inclusion defines helpers without touching the document. */
+export declare const coreKitSource: string;

package/dist/kit-source.js

@@ -0,0 +1,279 @@
+import { layoutPolicySource } from "./layout-policy.js";
+/** Plain plugin-sandbox JavaScript. Inclusion defines helpers without touching the document. */
+export const coreKitSource = String.raw `// penpair: read
+const pp = (() => {
+    const bindings = [], styles = [], recipes = new Map();
+    let flushing = false, queuedContext = null;
+    const numeric = (value, label) => { if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        throw new Error(label + " must be finite and nonnegative"); return value; };
+    const activeSets = () => { const sets = penpot.library.local.tokens.sets; if (!Array.isArray(sets))
+        throw new Error("Token API unavailable"); return sets.filter(set => set.active); };
+    const context = () => JSON.stringify(activeSets().map(set => [set.id || null, set.name, set.tokens.map(token => [token.id || null, token.name, token.type, token.value])]));
+    const tok = name => { if (typeof name !== "string" || !name)
+        throw new Error("Token name required"); let found = null, count = 0; for (const set of activeSets()) {
+        const matches = [];
+        for (const token of set.tokens) {
+            if (++count > 10000)
+                throw new Error("Active token budget exceeded");
+            if (token.name === name)
+                matches.push(token);
+        }
+        if (matches.length > 1)
+            throw new Error("Ambiguous token in set: " + name);
+        if (matches.length)
+            found = matches[0];
+    } if (!found)
+        throw new Error("No active token: " + name); return found; };
+    const numericToken = (value, label) => { if (value === undefined || value === 0)
+        return { value: 0, token: null }; if (typeof value !== "string")
+        throw new Error(label + " needs a token name (only unbound zero is allowed)"); const token = tok(value); if (token.type !== "spacing")
+        throw new Error(label + " needs a spacing token"); const resolved = token.resolvedValue === undefined ? Number(token.value) : Number(token.resolvedValue); return { value: numeric(resolved, label), token: value }; };
+    const reserve = () => { const actual = context(); if (queuedContext === null)
+        queuedContext = actual;
+    else if (queuedContext !== actual)
+        throw new Error("Active token context changed while building"); };
+    const bind = (shape, name, properties) => { if (!shape || !shape.id || typeof shape.applyToken !== "function")
+        throw new Error("Bindable shape required"); if (!Array.isArray(properties) || !properties.length || properties.some(key => typeof key !== "string" || !key))
+        throw new Error("Explicit binding properties required"); tok(name); reserve(); if (bindings.length >= 10000)
+        throw new Error("Binding queue exceeds budget"); bindings.push({ shape, name, properties: [...properties] }); return shape; };
+    const checkStyle = options => { for (const key of ["bg", "stroke", "radius"])
+        if (options[key] !== undefined && (typeof options[key] !== "string" || !options[key]))
+            throw new Error(key + " needs a token name"); for (const key of ["bg", "stroke", "radius"])
+        if (options[key] !== undefined) {
+            const token = tok(options[key]);
+            if (token.type !== (key === "radius" ? "borderRadius" : "color"))
+                throw new Error("Wrong token type for " + key);
+        } numericToken(options.gap, "gap"); const pad = options.pad === undefined ? [0, 0, 0, 0] : options.pad; if (!Array.isArray(pad) || pad.length !== 4)
+        throw new Error("Padding requires four token names or zeros"); pad.forEach(value => numericToken(value, "padding")); };
+    const style = (shape, options = {}) => {
+        checkStyle(options);
+        if ((options.gap !== undefined || options.pad !== undefined) && !shape.flex)
+            throw new Error("Spacing style requires a flex board");
+        for (const name of [options.bg, options.stroke, options.radius].filter(Boolean))
+            tok(name);
+        const gap = numericToken(options.gap, "gap"), pad = options.pad === undefined ? [0, 0, 0, 0] : options.pad;
+        if (!Array.isArray(pad) || pad.length !== 4)
+            throw new Error("Padding requires four token names or zeros");
+        const pads = pad.map(value => numericToken(value, "padding"));
+        reserve();
+        if (styles.length >= 5000)
+            throw new Error("Style queue exceeds budget");
+        styles.push(() => {
+            if (shape.flex) {
+                if (options.gap !== undefined) {
+                    shape.flex.rowGap = gap.value;
+                    shape.flex.columnGap = gap.value;
+                }
+                if (options.pad !== undefined) {
+                    shape.flex.paddingType = "multiple";
+                    ["topPadding", "rightPadding", "bottomPadding", "leftPadding"].forEach((key, index) => { shape.flex[key] = pads[index].value; });
+                }
+            }
+            if (options.stroke) {
+                shape.strokes = [{ strokeColor: "#000000", strokeWidth: options.strokeWidth === undefined ? 1 : numeric(options.strokeWidth, "stroke width"), strokeAlignment: "inner" }];
+                bind(shape, options.stroke, ["strokeColor"]);
+            }
+            if (options.bg)
+                bind(shape, options.bg, ["fill"]);
+            if (options.radius)
+                bind(shape, options.radius, ["borderRadiusTopLeft", "borderRadiusTopRight", "borderRadiusBottomRight", "borderRadiusBottomLeft"]);
+            if (gap.token)
+                bind(shape, gap.token, ["rowGap", "columnGap"]);
+            pads.forEach((entry, index) => { if (entry.token)
+                bind(shape, entry.token, [["paddingTop", "paddingRight", "paddingBottom", "paddingLeft"][index]]); });
+        });
+        return shape;
+    };
+    const box = (parent, options = {}) => {
+        checkStyle(options);
+        const gap = numericToken(options.gap, "gap");
+        if (options.w !== undefined)
+            numeric(options.w, "width");
+        if (options.h !== undefined)
+            numeric(options.h, "height");
+        const board = penpot.createBoard();
+        if (parent)
+            parent.appendChild(board);
+        board.name = options.name || "Board";
+        board.fills = [];
+        board.clipContent = !!options.clip;
+        board.addFlexLayout();
+        board.flex.dir = options.dir || "column";
+        board.flex.wrap = options.wrap ? "wrap" : "nowrap";
+        board.flex.alignItems = options.align || "start";
+        board.flex.justifyContent = options.justify || "start";
+        board.flex.rowGap = gap.value;
+        board.flex.columnGap = gap.value;
+        if (options.w !== undefined || options.h !== undefined)
+            board.resize(options.w === undefined ? board.width : options.w, options.h === undefined ? board.height : options.h);
+        board.flex.horizontalSizing = options.w === undefined ? "auto" : "fix";
+        board.flex.verticalSizing = options.h === undefined ? "auto" : "fix";
+        return style(board, { ...options, gap: options.gap === undefined ? 0 : options.gap, pad: options.pad === undefined ? [0, 0, 0, 0] : options.pad });
+    };
+    const text = (parent, value, options = {}) => {
+        if (typeof value !== "string" || value.length === 0)
+            throw new Error("Text needs nonempty characters; use an explicit space for blank text");
+        const typography = tok(options.typo);
+        if (typography.type !== "typography" || tok(options.color).type !== "color")
+            throw new Error("Text needs typography and color token types");
+        let resolved = typography.resolvedValue;
+        if (Array.isArray(resolved) && resolved.length === 1)
+            resolved = resolved[0];
+        const data = resolved && typeof resolved === "object" && !Array.isArray(resolved) ? resolved : typography.value;
+        const families = options.font || (data && typeof data === "object" && (data.fontFamilies || data.fontFamily));
+        const family = Array.isArray(families) ? families[0] : families;
+        if (typeof family !== "string" || !family || family.includes("{"))
+            throw new Error("An explicit or resolved font family is required");
+        const font = penpot.fonts.findByName(family);
+        if (!font || !Array.isArray(font.variants) || typeof font.applyToText !== "function")
+            throw new Error("Font unavailable: " + family);
+        const weight = String(options.weight || (data && typeof data === "object" && (data.fontWeight || data.fontWeights)) || "400"), fontStyle = options.fontStyle || "normal";
+        const variants = font.variants.filter(variant => String(variant.fontWeight) === weight && (variant.fontStyle || "normal") === fontStyle);
+        if (variants.length !== 1)
+            throw new Error("Font weight/style is missing or ambiguous: " + family + " " + weight);
+        const shape = penpot.createText(value);
+        if (parent)
+            parent.appendChild(shape);
+        shape.name = options.name || value.slice(0, 80);
+        shape.growType = options.wrap ? "auto-height" : options.grow || "auto-width";
+        if (options.align)
+            shape.align = options.align;
+        font.applyToText(shape, variants[0]);
+        if (options.wrap || options.fill) {
+            if (!shape.layoutChild)
+                throw new Error("Text layout child unavailable");
+            shape.layoutChild.horizontalSizing = "fill";
+        }
+        bind(shape, options.typo, ["typography"]);
+        bind(shape, options.color, ["fill"]);
+        return shape;
+    };
+    const glyphs = { chevron: { path: "M9 6 L15 12 L9 18", bounds: [9, 6, 6, 12] }, check: { path: "M4 12 L10 18 L20 6", bounds: [4, 6, 16, 12] }, alert: { path: "M12 3 L22 20 H2 Z M12 10 V14", bounds: [2, 3, 20, 17] }, calendar: { path: "M4 6 H20 V20 H4 Z M4 10 H20 M8 3 V7 M16 3 V7", bounds: [4, 3, 16, 17] } };
+    const icon = (parent, kind, color, size = 20) => {
+        numeric(size, "icon size");
+        if (size === 0)
+            throw new Error("Icon size must be positive");
+        tok(color);
+        const glyph = typeof kind === "string" ? glyphs[kind] : kind;
+        if (!glyph || typeof glyph.path !== "string" || !Array.isArray(glyph.bounds) || glyph.bounds.length !== 4 || !glyph.bounds.every(Number.isFinite) || glyph.bounds[2] <= 0 || glyph.bounds[3] <= 0)
+            throw new Error("Icon requires known path and positive bounds");
+        const board = penpot.createBoard();
+        if (parent)
+            parent.appendChild(board);
+        board.name = "Icon";
+        board.fills = [];
+        board.clipContent = false;
+        board.resize(size, size);
+        const path = penpot.createPath();
+        board.appendChild(path);
+        path.name = "Glyph";
+        path.content = glyph.path;
+        path.fills = [];
+        path.strokes = [{ strokeColor: "#000000", strokeWidth: Math.max(1, 2 * size / 24), strokeCapStyle: "round", strokeJoinStyle: "round" }];
+        const [x, y, width, height] = glyph.bounds, scale = size / 24;
+        path.proportionLock = true;
+        path.resize(width * scale, height * scale);
+        path.x = board.x + x * scale;
+        path.y = board.y + y * scale;
+        bind(path, color, ["strokeColor"]);
+        return board;
+    };
+    const dot = (parent, color, size = 8) => { numeric(size, "dot size"); if (!size)
+        throw new Error("Positive dot size required"); tok(color); const shape = penpot.createEllipse(); if (parent)
+        parent.appendChild(shape); shape.name = "Dot"; shape.resize(size, size); bind(shape, color, ["fill"]); return shape; };
+    const rule = (parent, color) => { tok(color); const shape = penpot.createRectangle(); if (parent)
+        parent.appendChild(shape); shape.name = "Rule"; shape.resize(10, 1); if (!shape.layoutChild)
+        throw new Error("Rule layout child unavailable"); shape.layoutChild.horizontalSizing = "fill"; bind(shape, color, ["fill"]); return shape; };
+    const descendants = root => { const out = [], stack = [root], seen = new Set(); while (stack.length) {
+        if (out.length >= 20000)
+            throw new Error("Component traversal exceeds budget");
+        const shape = stack.pop();
+        if (!shape.id || seen.has(shape.id))
+            throw new Error("Invalid component identity");
+        seen.add(shape.id);
+        out.push(shape);
+        for (const child of shape.children || [])
+            stack.push(child);
+    } return out; };
+    const inst = (parent, path, name, texts = {}, library = penpot.library.local) => {
+        const components = library.components.filter(component => component.path === path && component.name === name);
+        if (components.length !== 1)
+            throw new Error("Component missing or ambiguous: " + path + "/" + name);
+        const entries = Object.entries(texts);
+        if (entries.some(([, value]) => typeof value !== "string" || !value))
+            throw new Error("Text overrides must be nonempty strings");
+        const validate = root => { const rows = descendants(root); return entries.map(([key, value]) => { const matches = rows.filter(shape => shape.type === "text" && shape.name === key); if (matches.length !== 1)
+            throw new Error("Override target missing or ambiguous: " + key); return { shape: matches[0], value }; }); };
+        if (typeof components[0].mainInstance === "function")
+            validate(components[0].mainInstance());
+        const shape = components[0].instance();
+        const overrides = validate(shape);
+        if (parent)
+            parent.appendChild(shape);
+        for (const override of overrides)
+            override.shape.characters = override.value;
+        return shape;
+    };
+    const fill = shape => { if (!shape.layoutChild)
+        throw new Error("Layout child unavailable"); shape.layoutChild.horizontalSizing = "fill"; return shape; };
+    const fillV = shape => { if (!shape.layoutChild)
+        throw new Error("Layout child unavailable"); shape.layoutChild.verticalSizing = "fill"; return shape; };
+    const wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
+    ${layoutPolicySource}
+    const settle = async (root = penpot.currentPage.root, options = {}) => {
+        const fileId = penpot.currentFile.id, pageId = penpot.currentPage.id;
+        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 }); }
+        catch (error) { return { stable: false, method: "unavailable", samples: 0, reason: String(error && error.message || error) }; }
+    };
+    const flush = async (options = {}) => {
+        if (flushing)
+            throw new Error("Concurrent flush is unsupported");
+        flushing = true;
+        const timeout = options.timeoutMs === undefined ? 10000 : options.timeoutMs, started = Date.now();
+        let applied = 0;
+        const remaining = () => { const value = timeout - (Date.now() - started); if (value < 1)
+            throw new Error("Flush deadline exceeded"); return value; };
+        try {
+            if (queuedContext !== null && context() !== queuedContext)
+                throw new Error("Active token context changed before flush");
+            let layout = await settle(options.root || penpot.currentPage.root, { timeoutMs: remaining(), strategy: options.strategy });
+            if (!layout.stable)
+                throw new Error(layout.reason || "Layout did not settle");
+            if (queuedContext !== null && context() !== queuedContext)
+                throw new Error("Active token context changed during layout");
+            while (styles.length) {
+                remaining();
+                styles[0]();
+                styles.shift();
+            }
+            while (bindings.length) {
+                remaining();
+                if (context() !== queuedContext)
+                    throw new Error("Token context changed during binding");
+                const binding = bindings[0];
+                await binding.shape.applyToken(tok(binding.name), binding.properties);
+                bindings.shift();
+                applied++;
+            }
+            layout = await settle(options.root || penpot.currentPage.root, { timeoutMs: remaining(), strategy: options.strategy });
+            if (!layout.stable)
+                throw new Error(layout.reason || "Layout did not settle");
+            queuedContext = null;
+            return { applied, layout };
+        }
+        finally {
+            flushing = false;
+        }
+    };
+    const defineRecipe = (name, build, description = "") => { if (!/^[a-z][a-z0-9-]*$/.test(name) || typeof build !== "function" || recipes.has(name))
+        throw new Error("Invalid or duplicate recipe: " + name); recipes.set(name, { build, description }); return build; };
+    const recipe = (name, parent, props) => { const found = recipes.get(name); if (!found)
+        throw new Error("Unknown recipe: " + name); return found.build(parent, props || {}); };
+    defineRecipe("hello-card", (parent, props) => { if (!props.box || !props.text)
+        throw new Error("hello-card needs explicit box/text token styles"); tok(props.text.typo); tok(props.text.color); const board = box(parent, props.box); text(board, props.label || "Hello, card", props.text); return board; }, "A neutral text-in-board example, with explicit token styles");
+    return { tok, bind, box, text, icon, dot, rule, inst, style, fill, fillV, settle, flush, defineRecipe, recipe, recipes: () => [...recipes].map(([name, value]) => ({ name, description: value.description })) };
+})();
+`;

package/dist/kit.d.ts

@@ -0,0 +1,25 @@
+export interface RecipeInfo {
+    name: string;
+    description: string;
+}
+export interface BuildKit {
+    include: string;
+    source: string;
+    recipes: RecipeInfo[];
+    requires?: string[];
+}
+export declare const coreKit: BuildKit;
+/** Plain JavaScript to concatenate into a reviewed plugin body; defines the pp namespace. */
+export declare const kit: () => string;
+export declare function checkKits(kits: BuildKit[]): {
+    valid: boolean;
+    bytes: number;
+    sources: {
+        include: string;
+        bytes: number;
+        sha256: string;
+    }[];
+    problems: string[];
+};
+/** Adapter imports happen only when an explicitly requested alias cannot be supplied by the core. */
+export declare function loadKits(root: string, includes?: string[]): Promise<BuildKit[]>;

package/dist/kit.js

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+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",
+        },
+    ],
+};
+/** Plain JavaScript to concatenate into a reviewed plugin body; defines the pp namespace. */
+export const kit = () => coreKitSource;
+export function checkKits(kits) {
+    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") {
+            problems.push("Malformed kit at index " + index);
+            return {
+                include: "invalid",
+                bytes: 0,
+                sha256: "",
+            };
+        }
+        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"))) {
+            problems.push("Invalid kit dependencies: " + value.include);
+        }
+        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")) {
+            problems.push(`${value.include} must declare read-only top-level inclusion`);
+        }
+        const bytes = Buffer.byteLength(value.source);
+        if (bytes > 32768) {
+            problems.push(`${value.include} exceeds the 32 KiB source budget`);
+        }
+        const error = compiles(value.source);
+        if (error) {
+            problems.push(`${value.include}: ${error}`);
+        }
+        if (!Array.isArray(value.recipes)) {
+            problems.push(`${value.include} has invalid recipe metadata`);
+        }
+        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") {
+                    problems.push(`${value.include} has invalid recipe metadata`);
+                }
+                else if (recipeNames.has(recipe.name)) {
+                    problems.push("Duplicate recipe: " + recipe.name);
+                }
+                else {
+                    recipeNames.add(recipe.name);
+                }
+            }
+        }
+        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};");
+        bytes = Buffer.byteLength(combined.code);
+        const error = compiles(combined.code);
+        if (error) {
+            problems.push(error);
+        }
+    }
+    catch (error) {
+        problems.push(String(error.message));
+    }
+    if (bytes > 49152) {
+        problems.push("Combined kit exceeds the 48 KiB budget reserved before project code");
+    }
+    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",
+]) {
+    const config = await loadOptionalConfig(root);
+    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 loaded = await loadAdapters(root, config?.adapters);
+        for (const adapter of loaded.adapters) {
+            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") {
+                    throw new Error("Malformed adapter kit: " + adapter.name);
+                }
+                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)) {
+                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 report = checkKits(selected);
+    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

@@ -0,0 +1,21 @@
+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>;
+}
+export interface LayoutResult {
+    stable: boolean;
+    method: "native" | "geometry" | "unavailable";
+    samples: number;
+    reason?: string;
+    strategy?: LayoutStrategy;
+    nativeOutcome?: "skipped" | "unsupported" | "completed" | "failed";
+    fallbackReason?: string;
+    elapsedMs?: number;
+}
+/** 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

@@ -0,0 +1,36 @@
+import { PenpairError } from "./errors.js";
+import { commandSleep } from "./command-result.js";
+import { runSnippet, snippet } from "./snippet.js";
+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 = 30000, intervalMs = 200, strategy = "auto", sleep = commandSleep, shapeId, } = options;
+    try {
+        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,
+                strategy,
+                reason: "Layout observation did not complete within its request budget",
+            };
+        }
+        throw error;
+    }
+}

package/dist/live-smoke.d.ts

@@ -0,0 +1,8 @@
+import { type PenpotToolClient } from "./client.js";
+import { type DeepOptions, type DeepReport } from "./deep-check.js";
+/** A live write probe is never scheduled blindly: the caller explicitly identifies a disposable file and tested version. */
+export declare function runLiveSmoke(client: PenpotToolClient, options: DeepOptions & {
+    scratchFileId: string;
+    expectedVersion: string;
+    confirmedScratch: boolean;
+}): Promise<DeepReport>;

package/dist/live-smoke.js

@@ -0,0 +1,23 @@
+import { executeCode } from "./client.js";
+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)) {
+        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 actual = result;
+    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);
+}