@penpair/core 0.2.0 → 0.3.1

package/dist/skill-instructions.js

@@ -2,15 +2,22 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { resolveProjectOutput } from "./project-input.js";
 import { atomicWriteFile } from "./atomic-output.js";
-const start = "<!-- penpair:skills:start -->", end = "<!-- penpair:skills:end -->";
+import { renderSkillRouting } from "./skill-routing.js";
+const start = "<!-- penpair:skills:start -->";
+const end = "<!-- penpair:skills:end -->";
+export const skillInstructionMarkers = {
+    start,
+    end,
+};
 async function exists(file) {
     try {
         await lstat(file);
         return true;
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return false;
+        }
         throw error;
     }
 }
@@ -18,11 +25,23 @@ export async function planSkillInstructions(root, rows, destination) {
     let selected = destination;
     if (!selected) {
         const candidates = [];
-        for (const name of ["AGENTS.md", "CLAUDE.md"])
-            if (await exists(path.join(root, name)))
+        for (const name of [
+            "AGENTS.md",
+            "CLAUDE.md",
+        ]) {
+            if (await exists(path.join(root, name))) {
                 candidates.push(name);
-        if (candidates.length !== 1)
-            return { report: { path: null, status: candidates.length ? "choice-required" : "not-selected", diff: "" } };
+            }
+        }
+        if (candidates.length !== 1) {
+            return {
+                report: {
+                    path: null,
+                    status: candidates.length ? "choice-required" : "not-selected",
+                    diff: "",
+                },
+            };
+        }
         selected = candidates[0];
     }
     const canonicalRoot = await realpath(root);
@@ -32,44 +51,100 @@ export async function planSkillInstructions(root, rows, destination) {
         before = await readFile(file, "utf8");
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT") {
             throw error;
+        }
     }
     const text = before ?? "";
