@pagepocket/single-file-unit 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SingleFileUnit } from "./single-file-unit.js";
+export type { SingleFileUnitOptions } from "./single-file-unit.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { SingleFileUnit } from "./single-file-unit.js";

package/dist/single-file/build-single-file-files.d.ts

@@ -0,0 +1,14 @@
+import type { FileTree } from "@pagepocket/lib";
+export type SingleFileUnitOptions = {
+    maxInlineBytes?: number;
+    oversize?: {
+        script?: "error" | "placeholder";
+        stylesheet?: "error" | "placeholder";
+        image?: "error" | "placeholder";
+        media?: "error" | "placeholder";
+    };
+};
+export declare const buildSingleFileFiles: (input: {
+    files: FileTree;
+    options?: SingleFileUnitOptions;
+}) => Promise<FileTree>;

package/dist/single-file/build-single-file-files.js

@@ -0,0 +1,57 @@
+import { defaultOversizeBehavior } from "../utils/oversize.js";
+import { collectSnapshotBytesByPath } from "./collect-bytes.js";
+import { embedResourcesPathData } from "./embed-resources.js";
+import { createInlinePathUrl } from "./inline-path-url.js";
+import { createOversizeBehavior } from "./oversize-behavior.js";
+import { readIndexHtml, readOptionalApiSnapshot, readResourcesPathSnapshot } from "./read-snapshot.js";
+import { rewriteIndexHtmlToSingleFile } from "./rewrite-index-html.js";
+const DEFAULT_MAX_INLINE_BYTES = 25 * 1024 * 1024;
+export const buildSingleFileFiles = async (input) => {
+    const maxInlineBytes = input.options?.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+    const oversize = {
+        script: input.options?.oversize?.script ?? defaultOversizeBehavior.script,
+        stylesheet: input.options?.oversize?.stylesheet ?? defaultOversizeBehavior.stylesheet,
+        image: input.options?.oversize?.image ?? defaultOversizeBehavior.image,
+        media: input.options?.oversize?.media ?? defaultOversizeBehavior.media
+    };
+    const bytesByPath = await collectSnapshotBytesByPath(input.files);
+    const indexHtml = readIndexHtml(bytesByPath);
+    const apiSnapshot = readOptionalApiSnapshot(bytesByPath);
+    const resourcesPath = readResourcesPathSnapshot(bytesByPath);
+    const oversizeBehavior = createOversizeBehavior(oversize);
+    const inlinePathUrl = createInlinePathUrl({
+        bytesByPath,
+        maxInlineBytes,
+        oversizeBehavior
+    });
+    await embedResourcesPathData({
+        resourcesPath,
+        bytesByPath,
+        maxInlineBytes,
+        oversizeBehavior,
+        inlinePathUrl
+    });
+    const finalHtml = await rewriteIndexHtmlToSingleFile({
+        indexHtml,
+        bytesByPath,
+        resourcesPath,
+        apiSnapshot,
+        maxInlineBytes,
+        oversizeBehavior,
+        inlinePathUrl
+    });
+    return {
+        root: {
+            kind: "directory",
+            path: "",
+            entries: [
+                {
+                    kind: "file",
+                    path: "/index.html",
+                    source: { kind: "text", text: finalHtml }
+                }
+            ]
+        },
+        content: input.files.content
+    };
+};

package/dist/single-file/collect-bytes.d.ts

@@ -0,0 +1,2 @@
+import type { FileTree } from "@pagepocket/lib";
+export declare const collectSnapshotBytesByPath: (files: FileTree) => Promise<Map<string, Uint8Array<ArrayBufferLike>>>;

package/dist/single-file/collect-bytes.js

@@ -0,0 +1,27 @@
+import { flattenEntries } from "../utils/file-tree.js";
+import { streamToUint8Array } from "../utils/stream-to-uint8array.js";
+const readSourceBytes = async (files, source) => {
+    if (source.kind === "bytes") {
+        return source.data;
+    }
+    if (source.kind === "text") {
+        return new TextEncoder().encode(source.text);
+    }
+    const ref = source.ref;
+    if (!files.content) {
+        throw new Error("SingleFilePlugin requires ctx.value.files.content to resolve content-ref");
+    }
+    const stream = await files.content.open(ref);
+    return await streamToUint8Array(stream);
+};
+export const collectSnapshotBytesByPath = async (files) => {
+    if (!files.root || files.root.kind !== "directory") {
+        throw new Error("SingleFilePlugin requires ctx.value.files.root directory");
+    }
+    const flattened = flattenEntries(files.root, "");
+    const bytesByPath = new Map();
+    for (const item of flattened) {
+        bytesByPath.set(item.path, await readSourceBytes(files, item.file.source));
+    }
+    return bytesByPath;
+};

