@pagepocket/lib 0.12.0 → 0.14.5

package/dist/replay/templates/match-api-source.js

@@ -107,12 +107,25 @@ export const matchAPISource = `function matchAPI(options) {
         const recordPathSearch = stripTrailingSlash(toPathSearch(recordUrl));
         if (inputPathSearch === recordPathSearch)
             return true;
-        const inputPath = stripTrailingSlash(toPathname(inputUrl));
-        const recordPath = stripTrailingSlash(toPathname(recordUrl));
-        if (inputPath === recordPath)
-            return true;
         return false;
     };
+    const normalizePathLoose = (input) => {
+        const parsed = safeUrl(input);
+        if (parsed) {
+            return stripTrailingSlash(parsed.pathname);
+        }
+        const rawValue = String(input ?? "");
+        if (!rawValue) {
+            return "";
+        }
+        const valueWithoutHash = rawValue.split("#")[0] ?? "";
+        const valueWithoutQuery = valueWithoutHash.split("?")[0] ?? "";
+        const withoutOrigin = valueWithoutQuery.replace(/^([a-zA-Z][a-zA-Z\\d+\\-.]*:)?\\/\\/[^/]+/, "");
+        if (!withoutOrigin) {
+            return "/";
+        }
+        return stripTrailingSlash(withoutOrigin.startsWith("/") ? withoutOrigin : "/" + withoutOrigin);
+    };
     const scanRecords = (keyMethod, keyBody) => {
         for (const record of records || []) {
             if (!record || !record.url || !record.method)
@@ -128,10 +141,79 @@ export const matchAPISource = `function matchAPI(options) {
         }
         return undefined;
     };
+    const scanRecordsIgnoreQueryAndProtocol = (keyMethod, keyBody) => {
+        const inputPathname = normalizePathLoose(url);
+        if (!inputPathname) {
+            return undefined;
+        }
+        const candidates = [];
+        for (const record of records || []) {
+            if (!record || !record.url || !record.method)
+                continue;
+            if (record.method.toUpperCase() !== keyMethod)
+                continue;
+            const recordPathname = normalizePathLoose(record.url);
+            if (!recordPathname || recordPathname !== inputPathname)
+                continue;
+            const recordBody = record.requestBody || record.requestBodyBase64 || "";
+            if (keyBody && recordBody !== keyBody)
+                continue;
+            candidates.push(record);
+        }
+        if (candidates.length === 0)
+            return undefined;
+        if (candidates.length === 1) {
+            const candidate = candidates[0];
+            const inputParsed = safeUrl(url);
+            const candidateParsed = safeUrl(candidate.url);
+            if (inputParsed && candidateParsed) {
+                const inputKeys = Array.from(inputParsed.searchParams.keys());
+                const candidateKeys = new Set(candidateParsed.searchParams.keys());
+                const inputAllContained = inputKeys.length > 0 && inputKeys.every(k => candidateKeys.has(k));
+                const candidateHasExtra = candidateKeys.size > inputKeys.length;
+                if (inputAllContained && candidateHasExtra)
+                    return undefined;
+            }
+            return candidate;
+        }
+        const inputParsed = safeUrl(url);
+        const inputSearch = inputParsed ? inputParsed.search : "";
+        let bestRecord = undefined;
+        let bestScore = -Infinity;
+        for (const candidate of candidates) {
+            const candidateParsed = safeUrl(candidate.url);
+            const candidateSearch = candidateParsed ? candidateParsed.search : "";
+            if (candidateSearch === inputSearch)
+                return candidate;
+            const inputParams = inputParsed ? inputParsed.searchParams : new URLSearchParams();
+            const candidateParams = candidateParsed ? candidateParsed.searchParams : new URLSearchParams();
+            let shared = 0;
+            let recordOnly = 0;
+            for (const [key, value] of candidateParams.entries()) {
+                if (inputParams.get(key) === value) {
+                    shared++;
+                }
+                else {
+                    recordOnly++;
+                }
+            }
+            const score = shared - recordOnly * 2;
+            if (score > bestScore) {
+                bestScore = score;
+                bestRecord = candidate;
+            }
+        }
+        return bestRecord;
+    };
     for (const [keyMethod, keyBody] of matchOrder) {
         const record = scanRecords(keyMethod, keyBody);
         if (record)
             return record;
     }
