@pagepocket/write-down-unit 0.8.0

package/dist/filename.d.ts

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

package/dist/filename.js

@@ -0,0 +1,10 @@
+export const safeFilename = (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return "snapshot";
+    }
+    return (trimmed
+        .replace(/[^a-zA-Z0-9._-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 120) || "snapshot");
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { WriteDownUnit } from "./write-down-unit.js";
+export type { FileTree, FileTreeDirectory, FileTreeEntry, FileTreeFile, FileTreeSource } from "@pagepocket/lib";
+export type { WriteDownUnitOptions } from "./write-down-unit.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { WriteDownUnit } from "./write-down-unit.js";

package/dist/plugin.d.ts

@@ -0,0 +1,61 @@
+import type { ContentRef, PagePocketContext, PagePocketPlugin } from "@pagepocket/lib";
+export type WriteDownPluginOptions = {
+    enabled?: boolean;
+    type: "raw" | "zip";
+    /**
+     * For raw: output directory path.
+     * For zip: output file path.
+     */
+    outputPath: string;
+    overwrite?: boolean;
+};
+export type WriteDownFileSource = {
+    kind: "bytes";
+    data: Uint8Array;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "content-ref";
+    ref: ContentRef;
+};
+export type WriteDownFile = {
+    kind: "file";
+    /** Path relative to the root of this write-down (posix-ish, may include '/'). */
+    path: string;
+    source: WriteDownFileSource;
+};
+export type WriteDownDirectory = {
+    kind: "directory";
+    /** Path relative to the root of this write-down (posix-ish, may include '/'). */
+    path: string;
+    entries: WriteDownEntry[];
+};
+export type WriteDownEntry = WriteDownFile | WriteDownDirectory;
+/**
+ * Generic, plugin-agnostic filesystem tree to be written by WriteDownPlugin.
+ *
+ * Other plugins should populate `ctx.files` using this shape.
+ */
+export type WriteDownFiles = {
+    /** Root directory (virtual). Its own `path` should be "". */
+    root: WriteDownDirectory;
+    /**
+     * Optional content store handle used when entries reference `{ kind: "content-ref" }`.
+     *
+     * Typically this comes from a PageSnapshot's `content`.
+     */
+    content?: {
+        open(ref: ContentRef): Promise<ReadableStream<Uint8Array>>;
+        dispose?(): Promise<void>;
+    };
+};
+export declare class WriteDownPlugin implements PagePocketPlugin {
+    readonly name = "plugin:write-down";
+    enabled?: boolean;
+    private type;
+    private outputPath;
+    private overwrite;
+    constructor(options: WriteDownPluginOptions);
+    apply(ctx: PagePocketContext): void;
+}

package/dist/plugin.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteDownPlugin = void 0;
+const uni_fs_1 = require("@pagepocket/uni-fs");
+const normalizePath = (value) => value.replace(/\\/g, "/");
+const trimLeadingSlash = (value) => normalizePath(value).replace(/^\/+/, "");
+const joinPosix = (base, relative) => {
+    const cleanBase = normalizePath(base).replace(/\/+$/, "");
+    const cleanRel = normalizePath(relative).replace(/^\/+/, "");
+    if (!cleanBase) {
+        return cleanRel;
+    }
+    if (!cleanRel) {
+        return cleanBase;
+    }
+    return `${cleanBase}/${cleanRel}`;
+};
+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;
+};
+const encodeText = (text) => new TextEncoder().encode(text);
+const splitPathExtension = (value) => {
+    const clean = normalizePath(value);
+    const lastSlash = clean.lastIndexOf("/");
+    const lastDot = clean.lastIndexOf(".");
+    if (lastDot > lastSlash) {
+        return {
+            filename: clean.slice(0, lastDot),
+            extension: clean.slice(lastDot + 1)
+        };
+    }
+    return { filename: clean, extension: "" };
+};
+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, file: entry });
+            continue;
+        }
+        out.push(...flattenEntries(entry, dirPrefix));
+    }
+    return out;
+};
+const buildZipBytes = async (files) => {
+    // Minimal ZIP writer (store/no compression). Mirrors @pagepocket/lib toZip semantics.
+    const writeUint16 = (value) => {
+        const buffer = new Uint8Array(2);
+        const view = new DataView(buffer.buffer);
+        view.setUint16(0, value, true);
+        return buffer;
+    };
+    const writeUint32 = (value) => {
+        const buffer = new Uint8Array(4);
+        const view = new DataView(buffer.buffer);
+        view.setUint32(0, value, true);
+        return buffer;
+    };
+    const concatBytes = (chunks) => {
+        const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+        const output = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            output.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return output;
+    };
+    const crc32Table = (() => {
+        const table = new Uint32Array(256);
+        for (let i = 0; i < 256; i += 1) {
+            let c = i;
+            for (let k = 0; k < 8; k += 1) {
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            }
+            table[i] = c >>> 0;
+        }
+        return table;
+    })();
+    const crc32 = (data) => {
+        let crc = 0 ^ -1;
+        for (let i = 0; i < data.length; i += 1) {
+            crc = (crc >>> 8) ^ crc32Table[(crc ^ data[i]) & 0xff];
+        }
+        return (crc ^ -1) >>> 0;
+    };
+    const localChunks = [];
+    const centralChunks = [];
+    let offset = 0;
+    for (const file of files) {
+        const name = trimLeadingSlash(file.path);
+        const nameBytes = new TextEncoder().encode(name);
+        const data = file.data;
+        const crc = crc32(data);
+        const localHeader = concatBytes([
+            writeUint32(0x04034b50),
+            writeUint16(20),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint32(crc),
+            writeUint32(data.byteLength),
+            writeUint32(data.byteLength),
+            writeUint16(nameBytes.byteLength),
+            writeUint16(0),
+            nameBytes
+        ]);
+        localChunks.push(localHeader, data);
+        const centralHeader = concatBytes([
+            writeUint32(0x02014b50),
+            writeUint16(20),
+            writeUint16(20),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint32(crc),
+            writeUint32(data.byteLength),
+            writeUint32(data.byteLength),
+            writeUint16(nameBytes.byteLength),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint16(0),
+            writeUint32(0),
+            writeUint32(offset),
+            nameBytes
+        ]);
+        centralChunks.push(centralHeader);
+        offset += localHeader.byteLength + data.byteLength;
+    }
+    const centralDirectory = concatBytes(centralChunks);
+    const endRecord = concatBytes([
+        writeUint32(0x06054b50),
+        writeUint16(0),
+        writeUint16(0),
+        writeUint16(files.length),
+        writeUint16(files.length),
+        writeUint32(centralDirectory.byteLength),
+        writeUint32(offset),
+        writeUint16(0)
+    ]);
+    return concatBytes([...localChunks, centralDirectory, endRecord]);
+};
+class WriteDownPlugin {
+    constructor(options) {
+        this.name = "plugin:write-down";
+        this.enabled = options.enabled;
+        this.type = options.type;
+        this.outputPath = options.outputPath;
+        this.overwrite = options.overwrite ?? false;
+    }
+    apply(ctx) {
+        ctx.onFinalize(async () => {
+            const files = ctx.files;
+            if (!files) {
+                throw new Error("WriteDownPlugin requires ctx.files");
+            }
+            if (!files.root || files.root.kind !== "directory") {
+                throw new Error("WriteDownPlugin requires ctx.files.root directory");
+            }
+            const flattened = flattenEntries(files.root, "");
+            const outputs = [];
+            for (const item of flattened) {
+                const src = item.file.source;
+                if (src.kind === "bytes") {
+                    outputs.push({ path: item.path, data: src.data });
+                    continue;
+                }
+                if (src.kind === "text") {
+                    outputs.push({ path: item.path, data: encodeText(src.text) });
+                    continue;
+                }
+                if (src.kind === "content-ref") {
+                    if (!files.content) {
+                        throw new Error('WriteDownPlugin cannot resolve { kind: "content-ref" } without ctx.files.content');
+                    }
+                    const stream = await files.content.open(src.ref);
+                    const data = await streamToUint8Array(stream);
+                    outputs.push({ path: item.path, data });
+                    continue;
+                }
+                // Exhaustiveness guard.
+                const _never = src;
+                throw new Error(`Unhandled file source kind: ${String(_never)}`);
+            }
+            if (this.type === "raw") {
+                // Note: @pagepocket/uni-fs write() creates parent directories.
+                for (const file of outputs) {
+                    const outputPath = joinPosix(this.outputPath, file.path);
+                    const { filename, extension } = splitPathExtension(outputPath);
+                    await (0, uni_fs_1.write)(filename, extension, file.data);
+                }
+                if (files.content?.dispose) {
+                    await files.content.dispose();
+                }
+                return { kind: "raw", outputDir: this.outputPath };
+            }
+            const zipBytes = await buildZipBytes(outputs);
+            const { filename, extension } = splitPathExtension(this.outputPath);
+            await (0, uni_fs_1.write)(filename, extension, zipBytes);
+            if (files.content?.dispose) {
+                await files.content.dispose();
+            }
+            return { kind: "zip", zip: { data: zipBytes, outputPath: this.outputPath } };
+        });
+    }
+}
+exports.WriteDownPlugin = WriteDownPlugin;