package/dist/single-file/embed-resources.d.ts

@@ -0,0 +1,11 @@
+import type { ResourcesPathSnapshot } from "./read-snapshot.js";
+export declare const embedResourcesPathData: (options: {
+    resourcesPath: ResourcesPathSnapshot;
+    bytesByPath: Map<string, Uint8Array>;
+    maxInlineBytes: number;
+    oversizeBehavior: (mimeType?: string) => "error" | "placeholder";
+    inlinePathUrl: (raw: string, context: {
+        kind: "attr" | "css";
+        selector: string;
+    }) => string | null;
+}) => Promise<void>;

package/dist/single-file/embed-resources.js

@@ -0,0 +1,54 @@
+import { rewriteCssText } from "@pagepocket/lib";
+import { bytesToBase64 } from "@pagepocket/shared";
+import { decodeUtf8OrNull } from "../utils/decode-utf8-or-null.js";
+import { shouldSkipCssValue } from "../utils/should-skip-css-value.js";
+export const embedResourcesPathData = async (options) => {
+    const { resourcesPath, bytesByPath, maxInlineBytes, oversizeBehavior, inlinePathUrl } = options;
+    for (const item of resourcesPath.items) {
+        const path = item && item.path;
+        if (!path) {
+            continue;
+        }
+        const bytes = bytesByPath.get(path);
+        if (!bytes) {
+            continue;
+        }
+        // If the embedded resource is CSS, inline its url()/@import dependencies so file://
+        // replay doesn't attempt to load /... from disk.
+        if (item.mimeType === "text/css") {
+            const cssText = decodeUtf8OrNull(bytes);
+            if (cssText !== null) {
+                const rewritten = await rewriteCssText({
+                    cssText,
+                    cssUrl: item.path,
+                    resolveUrl: async (absolute) => {
+                        if (shouldSkipCssValue(absolute)) {
+                            return null;
+                        }
+                        if (!absolute.startsWith("/")) {
+                            return null;
+                        }
+                        return inlinePathUrl(absolute, {
+                            kind: "css",
+                            selector: `resources_path.json:${item.path}`
+                        });
+                    }
+                });
+                const outBytes = new TextEncoder().encode(rewritten);
+                item.dataEncoding = "base64";
+                item.data = bytesToBase64(outBytes);
+                continue;
+            }
+        }
+        if (bytes.byteLength > maxInlineBytes) {
+            const behavior = oversizeBehavior(item.mimeType);
+            if (behavior === "error") {
+                throw new Error(`SingleFilePlugin oversize resource (>${maxInlineBytes} bytes): ${path} (${item.mimeType || "unknown"})`);
+            }
+            // Skip embedding. HTML rewrite will handle placeholders for /... refs.
+            continue;
+        }
+        item.dataEncoding = "base64";
+        item.data = bytesToBase64(bytes);
+    }
+};

package/dist/single-file/inline-path-url.d.ts

@@ -0,0 +1,9 @@
+export type InlinePathUrlContext = {
+    kind: "attr" | "css";
+    selector: string;
+};
+export declare const createInlinePathUrl: (options: {
+    bytesByPath: Map<string, Uint8Array>;
+    maxInlineBytes: number;
+    oversizeBehavior: (mimeType?: string) => "error" | "placeholder";
+}) => (raw: string, context: InlinePathUrlContext) => string | null;

package/dist/single-file/inline-path-url.js

