@pagepocket/lighterceptor

Capture outbound requests an HTML/JS/CSS payload would trigger in a jsdom
environment, without hitting the network.

Install

``bash
pnpm add @pagepocket/lighterceptor
`

Quick Start

`ts
import { Lighterceptor } from "@pagepocket/lighterceptor";

const html =










;

const result = await new Lighterceptor(html).run();
console.log(result.requests);
`

Recursion (Dependency Graph)

Enable recursion to keep walking JS/CSS/HTML dependencies. This is useful when
HTML loads CSS/JS, and those assets load more assets.

`ts
import { Lighterceptor } from "@pagepocket/lighterceptor";

const html =



;

const result = await new Lighterceptor(html, { recursion: true }).run();
console.log(result.requests.map((item) => item.url));
`

Recursion uses the global fetch to load discovered resources. In tests or
offline usage, stub fetch to return deterministic content.

API

$3

`ts
type LighterceptorOptions = {
settleTimeMs?: number;
recursion?: boolean;
requestOnly?: boolean;
baseUrl?: string;
};

type RequestRecord = {
url: string;
source: "resource" | "img" | "css" | "fetch" | "xhr" | "unknown";
timestamp: number;
};

type ResponseRecord = {
status: number;
statusText: string;
headers: Record;
body: string;
bodyEncoding: "text" | "base64";
};

type NetworkRecord = {
url: string;
source: "resource" | "img" | "css" | "fetch" | "xhr" | "unknown";
method: string;
timestamp: number;
response?: ResponseRecord;
error?: string;
};

type LighterceptorResult = {
title?: string;
capturedAt: string;
requests: RequestRecord[];
networkRecords?: NetworkRecord[];
};
`

- settleTimeMs: wait time before the run finishes, so script-driven requests
can be captured.
- recursion: when true, fetches JS/CSS/HTML resources and applies the same
interception logic to their dependencies.
- requestOnly: when true, skips response capture and only records request
metadata.
- baseUrl: absolute URL used to resolve /path URLs and other relative
references.

$3

Use this when you need low-level access to jsdom.

`ts
import { createJSDOMWithInterceptor } from "@pagepocket/lighterceptor";

const dom = createJSDOMWithInterceptor({
html: "",
domOptions: {
pretendToBeVisual: true,
runScripts: "dangerously"
},
interceptor: (url, options) => {
console.log("Intercepted", url, options.source);
return "";
}
});
`

Examples

See the examples/ directory for more:

- examples/basic-lighterceptor.ts
- examples/custom-interceptor.ts
- examples/aggregate-requests.ts
- examples/recursive-crawl.ts
- examples/real-world-moon.ts`