package/dist/utils/bytes.d.ts

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

package/dist/utils/bytes.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;
+};
+export const textToUint8Array = (text) => new TextEncoder().encode(text);

package/dist/utils/posix-path.d.ts

@@ -0,0 +1,10 @@
+type PosixPath = string;
+export declare const normalizePath: (value: string) => PosixPath;
+export declare const trimLeadingSlash: (value: string) => string;
+export declare const joinPosix: (base: string, relative: string) => string;
+export declare const dirnamePosix: (value: string) => PosixPath;
+export declare const splitPathExtension: (value: string) => {
+    filename: string;
+    extension: string;
+};
+export {};

package/dist/utils/posix-path.js

@@ -0,0 +1,36 @@
+export const normalizePath = (value) => value.replace(/\\/g, "/");
+export const trimLeadingSlash = (value) => normalizePath(value).replace(/^\/+/, "");
+export const joinPosix = (base, relative) => {
+    const cleanBase = normalizePath(base).replace(/\/+$/, "");
+    const cleanRel = normalizePath(relative).replace(/^\/+/, "");
+    if (!cleanBase) {
+        return cleanRel;
+    }
+    if (!cleanRel) {
+        return cleanBase;
+    }
+    return `${cleanBase}/${cleanRel}`;
+};
+export const dirnamePosix = (value) => {
+    const clean = normalizePath(value).replace(/\/+$/, "");
+    const lastSlash = clean.lastIndexOf("/");
+    if (lastSlash < 0) {
+        return ".";
+    }
+    if (lastSlash === 0) {
+        return "/";
+    }
+    return clean.slice(0, lastSlash);
+};
+export const splitPathExtension = (value) => {
+    const clean = normalizePath(value);
+    const lastSlash = clean.lastIndexOf("/");
+    const lastDot = clean.lastIndexOf(".");
+    if (lastDot > lastSlash) {
+        return {
+            filename: clean.slice(0, lastDot),
+            extension: clean.slice(lastDot + 1)
+        };
+    }
+    return { filename: clean, extension: "" };
+};

