@penpair/core 0.3.7 → 0.4.1

package/dist/adapters.d.ts

@@ -51,7 +51,7 @@ export interface Adapter {
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export declare const defineAdapter: <T extends Adapter>(adapter: T) => T;
 /** The commands of the core itself; an adapter cannot take one of these names. */
-export declare const reservedCommands: readonly ["formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
+export declare const reservedCommands: readonly ["journey-map", "integration-map", "design-release", "formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "wake", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
 export interface LoadedAdapters {
     adapters: Adapter[];
     problems: string[];

package/dist/adapters.js

@@ -7,6 +7,9 @@ import { readProjectConfig } from "./instance/config.js";
 export const defineAdapter = (adapter) => adapter;
 /** The commands of the core itself; an adapter cannot take one of these names. */
 export const reservedCommands = [
+    "journey-map",
+    "integration-map",
+    "design-release",
     "formats",
     "snapshot",
     "approve",
@@ -35,6 +38,7 @@ export const reservedCommands = [
     "open",
     "status",
     "doctor",
+    "wake",
     "backup",
     "restore",
     "baselines",

package/dist/approvals.d.ts

@@ -1,5 +1,6 @@
 import type { CaptureIdentity, ExportResult } from "./export.js";
 import { type BaselineCase } from "./baselines-config.js";
+import type { BaselineImageFormat } from "./image-evidence.js";
 export interface ApprovalRecord {
     schemaVersion: 1;
     id: string;
@@ -28,5 +29,7 @@ export declare function readApprovals(root: string): Promise<ApprovalFile>;
 export declare function recordApproval(root: string, exported: ExportResult, words: {
     note: string;
     by: string;
-}, intent?: BaselineCase, redact?: (text: string) => string): Promise<ApprovalRecord>;
+}, intent?: BaselineCase, redact?: (text: string) => string, options?: {
+    format?: BaselineImageFormat;
+}): Promise<ApprovalRecord>;
 export declare function matchingApproval(root: string, capture: CaptureIdentity, sha256: string, intent?: BaselineCase): Promise<ApprovalRecord | undefined>;

package/dist/approvals.js

@@ -7,6 +7,7 @@ import { observationHash } from "./journal.js";
 import { resolveProjectInput, resolveProjectOutput } from "./project-input.js";
 import { validateBaselineCase } from "./baselines-config.js";
 import { pngSize } from "./png.js";
+import { encodeBaselineImage } from "./image-codec.js";
 export const approvalFile = "design/approvals.json";
 export const artifactSha = (bytes) => createHash("sha256").update(bytes).digest("hex");
 export function approvalFingerprint(capture, sha256, intent) {
@@ -91,7 +92,7 @@ export async function readApprovals(root) {
     }
 }
 /** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
-export async function recordApproval(root, exported, words, intent, redact) {
+export async function recordApproval(root, exported, words, intent, redact, options = {}) {
     exported = {
         ...exported,
         capture: structuredClone(exported.capture),
@@ -113,7 +114,9 @@ export async function recordApproval(root, exported, words, intent, redact) {
         words.by.length > 200) {
         throw new Error("Supply the owner's exact nonempty words and identity; an agent cannot invent approval");
     }
-    const sha256 = artifactSha(exported.png);
+    const format = options.format ?? "png";
+    const imageBytes = await encodeBaselineImage(exported.png, format);
+    const sha256 = artifactSha(imageBytes);
     const fingerprint = approvalFingerprint(exported.capture, sha256, intent);
     if (intent &&
         (!matchesDesignViewport(exported.capture.designSize, intent.viewport) ||
@@ -142,7 +145,7 @@ export async function recordApproval(root, exported, words, intent, redact) {
             }
             : {}),
         sha256,
-        image: `design/approvals/${sha256}.png`,
+        image: `design/approvals/${sha256}.${format}`,
         fingerprint,
     };
     const record = {
@@ -168,7 +171,7 @@ export async function recordApproval(root, exported, words, intent, redact) {
             recursive: true,
         });
         try {
-            await atomicWriteFile(image, exported.png);
+            await atomicWriteFile(image, imageBytes);
         }
         catch (error) {
             if (error.code !== "EEXIST" ||

package/dist/baseline-coverage.js

@@ -2,7 +2,7 @@ import { open } from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { resolveProjectOutput } from "./project-input.js";
-import { pngSize } from "./png.js";
+import { inspectImageEvidence } from "./image-evidence.js";
 import { matchesDesignViewport } from "./design-viewport.js";
 import { validateBaselines, } from "./baselines-config.js";
 import { observationHash } from "./journal.js";
@@ -228,13 +228,13 @@ export async function readBaselineCoverage(root, config, expectedFileId) {
             }
             const target = await resolveProjectOutput(root, path.join(config.root, result.file));
             const bytes = await boundedRead(target, 64 * 1024 * 1024);
-            const size = pngSize(bytes);
+            const size = inspectImageEvidence(bytes);
             if (!size ||
                 size.width < 1 ||
                 size.height < 1 ||
                 createHash("sha256").update(bytes).digest("hex") !== result.approved.sha256 ||
                 result.sha256 !== result.approved.sha256) {
-                throw new Error("Approved PNG bytes do not match their manifest");
+                throw new Error("Approved image bytes do not match their manifest");
             }
             result.imageWidth = size.width;
             result.imageHeight = size.height;

package/dist/baselines-config.d.ts

@@ -1,3 +1,4 @@
+import type { BaselineImageFormat } from "./image-evidence.js";
 /** Declared design intent. It does not switch themes or establish browser behavior. */
 export interface BaselineCase {
     viewport: {
@@ -34,6 +35,8 @@ export interface BaselineFrame {
 }
 /** What `penpair baselines` exports: the frames of one page, as images in a folder of the project. */
 export interface BaselinesConfig {
+    /** Encoding for new references; existing approved formats require explicit migration. */
+    format?: BaselineImageFormat;
     page: string;
     /** Folder for the images, relative to the project. */
     root: string;

package/dist/baselines-config.js

@@ -6,6 +6,9 @@ export function validateBaselines(value, fail) {
         return fail("baselines must be an object");
     }
     const v = value;
+    if (v.format !== undefined && v.format !== "png" && v.format !== "webp") {
+        fail("baselines.format must be png or webp");
+    }
     if (typeof v.page !== "string" || v.page.length === 0) {
         fail("baselines.page must be the name of a page");
     }

package/dist/baselines.d.ts

@@ -1,3 +1,4 @@
+import { type BaselineImageFormat } from "./image-evidence.js";
 export { pngSize } from "./png.js";
 import type { PenpotToolClient } from "./client.js";
 import { type BaselineCoverage } from "./baseline-coverage.js";
@@ -70,6 +71,10 @@ export interface BaselinesReport {
     wrote: string[];
 }
 export interface BaselinesOptions extends ExportOptions {
+    /** Encoding for new references, or the explicit migration target. */
+    format?: BaselineImageFormat;
+    /** Change an existing reference's encoding; apply also requires update and exact-artifact approval. */
+    migrateFormat?: boolean;
     signal?: AbortSignal;
     /** Write images that are new. Without it nothing is written, whatever is found. */
     apply?: boolean;
@@ -78,6 +83,8 @@ export interface BaselinesOptions extends ExportOptions {
     /** Explicit waiver for a changed baseline; retained as a forced reference, never an owner approval. */
     forceReason?: string;
 }
+/** Resolve the exact encoding used by both approval and baseline capture. */
+export declare function resolveBaselineImageFormat(projectRoot: string, config: BaselinesConfig, baselineId: string, options?: Pick<BaselinesOptions, "format" | "migrateFormat">): Promise<BaselineImageFormat>;
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of

package/dist/baselines.js

@@ -1,9 +1,11 @@
 import { matchingApproval } from "./approvals.js";
 import { matchesDesignViewport } from "./design-viewport.js";
 import { pngSize } from "./png.js";
+import { encodeBaselineImage } from "./image-codec.js";
+import { inspectImageEvidence } from "./image-evidence.js";
 export { pngSize } from "./png.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { baselineCoverage } from "./baseline-coverage.js";
 import { resolveProjectOutput } from "./project-input.js";
@@ -16,9 +18,16 @@ import { runOnPage } from "./operation.js";
 import { frames } from "./snippets/read.js";
 export * from "./baselines-config.js";
 const sha = (buffer) => createHash("sha256").update(buffer).digest("hex");
-async function readIfExists(file) {
+async function readIfExists(file, maximum = 64 * 1024 * 1024) {
     try {
-        return await readFile(file);
+        if ((await stat(file)).size > maximum) {
+            throw new Error("Baseline artifact exceeds its read budget");
+        }
+        const bytes = await readFile(file);
+        if (bytes.length > maximum) {
+            throw new Error("Baseline artifact exceeds its read budget");
+        }
+        return bytes;
     }
     catch (error) {
         if (error.code === "ENOENT") {
@@ -27,12 +36,72 @@ async function readIfExists(file) {
         throw error;
     }
 }
+async function existingBaseline(projectRoot, config, id, old) {
+    const candidates = old
+        ? [
+            old.file,
+        ]
+        : [
+            `${id}.png`,
+            `${id}.webp`,
+        ];
+    let found = {};
+    for (const file of candidates) {
+        if (typeof file !== "string" || path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
+            throw new Error("Existing baseline path leaves its folder");
+        }
+        const bytes = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
+        if (!bytes) {
+            continue;
+        }
+        if (found.bytes) {
+            throw new Error("Existing baseline candidates are ambiguous; inspect before capture");
+        }
+        found = {
+            file,
+            bytes,
+            format: inspectImageEvidence(bytes).format,
+        };
+    }
+    if (old &&
+        (!found.bytes ||
+            old.sha256 !== sha(found.bytes) ||
+            (old.approved && old.approved.sha256 !== old.sha256))) {
+        throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
+    }
+    return found;
+}
+/** Resolve the exact encoding used by both approval and baseline capture. */
+export async function resolveBaselineImageFormat(projectRoot, config, baselineId, options = {}) {
+    const target = options.format ?? config.format ?? "webp";
+    if (target !== "png" && target !== "webp") {
+        throw new Error("Baseline format must be png or webp");
+    }
+    const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
+    const bytes = await readIfExists(manifestPath, 16 * 1024 * 1024);
+    const previous = bytes ? JSON.parse(bytes.toString("utf8")) : undefined;
+    if (previous &&
+        ((previous.schemaVersion !== undefined && previous.schemaVersion !== 2) ||
+            !Array.isArray(previous.frames) ||
+            previous.frames.length > 1000)) {
+        throw new Error("Existing baseline manifest is invalid; preserve and inspect it");
+    }
+    const old = previous?.frames?.find((entry) => entry.id === baselineId);
+    const existing = await existingBaseline(projectRoot, config, baselineId, old);
+    return existing.format && !options.migrateFormat ? existing.format : target;
+}
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of
  * the design never silently becomes the new reference.
  */
 export async function exportBaselines(client, projectRoot, config, options = {}) {
+    if (options.format !== undefined && options.format !== "png" && options.format !== "webp") {
+        throw new Error("Baseline format must be png or webp");
+    }
+    if (options.migrateFormat && options.apply && !options.update) {
+        throw new Error("Applying a baseline format migration requires update");
+    }
     if (options.forceReason !== undefined &&
         (!options.update ||
             !options.apply ||
@@ -65,7 +134,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     const wrote = [];
     const folder = await resolveProjectOutput(projectRoot, config.root);
     const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
-    const previousBytes = await readIfExists(manifestPath);
+    const previousBytes = await readIfExists(manifestPath, 16 * 1024 * 1024);
     const previous = previousBytes
         ? JSON.parse(previousBytes.toString("utf8"))
         : undefined;
@@ -80,7 +149,13 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     for (const wanted of config.frames) {
         options.signal?.throwIfAborted();
         const old = previous?.frames?.find((entry) => entry.id === wanted.id);
-        const file = old?.file ?? `${wanted.id}.png`;
+        const existingEvidence = await existingBaseline(projectRoot, config, wanted.id, old);
+        const format = existingEvidence.format && !options.migrateFormat
+            ? existingEvidence.format
+            : (options.format ?? config.format ?? "webp");
+        const migrating = Boolean(existingEvidence.format && existingEvidence.format !== format);
+        const existing = existingEvidence.bytes;
+        const file = existingEvidence.file ?? `${wanted.id}.${format}`;
         if (path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
             throw new Error("Existing baseline path leaves its folder");
         }
@@ -157,13 +232,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         if (!pngSize(exported.png)) {
             throw new Error("Baseline export is not a PNG with dimensions");
         }
-        const existing = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
-        if (old &&
-            (!existing ||
-                old.sha256 !== sha(existing) ||
-                (old.approved && old.approved.sha256 !== old.sha256))) {
-            throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
-        }
+        const encoded = await encodeBaselineImage(exported.png, format);
         const captured = {
             ...(wanted.case
                 ? {
@@ -172,10 +241,10 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 : {}),
             layout: exported.layout,
             ...exported.capture,
-            sha256: sha(exported.png),
+            sha256: sha(encoded),
             capturedAt: new Date().toISOString(),
             toolVersion: version,
-            file: `${generation}/${wanted.id}.png`,
+            file: `${generation}/${wanted.id}.${format}`,
         };
         const caseProblems = [];
         if (wanted.case) {
@@ -237,7 +306,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                     recordHash: record.hash,
                 };
             }
-            else if (options.forceReason) {
+            else if (options.forceReason && !migrating) {
                 captured.approval = {
                     kind: "forced-reference",
                     reason: options.forceReason,
@@ -256,8 +325,8 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 legacy: true,
                 sha256: sha(existing),
             });
-        const image = approve ? exported.png : existing;
-        const size = pngSize(image);
+        const image = approve ? encoded : existing;
+        const size = inspectImageEvidence(image);
         results.push({
             ...base,
             file: approve && options.apply ? captured.file : file,
@@ -270,7 +339,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
             imageWidth: size?.width,
             imageHeight: size?.height,
         });
-        captures.set(wanted.id, exported.png);
+        captures.set(`${wanted.id}.${format}`, encoded);
     }
     const after = await runOnPage(client, frames({
         page: config.page,
@@ -311,10 +380,10 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         const staged = path.join(folder, `.stage-${runId}`);
         await mkdir(staged);
         try {
-            for (const [id, bytes] of captures) {
+            for (const [file, bytes] of captures) {
                 options.signal?.throwIfAborted();
-                await atomicWriteFile(path.join(staged, `${id}.png`), bytes);
-                options.onStep?.(`staging ${id}`);
+                await atomicWriteFile(path.join(staged, file), bytes);
+                options.onStep?.(`staging ${path.parse(file).name}`);
             }
             const cases = reflectionCases(config, results);
             await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({

package/dist/bounded-file.d.ts

@@ -0,0 +1,2 @@
+/** Read a regular project file with an allocation bound even if another process grows it. */
+export declare function readProjectBytes(root: string, file: string, maxBytes: number): Promise<Buffer>;

package/dist/bounded-file.js

@@ -0,0 +1,38 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+/** Read a regular project file with an allocation bound even if another process grows it. */
+export async function readProjectBytes(root, file, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new Error("A positive file byte budget is required");
+    }
+    const input = await resolveProjectInput(root, file);
+    if (!(await lstat(input)).isFile()) {
+        throw new Error("Artifact input must be a regular file");
+    }
+    const handle = await open(input, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxBytes) {
+            throw new Error("Artifact input is not a regular file within its byte budget");
+        }
+        const chunks = [];
+        let total = 0;
+        while (total <= maxBytes) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+            if (bytesRead === 0) {
+                return Buffer.concat(chunks, total);
+            }
+            total += bytesRead;
+            if (total > maxBytes) {
+                throw new Error("Artifact input exceeds its byte budget");
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        throw new Error("Artifact input exceeds its byte budget");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/browser-wake.d.ts

@@ -0,0 +1,22 @@
+export interface BrowserTargetOptions {
+    origin: string;
+    fileId: string;
+    port: number;
+    timeoutMs?: number;
+    allowLoopbackAlias?: boolean;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}
+export interface BrowserWakeResult {
+    activated: true;
+    targetId: string;
+    keepAlive: "none";
+}
+export interface BrowserInspectionResult {
+    targetId: string;
+    keepAlive: "unknown";
+}
+/** Activate only the existing page for the pinned file; never reload or evaluate page code. */
+export declare function wakeBrowserTarget(options: BrowserTargetOptions): Promise<BrowserWakeResult>;
+/** Read debugging metadata only; a listed tab does not establish plugin readiness or keep-alive. */
+export declare function inspectBrowserTarget(options: BrowserTargetOptions): Promise<BrowserInspectionResult>;

package/dist/browser-wake.js

@@ -0,0 +1,241 @@
+const maxTargetBytes = 1024 * 1024;
+const maxTargetCount = 1000;
+/** Activate only the existing page for the pinned file; never reload or evaluate page code. */
+export async function wakeBrowserTarget(options) {
+    return withBrowserDeadline(options, async (request) => {
+        const targetId = await findBrowserTarget(request);
+        const response = await browserRequest(request, `/json/activate/${encodeURIComponent(targetId)}`);
+        void response.body?.cancel().catch(() => undefined);
+        request.signal.throwIfAborted();
+        return {
+            activated: true,
+            targetId,
+            keepAlive: "none",
+        };
+    });
+}
+/** Read debugging metadata only; a listed tab does not establish plugin readiness or keep-alive. */
+export async function inspectBrowserTarget(options) {
+    return withBrowserDeadline(options, async (request) => ({
+        targetId: await findBrowserTarget(request),
+        keepAlive: "unknown",
+    }));
+}
+async function withBrowserDeadline(options, work) {
+    const origin = validateBrowserOptions(options);
+    if (options.signal?.aborted) {
+        throw new Error("Browser debugging cancelled");
+    }
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? 5000;
+    let timedOut = false;
+    const externalAbort = () => controller.abort();
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    options.signal?.addEventListener("abort", externalAbort, {
+        once: true,
+    });
+    let abort = () => undefined;
+    const interrupted = new Promise((_resolve, reject) => {
+        abort = () => reject(new Error(timedOut ? "Browser debugging deadline exceeded" : "Browser debugging cancelled"));
+        controller.signal.addEventListener("abort", abort, {
+            once: true,
+        });
+    });
+    try {
+        if (options.signal?.aborted) {
+            controller.abort();
+        }
+        controller.signal.throwIfAborted();
+        return await Promise.race([
+            interrupted,
+            work({
+                origin,
+                fileId: options.fileId,
+                allowLoopbackAlias: options.allowLoopbackAlias === true,
+                endpoint: `http://127.0.0.1:${options.port}`,
+                fetch: options.fetch ?? fetch,
+                signal: controller.signal,
+            }),
+        ]);
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new Error(timedOut ? "Browser debugging deadline exceeded" : "Browser debugging cancelled");
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", externalAbort);
+        controller.signal.removeEventListener("abort", abort);
+    }
+}
+function validateBrowserOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+        throw new Error("Browser debugging port must be an integer from 1 to 65535");
+    }
+    const timeoutMs = options.timeoutMs ?? 5000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 30000) {
+        throw new Error("Browser debugging timeout must be an integer from 1000 to 30000 ms");
+    }
+    if (typeof options.fileId !== "string" ||
+        !options.fileId.trim() ||
+        options.fileId.length > 256 ||
+        /[\u0000-\u0020\u007f]/.test(options.fileId)) {
+        throw new Error("Browser activation requires a pinned file ID");
+    }
+    let origin;
+    try {
+        origin = new URL(options.origin);
+    }
+    catch {
+        throw new Error("Browser activation requires a valid Penpot origin");
+    }
+    if (![
+        "http:",
+        "https:",
+    ].includes(origin.protocol) ||
+        origin.username ||
+        origin.password ||
+        origin.pathname !== "/" ||
+        origin.search ||
+        origin.hash) {
+        throw new Error("Browser activation requires a Penpot origin without credentials, path or query");
+    }
+    if (options.allowLoopbackAlias && !isHttpLoopback(origin)) {
+        throw new Error("Browser loopback aliases require an HTTP localhost or 127.0.0.1 origin");
+    }
+    return origin.origin;
+}
+async function browserRequest(request, path) {
+    request.signal.throwIfAborted();
+    let response;
+    try {
+        response = await request.fetch(`${request.endpoint}${path}`, {
+            method: "GET",
+            redirect: "error",
+            signal: request.signal,
+        });
+    }
+    catch {
+        throw new Error("Cannot reach the local browser debugging endpoint; start a dedicated browser with a loopback debugging port");
+    }
+    request.signal.throwIfAborted();
+    if (!response.ok || response.redirected) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new Error("The local browser debugging endpoint refused the request");
+    }
+    return response;
+}
+async function findBrowserTarget(request) {
+    const response = await browserRequest(request, "/json/list");
+    const text = await readTargetList(response);
+    request.signal.throwIfAborted();
+    let targets;
+    try {
+        targets = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Invalid browser debugging target list");
+    }
+    if (!Array.isArray(targets) ||
+        targets.length > maxTargetCount ||
+        !targets.every(isBrowserTarget)) {
+        throw new Error("Invalid browser debugging target list");
+    }
+    const matching = targets.filter((target) => target.type === "page" && matchesFile(target.url, request));
+    if (matching.length !== 1) {
+        throw new Error(matching.length === 0
+            ? "No browser page matches the project's Penpot origin and pinned file ID"
+            : "Multiple browser pages match the pinned file; close duplicate tabs before waking");
+    }
+    const targetId = matching[0].id;
+    if (!/^[A-Za-z0-9_-]{1,256}$/.test(targetId)) {
+        throw new Error("Invalid browser debugging target ID");
+    }
+    return targetId;
+}
+function isBrowserTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const target = value;
+    return (typeof target.id === "string" &&
+        typeof target.type === "string" &&
+        typeof target.url === "string");
+}
+function isHttpLoopback(url) {
+    return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+function matchesOrigin(target, request) {
+    if (target.origin === request.origin) {
+        return true;
+    }
+    if (!request.allowLoopbackAlias || !isHttpLoopback(target)) {
+        return false;
+    }
+    const expected = new URL(request.origin);
+    return isHttpLoopback(expected) && target.port === expected.port;
+}
+function matchesFile(targetUrl, request) {
+    let url;
+    try {
+        url = new URL(targetUrl);
+    }
+    catch {
+        return false;
+    }
+    if (!matchesOrigin(url, request) || url.username || url.password) {
+        return false;
+    }
+    const hashRoute = url.hash.slice(1);
+    const hashQuery = hashRoute.indexOf("?");
+    const parameters = hashQuery >= 0 && hashRoute.slice(0, hashQuery) === "/workspace"
+        ? new URLSearchParams(hashRoute.slice(hashQuery + 1))
+        : url.pathname === "/workspace" && !url.hash
+            ? url.searchParams
+            : undefined;
+    const fileIds = parameters?.getAll("file-id");
+    return fileIds?.length === 1 && fileIds[0] === request.fileId;
+}
+async function readTargetList(response) {
+    const declaredBytes = Number(response.headers.get("content-length"));
+    if (declaredBytes > maxTargetBytes) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new Error("Browser debugging target list exceeds the size limit");
+    }
+    if (!response.body) {
+        throw new Error("Invalid browser debugging target list");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                break;
+            }
+            bytes += next.value.byteLength;
+            if (bytes > maxTargetBytes) {
+                throw new Error("Browser debugging target list exceeds the size limit");
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        void reader.cancel().catch(() => undefined);
+        if (error instanceof Error &&
+            error.message === "Browser debugging target list exceeds the size limit") {
+            throw error;
+        }
+        throw new Error("Cannot read browser debugging target list");
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, bytes).toString("utf8");
+}