@@ -0,0 +1,31 @@
+import { lookupMimeTypeFromPath } from "@pagepocket/shared";
+import { placeholderSvgDataUrl } from "../utils/placeholder-svg.js";
+import { toDataUrlBase64 } from "../utils/to-data-url.js";
+export const createInlinePathUrl = (options) => {
+    const { bytesByPath, maxInlineBytes, oversizeBehavior } = options;
+    return (raw, context) => {
+        const value = String(raw || "").trim();
+        if (!value.startsWith("/")) {
+            return null;
+        }
+        const bytes = bytesByPath.get(value);
+        if (!bytes) {
+            return null;
+        }
+        const inferredMime = lookupMimeTypeFromPath(value);
+        if (bytes.byteLength > maxInlineBytes) {
+            const behavior = oversizeBehavior(inferredMime);
+            if (behavior === "error") {
+                throw new Error(`SingleFilePlugin oversize ${inferredMime} (> ${maxInlineBytes} bytes) referenced at ${value} from ${context.selector}`);
+            }
+            if (inferredMime.startsWith("image/")) {
+                return placeholderSvgDataUrl(`image omitted: ${value}`);
+            }
+            if (inferredMime.startsWith("video/") || inferredMime.startsWith("audio/")) {
+                return placeholderSvgDataUrl(`media omitted: ${value}`);
+            }
+            return null;
+        }
+        return toDataUrlBase64(inferredMime, bytes);
+    };
+};

package/dist/single-file/oversize-behavior.d.ts

@@ -0,0 +1,7 @@
+export type OversizeConfig = {
+    script: "error" | "placeholder";
+    stylesheet: "error" | "placeholder";
+    image: "error" | "placeholder";
+    media: "error" | "placeholder";
+};
+export declare const createOversizeBehavior: (oversize: OversizeConfig) => (mimeType?: string) => "error" | "placeholder";

package/dist/single-file/oversize-behavior.js

@@ -0,0 +1,15 @@
+import { parseResourceTypeFromMime } from "../utils/oversize.js";
+export const createOversizeBehavior = (oversize) => {
+    return (mimeType) => {
+        const type = parseResourceTypeFromMime(mimeType);
+        if (type === "script")
+            return oversize.script;
+        if (type === "stylesheet")
+            return oversize.stylesheet;
+        if (type === "image")
+            return oversize.image;
+        if (type === "media")
+            return oversize.media;
+        return "placeholder";
+    };
+};

package/dist/single-file/read-snapshot.d.ts

@@ -0,0 +1,24 @@
+type ResourcesPathSnapshotItem = {
+    url: string;
+    path: string;
+    resourceType?: string;
+    mimeType?: string;
+    size?: number;
+    dataEncoding?: "base64";
+    data?: string;
+};
+export type ResourcesPathSnapshot = {
+    version: "1.0";
+    createdAt: number;
+    items: ResourcesPathSnapshotItem[];
+};
+export type ApiSnapshot = {
+    version: "1.0";
+    url: string;
+    createdAt: number;
+    records: unknown[];
+};
+export declare const readIndexHtml: (bytesByPath: Map<string, Uint8Array>) => string;
+export declare const readOptionalApiSnapshot: (bytesByPath: Map<string, Uint8Array>) => ApiSnapshot | null;
+export declare const readResourcesPathSnapshot: (bytesByPath: Map<string, Uint8Array>) => ResourcesPathSnapshot;
+export {};

package/dist/single-file/read-snapshot.js

@@ -0,0 +1,49 @@
+import { decodeUtf8OrNull } from "../utils/decode-utf8-or-null.js";
+export const readIndexHtml = (bytesByPath) => {
+    const indexPath = "/index.html";
+    const indexBytes = bytesByPath.get(indexPath);
+    if (!indexBytes) {
+        throw new Error(`SingleFilePlugin requires ${indexPath}`);
+    }
+    const indexHtml = decodeUtf8OrNull(indexBytes);
+    if (indexHtml === null) {
+        throw new Error("SingleFilePlugin failed to decode index.html as utf-8");
+    }
+    return indexHtml;
+};
+export const readOptionalApiSnapshot = (bytesByPath) => {
+    const apiPath = "/api.json";
+    const apiBytes = bytesByPath.get(apiPath);
+    const apiJsonText = apiBytes ? decodeUtf8OrNull(apiBytes) : null;
+    if (!apiJsonText) {
+        return null;
+    }
+    try {
+        return JSON.parse(apiJsonText);
+    }
+    catch {
+        return null;
+    }
+};
+export const readResourcesPathSnapshot = (bytesByPath) => {
+    const resourcesPathPath = "/resources_path.json";
+    const bytes = bytesByPath.get(resourcesPathPath);
+    if (!bytes) {
+        throw new Error(`SingleFilePlugin requires ${resourcesPathPath}`);
+    }
+    const text = decodeUtf8OrNull(bytes);
+    if (text === null) {
+        throw new Error("SingleFilePlugin failed to decode resources_path.json as utf-8");
+    }
+    let parsed = null;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = null;
+    }
+    if (!parsed || parsed.version !== "1.0" || !Array.isArray(parsed.items)) {
+        throw new Error("SingleFilePlugin got invalid resources_path.json");
+    }
+    return parsed;
+};