package/dist/utils/zip.d.ts

@@ -0,0 +1,5 @@
+export type ZipEntry = {
+    path: string;
+    data: Uint8Array;
+};
+export declare const buildZipBytes: (files: ZipEntry[]) => Uint8Array;

package/dist/utils/zip.js

@@ -0,0 +1,11 @@
+import { zipSync } from "fflate";
+export const buildZipBytes = (files) => {
+    const entries = {};
+    for (const item of files) {
+        // ZIP expects paths without a leading slash.
+        const key = item.path.startsWith("/") ? item.path.slice(1) : item.path;
+        entries[key] = item.data;
+    }
+    // level: 0 => store/no compression (matches previous behavior intent).
+    return zipSync(entries, { level: 0 });
+};

package/dist/write-down-plugin.d.ts

@@ -0,0 +1,25 @@
+import type { FileTree, FileTreeDirectory, FileTreeEntry, FileTreeFile, FileTreeSource, PagePocketContext, PagePocketPlugin } from "@pagepocket/lib";
+export type WriteDownPluginOptions = {
+    type: "raw" | "zip";
+    /**
+     * Base output directory.
+     *
+     * - For raw emit: snapshot is written under <outputPath>/<title>/...
+     * - For zip emit: snapshot is written to <outputPath>/<title>.zip
+     */
+    outputPath: string;
+    overwrite?: boolean;
+};
+export type WriteDownFileSource = FileTreeSource;
+export type WriteDownFile = FileTreeFile;
+export type WriteDownDirectory = FileTreeDirectory;
+export type WriteDownEntry = FileTreeEntry;
+export type WriteDownFiles = FileTree;
+export declare class WriteDownPlugin implements PagePocketPlugin {
+    readonly name = "plugin:write-down";
+    private type;
+    private outputPath;
+    private overwrite;
+    constructor(options: WriteDownPluginOptions);
+    apply(ctx: PagePocketContext): void;
+}

package/dist/write-down-plugin.js