-    const starts = text.split(start).length - 1, ends = text.split(end).length - 1;
-    if (starts !== ends || starts > 1 || starts === 1 && text.indexOf(start) > text.indexOf(end))
+    const starts = text.split(start).length - 1;
+    const ends = text.split(end).length - 1;
+    if (starts !== ends || starts > 1 || (starts === 1 && text.indexOf(start) > text.indexOf(end))) {
         throw new Error("Malformed penpair skills markers; repair them before installation (no instruction text was changed)");
+    }
     const newline = text.includes("\r\n") ? "\r\n" : "\n";
     const relativeRows = rows.map((row) => row.replace(/\]\(([^)]+)\)/g, (_match, target) => {
-        const relative = path.relative(path.dirname(file), path.resolve(canonicalRoot, decodeURIComponent(target))).split(path.sep).join("/");
-        const link = relative.split("/").map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`)).join("/");
+        const relative = path
+            .relative(path.dirname(file), path.resolve(canonicalRoot, decodeURIComponent(target)))
+            .split(path.sep)
+            .join("/");
+        const link = relative
+            .split("/")
+            .map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/");
         return `](${link})`;
     }));
-    const block = [start, "| Skill | Purpose |", "| --- | --- |", ...relativeRows, end].join(newline);
+    const block = [
+        start,
+        ...renderSkillRouting(relativeRows),
+        "| Skill | Purpose |",
+        "| --- | --- |",
+        ...relativeRows,
+        end,
+    ].join(newline);
     let after;
-    if (starts === 1)
+    if (starts === 1) {
         after = text.slice(0, text.indexOf(start)) + block + text.slice(text.indexOf(end) + end.length);
-    else
-        after = text + (text ? text.endsWith(newline) ? newline : newline + newline : "") + "## Penpair skills" + newline + newline + block + newline;
+    }
+    else {
+        after =
+            text +
+                (text ? (text.endsWith(newline) ? newline : newline + newline) : "") +
+                "## Penpair skills" +
+                newline +
+                newline +
+                block +
+                newline;
+    }
     const changed = text !== after;
     // Diff only the owned region, never repeat unrelated instruction content in reports.
     const oldBlock = starts ? text.slice(text.indexOf(start), text.indexOf(end) + end.length) : "";
-    const diff = changed ? [`--- ${file}`, `+++ ${file}`, "@@ penpair-owned skills block @@", ...oldBlock.split(/\r?\n/).filter(Boolean).map((line) => `-${line}`), ...(starts ? block : "## Penpair skills" + newline + newline + block).split(/\r?\n/).map((line) => `+${line}`)].join("\n") : "";
-    return { before, after, mode: before === undefined ? 0o644 : (await lstat(file)).mode & 0o777, report: { path: file, status: changed ? "preview" : "unchanged", diff } };
+    const diff = changed
+        ? [
+            `--- ${file}`,
+            `+++ ${file}`,
+            "@@ penpair-owned skills block @@",
+            ...oldBlock
+                .split(/\r?\n/)
+                .filter(Boolean)
+                .map((line) => `-${line}`),
+            ...(starts ? block : "## Penpair skills" + newline + newline + block)
+                .split(/\r?\n/)
+                .map((line) => `+${line}`),
+        ].join("\n")
+        : "";
+    return {
+        before,
+        after,
+        mode: before === undefined ? 0o644 : (await lstat(file)).mode & 0o777,
+        report: {
+            path: file,
+            status: changed ? "preview" : "unchanged",
+            diff,
+        },
+    };
 }
 export async function applySkillInstructions(plan) {
-    if (plan.report.status !== "preview" || !plan.report.path || plan.after === undefined)
+    if (plan.report.status !== "preview" || !plan.report.path || plan.after === undefined) {
         return plan.report;
+    }
     let current;
     try {
         current = await readFile(plan.report.path, "utf8");
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT") {
             throw error;
+        }
     }
-    if (current !== plan.before)
+    if (current !== plan.before) {
         throw new Error("Instruction file changed after planning; nothing was overwritten");
-    await atomicWriteFile(plan.report.path, plan.after, { replace: plan.before !== undefined, mode: plan.mode });
-    return { ...plan.report, status: "written" };
+    }
+    await atomicWriteFile(plan.report.path, plan.after, {
+        replace: plan.before !== undefined,
+        mode: plan.mode,
+    });
+    return {
+        ...plan.report,
+        status: "written",
+    };
 }

package/dist/skill-metadata.d.ts

@@ -0,0 +1,8 @@
+export interface SkillMetadata {
+    name: string;
+    description: string;
+}
+export declare const maxSkillBytes: number;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export declare function parseSkillYaml(source: string): Record<string, unknown>;
+export declare function parseSkillMetadata(source: string, expectedName?: string): SkillMetadata;

package/dist/skill-metadata.js

@@ -0,0 +1,52 @@
+import { parseDocument } from "yaml";
+export const maxSkillBytes = 128 * 1024;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export function parseSkillYaml(source) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("Skill metadata exceeds the 128 KB limit");
+    }
+    const document = parseDocument(source, {
+        uniqueKeys: true,
+    });
+    if (document.errors.length || document.warnings.length) {
+        throw new Error("Invalid skill YAML metadata");
+    }
+    let value;
+    try {
+        value = document.toJS({
+            maxAliasCount: 0,
+        });
+    }
+    catch {
+        throw new Error("Skill YAML aliases are not supported");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Skill YAML metadata must be an object");
+    }
+    return value;
+}
+export function parseSkillMetadata(source, expectedName) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("SKILL.md exceeds the 128 KB limit");
+    }
+    const frontmatter = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (!frontmatter) {
+        throw new Error("SKILL.md requires YAML frontmatter with name and description");
+    }
+    const metadata = parseSkillYaml(frontmatter[1]);
+    if (typeof metadata.name !== "string" ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(metadata.name) ||
+        metadata.name.length > 64 ||
+        (expectedName !== undefined && metadata.name !== expectedName)) {
+        throw new Error("Skill name must match its kebab-case folder (at most 64 characters)");
+    }
+    if (typeof metadata.description !== "string" ||
+        !metadata.description.trim() ||
+        metadata.description.length > 1024) {
+        throw new Error("Skill description must be nonempty text (at most 1024 characters)");
+    }
+    return {
+        name: metadata.name,
+        description: metadata.description.trim().replace(/\s+/g, " "),
+    };
+}

package/dist/skill-routing.d.ts

@@ -0,0 +1,2 @@
+/** Instruction links have already been made relative to their destination. */
+export declare function renderSkillRouting(rows: string[]): string[];

package/dist/skill-routing.js

@@ -0,0 +1,36 @@
+const tasksBySkill = {
+    "penpair-setup": "Install Penpair or repair a Penpot connection",
+    "penpair-design": "Inspect, edit, audit or export a Penpot file",
+    "penpair-recipes": "Build a Penpot screen or derive a state variant from an approved frame",
+    "design-judgment": "Choose or critique hierarchy, density and screen states",
+    "penpair-handoff": "Implement a frontend from an approved Penpot design",
+    "penpair-verify": "Compare a frontend with its approved design or recheck visual fixes",
+};
+/** Instruction links have already been made relative to their destination. */
+export function renderSkillRouting(rows) {
+    const routes = [];
+    for (const row of rows) {
+        const match = /^\| \[([a-z0-9-]+)\]\(([^)]+)\) \|/.exec(row);
+        if (!match) {
+            continue;
+        }
+        const name = match[1];
+        const task = tasksBySkill[name];
+        if (task) {
+            routes.push(`| ${task} | [${name}](${match[2]}) |`);
+        }
+    }
+    if (!routes.length) {
+        return [];
+    }
+    return [
+        "Before working on a matching task, read the linked SKILL.md and follow its relevant workflow before running design or implementation tools.",
+        "Briefly name the selected skill and its purpose when starting or changing workflow; report actual evidence separately from the intention to use a skill.",
+        "Use the smallest applicable set of skills; follow a linked companion only when the task reaches that stage. Skill selection does not authorize additional writes or replace owner approval.",
+        "",
+        "| Task | Read first |",
+        "| --- | --- |",
+        ...routes,
+        "",
+    ];
+}

package/dist/skills.js

@@ -1,25 +1,38 @@
 import { atomicWriteFile } from "./atomic-output.js";
 import { resolveProjectOutput } from "./project-input.js";
-import { planSkillInstructions, applySkillInstructions } from "./skill-instructions.js";
+import { planSkillInstructions, applySkillInstructions, } from "./skill-instructions.js";
 import { lstat, mkdir, readdir, readFile, symlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseSkillMetadata } from "./skill-metadata.js";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export const bundledSkillsDirectory = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../skills");
 /** Files a project fills in. They are written once and never replaced, not even with --force. */
-const projectOwned = new Set(["references/project-facts.md", "PROJECT.md"]);
+const projectOwned = new Set([
+    "references/project-facts.md",
+    "PROJECT.md",
+]);
 export async function listBundledSkills(directory = bundledSkillsDirectory()) {
-    const entries = await readdir(directory, { withFileTypes: true });
-    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    const entries = await readdir(directory, {
+        withFileTypes: true,
+    });
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
 }
 async function filesUnder(directory, prefix = "") {
     const out = [];
-    for (const entry of await readdir(path.join(directory, prefix), { withFileTypes: true })) {
+    for (const entry of await readdir(path.join(directory, prefix), {
+        withFileTypes: true,
+    })) {
         const relative = path.posix.join(prefix, entry.name);
-        if (entry.isDirectory())
+        if (entry.isDirectory()) {
             out.push(...(await filesUnder(directory, relative)));
-        else
+        }
+        else {
             out.push(relative);
+        }
     }
     return out.sort();
 }
@@ -28,8 +41,9 @@ async function readIfExists(file) {
         return await readFile(file, "utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return undefined;
+        }
         throw error;
     }
 }
@@ -39,27 +53,41 @@ async function exists(file) {
         return true;
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return false;
+        }
         throw error;
     }
 }
 /** The skill's name and the first sentence of its description, from the frontmatter, for a row in a project's agent guide. */
 export async function describeSkill(skillDirectory) {
     const text = (await readIfExists(path.join(skillDirectory, "SKILL.md"))) ?? "";
-    const name = /^name:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? path.basename(skillDirectory);
-    const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
-    return { name, summary: description.split(/(?<=\.)\s/)[0] ?? description };
+    const { name, description } = parseSkillMetadata(text, path.basename(skillDirectory));
+    return {
+        name,
+        summary: description.split(/(?<=\.)\s/)[0] ?? description,
+    };
 }
 /** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
-export const renamedSkills = { "penpot-design": "penpair-design" };
+export const renamedSkills = {
+    "penpot-design": "penpair-design",
+};
 /** Where the penpair skills already live in a project as real folders (not links), so a later install goes to the same place. */
 export async function existingSkillsFolder(root) {
-    for (const folder of [".skills", ".claude/skills", ".agents/skills"]) {
-        for (const name of ["penpair-design", "penpair-setup", ...Object.keys(renamedSkills)]) {
+    for (const folder of [
+        ".skills",
+        ".claude/skills",
+        ".agents/skills",
+    ]) {
+        for (const name of [
+            "penpair-design",
+            "penpair-setup",
+            ...Object.keys(renamedSkills),
+        ]) {
             const found = await lstat(path.join(root, folder, name)).catch(() => undefined);
-            if (found?.isDirectory())
+            if (found?.isDirectory()) {
                 return folder;
+            }
         }
     }
     return undefined;
@@ -70,16 +98,38 @@ export async function installSkills(options) {
     await resolveProjectOutput(options.root, to);
     const names = await listBundledSkills(source);
     const chosen = options.only ?? names;
-    for (const name of chosen)
-        if (!names.includes(name))
+    for (const name of chosen) {
+        if (!names.includes(name)) {
             throw new Error(`no skill named ${name}; shipped: ${names.join(", ")}`);
+        }
+    }
     const rows = await Promise.all(chosen.map(async (name) => {
         const { summary } = await describeSkill(path.join(source, name));
-        const link = path.posix.join(to, name, "SKILL.md").split("/").map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`)).join("/");
+        const link = path.posix
+            .join(to, name, "SKILL.md")
+            .split("/")
+            .map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/");
         return `| [${name}](${link}) | ${summary.replace(/\|/g, "\\|")} |`;
     }));
     const instructionPlan = await planSkillInstructions(options.root, rows, options.agents);
