@pagepocket/lib 0.11.1 → 0.13.0

package/dist/core/pagepocket.d.ts

@@ -13,11 +13,27 @@ export type CaptureTarget = {
     baseUrl: string;
     url?: string;
 };
+import type { ProgressEvent } from "@pagepocket/contracts";
 import type { PagePocketOptions } from "../types.js";
 import type { CaptureResult as PagePocketCaptureResult, Plugin as V3Plugin, Unit as V3Unit } from "../units/contracts-bridge.js";
+import type { CaptureOptions } from "../units/types.js";
+export type CaptureEventMap = {
+    "unit:start": Extract<ProgressEvent, {
+        type: "unit:start";
+    }>;
+    "unit:end": Extract<ProgressEvent, {
+        type: "unit:end";
+    }>;
+    "unit:log": Extract<ProgressEvent, {
+        type: "unit:log";
+    }>;
+};
+type CaptureEventName = keyof CaptureEventMap;
+type CaptureEventListener<K extends CaptureEventName> = (event: CaptureEventMap[K]) => void;
 export declare class PagePocket {
     private target;
     private options;
+    private listeners;
     private constructor();
     static fromURL(url: string, options?: PagePocketOptions): PagePocket;
     static fromPuppeteerPage(page: unknown, options?: PagePocketOptions): PagePocket;
@@ -31,8 +47,10 @@ export declare class PagePocket {
         url?: string;
         serialize?: (doc: unknown) => string;
     } & PagePocketOptions): PagePocket;
+    on<K extends CaptureEventName>(event: K, listener: CaptureEventListener<K>): this;
     capture(options: {
         units: V3Unit[];
         plugins?: V3Plugin[];
-    } & import("../units/types.js").CaptureOptions): Promise<PagePocketCaptureResult>;
+    } & CaptureOptions): Promise<PagePocketCaptureResult>;
 }
+export {};

package/dist/core/pagepocket.js