@@ -0,0 +1,196 @@
+import { write } from "@pagepocket/uni-fs";
+import { safeFilename } from "./filename.js";
+import { buildZipBytes } from "./utils/zip.js";
+const normalizePath = (value) => value.replace(/\\/g, "/");
+const joinPosix = (base, relative) => {
+    const cleanBase = normalizePath(base).replace(/\/+$/, "");
+    const cleanRel = normalizePath(relative).replace(/^\/+/, "");
+    if (!cleanBase) {
+        return cleanRel;
+    }
+    if (!cleanRel) {
+        return cleanBase;
+    }
+    return `${cleanBase}/${cleanRel}`;
+};
+const extractHtmlTitle = (html) => {
+    const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    if (!match) {
+        return undefined;
+    }
+    const raw = match[1] ?? "";
+    const normalized = raw.replace(/\s+/g, " ").trim();
+    return normalized || undefined;
+};
+const tryHostname = (url) => {
+    if (!url) {
+        return undefined;
+    }
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+};
+const pathExists = async (p) => {
+    const { stat } = await import("node:fs/promises");
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const removeExistingPath = async (p) => {
+    const { rm } = await import("node:fs/promises");
+    await rm(p, { force: true, recursive: true });
+};
+const withUniquePath = async (desiredPath, options) => {
+    if (!(await pathExists(desiredPath))) {
+        return desiredPath;
+    }
+    if (options.overwrite) {
+        await removeExistingPath(desiredPath);
+        return desiredPath;
+    }
+    const pathMod = await import("node:path");
+    const parsed = pathMod.parse(desiredPath);
+    const base = pathMod.join(parsed.dir, parsed.name);
+    const ext = parsed.ext;
+    for (let i = 2; i <= 9999; i += 1) {
+        const candidate = `${base}-${i}${ext}`;
+        if (!(await pathExists(candidate))) {
+            return candidate;
+        }
+    }
+    throw new Error(`Unable to find a unique output path for: ${desiredPath}`);
+};
+const resolveSnapshotBaseName = async (ctx) => {
+    const html = await ctx.whenHtml();
+    const titleFromHtml = extractHtmlTitle(html.htmlString);
+    const fallbackHostname = ctx.entry.kind === "url" ? tryHostname(ctx.entry.url) : tryHostname(html.url ?? html.baseUrl);
+    return safeFilename(titleFromHtml ?? fallbackHostname ?? "snapshot");
+};
+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;
+};
+const encodeText = (text) => new TextEncoder().encode(text);
+const splitPathExtension = (value) => {
+    const clean = normalizePath(value);
+    const lastSlash = clean.lastIndexOf("/");
+    const lastDot = clean.lastIndexOf(".");
+    if (lastDot > lastSlash) {
+        return {
+            filename: clean.slice(0, lastDot),
+            extension: clean.slice(lastDot + 1)
+        };
+    }
+    return { filename: clean, extension: "" };
+};
+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, file: entry });
+            continue;
+        }
+        out.push(...flattenEntries(entry, dirPrefix));
+    }
+    return out;
+};
+// buildZipBytes moved to ./utils/zip
+export class WriteDownPlugin {
+    constructor(options) {
+        this.name = "plugin:write-down";
+        this.type = options.type;
+        this.outputPath = options.outputPath;
+        this.overwrite = options.overwrite ?? false;
+    }
+    apply(ctx) {
+        ctx.onFinalize(async () => {
+            if (!this.outputPath || !this.outputPath.trim()) {
+                throw new Error("WriteDownPlugin requires a non-empty outputPath");
+            }
+            const baseName = await resolveSnapshotBaseName(ctx);
+            const pathMod = await import("node:path");
+            const outputRoot = pathMod.resolve(this.outputPath);
+            const rawDir = pathMod.join(outputRoot, baseName);
+            const zipPath = pathMod.join(outputRoot, `${baseName}.zip`);
+            const finalRawDir = await withUniquePath(rawDir, { overwrite: this.overwrite });
+            const finalZipPath = await withUniquePath(zipPath, { overwrite: this.overwrite });
+            const files = ctx.files;
+            if (!files) {
+                throw new Error("WriteDownPlugin requires ctx.files");
+            }
+            if (!files.root || files.root.kind !== "directory") {
+                throw new Error("WriteDownPlugin requires ctx.files.root directory");
+            }
+            const flattened = flattenEntries(files.root, "");
+            const outputs = [];
+            for (const item of flattened) {
+                const src = item.file.source;
+                if (src.kind === "bytes") {
+                    outputs.push({ path: item.path, data: src.data });
+                    continue;
+                }
+                if (src.kind === "text") {
+                    outputs.push({ path: item.path, data: encodeText(src.text) });
+                    continue;
+                }
+                if (src.kind === "content-ref") {
+                    if (!files.content) {
+                        throw new Error('WriteDownPlugin cannot resolve { kind: "content-ref" } without ctx.files.content');
+                    }
+                    const stream = await files.content.open(src.ref);
+                    const data = await streamToUint8Array(stream);
+                    outputs.push({ path: item.path, data });
+                    continue;
+                }
+                // Exhaustiveness guard.
+                const _never = src;
+                throw new Error(`Unhandled file source kind: ${String(_never)}`);
+            }
+            if (this.type === "raw") {
+                // Note: @pagepocket/uni-fs write() creates parent directories.
+                for (const file of outputs) {
+                    const outputPath = joinPosix(finalRawDir, file.path);
+                    const { filename, extension } = splitPathExtension(outputPath);
+                    await write(filename, extension, file.data);
+                }
+                if (files.content?.dispose) {
+                    await files.content.dispose();
+                }
+                return { kind: "raw", outputDir: finalRawDir };
+            }
+            const zipBytes = await buildZipBytes(outputs);
+            const { filename, extension } = splitPathExtension(finalZipPath);
+            await write(filename, extension, zipBytes);
+            if (files.content?.dispose) {
+                await files.content.dispose();
+            }
+            return { kind: "zip", zip: { data: zipBytes, outputPath: finalZipPath } };
+        });
+    }
+}