-    const report = { to, installed: [], unchanged: [], kept: [], linked: [], agentsRows: rows, legacy: [], instructions: instructionPlan.report, ...(options.dryRun ? { dryRun: true, wouldInstall: [], wouldLink: [] } : {}) };
+    const report = {
+        to,
+        installed: [],
+        unchanged: [],
+        kept: [],
+        linked: [],
+        agentsRows: rows,
+        legacy: [],
+        instructions: instructionPlan.report,
+        ...(options.dryRun
+            ? {
+                dryRun: true,
+                wouldInstall: [],
+                wouldLink: [],
+            }
+            : {}),
+    };
     const writes = new Map();
     const links = [];
     for (const name of chosen) {
@@ -89,56 +139,96 @@ export async function installSkills(options) {
             const shipped = await readFile(path.join(from, file), "utf8");
             const present = await readIfExists(target);
             const label = path.posix.join(to, name, file);
-            if (present === shipped)
+            if (present === shipped) {
                 report.unchanged.push(label);
-            else if (present === undefined || options.force && !projectOwned.has(file))
-                writes.set(target, { label, before: present, content: shipped });
-            else
+            }
+            else if (present === undefined || (options.force && !projectOwned.has(file))) {
+                writes.set(target, {
+                    label,
+                    before: present,
+                    content: shipped,
+                });
+            }
+            else {
                 report.kept.push(label);
+            }
         }
-        if (options.links !== false)
-            for (const hub of [".agents/skills", ".claude/skills"]) {
+        if (options.links !== false) {
+            for (const hub of [
+                ".agents/skills",
+                ".claude/skills",
+            ]) {
                 const link = path.join(options.root, hub, name);
-                if (path.resolve(link) === path.resolve(options.root, to, name) || await exists(link))
+                if (path.resolve(link) === path.resolve(options.root, to, name) || (await exists(link))) {
                     continue;
+                }
                 const safe = await resolveProjectOutput(options.root, path.join(hub, name));
                 const target = await resolveProjectOutput(options.root, path.join(to, name));
-                if (safe === target)
+                if (safe === target) {
                     continue;
-                links.push({ file: safe, target: path.relative(path.dirname(safe), target), label: path.posix.join(hub, name) });
+                }
+                links.push({
+                    file: safe,
+                    target: path.relative(path.dirname(safe), target),
+                    label: path.posix.join(hub, name),
+                });
             }
+        }
     }
     for (const [oldName, newName] of Object.entries(renamedSkills)) {
-        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName))))
+        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName)))) {
             continue;
+        }
         const oldFacts = await readIfExists(await resolveProjectOutput(options.root, path.join(to, oldName, "references/project-facts.md")));
         const newFactsFile = await resolveProjectOutput(options.root, path.join(to, newName, "references/project-facts.md"));
         const template = await readIfExists(path.join(source, newName, "references/project-facts.md"));
