@voidberg/quarto 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2026 Alexandru Badiu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+![Quarto](assets/quarto.png)
+
+# Quarto
+
+[![npm](https://img.shields.io/npm/v/@voidberg/quarto.svg)](https://www.npmjs.com/package/@voidberg/quarto)
+[![JSR](https://jsr.io/badges/@voidberg/quarto)](https://jsr.io/@voidberg/quarto)
+[![CI](https://github.com/voidberg/quarto/actions/workflows/ci.yml/badge.svg)](https://github.com/voidberg/quarto/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/npm/l/@voidberg/quarto.svg)](https://opensource.org/licenses/MIT)
+
+> a book size of about 9½ × 12 inches (24 × 30 centimetres), determined by folding printed sheets twice to form four leaves or eight pages.
+
+Generate **EPUB3** and Kobo **kepub** files from HTML — entirely in memory, with no native dependencies and no external binaries.
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { generateEpub, toKepub } from "@voidberg/quarto";
+
+const epub = await generateEpub({
+  title: "On the Shortness of Life",
+  author: "Seneca",
+  chapters: [{ title: "I", html: "<p>It is not that we have a short time to live…</p>" }],
+});
+
+await writeFile("seneca.epub", epub);            // or Deno.writeFile, Bun.write…
+await writeFile("seneca.kepub.epub", toKepub(epub));
+```
+
+## Why another EPUB library?
+
+Quarto came out of specific needs in my own projects (like [instakobo](https://github.com/voidberg/instakobo)):
+
+- skip the table of contents, which for articles and newsletters is just noise
+- generate kepubs without relying on kepubify
+- work in the browser
+
+## Features
+
+- Valid EPUB3 (verified against [EPUBCheck](https://www.w3.org/publishing/epubcheck/) in CI)
+- Optional table of contents (`includeToc`)
+- Native kepub conversion (`toKepub`) — Kobo reading-location spans, no binary needed
+- In-memory: returns a `Uint8Array`, never touches the filesystem
+- Runtime-agnostic: Node, Deno, Bun, and the browser (Web APIs + [`fflate`](https://github.com/101arrowz/fflate))
+- Re-serializes messy HTML into well-formed XHTML for you
+- Downloads and embeds remote images so the book is self-contained
+- Modern **ESM-only** (Node ≥ 18; `require()`-able from CommonJS on Node ≥ 20.19 / 22)
+
+## Used by
+
+- [instakobo](https://github.com/voidberg/instakobo) — Read and annotate (and sync back) your Instapaper articles on your Kobo device
+- reSafari — Send webpages to your reMarkable tablet from Safari
+
+## Install
+
+```sh
+npm install @voidberg/quarto       # npm / pnpm / yarn
+deno add jsr:@voidberg/quarto      # Deno (JSR)
+```
+
+## API
+
+### `generateEpub(input): Promise<Uint8Array>`
+
+| Option              | Type                   | Default               | Notes |
+|---------------------|------------------------|-----------------------|-------|
+| `title`             | `string`               | —                     | Required. |
+| `chapters`          | `Chapter[]`            | —                     | Required, at least one. |
+| `author`            | `string \| string[]`   | —                     | One or many creators. |
+| `includeToc`        | `boolean`              | `true`                | `false` ⇒ no visible TOC page. |
+| `tocTitle`          | `string`               | `"Table of Contents"` | Heading on the TOC page. |
+| `cover`             | `string \| Uint8Array` | —                     | URL or raw bytes; generates a cover page. |
+| `coverFromLeadImage`| `boolean`              | `false`               | Promote a chapter's leading image to the cover (see below). |
+| `coverBackground`   | `string`               | reader default        | CSS colour filling the cover's letterbox bands. |
+| `language`          | `string`               | `"en"`                | BCP-47 tag. |
+| `css`               | `string \| false`      | bundled stylesheet    | `false` ships no CSS. |
+| `downloadImages`    | `boolean`              | `true`                | Embed remote `<img>` sources. |
+| `transformImage`    | `ImageTransform`       | —                     | Rewrite each image before embedding (see below). |
+| `transformCover`    | `CoverTransform`       | —                     | Compose/replace the cover before embedding (see below). |
+| `publisher`         | `string`               | —                     | |
+| `description`       | `string`               | —                     | |
+| `date`              | `string` (ISO-8601)    | —                     | Pass for reproducible builds. |
+| `id`                | `string`               | derived (stable UUID) | Unique book identifier. |
+| `fetch`             | `typeof fetch`         | global `fetch`        | Override for proxies/testing. |
+
+A **`Chapter`** is `{ title, html, excludeFromToc?, author?, insertTitle? }`. `html` is an HTML fragment — it does not need to be well-formed; Quarto parses and re-serializes it as valid XHTML. Set `insertTitle: false` to suppress the auto-generated `<h1>` heading and render only your markup.
+
+### `toKepub(epub: Uint8Array): Uint8Array`
+
+Converts an EPUB (such as the output of `generateEpub`) into a Kobo kepub: every content document is rewritten with `koboSpan` reading-location markers and Kobo's `book-columns` / `book-inner` wrappers. Write the result with a `.kepub.epub` extension. No `kepubify` binary required.
+
+### `DEFAULT_CSS: string`
+
+The bundled stylesheet, exported so you can extend rather than replace it.
+
+### `imageSize(bytes, mime): { width, height } | undefined`
+
+Reads an image's pixel dimensions straight from its header — no decoding, no native deps. Supports PNG, GIF and JPEG; returns `undefined` for anything else or malformed data. Handy inside a `transformCover` to make layout decisions.
+
+## Images & covers
+
+By default every `<img>` source (and the `cover`) is downloaded and embedded so the book is self-contained. Two hooks let you customize what gets stored:
+
+- **`transformImage(image)`** runs on each fetched image *before* the core-media-type check, so it can transcode an unsupported format (e.g. WebP/AVIF → PNG for older e-readers), resize, or return `null` to drop the image.
+- **`transformCover(cover, meta)`** runs after the cover source is downloaded and passed through `transformImage`. It's called **even when there's no cover source**, so you can compose a designed cover from `meta.title` / `meta.author` alone. Return `null` for no cover.
+
+Both receive/return `RawImage` (`{ data: Uint8Array; mime: string }`) and may be async.
+
+```ts
+import { generateEpub, imageSize, type CoverTransform } from "@voidberg/quarto";
+
+const brandCover: CoverTransform = (cover, meta) => {
+  if (cover && imageSize(cover.data, cover.mime)) return cover; // usable as-is
+  return renderCover(meta.title, meta.author);                 // your designer → RawImage
+};
+
+await generateEpub({
+  title: "Field Notes",
+  coverFromLeadImage: true,        // no cover? promote the article's leading image
+  coverBackground: "#f4f1ea",      // blend the letterbox bands into the artwork
+  transformCover: brandCover,
+  chapters: [{ title: "Field Notes", html }],
+});
+```
+
+`coverFromLeadImage` only promotes an image that appears **before any text** in the first chapter (and removes it from the body so it isn't shown twice); images that follow text are left in place.
+
+## Example: no table of contents
+
+```ts
+const epub = await generateEpub({
+  title: "A Single Essay",
+  includeToc: false,
+  chapters: [{ title: "Essay", html: essayHtml, excludeFromToc: true }],
+});
+```
+
+## Development
+
+```sh
+npm install
+npm test         # vitest
+npm run build    # tsc → dist (ESM + d.ts)
+npm run typecheck
+npm run validate # EPUBCheck (needs Java + EPUBCHECK_JAR)
+```
+
+EPUBCheck runs in CI against generated fixtures to guarantee spec compliance.
+
+## Thanks to
+
+- [epub-gen](https://github.com/cyrilis/epub-gen) and [epub-gen-memory](https://github.com/cpiber/epub-gen-memory) for inspiration.
+- [kepubify](https://github.com/pgaskin/kepubify) for documenting the kepub transform.
+- [epub-css-starter-kit](https://github.com/mattharrison/epub-css-starter-kit) for the styles.
+- [Freepik – Flaticon](https://www.flaticon.com/free-icons/book) for the logo.
+
+## License
+
+[MIT](./LICENSE) © Alexandru Badiu

package/dist/css.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Default EPUB stylesheet. Adapted from the public-domain
+ * epub-css-starter-kit (https://github.com/mattharrison/epub-css-starter-kit) —
+ * conservative defaults that render well across e-readers, Kobo included.
+ */
+export declare const DEFAULT_CSS: string;

package/dist/css.js

@@ -0,0 +1,109 @@
+/**
+ * Default EPUB stylesheet. Adapted from the public-domain
+ * epub-css-starter-kit (https://github.com/mattharrison/epub-css-starter-kit) —
+ * conservative defaults that render well across e-readers, Kobo included.
+ */
+export const DEFAULT_CSS = `@charset "UTF-8";
+
+html, body {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: serif;
+  line-height: 1.5;
+  text-align: justify;
+  padding: 0 1em;
+  widows: 2;
+  orphans: 2;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: sans-serif;
+  line-height: 1.2;
+  text-align: left;
+  page-break-after: avoid;
+  break-after: avoid;
+  -webkit-hyphens: none;
+  hyphens: none;
+}
+
+h1 {
+  font-size: 1.6em;
+  margin: 1em 0 0.6em;
+}
+
+h2 { font-size: 1.4em; }
+h3 { font-size: 1.2em; }
+
+p {
+  margin: 0;
+  text-indent: 1.2em;
+}
+
+p:first-of-type,
+h1 + p,
+h2 + p,
+h3 + p,
+blockquote p:first-child {
+  text-indent: 0;
+}
+
+a { color: inherit; text-decoration: underline; }
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+figure { margin: 1em 0; text-align: center; }
+figcaption { font-size: 0.85em; font-style: italic; text-align: center; }
+
+blockquote {
+  margin: 1em 1.5em;
+  font-style: italic;
+}
+
+pre, code, kbd, samp {
+  font-family: monospace;
+  white-space: pre-wrap;
+}
+
+pre {
+  font-size: 0.85em;
+  margin: 1em 0;
+  overflow-wrap: break-word;
+}
+
+hr {
+  border: none;
+  border-top: 1px solid currentColor;
+  margin: 1.5em auto;
+  width: 25%;
+  opacity: 0.4;
+}
+
+ul, ol { margin: 1em 0; padding-left: 1.5em; }
+
+table { border-collapse: collapse; margin: 1em 0; }
+th, td { border: 1px solid currentColor; padding: 0.3em 0.6em; }
+
+.quarto-title { text-align: left; }
+.quarto-author {
+  font-family: sans-serif;
+  font-size: 0.9em;
+  font-style: italic;
+  margin: 0 0 1.5em;
+}
+
+.quarto-cover {
+  margin: 0;
+  padding: 0;
+  text-align: center;
+  height: 100%;
+  page-break-after: always;
+}
+.quarto-cover img { max-width: 100%; max-height: 100%; }
+`;
+//# sourceMappingURL=css.js.map

package/dist/css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../src/css.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsGlC,CAAC"}

package/dist/epub.d.ts

@@ -0,0 +1,8 @@
+import type { EpubInput } from "./types.js";
+/**
+ * Generate a complete, valid EPUB3 publication in memory from HTML chapters.
+ *
+ * The returned bytes are a ready-to-write `.epub`. Pass the result to
+ * {@link toKepub} to produce a Kobo-optimised `.kepub.epub`.
+ */
+export declare function generateEpub(input: EpubInput): Promise<Uint8Array>;

package/dist/epub.js

@@ -0,0 +1,232 @@
+import { DEFAULT_CSS } from "./css.js";
+import { HtmlFragment } from "./html.js";
+import { embedImages, fetchImage } from "./images.js";
+import { buildNav, buildNcx, buildOpf, buildSvgCover, buildXhtml, CONTAINER_XML, } from "./opf.js";
+import { deterministicUuid, encodeUtf8, escapeXml, extFromMime, imageSize, isCoreImageType, } from "./util.js";
+import { zipEpub } from "./zip.js";
+/**
+ * Generate a complete, valid EPUB3 publication in memory from HTML chapters.
+ *
+ * The returned bytes are a ready-to-write `.epub`. Pass the result to
+ * {@link toKepub} to produce a Kobo-optimised `.kepub.epub`.
+ */
+export async function generateEpub(input) {
+    if (!input.chapters?.length) {
+        throw new Error("generateEpub: at least one chapter is required.");
+    }
+    const opts = resolveOptions(input);
+    const authors = normalizeAuthors(input.author);
+    const id = input.id ?? deterministicUuid(`${input.title} ${authors.join(",")}`);
+    const ctx = { files: {}, manifest: [], spine: [] };
+    ctx.files["META-INF/container.xml"] = encodeUtf8(CONTAINER_XML);
+    addStylesheet(ctx, opts.css);
+    const fragments = input.chapters.map((ch) => HtmlFragment.parse(ch.html));
+    // No explicit cover? Optionally promote the first chapter's lead image.
+    const coverSource = input.cover ?? (opts.coverFromLeadImage ? fragments[0].extractLeadImage() : undefined);
+    const cover = await addCover(ctx, coverSource, input.title, authors, opts);
+    await embedChapterImages(ctx, fragments, opts);
+    const navEntries = addChapters(ctx, input.chapters, fragments, opts);
+    const ncxId = addNavigation(ctx, input.chapters, navEntries, opts, cover.hasCoverPage, id, input.title);
+    // EPUB2 guide (cover + reading start) for readers that rely on it.
+    const guide = [];
+    if (cover.hasCoverPage)
+        guide.push({ type: "cover", href: "text/cover.xhtml", title: "Cover" });
+    guide.push({ type: "text", href: "text/chapter-1.xhtml", title: "Start" });
+    ctx.files["EPUB/content.opf"] = encodeUtf8(buildOpf({
+        id,
+        title: input.title,
+        authors,
+        language: opts.language,
+        publisher: input.publisher,
+        description: input.description,
+        date: input.date,
+        coverImageId: cover.coverImageId,
+    }, ctx.manifest, ctx.spine, { ncxId, guide }));
+    return zipEpub(ctx.files);
+}
+function resolveOptions(input) {
+    const css = input.css === false ? undefined : (input.css ?? DEFAULT_CSS);
+    return {
+        language: input.language ?? "en",
+        includeToc: input.includeToc ?? true,
+        downloadImages: input.downloadImages ?? true,
+        tocTitle: input.tocTitle ?? "Table of Contents",
+        fetcher: input.fetch ?? globalThis.fetch,
+        coverFromLeadImage: input.coverFromLeadImage ?? false,
+        coverBackground: input.coverBackground,
+        transformImage: input.transformImage,
+        transformCover: input.transformCover,
+        css,
+        cssHref: css ? "../style.css" : undefined,
+    };
+}
+/** Write the stylesheet (when enabled) and register it in the manifest. */
+function addStylesheet(ctx, css) {
+    if (!css)
+        return;
+    ctx.files["EPUB/style.css"] = encodeUtf8(css);
+    ctx.manifest.push({ id: "css", href: "style.css", mediaType: "text/css" });
+}
+/**
+ * Resolve and embed the cover. The source image (if any) is downloaded and run
+ * through {@link ResolvedOptions.transformImage}; then {@link ResolvedOptions.transformCover}
+ * gets the final say (even with no source image, so it can compose one from
+ * metadata). The result is embedded as the cover image + a dedicated cover page
+ * (SVG-wrapped for reliable scaling) at the front of the spine. Any failure is
+ * swallowed — a missing cover must never abort the build.
+ */
+async function addCover(ctx, coverSource, title, authors, opts) {
+    // 1. Download + transcode the source image, if there is one.
+    let img = null;
+    if (coverSource) {
+        try {
+            const fetched = await fetchImage(coverSource, opts.fetcher);
+            const transformed = opts.transformImage ? await opts.transformImage(fetched) : fetched;
+            // Only keep a cover whose type EPUB can carry without a fallback.
+            if (transformed && isCoreImageType(transformed.mime))
+                img = transformed;
+        }
+        catch {
+            // Leave img null; transformCover may still compose one.
+        }
+    }
+    // 2. Let the caller shape the final cover (compose with title, normalise, …).
+    if (opts.transformCover) {
+        try {
+            img = await opts.transformCover(img, { title, author: authors[0] });
+        }
+        catch {
+            // Fall back to the un-composed image (or none) rather than aborting.
+        }
+    }
+    if (!img)
+        return { hasCoverPage: false };
+    // 3. Embed the cover image + cover page.
+    const coverPath = `images/cover.${extFromMime(img.mime)}`;
+    ctx.files[`EPUB/${coverPath}`] = img.data;
+    ctx.manifest.push({
+        id: "cover-image",
+        href: coverPath,
+        mediaType: img.mime,
+        properties: "cover-image",
+    });
+    // Prefer an SVG-wrapped cover (fills + centers reliably on e-readers); fall
+    // back to a plain <img> only when we can't read the image's dimensions.
+    const coverHref = `../${coverPath}`;
+    const dims = imageSize(img.data, img.mime);
+    if (dims) {
+        ctx.files["EPUB/text/cover.xhtml"] = encodeUtf8(buildSvgCover({
+            title,
+            language: opts.language,
+            imageHref: coverHref,
+            width: dims.width,
+            height: dims.height,
+            background: opts.coverBackground,
+        }));
+        ctx.manifest.push({
+            id: "cover-page",
+            href: "text/cover.xhtml",
+            mediaType: "application/xhtml+xml",
+            properties: "svg",
+        });
+    }
+    else {
+        const coverBody = `    <div class="quarto-cover" epub:type="cover">\n      <img src="${coverHref}" alt="${escapeXml(title)}"/>\n    </div>`;
+        ctx.files["EPUB/text/cover.xhtml"] = encodeUtf8(buildXhtml({ title, language: opts.language, cssHref: opts.cssHref, bodyHtml: coverBody }));
+        ctx.manifest.push({
+            id: "cover-page",
+            href: "text/cover.xhtml",
+            mediaType: "application/xhtml+xml",
+        });
+    }
+    ctx.spine.push("cover-page");
+    return { coverImageId: "cover-image", hasCoverPage: true };
+}
+/**
+ * Resolve the images referenced by the chapter fragments. When downloading,
+ * fetch and embed them (rewriting each `<img>` to its in-package path); when not,
+ * drop external references so only self-contained `data:` images survive.
+ */
+async function embedChapterImages(ctx, fragments, opts) {
+    if (!opts.downloadImages) {
+        for (const f of fragments)
+            f.stripExternalImages();
+        return;
+    }
+    const allUrls = fragments.flatMap((f) => f.imageSources());
+    const { images, rewrites } = await embedImages(allUrls, opts.fetcher, opts.transformImage);
+    // Chapter files live in EPUB/text/, images in EPUB/images/.
+    const chapterRewrites = new Map();
+    for (const [url, path] of rewrites)
+        chapterRewrites.set(url, `../${path}`);
+    for (const f of fragments)
+        f.resolveImages(chapterRewrites, true);
+    for (const img of images) {
+        ctx.files[`EPUB/${img.path}`] = img.data;
+        ctx.manifest.push({ id: img.id, href: img.path, mediaType: img.mime });
+    }
+}
+/** Write one XHTML document per chapter; return the TOC entries to surface. */
+function addChapters(ctx, chapters, fragments, opts) {
+    const navEntries = [];
+    chapters.forEach((chapter, i) => {
+        const fileId = `chapter-${i + 1}`;
+        const href = `text/${fileId}.xhtml`;
+        const heading = chapter.insertTitle === false ? "" : titleBlock(chapter.title, chapter.author);
+        const bodyHtml = `${heading}${fragments[i].serialize()}`;
+        ctx.files[`EPUB/${href}`] = encodeUtf8(buildXhtml({
+            title: chapter.title,
+            language: opts.language,
+            cssHref: opts.cssHref,
+            bodyHtml: `    ${bodyHtml}`,
+        }));
+        ctx.manifest.push({ id: fileId, href, mediaType: "application/xhtml+xml" });
+        ctx.spine.push(fileId);
+        if (!chapter.excludeFromToc)
+            navEntries.push({ href, title: chapter.title });
+    });
+    return navEntries;
+}
+/**
+ * Emit the navigation document (always — EPUB3 requires one) plus, for a visible
+ * TOC, the spine entry and NCX. Returns the NCX id, or `undefined` when hidden.
+ */
+function addNavigation(ctx, chapters, navEntries, opts, hasCoverPage, id, title) {
+    // A visible TOC requires includeToc AND at least one non-excluded chapter.
+    const showToc = opts.includeToc && navEntries.length > 0;
+    // The nav doc must reference content even when hidden, so fall back to all chapters.
+    const navList = navEntries.length
+        ? navEntries
+        : chapters.map((ch, i) => ({ href: `text/chapter-${i + 1}.xhtml`, title: ch.title }));
+    // Landmarks let readers jump to the cover / reading start.
+    const landmarks = [];
+    if (hasCoverPage)
+        landmarks.push({ type: "cover", href: "text/cover.xhtml", title: "Cover" });
+    landmarks.push({ type: "bodymatter", href: "text/chapter-1.xhtml", title: "Start" });
+    if (showToc)
+        landmarks.push({ type: "toc", href: "nav.xhtml", title: opts.tocTitle });
+    ctx.files["EPUB/nav.xhtml"] = encodeUtf8(buildNav(opts.tocTitle, opts.language, navList, !showToc, landmarks));
+    ctx.manifest.push({
+        id: "nav",
+        href: "nav.xhtml",
+        mediaType: "application/xhtml+xml",
+        properties: "nav",
+    });
+    if (!showToc)
+        return undefined;
+    // Reading order: cover (if any) → TOC page → chapters.
+    ctx.spine.splice(hasCoverPage ? 1 : 0, 0, "nav");
+    ctx.files["EPUB/toc.ncx"] = encodeUtf8(buildNcx(id, title, navList));
+    ctx.manifest.push({ id: "ncx", href: "toc.ncx", mediaType: "application/x-dtbncx+xml" });
+    return "ncx";
+}
+function normalizeAuthors(author) {
+    if (!author)
+        return [];
+    return (Array.isArray(author) ? author : [author]).filter((a) => a.trim().length > 0);
+}
+function titleBlock(title, author) {
+    const authorLine = author ? `\n    <p class="quarto-author">${escapeXml(author)}</p>` : "";
+    return `<h1 class="quarto-title">${escapeXml(title)}</h1>${authorLine}\n    `;
+}
+//# sourceMappingURL=epub.js.map

package/dist/epub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epub.js","sourceRoot":"","sources":["../src/epub.ts"],"names":[],"mappings":"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"}

package/dist/html.d.ts

@@ -0,0 +1,54 @@
+/** A parsed HTML fragment ready to inspect, mutate and serialize. */
+export declare class HtmlFragment {
+    private readonly nodes;
+    private constructor();
+    static parse(html: string): HtmlFragment;
+    /** Collect the `src` of every `<img>` (in document order). */
+    imageSources(): string[];
+    /**
+     * Walk every `<img>` (depth-first, splice-safe) and apply a decision based on
+     * its `src`:
+     *  - a string  → rewrite `src` to it (and ensure `alt`);
+     *  - `null`    → remove the element;
+     *  - `undefined` → leave it (and ensure `alt`).
+     */
+    private transformImages;
+    /**
+     * Resolve every `<img>` against an embedded-image map (original src → in-package
+     * path). Matched images are rewritten and given alt text. When
+     * `stripUnresolved` is set, images that were not embedded (failed downloads,
+     * unsupported sources) are removed entirely so the EPUB has no dangling
+     * foreign resources — EPUBCheck rejects those.
+     */
+    resolveImages(map: Map<string, string>, stripUnresolved: boolean): void;
+    /**
+     * Remove every `<img>` that references something outside the container — i.e.
+     * anything that isn't an inline `data:` URI (remote URLs and relative paths
+     * alike). Used when image downloading is disabled: only self-contained `data:`
+     * images can survive, so this keeps the EPUB valid instead of leaving dangling
+     * references EPUBCheck rejects.
+     */
+    stripExternalImages(): void;
+    /**
+     * If the fragment's first meaningful content is an image (i.e. no text
+     * precedes it), remove that image and return its `src` — for promoting an
+     * article's lead image to the cover. Returns `undefined` when text comes first,
+     * so we never pull an image out of the middle of the prose.
+     */
+    extractLeadImage(): string | undefined;
+    serialize(): string;
+}
+/**
+ * Transform an XHTML content document into its Kobo (kepub) form, mirroring
+ * kepubify:
+ *
+ *  - every text run inside a block element is wrapped in
+ *    `<span class="koboSpan" id="kobo.{segment}.{fragment}">` so the firmware can
+ *    track reading position and anchor highlights precisely;
+ *  - the body content is wrapped in `<div id="book-columns"><div id="book-inner">`
+ *    which Kobo relies on for pagination and justification.
+ *
+ * Returns a complete XHTML document string. If the input has no parseable
+ * `<body>`, it is returned unchanged.
+ */
+export declare function kepubifyXhtml(documentHtml: string): string;