package/dist/write-down-unit.d.ts

@@ -0,0 +1,20 @@
+import { Unit, type CaptureResult, type UnitContext } from "@pagepocket/lib";
+export type WriteDownUnitOptions = {
+    type: "raw" | "zip";
+    outputPath: string;
+    overwrite?: boolean;
+};
+/**
+ * v3 unit wrapper around the existing WriteDownPlugin logic.
+ *
+ * Break-change path: this will become the primary implementation.
+ */
+export declare class WriteDownUnit extends Unit {
+    readonly id = "writeDown";
+    readonly kind = "write.down";
+    private options;
+    constructor(options: WriteDownUnitOptions);
+    run(ctx: UnitContext, rt: import("@pagepocket/lib").UnitRuntime): Promise<{
+        __pagepocketResult: CaptureResult;
+    }>;
+}

package/dist/write-down-unit.js

@@ -0,0 +1,35 @@
+import { TERMINAL_RESULT_KEY, Unit } from "@pagepocket/lib";
+import { writeDown } from "./write-down.js";
+/**
+ * v3 unit wrapper around the existing WriteDownPlugin logic.
+ *
+ * Break-change path: this will become the primary implementation.
+ */
+export class WriteDownUnit extends Unit {
+    constructor(options) {
+        super();
+        this.id = "writeDown";
+        this.kind = "write.down";
+        this.options = options;
+    }
+    async run(ctx, rt) {
+        const files = ctx.value.files;
+        if (!files) {
+            throw new Error("WriteDownUnit requires ctx.value.files");
+        }
+        const html = ctx.value.html;
+        if (!html) {
+            throw new Error("WriteDownUnit requires ctx.value.html");
+        }
+        // Reuse the library implementation directly.
+        const result = await writeDown({
+            entry: rt.entry,
+            html,
+            files,
+            type: this.options.type,
+            outputPath: this.options.outputPath,
+            overwrite: this.options.overwrite ?? false
+        });
+        return { [TERMINAL_RESULT_KEY]: result };
+    }
+}

package/dist/write-down.d.ts

@@ -0,0 +1,18 @@
+import type { FileTree } from "@pagepocket/lib";
+export type WriteDownOptions = {
+    type: "raw" | "zip";
+    outputPath: string;
+    overwrite: boolean;
+};
+export declare const writeDown: (input: {
+    entry: unknown;
+    html: {
+        htmlString: string;
+        baseUrl: string;
+        url?: string;
+    };
+    files: FileTree;
+    type: WriteDownOptions["type"];
+    outputPath: string;
+    overwrite: boolean;
+}) => Promise<import("@pagepocket/lib").PagePocketCaptureResult>;

package/dist/write-down.js

