@penpair/core 0.2.0 → 0.3.0

package/dist/mcp-server.js

@@ -2,101 +2,414 @@ import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { runCommand } from "./cli-main.js";
 import { loadConfig } from "./instance/config.js";
 import { resolveProjectOutput } from "./project-input.js";
 import { collectCommand } from "./command-result.js";
 import { version } from "./version.js";
-const string = { type: "string", minLength: 1, maxLength: 1000 };
-const integer = (max) => ({ type: "integer", minimum: 0, maximum: max });
+const string = {
+    type: "string",
+    minLength: 1,
+    maxLength: 1000,
+};
+const integer = (max) => ({
+    type: "integer",
+    minimum: 0,
+    maximum: max,
+});
 const definitions = [
-    { name: "pages", description: "List pages in the pinned project file", properties: {}, required: [], command: () => ["pages"] },
-    { name: "tree", description: "Bounded tree preview; omitted nodes are explicit", properties: { page: string, depth: integer(100) }, required: ["page"], command: a => ["tree", "--page", String(a.page), "--depth", String(a.depth ?? 5)] },
-    { name: "audit", description: "Inspect layout/token findings with documented heuristic limits", properties: { page: string }, required: ["page"], command: a => ["audit", "--page", String(a.page)] },
-    { name: "inspect", description: "One bounded structured inspection chunk; use returned cursor for continuation", properties: { page: string, id: string, cursor: string }, required: ["page", "id"], command: a => ["inspect", String(a.id), "--page", String(a.page), ...(a.cursor ? ["--cursor", String(a.cursor)] : [])] },
-    { name: "tokens_dump", description: "Bounded token capture; completeness is explicit", properties: {}, required: [], command: () => ["tokens", "dump", "--max-total-bytes", "131072"] },
-    { name: "run_status", description: "Inspect an explicit local recovery journal", properties: { id: string }, required: ["id"], command: a => ["runs", String(a.id)] },
-    { name: "baselines_status", description: "Offline coverage/evidence status; no capture or approval", properties: {}, required: [], command: () => ["baselines", "coverage"] },
-    { name: "project_status", description: "Project health with explicit unknowns; no adapter imports", properties: {}, required: [], command: () => ["status"] },
-    { name: "doctor", description: "Project connection/file identity diagnostics", properties: {}, required: [], command: () => ["doctor"] },
-    { name: "design_spec", description: "Derived handoff for an exact frame ID; unknown semantics remain explicit", properties: { page: string, id: string }, required: ["page", "id"], command: a => ["spec", "--page", String(a.page), "--frame", String(a.id)] },
-    { name: "export", description: "Capture stable PNG to a relative path inside the project; creates a local file", properties: { page: string, id: string, out: string }, required: ["page", "id", "out"], command: a => ["export", String(a.id), String(a.out), "--page", String(a.page)], localWrite: true },
-    { name: "run_registered", description: "Execute a trusted registered operation: inspect by default, explicit apply and recovery for writes. Not a sandbox.", properties: { name: string, params: { type: "object", additionalProperties: { type: "string", maxLength: 4000 }, maxProperties: 100 }, apply: { type: "boolean", default: false }, resume: string, checkpoint: { type: "boolean", default: false } }, required: ["name"], write: true, command: a => ["run", String(a.name), ...Object.entries(a.params ?? {}).flatMap(([k, v]) => ["--param", `${k}=${v}`]), ...(a.apply ? ["--apply"] : []), ...(a.resume ? ["--resume", String(a.resume)] : []), ...(a.checkpoint ? ["--checkpoint"] : [])] },
+    {
+        name: "pages",
+        description: "List pages in the pinned project file",
+        properties: {},
+        required: [],
+        command: () => [
+            "pages",
+        ],
+    },
+    {
+        name: "tree",
+        description: "Bounded tree preview; omitted nodes are explicit",
+        properties: {
+            page: string,
+            depth: integer(100),
+        },
+        required: [
+            "page",
+        ],
+        command: (a) => [
+            "tree",
+            "--page",
+            String(a.page),
+            "--depth",
+            String(a.depth ?? 5),
+        ],
+    },
+    {
+        name: "audit",
+        description: "Inspect layout/token findings with documented heuristic limits",
+        properties: {
+            page: string,
+        },
+        required: [
+            "page",
+        ],
+        command: (a) => [
+            "audit",
+            "--page",
+            String(a.page),
+        ],
+    },
+    {
+        name: "inspect",
+        description: "One bounded structured inspection chunk; use returned cursor for continuation",
+        properties: {
+            page: string,
+            id: string,
+            cursor: string,
+        },
+        required: [
+            "page",
+            "id",
+        ],
+        command: (a) => [
+            "inspect",
+            String(a.id),
+            "--page",
+            String(a.page),
+            ...(a.cursor
+                ? [
+                    "--cursor",
+                    String(a.cursor),
+                ]
+                : []),
+        ],
+    },
+    {
+        name: "tokens_dump",
+        description: "Bounded token capture; completeness is explicit",
+        properties: {},
+        required: [],
+        command: () => [
+            "tokens",
+            "dump",
+            "--max-total-bytes",
+            "131072",
+        ],
+    },
+    {
+        name: "run_status",
+        description: "Inspect an explicit local recovery journal",
+        properties: {
+            id: string,
+        },
+        required: [
+            "id",
+        ],
+        command: (a) => [
+            "runs",
+            String(a.id),
+        ],
+    },
+    {
+        name: "baselines_status",
+        description: "Offline coverage/evidence status; no capture or approval",
+        properties: {},
+        required: [],
+        command: () => [
+            "baselines",
+            "coverage",
+        ],
+    },
+    {
+        name: "project_status",
+        description: "Project health with explicit unknowns; no adapter imports",
+        properties: {},
+        required: [],
+        command: () => [
+            "status",
+        ],
+    },
+    {
+        name: "doctor",
+        description: "Project connection/file identity diagnostics",
+        properties: {},
+        required: [],
+        command: () => [
+            "doctor",
+        ],
+    },
+    {
+        name: "design_spec",
+        description: "Derived handoff for an exact frame ID; unknown semantics remain explicit",
+        properties: {
+            page: string,
+            id: string,
+        },
+        required: [
+            "page",
+            "id",
+        ],
+        command: (a) => [
+            "spec",
+            "--page",
+            String(a.page),
+            "--frame",
+            String(a.id),
+        ],
+    },
+    {
+        name: "export",
+        description: "Capture stable PNG to a relative path inside the project; creates a local file",
+        properties: {
+            page: string,
+            id: string,
+            out: string,
+        },
+        required: [
+            "page",
+            "id",
+            "out",
+        ],
+        command: (a) => [
+            "export",
+            String(a.id),
+            String(a.out),
+            "--page",
+            String(a.page),
+        ],
+        localWrite: true,
+    },
+    {
+        name: "run_registered",
+        description: "Execute a trusted registered operation: inspect by default, explicit apply and recovery for writes. Not a sandbox.",
+        properties: {
+            name: string,
+            params: {
+                type: "object",
+                additionalProperties: {
+                    type: "string",
+                    maxLength: 4000,
+                },
+                maxProperties: 100,
+            },
+            apply: {
+                type: "boolean",
+                default: false,
+            },
+            resume: string,
+            checkpoint: {
+                type: "boolean",
+                default: false,
+            },
+        },
+        required: [
+            "name",
+        ],
+        write: true,
+        command: (a) => [
+            "run",
+            String(a.name),
+            ...Object.entries(a.params ?? {}).flatMap(([k, v]) => [
+                "--param",
+                `${k}=${v}`,
+            ]),
+            ...(a.apply
+                ? [
+                    "--apply",
+                ]
+                : []),
+            ...(a.resume
+                ? [
+                    "--resume",
+                    String(a.resume),
+                ]
+                : []),
+            ...(a.checkpoint
+                ? [
+                    "--checkpoint",
+                ]
+                : []),
+        ],
+    },
 ];
 function validate(def, raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         raw = {};
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("Tool arguments must be an object");
+    }
     const a = raw;
