@penpair/core 0.1.2 → 0.2.0

package/dist/kit-source.js

@@ -0,0 +1,309 @@
+/** 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));
+    const settle = async (root = penpot.currentPage.root, options = {}) => {
+        const timeout = options.timeoutMs === undefined ? 10000 : options.timeoutMs, interval = options.intervalMs === undefined ? 100 : options.intervalMs, maxNodes = options.maxNodes === undefined ? 10000 : options.maxNodes;
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 30000 || !Number.isInteger(interval) || interval < 1 || interval > 1000 || !Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 10000)
+            throw new Error("Invalid settling budgets");
+        const started = Date.now(), sample = () => { const rows = [], stack = [root], seen = new Set(); while (stack.length) {
+            if (rows.length >= maxNodes)
+                throw new Error("Settling node budget exceeded");
+            const shape = stack.pop();
+            if (!shape || !shape.id || seen.has(shape.id) || ![shape.x, shape.y, shape.width, shape.height].every(Number.isFinite))
+                throw new Error("Malformed settling geometry");
+            seen.add(shape.id);
+            rows.push([shape.id, shape.x, shape.y, shape.width, shape.height]);
+            for (const child of shape.children || [])
+                stack.push(child);
+        } return JSON.stringify(rows); };
+        try {
+            const target = root && typeof root.waitForLayoutUpdate === "function" ? root : penpot;
+            if (typeof target.waitForLayoutUpdate === "function") {
+                await target.waitForLayoutUpdate(timeout);
+                sample();
+                if (Date.now() - started >= timeout)
+                    return { stable: false, method: "native", samples: 1, reason: "Native layout exceeded deadline" };
+                return { stable: true, method: "native", samples: 1 };
+            }
+            let previous = sample();
+            for (let samples = 2; samples <= 1000 && Date.now() - started < timeout; samples++) {
+                await wait(Math.min(interval, Math.max(1, timeout - (Date.now() - started))));
+                const current = sample();
+                if (Date.now() - started >= timeout)
+                    break;
+                if (current === previous)
+                    return { stable: true, method: "geometry", samples };
+                previous = current;
+            }
+            return { stable: false, method: "geometry", reason: "Layout did not settle within budget" };
+        }
+        catch (error) {
+            return { stable: false, method: "unavailable", 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() });
+            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() });
+            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,90 @@
+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 = [], names = new Set(), 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.d.ts

@@ -0,0 +1,15 @@
+import type { PenpotToolClient } from "./client.js";
+export interface LayoutOptions {
+    shapeId?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface LayoutResult {
+    stable: boolean;
+    method: "native" | "geometry" | "unavailable";
+    samples: number;
+    reason?: string;
+}
+/** Native completion is preferred. Older APIs fall back to bounded geometry samples; pixel verification stays separate. */
+export declare function waitForStableLayout(client: PenpotToolClient, options?: LayoutOptions): Promise<LayoutResult>;

package/dist/layout.js

@@ -0,0 +1,79 @@
+import { commandSleep } from "./command-result.js";
+import { PenpairError } from "./errors.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. */
+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;
+    try {
+        first = await sample(true);
+    }
+    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);
+        }
+        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;
+    }
+    return { stable: false, method: "geometry", samples, reason: "Layout did not settle within its bounded samples" };
+}

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,14 @@
+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);
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,12 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type CliOptions } from "./cli-main.js";
+export interface McpOptions {
+    root: string;
+    allowWrites?: boolean;
+    cli?: CliOptions;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+/** Long-lived server with an immutable explicit root and no process.chdir or raw-code tool. */
+export declare function createMcpServer(options: McpOptions): Promise<Server>;
+export declare function serveMcp(options: McpOptions): Promise<Server>;