@@ -0,0 +1,127 @@
+import { rm, stat } from "node:fs/promises";
+import pathMod from "node:path";
+import { write } from "@pagepocket/uni-fs";
+import { safeFilename } from "./filename.js";
+import { streamToUint8Array, textToUint8Array } from "./utils/bytes.js";
+import { joinPosix, normalizePath } from "./utils/posix-path.js";
+import { buildZipBytes } from "./utils/zip.js";
+const extractHtmlTitle = (html) => {
+    const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    if (!match) {
+        return undefined;
+    }
+    const raw = match[1] ?? "";
+    const normalized = raw.replace(/\s+/g, " ").trim();
+    return normalized || undefined;
+};
+const tryHostname = (url) => {
+    if (!url) {
+        return undefined;
+    }
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+};
+const pathExists = async (p) => {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const removeExistingPath = async (p) => {
+    await rm(p, { force: true, recursive: true });
+};
+const withUniquePath = async (desiredPath, options) => {
+    if (!(await pathExists(desiredPath))) {
+        return desiredPath;
+    }
+    if (options.overwrite) {
+        await removeExistingPath(desiredPath);
+        return desiredPath;
+    }
+    const parsed = pathMod.parse(desiredPath);
+    const base = pathMod.join(parsed.dir, parsed.name);
+    const ext = parsed.ext;
+    for (let i = 2; i <= 9999; i += 1) {
+        const candidate = `${base}-${i}${ext}`;
+        if (!(await pathExists(candidate))) {
+            return candidate;
+        }
+    }
+    throw new Error(`Unable to find a unique output path for: ${desiredPath}`);
+};
+const resolveSnapshotBaseName = (entry, html) => {
+    const titleFromHtml = extractHtmlTitle(html.htmlString);
+    const entryUrl = entry && typeof entry === "object" && "kind" in entry && entry.kind === "url"
+        ? entry.url
+        : undefined;
+    const fallbackHostname = tryHostname(entryUrl) ?? tryHostname(html.url ?? html.baseUrl);
+    return safeFilename(titleFromHtml ?? fallbackHostname ?? "snapshot");
+};
+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, file: entry });
+            continue;
+        }
+        out.push(...flattenEntries(entry, dirPrefix));
+    }
+    return out;
+};
+export const writeDown = async (input) => {
+    if (!input.outputPath || !input.outputPath.trim()) {
+        throw new Error("WriteDownUnit requires a non-empty outputPath");
+    }
+    if (!input.files.root || input.files.root.kind !== "directory") {
+        throw new Error("WriteDownUnit requires files.root directory");
+    }
+    const baseName = resolveSnapshotBaseName(input.entry, input.html);
+    const outputRoot = pathMod.resolve(input.outputPath);
+    const rawDir = pathMod.join(outputRoot, baseName);
+    const zipPath = pathMod.join(outputRoot, `${baseName}.zip`);
+    const finalRawDir = await withUniquePath(rawDir, { overwrite: input.overwrite });
+    const finalZipPath = await withUniquePath(zipPath, { overwrite: input.overwrite });
+    const flattened = flattenEntries(input.files.root, "");
+    const outputs = [];
+    for (const item of flattened) {
+        const src = item.file.source;
+        if (src.kind === "bytes") {
+            outputs.push({ path: item.path, data: src.data });
+            continue;
+        }
+        if (src.kind === "text") {
+            outputs.push({ path: item.path, data: textToUint8Array(src.text) });
+            continue;
+        }
+        if (src.kind === "content-ref") {
+            if (!input.files.content) {
+                throw new Error('WriteDownUnit cannot resolve { kind: "content-ref" } without files.content');
+            }
+            const stream = await input.files.content.open(src.ref);
+            const data = await streamToUint8Array(stream);
+            outputs.push({ path: item.path, data });
+            continue;
+        }
+        const _never = src;
+        throw new Error(`Unhandled file source kind: ${String(_never)}`);
+    }
+    if (input.type === "raw") {
+        for (const item of outputs) {
+            const outPath = pathMod.join(finalRawDir, normalizePath(item.path).replace(/^\/+/, ""));
+            await write(outPath, "", item.data);
+        }
+        return { kind: "raw", outputDir: finalRawDir };
+    }
+    const zipBytes = buildZipBytes(outputs);
+    await write(finalZipPath, "", zipBytes);
+    return { kind: "zip", zip: { data: zipBytes, outputPath: finalZipPath } };
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pagepocket/write-down-unit",
+  "version": "0.8.0",
+  "description": "PagePocket plugin: write snapshot output to fs (raw or zip)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "@pagepocket/lib": "0.8.0",
+    "@pagepocket/contracts": "0.8.0",
+    "@pagepocket/uni-fs": "0.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node -e \"process.exit(0)\""
+  }
+}