-    for (const key of def.required)
-        if (!(key in a))
+    for (const key of def.required) {
+        if (!(key in a)) {
             throw new Error(`Missing ${key}`);
+        }
+    }
     for (const [key, value] of Object.entries(a)) {
         const schema = def.properties[key];
-        if (!schema)
+        if (!schema) {
             throw new Error(`Unexpected tool argument ${key}`);
-        if (schema.type === "string" && (typeof value !== "string" || !value || value.startsWith("-") || value.length > (schema.maxLength ?? 1000) || /[\x00-\x1f]/.test(value)))
+        }
+        if (schema.type === "string" &&
+            (typeof value !== "string" ||
+                !value ||
+                value.startsWith("-") ||
+                value.length > (schema.maxLength ?? 1000) ||
+                /[\x00-\x1f]/.test(value))) {
             throw new Error(`Invalid ${key}`);
-        if (schema.type === "boolean" && typeof value !== "boolean")
+        }
+        if (schema.type === "boolean" && typeof value !== "boolean") {
             throw new Error(`Invalid ${key}`);
-        if (schema.type === "integer" && (!Number.isInteger(value) || Number(value) < 0 || Number(value) > schema.maximum))
+        }
+        if (schema.type === "integer" &&
+            (!Number.isInteger(value) || Number(value) < 0 || Number(value) > schema.maximum)) {
             throw new Error(`Invalid ${key}`);
-        if (key === "params" && (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length > 100 || Object.entries(value).some(([k, v]) => !/^[a-zA-Z][\w-]{0,100}$/.test(k) || typeof v !== "string" || v.length > 4000)))
+        }
+        if (key === "params" &&
+            (!value ||
+                typeof value !== "object" ||
+                Array.isArray(value) ||
+                Object.keys(value).length > 100 ||
+                Object.entries(value).some(([k, v]) => !/^[a-zA-Z][\w-]{0,100}$/.test(k) || typeof v !== "string" || v.length > 4000))) {
             throw new Error("Invalid registered parameters");
+        }
     }