@@ -1,6 +1,7 @@
 import { runCapture } from "../units/index.js";
 export class PagePocket {
     constructor(target, options) {
+        this.listeners = new Map();
         this.target = target;
         this.options = options ?? {};
     }
@@ -32,6 +33,16 @@ export class PagePocket {
         const { baseUrl, url, serialize: _serialize, ...rest } = options;
         return new PagePocket({ kind: "html", htmlString, baseUrl, ...(url ? { url } : {}) }, rest);
     }
+    on(event, listener) {
+        const existing = this.listeners.get(event);
+        if (existing) {
+            existing.push(listener);
+        }
+        else {
+            this.listeners.set(event, [listener]);
+        }
+        return this;
+    }
     async capture(options) {
         const entry = this.target.kind === "url"
             ? { kind: "url", url: this.target.url }
@@ -45,12 +56,25 @@ export class PagePocket {
                         htmlString: this.target.htmlString,
                         ...(this.target.url ? { url: this.target.url } : {})
                     };
+        const hasListeners = this.listeners.size > 0;
+        const onProgress = hasListeners
+            ? (event) => {
+                const eventListeners = this.listeners.get(event.type);
+                if (!eventListeners) {
+                    return;
+                }
+                for (const listener of eventListeners) {
+                    listener(event);
+                }
+            }
+            : undefined;
         const result = await runCapture({
             entry,
             pocketOptions: this.options,
             options,
             units: options.units,
-            plugins: options.plugins
+            plugins: options.plugins,
+            onProgress
         });
         return result;
     }

package/dist/hackers/replay-css-proxy.js

@@ -33,8 +33,8 @@ export const replayCssProxy = {
           if (!next) {
             return full;
           }
-          const q = quote || "";
-          return "url(" + q + next + q + ")";
+          const quoteSymbol = quote || "";
+          return "url(" + quoteSymbol + next + quoteSymbol + ")";
         } catch {
           return full;
         }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { PagePocket } from "./core/pagepocket.js";
+export type { CaptureEventMap } from "./core/pagepocket.js";
 export * from "./units/index.js";
 export type { UnitContext, UnitContributeContext, UnitPatch, UnitRuntime } from "./units/contracts-bridge.js";
 export { TERMINAL_RESULT_KEY } from "./units/contracts-bridge.js";

package/dist/kind-map.js

@@ -42,17 +42,13 @@ export const requiredEntryKindError = (unitName, requiredKind, entry) => {
  * Convenience handler for `mapKind` that throws a standardized
  * "does not support entry kind" error.
  */
-export const throwUnsupportedEntryKind = (unitName) => {
-    return (_kind, entry) => {
-        throw unsupportedEntryKindError(unitName, entry);
-    };
+export const throwUnsupportedEntryKind = (unitName) => (_kind, entry) => {
+    throw unsupportedEntryKindError(unitName, entry);
 };
 /**
  * Convenience handler for `mapKind` that throws a standardized
  * "requires entry kind" error.
  */
-export const throwRequiredEntryKind = (unitName, requiredKind) => {
-    return (_kind, entry) => {
-        throw requiredEntryKindError(unitName, requiredKind, entry);
-    };
+export const throwRequiredEntryKind = (unitName, requiredKind) => (_kind, entry) => {
+    throw requiredEntryKindError(unitName, requiredKind, entry);
 };

package/dist/replace-elements/normalize.js

@@ -3,9 +3,7 @@ const defaultApply = {
     limit: "all",
     onReplaced: "stop"
 };
-const isPlainObject = (value) => {
-    return typeof value === "object" && value !== null;
-};
+const isPlainObject = (value) => typeof value === "object" && value !== null;
 const normalizeApply = (apply) => ({
     scope: apply?.scope ?? defaultApply.scope,
     limit: apply?.limit ?? defaultApply.limit,

package/dist/replace-elements.js

@@ -7,19 +7,19 @@ const runFnRuleOnSelection = async (input) => {
     const selection = $(item.query).toArray();
     const limit = item.apply.limit;
     const max = limit === "all" ? selection.length : Math.max(0, limit);
-    for (let i = 0; i < selection.length && i < max; i += 1) {
-        const el = selection[i];
-        const $el = $(el);
-        if (!isHtmlElement($, $el)) {
+    for (let selectionIndex = 0; selectionIndex < selection.length && selectionIndex < max; selectionIndex += 1) {
+        const selectedElement = selection[selectionIndex];
+        const $selectedElement = $(selectedElement);
+        if (!isHtmlElement($, $selectedElement)) {
             continue;
         }
         const ctx = {
             $,
-            $el,
+            $el: $selectedElement,
             url: input.url,
             entryUrl: input.entryUrl,
             ruleIndex: item.ruleIndex,
-            matchIndex: i
+            matchIndex: selectionIndex
         };
         const result = await item.run(ctx);
         if (!result) {
@@ -27,7 +27,7 @@ const runFnRuleOnSelection = async (input) => {
         }
         const actions = Array.isArray(result) ? result : [result];
         for (const action of actions) {
-            applyReplaceAction($, $el, action);
+            applyReplaceAction($, $selectedElement, action);
         }
     }
 };
@@ -56,22 +56,22 @@ export const applyReplaceElements = async (input) => {
         const limit = item.apply.limit;
         const max = limit === "all" ? selection.length : Math.max(0, limit);
         let replacedCount = 0;
-        for (let i = 0; i < selection.length && replacedCount < max; i += 1) {
-            const el = selection[i];
-            if (item.apply.onReplaced === "stop" && replacedByIndex.has(el)) {
+        for (let selectionIndex = 0; selectionIndex < selection.length && replacedCount < max; selectionIndex += 1) {
+            const selectedElementIdentity = selection[selectionIndex];
+            if (item.apply.onReplaced === "stop" && replacedByIndex.has(selectedElementIdentity)) {
                 continue;
             }
-            const $el = input.$(selection[i]);
-            if (!isHtmlElement(input.$, $el)) {
+            const $selectedElement = input.$(selection[selectionIndex]);
+            if (!isHtmlElement(input.$, $selectedElement)) {
                 continue;
             }
-            if (!elementMatchesFilter(input.$, $el, filter)) {
+            if (!elementMatchesFilter(input.$, $selectedElement, filter)) {
                 continue;
             }
-            applyReplaceAction(input.$, $el, item.rule.replace);
+            applyReplaceAction(input.$, $selectedElement, item.rule.replace);
             replacedCount += 1;
             if (item.apply.onReplaced === "stop") {
-                replacedByIndex.add(el);
+                replacedByIndex.add(selectedElementIdentity);
             }
         }
     }

package/dist/resource-proxy/escape-percent.js

@@ -1,6 +1,4 @@
-const looksAlreadyEscapedForStaticServers = (value) => {
-    return /%25[0-9a-fA-F]{2}/.test(value);
-};
+const looksAlreadyEscapedForStaticServers = (value) => /%25[0-9a-fA-F]{2}/.test(value);
 export const escapePercentForStaticServersOnce = (value) => {
     if (!value) {
         return value;

package/dist/resource-proxy/pathname-variants.js

@@ -14,19 +14,19 @@ const encodeEmbeddedUrlTailIfPresent = (pathname) => {
         return undefined;
     }
     const parts = raw.split("/");
-    for (let i = 0; i < parts.length; i += 1) {
-        const scheme = parts[i];
+    for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
+        const scheme = parts[partIndex];
         if (scheme !== "http:" && scheme !== "https:") {
             continue;
         }
-        const hasDoubleSlash = parts[i + 1] === "";
-        const host = parts[i + 2] || "";
+        const hasDoubleSlash = parts[partIndex + 1] === "";
+        const host = parts[partIndex + 2] || "";
         if (!hasDoubleSlash || !isLikelyHostname(host)) {
             continue;
         }
-        const embedded = scheme + "//" + parts.slice(i + 2).join("/");
+        const embedded = scheme + "//" + parts.slice(partIndex + 2).join("/");
         const encoded = encodeURIComponent(embedded);
-        const nextParts = parts.slice(0, i).concat(encoded);
+        const nextParts = parts.slice(0, partIndex).concat(encoded);
         const rebuilt = nextParts.join("/") || "/";
         return rebuilt.startsWith("/") ? rebuilt : "/" + rebuilt;
     }

package/dist/resource-proxy.js

@@ -92,7 +92,7 @@ const preferSingle = (items, baseUrl, suffixLength) => {
         }
     })();
     if (baseParsed) {
-        const sameOrigin = items.filter((i) => i.parsed.origin === baseParsed.origin);
+        const sameOrigin = items.filter((indexedItem) => indexedItem.parsed.origin === baseParsed.origin);
         if (sameOrigin.length === 1) {
             return sameOrigin[0];
         }
@@ -120,9 +120,9 @@ const tryCandidates = (items, baseUrl, suffixLength) => {
 const makeSuffixes = (pathname) => {
     const parts = pathname.split("/").filter(Boolean);
     const out = [];
-    for (let i = 0; i < parts.length; i += 1) {
-        const suffix = "/" + parts.slice(i).join("/");
-        out.push({ key: suffix, depth: parts.length - i });
+    for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
+        const suffix = "/" + parts.slice(partIndex).join("/");
+        out.push({ key: suffix, depth: parts.length - partIndex });
     }
     return out;
 };
@@ -175,7 +175,7 @@ export const resolveToLocalPath = (options) => {
     const pathname = abs.pathname || "/";
     const pathnameVariants = makePathnameVariants(pathname);
     const search = abs.search || "";
-    const pathnameWithSearchVariants = pathnameVariants.map((p) => p + search);
+    const pathnameWithSearchVariants = pathnameVariants.map((pathnameVariant) => pathnameVariant + search);
     for (const key of pathnameWithSearchVariants) {
         const items = toArray(index.byPathnameWithSearch.get(key));
         const match = tryCandidates(items, baseUrl, 99);

package/dist/rewrite-links/srcset.js

@@ -24,7 +24,7 @@ const isDescriptorToken = (token) => {
 const parseSrcset = (input) => {
     const rawCandidates = input
         .split(",")
-        .map((c) => c.trim())
+        .map((candidateText) => candidateText.trim())
         .filter(Boolean);
     return rawCandidates.map((candidate) => {
         const tokens = candidate.split(/\s+/).filter(Boolean);
@@ -40,26 +40,24 @@ const parseSrcset = (input) => {
         return { url: candidate };
     });
 };
-const stringifySrcset = (candidates) => {
-    return candidates
-        .map((c) => {
-        const url = c.url.trim();
-        if (!c.descriptor) {
-            return url;
-        }
-        return `${url} ${c.descriptor.trim()}`;
-    })
-        .filter(Boolean)
-        .join(",");
-};
+const stringifySrcset = (candidates) => candidates
+    .map((candidate) => {
+    const url = candidate.url.trim();
+    if (!candidate.descriptor) {
+        return url;
+    }
+    return `${url} ${candidate.descriptor.trim()}`;
+})
+    .filter(Boolean)
+    .join(",");
 export const rewriteSrcsetValue = (value, baseUrl, resolve) => {
     if (isUnsafeSrcsetValue(value)) {
         return "";
     }
     const candidates = parseSrcset(value);
-    const rewritten = candidates.map((c) => {
-        const resolved = resolveUrlValue(c.url, baseUrl, resolve);
-        return { url: resolved ?? c.url, descriptor: c.descriptor };
+    const rewritten = candidates.map((candidate) => {
+        const resolved = resolveUrlValue(candidate.url, baseUrl, resolve);
+        return { url: resolved ?? candidate.url, descriptor: candidate.descriptor };
     });
     return stringifySrcset(rewritten);
 };

package/dist/snapshot-builder/http.js

@@ -1,7 +1,7 @@
 export const headersListToRecord = (headers) => {
     const out = {};
-    for (const h of headers) {
-        out[h.name] = h.value;
+    for (const header of headers) {
+        out[header.name] = header.value;
     }
     return out;
 };

package/dist/snapshot-builder/path-map.js

@@ -1,16 +1,15 @@
 import { sanitizePosixPath } from "../utils.js";
-export const escapePercentForStaticServers = (value) => {
-    // Many static servers decode percent-encoding in the request path before
-    // resolving it to a filesystem path.
-    //
-    // Our snapshots can contain literal "%2F" sequences in filenames (e.g.
-    // Substack image URLs embedded into a path segment). When a server decodes
-    // "%2F" to "/", it changes the path structure and causes 404s.
-    //
-    // Escaping "%" to "%25" makes the request decode back to the original
-    // filename on disk.
-    return value.split("%").join("%25");
-};
+export const escapePercentForStaticServers = (value) => 
+// Many static servers decode percent-encoding in the request path before
+// resolving it to a filesystem path.
+//
+// Our snapshots can contain literal "%2F" sequences in filenames (e.g.
+// Substack image URLs embedded into a path segment). When a server decodes
+// "%2F" to "/", it changes the path structure and causes 404s.
+//
+// Escaping "%" to "%25" makes the request decode back to the original
+// filename on disk.
+value.split("%").join("%25");
 export const docDirFromUrl = (url) => {
     try {
         const parsed = new URL(url);

package/dist/units/apply-replace-elements-to-file-tree.d.ts

@@ -0,0 +1,7 @@
+import type { FileTree } from "../core/file-tree.js";
+import type { ReplaceElementsConfig } from "../types.js";
+export declare const applyReplaceElementsToFileTree: (input: {
+    files: FileTree;
+    replaceElements: ReplaceElementsConfig;
+    entryUrl: string;
+}) => Promise<FileTree>;

package/dist/units/apply-replace-elements-to-file-tree.js

@@ -0,0 +1,63 @@
+import * as cheerio from "cheerio";
+import { applyReplaceElements } from "../replace-elements.js";
+import { streamToUint8Array } from "../utils/streams.js";
+import { decodeUtf8 } from "../utils.js";
+const isHtmlFile = (path) => path.endsWith(".html") || path.endsWith(".htm");
+const readFileSource = async (file, fileTree) => {
+    const source = file.source;
+    if (source.kind === "bytes") {
+        return source.data;
+    }
+    if (source.kind === "text") {
+        return new TextEncoder().encode(source.text);
+    }
+    if (source.kind === "content-ref" && fileTree.content) {
+        const stream = await fileTree.content.open(source.ref);
+        return streamToUint8Array(stream);
+    }
+    return undefined;
+};
+const processHtmlFile = async (file, fileTree, replaceElements, entryUrl) => {
+    const bytes = await readFileSource(file, fileTree);
+    if (!bytes) {
+        return file;
+    }
+    const decoded = decodeUtf8(bytes);
+    if (typeof decoded === "undefined") {
+        return file;
+    }
+    const $ = cheerio.load(decoded);
+    await applyReplaceElements({
+        $,
+        entryUrl,
+        url: entryUrl,
+        replaceElements,
+        isEntryDocument: true
+    });
+    const updatedHtml = $.html();
+    const updatedBytes = new TextEncoder().encode(updatedHtml);
+    return {
+        ...file,
+        source: { kind: "bytes", data: updatedBytes }
+    };
+};
+const processDirectory = async (dir, fileTree, replaceElements, entryUrl) => {
+    const updatedEntries = [];
+    for (const entry of dir.entries) {
+        if (entry.kind === "file" && isHtmlFile(entry.path)) {
+            updatedEntries.push(await processHtmlFile(entry, fileTree, replaceElements, entryUrl));
+            continue;
+        }
+        if (entry.kind === "directory") {
+            updatedEntries.push(await processDirectory(entry, fileTree, replaceElements, entryUrl));
+            continue;
+        }
+        updatedEntries.push(entry);
+    }
+    return { ...dir, entries: updatedEntries };
+};
+export const applyReplaceElementsToFileTree = async (input) => {
+    const { files, replaceElements, entryUrl } = input;
+    const updatedRoot = await processDirectory(files.root, files, replaceElements, entryUrl);
+    return { ...files, root: updatedRoot };
+};

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

@@ -1,4 +1,5 @@
 import type { ChannelToken, ReplaceElementsConfig } from "@pagepocket/contracts";
+import type { CaptureOptions, EntryInfo, PagePocketOptions } from "./types.js";
 export type CaptureResult = {
     kind: "raw";
     outputDir: string;
@@ -46,18 +47,26 @@ export interface ElementPatchRegistry {
     compile(): Promise<ReplaceElementsConfig>;
 }
 export interface UnitRuntime {
-    readonly entry: import("./types.js").EntryInfo;
-    readonly options: import("./types.js").CaptureOptions;
-    readonly pocketOptions: import("./types.js").PagePocketOptions;
+    readonly entry: EntryInfo;
+    readonly options: CaptureOptions;
+    readonly pocketOptions: 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;
+    /**
+     * Emit a log message from the currently executing unit.
+     *
+     * The message is published on the well-known PROGRESS channel as a
+     * `unit:log` event so external consumers (e.g. `PagePocket.on("unit:log", …)`)
+     * can observe it.
+     */
+    log(message: string, data?: unknown): void;
 }
 export interface PluginHost {
-    readonly entry: import("./types.js").EntryInfo;
-    readonly options: import("./types.js").CaptureOptions;
+    readonly entry: EntryInfo;
+    readonly options: CaptureOptions;
     subscribe<T>(t: ChannelToken<T>): AsyncIterable<T>;
     hasPublisher(t: ChannelToken<unknown>): boolean;
     readonly elements: ElementPatchRegistry;
@@ -65,7 +74,7 @@ export interface PluginHost {
 }
 export declare abstract class Unit {
     abstract readonly id: string;
-    abstract readonly kind: string;
+    abstract readonly description: string;
     abstract run(ctx: UnitContext, rt: UnitRuntime): Promise<void | UnitPatch>;
     merge(returnValue: UnitPatch, pluginContributedValue?: UnitPatch): UnitPatch;
 }

package/dist/units/file-tree-unit.d.ts

@@ -0,0 +1,28 @@
+import { Unit, type UnitPatch } from "./contracts-bridge.js";
+/**
+ * Abstract base class for units whose `run()` produces a `FileTree`.
+ *
+ * Provides a default `merge` implementation that deep-merges the `files`
+ * property when both the unit return value and the plugin-contributed value
+ * contain a valid `FileTree`.  All other properties are shallow-spread
+ * (plugin wins on conflict), matching the base `Unit.merge` behaviour.
+ *
+ * Subclasses only need to implement `id` and `run()`.
+ *
+ * Usage:
+ * ```ts
+ * import { FileTreeUnit } from "@pagepocket/lib";
+ *
+ * export class MyUnit extends FileTreeUnit {
+ *   readonly id = "my";
+ *
+ *   async run(ctx, rt) {
+ *     const files = buildFiles();
+ *     return { files };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class FileTreeUnit extends Unit {
+    merge(returnValue: UnitPatch, pluginContributedValue?: UnitPatch): UnitPatch;
+}

package/dist/units/file-tree-unit.js

@@ -0,0 +1,53 @@
+import { mergeFileTrees } from "../core/file-tree-merge.js";
+import { Unit } from "./contracts-bridge.js";
+/**
+ * Abstract base class for units whose `run()` produces a `FileTree`.
+ *
+ * Provides a default `merge` implementation that deep-merges the `files`
+ * property when both the unit return value and the plugin-contributed value
+ * contain a valid `FileTree`.  All other properties are shallow-spread
+ * (plugin wins on conflict), matching the base `Unit.merge` behaviour.
+ *
+ * Subclasses only need to implement `id` and `run()`.
+ *
+ * Usage:
+ * ```ts
+ * import { FileTreeUnit } from "@pagepocket/lib";
+ *
+ * export class MyUnit extends FileTreeUnit {
+ *   readonly id = "my";
+ *
+ *   async run(ctx, rt) {
+ *     const files = buildFiles();
+ *     return { files };
+ *   }
+ * }
+ * ```
+ */
+export class FileTreeUnit extends Unit {
+    merge(returnValue, pluginContributedValue = {}) {
+        const mergedValue = { ...returnValue, ...pluginContributedValue };
+        const returnFiles = returnValue.files;
+        const pluginFiles = pluginContributedValue.files;
+        if (!isFileTree(returnFiles) || !isFileTree(pluginFiles)) {
+            return mergedValue;
+        }
+        return { ...mergedValue, files: mergeFileTrees(returnFiles, pluginFiles) };
+    }
+}
+const isFileTree = (value) => {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    if (!("root" in value)) {
+        return false;
+    }
+    const root = value.root;
+    if (!root || typeof root !== "object") {
+        return false;
+    }
+    const rootRecord = root;
+    return (rootRecord.kind === "directory" &&
+        typeof rootRecord.path === "string" &&
+        Array.isArray(rootRecord.entries));
+};

package/dist/units/index.d.ts

@@ -1,4 +1,7 @@
 export type { CaptureOptions, EntryInfo } from "./types.js";
 export type { CaptureResult, Plugin, PluginHost, UnitRuntime } from "./contracts-bridge.js";
 export { Unit } from "./contracts-bridge.js";
+export { FileTreeUnit } from "./file-tree-unit.js";
+export { SnapshotUnit } from "./snapshot-unit.js";
 export { runCapture } from "./runner.js";
+export type { ProgressListener } from "./runner.js";

package/dist/units/index.js

@@ -1,2 +1,4 @@
 export { Unit } from "./contracts-bridge.js";
+export { FileTreeUnit } from "./file-tree-unit.js";
+export { SnapshotUnit } from "./snapshot-unit.js";
 export { runCapture } from "./runner.js";

package/dist/units/internal/async-queue.js

@@ -35,11 +35,11 @@ export class AsyncQueue {
     async *iterate() {
         while (true) {
             if (this.values.length > 0) {
-                const v = this.values.shift();
-                if (v === undefined) {
+                const value = this.values.shift();
+                if (value === undefined) {
                     continue;
                 }
-                yield v;
+                yield value;
                 continue;
             }
             if (this.done) {

package/dist/units/internal/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelToken, ReplaceElementsConfig } from "@pagepocket/contracts";
+import { type ChannelToken, type ReplaceElementsConfig } from "@pagepocket/contracts";
 import { type ElementPatchRegistry, type UnitContext, type UnitPatch, type UnitRuntime } from "../contracts-bridge.js";
 import type { CaptureOptions, EntryInfo, PagePocketOptions } from "../types.js";
 declare class ElementPatchRegistryImpl implements ElementPatchRegistry {
@@ -19,17 +19,20 @@ export declare class RuntimeImpl implements UnitRuntime {
     readonly pocketOptions: PagePocketOptions;
     private channels;
     private deferred;
+    private currentUnitId;
     readonly elements: ElementPatchRegistryImpl;
     constructor(input: {
         entry: EntryInfo;
         options: CaptureOptions;
         pocketOptions: PagePocketOptions;
     });
-    publish<T>(t: ChannelToken<T>, value: T): void;
-    subscribe<T>(t: ChannelToken<T>): AsyncIterable<T>;
-    hasPublisher(t: ChannelToken<unknown>): boolean;
+    _setCurrentUnitId(unitId: string): void;
+    log(message: string, data?: unknown): void;
+    publish<T>(channelToken: ChannelToken<T>, value: T): void;
+    subscribe<T>(channelToken: ChannelToken<T>): AsyncIterable<T>;
+    hasPublisher(channelToken: ChannelToken<unknown>): boolean;
     defer(promise: Promise<unknown>): void;
-    _ensureChannel(t: ChannelToken<unknown>): void;
+    _ensureChannel<T>(channelToken: ChannelToken<T>): void;
     _closeAllChannels(): Promise<void>;
     _awaitDeferred(): Promise<void>;
 }

package/dist/units/internal/runtime.js

@@ -1,3 +1,4 @@
+import { PROGRESS } from "@pagepocket/contracts";
 import { TERMINAL_RESULT_KEY } from "../contracts-bridge.js";
 import { AsyncQueue, emptyAsyncIterable } from "./async-queue.js";
 import { DeferredTracker } from "./deferred-tracker.js";
@@ -30,13 +31,26 @@ export class RuntimeImpl {
     constructor(input) {
         this.channels = new Map();
         this.deferred = new DeferredTracker();
+        this.currentUnitId = "";
         this.elements = new ElementPatchRegistryImpl();
         this.entry = input.entry;
         this.options = input.options;
         this.pocketOptions = input.pocketOptions;
     }
-    publish(t, value) {
-        const state = this.channels.get(t.id);
+    _setCurrentUnitId(unitId) {
+        this.currentUnitId = unitId;
+    }
+    log(message, data) {
+        const event = {
+            type: "unit:log",
+            unitId: this.currentUnitId,
+            message,
+            ...(data !== undefined ? { data } : {})
+        };
+        this.publish(PROGRESS, event);
+    }
+    publish(channelToken, value) {
+        const state = this.channels.get(channelToken.id);
         if (!state || state.closed) {
             return;
         }
@@ -45,45 +59,45 @@ export class RuntimeImpl {
             sub.push(value);
         }
     }
-    subscribe(t) {
-        if (!this.channels.has(t.id)) {
-            this.channels.set(t.id, { hasPublisher: false, subs: new Set(), closed: false });
+    subscribe(channelToken) {
+        if (!this.channels.has(channelToken.id)) {
+            this.channels.set(channelToken.id, { hasPublisher: false, subs: new Set(), closed: false });
         }
-        const state = this.channels.get(t.id);
+        const state = this.channels.get(channelToken.id);
         if (!state || state.closed) {
             return emptyAsyncIterable();
         }
-        const q = new AsyncQueue();
+        const queue = new AsyncQueue();
         const sub = {
-            push: (v) => q.push(v),
-            close: () => q.close()
+            push: (value) => queue.push(value),
+            close: () => queue.close()
         };
         state.subs.add(sub);
         const owner = this;
         return (async function* () {
             try {
-                for await (const v of q.iterate()) {
-                    yield v;
+                for await (const value of queue.iterate()) {
+                    yield value;
                 }
             }
             finally {
-                const s = owner.channels.get(t.id);
-                s?.subs.delete(sub);
-                q.close();
+                const channelState = owner.channels.get(channelToken.id);
+                channelState?.subs.delete(sub);
+                queue.close();
             }
         })();
     }
-    hasPublisher(t) {
-        return this.channels.get(t.id)?.hasPublisher === true;
+    hasPublisher(channelToken) {
+        return this.channels.get(channelToken.id)?.hasPublisher === true;
     }
     defer(promise) {
         this.deferred.add(promise);
     }
-    _ensureChannel(t) {
-        if (this.channels.has(t.id)) {
+    _ensureChannel(channelToken) {
+        if (this.channels.has(channelToken.id)) {
             return;
         }
-        this.channels.set(t.id, { hasPublisher: false, subs: new Set(), closed: false });
+        this.channels.set(channelToken.id, { hasPublisher: false, subs: new Set(), closed: false });
     }
     async _closeAllChannels() {
         for (const state of this.channels.values()) {
@@ -103,11 +117,11 @@ export class RuntimeImpl {
 }
 export const mergePatchIntoFreshContext = (patch) => {
     const next = { value: {} };
-    for (const [k, v] of Object.entries(patch)) {
-        if (k === TERMINAL_RESULT_KEY) {
+    for (const [key, value] of Object.entries(patch)) {
+        if (key === TERMINAL_RESULT_KEY) {
             continue;
         }
-        next.value[k] = v;
+        next.value[key] = value;
     }
     return next;
 };

package/dist/units/runner.d.ts

@@ -1,6 +1,7 @@
-import type { ChannelToken } from "@pagepocket/contracts";
+import { type ChannelToken, type ProgressEvent } from "@pagepocket/contracts";
 import { type CaptureResult, type Plugin, type Unit } from "./contracts-bridge.js";
 import type { CaptureOptions, EntryInfo, PagePocketOptions } from "./types.js";
+export type ProgressListener = (event: ProgressEvent) => void;
 export declare const runCapture: (input: {
     entry: EntryInfo;
     pocketOptions: PagePocketOptions;
@@ -8,4 +9,5 @@ export declare const runCapture: (input: {
     units: Unit[];
     plugins?: Plugin[];
     declaredChannels?: ChannelToken<unknown>[];
+    onProgress?: ProgressListener;
 }) => Promise<CaptureResult>;

package/dist/units/runner.js

@@ -1,3 +1,5 @@
+import { PROGRESS } from "@pagepocket/contracts";
+import { debugLog } from "../core/debug.js";
 import { TERMINAL_RESULT_KEY } from "./contracts-bridge.js";
 import { mergePatchIntoFreshContext, RuntimeImpl } from "./internal/runtime.js";
 export const runCapture = async (input) => {
@@ -6,34 +8,54 @@ export const runCapture = async (input) => {
         options: input.options,
         pocketOptions: input.pocketOptions
     });
-    for (const ch of input.declaredChannels ?? []) {
-        rt._ensureChannel(ch);
+    for (const channel of input.declaredChannels ?? []) {
+        rt._ensureChannel(channel);
+    }
+    rt._ensureChannel(PROGRESS);
+    if (input.onProgress) {
+        const listener = input.onProgress;
+        const progressTask = (async () => {
+            for await (const event of rt.subscribe(PROGRESS)) {
+                listener(event);
+            }
+        })();
+        rt.defer(progressTask);
     }
     const pluginHost = {
         entry: rt.entry,
         options: rt.options,
-        subscribe: (t) => rt.subscribe(t),
-        hasPublisher: (t) => rt.hasPublisher(t),
+        subscribe: (channelToken) => rt.subscribe(channelToken),
+        hasPublisher: (channelToken) => rt.hasPublisher(channelToken),
         elements: rt.elements,
-        defer: (p) => rt.defer(p)
+        defer: (deferredPromise) => rt.defer(deferredPromise)
     };
     const pluginSetupValues = new Map();
     for (const plugin of input.plugins ?? []) {
-        const v = await plugin.setup(pluginHost);
-        if (typeof v !== "undefined") {
-            pluginSetupValues.set(plugin, v);
+        const setupValue = await plugin.setup(pluginHost);
+        if (typeof setupValue !== "undefined") {
+            pluginSetupValues.set(plugin, setupValue);
         }
     }
-    const mergePatch = (_ctx, patch) => {
-        return mergePatchIntoFreshContext(patch);
-    };
+    const mergePatch = (_ctx, patch) => mergePatchIntoFreshContext(patch);
     let ctx = { value: {} };
     let result;
+    const totalUnits = input.units.length;
     try {
-        for (const unit of input.units) {
+        for (let i = 0; i < input.units.length; i++) {
             if (result) {
                 break;
             }
+            const unit = input.units[i];
+            const unitIndex = i;
+            rt._setCurrentUnitId(unit.id);
+            rt.publish(PROGRESS, {
+                type: "unit:start",
+                unitId: unit.id,
+                unitDescription: unit.description,
+                index: unitIndex,
+                total: totalUnits
+            });
+            const unitStartTime = Date.now();
             const baseCtx = ctx;
             const boundPlugins = (input.plugins ?? []).filter((plugin) => {
                 const unitId = plugin.constructor?.unitId;
@@ -42,13 +64,13 @@ export const runCapture = async (input) => {
             let pluginContributedValue = {};
             if (boundPlugins.length > 0) {
                 const pluginResults = await Promise.allSettled(boundPlugins
-                    .filter((p) => typeof p.contribute === "function")
-                    .map(async (p) => p.contribute({ value: ctx.value, setupValue: pluginSetupValues.get(p) }, rt)));
-                for (const r of pluginResults) {
-                    if (r.status !== "fulfilled") {
+                    .filter((pluginBinding) => typeof pluginBinding.contribute === "function")
+                    .map(async (pluginBinding) => pluginBinding.contribute({ value: ctx.value, setupValue: pluginSetupValues.get(pluginBinding) }, rt)));
+                for (const pluginResult of pluginResults) {
+                    if (pluginResult.status !== "fulfilled") {
                         continue;
                     }
-                    const patch = r.value;
+                    const patch = pluginResult.value;
                     if (!patch || typeof patch !== "object") {
                         continue;
                     }
@@ -64,13 +86,44 @@ export const runCapture = async (input) => {
                 }
             }
             if (result) {
+                rt.publish(PROGRESS, {
+                    type: "unit:end",
+                    unitId: unit.id,
+                    unitDescription: unit.description,
+                    index: unitIndex,
+                    total: totalUnits,
+                    durationMs: Date.now() - unitStartTime
+                });
                 break;
             }
-            const out = (await unit.run(baseCtx, rt)) ?? {};
+            let out;
+            try {
+                out = (await unit.run(baseCtx, rt)) ?? {};
+            }
+            catch (err) {
+                debugLog(`[runner] unit "${unit.id}" threw:`, err);
+                rt.publish(PROGRESS, {
+                    type: "unit:end",
+                    unitId: unit.id,
+                    unitDescription: unit.description,
+                    index: unitIndex,
+                    total: totalUnits,
+                    durationMs: Date.now() - unitStartTime
+                });
+                continue;
+            }
             const unitReturnValue = out && typeof out === "object" ? out : {};
             const merged = unit.merge(unitReturnValue, pluginContributedValue);
             const mergedPatch = merged && typeof merged === "object" ? merged : {};
             ctx = { value: mergePatch({ value: {} }, mergedPatch).value };
+            rt.publish(PROGRESS, {
+                type: "unit:end",
+                unitId: unit.id,
+                unitDescription: unit.description,
+                index: unitIndex,
+                total: totalUnits,
+                durationMs: Date.now() - unitStartTime
+            });
             const terminal = mergedPatch[TERMINAL_RESULT_KEY];
             if (terminal) {
                 result = terminal;

package/dist/units/snapshot-unit.d.ts

@@ -0,0 +1,31 @@
+import type { UnitContext, UnitPatch, UnitRuntime } from "./contracts-bridge.js";
+import { FileTreeUnit } from "./file-tree-unit.js";
+/**
+ * Base class for units that produce the primary snapshot FileTree.
+ *
+ * `run()` delegates to `build()` and automatically:
+ * - Injects `snapshotType` into the returned patch.
+ * - Compiles all plugin-contributed element-replacement rules
+ *   (`rt.elements.compile()`) and applies them to every HTML file
+ *   in the returned FileTree.  Subclasses never need to call
+ *   `rt.elements.compile()` themselves.
+ *
+ * Subclasses implement `id`, `snapshotType`, and `build()`.
+ *
+ * ```ts
+ * export class MySnapshotUnit extends SnapshotUnit {
+ *   readonly id = "mySnapshot";
+ *   readonly snapshotType = "my-type";
+ *
+ *   async build(ctx, rt) {
+ *     return { files: buildFiles(), html: ctx.value.html };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class SnapshotUnit extends FileTreeUnit {
+    /** Identifier for the kind of snapshot this unit produces (e.g. "full", "main-content"). */
+    abstract readonly snapshotType: string;
+    abstract build(ctx: UnitContext, rt: UnitRuntime): Promise<void | UnitPatch>;
+    run(ctx: UnitContext, rt: UnitRuntime): Promise<void | UnitPatch>;
+}

package/dist/units/snapshot-unit.js

@@ -0,0 +1,58 @@
+import { applyReplaceElementsToFileTree } from "./apply-replace-elements-to-file-tree.js";
+import { FileTreeUnit } from "./file-tree-unit.js";
+/**
+ * Base class for units that produce the primary snapshot FileTree.
+ *
+ * `run()` delegates to `build()` and automatically:
+ * - Injects `snapshotType` into the returned patch.
+ * - Compiles all plugin-contributed element-replacement rules
+ *   (`rt.elements.compile()`) and applies them to every HTML file
+ *   in the returned FileTree.  Subclasses never need to call
+ *   `rt.elements.compile()` themselves.
+ *
+ * Subclasses implement `id`, `snapshotType`, and `build()`.
+ *
+ * ```ts
+ * export class MySnapshotUnit extends SnapshotUnit {
+ *   readonly id = "mySnapshot";
+ *   readonly snapshotType = "my-type";
+ *
+ *   async build(ctx, rt) {
+ *     return { files: buildFiles(), html: ctx.value.html };
+ *   }
+ * }
+ * ```
+ */
+export class SnapshotUnit extends FileTreeUnit {
+    async run(ctx, rt) {
+        const patch = await this.build(ctx, rt);
+        if (!patch) {
+            return;
+        }
+        const files = patch.files;
+        const replaceElements = await rt.elements.compile();
+        if (files && replaceElements.length > 0) {
+            const entryUrl = resolveEntryUrl(rt);
+            const updatedFiles = await applyReplaceElementsToFileTree({
+                files,
+                replaceElements,
+                entryUrl
+            });
+            return { ...patch, files: updatedFiles, snapshotType: this.snapshotType };
+        }
+        return { ...patch, snapshotType: this.snapshotType };
+    }
+}
+const resolveEntryUrl = (rt) => {
+    const entry = rt.entry;
+    if (entry.kind === "url") {
+        return entry.url;
+    }
+    if (entry.kind === "html-string" || entry.kind === "document") {
+        return entry.url ?? entry.baseUrl;
+    }
+    if (entry.kind === "puppeteer-page" || entry.kind === "cdp-tab") {
+        return entry.url ?? "";
+    }
+    return "";
+};

package/dist/units/types.d.ts

@@ -1,4 +1,4 @@
-import type { CompletionStrategy, ContentStore, PathResolver, ResourceFilter } from "../types.js";
+import type { CompletionStrategy, ContentStore, PagePocketOptions, PathResolver, ResourceFilter } from "../types.js";
 export type EntryInfo = {
     kind: "url";
     url: string;
@@ -36,4 +36,4 @@ export interface CaptureOptions {
         maxResources?: number;
     };
 }
-export type PagePocketOptions = import("../types.js").PagePocketOptions;
+export type { PagePocketOptions };

package/dist/utils.js

@@ -4,8 +4,8 @@ const FNV_PRIME = 0x01000193;
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const hashString = (value) => {
     let hash = FNV_OFFSET;
-    for (let i = 0; i < value.length; i += 1) {
-        hash ^= value.charCodeAt(i);
+    for (let characterIndex = 0; characterIndex < value.length; characterIndex += 1) {
+        hash ^= value.charCodeAt(characterIndex);
         hash = (hash * FNV_PRIME) >>> 0;
     }
     return hash.toString(16).padStart(8, "0");
@@ -24,9 +24,7 @@ export const sanitizePosixPath = (value) => {
     }
     return clean.join("/");
 };
-const getGlobalBuffer = () => {
-    return globalThis.Buffer;
-};
+const getGlobalBuffer = () => globalThis.Buffer;
 export const bytesToBase64 = (bytes) => {
     const BufferCtor = getGlobalBuffer();
     if (BufferCtor) {
@@ -34,8 +32,8 @@ export const bytesToBase64 = (bytes) => {
     }
     let binary = "";
     const chunkSize = 0x8000;
-    for (let i = 0; i < bytes.length; i += chunkSize) {
-        const chunk = bytes.subarray(i, i + chunkSize);
+    for (let chunkStart = 0; chunkStart < bytes.length; chunkStart += chunkSize) {
+        const chunk = bytes.subarray(chunkStart, chunkStart + chunkSize);
         binary += String.fromCharCode(...chunk);
     }
     return btoa(binary);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagepocket/lib",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Library for rewriting HTML snapshots and inlining local resources.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,9 +20,9 @@
   "dependencies": {
     "cheerio": "^1.0.0-rc.12",
     "domhandler": "^5.0.3",
-    "@pagepocket/contracts": "0.11.1",
-    "@pagepocket/uni-fs": "0.11.1",
-    "@pagepocket/shared": "0.11.1"
+    "@pagepocket/contracts": "0.13.0",
+    "@pagepocket/shared": "0.13.0",
+    "@pagepocket/uni-fs": "0.13.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.50.1",