@penpair/core 0.1.3 → 0.3.0

package/dist/skills.js

@@ -1,22 +1,37 @@
-import { lstat, mkdir, readdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { atomicWriteFile } from "./atomic-output.js";
+import { resolveProjectOutput } from "./project-input.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";
 /** 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();
 }
@@ -24,8 +39,11 @@ async function readIfExists(file) {
     try {
         return await readFile(file, "utf8");
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
     }
 }
 async function exists(file) {
@@ -33,8 +51,11 @@ async function exists(file) {
         await lstat(file);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        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. */
@@ -42,17 +63,31 @@ 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 };
+    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;
@@ -60,58 +95,140 @@ export async function existingSkillsFolder(root) {
 export async function installSkills(options) {
     const source = options.source ?? bundledSkillsDirectory();
     const to = options.to ?? (await existingSkillsFolder(options.root)) ?? ".skills";
+    await resolveProjectOutput(options.root, to);
     const names = await listBundledSkills(source);
-    const chosen = options.only ? options.only : names;
-    for (const name of chosen)
-        if (!names.includes(name))
+    const chosen = options.only ?? names;
+    for (const name of chosen) {
+        if (!names.includes(name)) {
             throw new Error(`no skill named ${name}; shipped: ${names.join(", ")}`);
-    const report = { to, installed: [], unchanged: [], kept: [], linked: [], agentsRows: [], legacy: [] };
+        }
+    }
+    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("/");
+        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 writes = new Map();
+    const links = [];
     for (const name of chosen) {
         const from = path.join(source, name);
         for (const file of await filesUnder(from)) {
-            const target = path.join(options.root, to, name, file);
+            const target = await resolveProjectOutput(options.root, path.join(to, name, file));
             const shipped = await readFile(path.join(from, file), "utf8");
             const present = await readIfExists(target);
             const label = path.posix.join(to, name, file);
-            if (present === undefined) {
-                await mkdir(path.dirname(target), { recursive: true });
-                await writeFile(target, shipped);
-                report.installed.push(label);
-            }
-            else if (present === shipped)
+            if (present === shipped) {
                 report.unchanged.push(label);
-            else if (options.force && !projectOwned.has(file)) {
-                await writeFile(target, shipped);
-                report.installed.push(label);
             }
-            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"]) {
+            for (const hub of [
+                ".agents/skills",
+                ".claude/skills",
+            ]) {
                 const link = path.join(options.root, hub, name);
-                if (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) {
                     continue;
-                await mkdir(path.dirname(link), { recursive: true });
-                await symlink(path.relative(path.dirname(link), path.join(options.root, to, name)), link);
-                report.linked.push(path.posix.join(hub, name));
+                }
+                links.push({
+                    file: safe,
+                    target: path.relative(path.dirname(safe), target),
+                    label: path.posix.join(hub, name),
+                });
             }
         }
-        const { summary } = await describeSkill(from);
-        report.agentsRows.push(`| [${name}](${path.posix.join(to, name, "SKILL.md")}) | ${summary} |`);
     }
     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;
-        // The project-facts file is the project's own work: carry it over when the new copy is still the empty template.
-        const oldFacts = await readIfExists(path.join(options.root, to, oldName, "references/project-facts.md"));
-        const newFactsFile = path.join(options.root, to, newName, "references/project-facts.md");
+        }
+        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 = await readIfExists(newFactsFile);
+        const current = writes.get(newFactsFile)?.content ?? (await readIfExists(newFactsFile));
         const carriedFacts = oldFacts !== undefined && oldFacts !== template && current === template;
-        if (carriedFacts)
-            await writeFile(newFactsFile, oldFacts);
-        report.legacy.push({ folder: path.posix.join(to, oldName), renamedTo: newName, carriedFacts });
+        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.wouldLink = links.map((link) => link.label);
+        return report;
+    }
+    for (const [file, write] of writes) {
+        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,
+        });
+        report.installed.push(write.label);
+    }
+    for (const link of links) {
+        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,
+        });
     }
+    report.instructions = await applySkillInstructions(instructionPlan);
     return report;
 }

package/dist/snippet.d.ts