-        const current = writes.get(newFactsFile)?.content ?? await readIfExists(newFactsFile);
+        const current = writes.get(newFactsFile)?.content ?? (await readIfExists(newFactsFile));
         const carriedFacts = oldFacts !== undefined && oldFacts !== template && current === template;
-        if (carriedFacts)
-            writes.set(newFactsFile, { label: path.posix.join(to, newName, "references/project-facts.md"), before: await readIfExists(newFactsFile), content: oldFacts });
-        report.legacy.push({ folder: path.posix.join(to, oldName), renamedTo: newName, carriedFacts: carriedFacts && !options.dryRun });
+        if (carriedFacts) {
+            writes.set(newFactsFile, {
+                label: path.posix.join(to, newName, "references/project-facts.md"),
+                before: await readIfExists(newFactsFile),
+                content: oldFacts,
+            });
+        }
+        report.legacy.push({
+            folder: path.posix.join(to, oldName),
+            renamedTo: newName,
+            carriedFacts: carriedFacts && !options.dryRun,
+        });
     }
     if (options.dryRun) {
-        report.wouldInstall = [...writes.values()].map((write) => write.label);
+        report.wouldInstall = [
+            ...writes.values(),
+        ].map((write) => write.label);
         report.wouldLink = links.map((link) => link.label);
         return report;
     }
     for (const [file, write] of writes) {
-        if (await readIfExists(file) !== write.before)
+        if ((await readIfExists(file)) !== write.before) {
             throw new Error("A skill file changed after planning; nothing overwrote that file");
-        await mkdir(path.dirname(file), { recursive: true });
-        await atomicWriteFile(file, write.content, { replace: write.before !== undefined, mode: write.before === undefined ? 0o644 : (await lstat(file)).mode & 0o777 });
+        }
+        await mkdir(path.dirname(file), {
+            recursive: true,
+        });
+        await atomicWriteFile(file, write.content, {
+            replace: write.before !== undefined,
+            mode: write.before === undefined ? 0o644 : (await lstat(file)).mode & 0o777,
+        });
         report.installed.push(write.label);
     }
     for (const link of links) {
-        await mkdir(path.dirname(link.file), { recursive: true });
+        await mkdir(path.dirname(link.file), {
+            recursive: true,
+        });
         await symlink(link.target, link.file);
         report.linked.push(link.label);
     }
