@pagepocket/lib 0.7.1 → 0.8.0

package/dist/snapshot-builder.js

@@ -4,7 +4,6 @@ exports.buildSnapshot = void 0;
 const css_rewrite_1 = require("./css-rewrite");
 const path_resolver_1 = require("./path-resolver");
 const rewrite_links_1 = require("./rewrite-links");
-const snapshot_1 = require("./snapshot");
 const utils_1 = require("./utils");
 const escapePercentForStaticServers = (value) => {
     // Many static servers decode percent-encoding in the request path before
@@ -18,6 +17,197 @@ const escapePercentForStaticServers = (value) => {
     // filename on disk.
     return value.split("%").join("%25");
 };
+const isApiResource = (request) => {
+    const type = request?.resourceType;
+    return type === "fetch" || type === "xhr";
+};
+const headersListToRecord = (headers) => {
+    const out = {};
+    for (const h of headers) {
+        out[h.name] = h.value;
+    }
+    return out;
+};
+const getHeaderValue = (headers, name) => {
+    const target = name.toLowerCase();
+    for (const key in headers) {
+        if (key.toLowerCase() === target) {
+            return headers[key];
+        }
+    }
+    return undefined;
+};
+const parseContentLength = (headers) => {
+    const raw = getHeaderValue(headers, "content-length");
+    if (!raw) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
+};
+const responseMimeType = (response) => response.mimeType || getHeaderValue(response.headers || {}, "content-type");
+const buildIndexFromCapture = async (input) => {
+    const byId = new Map();
+    const ensure = (requestId) => {
+        const existing = byId.get(requestId);
+        if (existing)
+            return existing;
+        const created = {};
+        byId.set(requestId, created);
+        return created;
+    };
+    for (const event of input.capture.events) {
+        if (event.type === "http.request") {
+            ensure(event.requestId).request = event;
+            continue;
+        }
+        if (event.type === "http.response") {
+            ensure(event.requestId).response = event;
+            continue;
+        }
+        if (event.type === "http.failed") {
+            ensure(event.requestId).failed = event;
+        }
+    }
+    const resources = [];
+    const apiEntries = [];
+    const apiSeen = new Set();
+    let totalBytes = 0;
+    const recordApiFailure = (request, failed) => {
+        if (apiSeen.has(request.requestId))
+            return;
+        apiSeen.add(request.requestId);
+        apiEntries.push({
+            request,
+            record: {
+                url: request.url,
+                method: request.method,
+                requestHeaders: request.headers,
+                error: failed.errorText,
+                timestamp: failed.timestamp
+            }
+        });
+    };
+    const recordApiResponse = async (request, response, bodyRef) => {
+        if (apiSeen.has(request.requestId))
+            return;
+        apiSeen.add(request.requestId);
+        const record = {
+            url: request.url,
+            method: request.method,
+            requestHeaders: request.headers,
+            status: response.status,
+            statusText: response.statusText,
+            responseHeaders: response.headers,
+            timestamp: response.timestamp
+        };
+        if (bodyRef) {
+            const stream = await input.capture.contentStore.open(bodyRef);
+            const bytes = await streamToUint8Array(stream);
+            if (bytes.byteLength > 0) {
+                const mimeType = responseMimeType(response);
+                const decoded = (0, utils_1.bodyToTextOrBase64)(bytes, mimeType);
+                if (decoded.encoding === "text") {
+                    record.responseBody = decoded.text;
+                    record.responseEncoding = "text";
+                }
+                else {
+                    record.responseBodyBase64 = decoded.base64;
+                    record.responseEncoding = "base64";
+                }
+            }
+        }
+        apiEntries.push({ request, record });
+    };
+    for (const record of byId.values()) {
+        if (!record.request || record.request.type !== "http.request") {
+            continue;
+        }
+        const requestEvent = record.request;
+        const request = {
+            type: "request",
+            requestId: requestEvent.requestId,
+            url: requestEvent.url,
+            method: requestEvent.method,
+            headers: headersListToRecord(requestEvent.headers),
+            timestamp: requestEvent.timestamp,
+            frameId: requestEvent.frameId,
+            resourceType: requestEvent.resourceType,
+            initiator: requestEvent.initiator
+        };
+        if (record.failed && record.failed.type === "http.failed") {
+            const failedEvent = record.failed;
+            const failed = {
+                type: "failed",
+                requestId: failedEvent.requestId,
+                url: failedEvent.url,
+                errorText: failedEvent.errorText,
+                timestamp: failedEvent.timestamp
+            };
+            if (isApiResource(request)) {
+                recordApiFailure(request, failed);
+            }
+            continue;
+        }
+        if (!record.response || record.response.type !== "http.response") {
+            continue;
+        }
+        const responseEvent = record.response;
+        const response = {
+            type: "response",
+            requestId: responseEvent.requestId,
+            url: responseEvent.url,
+            status: responseEvent.status,
+            statusText: responseEvent.statusText,
+            headers: headersListToRecord(responseEvent.headers),
+            timestamp: responseEvent.timestamp,
+            mimeType: responseEvent.mimeType,
+            fromDiskCache: responseEvent.fromDiskCache,
+            fromServiceWorker: responseEvent.fromServiceWorker,
+            body: undefined
+        };
+        const bodyRef = responseEvent.bodyRef;
+        const isApi = isApiResource(request);
+        if (isApi) {
+            await recordApiResponse(request, response, bodyRef);
+        }
+        const shouldSave = input.filter.shouldSave(request, response);
+        if (!shouldSave) {
+            continue;
+        }
+        if (!bodyRef) {
+            input.warnings.push(`Missing body for ${request.url}`);
+            continue;
+        }
+        const stream = await input.capture.contentStore.open(bodyRef);
+        const bytes = await streamToUint8Array(stream);
+        const byteLength = bytes.byteLength;
+        if (input.limits?.maxSingleResourceBytes && byteLength > input.limits.maxSingleResourceBytes) {
+            input.warnings.push(`Resource too large: ${request.url}`);
+            continue;
+        }
+        if (input.limits?.maxResources && resources.length >= input.limits.maxResources) {
+            input.warnings.push(`Resource limit reached at ${request.url}`);
+            continue;
+        }
+        if (input.limits?.maxTotalBytes && totalBytes + byteLength > input.limits.maxTotalBytes) {
+            input.warnings.push(`Total byte limit reached at ${request.url}`);
+            continue;
+        }
+        totalBytes += byteLength;
+        resources.push({
+            request,
+            response,
+            contentRef: bodyRef,
+            size: parseContentLength(response.headers || {}) ?? byteLength,
+            mimeType: responseMimeType(response)
+        });
+    }
+    return { resources, apiEntries };
+};
 const streamToUint8Array = async (stream) => {
     const reader = stream.getReader();
     const chunks = [];
@@ -161,6 +351,17 @@ const buildResourcesPathSnapshot = (createdAt, files) => {
             size: file.size
         });
     }