@@ -1,6 +1,7 @@
 import { type ExecuteOptions, type PenpotToolClient } from "./client.js";
 /** Plugin source ready to send, with the parameters already injected. */
 export interface Snippet {
+    effect?: ExecuteOptions["effect"];
     name: string;
     code: string;
 }
@@ -10,8 +11,8 @@ export interface Snippet {
  */
 export declare function wrap(body: string, params?: unknown): string;
 /** Plugin code for snippets that work on one page: they say so instead of acting on whatever page is open. */
-export declare const requirePage = "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 declare function snippet(name: string, body: string, params?: unknown): Snippet;
+export declare const requirePage = "if (CFG.page && penpot.currentFile?.pages?.filter((p) => p.name === CFG.page).length > 1) return { ok:false, message:\"page name is ambiguous; rename pages before selecting by name\" };\nif (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 declare function snippet(name: string, body: string, params?: unknown, effect?: ExecuteOptions["effect"]): Snippet;
 /** Whether the plugin source is valid JavaScript for an async function. Catches typos without a Penpot connection. */
 export declare function compiles(code: string): string | undefined;
 export interface SnippetResult {

package/dist/snippet.js

@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer";
-import { executeCode, maxSnippetBytes } 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
@@ -9,12 +9,18 @@ export function wrap(body, params = {}) {
     return `const CFG = ${JSON.stringify(params)};\ntry {\n${body}\n} catch (error) { return { ok: false, message: String(error && error.message || error) }; }`;
 }
 /** Plugin code for snippets that work on one page: they say so instead of acting on whatever page is open. */
-export const requirePage = `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 = {}) {
+export const requirePage = `if (CFG.page && penpot.currentFile?.pages?.filter((p) => p.name === CFG.page).length > 1) return { ok:false, message:"page name is ambiguous; rename pages before selecting by name" };
+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 };
+    }
+    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) {
@@ -29,9 +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 } = await executeCode(client, s.code, options);
-    const record = typeof result === "object" && result !== null ? result : { ok: true, value: result };
-    if (record.ok === false && !record.wrongPage)
+    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") {
+            throw new UncertainExecutionError(runId, `${s.name}: ${record.message ?? "failed"}`);
+        }
         throw new PenpairError("tool-failed", `${s.name}: ${record.message ?? "failed"}`);
-    return record;
+    }
+    return {
+        ...record,
+        execution: {
+            runId,
+            outcome: "ran",
+            metrics,
+        },
+    };
 }

package/dist/snippets/archive.d.ts

