@penpair/core 0.1.2 → 0.2.0

package/dist/export.js

@@ -1,3 +1,6 @@
+import { waitForStableLayout } from "./layout.js";
+import { PenpairError } from "./errors.js";
+import { commandSleep } from "./command-result.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { snippet, requirePage } from "./snippet.js";
@@ -5,18 +8,41 @@ import { runOnPage } from "./operation.js";
 const exportSnippet = (shapeId, scale, page) => snippet("export", `${requirePage}
 const s = penpot.currentPage.getShapeById(CFG.id);
 if (!s) return { ok: false, message: "no shape " + CFG.id + " on " + penpot.currentPage.name };
+const active = (penpot.library?.local?.tokens?.themes || []).filter(t=>t.active);
+const capture = {designSize:{width:s.width,height:s.height},activeThemeIds:active.every(t=>typeof t.id==="string"&&t.id)?active.map(t=>t.id).sort():null,fileId:penpot.currentFile.id, pageId:penpot.currentPage.id, frameId:s.id, revision:penpot.currentFile.revn, scale:CFG.scale,
+  penpotApiVersion:typeof penpot.version === "string" ? penpot.version : null,
+  renderEnvironment:typeof navigator !== "undefined" ? navigator.userAgent : null,
+  activeThemes:(penpot.library?.local?.tokens?.themes || []).filter(t=>t.active).map(t=>t.group+"/"+t.name).sort()};
+const geometry = JSON.stringify([s.x,s.y,s.width,s.height]);
 const bytes = await s.export({ type: "png", scale: CFG.scale });
+const afterShape = penpot.currentPage.getShapeById(CFG.id);
+if (penpot.currentFile.id !== capture.fileId || penpot.currentPage.id !== capture.pageId || penpot.currentFile.revn !== capture.revision || !afterShape || afterShape.id !== capture.frameId || JSON.stringify([afterShape.x,afterShape.y,afterShape.width,afterShape.height]) !== geometry)
+ return {ok:false, message:"Export source changed during capture"};
 let bin = ""; for (let i = 0; i < bytes.length; i += 8192) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
-return { ok: true, base64: btoa(bin), length: bytes.length };`, { id: shapeId, scale, page });
-const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+return { ok: true, base64: btoa(bin), length: bytes.length, capture };`, { id: shapeId, scale, page }, "read");
+const defaultSleep = commandSleep;
 /** Exports one shape as PNG. A first call can fail once and then work; this retries, and by default waits for a stable render. */
 export async function exportShapePng(client, shapeId, options = {}) {
     const { page, scale = 1, attempts = 3, stable = true, maxExports = 4, sleep = defaultSleep } = options;
+    if (!Number.isFinite(scale) || scale <= 0 || scale > 8 || !Number.isInteger(attempts) || attempts < 1 || attempts > 10 || !Number.isInteger(maxExports) || maxExports < (stable ? 2 : 1) || maxExports > 20)
+        throw new Error("Invalid export scale/attempt limits");
     const once = async () => {
         for (let attempt = 1;; attempt++) {
             try {
                 const record = await runOnPage(client, exportSnippet(shapeId, scale, page), page, options);
-                return Buffer.from(String(record.base64), "base64");
+                const capture = record.capture;
+                if (!capture || typeof capture.fileId !== "string" || !capture.fileId || typeof capture.pageId !== "string" || !capture.pageId || capture.frameId !== shapeId || !Number.isInteger(capture.revision) || capture.scale !== scale || !Array.isArray(capture.activeThemes))
+                    throw new Error("Export did not return target provenance");
+                if (capture.designSize && (![capture.designSize.width, capture.designSize.height].every(value => Number.isFinite(value) && value >= 0)))
+                    throw new Error("Export has malformed design dimensions");
+                if (capture.activeThemeIds !== undefined && capture.activeThemeIds !== null && (!Array.isArray(capture.activeThemeIds) || capture.activeThemeIds.some(id => typeof id !== "string" || !id) || new Set(capture.activeThemeIds).size !== capture.activeThemeIds.length))
+                    throw new Error("Export has malformed active theme identity");
+                if (typeof record.base64 !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(record.base64))
+                    throw new Error("Invalid export byte encoding");
+                const png = Buffer.from(record.base64, "base64");
+                if (!png.length || png.length !== record.length)
+                    throw new Error("Export byte length does not match its evidence");
+                return { png, capture };
             }
             catch (error) {
                 if (attempt >= attempts)
@@ -26,15 +52,24 @@ export async function exportShapePng(client, shapeId, options = {}) {
         }
     };
     let previous = await once();
+    let layout;
+    if (options.layout !== false) {
+        layout = await waitForStableLayout(client, { shapeId, sleep, ...options.layout });
+        if (!layout.stable)
+            throw new PenpairError("incomplete-output", `Layout did not settle before export: ${layout.reason ?? "unknown reason"}`);
+    }
     if (!stable)
-        return { png: previous, stable: false, exports: 1 };
+        return { layout, ...previous, stable: false, exports: 1 };
     const hash = (buffer) => createHash("sha256").update(buffer).digest("hex");
     for (let count = 2; count <= maxExports; count++) {
         await sleep(2_000);
         const next = await once();
-        if (hash(next) === hash(previous))
-            return { png: next, stable: true, exports: count };
+        const identity = ({ designSize: _size, ...value }) => value;
+        if (JSON.stringify(identity(next.capture)) !== JSON.stringify(identity(previous.capture)))
+            throw new Error("Export identity, revision or render environment changed between captures");
+        if (JSON.stringify(next.capture.designSize ?? null) === JSON.stringify(previous.capture.designSize ?? null) && hash(next.png) === hash(previous.png))
+            return { layout, ...next, stable: true, exports: count };
         previous = next;
     }
-    return { png: previous, stable: false, exports: maxExports };
+    return { layout, ...previous, stable: false, exports: maxExports };
 }

package/dist/file-archive.d.ts

@@ -0,0 +1,16 @@
+import type { PenpotToolClient } from "./client.js";
+export type FileArchive = {
+    status: "exported";
+    bytes: Buffer;
+    fileId: string;
+    revn: number;
+    sha256: string;
+    restoreVerified: false;
+} | {
+    status: "unsupported" | "failed" | "too-large" | "changed";
+    message: string;
+};
+/** Full-fidelity recovery is established by import/readback, not by receiving archive bytes. */
+export declare function exportFileArchive(client: PenpotToolClient, options?: {
+    maxBytes?: number;
+}): Promise<FileArchive>;

package/dist/file-archive.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { runSnippet, snippet } from "./snippet.js";
+import { redactEndpoint } from "./endpoint.js";
+/** Full-fidelity recovery is established by import/readback, not by receiving archive bytes. */
+export async function exportFileArchive(client, options = {}) {
+    const maxBytes = options.maxBytes ?? 512 * 1024;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 16 * 1024 * 1024)
+        throw new Error("Archive budget must be positive and at most 16 MiB");
+    const result = await runSnippet(client, snippet("file-archive", `
+const file = penpot.currentFile, fileId = file.id, revn = file.revn;
+if (typeof file.export !== "function") return { ok: true, status: "unsupported", message: "File export is unavailable; use Penpot's File export menu" };
+let bytes;
+try { bytes = await file.export("penpot", "all"); }
+catch (error) { return { ok: true, status: "failed", message: "Archive export failed: " + String(error && error.message || error) + ". Use the manual export route." }; }
+if (penpot.currentFile.id !== fileId || penpot.currentFile.revn !== revn) return { ok: true, status: "changed", message: "The file changed during export; archive was not accepted" };
+if (!bytes || !Number.isSafeInteger(bytes.length) || bytes.length === 0) return { ok: true, status: "failed", message: "File export returned no archive bytes" };
+if (bytes.length > CFG.maxBytes) return { ok: true, status: "too-large", message: "Archive exceeds the configured response budget; export it manually" };
+let binary = "";
+for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
+return { ok: true, status: "exported", fileId, revn, length: bytes.length, base64: btoa(binary) };`, { maxBytes }, "read"));
+    if (result.status !== "exported") {
+        if (!["unsupported", "failed", "too-large", "changed"].includes(String(result.status)) || typeof result.message !== "string")
+            throw new Error("Archive response contained no valid outcome");
+        return { status: result.status, message: redactEndpoint(result.message) };
+    }
+    if (result.ok !== true || typeof result.fileId !== "string" || !Number.isInteger(result.revn) || typeof result.base64 !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(result.base64))
+        throw new Error("Archive response contained incomplete metadata");
+    const bytes = Buffer.from(result.base64, "base64");
+    if (bytes.length === 0 || bytes.length > maxBytes || bytes.length !== result.length)
+        throw new Error("Archive response was empty, truncated or over budget");
+    return { status: "exported", bytes, fileId: result.fileId, revn: Number(result.revn), sha256: createHash("sha256").update(bytes).digest("hex"), restoreVerified: false };
+}

package/dist/file-guard.d.ts

@@ -0,0 +1,8 @@
+import { type PenpotToolClient } from "./client.js";
+import type { ProjectFile } from "./instance/config.js";
+/** A guard in the delivered execution closes the gap between a connection check and a later batch. */
+export declare function guardFile(client: PenpotToolClient, expected: ProjectFile | undefined, options?: {
+    mode?: "strict" | "warn";
+    anyFile?: boolean;
+    warn?: (message: string) => void;
+}): PenpotToolClient;

package/dist/file-guard.js

@@ -0,0 +1,40 @@
+import { executionEnvelope, maxSnippetBytes } from "./client.js";
+import { PenpairError } from "./errors.js";
+/** A guard in the delivered execution closes the gap between a connection check and a later batch. */
+export function guardFile(client, expected, options = {}) {
+    if (!expected || options.anyFile) {
+        options.warn?.(options.anyFile ? "--any-file overrides the project's file guard for this run." : "No file ID is pinned. Run `penpair connect --pin-file` to protect this project's file.");
+        return client;
+    }
+    const warningPrefix = "penpair-file-warning: ";
+    return {
+        ...client,
+        close: () => client.close(),
+        ...(client.listTools ? { listTools: () => client.listTools() } : {}),
+        async callTool(name, args, callOptions) {
+            if (name !== "execute_code" || typeof args.code !== "string")
+                throw new PenpairError("file-mismatch", "The file guard only permits guarded execute_code calls.");
+            const guard = `{ const __penpairExpectedFile = ${JSON.stringify(expected)};
+const __penpairActualFile = penpot.currentFile;
+if (!__penpairActualFile || __penpairActualFile.id !== __penpairExpectedFile.id) {
+  const message = "Expected file " + (__penpairExpectedFile.name || __penpairExpectedFile.id) + " (" + __penpairExpectedFile.id + "), connected to " + (__penpairActualFile ? __penpairActualFile.name + " (" + __penpairActualFile.id + ")" : "no file") + ". Open the expected file and reconnect, or explicitly use --any-file.";
+  ${options.mode === "warn" ? `console.warn(${JSON.stringify(warningPrefix)} + message);` : 'return { ok: false, fileMismatch: true, message };'}
+} }
+`;
+            const code = guard + args.code;
+            if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
+                throw new PenpairError("snippet-too-large", "The snippet including its file guard exceeds 90 KB");
+            const outcome = await client.callTool(name, { ...args, code }, callOptions);
+            const envelope = executionEnvelope(outcome);
+            const result = envelope?.result;
+            if (typeof result === "object" && result !== null && "fileMismatch" in result && result.fileMismatch === true)
+                throw new PenpairError("file-mismatch", String("message" in result ? result.message : "The connected file changed"));
+            if (typeof envelope?.log === "string") {
+                for (const line of envelope.log.split("\n"))
+                    if (line.includes(warningPrefix))
+                        options.warn?.(line.slice(line.indexOf(warningPrefix) + warningPrefix.length));
+            }
+            return outcome;
+        },
+    };
+}

package/dist/formats.d.ts

@@ -0,0 +1,4 @@
+/** Public envelope schemas; runtime validators additionally enforce hashes, identities, hierarchy and budgets. */
+export declare const artifactSchemas: Record<string, unknown>;
+/** Legacy unversioned config is v1; preserve every extension block and require explicit new output for persistence. */
+export declare function migrateProjectConfig(raw: unknown): Record<string, unknown>;

package/dist/formats.js

@@ -0,0 +1,28 @@
+import { projectConfigSchema } from "./instance/config-schema.js";
+import { validateProjectConfig } from "./instance/config.js";
+import { commandResultSchema } from "./command-result.js";
+const string = { type: "string" }, array = { type: "array" };
+const schema = (name, version, kind, properties, required = Object.keys(properties)) => ({ $schema: "https://json-schema.org/draft/2020-12/schema", $id: `urn:penpair:schema:v${version}:${name}`, title: `${name} v${version}`, type: "object", required: ["schemaVersion", ...(kind ? ["kind"] : []), ...required], properties: { schemaVersion: { const: version }, ...(kind ? { kind: { const: kind } } : {}), ...properties }, additionalProperties: true });
+/** Public envelope schemas; runtime validators additionally enforce hashes, identities, hierarchy and budgets. */
+export const artifactSchemas = {
+    "project-config": { ...projectConfigSchema, $id: "urn:penpair:schema:v1:project-config" },
+    "command-result": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "urn:penpair:schema:v1:command-result", ...commandResultSchema },
+    "inspection": schema("inspection", 1, undefined, { kind: { enum: ["shape-inspection", "token-inspection"] }, fileId: string, pageId: { type: ["string", "null"] }, revision: { type: "integer", minimum: 0 }, complete: { type: "boolean" }, counts: { type: "object" }, reasons: array, producer: { type: "object" } }),
+    "component-map": schema("component-map", 1, undefined, { components: { type: "array", maxItems: 1000, items: { type: "object", required: ["libraryId", "componentId", "codeComponent"], properties: { libraryId: string, componentId: string, codeComponent: string, props: { type: "object" }, textProps: { type: "object", additionalProperties: string } } } } }),
+    "design-spec": schema("design-spec", 1, "design-spec", { source: { type: "object" }, mappingHash: string, nodes: array, unknowns: array }),
+    "approvals": schema("approvals", 1, "design-approvals", { records: { type: "array", maxItems: 10000 } }),
+    "structural-manifest": schema("structural-manifest", 1, "structural-snapshot-manifest", { fileId: string, revision: { type: "integer" }, producer: string, fidelity: { const: "review-only" }, pages: { type: "array", minItems: 1, maxItems: 100 }, tokens: { type: "object" }, hash: string }),
+    "baseline-manifest": schema("baseline-manifest", 2, undefined, { complete: { type: "boolean" }, fileId: string, pageId: string, captureId: string, frames: { type: "array", maxItems: 1000 } }),
+    "portable-tokens": schema("portable-tokens", 1, "portable-tokens", { format: { const: "dtcg-2025.10-subset" }, tokens: { type: "array", minItems: 1, maxItems: 10000, items: { type: "object", required: ["path", "type", "value"], properties: { path: { type: "array", minItems: 1, maxItems: 32, items: string }, type: { enum: ["color", "dimension", "number", "fontFamily", "fontWeight", "typography"] }, value: {}, description: string, extensions: { type: "object" } } } }, groups: { type: "object" }, losses: { type: "array", maxItems: 0 } }),
+};
+/** Legacy unversioned config is v1; preserve every extension block and require explicit new output for persistence. */
+export function migrateProjectConfig(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("Config migration requires a JSON object");
+    const v = raw;
+    if (v.schemaVersion !== undefined && v.schemaVersion !== 1)
+        throw new Error("Unsupported project config major version; use the producer's documented migration before opening it");
+    const migrated = { ...structuredClone(v), schemaVersion: 1 };
+    validateProjectConfig(migrated);
+    return migrated;
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 export { version } from "./version.js";
 export * from "./adapters.js";
 export * from "./baselines.js";
-export { runCli } from "./cli-main.js";
+export { runCommand, runCli } from "./cli-main.js";
 export * from "./client.js";
+export { guardFile } from "./file-guard.js";
 export * from "./deep-check.js";
+export { runLiveSmoke } from "./live-smoke.js";
+export * from "./layout.js";
+export * from "./native-api.js";
+export * from "./file-archive.js";
+export { backupNoteCheck } from "./backup-note.js";
+export * from "./journal.js";
 export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
@@ -18,8 +25,33 @@ export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
 export * from "./instance/config.js";
+export { projectConfigSchema } from "./instance/config-schema.js";
 export * from "./instance/connection.js";
 export * from "./instance/gitignore.js";
 export { defaultInstanceName, init } from "./instance/init.js";
 export type { InitOptions, InitResult } from "./instance/init.js";
 export * from "./instance/runner.js";
+export { writeCoordinator, guardRevision, type WriteLease, type CoordinationOptions } from "./coordination.js";
+export { onboardingChecklist } from "./onboard.js";
+export { atomicWriteFile } from "./atomic-output.js";
+export { commandSleep, withCleanupDeadline, commandResultSchema, collectCommand, commandOutput, type CommandResult, type CommandFailure, type CommandOutput } from "./command-result.js";
+export { resolveProjectInput, resolveProjectOutput, designDataBlock } from "./project-input.js";
+export { planSkillInstructions, applySkillInstructions, type InstructionReport } from "./skill-instructions.js";
+export { parseCommandArgs, CommandArgumentError } from "./cli-arguments.js";
+export { findShapesByName, exportShapeByName, captureShots, type ShapeLookup, type ShapeMatch, type ShotsReport } from "./shots.js";
+export * from "./inspection.js";
+export { tokenTypes, validateEditableToken, validateTokenEdit, planTokenEdit, tokenEditOperation, type EditableToken, type TokenEdit, type TokenEditState, type TokenEditPlan } from "./token-edit.js";
+export { ensureGitignoreEntry } from "./instance/gitignore.js";
+export { prepareFileScript, runFileScript, type FileScriptOptions, type PreparedFileScript } from "./run-file.js";
+export { kit, coreKit, checkKits, loadKits, type BuildKit, type RecipeInfo } from "./kit.js";
+export { runKitSmoke, kitSmokeOperation } from "./kit-smoke.js";
+export { baselineCoverage, readBaselineCoverage, designCaseKey, type BaselineCoverage, type CoverageRow } from "./baseline-coverage.js";
+export * from "./design-spec.js";
+export * from "./mcp-server.js";
+export * from "./approvals.js";
+export * from "./structure-snapshot.js";
+export * from "./portable-tokens.js";
+export * from "./formats.js";
+export * from "./project-status.js";
+export * from "./audit-rules.js";
+export * from "./credentials.js";

package/dist/index.js

@@ -1,9 +1,16 @@
 export { version } from "./version.js";
 export * from "./adapters.js";
 export * from "./baselines.js";
-export { runCli } from "./cli-main.js";
+export { runCommand, runCli } from "./cli-main.js";
 export * from "./client.js";
+export { guardFile } from "./file-guard.js";
 export * from "./deep-check.js";
+export { runLiveSmoke } from "./live-smoke.js";
+export * from "./layout.js";
+export * from "./native-api.js";
+export * from "./file-archive.js";
+export { backupNoteCheck } from "./backup-note.js";
+export * from "./journal.js";
 export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
@@ -18,7 +25,32 @@ export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
 export * from "./instance/config.js";
+export { projectConfigSchema } from "./instance/config-schema.js";
 export * from "./instance/connection.js";
 export * from "./instance/gitignore.js";
 export { defaultInstanceName, init } from "./instance/init.js";
 export * from "./instance/runner.js";
+export { writeCoordinator, guardRevision } from "./coordination.js";
+export { onboardingChecklist } from "./onboard.js";
+export { atomicWriteFile } from "./atomic-output.js";
+export { commandSleep, withCleanupDeadline, commandResultSchema, collectCommand, commandOutput } from "./command-result.js";
+export { resolveProjectInput, resolveProjectOutput, designDataBlock } from "./project-input.js";
+export { planSkillInstructions, applySkillInstructions } from "./skill-instructions.js";
+export { parseCommandArgs, CommandArgumentError } from "./cli-arguments.js";
+export { findShapesByName, exportShapeByName, captureShots } from "./shots.js";
+export * from "./inspection.js";
+export { tokenTypes, validateEditableToken, validateTokenEdit, planTokenEdit, tokenEditOperation } from "./token-edit.js";
+export { ensureGitignoreEntry } from "./instance/gitignore.js";
+export { prepareFileScript, runFileScript } from "./run-file.js";
+export { kit, coreKit, checkKits, loadKits } from "./kit.js";
+export { runKitSmoke, kitSmokeOperation } from "./kit-smoke.js";
+export { baselineCoverage, readBaselineCoverage, designCaseKey } from "./baseline-coverage.js";
+export * from "./design-spec.js";
+export * from "./mcp-server.js";
+export * from "./approvals.js";
+export * from "./structure-snapshot.js";
+export * from "./portable-tokens.js";
+export * from "./formats.js";
+export * from "./project-status.js";
+export * from "./audit-rules.js";
+export * from "./credentials.js";

package/dist/inspection.d.ts

@@ -0,0 +1,106 @@
+import { type ExecutionMetrics, type PenpotToolClient } from "./client.js";
+export declare const inspectionFields: readonly ["geometry", "text", "layout", "component", "tokens", "style", "metadata"];
+export type InspectionField = typeof inspectionFields[number];
+export interface InspectionQuery {
+    kind?: "shape" | "tokens";
+    shapeId?: string;
+    page?: string;
+    fields?: InspectionField[];
+    depth?: number;
+    maxNodes?: number;
+    responseBytes?: number;
+    timeBudgetMs?: number;
+    documentBytes?: number;
+    cursor?: string;
+}
+export interface InspectionChunk {
+    schemaVersion: 1;
+    kind: "inspection-chunk";
+    fileId: string;
+    pageId: string | null;
+    revision: number;
+    queryHash: string;
+    digest: string;
+    digestAlgorithm: "cyrb53-change-detector";
+    sourceComplete: boolean;
+    offset: number;
+    nextOffset: number | null;
+    totalCodeUnits: number;
+    chunk: string;
+    nextCursor: string | null;
+    complete: boolean;
+    counts: Record<string, number | null>;
+    observationMs: number;
+    metrics: ExecutionMetrics;
+}
+export interface InspectionDocument {
+    schemaVersion: 1;
+    kind: "shape-inspection" | "token-inspection";
+    fileId: string;
+    pageId: string | null;
+    revision: number;
+    complete: boolean;
+    counts: Record<string, number | null>;
+    reasons: string[];
+    producer: {
+        name: string;
+        version: string;
+    };
+    nodes?: Record<string, unknown>[];
+    sets?: Record<string, unknown>[];
+    themes?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+export interface InspectionMetrics {
+    calls: number;
+    requestSnippetBytes: number;
+    responsePayloadBytes: number;
+    maxRequestSnippetBytes: number;
+    maxResponsePayloadBytes: number;
+    assembledBytes: number;
+    durationMs: number;
+}
+export type InspectionCapture = InspectionDocument & {
+    capturedAt: string;
+    sha256: string;
+    metrics: InspectionMetrics;
+};
+export interface PartialInspection {
+    schemaVersion: 1;
+    kind: "inspection-partial";
+    fileId: string | null;
+    pageId: string | null;
+    complete: false;
+    reason: string;
+    chunks: InspectionChunk[];
+    nextCursor: string | null;
+    metrics: InspectionMetrics;
+}
+export interface CaptureBudget {
+    maxCalls?: number;
+    maxTotalBytes?: number;
+    timeoutMs?: number;
+}
+export declare function validateInspectionQuery(query: InspectionQuery): {
+    queryHash: string;
+    producerVersion: string;
+    kind: "tokens" | "shape";
+    shapeId: string | undefined;
+    page: string | undefined;
+    fields: ("text" | "geometry" | "layout" | "component" | "tokens" | "style" | "metadata")[];
+    depth: number;
+    maxNodes: number;
+    responseBytes: number;
+    timeBudgetMs: number;
+    documentBytes: number;
+};
+export declare function inspectChunk(client: PenpotToolClient, query: InspectionQuery, requestTimeoutMs?: number): Promise<InspectionChunk>;
+/** Validate structural evidence independently of the transport envelope. Unknown API fields remain explicit nulls. */
+export declare function validateInspectionDocument(input: unknown): InspectionDocument;
+export declare function reassembleInspection(chunks: InspectionChunk[]): InspectionDocument;
+export declare function validateCaptureBudget(budget?: CaptureBudget): {
+    maxCalls: number;
+    maxTotalBytes: number;
+    timeoutMs: number;
+};
+export declare function captureInspection(client: PenpotToolClient, query: InspectionQuery, budget?: CaptureBudget): Promise<InspectionCapture | PartialInspection>;