+    items.sort((left, right) => {
+        if (left.path < right.path)
+            return -1;
+        if (left.path > right.path)
+            return 1;
+        if (left.url < right.url)
+            return -1;
+        if (left.url > right.url)
+            return 1;
+        return 0;
+    });
     return {
         version: "1.0",
         createdAt,
@@ -169,10 +370,19 @@ const buildResourcesPathSnapshot = (createdAt, files) => {
 };
 const buildSnapshot = async (input) => {
     const warnings = input.warnings;
+    const shouldRewriteLinks = input.rewriteEntry !== false;
+    const contentStore = input.capture.contentStore;
+    const indexed = await buildIndexFromCapture({
+        capture: input.capture,
+        filter: input.filter,
+        entryUrl: input.entryUrl,
+        limits: input.limits,
+        warnings
+    });
     const groups = groupResources({
         entryUrl: input.entryUrl,
-        resources: input.resources,
-        apiEntries: input.apiEntries,
+        resources: indexed.resources,
+        apiEntries: indexed.apiEntries,
         warnings
     });
     const multiDoc = groups.length > 1;
@@ -211,9 +421,26 @@ const buildSnapshot = async (input) => {
         for (const resource of group.resources) {
             if (resource.request.resourceType === "document") {
                 const path = urlToPath.get(resource.request.url) ?? "/index.html";
-                const stream = await input.contentStore.open(resource.contentRef);
+                const stream = await contentStore.open(resource.contentRef);
                 const bytes = await streamToUint8Array(stream);
-                const decoded = (0, utils_1.decodeUtf8)(bytes) ?? "";
+                const decoded = (0, utils_1.decodeUtf8)(bytes);
+                if (decoded === null) {
+                    // Be defensive: if the document body can't be decoded, don't attempt rewrite.
+                    // Still emit a file so snapshot layout stays consistent.
+                    files.push({
+                        path,
+                        mimeType: resource.mimeType ?? "text/html",
+                        size: bytes.byteLength,
+                        source: resource.contentRef,
+                        originalUrl: resource.request.url,
+                        resourceType: resource.request.resourceType,
+                        headers: resource.response.headers
+                    });
+                    if (resource.request.url === input.entryUrl || !entryPath) {
+                        entryPath = path;
+                    }
+                    continue;
+                }
                 let html = decoded;
                 const rewritten = await (0, rewrite_links_1.rewriteEntryHtml)({
                     html,
@@ -230,7 +457,7 @@ const buildSnapshot = async (input) => {
                     title = rewritten.title;
                 }
                 const encoded = new TextEncoder().encode(html);
-                const contentRef = await input.contentStore.put({ kind: "buffer", data: encoded }, { url: resource.request.url, mimeType: resource.mimeType, sizeHint: encoded.byteLength });
+                const contentRef = await contentStore.put({ kind: "buffer", data: encoded }, { url: resource.request.url, mimeType: resource.mimeType, sizeHint: encoded.byteLength });
                 files.push({
                     path,
                     mimeType: resource.mimeType ?? "text/html",
@@ -248,7 +475,7 @@ const buildSnapshot = async (input) => {
             let contentRef = resource.contentRef;
             let size = resource.size;
             if (resource.request.resourceType === "stylesheet" && input.rewriteCSS) {
-                const stream = await input.contentStore.open(resource.contentRef);
+                const stream = await contentStore.open(resource.contentRef);
                 const bytes = await streamToUint8Array(stream);
                 const decoded = (0, utils_1.decodeUtf8)(bytes);
                 if (decoded !== null) {
@@ -259,7 +486,7 @@ const buildSnapshot = async (input) => {
                     });
                     if (rewritten !== decoded) {
                         const encoded = new TextEncoder().encode(rewritten);
-                        contentRef = await input.contentStore.put({ kind: "buffer", data: encoded }, {
+                        contentRef = await contentStore.put({ kind: "buffer", data: encoded }, {
                             url: resource.request.url,
                             mimeType: resource.mimeType,
                             sizeHint: encoded.byteLength
@@ -269,14 +496,14 @@ const buildSnapshot = async (input) => {
                 }
             }
             if (resource.request.resourceType === "script") {
-                const stream = await input.contentStore.open(contentRef);
+                const stream = await contentStore.open(contentRef);
                 const bytes = await streamToUint8Array(stream);
                 const decoded = (0, utils_1.decodeUtf8)(bytes);
                 if (decoded !== null) {
                     const rewritten = await (0, rewrite_links_1.rewriteJsText)(decoded, resolve, resource.request.url);
                     if (rewritten !== decoded) {
                         const encoded = new TextEncoder().encode(rewritten);
-                        contentRef = await input.contentStore.put({ kind: "buffer", data: encoded }, {
+                        contentRef = await contentStore.put({ kind: "buffer", data: encoded }, {
                             url: resource.request.url,
                             mimeType: resource.mimeType,
                             sizeHint: encoded.byteLength
@@ -305,8 +532,8 @@ const buildSnapshot = async (input) => {
             });
         }
         const apiSnapshot = buildApiSnapshot(group.url, input.createdAt, group.apiEntries);
-        const apiBytes = new TextEncoder().encode(JSON.stringify(apiSnapshot, null, 2));
-        const apiRef = await input.contentStore.put({ kind: "buffer", data: apiBytes }, { url: apiPath, mimeType: "application/json", sizeHint: apiBytes.byteLength });
+        const apiBytes = new TextEncoder().encode(`${JSON.stringify(apiSnapshot, null, 2)}\n`);
+        const apiRef = await contentStore.put({ kind: "buffer", data: apiBytes }, { url: apiPath, mimeType: "application/json", sizeHint: apiBytes.byteLength });
         files.push({
             path: apiPath,
             mimeType: "application/json",
@@ -317,7 +544,7 @@ const buildSnapshot = async (input) => {
     }
     {
         const resourcesPath = buildResourcesPathSnapshot(input.createdAt, files);
-        const bytes = new TextEncoder().encode(JSON.stringify(resourcesPath, null, 2));
+        const bytes = new TextEncoder().encode(`${JSON.stringify(resourcesPath, null, 2)}\n`);
         // Snapshot-local artifact. It intentionally has no originalUrl.
         files.push({
             path: "/resources_path.json",
@@ -329,24 +556,22 @@ const buildSnapshot = async (input) => {
     const totalBytes = files.reduce((sum, file) => sum + (file.size ?? 0), 0);
     const totalFiles = files.length;
     const snapshotUrl = input.entryUrl || groups[0]?.url || "";
-    return (0, snapshot_1.createPageSnapshot)({
-        version: "1.0",
-        createdAt: input.createdAt,
-        url: snapshotUrl,
-        title,
-        entry: entryPath || "/index.html",
-        files,
-        meta: {
-            totalBytes,
-            totalFiles,
-            warnings: warnings.length ? warnings : undefined
+    return {
+        root: {
+            kind: "directory",
+            path: "",
+            entries: files.map((file) => ({
+                kind: "file",
+                path: file.path,
+                source: { kind: "content-ref", ref: file.source }
+            }))
         },
         content: {
-            open: (ref) => input.contentStore.open(ref),
+            open: (ref) => contentStore.open(ref),
             dispose: async () => {
-                await input.contentStore.dispose?.();
+                await contentStore.dispose?.();
             }
         }
-    });
+    };
 };
 exports.buildSnapshot = buildSnapshot;

package/dist/types.d.ts

@@ -1,7 +1,121 @@
-import type { BodySource, NetworkInterceptorAdapter, NetworkRequestEvent, NetworkResponseEvent, ResourceType } from "@pagepocket/interceptor";
+/**
+ * Network types used by the plugin runner and capture plugins.
+ *
+ * NOTE: This repo previously sourced these from a dedicated `@pagepocket/interceptor` package.
+ * That package has been removed; the contracts live in `@pagepocket/lib` now.
+ */
 import type { Cheerio, CheerioAPI } from "cheerio";
-export type { BodySource, InterceptOptions, InterceptSession, InterceptTarget, InterceptorActions, InterceptorCapabilities, NavigateOptions, NetworkEvent, NetworkEventHandlers, NetworkInterceptorAdapter, NetworkRequestEvent, NetworkRequestFailedEvent, NetworkResponseEvent, ResourceType, TriggerAction } from "@pagepocket/interceptor";
-import type { NetworkEvent } from "@pagepocket/interceptor";
+export type ResourceType = "document" | "stylesheet" | "script" | "image" | "font" | "media" | "xhr" | "fetch" | "other" | (string & {});
+export type BodySource = {
+    kind: "buffer";
+    data: Uint8Array;
+} | {
+    kind: "stream";
+    stream: ReadableStream<Uint8Array>;
+} | {
+    kind: "late";
+    read: () => Promise<Uint8Array>;
+};
+export interface NetworkRequestEvent {
+    type: "request";
+    requestId: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    frameId?: string;
+    resourceType?: ResourceType;
+    initiator?: {
+        type?: string;
+        url?: string;
+    };
+    timestamp: number;
+}
+export interface NetworkResponseEvent {
+    type: "response";
+    requestId: string;
+    url: string;
+    status: number;
+    statusText?: string;
+    headers: Record<string, string>;
+    mimeType?: string;
+    fromDiskCache?: boolean;
+    fromServiceWorker?: boolean;
+    timestamp: number;
+    body?: BodySource;
+}
+export interface NetworkRequestFailedEvent {
+    type: "failed";
+    requestId: string;
+    url: string;
+    errorText: string;
+    timestamp: number;
+}
+export type NetworkEvent = NetworkRequestEvent | NetworkResponseEvent | NetworkRequestFailedEvent;
+export interface NetworkEventHandlers {
+    onEvent(event: NetworkEvent): void;
+    onError?(error: Error): void;
+    onLog?(msg: string, meta?: unknown): void;
+}
+export interface InterceptorCapabilities {
+    canGetResponseBody: boolean;
+    canStreamResponseBody: boolean;
+    canGetRequestBody: boolean;
+    providesResourceType: boolean;
+    /** Adapter can provide a primary-document HTML milestone. */
+    canWaitForHtml: boolean;
+    /** Adapter implements a meaningful staged capture boundary. */
+    supportsStagedCapture: boolean;
+}
+export type InterceptTarget = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "puppeteer-page";
+    page: unknown;
+} | {
+    kind: "cdp-tab";
+    tabId: number;
+} | {
+    kind: "html";
+    htmlString: string;
+    baseUrl: string;
+    url?: string;
+};
+export type InterceptOptions = Record<string, unknown>;
+export type NavigateOptions = Record<string, unknown>;
+export interface InterceptSession {
+    navigate?(url: string, options?: NavigateOptions): Promise<void>;
+    waitForHtml(): Promise<{
+        htmlString: string;
+        baseUrl: string;
+        url?: string;
+        contentType?: string;
+    }>;
+    /**
+     * Returns a snapshot of the current DOM HTML.
+     *
+     * This is intended to be called after capture completion (e.g. after network
+     * idle) when the page has finished client-side rendering.
+     */
+    getDomHtml?(): Promise<{
+        htmlString: string;
+        baseUrl: string;
+        url?: string;
+        contentType?: string;
+    }>;
+    startCapture(): Promise<void>;
+    stop(): Promise<void>;
+}
+export type InterceptorActions = {
+    triggerActions?: TriggerAction[];
+    timeoutMs?: number;
+    maxDurationMs?: number;
+};
+export interface NetworkInterceptorAdapter {
+    readonly name: string;
+    readonly capabilities: InterceptorCapabilities;
+    start(target: InterceptTarget, handlers: NetworkEventHandlers, options?: InterceptOptions & InterceptorActions): Promise<InterceptSession>;
+}
 export interface PathResolver {
     resolve(input: {
         url: string;
@@ -50,43 +164,11 @@ export interface CompletionStrategy {
 export interface PagePocketOptions {
 }
 export type NetworkEventStream = AsyncIterable<NetworkEvent>;
-export interface CaptureOptions {
-    interceptor: NetworkInterceptorAdapter;
-    completion?: CompletionStrategy | CompletionStrategy[];
-    /**
-     * Network idle duration (ms) used to determine capture completion.
-     *
-     * If `completion` is not provided, PagePocket will wait until the network has
-     * been idle (no inflight requests) for this duration.
-     *
-     * Note: this is NOT a wall-clock timeout from capture start.
-     */
-    timeoutMs?: number;
-    /**
-     * Hard wall-clock limit (ms) for the overall capture session.
-     *
-     * When `completion` is not provided, PagePocket will stop after either:
-     * - network has been idle for `timeoutMs`, OR
-     * - `maxDurationMs` has elapsed.
-     */
-    maxDurationMs?: number;
-    filter?: ResourceFilter;
-    pathResolver?: PathResolver;
-    contentStore?: ContentStore;
-    rewriteEntry?: boolean;
-    rewriteCSS?: boolean;
-    blacklist?: RegExp[];
-    /**
-     * Replace parts of the captured HTML (Document response body) during the HTML
-     * rewrite stage (Cheerio).
-     */
-    replaceElements?: ReplaceElementsConfig;
-    limits?: {
-        maxTotalBytes?: number;
-        maxSingleResourceBytes?: number;
-        maxResources?: number;
-    };
-}
+export declare const TriggerActionValues: {
+    readonly HOVER: "HOVER";
+    readonly SCROLL_TO_END: "SCROLL_TO_END";
+};
+export type TriggerAction = (typeof TriggerActionValues)[keyof typeof TriggerActionValues];
 export type ReplaceElementsConfig = Array<ReplaceElementRule | ReplaceElementFn | ReplaceElementFnWithQuery>;
 export type MatchQuery = string | {
     selector?: string;
@@ -146,44 +228,6 @@ export interface SnapshotFile {
     resourceType?: ResourceType;
     headers?: Record<string, string>;
 }
-export interface PageSnapshot {
-    version: "1.0";
-    createdAt: number;
-    url: string;
-    title?: string;
-    entry: string;
-    files: SnapshotFile[];
-    meta?: {
-        totalBytes?: number;
-        totalFiles?: number;
-        warnings?: string[];
-    };
-    content: ContentStoreHandle;
-    toDirectory(outDir: string, options?: WriteFSOptions): Promise<WriteResult>;
-    toZip(options?: ZipOptions): Promise<ZipResult>;
-}
-export interface WriteFSOptions {
-    clearCache?: boolean;
-    overwrite?: boolean;
-    suffix?: string;
-}
-export interface WriteResult {
-    filesWritten: number;
-    totalBytes: number;
-    outputDir?: string;
-}
-export interface ZipOptions {
-    asBlob?: boolean;
-    clearCache?: boolean;
-    overwrite?: boolean;
-    suffix?: string;
-    outputPath?: string;
-}
-export interface ZipWriteResult {
-    data: Uint8Array | Blob;
-    outputPath: string;
-}
-export type ZipResult = Uint8Array | Blob | ZipWriteResult;
 export interface ApiRecord {
     url: string;
     method: string;

package/dist/types.js

@@ -1,2 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export const TriggerActionValues = {
+    HOVER: "HOVER",
+    SCROLL_TO_END: "SCROLL_TO_END"
+};

package/dist/units/contracts-bridge.d.ts

@@ -0,0 +1,76 @@
+import type { ChannelToken, ReplaceElementsConfig } from "@pagepocket/contracts";
+export type CaptureResult = {
+    kind: "raw";
+    outputDir: string;
+    meta?: unknown;
+} | {
+    kind: "zip";
+    zip: {
+        data: Uint8Array | Blob;
+        outputPath: string;
+    };
+    meta?: unknown;
+} | {
+    kind: "html";
+    html: string;
+    meta?: unknown;
+} | {
+    kind: "text";
+    text: string;
+    meta?: unknown;
+} | {
+    kind: "custom";
+    value: unknown;
+};
+export type DeferredHandle = Promise<unknown>;
+export type UnitValue = Record<string, unknown>;
+export type UnitContext<T = UnitValue> = {
+    value: T;
+};
+export type UnitContributeContext<TValue = UnitValue, TSetupValue = unknown> = UnitContext<TValue> & {
+    setupValue: TSetupValue | undefined;
+};
+export declare const TERMINAL_RESULT_KEY: "__pagepocketResult";
+export type UnitPatch = UnitValue & {
+    [TERMINAL_RESULT_KEY]?: CaptureResult;
+};
+export interface ElementPatchRegistry {
+    contribute(source: {
+        type: "unit" | "plugin";
+        name: string;
+    }, rules: ReplaceElementsConfig): void;
+    contributeLazy(source: {
+        type: "unit" | "plugin";
+        name: string;
+    }, build: () => ReplaceElementsConfig | Promise<ReplaceElementsConfig>): void;
+    compile(): Promise<ReplaceElementsConfig>;
+}
+export interface UnitRuntime {
+    readonly entry: import("./types.js").EntryInfo;
+    readonly options: import("./types.js").CaptureOptions;
+    readonly pocketOptions: import("./types.js").PagePocketOptions;
+    publish<T>(t: ChannelToken<T>, value: T): void;
+    subscribe<T>(t: ChannelToken<T>): AsyncIterable<T>;
+    hasPublisher(t: ChannelToken<unknown>): boolean;
+    readonly elements: ElementPatchRegistry;
+    defer(promise: DeferredHandle): void;
+}
+export interface PluginHost {
+    readonly entry: import("./types.js").EntryInfo;
+    readonly options: import("./types.js").CaptureOptions;
+    subscribe<T>(t: ChannelToken<T>): AsyncIterable<T>;
+    hasPublisher(t: ChannelToken<unknown>): boolean;
+    readonly elements: ElementPatchRegistry;
+    defer(promise: DeferredHandle): void;
+}
+export declare abstract class Unit {
+    abstract readonly id: string;
+    abstract readonly kind: string;
+    abstract run(ctx: UnitContext, rt: UnitRuntime): Promise<void | UnitPatch>;
+    merge(returnValue: UnitPatch, pluginContributedValue?: UnitPatch): UnitPatch;
+}
+export interface Plugin<TSetupValue = unknown> {
+    readonly name: string;
+    setup(host: PluginHost): TSetupValue | void | Promise<TSetupValue | void>;
+    contribute?(ctx: UnitContributeContext<UnitValue, TSetupValue>, rt: UnitRuntime): Promise<UnitPatch>;
+}

package/dist/units/contracts-bridge.js

@@ -0,0 +1,6 @@
+export const TERMINAL_RESULT_KEY = "__pagepocketResult";
+export class Unit {
+    merge(returnValue, pluginContributedValue = {}) {
+        return { ...returnValue, ...pluginContributedValue };
+    }
+}

package/dist/units/index.d.ts

@@ -0,0 +1,4 @@
+export type { CaptureOptions, EntryInfo } from "./types.js";
+export type { CaptureResult, Plugin, PluginHost, UnitRuntime } from "./contracts-bridge.js";
+export { Unit } from "./contracts-bridge.js";
+export { runCapture } from "./runner.js";

package/dist/units/index.js

@@ -0,0 +1,2 @@
+export { Unit } from "./contracts-bridge.js";
+export { runCapture } from "./runner.js";