@penpair/core 0.1.3 → 0.2.0

package/dist/skill-instructions.js

@@ -0,0 +1,75 @@
+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 -->";
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+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)))
+                candidates.push(name);
+        if (candidates.length !== 1)
+            return { report: { path: null, status: candidates.length ? "choice-required" : "not-selected", diff: "" } };
+        selected = candidates[0];
+    }
+    const canonicalRoot = await realpath(root);
+    const file = await resolveProjectOutput(canonicalRoot, selected);
+    let before;
+    try {
+        before = await readFile(file, "utf8");
+    }
+    catch (error) {
+        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))
+        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("/");
+        return `](${link})`;
+    }));
+    const block = [start, "| Skill | Purpose |", "| --- | --- |", ...relativeRows, end].join(newline);
+    let after;
+    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;
+    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 } };
+}
+export async function applySkillInstructions(plan) {
+    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")
+            throw error;
+    }
+    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" };
+}

package/dist/skills.d.ts

@@ -1,3 +1,4 @@
+import { type InstructionReport } from "./skill-instructions.js";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export declare const bundledSkillsDirectory: () => string;
 export declare function listBundledSkills(directory?: string): Promise<string[]>;
@@ -7,6 +8,8 @@ export declare function describeSkill(skillDirectory: string): Promise<{
     summary: string;
 }>;
 export interface InstallOptions {
+    agents?: string;
+    dryRun?: boolean;
     /** The project's root. */
     root: string;
     /** Where the skills go, relative to the root. */
@@ -23,6 +26,10 @@ export interface InstallOptions {
 /** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
 export declare const renamedSkills: Record<string, string>;
 export interface InstallReport {
+    instructions?: InstructionReport;
+    dryRun?: boolean;
+    wouldInstall?: string[];
+    wouldLink?: string[];
     /** The folder the skills went to, relative to the root. */
     to: string;
     installed: string[];

package/dist/skills.js

@@ -1,4 +1,7 @@
-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/`). */
@@ -24,8 +27,10 @@ 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 +38,10 @@ 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. */
@@ -60,58 +67,78 @@ 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;
+    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 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) {
+        if (options.links !== false)
             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;
-                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));
+                const safe = await resolveProjectOutput(options.root, path.join(hub, name));
+                const target = await resolveProjectOutput(options.root, path.join(to, name));
+                if (safe === target)
+                    continue;
+                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))))
             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 });
+            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,13 @@ 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)
         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 +30,12 @@ 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. */
@@ -13,53 +14,83 @@ 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}};`);
 }

package/dist/structure-snapshot.d.ts

@@ -0,0 +1,73 @@
+import { type InspectionDocument } from "./inspection.js";
+import type { ExecuteOptions, PenpotToolClient } from "./client.js";
+export interface StructuralPage {
+    schemaVersion: 1;
+    kind: "page-structure";
+    fileId: string;
+    pageId: string;
+    revision: number;
+    name: string;
+    nodes: Record<string, unknown>[];
+}
+export interface StructuralTokens {
+    schemaVersion: 1;
+    kind: "token-structure";
+    fileId: string;
+    revision: number;
+    sets: Record<string, unknown>[];
+    themes: Record<string, unknown>[];
+}
+export interface StructuralSnapshot {
+    schemaVersion: 1;
+    kind: "structural-snapshot";
+    fileId: string;
+    revision: number;
+    pages: StructuralPage[];
+    tokens: StructuralTokens;
+    fidelity: "review-only";
+}
+export interface StructuralManifest {
+    schemaVersion: 1;
+    kind: "structural-snapshot-manifest";
+    fileId: string;
+    revision: number;
+    producer: string;
+    fidelity: "review-only";
+    pages: Array<{
+        id: string;
+        name: string;
+        file: string;
+        hash: string;
+    }>;
+    tokens: {
+        file: "tokens.json";
+        hash: string;
+    };
+    hash: string;
+}
+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 declare function captureStructuralSnapshot(client: PenpotToolClient, options?: ExecuteOptions & {
+    signal?: AbortSignal;
+}): 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>;
+export declare function diffStructuralSnapshots(before: StructuralSnapshot, after: StructuralSnapshot, limit?: number): {
+    schemaVersion: number;
+    kind: string;
+    fileId: string;
+    beforeRevision: number;
+    afterRevision: number;
+    totalChanges: number;
+    complete: boolean;
+    changes: {
+        kind: string;
+        pageId?: string;
+        nodeId?: string;
+        before: unknown;
+        after: unknown;
+    }[];
+    fidelity: string;
+};
+export declare const renderStructuralDiff: (diff: ReturnType<typeof diffStructuralSnapshots>) => string;