-    if ((a.resume || a.checkpoint) && !a.apply)
+    if ((a.resume || a.checkpoint) && !a.apply) {
         throw new Error("Explicit resume requires apply");
+    }
     return a;
 }
 /** Long-lived server with an immutable explicit root and no process.chdir or raw-code tool. */
 export async function createMcpServer(options) {
-    if (!path.isAbsolute(options.root))
+    if (!path.isAbsolute(options.root)) {
         throw new Error("MCP project root must be absolute");
-    const root = await realpath(options.root), config = await loadConfig(root);
-    if (!config.file?.id)
+    }
+    const root = await realpath(options.root);
+    const config = await loadConfig(root);
+    if (!config.file?.id) {
         throw new Error("MCP server requires a configured owner-confirmed file pin");
-    const pinned = { instance: config.instance, fileId: config.file.id, profile: JSON.stringify("profile" in config ? config.profile : null) };
-    const timeout = options.timeoutMs ?? 60000, limit = options.maxOutputBytes ?? 256 * 1024;
-    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300000 || !Number.isInteger(limit) || limit < 1024 || limit > 1024 * 1024)
+    }
+    const pinned = {
+        instance: config.instance,
+        fileId: config.file.id,
+        profile: JSON.stringify("profile" in config ? config.profile : null),
+    };
+    const timeout = options.timeoutMs ?? 60000;
+    const limit = options.maxOutputBytes ?? 256 * 1024;
+    if (!Number.isInteger(timeout) ||
+        timeout < 1 ||
+        timeout > 300000 ||
+        !Number.isInteger(limit) ||
+        limit < 1024 ||
+        limit > 1024 * 1024) {
         throw new Error("Invalid MCP budgets");
-    const available = definitions.filter(d => !d.write || options.allowWrites);
-    const server = new Server({ name: "penpair", version }, { capabilities: { tools: {} } });
-    const tools = available.map(d => ({ name: d.name, description: d.description, inputSchema: { type: "object", properties: d.properties, required: d.required, additionalProperties: false }, annotations: { readOnlyHint: !d.write && !d.localWrite, destructiveHint: Boolean(d.write || d.localWrite), idempotentHint: !d.write && !d.localWrite, openWorldHint: true } }));
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    }
+    const available = definitions.filter((d) => !d.write || options.allowWrites);
+    const server = new Server({
+        name: "penpair",
+        version,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const tools = available.map((d) => ({
+        name: d.name,
+        description: d.description,
+        inputSchema: {
+            type: "object",
+            properties: d.properties,
+            required: d.required,
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: !d.write && !d.localWrite,
+            destructiveHint: Boolean(d.write || d.localWrite),
+            idempotentHint: !d.write && !d.localWrite,
+            openWorldHint: true,
+        },
+    }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools,
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const controller = new AbortController();
         const abort = () => controller.abort(extra.signal.reason);
-        extra.signal.addEventListener("abort", abort, { once: true });
-        if (extra.signal.aborted)
+        extra.signal.addEventListener("abort", abort, {
+            once: true,
+        });
+        if (extra.signal.aborted) {
             abort();
-        const timer = setTimeout(() => controller.abort(Object.assign(new Error("MCP command deadline exceeded"), { code: "deadline" })), timeout);
+        }
+        const timer = setTimeout(() => controller.abort(Object.assign(new Error("MCP command deadline exceeded"), {
+            code: "deadline",
+        })), timeout);
         let result;
         try {
-            const def = available.find(d => d.name === request.params.name);
-            if (!def)
+            const def = available.find((d) => d.name === request.params.name);
+            if (!def) {
                 throw new Error("Unknown or disabled tool");
+            }
             const args = validate(def, request.params.arguments);
             const current = await loadConfig(root);
-            if (current.instance !== pinned.instance || current.file?.id !== pinned.fileId || JSON.stringify("profile" in current ? current.profile : null) !== pinned.profile)
+            if (current.instance !== pinned.instance ||
+                current.file?.id !== pinned.fileId ||
+                JSON.stringify("profile" in current ? current.profile : null) !== pinned.profile) {
                 throw new Error("Pinned project target changed; restart and explicitly review server configuration");
-            if (def.localWrite)
+            }
+            if (def.localWrite) {
                 args.out = await resolveProjectOutput(root, String(args.out));
-            result = await runCommand(def.command(args), { ...options.cli, root, projectEndpointOnly: true, pinnedConfig: config, strictFileGuard: true, signal: controller.signal });
+            }
+            result = await runCommand(def.command(args), {
+                ...options.cli,
+                root,
+                projectEndpointOnly: true,
+                pinnedConfig: config,
+                strictFileGuard: true,
+                signal: controller.signal,
+            });
         }
         catch (error) {
-            result = await collectCommand(request.params.name, async () => { throw error; });
+            result = await collectCommand(request.params.name, async () => {
+                throw error;
+            });
         }
         finally {
             clearTimeout(timer);
             extra.signal.removeEventListener("abort", abort);
         }
         if (Buffer.byteLength(JSON.stringify(result), "utf8") > limit) {
-            result = { ...result, outcome: result.outcome === "uncertain" ? "uncertain" : "incomplete", exitCode: result.outcome === "uncertain" ? 4 : 3, data: null, messages: [], warnings: [], errors: [], completeness: { complete: false, reason: "MCP response byte budget exceeded; use a narrower inspection or the CLI artifact path" } };
+            result = {
+                ...result,
+                outcome: result.outcome === "uncertain" ? "uncertain" : "incomplete",
+                exitCode: result.outcome === "uncertain" ? 4 : 3,
+                data: null,
+                messages: [],
+                warnings: [],
+                errors: [],
+                completeness: {
+                    complete: false,
+                    reason: "MCP response byte budget exceeded; use a narrower inspection or the CLI artifact path",
+                },
+            };
         }
-        return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result, isError: result.exitCode !== 0 };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result),
+                },
+            ],
+            structuredContent: result,
+            isError: result.exitCode !== 0,
+        };
     });
     return server;
 }