@@ -1,5 +1,14 @@
 import { type Snippet } from "../snippet.js";
 export interface ArchiveParams {
+    expectedPlan?: {
+        id: string;
+        name: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }[];
+    expectedArchiveId?: string | null;
     page: string;
     /** Name of the board the archived frames are nested into. */
     archiveName: string;

package/dist/snippets/archive.js

@@ -4,17 +4,21 @@ const select = `${requirePage}
 const top = penpot.currentPage.root.children;
 const isPart = (n) => CFG.partPrefixes.some((p) => n.startsWith(p));
 const isKept = (n) => CFG.keepPrefixes.some((p) => n.startsWith(p));
-const existing = top.find((c) => c.name === CFG.archiveName && c.type === "board");
+const archives = top.filter((c) => c.name === CFG.archiveName && c.type === "board");
+if (archives.length > 1) return { ok: false, message: "archive name is ambiguous" };
+const existing = archives[0];
 const candidates = top.filter((c) => c.type === "board" && c !== existing && !isPart(c.name) && !isKept(c.name));
 const plan = candidates.map((c) => ({ id: c.id, name: c.name, x: Math.round(c.x), y: Math.round(c.y), w: Math.round(c.width), h: Math.round(c.height) }));`;
 /** Read-only: what would move and what stays. */
 export function archiveInspect(params) {
     return snippet("archive-inspect", `${select}
-return { ok: true, readOnly: true, archiveExists: !!existing, willMove: plan.length, stays: top.filter((c) => c !== existing && !candidates.includes(c)).length, plan };`, params);
+return { ok: true, readOnly: true, archiveExists: !!existing, archiveId: existing ? existing.id : null, insideIds: existing ? existing.children.map((c) => c.id) : [], willMove: plan.length, stays: top.filter((c) => c !== existing && !candidates.includes(c)).length, plan };`, params);
 }
 /** One write: nests the frames in the archive board and moves the board aside. Safe to run again; frames already inside are not touched. */
 export function archiveApply(params) {
     return snippet("archive-apply", `${select}
+if (CFG.expectedPlan && JSON.stringify(plan) !== JSON.stringify(CFG.expectedPlan)) return { ok: false, message: "Archive source changed since inspection; no frames were moved" };
+if (Object.prototype.hasOwnProperty.call(CFG, "expectedArchiveId") && CFG.expectedArchiveId !== (existing ? existing.id : null)) return { ok: false, message: "Archive target changed since inspection; no frames were moved" };
 if (plan.length === 0) return { ok: true, moved: 0, archiveId: existing ? existing.id : null };
 const minX = Math.min(...plan.map((p) => p.x)), minY = Math.min(...plan.map((p) => p.y));
 const maxX = Math.max(...plan.map((p) => p.x + p.w)), maxY = Math.max(...plan.map((p) => p.y + p.h));
@@ -32,10 +36,12 @@ return { ok: true, submitted: true, moved: plan.length, archiveId: archive.id };
 export function archiveReadback(params) {
     return snippet("archive-readback", `${requirePage}
 const top = penpot.currentPage.root.children;
-const archive = top.find((c) => c.name === CFG.archiveName && c.type === "board");
+const archives = top.filter((c) => c.name === CFG.archiveName && c.type === "board");
+if (archives.length > 1) return { ok: false, message: "archive name is ambiguous" };
+const archive = archives[0];
 const inside = archive ? archive.children.map((c) => c.id) : [];
 const isPart = (n) => CFG.partPrefixes.some((p) => n.startsWith(p));
 const isKept = (n) => CFG.keepPrefixes.some((p) => n.startsWith(p));
 const loose = top.filter((c) => c !== archive && c.type === "board" && !isPart(c.name) && !isKept(c.name)).map((c) => c.name);
-return { ok: true, readOnly: true, archive: archive ? { id: archive.id, x: Math.round(archive.x), y: Math.round(archive.y), children: inside.length } : null, loose };`, params);
+return { ok: true, readOnly: true, archive: archive ? { id: archive.id, x: Math.round(archive.x), y: Math.round(archive.y), children: inside.length } : null, insideIds: inside, loose };`, params);
 }

package/dist/snippets/read.d.ts

@@ -28,5 +28,5 @@ export interface AuditParams {
 }
 /** Blank text, colours and strokes not bound to a token, children sticking out of their parent, gaps off the allowed steps. */
 export declare function audit(params: AuditParams): Snippet;
-/** Token sets (in order, with whether each is active) and themes. Object-valued tokens print as [object Object]; compare names for those. */
+/** Bounded typed preview. Use captureInspection(kind: tokens) for chunked complete evidence. */
 export declare function tokensDump(): Snippet;

package/dist/snippets/read.js

@@ -1,6 +1,7 @@
 import { requirePage, snippet } from "../snippet.js";
+const readSnippet = (name, body, params = {}) => snippet(name, body, params, "read");
 export function pages() {
-    return snippet("pages", `return { ok: true, readOnly: true, file: penpot.currentFile.name, revn: penpot.currentFile.revn, current: penpot.currentPage.name,
+    return readSnippet("pages", `return { ok: true, readOnly: true, file: penpot.currentFile.name, revn: penpot.currentFile.revn, current: penpot.currentPage.name,
   pages: penpot.currentFile.pages.map((p) => ({ id: p.id, name: p.name, count: p.root.children.length })) };`);
 }
 /** The editor can only change page between snippets: it switches, and the next snippet sees the new page. */
@@ -9,57 +10,93 @@ 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) {
-    return snippet("frames", `${requirePage}
-return { ok: true, readOnly: true, file: penpot.currentFile.name, revn: penpot.currentFile.revn, page: penpot.currentPage.name,
+    return readSnippet("frames", `${requirePage}
+return { ok: true, readOnly: true, file: penpot.currentFile.name, fileId: penpot.currentFile.id, revn: penpot.currentFile.revn, page: penpot.currentPage.name, pageId: penpot.currentPage.id,
   frames: penpot.currentPage.root.children.filter((c) => c.type === "board").map((c) => ({ id: c.id, name: c.name, width: Math.round(c.width), height: Math.round(c.height) })) };`, params);
 }
 /** One line per shape: type, name, size, position on the page, layout and sizing, the text it carries. */
 export function tree(params) {
-    return snippet("tree", `${requirePage}
-const depth = CFG.depth === undefined ? 3 : CFG.depth, limit = CFG.limit || 400, lines = [];
-const fx = (s) => (s.flex ? " flex:" + s.flex.dir + "/" + s.flex.horizontalSizing + "-" + s.flex.verticalSizing : "");
-const lc = (s) => (s.layoutChild ? " lc:" + (s.layoutChild.horizontalSizing || "") + "-" + (s.layoutChild.verticalSizing || "") + (s.layoutChild.absolute ? " ABS" : "") : "");
-const walk = (s, d) => {
-  if (d > depth || lines.length >= limit) return;
-  lines.push("  ".repeat(d) + s.type[0] + " " + s.name + " " + Math.round(s.width) + "x" + Math.round(s.height) + "@" + Math.round(s.x) + "," + Math.round(s.y) + fx(s) + lc(s) + (s.type === "text" ? " «" + (s.characters || "").slice(0, 24) + "»" : "") + (s.hidden ? " HIDDEN" : ""));
-  (s.children || []).forEach((c) => walk(c, d + 1));
-};
-penpot.currentPage.root.children.filter((c) => !CFG.namePrefix || c.name.startsWith(CFG.namePrefix)).forEach((c) => walk(c, 0));
-return { ok: true, readOnly: true, page: penpot.currentPage.name, lines, truncated: lines.length >= limit };`, 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))) {
+        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;
+const stack=[],roots=penpot.currentPage.root.children.filter(c=>!CFG.namePrefix||c.name.startsWith(CFG.namePrefix));
+for(let i=Math.min(roots.length,20000)-1;i>=0;i--)stack.push({shape:roots[i],depth:0});
+const fx=s=>s.flex?" flex:"+s.flex.dir+"/"+s.flex.horizontalSizing+"-"+s.flex.verticalSizing:"";
+const lc=s=>s.layoutChild?" lc:"+(s.layoutChild.horizontalSizing||"")+"-"+(s.layoutChild.verticalSizing||"")+(s.layoutChild.absolute?" ABS":""):"";
+while(stack.length&&lines.length<limit){
+  const item=stack.pop(),s=item.shape,name=String(s.name||""),text=String(s.characters||"");
+  if(name.length>200)labelLimited=true;if(s.type==="text"&&text.length>24)textLimited=true;
+  lines.push("  ".repeat(item.depth)+(s.type||"?")[0]+" "+s.id+" "+JSON.stringify(name.slice(0,200))+" "+Math.round(s.width)+"x"+Math.round(s.height)+"@"+Math.round(s.x)+","+Math.round(s.y)+fx(s)+lc(s)+(s.type==="text"?" «"+JSON.stringify(text.slice(0,24))+"»":"")+(s.hidden?" HIDDEN":""));
+  const children=s.children||[];
+  if(item.depth>=depth){if(children.length)depthLimited=true;continue;}
+  const take=Math.min(children.length,20000-stack.length);
+  if(take<children.length)depthLimited=true;
+  for(let i=take-1;i>=0;i--)stack.push({shape:children[i],depth:item.depth+1});
+}
+const truncated=stack.length>0||roots.length>20000||depthLimited||textLimited||labelLimited;
+return {ok:true,readOnly:true,page:penpot.currentPage.name,fileId:penpot.currentFile?.id??null,pageId:penpot.currentPage.id??null,revision:penpot.currentFile?.revn??null,lines,returnedLines:lines.length,depthLimit:depth,lineLimit:limit,truncated,complete:!truncated,limits:{depthLimited,textLimited,labelLimited,pendingBranches:stack.length}};`, params);
 }
 /** Blank text, colours and strokes not bound to a token, children sticking out of their parent, gaps off the allowed steps. */
 export function audit(params) {
-    return snippet("audit", `${requirePage}
-const frames = penpot.currentPage.root.children.filter((c) => c.name.startsWith(CFG.framePrefix));
-const skip = (n) => (CFG.ignoreUnbound || []).some((p) => n.startsWith(p));
-const out = {};
-for (const fr of frames) {
-  const f = { nodes: 0, texts: 0, blankText: 0, unboundFills: [], unboundStrokes: [], badSpacing: [], overflow: [] };
-  const walk = (s, parent) => {
-    f.nodes++;
-    const tk = s.tokens ? Object.keys(s.tokens) : [];
-    if (s.type === "text") { if (!(s.characters || "").trim()) f.blankText++; else f.texts++; }
-    else if (!skip(s.name) && s.fills && s.fills.some((x) => x.fillColor) && !tk.some((k) => k.startsWith("fill"))) f.unboundFills.push(s.name + ":" + s.fills[0].fillColor);
-    if (s.type !== "text" && !skip(s.name) && s.strokes && s.strokes.length && !tk.some((k) => k.startsWith("stroke"))) f.unboundStrokes.push(s.name);
-    if (s.flex && CFG.spacingSteps) for (const v of [s.flex.rowGap, s.flex.columnGap, s.flex.topPadding, s.flex.rightPadding, s.flex.bottomPadding, s.flex.leftPadding])
-      if (v !== undefined && v !== null && !CFG.spacingSteps.includes(Math.round(v))) f.badSpacing.push(s.name + ":" + v);
-    if (parent && parent.type === "board" && !(s.layoutChild && s.layoutChild.absolute) && (s.x + s.width > parent.x + parent.width + 1 || s.x < parent.x - 1)) f.overflow.push(s.name + " in " + parent.name);
-    (s.children || []).forEach((c) => { if (!c.hidden) walk(c, s); });
-  };
-  walk(fr, null);
-  for (const k of ["unboundFills", "unboundStrokes", "badSpacing", "overflow"]) f[k] = f[k].slice(0, 8);
-  out[fr.name] = f;
+    return readSnippet("audit", `${requirePage}
+const candidates=penpot.currentPage.root.children.filter(c=>c.name.startsWith(CFG.framePrefix)),frames=candidates.slice(0,20),out=Object.create(null);
+const skip=n=>(CFG.ignoreUnbound||[]).some(prefix=>n.startsWith(prefix));
+let visited=0,exampleBytes=0,partial=candidates.length>20;const deadline=Date.now()+5000;
+const size=text=>{let n=0;for(const c of text){const p=c.codePointAt(0);n+=p<128?1:p<2048?2:p<65536?3:4;}return n;};
+for(const fr of frames){
+  const f={id:fr.id,name:fr.name.slice(0,200),nodes:0,texts:0,blankText:0,unboundFills:[],unboundStrokes:[],badSpacing:[],overflow:[],totals:{unboundFills:0,unboundStrokes:0,badSpacing:0,overflow:0},truncated:fr.name.length>200,scanComplete:true};
+  const issue=(category,s,label)=>{f.totals[category]++;const example={id:s.id,label:String(label).slice(0,80)},bytes=size(JSON.stringify(example));if(f[category].length<8&&exampleBytes+bytes<=65536){f[category].push(example);exampleBytes+=bytes;}else f.truncated=true;if(String(label).length>80)f.truncated=true;};
+  const stack=[{shape:fr,parent:null}];
+  while(stack.length){
+    if(visited>=20000||Date.now()>deadline){f.scanComplete=false;f.truncated=true;partial=true;break;}
+    const {shape:s,parent}=stack.pop();visited++;f.nodes++;
+    const tk=Object.keys(s.tokens||{});
+    if(s.type==="text"){if(!(s.characters||"").trim())f.blankText++;else f.texts++;}
+    else if(!skip(s.name)&&s.fills&&s.fills.some(fill=>fill.fillColor)&&!tk.some(key=>key.startsWith("fill")))issue("unboundFills",s,s.name+":"+s.fills[0].fillColor);
+    if(s.type!=="text"&&!skip(s.name)&&s.strokes&&s.strokes.length&&!tk.some(key=>key.startsWith("stroke")))issue("unboundStrokes",s,s.name);
+    if(s.flex&&CFG.spacingSteps)for(const value of [s.flex.rowGap,s.flex.columnGap,s.flex.topPadding,s.flex.rightPadding,s.flex.bottomPadding,s.flex.leftPadding])if(value!==undefined&&value!==null&&!CFG.spacingSteps.includes(Math.round(value)))issue("badSpacing",s,s.name+":"+value);
+    if(parent&&parent.type==="board"&&!(s.layoutChild&&s.layoutChild.absolute)&&(s.x+s.width>parent.x+parent.width+1||s.x<parent.x-1))issue("overflow",s,s.name+" in "+parent.name);
+    const children=(s.children||[]).filter(child=>!child.hidden),take=Math.min(children.length,Math.max(0,20000-visited-stack.length));
+    if(take<children.length){f.scanComplete=false;f.truncated=true;partial=true;}
+    for(let i=take-1;i>=0;i--)stack.push({shape:children[i],parent:s});
+  }
+  f.totalNodes=f.scanComplete?f.nodes:null;out[fr.id]=f;
 }
-return { ok: true, readOnly: true, frames: out };`, params);
+const truncated=partial||Object.values(out).some(frame=>frame.truncated);
+return {ok:true,readOnly:true,schemaVersion:1,kind:"audit-preview",scope:{framePrefix:CFG.framePrefix,includeHiddenDescendants:false},frames:out,frameCount:candidates.length,returnedFrames:frames.length,visitedNodes:visited,countsComplete:!partial,truncated,complete:!truncated,budgets:{frames:20,nodes:20000,timeMs:5000,examplesPerCategory:8,exampleBytes:65536}};`, params);
 }
-/** Token sets (in order, with whether each is active) and themes. Object-valued tokens print as [object Object]; compare names for those. */
+/** Bounded typed preview. Use captureInspection(kind: tokens) for chunked complete evidence. */
 export function tokensDump() {
-    return snippet("tokens-dump", `const tokens = penpot.library.local.tokens;
-return { ok: true, readOnly: true,
-  sets: tokens.sets.map((s, i) => ({ order: i, name: s.name, active: !!s.active, tokens: s.tokens.map((t) => t.name + "=" + t.value) })),
-  themes: tokens.themes.map((t) => ({ group: t.group, name: t.name, active: !!t.active, sets: (t.activeSets || []).map((x) => (typeof x === "string" ? x : x.name)) })) };`);
+    return readSnippet("tokens-dump", `const tokens=penpot.library.local.tokens;
+const sets=[],themes=[];let records=0,bytes=1024,returnedTokens=0,complete=true;
+const size=(value)=>{let n=0;for(const c of JSON.stringify(value)){const p=c.codePointAt(0);n+=p<128?1:p<2048?2:p<65536?3:4;}return n;};
+outer:for(const [order,set] of tokens.sets.entries()){
+  const value={order,name:set.name,active:!!set.active,tokens:[]};
+  const count=size(value);
+  if(records>=5000||bytes+count>262144){complete=false;break;}
+  sets.push(value);records++;bytes+=count+1;
+  for(const t of set.tokens){
+    const token={name:t.name,value:t.value===undefined?null:t.value,type:t.type??null,description:t.description||"",unknowns:[...(t.type===undefined?["type"]:[]),...(t.value===undefined?["value"]:[])]},count=size(token);
+    if(records>=5000||bytes+count>262144){complete=false;break outer;}
+    value.tokens.push(token);records++;returnedTokens++;bytes+=count+1;
+  }
+}
+for(const theme of tokens.themes){
+  const value={group:theme.group,name:theme.name,active:!!theme.active,sets:(theme.activeSets||[]).map(s=>typeof s==="string"?s:s.name)},count=size(value);
+  if(records>=5000||bytes+count>262144){complete=false;break;}
+  themes.push(value);records++;bytes+=count+1;
+}
+return {ok:true,readOnly:true,schemaVersion:1,kind:"token-preview",fileId:penpot.currentFile.id,revision:penpot.currentFile.revn,complete,truncated:!complete,sets,themes,counts:{returnedTokens,totalTokens:complete?returnedTokens:null,setsTotal:tokens.sets.length,themesTotal:tokens.themes.length},previewBudget:{entities:5000,bytes:262144}};`);
 }