package/dist/single-file/rewrite-index-html.d.ts

@@ -0,0 +1,13 @@
+import type { ApiSnapshot, ResourcesPathSnapshot } from "./read-snapshot.js";
+export declare const rewriteIndexHtmlToSingleFile: (options: {
+    indexHtml: string;
+    bytesByPath: Map<string, Uint8Array>;
+    resourcesPath: ResourcesPathSnapshot;
+    apiSnapshot: ApiSnapshot | null;
+    maxInlineBytes: number;
+    oversizeBehavior: (mimeType?: string) => "error" | "placeholder";
+    inlinePathUrl: (raw: string, context: {
+        kind: "attr" | "css";
+        selector: string;
+    }) => string | null;
+}) => Promise<string>;

package/dist/single-file/rewrite-index-html.js

@@ -0,0 +1,213 @@
+import { rewriteCssText } from "@pagepocket/lib";
+import { lookupMimeTypeFromPath } from "@pagepocket/shared";
+import * as cheerio from "cheerio";
+import { decodeUtf8OrNull } from "../utils/decode-utf8-or-null.js";
+import { placeholderSvgDataUrl } from "../utils/placeholder-svg.js";
+import { shouldSkipCssValue } from "../utils/should-skip-css-value.js";
+import { toDataUrlBase64 } from "../utils/to-data-url.js";
+const buildWindowBootstrap = (payload) => {
+    const resourcesJson = JSON.stringify(payload.resourcesPath);
+    const apiJson = payload.apiSnapshot ? JSON.stringify(payload.apiSnapshot) : "null";
+    return `\n<script>(function(){\n  window.__pagepocketResourcesPath = ${resourcesJson};\n  window.__pagepocketApiSnapshot = ${apiJson};\n})();</script>\n`;
+};
+export const rewriteIndexHtmlToSingleFile = async (options) => {
+    const { indexHtml, bytesByPath, resourcesPath, apiSnapshot, maxInlineBytes, oversizeBehavior, inlinePathUrl } = options;
+    const $ = cheerio.load(indexHtml);
+    // rewriteCssText() relies on URL() which requires an absolute base URL.
+    // We use a stable synthetic origin and convert back to snapshot-local paths.
+    const CSS_BASE_URL = "https://pagepocket.local";
+    const toSnapshotLocalPath = (absoluteOrPath) => {
+        const raw = String(absoluteOrPath || "").trim();
+        if (!raw) {
+            return null;
+        }
+        if (raw.startsWith("/")) {
+            return raw;
+        }
+        try {
+            const parsed = new URL(raw);
+            if (parsed.origin !== CSS_BASE_URL) {
+                return null;
+            }
+            const withSearch = `${parsed.pathname}${parsed.search || ""}`;
+            return withSearch || parsed.pathname || null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const rewriteCssFileToDataUrl = async (cssPath, cssBytes) => {
+        if (cssBytes.byteLength > maxInlineBytes) {
+            const behavior = oversizeBehavior("text/css");
+            if (behavior === "error") {
+                throw new Error(`SingleFilePlugin oversize text/css (>${maxInlineBytes} bytes): ${cssPath}`);
+            }
+            return placeholderSvgDataUrl(`stylesheet omitted: ${cssPath}`);
+        }
+        const cssText = decodeUtf8OrNull(cssBytes);
+        if (cssText === null) {
+            return toDataUrlBase64("text/css", cssBytes);
+        }
+        const rewritten = await rewriteCssText({
+            cssText,
+            cssUrl: `${CSS_BASE_URL}${cssPath}`,
+            resolveUrl: async (absolute) => {
+                if (shouldSkipCssValue(absolute)) {
+                    return null;
+                }
+                const snapshotPath = toSnapshotLocalPath(absolute);
+                if (!snapshotPath) {
+                    return null;
+                }
+                const mime = lookupMimeTypeFromPath(snapshotPath);
+                const behavior = oversizeBehavior(mime);
+                const bytes = bytesByPath.get(snapshotPath) ??
+                    bytesByPath.get(snapshotPath.split("?")[0] || snapshotPath);
+                if (!bytes) {
+                    return null;
+                }
+                if (bytes.byteLength > maxInlineBytes) {
+                    if (behavior === "error") {
+                        throw new Error(`SingleFilePlugin oversize ${mime} (>${maxInlineBytes} bytes) referenced from ${cssPath}: ${absolute}`);
+                    }
+                    if (mime.startsWith("image/")) {
+                        return placeholderSvgDataUrl(`image omitted: ${snapshotPath}`);
+                    }
+                    if (mime.startsWith("video/") || mime.startsWith("audio/")) {
+                        return placeholderSvgDataUrl(`media omitted: ${snapshotPath}`);
+                    }
+                    return null;
+                }
+                return toDataUrlBase64(mime, bytes);
+            }
+        });
+        const outBytes = new TextEncoder().encode(rewritten);
+        return toDataUrlBase64("text/css", outBytes);
+    };
+    const rewriteAttrToInline = (selector, attr) => {
+        $(selector).each((_, element) => {
+            const current = $(element).attr(attr);
+            if (!current) {
+                return;
+            }
+            const next = inlinePathUrl(current, { kind: "attr", selector: `${selector}[${attr}]` });
+            if (next) {
+                $(element).attr(attr, next);
+            }
+        });
+    };
+    rewriteAttrToInline("script[src]", "src");
+    rewriteAttrToInline("img[src]", "src");
+    rewriteAttrToInline("source[src]", "src");
+    rewriteAttrToInline("video[src]", "src");
+    rewriteAttrToInline("audio[src]", "src");
+    rewriteAttrToInline("track[src]", "src");
+    rewriteAttrToInline("iframe[src]", "src");
+    rewriteAttrToInline("embed[src]", "src");
+    rewriteAttrToInline("object[data]", "data");
+    rewriteAttrToInline("[poster]", "poster");
+    const linkNodes = $("link[href]").toArray();
+    for (const element of linkNodes) {
+        const value = $(element).attr("href");
+        if (!value) {
+            continue;
+        }
+        const href = String(value).trim();
+        if (!href.startsWith("/")) {
+            continue;
+        }
+        const rel = String($(element).attr("rel") || "").toLowerCase();
+        const isStylesheet = rel.includes("stylesheet");
+        if (isStylesheet && href.endsWith(".css")) {
+            const bytes = bytesByPath.get(href);
+            if (!bytes) {
+                continue;
+            }
+            const next = await rewriteCssFileToDataUrl(href, bytes);
+            $(element).attr("href", next);
+            continue;
+        }
+        const next = inlinePathUrl(href, { kind: "attr", selector: "link[href]" });
+        if (next) {
+            $(element).attr("href", next);
+        }
+    }
+    const rewriteSrcsetInline = (value) => {
+        return String(value || "")
+            .split(",")
+            .map((part) => {
+            const trimmed = part.trim();
+            if (!trimmed)
+                return trimmed;
+            const pieces = trimmed.split(/\s+/, 2);
+            const url = pieces[0] || "";
+            const descriptor = pieces[1];
+            const next = inlinePathUrl(url, { kind: "attr", selector: "[srcset]" });
+            if (!next) {
+                return trimmed;
+            }
+            return descriptor ? `${next} ${descriptor}` : next;
+        })
+            .join(", ");
+    };
+    $("img[srcset], source[srcset]").each((_index, element) => {
+        const value = $(element).attr("srcset");
+        if (!value)
+            return;
+        $(element).attr("srcset", rewriteSrcsetInline(value));
+    });
+    $("link[imagesrcset]").each((_index, element) => {
+        const value = $(element).attr("imagesrcset");
+        if (!value)
+            return;
+        $(element).attr("imagesrcset", rewriteSrcsetInline(value));
+    });
+    const inlineStyleText = async (cssText) => {
+        if (!cssText) {
+            return cssText;
+        }
+        return await rewriteCssText({
+            cssText,
+            cssUrl: `${CSS_BASE_URL}/`,
+            resolveUrl: async (absolute) => {
+                if (shouldSkipCssValue(absolute)) {
+                    return null;
+                }
+                const snapshotPath = toSnapshotLocalPath(absolute);
+                if (!snapshotPath) {
+                    return null;
+                }
+                return inlinePathUrl(snapshotPath, { kind: "css", selector: "css" });
+            }
+        });
+    };
+    const styleNodes = $("style").toArray();
+    for (const el of styleNodes) {
+        const current = $(el).html();
+        if (!current)
+            continue;
+        const next = await inlineStyleText(current);
+        if (next !== current) {
+            $(el).html(next);
+        }
+    }
+    const styled = $("[style]").toArray();
+    for (const el of styled) {
+        const current = $(el).attr("style");
+        if (!current)
+            continue;
+        const next = await inlineStyleText(current);
+        if (next !== current) {
+            $(el).attr("style", next);
+        }
+    }
+    const bootstrap = buildWindowBootstrap({ resourcesPath, apiSnapshot });
+    const head = $("head");
+    if (head.length) {
+        head.prepend(bootstrap);
+    }
+    else {
+        $.root().prepend(bootstrap);
+    }
+    return `${$.html()}\n`;
+};

package/dist/single-file-plugin.d.ts

@@ -0,0 +1,28 @@
+import type { PagePocketContext, PagePocketPlugin } from "@pagepocket/lib";
+export type SingleFilePluginOptions = {
+    /**
+     * Max bytes to inline per resource.
+     *
+     * In strong-offline single-file mode, script/stylesheet over this limit will error.
+     * image/media over this limit will be replaced with placeholders in HTML.
+     */
+    maxInlineBytes?: number;
+    /**
+     * Oversize behavior by resource type.
+     * - "error": throw and stop single-file build
+     * - "placeholder": replace URL with a placeholder data URL
+     */
+    oversize?: {
+        script?: "error" | "placeholder";
+        stylesheet?: "error" | "placeholder";
+        image?: "error" | "placeholder";
+        media?: "error" | "placeholder";
+    };
+};
+export declare class SingleFilePlugin implements PagePocketPlugin {
+    readonly name = "plugin:single-file";
+    private maxInlineBytes;
+    private oversize;
+    constructor(options?: SingleFilePluginOptions);
+    apply(ctx: PagePocketContext): void;
+}

package/dist/single-file-plugin.js

@@ -0,0 +1,69 @@
+import { collectSnapshotBytesByPath } from "./single-file/collect-bytes.js";
+import { embedResourcesPathData } from "./single-file/embed-resources.js";
+import { createInlinePathUrl } from "./single-file/inline-path-url.js";
+import { createOversizeBehavior } from "./single-file/oversize-behavior.js";
+import { readIndexHtml, readOptionalApiSnapshot, readResourcesPathSnapshot } from "./single-file/read-snapshot.js";
+import { rewriteIndexHtmlToSingleFile } from "./single-file/rewrite-index-html.js";
+import { defaultOversizeBehavior } from "./utils/oversize.js";
+const DEFAULT_MAX_INLINE_BYTES = 25 * 1024 * 1024;
+const defaultOversize = defaultOversizeBehavior;
+export class SingleFilePlugin {
+    constructor(options) {
+        this.name = "plugin:single-file";
+        this.maxInlineBytes = options?.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+        this.oversize = {
+            script: options?.oversize?.script ?? defaultOversize.script,
+            stylesheet: options?.oversize?.stylesheet ?? defaultOversize.stylesheet,
+            image: options?.oversize?.image ?? defaultOversize.image,
+            media: options?.oversize?.media ?? defaultOversize.media
+        };
+    }
+    apply(ctx) {
+        ctx.onFinalize(async () => {
+            const files = ctx.files;
+            if (!files) {
+                throw new Error("SingleFilePlugin requires ctx.files (run after snapshot builders)");
+            }
+            const bytesByPath = await collectSnapshotBytesByPath(files);
+            const indexHtml = readIndexHtml(bytesByPath);
+            const apiSnapshot = readOptionalApiSnapshot(bytesByPath);
+            const resourcesPath = readResourcesPathSnapshot(bytesByPath);
+            const oversizeBehavior = createOversizeBehavior(this.oversize);
+            const inlinePathUrl = createInlinePathUrl({
+                bytesByPath,
+                maxInlineBytes: this.maxInlineBytes,
+                oversizeBehavior
+            });
+            await embedResourcesPathData({
+                resourcesPath,
+                bytesByPath,
+                maxInlineBytes: this.maxInlineBytes,
+                oversizeBehavior,
+                inlinePathUrl
+            });
+            const finalHtml = await rewriteIndexHtmlToSingleFile({
+                indexHtml,
+                bytesByPath,
+                resourcesPath,
+                apiSnapshot,
+                maxInlineBytes: this.maxInlineBytes,
+                oversizeBehavior,
+                inlinePathUrl
+            });
+            ctx.files = {
+                root: {
+                    kind: "directory",
+                    path: "",
+                    entries: [
+                        {
+                            kind: "file",
+                            path: "/index.html",
+                            source: { kind: "text", text: finalHtml }
+                        }
+                    ]
+                },
+                content: files.content
+            };
+        });
+    }
+}

package/dist/single-file-unit.d.ts

@@ -0,0 +1,17 @@
+import { Unit, type UnitContext } from "@pagepocket/lib";
+export type SingleFileUnitOptions = {
+    maxInlineBytes?: number;
+    oversize?: {
+        script?: "error" | "placeholder";
+        stylesheet?: "error" | "placeholder";
+        image?: "error" | "placeholder";
+        media?: "error" | "placeholder";
+    };
+};
+export declare class SingleFileUnit extends Unit {
+    readonly id = "singleFile";
+    readonly kind = "build.singleFile";
+    private options;
+    constructor(options?: SingleFileUnitOptions);
+    run(ctx: UnitContext): Promise<void | Record<string, unknown>>;
+}

package/dist/single-file-unit.js

@@ -0,0 +1,20 @@
+import { Unit } from "@pagepocket/lib";
+export class SingleFileUnit extends Unit {
+    constructor(options) {
+        super();
+        this.id = "singleFile";
+        this.kind = "build.singleFile";
+        this.options = options;
+    }
+    async run(ctx) {
+        const files = ctx.value.files;
+        if (!files) {
+            throw new Error("SingleFileUnit requires ctx.value.files");
+        }
+        // Single-file transformation is pure with respect to artifacts.
+        // We keep implementation local to this package; it consumes and produces files@1.
+        const { buildSingleFileFiles } = await import("./single-file/build-single-file-files.js");
+        const nextFiles = await buildSingleFileFiles({ files, options: this.options });
+        return { files: nextFiles };
+    }
+}

package/dist/utils/decode-utf8-or-null.d.ts

@@ -0,0 +1 @@
+export declare const decodeUtf8OrNull: (bytes: Uint8Array) => string | null;

package/dist/utils/decode-utf8-or-null.js

@@ -0,0 +1,5 @@
+import { decodeUtf8Lenient } from "@pagepocket/shared";
+export const decodeUtf8OrNull = (bytes) => {
+    const decoded = decodeUtf8Lenient(bytes);
+    return decoded ? decoded : null;
+};

package/dist/utils/file-tree.d.ts

@@ -0,0 +1,5 @@
+import type { FileTreeDirectory, FileTreeFile } from "@pagepocket/lib";
+export declare const flattenEntries: (dir: FileTreeDirectory, prefix: string) => Array<{
+    path: string;
+    file: FileTreeFile;
+}>;

package/dist/utils/file-tree.js

@@ -0,0 +1,28 @@
+const joinPosix = (base, relative) => {
+    const cleanBase = String(base || "")
+        .replace(/\\/g, "/")
+        .replace(/\/+$/, "");
+    const cleanRel = String(relative || "")
+        .replace(/\\/g, "/")
+        .replace(/^\/+/, "");
+    if (!cleanBase) {
+        return cleanRel;
+    }
+    if (!cleanRel) {
+        return cleanBase;
+    }
+    return `${cleanBase}/${cleanRel}`;
+};
+export const flattenEntries = (dir, prefix) => {
+    const out = [];
+    const dirPrefix = joinPosix(prefix, dir.path);
+    for (const entry of dir.entries) {
+        if (entry.kind === "file") {
+            const filePath = joinPosix(dirPrefix, entry.path);
+            out.push({ path: filePath.startsWith("/") ? filePath : `/${filePath}`, file: entry });
+            continue;
+        }
+        out.push(...flattenEntries(entry, dirPrefix));
+    }
+    return out;
+};

package/dist/utils/oversize.d.ts

@@ -0,0 +1,16 @@
+declare const defaultOversize: {
+    readonly script: "error";
+    readonly stylesheet: "error";
+    readonly image: "placeholder";
+    readonly media: "placeholder";
+};
+export type OversizeResourceType = keyof typeof defaultOversize;
+export type OversizeBehavior = (typeof defaultOversize)[OversizeResourceType];
+export declare const parseResourceTypeFromMime: (mimeType?: string) => OversizeResourceType | null;
+export declare const defaultOversizeBehavior: {
+    readonly script: "error";
+    readonly stylesheet: "error";
+    readonly image: "placeholder";
+    readonly media: "placeholder";
+};
+export {};

package/dist/utils/oversize.js

@@ -0,0 +1,25 @@
+const defaultOversize = {
+    script: "error",
+    stylesheet: "error",
+    image: "placeholder",
+    media: "placeholder"
+};
+export const parseResourceTypeFromMime = (mimeType) => {
+    const mime = String(mimeType || "").toLowerCase();
+    if (mime.includes("javascript") ||
+        mime === "application/x-javascript" ||
+        mime === "text/ecmascript") {
+        return "script";
+    }
+    if (mime === "text/css") {
+        return "stylesheet";
+    }
+    if (mime.startsWith("image/")) {
+        return "image";
+    }
+    if (mime.startsWith("video/") || mime.startsWith("audio/")) {
+        return "media";
+    }
+    return null;
+};
+export const defaultOversizeBehavior = defaultOversize;

package/dist/utils/placeholder-svg.d.ts

@@ -0,0 +1 @@
+export declare const placeholderSvgDataUrl: (label: string) => string;

package/dist/utils/placeholder-svg.js

@@ -0,0 +1,5 @@
+export const placeholderSvgDataUrl = (label) => {
+    const safe = String(label || "omitted").replace(/[<>]/g, "");
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="320" height="180"><rect width="100%" height="100%" fill="#eee"/><text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="monospace" font-size="14" fill="#444">${safe}</text></svg>`;
+    return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+};

package/dist/utils/should-skip-css-value.d.ts

@@ -0,0 +1 @@
+export declare const shouldSkipCssValue: (value: string) => boolean;

package/dist/utils/should-skip-css-value.js

@@ -0,0 +1,10 @@
+export const shouldSkipCssValue = (value) => {
+    const trimmed = String(value || "").trim();
+    return (!trimmed ||
+        trimmed.startsWith("data:") ||
+        trimmed.startsWith("blob:") ||
+        trimmed.startsWith("mailto:") ||
+        trimmed.startsWith("tel:") ||
+        trimmed.startsWith("javascript:") ||
+        trimmed.startsWith("#"));
+};

package/dist/utils/stream-to-uint8array.d.ts

@@ -0,0 +1 @@
+export declare const streamToUint8Array: (stream: ReadableStream<Uint8Array>) => Promise<Uint8Array>;

package/dist/utils/stream-to-uint8array.js

@@ -0,0 +1,22 @@
+export const streamToUint8Array = async (stream) => {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const result = await reader.read();
+        if (result.done) {
+            break;
+        }
+        if (result.value) {
+            chunks.push(result.value);
+            total += result.value.byteLength;
+        }
+    }
+    const output = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+};

package/dist/utils/to-data-url.d.ts

@@ -0,0 +1 @@
+export declare const toDataUrlBase64: (mimeType: string, bytes: Uint8Array) => string;

package/dist/utils/to-data-url.js

@@ -0,0 +1,5 @@
+import { bytesToBase64 } from "@pagepocket/shared";
+export const toDataUrlBase64 = (mimeType, bytes) => {
+    const mime = mimeType || "application/octet-stream";
+    return `data:${mime};base64,${bytesToBase64(bytes)}`;
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pagepocket/single-file-unit",
+  "version": "0.8.0",
+  "description": "PagePocket plugin: emit strong-offline single-file index.html",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "cheerio": "^1.1.2",
+    "@pagepocket/lib": "0.8.0",
+    "@pagepocket/shared": "0.8.0",
+    "@pagepocket/contracts": "0.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node -e \"process.exit(0)\""
+  }
+}