-export async function serveMcp(options) { const server = await createMcpServer(options); await server.connect(new StdioServerTransport()); return server; }
+export async function serveMcp(options) {
+    const server = await createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/native-api.js

@@ -6,28 +6,54 @@ if (typeof penpot.currentFile.validate !== "function") return { ok: true, suppor
 const issues = penpot.currentFile.validate();
 if (!Array.isArray(issues)) return { ok: false, message: "file.validate returned no issue list" };
 return { ok: true, supported: true, valid: issues.length === 0, issues };`, {}, "read"));
-    if (typeof result.supported !== "boolean")
+    if (typeof result.supported !== "boolean") {
         throw new Error("Integrity check returned no capability result");
-    if (result.supported && (!Array.isArray(result.issues) || typeof result.valid !== "boolean" || result.valid !== (result.issues.length === 0)))
+    }
+    if (result.supported &&
+        (!Array.isArray(result.issues) ||
+            typeof result.valid !== "boolean" ||
+            result.valid !== (result.issues.length === 0))) {
         throw new Error("Integrity check returned incomplete or contradictory observations");
-    return { supported: result.supported, ...(result.supported ? { valid: result.valid === true, issues: result.issues } : {}) };
+    }
+    return {
+        supported: result.supported,
+        ...(result.supported
+            ? {
+                valid: result.valid === true,
+                issues: result.issues,
+            }
+            : {}),
+    };
 }
 /** Version history is a recovery aid, never a substitute for a restored independent backup. */
 export async function createCheckpoint(client, checkpoint, options = {}) {
-    if (!checkpoint.label.trim() || checkpoint.label.length > 120 || !/^[a-zA-Z0-9-]{1,100}$/.test(checkpoint.runId))
+    if (!checkpoint.label.trim() ||
+        checkpoint.label.length > 120 ||
+        !/^[a-zA-Z0-9-]{1,100}$/.test(checkpoint.runId)) {
         throw new Error("A checkpoint requires a short label and a stable alphanumeric/hyphen run ID");
+    }
     const capability = await runSnippet(client, snippet("checkpoint-capability", `return { ok: true, fileId: penpot.currentFile.id, supported: typeof penpot.currentFile.saveVersion === "function" && typeof penpot.currentFile.findVersions === "function" };`, {}, "read"));
-    if (capability.ok !== true || typeof capability.supported !== "boolean" || typeof capability.fileId !== "string")
+    if (capability.ok !== true ||
+        typeof capability.supported !== "boolean" ||
+        typeof capability.fileId !== "string") {
         throw new Error("Checkpoint capability returned no target/presence observations");
-    if (capability.supported !== true)
-        return { supported: false };
-    const params = { label: `penpair/${checkpoint.runId}/${checkpoint.label}`, fileId: capability.fileId };
+    }
+    if (capability.supported !== true) {
+        return {
+            supported: false,
+        };
+    }
+    const params = {
+        label: `penpair/${checkpoint.runId}/${checkpoint.label}`,
+        fileId: capability.fileId,
+    };
     const guard = 'if (penpot.currentFile.id !== CFG.fileId) return { ok: false, message: "checkpoint file changed" };';
     const listing = `${guard}
 const versions = (await penpot.currentFile.findVersions()).filter((version) => version.label === CFG.label);
 return { ok: true, fileId: penpot.currentFile.id, versions: versions.map((version) => ({ label: version.label, createdAt: String(version.createdAt) })) };`;
     const report = await runOperation(client, {
-        name: "checkpoint", page: () => undefined,
+        name: "checkpoint",
+        page: () => undefined,
         inspect: () => snippet("checkpoint-inspect", listing, params, "read"),
         apply: () => snippet("checkpoint-apply", `${guard}
 const versions = (await penpot.currentFile.findVersions()).filter((version) => version.label === CFG.label);
@@ -36,7 +62,17 @@ if (versions.length === 1) return { ok: true, existed: true };
 await penpot.currentFile.saveVersion(CFG.label);
 return { ok: true, created: true };`, params, "write"),
         readback: () => snippet("checkpoint-readback", listing, params, "read"),
-        verify: ({ readback }) => readback.fileId === params.fileId && Array.isArray(readback.versions) && readback.versions.length === 1 && readback.versions[0]?.label === params.label ? [] : ["Checkpoint was not independently found once in the intended file"],
+        verify: ({ readback }) => readback.fileId === params.fileId &&
+            Array.isArray(readback.versions) &&
+            readback.versions.length === 1 &&
+            readback.versions[0]?.label === params.label
+            ? []
+            : [
+                "Checkpoint was not independently found once in the intended file",
+            ],
     }, undefined, options);
-    return { supported: true, report };
+    return {
+        supported: true,
+        report,
+    };
 }

package/dist/onboard.js

@@ -1,15 +1,41 @@
 import { isExternal } from "./instance/config.js";
 export function onboardingChecklist(config) {
-    const origin = isExternal(config) ? config.profile.origin : `http://localhost:${config.ports.frontend}`;
-    const fileUrl = config.file ? `${origin}/#/workspace?file-id=${encodeURIComponent(config.file.id)}` : null;
-    return { schemaVersion: 1, project: config.instance, origin, file: config.file ?? null, fileUrl,
-        steps: ["Clone the project and install its locked dependencies with the repository's package manager.",
+    const origin = isExternal(config)
+        ? config.profile.origin
+        : `http://localhost:${config.ports.frontend}`;
+    const fileUrl = config.file
+        ? `${origin}/#/workspace?file-id=${encodeURIComponent(config.file.id)}`
+        : null;
+    return {
+        schemaVersion: 1,
+        project: config.instance,
+        origin,
+        file: config.file ?? null,
+        fileUrl,
+        steps: [
+            "Clone the project and install its locked dependencies with the repository's package manager.",
             `Ask the owner to invite your own Penpot account to the shared file at ${origin}.`,
             "Create your own personal MCP key. Keep it out of chat, commits and command arguments.",
             "Run the project's penpair connect command; enter your own key in its hidden prompt.",
-            config.file ? `Open ${config.file.name || config.file.id} (${config.file.id}). Use the owner's full editor link if the direct file link needs team context.` : "Ask the owner to pin the shared file with penpair connect --pin-file and commit the pin.",
+            config.file
+                ? `Open ${config.file.name || config.file.id} (${config.file.id}). Use the owner's full editor link if the direct file link needs team context.`
+                : "Ask the owner to pin the shared file with penpair connect --pin-file and commit the pin.",
             "Open the Penpot MCP plugin and Connect. Keep the editor tab open and awake.",
             "Run penpair doctor --json, then a read-only penpair pages before proposing writes.",
-            "Coordinate a write window with colleagues. Inspect the plan, apply once, verify independently and review the export."],
-        warnings: [...(!isExternal(config) ? ["localhost is this computer only. A colleague needs access to a shared reachable deployment; do not share generated instance secrets."] : []), ...(!config.file ? ["No shared file ID is pinned yet."] : []), "Writer markers are advisory and do not block human editing or guarantee exclusion across machines."] };
+            "Coordinate a write window with colleagues. Inspect the plan, apply once, verify independently and review the export.",
+        ],
+        warnings: [
+            ...(!isExternal(config)
+                ? [
+                    "localhost is this computer only. A colleague needs access to a shared reachable deployment; do not share generated instance secrets.",
+                ]
+                : []),
+            ...(!config.file
+                ? [
+                    "No shared file ID is pinned yet.",
+                ]
+                : []),
+            "Writer markers are advisory and do not block human editing or guarantee exclusion across machines.",
+        ],
+    };
 }

package/dist/operation.d.ts

@@ -53,8 +53,8 @@ export interface OperationReport {
     problems: string[];
     verified: boolean;
 }
-/** Runs a snippet; if the editor shows another page, opens the right one, waits, and tries once more. */
-export declare function runOnPage(client: PenpotToolClient, s: Snippet, page: string | undefined, { settleMs, sleep, onStep, ...execute }?: OperationOptions): Promise<SnippetResult>;
+/** Runs once on the expected page; page transitions require independently observed IDs. */
+export declare function runOnPage(client: PenpotToolClient, s: Snippet, page: string | undefined, { settleMs: _settleMs, sleep, onStep, ...execute }?: OperationOptions): Promise<SnippetResult>;
 export declare function runOperation<P>(client: PenpotToolClient, operation: Operation<P>, params: P, options?: OperationOptions): Promise<OperationReport>;
 /** Nests the frames that are not part of the live work into one archive board. Frames keep their names, ids and component links. */
 export declare const archiveOperation: Operation<ArchiveParams>;