-    if (instructionPlan.report.path)
-        await mkdir(path.dirname(instructionPlan.report.path), { recursive: true });
+    if (instructionPlan.report.path) {
+        await mkdir(path.dirname(instructionPlan.report.path), {
+            recursive: true,
+        });
+    }
     report.instructions = await applySkillInstructions(instructionPlan);
     return report;
 }

package/dist/snippet.js

@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer";
-import { executeCode, maxSnippetBytes, UncertainExecutionError } from "./client.js";
+import { executeCode, maxSnippetBytes, UncertainExecutionError, } from "./client.js";
 import { PenpairError } from "./errors.js";
 /**
  * Wraps snippet body text for the Penpot editor: the parameters arrive as `CFG`, and any error comes back as
@@ -13,9 +13,14 @@ export const requirePage = `if (CFG.page && penpot.currentFile?.pages?.filter((p
 if (CFG.page && penpot.currentPage.name !== CFG.page) return { ok: false, wrongPage: true, current: penpot.currentPage.name, message: "the editor shows " + penpot.currentPage.name + ", not " + CFG.page };`;
 export function snippet(name, body, params = {}, effect = "unknown") {
     const code = wrap(body, params);
-    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
+    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes) {
         throw new PenpairError("snippet-too-large", `Snippet ${name} is ${Buffer.byteLength(code, "utf8")} bytes`);
-    return { name, code, effect };
+    }
+    return {
+        name,
+        code,
+        effect,
+    };
 }
 /** Whether the plugin source is valid JavaScript for an async function. Catches typos without a Penpot connection. */
 export function compiles(code) {
@@ -30,12 +35,27 @@ export function compiles(code) {
 }
 /** Runs a snippet and returns its result record. A snippet that reports `ok: false` throws, except a wrong page, which the caller handles. */
 export async function runSnippet(client, s, options) {
-    const { result, runId, metrics } = await executeCode(client, s.code, { effect: s.effect, ...options });
-    const record = typeof result === "object" && result !== null && !Array.isArray(result) ? result : { value: result };
+    const { result, runId, metrics } = await executeCode(client, s.code, {
+        effect: s.effect,
+        ...options,
+    });
+    const record = typeof result === "object" && result !== null && !Array.isArray(result)
+        ? result
+        : {
+            value: result,
+        };
     if (record.ok === false && !record.wrongPage) {
-        if ((options?.effect ?? s.effect) !== "read")
+        if ((options?.effect ?? s.effect) !== "read") {
             throw new UncertainExecutionError(runId, `${s.name}: ${record.message ?? "failed"}`);
+        }
         throw new PenpairError("tool-failed", `${s.name}: ${record.message ?? "failed"}`);
     }
-    return { ...record, execution: { runId, outcome: "ran", metrics } };
+    return {
+        ...record,
+        execution: {
+            runId,
+            outcome: "ran",
+            metrics,
+        },
+    };
 }

package/dist/snippets/read.js

@@ -10,7 +10,9 @@ export function switchPage(name) {
 if (!target) return { ok: false, message: "no page named " + CFG.name };
 if (penpot.currentPage.id === target.id) return { ok: true, alreadyThere: true };
 penpot.openPage(target);
-return { ok: true, switched: true };`, { name });
+return { ok: true, switched: true };`, {
+        name,
+    });
 }
 /** The top-level frames of a page: id, name and size, so they can be found by name and exported. */
 export function frames(params) {
@@ -20,8 +22,12 @@ return { ok: true, readOnly: true, file: penpot.currentFile.name, fileId: penpot
 }
 /** One line per shape: type, name, size, position on the page, layout and sizing, the text it carries. */
 export function tree(params) {
-    if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1000) || params.depth !== undefined && (!Number.isInteger(params.depth) || params.depth < 0 || params.depth > 100))
+    if ((params.limit !== undefined &&
+        (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1000)) ||
+        (params.depth !== undefined &&
+            (!Number.isInteger(params.depth) || params.depth < 0 || params.depth > 100))) {
         throw new Error("Readable tree budgets require limit 1..1000 and depth 0..100; use inspect for larger structured scopes");
+    }
     return readSnippet("tree", `${requirePage}
 const depth=CFG.depth===undefined?3:CFG.depth,limit=CFG.limit||400,lines=[];
 let depthLimited=false,textLimited=false,labelLimited=false;

package/dist/structure-snapshot.d.ts

@@ -48,8 +48,20 @@ export interface StructuralManifest {
 export declare const structuralJson: (value: unknown) => string;
 export declare function structuralPage(raw: InspectionDocument, name: string): StructuralPage;
 export declare function assembleStructuralSnapshot(pages: StructuralPage[], rawTokens: InspectionDocument): StructuralSnapshot;
+export interface SnapshotProgress {
+    pageId: string;
+    stage: "start" | "complete";
+    elapsedMs: number;
+}
+export declare class SnapshotCaptureError extends Error {
+    readonly progress: SnapshotProgress[];
+    readonly restorationError?: string | undefined;
+    constructor(message: string, progress: SnapshotProgress[], restorationError?: string | undefined);
+}
 export declare function captureStructuralSnapshot(client: PenpotToolClient, options?: ExecuteOptions & {
     signal?: AbortSignal;
+    onStep?: (message: string) => void;
+    onProgress?: (event: SnapshotProgress) => void;
 }): Promise<StructuralSnapshot>;
 export declare function writeStructuralSnapshot(root: string, out: string, snapshot: StructuralSnapshot, redact?: (text: string) => string): Promise<StructuralManifest>;
 export declare function readStructuralSnapshot(root: string, folder: string): Promise<StructuralSnapshot>;