@leopiccionia/epub-builder 0.0.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Leonardo Piccioni de Almeida
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,67 @@
+# Epub Builder
+
+A non-opinionated EPUB builder for reflowable content
+
+## Install
+
+```bash
+npm install @leopiccionia/epub-builder
+```
+
+## Features
+
+Generates EPUBs that are fully compatible with [EPUB 3.3](https://www.w3.org/TR/epub-33/) standard, with some additional compatibility with EPUB 2.
+
+It provides a declarative API, for easy configuration, and writes for you:
+
+- a machine-readable table of contents
+- accessibility landmarks
+- all the boring EPUB ceremony
+
+## Usage example
+
+```js
+import { EpubBuilder } from '@leopiccionia/epub-builder'
+
+const ebook = await EpubBuilder.init({
+  // Some book metadata
+  meta: {
+    title: 'An example book',
+    creators: [
+      { name: 'John Doe' },
+    ],
+  },
+  // The reading order
+  spine: [
+    'cover.xhtml',
+    'toc.xhtml',
+    'chapter-1.xhtml',
+  ],
+  // The table of contents
+  toc: [
+    { href: 'toc.xhtml', text: 'Table of contents' },
+    { href: 'chapter-1.xhtml', text: 'Chapter 1', children: [
+      { href: 'chapter-1.xhtml#introduction', text: 'Introduction' },
+      { href: 'chapter-1.xhtml#conclusion', text: 'Conclusion' },
+    ] },
+  ],
+  // Some accessibility landmarks
+  landmarks: {
+    toc: 'toc.xhtml', // The table of contents
+    bodymatter: 'chapter-1.xhtml', // The start of content
+  },
+})
+
+// Add the ebook files
+await ebook.addTextFile('toc.xhtml', '...')
+await ebook.addTextFile('chapter-1.xhtml', '...')
+await ebook.addTextFile('cover.xhtml', '...')
+await ebook.copyFile('cover.png', 'PATH TO THE IMAGE')
+
+// Returns the ZIP file
+const blob = await ebook.seal()
+```
+
+## Related projects
+
+- [Pubmark](https://github.com/leopiccionia/pubmark) - A Markdown to EPUB converter powered by this package

package/dist/index.d.mts

@@ -0,0 +1,309 @@
+/**
+ * An EpubBuilder locale
+ */
+interface Locale {
+    /**
+     * Translation of "Start of content"
+     */
+    bodymatter: string;
+    /**
+     * Translation of "Guide"
+     */
+    landmarks: string;
+    /**
+     * Translation of "List of images"
+     */
+    loi: string;
+    /**
+     * Translation of "Table of contents"
+     */
+    toc: string;
+    /**
+     * Translation of the name of another landmark
+     */
+    [landmark: string]: string | undefined;
+}
+
+/**
+ * An ebook set of metadata
+ */
+interface EbookMeta {
+    /**
+     * The book title
+     */
+    title: string;
+    /**
+     * The book subtitle
+     */
+    subtitle: string;
+    /**
+     * The book description
+     */
+    description: string;
+    /**
+     * The reading direction (left-to-right, right-to-left, or auto)
+     */
+    direction: 'ltr' | 'rtl' | 'auto';
+    /**
+     * The language tag
+     * @see https://www.w3.org/International/articles/language-tags/
+     */
+    language: string;
+    /**
+     * The book publishing date, in `YYYY-MM-DD` format
+     */
+    date: string;
+    /**
+     * The book publisher
+     */
+    publisher: {
+        /**
+         * The publisher type
+         */
+        type?: 'Organization' | 'Person';
+        /**
+         * The publisher name
+         */
+        name: string;
+    };
+    /**
+     * A list of contributors to the book
+     */
+    creators: Array<{
+        /**
+         * The contributor's name
+         */
+        name: string;
+        /**
+         * The contributor's role MARC code
+         * @see https://www.loc.gov/marc/relators/relaterm.html
+         */
+        role: string;
+        /**
+         * The contributor's type
+         */
+        type?: 'Organization' | 'Person';
+        /**
+         * Normalized form of contributor's name
+         */
+        'file as'?: string;
+        /**
+         * Contributor's name in alternative scripts or languages
+         */
+        alternate?: {
+            [language: string]: string;
+        };
+    }>;
+    /**
+     * The book subjects
+     */
+    subjects: Array<{
+        /**
+         * The human-readable subject description
+         */
+        label: string;
+        /**
+         * The authority that issued the subject term
+         */
+        authority: string;
+        /**
+         * The machine-readable subject term
+         */
+        term: number | string;
+    }>;
+    /**
+     * Unique identifiers
+     */
+    ids: {
+        /**
+         * An ISBN (International Standard Book Number) identifier
+         */
+        isbn?: string;
+        /**
+         * A DOI (Digital Object Identifier) identifier
+         */
+        doi?: string;
+        /**
+         * An UUID (Universally Unique Identifier) v4-compatible identifier
+         */
+        uuid?: string;
+    };
+}
+/**
+ * An EPUB landmarks definition
+ */
+interface Landmarks {
+    /**
+     * The start of content
+     */
+    bodymatter: string;
+    /**
+     * The table of contents
+     */
+    toc: string;
+    /**
+     * The list of images
+     */
+    loi?: string;
+    /**
+     * Other landmarks (may not be supported by all readers)
+     */
+    [landmark: string]: string | undefined;
+}
+/**
+ * A link in the table of contents
+ */
+type TocEntry = {
+    text: string;
+    href: string;
+    children?: TocEntry[];
+};
+/**
+ * An EPUB builder config
+ */
+interface EpubBuilderConfig {
+    /**
+     * The ebook landmarks
+     */
+    landmarks: Landmarks;
+    /**
+     * The builder locale
+     */
+    locale: Locale;
+    /**
+     * The ebook metadata
+     */
+    meta: EbookMeta;
+    /**
+     * The ebook spine
+     */
+    spine: string[];
+    /**
+     * The table of contents
+     */
+    toc: TocEntry[];
+}
+interface EpubBuilderPartialConfig {
+    /**
+    * The ebook landmarks
+    */
+    landmarks: Landmarks;
+    /**
+     * The builder locale
+     */
+    locale?: Locale;
+    /**
+     * The ebook metadata
+     */
+    meta?: Partial<EbookMeta>;
+    /**
+     * The ebook spine
+     */
+    spine: string[];
+    /**
+     * The table of contents
+     */
+    toc: TocEntry[];
+}
+/**
+ * Fills the user-provided config with default values
+ * @param partialConfig The partial config
+ * @returns The completely-filled config
+ */
+declare function populateConfig(partialConfig: EpubBuilderPartialConfig): EpubBuilderConfig;
+
+/**
+ * A resource manifest property
+ * @see https://www.w3.org/TR/epub-33/#app-item-properties-vocab
+ */
+type ResourceProperty = 'cover-image' | 'mathml' | 'nav' | 'remote-resources' | 'scripted' | 'svg' | 'switch';
+/**
+ * A resource representing a file asset
+ */
+interface Resource {
+    /**
+     * The resource's path
+     */
+    href: string;
+    /**
+     * The resource's MIME type
+     */
+    mime: string;
+    /**
+     * The resource's manifest properties
+     */
+    properties: ResourceProperty[];
+}
+
+/**
+ * A non-opinionated EPUB builder
+ */
+declare class EpubBuilder {
+    #private;
+    /**
+     * The builder config
+     */
+    config: EpubBuilderConfig;
+    /**
+     * The list of registered EPUB resources
+     */
+    readonly resources: Resource[];
+    /**
+     * The EPUB ZIP container
+     */
+    private zip;
+    /**
+     * The private constructor
+     * @param config The builder config
+     */
+    private constructor();
+    /**
+     * Registers a binary-encoded file
+     * @param href The resource's path inside the EPUB container
+     * @param content The resource's binary-encoded content
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    addBinaryFile(href: string, content: Blob, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Registers a text-encoded file
+     * @param href The resource's path inside the EPUB container
+     * @param content The resource's text-encoded content
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    addTextFile(href: string, content: string, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Reads a file and registers it as a resource
+     * @param href The resource's path inside the EPUB container
+     * @param path The file's physical path
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    copyFile(href: string, path: string, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Returns an empty `EpubBuilder`
+     * @param partialConfig The builder config
+     */
+    static init(partialConfig: EpubBuilderPartialConfig): Promise<EpubBuilder>;
+    /**
+     * Closes the ZIP container, returning its content
+     * @returns The EPUB binary data
+     */
+    seal(): Promise<Blob>;
+}
+
+/**
+ * Detects the MIME type of a certain file
+ * @param path The file path
+ * @returns The MIME type of the file, or `undefined` if not recognized
+ */
+declare function getMimeType(path: string): string | undefined;
+/**
+ * Detects if the MIME type is an EPUB core media type
+ * @param mimeType The MIME type
+ * @returns Whether the media type is recognized and a core media type
+ */
+declare function isCoreMediaType(mimeType: string | undefined): boolean;
+
+export { type EbookMeta, EpubBuilder, type EpubBuilderConfig, type EpubBuilderPartialConfig, type Landmarks, type Locale, type Resource, type ResourceProperty, type TocEntry, getMimeType, isCoreMediaType, populateConfig };

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * An EpubBuilder locale
+ */
+interface Locale {
+    /**
+     * Translation of "Start of content"
+     */
+    bodymatter: string;
+    /**
+     * Translation of "Guide"
+     */
+    landmarks: string;
+    /**
+     * Translation of "List of images"
+     */
+    loi: string;
+    /**
+     * Translation of "Table of contents"
+     */
+    toc: string;
+    /**
+     * Translation of the name of another landmark
+     */
+    [landmark: string]: string | undefined;
+}
+
+/**
+ * An ebook set of metadata
+ */
+interface EbookMeta {
+    /**
+     * The book title
+     */
+    title: string;
+    /**
+     * The book subtitle
+     */
+    subtitle: string;
+    /**
+     * The book description
+     */
+    description: string;
+    /**
+     * The reading direction (left-to-right, right-to-left, or auto)
+     */
+    direction: 'ltr' | 'rtl' | 'auto';
+    /**
+     * The language tag
+     * @see https://www.w3.org/International/articles/language-tags/
+     */
+    language: string;
+    /**
+     * The book publishing date, in `YYYY-MM-DD` format
+     */
+    date: string;
+    /**
+     * The book publisher
+     */
+    publisher: {
+        /**
+         * The publisher type
+         */
+        type?: 'Organization' | 'Person';
+        /**
+         * The publisher name
+         */
+        name: string;
+    };
+    /**
+     * A list of contributors to the book
+     */
+    creators: Array<{
+        /**
+         * The contributor's name
+         */
+        name: string;
+        /**
+         * The contributor's role MARC code
+         * @see https://www.loc.gov/marc/relators/relaterm.html
+         */
+        role: string;
+        /**
+         * The contributor's type
+         */
+        type?: 'Organization' | 'Person';
+        /**
+         * Normalized form of contributor's name
+         */
+        'file as'?: string;
+        /**
+         * Contributor's name in alternative scripts or languages
+         */
+        alternate?: {
+            [language: string]: string;
+        };
+    }>;
+    /**
+     * The book subjects
+     */
+    subjects: Array<{
+        /**
+         * The human-readable subject description
+         */
+        label: string;
+        /**
+         * The authority that issued the subject term
+         */
+        authority: string;
+        /**
+         * The machine-readable subject term
+         */
+        term: number | string;
+    }>;
+    /**
+     * Unique identifiers
+     */
+    ids: {
+        /**
+         * An ISBN (International Standard Book Number) identifier
+         */
+        isbn?: string;
+        /**
+         * A DOI (Digital Object Identifier) identifier
+         */
+        doi?: string;
+        /**
+         * An UUID (Universally Unique Identifier) v4-compatible identifier
+         */
+        uuid?: string;
+    };
+}
+/**
+ * An EPUB landmarks definition
+ */
+interface Landmarks {
+    /**
+     * The start of content
+     */
+    bodymatter: string;
+    /**
+     * The table of contents
+     */
+    toc: string;
+    /**
+     * The list of images
+     */
+    loi?: string;
+    /**
+     * Other landmarks (may not be supported by all readers)
+     */
+    [landmark: string]: string | undefined;
+}
+/**
+ * A link in the table of contents
+ */
+type TocEntry = {
+    text: string;
+    href: string;
+    children?: TocEntry[];
+};
+/**
+ * An EPUB builder config
+ */
+interface EpubBuilderConfig {
+    /**
+     * The ebook landmarks
+     */
+    landmarks: Landmarks;
+    /**
+     * The builder locale
+     */
+    locale: Locale;
+    /**
+     * The ebook metadata
+     */
+    meta: EbookMeta;
+    /**
+     * The ebook spine
+     */
+    spine: string[];
+    /**
+     * The table of contents
+     */
+    toc: TocEntry[];
+}
+interface EpubBuilderPartialConfig {
+    /**
+    * The ebook landmarks
+    */
+    landmarks: Landmarks;
+    /**
+     * The builder locale
+     */
+    locale?: Locale;
+    /**
+     * The ebook metadata
+     */
+    meta?: Partial<EbookMeta>;
+    /**
+     * The ebook spine
+     */
+    spine: string[];
+    /**
+     * The table of contents
+     */
+    toc: TocEntry[];
+}
+/**
+ * Fills the user-provided config with default values
+ * @param partialConfig The partial config
+ * @returns The completely-filled config
+ */
+declare function populateConfig(partialConfig: EpubBuilderPartialConfig): EpubBuilderConfig;
+
+/**
+ * A resource manifest property
+ * @see https://www.w3.org/TR/epub-33/#app-item-properties-vocab
+ */
+type ResourceProperty = 'cover-image' | 'mathml' | 'nav' | 'remote-resources' | 'scripted' | 'svg' | 'switch';
+/**
+ * A resource representing a file asset
+ */
+interface Resource {
+    /**
+     * The resource's path
+     */
+    href: string;
+    /**
+     * The resource's MIME type
+     */
+    mime: string;
+    /**
+     * The resource's manifest properties
+     */
+    properties: ResourceProperty[];
+}
+
+/**
+ * A non-opinionated EPUB builder
+ */
+declare class EpubBuilder {
+    #private;
+    /**
+     * The builder config
+     */
+    config: EpubBuilderConfig;
+    /**
+     * The list of registered EPUB resources
+     */
+    readonly resources: Resource[];
+    /**
+     * The EPUB ZIP container
+     */
+    private zip;
+    /**
+     * The private constructor
+     * @param config The builder config
+     */
+    private constructor();
+    /**
+     * Registers a binary-encoded file
+     * @param href The resource's path inside the EPUB container
+     * @param content The resource's binary-encoded content
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    addBinaryFile(href: string, content: Blob, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Registers a text-encoded file
+     * @param href The resource's path inside the EPUB container
+     * @param content The resource's text-encoded content
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    addTextFile(href: string, content: string, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Reads a file and registers it as a resource
+     * @param href The resource's path inside the EPUB container
+     * @param path The file's physical path
+     * @param properties The resource's manifest properties
+     * @returns The registered resource
+     */
+    copyFile(href: string, path: string, properties?: ResourceProperty[]): Promise<Resource>;
+    /**
+     * Returns an empty `EpubBuilder`
+     * @param partialConfig The builder config
+     */
+    static init(partialConfig: EpubBuilderPartialConfig): Promise<EpubBuilder>;
+    /**
+     * Closes the ZIP container, returning its content
+     * @returns The EPUB binary data
+     */
+    seal(): Promise<Blob>;
+}
+
+/**
+ * Detects the MIME type of a certain file
+ * @param path The file path
+ * @returns The MIME type of the file, or `undefined` if not recognized
+ */
+declare function getMimeType(path: string): string | undefined;
+/**
+ * Detects if the MIME type is an EPUB core media type
+ * @param mimeType The MIME type
+ * @returns Whether the media type is recognized and a core media type
+ */
+declare function isCoreMediaType(mimeType: string | undefined): boolean;
+
+export { type EbookMeta, EpubBuilder, type EpubBuilderConfig, type EpubBuilderPartialConfig, type Landmarks, type Locale, type Resource, type ResourceProperty, type TocEntry, getMimeType, isCoreMediaType, populateConfig };

package/dist/index.mjs

@@ -0,0 +1,458 @@
+import { u } from 'unist-builder';
+import { x } from 'xastscript';
+import { toXml } from 'xast-util-to-xml';
+import { v4 } from '@lukeed/uuid/secure';
+import { defu } from 'defu';
+import mime from 'mime';
+import { readFile } from 'node:fs/promises';
+import { BlobWriter, ZipWriter, BlobReader, TextReader } from '@zip.js/zip.js';
+
+function stringifyXml(tree) {
+  return toXml(tree, {
+    closeEmptyElements: true
+  });
+}
+
+function generateAppleDisplayOptionsXml(resources) {
+  const hasEmbeddedFonts = resources.some((resource) => {
+    return resource.mime.startsWith("font/");
+  });
+  const hasInteractiveContent = resources.some((resource) => {
+    return resource.mime === "application/javascript" || resource.properties.includes("scripted");
+  });
+  const tree = x(null, [
+    u("instruction", { name: "xml" }, 'version="1.0" encoding="utf-8"'),
+    x("display_options", [
+      x("platform", { name: "*" }, [
+        x("option", { name: "specified-fonts" }, String(hasEmbeddedFonts)),
+        x("option", { name: "interactive" }, String(hasInteractiveContent))
+      ])
+    ])
+  ]);
+  return stringifyXml(tree);
+}
+
+const bodymatter = "Start of content";
+const landmarks = "Guide";
+const loi = "List of images";
+const toc = "Table of Contents";
+const EN = {
+	bodymatter: bodymatter,
+	landmarks: landmarks,
+	loi: loi,
+	toc: toc
+};
+
+function populateConfig(partialConfig) {
+  return defu(partialConfig, {
+    locale: EN,
+    meta: {
+      title: "EPUB",
+      subtitle: "",
+      description: "",
+      direction: "ltr",
+      language: "en",
+      date: "",
+      publisher: {
+        type: "Organization",
+        name: ""
+      },
+      creators: [],
+      subjects: [],
+      ids: {
+        uuid: v4()
+      }
+    }
+  });
+}
+
+function generateContainerXml() {
+  const tree = x(null, [
+    u("instruction", { name: "xml" }, 'version="1.0" encoding="utf-8"'),
+    x("container", { version: "1.0", xmlns: "urn:oasis:names:tc:opendocument:xmlns:container" }, [
+      x("rootfiles", [
+        x("rootfile", { "full-path": "OEBPS/content.opf", "media-type": "application/oebps-package+xml" })
+      ])
+    ])
+  ]);
+  return stringifyXml(tree);
+}
+
+function generateGuide(landmarks, locale) {
+  return x("guide", [
+    x("reference", { href: landmarks.toc, title: locale.toc, type: "toc" })
+  ]);
+}
+
+function generateItemId(path) {
+  return path.replaceAll(/\W/g, "-");
+}
+
+function generateManifest(resources) {
+  return x("manifest", resources.map(({ href, mime, properties }) => x("item", {
+    href,
+    id: generateItemId(href),
+    "media-type": mime,
+    properties: properties.length > 0 ? properties.join(" ") : undefined
+  })));
+}
+
+const PUB_ID = "pub-id";
+function generateCreators(meta) {
+  return meta.creators.flatMap((creator, index) => {
+    const id = `creators-${index + 1}`;
+    const dcTag = ["aut", "dub"].includes(creator.role) ? "dc:creator" : "dc:contributor";
+    const creatorMeta = [
+      x(dcTag, { id }, creator.name),
+      x("meta", { refines: `#${id}`, property: "role", scheme: "marc:relators" }, creator.role)
+    ];
+    if (creator["file as"]) {
+      creatorMeta.push(
+        x("meta", { refines: `#${id}`, property: "file-as" }, creator["file as"])
+      );
+    }
+    if (creator.alternate) {
+      for (const [lang, alias] of Object.entries(creator.alternate)) {
+        x("meta", { refines: `#${id}`, property: "alternate-script", "xml:lang": lang }, alias);
+      }
+    }
+    return creatorMeta;
+  });
+}
+function generateSubjects(meta) {
+  return meta.subjects.flatMap((subject, index) => {
+    const id = `subject-${index + 1}`;
+    return [
+      x("dc:subject", { id }, subject.label),
+      x("meta", { refines: `#${id}`, property: "authority" }, subject.authority),
+      x("meta", { refines: `#${id}`, property: "term" }, subject.term)
+    ];
+  });
+}
+function generateMetadata(meta, cover) {
+  const { id: pubId, onix } = getUniqueIdentifier(meta);
+  return x("metadata", { "xmlns:dc": "http://purl.org/dc/elements/1.1/", "xmlns:opf": "http://www.idpf.org/2007/opf" }, [
+    x("dc:identifier", { id: PUB_ID }, pubId),
+    x("dc:title", { id: "title" }, meta.title),
+    meta.subtitle ? x(null, [
+      x("dc:title", { id: "subtitle" }, meta.subtitle),
+      x("meta", { refines: "#subtitle", property: "title-type" }, "subtitle")
+    ]) : null,
+    meta.description ? x("dc:description", meta.description) : null,
+    meta.publisher.name ? x("dc:publisher", meta.publisher.name) : null,
+    meta.date ? x("dc:date", meta.date) : null,
+    x("dc:language", meta.language),
+    x("meta", { property: "dcterms:modified" }, getTimestamp()),
+    x("meta", { refines: `#${PUB_ID}`, property: "identifier-type", scheme: "onix:codelist5" }, onix),
+    cover && x("meta", { name: "cover", content: cover.href }),
+    ...generateCreators(meta),
+    ...generateSubjects(meta)
+  ]);
+}
+function getTimestamp() {
+  const isoString = (/* @__PURE__ */ new Date()).toISOString();
+  return isoString.slice(0, 19) + "Z";
+}
+function getUniqueIdentifier(meta) {
+  const { doi, isbn, uuid } = meta.ids;
+  if (isbn) {
+    const onix = isbn.length > 10 ? "15" : "02";
+    return { id: `urn:isbn:${isbn}`, onix };
+  } else if (doi) {
+    return { id: `urn:doi:${doi}`, onix: "06" };
+  } else {
+    return { id: `urn:uuid:${uuid}`, onix: "01" };
+  }
+}
+
+function generateSpine(meta, spine) {
+  return x(
+    "spine",
+    { "page-progression-direction": meta.direction, toc: "toc-ncx" },
+    spine.map((href) => x("itemref", {
+      idref: generateItemId(href),
+      linear: "yes"
+    }))
+  );
+}
+
+function generateContentOpf(config, resources) {
+  const { landmarks, locale, meta, spine } = config;
+  const cover = resources.find((resource) => resource.properties.includes("cover-image"));
+  const tree = x(null, [
+    u("instruction", { name: "xml" }, 'version="1.0" encoding="utf-8"'),
+    x("package", {
+      dir: meta.direction,
+      "unique-identifier": PUB_ID,
+      version: "3.0",
+      "xml:lang": meta.language,
+      xmlns: "http://www.idpf.org/2007/opf"
+    }, [
+      generateMetadata(meta, cover),
+      generateManifest(resources),
+      generateSpine(meta, spine),
+      generateGuide(landmarks, locale)
+    ])
+  ]);
+  return stringifyXml(tree);
+}
+
+function generateLandmarks(landmarks, locale) {
+  return x(
+    "ol",
+    Object.entries(landmarks).map(([landmark, href]) => x("li", [
+      x("a", { "epub:type": landmark, "href": href }, locale[landmark] ?? landmark)
+    ]))
+  );
+}
+function generateTocList(entries) {
+  return x(
+    "ol",
+    entries.map(({ children, href, text }) => x("li", [
+      x("a", { href }, text),
+      children && children.length > 0 ? generateTocList(children) : null
+    ]))
+  );
+}
+function generateNavXhtml(config) {
+  const { landmarks, locale, meta, toc } = config;
+  const tree = x("html", {
+    dir: meta.direction,
+    lang: meta.language,
+    "xml:lang": meta.language,
+    xmlns: "http://www.w3.org/1999/xhtml",
+    "xmlns:epub": "http://www.idpf.org/2007/ops"
+  }, [
+    x("head", [
+      x("meta", { charset: "UTF-8" }),
+      x("title", meta.title)
+    ]),
+    x("body", [
+      x("h1", meta.title),
+      x("nav", { "epub:type": "toc" }, [
+        x("h2", locale.toc),
+        generateTocList(toc)
+      ]),
+      x("nav", { "epub:type": "landmarks" }, [
+        x("h2", locale.landmarks),
+        generateLandmarks(landmarks, locale)
+      ])
+    ])
+  ]);
+  return stringifyXml(tree);
+}
+
+function generateList(entries, prefix = "ncx") {
+  return entries.map((entry, index) => {
+    const entryId = `${prefix}-${index}`;
+    return x("navPoint", { id: entryId }, [
+      x("navLabel", [
+        x("text", entry.text)
+      ]),
+      x("content", { src: entry.href }),
+      ...entry.children && entry.children.length > 0 ? generateList(entry.children, entryId) : []
+    ]);
+  });
+}
+function generateNcx(config) {
+  const { meta, toc } = config;
+  const tree = x("ncx", { version: "2005-1", "xml:lang": meta.language, xmlns: "http://www.daisy.org/z3986/2005/ncx/" }, [
+    x("head", [
+      x("meta", { content: getUniqueIdentifier(meta).id, name: "dtb:uid" })
+    ]),
+    x("docTitle", [
+      x("text", meta.title)
+    ]),
+    x("navMap", generateList(toc))
+  ]);
+  return stringifyXml(tree);
+}
+
+const ALLOWED_MEDIA_TYPES = [
+  // Images
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/svg+xml",
+  "image/webp",
+  // Audio
+  "audio/mpeg",
+  "audio/mp4",
+  "audio/ogg",
+  // Style
+  "text/css",
+  // Fonts
+  "font/ttf",
+  "font/otf",
+  "font/woff",
+  "font/woff2",
+  // Other
+  "application/xhtml+xml",
+  "application/javascript",
+  "application/x-dtbncx+xml",
+  "application/smil+xml"
+];
+function getMimeType(path) {
+  const mimeType = mime.getType(path) ?? undefined;
+  if (mimeType === "video/mp4") {
+    return "audio/mp4";
+  } else if (mimeType === "text/javascript") {
+    return "application/javascript";
+  }
+  return mimeType;
+}
+function isCoreMediaType(mimeType) {
+  if (!mimeType) {
+    return false;
+  }
+  return ALLOWED_MEDIA_TYPES.includes(mimeType);
+}
+
+function createResource(href, properties = []) {
+  return {
+    href,
+    mime: getMimeType(href),
+    properties
+  };
+}
+
+async function readBinaryFile(path) {
+  const buffer = await readFile(path);
+  return new Blob([buffer]);
+}
+
+class ZipContainer {
+  #zip;
+  /**
+   * The private constructor
+   */
+  constructor() {
+    const writer = new BlobWriter("application/epub+zip");
+    this.#zip = new ZipWriter(writer);
+  }
+  /**
+   * Adds a binary file to the container
+   * @param path The path to the file inside the container
+   * @param blob The binary data
+   * @param options Options passed to `zip.js`
+   */
+  async addBinaryFile(path, blob, options = {}) {
+    const reader = new BlobReader(blob);
+    await this.#zip.add(path, reader, options);
+  }
+  /**
+   * Adds a text file to the container
+   * @param path The path to the file inside the container
+   * @param text The textual data
+   * @param options Options passed to `zip.js`
+   */
+  async addTextFile(path, text, options = {}) {
+    const reader = new TextReader(text);
+    await this.#zip.add(path, reader, options);
+  }
+  /**
+   * Returns an empty `ZipContainer`
+   */
+  static async init() {
+    const container = new ZipContainer();
+    await container.addTextFile("mimetype", "application/epub+zip", { compressionMethod: 0, extendedTimestamp: false });
+    return container;
+  }
+  /**
+   * Closes the container, returning its content
+   * @returns The EPUB binary data
+   */
+  async seal() {
+    return this.#zip.close();
+  }
+}
+
+class EpubBuilder {
+  /**
+   * The builder config
+   */
+  config;
+  /**
+   * The list of registered EPUB resources
+   */
+  resources;
+  /**
+   * The EPUB ZIP container
+   */
+  zip;
+  /**
+   * The private constructor
+   * @param config The builder config
+   */
+  constructor(config) {
+    this.config = config;
+    this.resources = [];
+  }
+  /**
+   * Registers a binary-encoded file
+   * @param href The resource's path inside the EPUB container
+   * @param content The resource's binary-encoded content
+   * @param properties The resource's manifest properties
+   * @returns The registered resource
+   */
+  async addBinaryFile(href, content, properties = []) {
+    const resource = createResource(href, properties);
+    this.resources.push(resource);
+    await this.zip.addBinaryFile(`OEBPS/${href}`, content);
+    return resource;
+  }
+  /**
+   * Registers a text-encoded file
+   * @param href The resource's path inside the EPUB container
+   * @param content The resource's text-encoded content
+   * @param properties The resource's manifest properties
+   * @returns The registered resource
+   */
+  async addTextFile(href, content, properties = []) {
+    const resource = createResource(href, properties);
+    this.resources.push(resource);
+    await this.zip.addTextFile(`OEBPS/${href}`, content);
+    return resource;
+  }
+  /**
+   * Reads a file and registers it as a resource
+   * @param href The resource's path inside the EPUB container
+   * @param path The file's physical path
+   * @param properties The resource's manifest properties
+   * @returns The registered resource
+   */
+  async copyFile(href, path, properties = []) {
+    const blob = await readBinaryFile(path);
+    return this.addBinaryFile(href, blob, properties);
+  }
+  /**
+   * Generate metadata files for EPUB compliance
+   */
+  async #generateFiles() {
+    await this.addTextFile("nav.xhtml", generateNavXhtml(this.config), ["nav"]);
+    await this.addTextFile("toc.ncx", generateNcx(this.config));
+    await this.zip.addTextFile("OEBPS/content.opf", generateContentOpf(this.config, this.resources));
+    await this.zip.addTextFile("META-INF/com.apple.ibooks.display-options.xml", generateAppleDisplayOptionsXml(this.resources));
+  }
+  /**
+   * Returns an empty `EpubBuilder`
+   * @param partialConfig The builder config
+   */
+  static async init(partialConfig) {
+    const config = populateConfig(partialConfig);
+    const builder = new EpubBuilder(config);
+    builder.zip = await ZipContainer.init();
+    await builder.zip.addTextFile("META-INF/container.xml", generateContainerXml());
+    return builder;
+  }
+  /**
+   * Closes the ZIP container, returning its content
+   * @returns The EPUB binary data
+   */
+  async seal() {
+    await this.#generateFiles();
+    return this.zip.seal();
+  }
+}
+
+export { EpubBuilder, getMimeType, isCoreMediaType, populateConfig };

package/dist/locales/en.json

@@ -0,0 +1,6 @@
+{
+  "bodymatter": "Start of content",
+  "landmarks": "Guide",
+  "loi": "List of images",
+  "toc": "Table of Contents"
+}

package/dist/locales/pt.json

@@ -0,0 +1,6 @@
+{
+  "bodymatter": "Início do conteúdo",
+  "landmarks": "Guia",
+  "loi": "Lista de imagens",
+  "toc": "Índice"
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@leopiccionia/epub-builder",
+  "version": "0.0.1",
+  "description": "A non-opinionated EPUB builder for reflowable content",
+  "type": "module",
+  "keywords": [
+    "ebook",
+    "epub"
+  ],
+  "homepage": "https://github.com/leopiccionia/epub-builder",
+  "author": {
+    "email": "leopiccionia@gmail.com",
+    "name": "Leonardo Piccioni de Almeida",
+    "url": "https://leopiccionia.github.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leopiccionia/epub-builder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/leopiccionia/epub-builder/issues",
+    "email": "leopiccionia@gmail.com"
+  },
+  "license": "BSD-3-Clause",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./locales/*": "./dist/locales/*"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/xast": "^2.0.4",
+    "unbuild": "^3.3.1",
+    "vitest": "^3.0.4"
+  },
+  "dependencies": {
+    "@lukeed/uuid": "^2.0.1",
+    "@zip.js/zip.js": "^2.7.57",
+    "defu": "^6.1.4",
+    "mime": "^4.0.6",
+    "unist-builder": "^4.0.0",
+    "xast-util-to-xml": "^4.0.0",
+    "xastscript": "^4.0.0"
+  }
+}