+    for (const [keyMethod, keyBody] of matchOrder) {
+        const record = scanRecordsIgnoreQueryAndProtocol(keyMethod, keyBody);
+        if (record)
+            return record;
+    }
     return undefined;
 }`;

package/dist/replay/templates/replay-script-template.part-2.js

@@ -37,6 +37,25 @@ export const buildReplayInjectedScriptPart2 = (options) => {
     return snapshot;
   })();
 
+
+  // Synchronous fast-path: when the loader page has already set
+  // window.__pagepocketResourcesPath / window.__pagepocketApiSnapshot,
+  // build resourceIndex immediately so document.write URL rewriting
+  // works before the async ready promise resolves.
+  try {
+    var preloadedResources = window.__pagepocketResourcesPath;
+    if (preloadedResources && preloadedResources.version === "1.0" && Array.isArray(preloadedResources.items)) {
+      resourceIndex = __pagepocketResourceProxy.buildIndex(preloadedResources);
+    }
+  } catch (syncInitError) {}
+
+  try {
+    var preloadedApi = window.__pagepocketApiSnapshot;
+    if (preloadedApi && preloadedApi.version === "1.0" && Array.isArray(preloadedApi.records)) {
+      primeLookups(preloadedApi);
+    }
+  } catch (syncInitError) {}
+
   const isLocalResource = (value) => {
     if (!value) return false;
     if (value.startsWith("data:") || value.startsWith("blob:")) return true;
@@ -202,7 +221,11 @@ export const buildReplayInjectedScriptPart2 = (options) => {
   };
 
   const responseFromRecord = (record) => {
-    const headers = new Headers(record.responseHeaders || {});
+    var headers = new Headers();
+    var rawHeaders = record.responseHeaders || {};
+    for (var key in rawHeaders) {
+      try { headers.append(key, rawHeaders[key]); } catch (e) {}
+    }
     if (record.responseEncoding === "base64" && record.responseBodyBase64) {
       const bytes = decodeBase64(record.responseBodyBase64);
       return new Response(bytes, {

package/dist/resource-filter.js

@@ -4,17 +4,43 @@ const isSkippableUrl = (url) => url.startsWith("data:") ||
     url.startsWith("mailto:") ||
     url.startsWith("tel:") ||
     url.startsWith("javascript:");
+/**
+ * Checks whether a response mimeType represents a saveable binary asset.
+ *
+ * Some SPAs (e.g. Feishu, Notion) load images and fonts via `fetch()` or
+ * `XMLHttpRequest` instead of `<img>` tags.  Puppeteer marks those requests
+ * as `resourceType: "fetch"` / `"xhr"`, but the response is still an image
+ * or font that must be persisted for offline replay.
+ *
+ * We detect this by inspecting the response `mimeType`.
+ */
+const isSaveableMimeType = (mimeType) => {
+    const lower = mimeType.toLowerCase().split(";")[0].trim();
+    if (lower.startsWith("image/")) {
+        return true;
+    }
+    if (lower.startsWith("font/")) {
+        return true;
+    }
+    if (lower.startsWith("audio/") || lower.startsWith("video/")) {
+        return true;
+    }
+    if (lower === "application/font-woff" || lower === "application/font-woff2" || lower === "application/octet-stream") {
+        return true;
+    }
+    return false;
+};
 export const createDefaultResourceFilter = () => ({
     shouldSave(req, res) {
         if (isSkippableUrl(req.url)) {
             return false;
         }
-        if (req.resourceType && (req.resourceType === "fetch" || req.resourceType === "xhr")) {
-            return false;
-        }
         if (res && res.status >= 400) {
             return false;
         }
+        if (req.resourceType && (req.resourceType === "fetch" || req.resourceType === "xhr")) {
+            return res?.mimeType ? isSaveableMimeType(res.mimeType) : false;
+        }
         if (req.resourceType) {
             return DEFAULT_ALLOWED.has(req.resourceType);
         }

package/dist/snapshot-builder/build-snapshot.js

@@ -8,6 +8,7 @@ import { responseMimeType } from "./http.js";
 import { docDirFromUrl, resolveSnapshotPath } from "./path-map.js";
 import { buildResourcesPathSnapshot } from "./resources-path.js";
 import { maybeRewriteScript, maybeRewriteStylesheet } from "./rewrite-resource.js";
+import { buildLoaderHtml } from "../replay/templates/loader-template.js";
 export const buildSnapshot = async (input) => {
     const warnings = input.warnings;
     const contentStore = input.capture.contentStore;
@@ -46,10 +47,11 @@ export const buildSnapshot = async (input) => {
         const apiPath = ensureLeadingSlash(multiDoc ? `${sanitizePosixPath(docDir)}/api.json` : "/api.json");
         for (const resource of group.resources) {
             if (resource.request.resourceType === "document") {
-                const path = urlToPath.get(resource.request.url) ?? "/index.html";
+                const originalPath = urlToPath.get(resource.request.url) ?? "/index.html";
+                const pagePath = toPagePath(originalPath);
                 const { file } = await emitDocumentFile({
                     resource,
-                    path,
+                    path: pagePath,
                     entryUrl: input.entryUrl,
                     groupUrl: group.url,
                     apiPath,
@@ -60,8 +62,23 @@ export const buildSnapshot = async (input) => {
                     snapshotEntryUrl: input.entryUrl
                 });
                 files.push(file);
+                const loaderHtml = buildLoaderHtml({
+                    pageUrl: pagePath,
+                    apiPath,
+                    resourcesPathUrl: "/resources_path.json"
+                });
+                const loaderBytes = new TextEncoder().encode(loaderHtml);
+                const loaderRef = await contentStore.put({ kind: "buffer", data: loaderBytes }, { url: originalPath, mimeType: "text/html", sizeHint: loaderBytes.byteLength });
+                files.push({
+                    path: originalPath,
+                    mimeType: "text/html",
+                    size: loaderBytes.byteLength,
+                    source: loaderRef,
+                    originalUrl: resource.request.url,
+                    resourceType: "document"
+                });
                 if (resource.request.url === input.entryUrl || !entryPath) {
-                    entryPath = path;
+                    entryPath = originalPath;
                 }
                 continue;
             }
@@ -135,3 +152,16 @@ export const buildSnapshot = async (input) => {
     };
 };
 const resourceMimeType = (resource) => resource.mimeType || responseMimeType(resource.response) || undefined;
+/**
+ * Derive the "page" path from the original document path.
+ * `/index.html` → `/_page.html`, `/foo/bar.html` → `/foo/_bar.html`.
+ */
+const toPagePath = (originalPath) => {
+    const lastSlash = originalPath.lastIndexOf("/");
+    if (lastSlash === -1) {
+        return `_${originalPath}`;
+    }
+    const dir = originalPath.slice(0, lastSlash + 1);
+    const filename = originalPath.slice(lastSlash + 1);
+    return `${dir}_${filename}`;
+};

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

@@ -55,6 +55,14 @@ export interface UnitRuntime {
     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: EntryInfo;
@@ -66,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/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;
     });
+    _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(channelToken: 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,11 +31,24 @@ 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;
     }
+    _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) {

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) => {
@@ -9,6 +11,16 @@ export const runCapture = async (input) => {
     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,
@@ -27,11 +39,24 @@ export const runCapture = async (input) => {
     const mergePatch = (_ctx, patch) => mergePatchIntoFreshContext(patch);
     let ctx = { value: {} };
     let result;
+    const unitErrors = [];
+    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;
@@ -62,13 +87,45 @@ 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);
+                unitErrors.push({ unitId: unit.id, error: 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;
@@ -81,6 +138,19 @@ export const runCapture = async (input) => {
         await rt._awaitDeferred();
     }
     if (!result) {
+        if (unitErrors.length > 0) {
+            const first = unitErrors[0];
+            const rootCause = first.error instanceof Error ? first.error : new Error(String(first.error));
+            if (unitErrors.length > 1) {
+                const summary = unitErrors
+                    .map((e) => `${e.unitId}: ${e.error instanceof Error ? e.error.message : String(e.error)}`)
+                    .join("; ");
+                const wrapped = new Error(`Pipeline failed: ${unitErrors.length} unit(s) threw errors. ${summary}`);
+                wrapped.cause = rootCause;
+                throw wrapped;
+            }
+            throw rootCause;
+        }
         throw new Error("No terminal result. Ensure a terminal unit returns a CaptureResult or calls finish().");
     }
     return result;

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>;
+}