@pagepocket/capture-http-puppeteer-unit 0.13.0 → 0.14.5

package/dist/capture-http-puppeteer-unit.d.ts

@@ -3,7 +3,7 @@ import { type PuppeteerAdapterOptions } from "./internal/puppeteer-adapter.js";
 export type CaptureHttpPuppeteerUnitOptions = PuppeteerAdapterOptions;
 export declare class CaptureHttpPuppeteerUnit extends Unit {
     readonly id = "captureHttpPuppeteer";
-    readonly description = "Capturing page via Puppeteer";
+    readonly description = "Capturing page";
     private adapterOptions;
     constructor(options?: CaptureHttpPuppeteerUnitOptions);
     run(ctx: UnitContext, rt: UnitRuntime): Promise<{

package/dist/capture-http-puppeteer-unit.js

@@ -44,7 +44,7 @@ export class CaptureHttpPuppeteerUnit extends Unit {
     constructor(options) {
         super();
         this.id = "captureHttpPuppeteer";
-        this.description = "Capturing page via Puppeteer";
+        this.description = "Capturing page";
         this.adapterOptions = options ?? {};
     }
     async run(ctx, rt) {

package/dist/internal/puppeteer-adapter/worker-cdp-types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CDP payload types and helpers for worker network capture.
+ *
+ * These are a minimal subset of the Chrome DevTools Protocol shapes needed
+ * to monitor `Network.*` events on WebWorker targets.
+ */
+import type { ResourceType } from "@pagepocket/lib";
+export type CdpRequestWillBeSent = {
+    requestId: string;
+    timestamp?: number;
+    wallTime?: number;
+    type?: string;
+    initiator?: {
+        type?: string;
+        url?: string;
+    };
+    request: {
+        url: string;
+        method: string;
+        headers?: Record<string, unknown>;
+    };
+};
+export type CdpResponseReceived = {
+    requestId: string;
+    timestamp?: number;
+    wallTime?: number;
+    type?: string;
+    response: {
+        url: string;
+        status: number;
+        statusText?: string;
+        headers?: Record<string, unknown>;
+        mimeType?: string;
+        fromDiskCache?: boolean;
+        fromServiceWorker?: boolean;
+    };
+};
+export type CdpLoadingFinished = {
+    requestId: string;
+    timestamp?: number;
+};
+export type CdpLoadingFailed = {
+    requestId: string;
+    timestamp?: number;
+    errorText: string;
+};
+export declare const normalizeHeaders: (headers?: Record<string, unknown>) => Record<string, string>;
+export declare const mapResourceType: (input?: string) => ResourceType | undefined;
+export declare const resolveTimestampMs: (payload: {
+    timestamp?: number;
+    wallTime?: number;
+}) => number;

package/dist/internal/puppeteer-adapter/worker-cdp-types.js

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export const normalizeHeaders = (headers) => {
+    const output = {};
+    if (!headers) {
+        return output;
+    }
+    for (const key of Object.keys(headers)) {
+        const value = headers[key];
+        if (value === undefined) {
+            continue;
+        }
+        output[key] = Array.isArray(value) ? value.join(", ") : String(value);
+    }
+    return output;
+};
+export const mapResourceType = (input) => {
+    if (!input) {
+        return undefined;
+    }
+    const normalized = input.toLowerCase();
+    switch (normalized) {
+        case "document":
+        case "stylesheet":
+        case "script":
+        case "image":
+        case "font":
+        case "media":
+        case "xhr":
+        case "fetch":
+        case "other":
+            return normalized;
+        default:
+            return normalized;
+    }
+};
+export const resolveTimestampMs = (payload) => {
+    if (typeof payload.wallTime === "number") {
+        return Math.round(payload.wallTime * 1000);
+    }
+    if (typeof payload.timestamp === "number") {
+        return Math.round(payload.timestamp * 1000);
+    }
+    return Date.now();
+};

package/dist/internal/puppeteer-adapter/worker-network.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CDP-based network capture for WebWorker targets.
+ *
+ * Puppeteer's `page.on("request")` does not fire for requests made inside
+ * dedicated WebWorkers.  This module attaches a CDP `Network` session to each
+ * worker so those requests are captured alongside the main-page traffic.
+ *
+ * Non-intercepting: we only listen (`Network.enable`), never pause requests.
+ */
+import type { NetworkEventHandlers } from "@pagepocket/lib";
+import type { Page } from "puppeteer";
+export type WorkerNetworkCapture = {
+    /** Stop all worker network listeners and detach future-worker handling. */
+    stop: () => Promise<void>;
+};
+/**
+ * Start capturing network traffic from all current and future WebWorkers on
+ * the given page.
+ *
+ * Returns a handle whose `stop()` tears down every worker listener.
+ */
+export declare const startWorkerNetworkCapture: (page: Page, handlers: NetworkEventHandlers) => WorkerNetworkCapture;

package/dist/internal/puppeteer-adapter/worker-network.js

@@ -0,0 +1,170 @@
+import { mapResourceType, normalizeHeaders, resolveTimestampMs } from "./worker-cdp-types.js";
+const attachToWorker = async (worker, handlers, requestIdPrefix) => {
+    // CdpWebWorker (the Chromium-backed Puppeteer implementation) exposes a
+    // `client` getter that returns the underlying CDPSession.  The base
+    // `WebWorker` class does not expose this, so we access it via cast.
+    const workerRef = worker;
+    const cdpSession = workerRef.client;
+    if (!cdpSession || typeof cdpSession.send !== "function") {
+        return undefined;
+    }
+    try {
+        await cdpSession.send("Network.enable");
+    }
+    catch {
+        return undefined;
+    }
+    let requestSequence = 0;
+    const cdpToLogical = new Map();
+    const getLogicalId = (cdpRequestId) => {
+        const existing = cdpToLogical.get(cdpRequestId);
+        if (existing) {
+            return existing;
+        }
+        const logicalId = `${requestIdPrefix}-${requestSequence++}`;
+        cdpToLogical.set(cdpRequestId, logicalId);
+        return logicalId;
+    };
+    const storedResponses = new Map();
+    const requestUrls = new Map();
+    const onRequestWillBeSent = (raw) => {
+        const payload = raw;
+        const logicalId = getLogicalId(payload.requestId);
+        const timestamp = resolveTimestampMs(payload);
+        requestUrls.set(logicalId, payload.request.url);
+        const event = {
+            type: "request",
+            requestId: logicalId,
+            url: payload.request.url,
+            method: payload.request.method,
+            headers: normalizeHeaders(payload.request.headers),
+            resourceType: mapResourceType(payload.type),
+            initiator: payload.initiator
+                ? { type: payload.initiator.type, url: payload.initiator.url }
+                : undefined,
+            timestamp
+        };
+        handlers.onEvent(event);
+    };
+    const onResponseReceived = (raw) => {
+        const payload = raw;
+        const logicalId = getLogicalId(payload.requestId);
+        storedResponses.set(payload.requestId, {
+            logicalId,
+            response: payload.response,
+            resourceType: mapResourceType(payload.type)
+        });
+    };
+    const onLoadingFinished = async (raw) => {
+        const payload = raw;
+        const stored = storedResponses.get(payload.requestId);
+        if (!stored) {
+            return;
+        }
+        storedResponses.delete(payload.requestId);
+        let bodyBytes;
+        try {
+            const result = await cdpSession.send("Network.getResponseBody", {
+                requestId: payload.requestId
+            });
+            const typed = result;
+            if (typed.base64Encoded) {
+                const binary = atob(typed.body);
+                const bytes = new Uint8Array(binary.length);
+                for (let byteIndex = 0; byteIndex < binary.length; byteIndex += 1) {
+                    bytes[byteIndex] = binary.charCodeAt(byteIndex);
+                }
+                bodyBytes = bytes;
+            }
+            else {
+                bodyBytes = new TextEncoder().encode(typed.body);
+            }
+        }
+        catch {
+            // Body may be unavailable (204, redirects, already-destroyed worker).
+        }
+        if (bodyBytes && bodyBytes.byteLength === 0) {
+            bodyBytes = undefined;
+        }
+        const responseEvent = {
+            type: "response",
+            requestId: stored.logicalId,
+            url: stored.response.url,
+            status: stored.response.status,
+            statusText: stored.response.statusText,
+            headers: normalizeHeaders(stored.response.headers),
+            mimeType: stored.response.mimeType,
+            fromDiskCache: stored.response.fromDiskCache,
+            fromServiceWorker: stored.response.fromServiceWorker,
+            timestamp: resolveTimestampMs(payload),
+            body: bodyBytes ? { kind: "buffer", data: bodyBytes } : undefined
+        };
+        handlers.onEvent(responseEvent);
+    };
+    const onLoadingFailed = (raw) => {
+        const payload = raw;
+        const logicalId = getLogicalId(payload.requestId);
+        storedResponses.delete(payload.requestId);
+        const failedEvent = {
+            type: "failed",
+            requestId: logicalId,
+            url: requestUrls.get(logicalId) ?? "",
+            errorText: payload.errorText,
+            timestamp: resolveTimestampMs(payload)
+        };
+        handlers.onEvent(failedEvent);
+    };
+    cdpSession.on("Network.requestWillBeSent", onRequestWillBeSent);
+    cdpSession.on("Network.responseReceived", onResponseReceived);
+    cdpSession.on("Network.loadingFinished", onLoadingFinished);
+    cdpSession.on("Network.loadingFailed", onLoadingFailed);
+    const stop = async () => {
+        cdpSession.off("Network.requestWillBeSent", onRequestWillBeSent);
+        cdpSession.off("Network.responseReceived", onResponseReceived);
+        cdpSession.off("Network.loadingFinished", onLoadingFinished);
+        cdpSession.off("Network.loadingFailed", onLoadingFailed);
+        try {
+            await cdpSession.send("Network.disable");
+        }
+        catch {
+            // Worker may already be gone.
+        }
+    };
+    return { stop };
+};
+/**
+ * Start capturing network traffic from all current and future WebWorkers on
+ * the given page.
+ *
+ * Returns a handle whose `stop()` tears down every worker listener.
+ */
+export const startWorkerNetworkCapture = (page, handlers) => {
+    const sessions = [];
+    let workerSequence = 0;
+    const handleWorker = async (worker) => {
+        const prefix = `pptr-worker-${Date.now()}-${workerSequence++}`;
+        const session = await attachToWorker(worker, handlers, prefix);
+        if (session) {
+            sessions.push(session);
+        }
+    };
+    // Attach to workers that already exist.
+    const castPage = page;
+    if (typeof castPage.workers === "function") {
+        for (const existingWorker of castPage.workers()) {
+            void handleWorker(existingWorker);
+        }
+    }
+    // Listen for future workers.
+    const onWorkerCreated = (event) => {
+        void handleWorker(event);
+    };
+    page.on("workercreated", onWorkerCreated);
+    const stop = async () => {
+        page.off("workercreated", onWorkerCreated);
+        const pending = sessions.map((session) => session.stop());
+        await Promise.all(pending);
+        sessions.length = 0;
+    };
+    return { stop };
+};

package/dist/internal/puppeteer-adapter.d.ts

@@ -1,10 +1,10 @@
 import type { NetworkEventHandlers, NetworkInterceptorAdapter, TriggerAction, InterceptTarget, InterceptSession } from "@pagepocket/lib";
-import { type Browser, type GoToOptions, type LaunchOptions, type Page } from "puppeteer";
+import { type Browser, type GoToOptions, type PuppeteerLaunchOptions, type Page } from "puppeteer";
 export type PuppeteerAdapterOptions = {
     browser?: Browser;
     page?: Page;
-    launch?: (options?: LaunchOptions) => Promise<Browser>;
-    launchOptions?: LaunchOptions;
+    launch?: (options?: PuppeteerLaunchOptions) => Promise<Browser>;
+    launchOptions?: PuppeteerLaunchOptions;
     gotoOptions?: GoToOptions;
     triggerActions?: TriggerAction[];
 };

package/dist/internal/puppeteer-adapter.js

@@ -1,10 +1,13 @@
 import puppeteer from "puppeteer";
 import { createEmitRequest, createOnRequestFailed, createOnResponse, createRequestIdStore } from "./puppeteer-adapter/events.js";
 import { buildNavigate, ensureHtmlTargetLoaded } from "./puppeteer-adapter/targets.js";
+import { startWorkerNetworkCapture } from "./puppeteer-adapter/worker-network.js";
 import { readDomHtml } from "./utils/dom-html.js";
 import { getEnvString } from "./utils/env.js";
-import { buildMissingChromeHelp, getErrorMessage, isMissingChromeError } from "./utils/errors.js";
+import { isMissingChromeError } from "./utils/errors.js";
+import { ensureBrowser } from "./utils/ensure-browser.js";
 import { runTriggerActions } from "./utils/trigger-actions.js";
+import { getSandboxArgs } from "./utils/sandbox-args.js";
 /**
  * Internal adapter for the capture plugin.
  *
@@ -38,17 +41,25 @@ export class PuppeteerAdapter {
                     const envExecutablePath = getEnvString("PUPPETEER_EXECUTABLE_PATH");
                     const launchOptionsFromUser = this.options.launchOptions;
                     const executablePath = launchOptionsFromUser?.executablePath ?? envExecutablePath;
+                    const sandboxArgs = getSandboxArgs();
+                    const mergedArgs = [...(launchOptionsFromUser?.args ?? []), ...sandboxArgs];
+                    const baseLaunchOptions = {
+                        ...launchOptionsFromUser,
+                        ...(executablePath ? { executablePath } : {}),
+                        ...(mergedArgs.length > 0 ? { args: mergedArgs } : {})
+                    };
                     try {
-                        browser = await doLaunch({
-                            ...launchOptionsFromUser,
-                            ...(executablePath ? { executablePath } : {})
-                        });
+                        browser = await doLaunch(baseLaunchOptions);
                     }
                     catch (error) {
                         if (!isMissingChromeError(error)) {
                             throw error;
                         }
-                        throw new Error(`${getErrorMessage(error)}\n\n${buildMissingChromeHelp()}`);
+                        const downloadedPath = await ensureBrowser();
+                        browser = await doLaunch({
+                            ...baseLaunchOptions,
+                            executablePath: downloadedPath
+                        });
                     }
                     ownsBrowser = true;
                 }
@@ -62,6 +73,17 @@ export class PuppeteerAdapter {
         if (!page || typeof page.on !== "function") {
             throw new Error("PuppeteerAdapter requires a Puppeteer Page instance.");
         }
+        // Activate the CDP Fetch domain with a catch-all pattern.
+        // Without Fetch.enable, Chrome silently omits Network events for certain
+        // XHR requests (e.g. Feishu's encrypted-image blob downloads via
+        // XMLHttpRequest to CDN).  Enabling Fetch forces every request through
+        // the CDP pipeline, making them visible to Network.* listeners.
+        // We immediately continue each paused request so page behavior is unchanged.
+        const cdpSession = await page.createCDPSession();
+        await cdpSession.send("Fetch.enable", { patterns: [{ urlPattern: "*" }] });
+        cdpSession.on("Fetch.requestPaused", (event) => {
+            cdpSession.send("Fetch.continueRequest", { requestId: event.requestId }).catch(() => { });
+        });
         const { getRequestId, has } = createRequestIdStore();
         const emitRequest = createEmitRequest(handlers, getRequestId);
         const onRequest = (request) => emitRequest(request, Date.now());
@@ -80,6 +102,9 @@ export class PuppeteerAdapter {
         page.on("request", onRequest);
         page.on("response", onResponse);
         page.on("requestfailed", onRequestFailed);
+        // Capture network traffic from WebWorkers via CDP Network.enable.
+        // Puppeteer's page-level events do not fire for worker requests.
+        const workerCapture = startWorkerNetworkCapture(page, handlers);
         const { navigate, awaitLastNavigation } = buildNavigate(page, this.options.gotoOptions);
         let htmlLoaded = false;
         const whenHtmlLoaded = async () => {
@@ -120,6 +145,9 @@ export class PuppeteerAdapter {
             getDomHtml,
             startCapture,
             stop: async () => {
+                await workerCapture.stop();
+                await cdpSession.send("Fetch.disable").catch(() => { });
+                await cdpSession.detach().catch(() => { });
                 page.off("request", onRequest);
                 page.off("response", onResponse);
                 page.off("requestfailed", onRequestFailed);

package/dist/internal/utils/ensure-browser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ensures a Chrome executable is available for Puppeteer.
+ *
+ * When Puppeteer cannot find a compatible Chrome installation on the system,
+ * this helper automatically downloads Chrome for Testing using `@puppeteer/browsers`.
+ * The downloaded browser is cached in `~/.cache/puppeteer` and reused on
+ * subsequent runs.
+ *
+ * Usage:
+ *   const executablePath = await ensureBrowser();
+ *   const browser = await puppeteer.launch({ executablePath });
+ */
+export declare const ensureBrowser: () => Promise<string>;

package/dist/internal/utils/ensure-browser.js

@@ -0,0 +1,42 @@
+import os from "os";
+import path from "path";
+import { Browser, computeExecutablePath, detectBrowserPlatform, getInstalledBrowsers, install, resolveBuildId } from "@puppeteer/browsers";
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".cache", "puppeteer");
+/**
+ * Ensures a Chrome executable is available for Puppeteer.
+ *
+ * When Puppeteer cannot find a compatible Chrome installation on the system,
+ * this helper automatically downloads Chrome for Testing using `@puppeteer/browsers`.
+ * The downloaded browser is cached in `~/.cache/puppeteer` and reused on
+ * subsequent runs.
+ *
+ * Usage:
+ *   const executablePath = await ensureBrowser();
+ *   const browser = await puppeteer.launch({ executablePath });
+ */
+export const ensureBrowser = async () => {
+    const platform = detectBrowserPlatform();
+    if (!platform) {
+        throw new Error(`Cannot detect browser platform for: ${os.platform()} (${os.arch()})`);
+    }
+    const cacheDir = DEFAULT_CACHE_DIR;
+    const buildId = await resolveBuildId(Browser.CHROME, platform, "stable");
+    const installedBrowsers = await getInstalledBrowsers({ cacheDir });
+    const existingInstall = installedBrowsers.find((entry) => entry.browser === Browser.CHROME && entry.buildId === buildId);
+    if (existingInstall) {
+        return computeExecutablePath({
+            browser: Browser.CHROME,
+            buildId,
+            cacheDir
+        });
+    }
+    console.log(`Chrome not found. Downloading Chrome (buildId: ${buildId})...`);
+    const installedBrowser = await install({
+        browser: Browser.CHROME,
+        cacheDir,
+        buildId,
+        platform
+    });
+    console.log(`Chrome downloaded to ${installedBrowser.executablePath}`);
+    return installedBrowser.executablePath;
+};

package/dist/internal/utils/puppeteer-auto-scroll.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from "puppeteer";
+export type AutoScrollOptions = {
+    distancePx?: number;
+    intervalMs?: number;
+    maxIdleTicks?: number;
+    maxSteps?: number;
+};
+/**
+ * Incrementally scrolls a page to the bottom until height stabilizes.
+ *
+ * Handles both traditional pages (window is the scroller) and SPA layouts
+ * where the actual scrollable area is a nested container with
+ * `overflow: auto | scroll` (e.g. Feishu, Notion, Google Docs).
+ *
+ * Detection logic:
+ * 1. If `document.scrollingElement.scrollHeight > window.innerHeight`,
+ *    use `window.scrollBy` (classic path).
+ * 2. Otherwise, find the DOM element with the largest scrollable overflow
+ *    (`scrollHeight - clientHeight`) and scroll that element instead.
+ *
+ * Usage:
+ *   await autoScrollToEnd(page);
+ *   await autoScrollToEnd(page, { intervalMs: 150, distancePx: 200 });
+ */
+export declare const autoScrollToEnd: (page: Page, options?: AutoScrollOptions) => Promise<void>;

package/dist/internal/utils/puppeteer-auto-scroll.js

@@ -0,0 +1,110 @@
+/**
+ * Incrementally scrolls a page to the bottom until height stabilizes.
+ *
+ * Handles both traditional pages (window is the scroller) and SPA layouts
+ * where the actual scrollable area is a nested container with
+ * `overflow: auto | scroll` (e.g. Feishu, Notion, Google Docs).
+ *
+ * Detection logic:
+ * 1. If `document.scrollingElement.scrollHeight > window.innerHeight`,
+ *    use `window.scrollBy` (classic path).
+ * 2. Otherwise, find the DOM element with the largest scrollable overflow
+ *    (`scrollHeight - clientHeight`) and scroll that element instead.
+ *
+ * Usage:
+ *   await autoScrollToEnd(page);
+ *   await autoScrollToEnd(page, { intervalMs: 150, distancePx: 200 });
+ */
+export const autoScrollToEnd = async (page, options = {}) => {
+    const distancePx = options.distancePx ?? 100;
+    const intervalMs = options.intervalMs ?? 100;
+    const maxIdleTicks = options.maxIdleTicks ?? 8;
+    const maxSteps = options.maxSteps ?? 300;
+    await page.evaluate(async (scrollOptions) => {
+        /**
+         * Find the primary scroll target.
+         *
+         * Returns `null` when the window itself is scrollable (caller should
+         * fall back to `window.scrollBy`). Returns an `Element` when a nested
+         * container owns the scroll.
+         */
+        const findScrollContainer = () => {
+            const root = document.scrollingElement ?? document.documentElement ?? document.body;
+            if (root && root.scrollHeight > window.innerHeight + 1) {
+                return null;
+            }
+            let best = null;
+            let bestDelta = 0;
+            const elements = Array.from(document.querySelectorAll("*"));
+            for (const el of elements) {
+                const style = getComputedStyle(el);
+                const oy = style.overflowY;
+                const isScrollable = oy === "auto" || oy === "scroll";
+                if (!isScrollable) {
+                    continue;
+                }
+                const delta = el.scrollHeight - el.clientHeight;
+                if (delta > bestDelta) {
+                    bestDelta = delta;
+                    best = el;
+                }
+            }
+            return best;
+        };
+        const container = findScrollContainer();
+        const getScrollHeight = () => {
+            if (container) {
+                return container.scrollHeight;
+            }
+            const root = document.scrollingElement ?? document.documentElement ?? document.body;
+            return Math.max(document.body?.scrollHeight ?? 0, document.documentElement?.scrollHeight ?? 0, root?.scrollHeight ?? 0);
+        };
+        const getScrollPosition = () => {
+            if (container) {
+                return container.scrollTop;
+            }
+            return window.scrollY;
+        };
+        const getViewportSize = () => {
+            if (container) {
+                return container.clientHeight;
+            }
+            return window.innerHeight;
+        };
+        const scrollBy = (distance) => {
+            if (container) {
+                container.scrollTop += distance;
+            }
+            else {
+                window.scrollBy(0, distance);
+            }
+        };
+        await new Promise((resolve) => {
+            let stepCount = 0;
+            let idleTickCount = 0;
+            let lastKnownHeight = getScrollHeight();
+            const epsilon = 1;
+            const timer = window.setInterval(() => {
+                const currentHeight = getScrollHeight();
+                const viewportBottom = getScrollPosition() + getViewportSize();
+                const reachedBottom = viewportBottom + epsilon >= currentHeight;
+                if (currentHeight > lastKnownHeight) {
+                    lastKnownHeight = currentHeight;
+                    idleTickCount = 0;
+                }
+                else if (reachedBottom) {
+                    idleTickCount += 1;
+                }
+                else {
+                    idleTickCount = 0;
+                }
+                scrollBy(scrollOptions.distancePx);
+                stepCount += 1;
+                if (stepCount >= scrollOptions.maxSteps || idleTickCount >= scrollOptions.maxIdleTicks) {
+                    window.clearInterval(timer);
+                    resolve();
+                }
+            }, scrollOptions.intervalMs);
+        });
+    }, { distancePx, intervalMs, maxIdleTicks, maxSteps });
+};

package/dist/internal/utils/sandbox-args.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Returns Chromium CLI flags that disable the sandbox on Linux.
+ *
+ * Ubuntu 23.10+ (and other distros) restrict unprivileged user namespaces
+ * via AppArmor, which makes the Chrome sandbox fail with:
+ *
+ *   "No usable sandbox! … see apparmor-userns-restrictions.md"
+ *
+ * Adding `--no-sandbox --disable-setuid-sandbox` is the standard workaround
+ * recommended by Puppeteer for Linux environments (CI and desktop alike).
+ *
+ * On non-Linux platforms the sandbox works out of the box, so no extra
+ * flags are injected.
+ *
+ * Usage:
+ *   const args = [...(userArgs ?? []), ...getSandboxArgs()];
+ */
+export declare const getSandboxArgs: () => string[];

package/dist/internal/utils/sandbox-args.js

@@ -0,0 +1,24 @@
+import { platform } from "node:os";
+/**
+ * Returns Chromium CLI flags that disable the sandbox on Linux.
+ *
+ * Ubuntu 23.10+ (and other distros) restrict unprivileged user namespaces
+ * via AppArmor, which makes the Chrome sandbox fail with:
+ *
+ *   "No usable sandbox! … see apparmor-userns-restrictions.md"
+ *
+ * Adding `--no-sandbox --disable-setuid-sandbox` is the standard workaround
+ * recommended by Puppeteer for Linux environments (CI and desktop alike).
+ *
+ * On non-Linux platforms the sandbox works out of the box, so no extra
+ * flags are injected.
+ *
+ * Usage:
+ *   const args = [...(userArgs ?? []), ...getSandboxArgs()];
+ */
+export const getSandboxArgs = () => {
+    if (platform() !== "linux") {
+        return [];
+    }
+    return ["--no-sandbox", "--disable-setuid-sandbox"];
+};

package/dist/internal/utils/trigger-actions.js

@@ -1,37 +1,32 @@
+import { autoScrollToEnd } from "./puppeteer-auto-scroll.js";
+const hoverAllElements = async (page) => {
+    await page.evaluate(() => {
+        const elements = Array.from(document.querySelectorAll("*"));
+        const triggerMouseOver = (element) => {
+            const rect = element.getBoundingClientRect();
+            const pointerX = rect.left + rect.width / 2;
+            const pointerY = rect.top + rect.height / 2;
+            const event = new MouseEvent("mouseover", {
+                bubbles: true,
+                cancelable: true,
+                clientX: pointerX,
+                clientY: pointerY
+            });
+            element.dispatchEvent(event);
+        };
+        elements.forEach(triggerMouseOver);
+    });
+};
 export const runTriggerActions = async (page, actions = []) => {
     if (actions.length === 0) {
         return;
     }
-    await page.evaluate((actionsArg) => {
-        const hoverAll = () => {
-            const elements = Array.from(document.querySelectorAll("*"));
-            const trigger = (el) => {
-                const rect = el.getBoundingClientRect();
-                const pointerX = rect.left + rect.width / 2;
-                const pointerY = rect.top + rect.height / 2;
-                const event = new MouseEvent("mouseover", {
-                    bubbles: true,
-                    cancelable: true,
-                    clientX: pointerX,
-                    clientY: pointerY
-                });
-                el.dispatchEvent(event);
-            };
-            elements.forEach(trigger);
-        };
-        const scrollToEnd = () => {
-            const scrollHeight = document.documentElement?.scrollHeight ?? document.body?.scrollHeight;
-            if (typeof scrollHeight === "number") {
-                window.scrollTo({ top: scrollHeight, behavior: "instant" });
-            }
-        };
-        for (const action of actionsArg) {
-            if (action === "HOVER") {
-                hoverAll();
-            }
-            if (action === "SCROLL_TO_END") {
-                scrollToEnd();
-            }
+    for (const action of actions) {
+        if (action === "HOVER") {
+            await hoverAllElements(page);
+        }
+        if (action === "SCROLL_TO_END") {
+            await autoScrollToEnd(page);
         }
-    }, actions);
+    }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagepocket/capture-http-puppeteer-unit",
-  "version": "0.13.0",
+  "version": "0.14.5",
   "description": "PagePocket plugin: capture HTTP events (puppeteer adapter)",
   "type": "module",
   "main": "dist/index.js",
@@ -11,8 +11,9 @@
   "license": "ISC",
   "dependencies": {
     "puppeteer": "^22.12.1",
-    "@pagepocket/lib": "0.13.0",
-    "@pagepocket/contracts": "0.13.0"
+    "@puppeteer/browsers": "2.3.0",
+    "@pagepocket/contracts": "0.14.5",
+    "@pagepocket/lib": "0.14.5"
   },
   "devDependencies": {
     "typescript": "^5.4.5"