postext-epub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postext contributors
+
+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,194 @@
+# postext-epub
+
+**EPUB 3 writer for [postext](https://www.npmjs.com/package/postext).**
+
+`postext-epub` writes a book that `postext` has laid out as an EPUB 3.3 file, in the browser or in Node, with no server. It reads the same per-chapter `VDTDocument`s the PDF backend renders, so page numbers, footnotes, citations, cross-references, the contents and the index arrive already resolved. The whole file is built in memory and returned as bytes.
+
+A book comes out in one of the two renditions EPUB 3 defines (the `rendition:layout` property):
+
+- **Fixed layout** (`layout: 'fixed'`, EPUB `pre-paginated`): every printed page as it is, one XHTML document per page, with real, selectable text placed where the PDF places it.
+- **Reflowable** (`layout: 'reflowable'`, the EPUB default): the text, figures and tables in reading order, as semantic XHTML that the reading system sets again for its screen, typeface and type size.
+
+Right-to-left books (Arabic, Persian, Hebrew…) declare their language and direction on every document and on the navigation, and a right-bound book turns its pages to the left (`page-progression-direction="rtl"`). In the reflowable rendition a run set against its paragraph (a Latin name in Arabic, an Arabic quotation in English) is a `dir` isolate, a language named on `:ltr[…]{lang=en}` is declared, a `:::verse` poem sets each bayt as two hemistichs side by side, and the tatweels kashida justification inserted are left out (the reading system justifies; tatweels the author typed stay). The fixed layout paints them as printed, out of reach of a text selection.
+
+**Website:** [postext.dev](https://postext.dev/) · **Docs:** [EPUB books](https://postext.dev/en/docs/configuration#epub-books-postext-epub)
+
+## Install
+
+```bash
+npm install postext postext-epub
+```
+
+`postext` is a peer dependency. Each `postext-epub` release needs the `postext` it was released with, or a later one of the same major, so upgrade the two together. Or import both straight from a CDN:
+
+```js
+import { buildDocument } from 'https://esm.sh/postext';
+import { renderToEpub } from 'https://esm.sh/postext-epub';
+```
+
+## Quick example
+
+```ts
+import { buildDocument } from 'postext';
+import { renderToEpub } from 'postext-epub';
+
+// Postext measures text with the fonts the browser has loaded.
+await document.fonts.load('16px "EB Garamond"');
+
+const doc = buildDocument({ markdown: '# Lantern\n\nTypeset me.' }, {
+  page: { sizePreset: '17x24' },
+  bodyText: { fontFamily: 'EB Garamond' },
+});
+
+const bytes = await renderToEpub([doc], {
+  layout: 'reflowable', // or 'fixed'
+  metadata: { title: 'Lantern', creators: ['Ada Lovelace'], language: 'en' },
+  fonts: [
+    { family: 'EB Garamond', weight: 400, style: 'normal', bytes: garamondRegular, format: 'woff2' },
+    { family: 'EB Garamond', weight: 400, style: 'italic', bytes: garamondItalic, format: 'woff2' },
+  ],
+});
+
+const url = URL.createObjectURL(new Blob([bytes], { type: 'application/epub+zip' }));
+```
+
+## A whole book
+
+`renderToEpub` takes the book's chapters in order, each laid out as a continuation of the one before (counters, page parity, page numbers), which is what `buildBundle` returns for a `.postext` file:
+
+```ts
+import { openBundle, buildBundle } from 'postext';
+import { renderToEpub } from 'postext-epub';
+
+const bundle = await openBundle(fileBytes, { locale: 'es' });
+const docs = buildBundle(bundle); // one VDTDocument per chapter
+
+const bytes = await renderToEpub(docs, {
+  layout: 'fixed',
+  metadata: { title: 'Don Quijote', creators: ['Miguel de Cervantes'], language: 'es' },
+  fonts: bundle.fonts.map((f) => ({ family: f.family, weight: f.weight, style: f.style, bytes: new Uint8Array(f.bytes), format: f.format })),
+  resourceBytes: (fileId) => {
+    const data = bundle.files.get(fileId);
+    return data ? { bytes: data, mediaType: '' } : undefined; // '' = read the type from the bytes
+  },
+  onProgress: ({ phase, done, total }) => console.log(phase, done, total),
+  onWarning: (w) => console.warn(w),
+});
+```
+
+The same array is what `renderToPdf` from `postext-pdf` takes for a book, so a PDF and an EPUB of one book come from one layout.
+
+## API
+
+### `renderToEpub(docs, options): Promise<Uint8Array>`
+
+`docs` is the book's print documents, one per chapter in book order (at least one). The result is the `.epub` file.
+
+<table>
+  <thead>
+    <tr><th>Option</th><th>What it does</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>layout</code></td><td>Required. <code>'fixed'</code> or <code>'reflowable'</code>.</td></tr>
+    <tr><td><code>metadata</code></td><td>Required. <code>title</code> and <code>language</code> (a BCP 47 tag), and optionally <code>subtitle</code>, <code>creators</code> (authors in order), <code>identifier</code>, <code>date</code> (ISO 8601), <code>publisher</code>, <code>rights</code>, <code>description</code> and <code>modified</code>.</td></tr>
+    <tr><td><code>fonts</code></td><td>The faces to embed: <code>{ family, weight, style, bytes, format, unicodeRange? }</code>, with <code>format</code> one of <code>woff2</code>, <code>woff</code>, <code>ttf</code>, <code>otf</code>. Each face becomes a file and an <code>@font-face</code> rule. Several files of one face, each with its <code>unicodeRange</code> (Google Fonts slices), are allowed.</td></tr>
+    <tr><td><code>resourceBytes</code></td><td><code>(fileId) =&gt; { bytes, mediaType } | undefined</code>, sync or async: the pictures the pages place, by file id. Bitmaps as they are, SVGs as their source (not a PDF print master). An empty <code>mediaType</code> is read from the bytes. A single-ink book (<code>diagramStyle.singleInk</code>) has its SVGs recoloured in the file.</td></tr>
+    <tr><td><code>cover</code></td><td><code>{ bytes, mediaType, alt? }</code>: a JPEG, PNG, WebP or SVG cover picture. It opens the book on a cover document of its own and is marked as the <code>cover-image</code>. Without it, the fixed layout names its first page as the cover, and the reflowable book has no cover picture.</td></tr>
+    <tr><td><code>onProgress</code></td><td><code>{ phase, done, total }</code>, with <code>phase</code> one of <code>resources</code> (fonts and pictures), <code>documents</code> (pages for a fixed layout, chapters for a reflowable one) and <code>package</code> (the package document, the navigation and the zip).</td></tr>
+    <tr><td><code>onWarning</code></td><td>Problems that do not stop the file: <code>missingImage</code> (a picture with no bytes, left as an empty frame), <code>missingFont</code> (a family, weight or style the pages use with no embedded face, which reading systems replace) and <code>unsupported</code>.</td></tr>
+    <tr><td><code>signal</code></td><td>An <code>AbortSignal</code>; aborting rejects the promise between steps.</td></tr>
+  </tbody>
+</table>
+
+Without an `identifier`, the book gets a `urn:uuid:` derived from its title, creators and language, so writing the same book again keeps its identity in a reader's library. A bare ISBN becomes `urn:isbn:…`. Pass `modified` as well for byte-identical output from the same input.
+
+### Writing on a worker: `createEpubWorker()` (`postext-epub/worker`)
+
+`renderToEpub` keeps the thread it runs on busy while it writes; a fixed layout of a long book takes a second or more. In a page, write the book on a worker instead:
+
+```ts
+import { createEpubWorker } from 'postext-epub/worker';
+
+const epubWorker = createEpubWorker();
+const controller = new AbortController();
+const bytes = await epubWorker.render(docs, {
+  layout: 'fixed',
+  metadata: { title: 'My book', language: 'en' },
+  fonts,
+  resourceBytes, // a function, as for renderToEpub, or a Map by fileId
+  onProgress: (p) => console.log(p.phase, p.done, p.total),
+  onWarning: (w) => console.warn(w),
+  signal: controller.signal,
+});
+epubWorker.dispose(); // when the page no longer needs it
+```
+
+`render(docs, options)` takes the options of `renderToEpub` and returns the same bytes. What travels to the worker:
+
+- The documents are copied (structured clone).
+- A `resourceBytes` function is asked on the calling thread for every picture the pages place before the worker starts, since the worker cannot reach the host's stores. A `Map` of `{ bytes, mediaType }` by file id is sent as it is.
+- The buffers of the fonts, the pictures and the cover are transferred, not copied, so the caller's views of them are empty afterwards. Pass copies of bytes you keep.
+- The finished file comes back transferred.
+
+Progress and warnings are forwarded as they happen. Aborting the signal rejects at once with an `AbortError` and stops the worker, and the next render starts a fresh one.
+
+The worker script is `new URL('./epub.worker.js', import.meta.url)`, which webpack, Vite and esbuild bundle. A host that builds its own worker passes it as `createEpubWorker({ worker })`, a `Worker` or a function that makes one. Its script imports `postext-epub/worker/entry`. A worker that fails to load rejects with an `EpubWorkerError`, and the host can then call `renderToEpub` on its own thread.
+
+### `readEpub(bytes): ReadEpubResult`
+
+Reads an EPUB back for a viewer, without `DOMParser`: the layout, the metadata, the reading direction, every file by its zip path, the manifest, the spine in reading order, the table of contents (from the navigation document, or the NCX of an older file), the page list, the fixed-layout viewport and the cover picture's path. `resolveHref(base, href)` and `dirOf(path)` resolve the links between those files.
+
+### Lower-level exports
+
+`buildFixedPublication` and `buildReflowablePublication` return the publication model (`EpubPublication`: items, spine, navigation, accessibility metadata) without packing it, and `packEpub(publication)` writes such a model as a file. `bookIdentifier` and `uuidV5` compute the identifier `renderToEpub` uses.
+
+## What each layout produces
+
+### Fixed layout
+
+- One XHTML document per printed page, from the HTML backend's markup for that page. The viewport is the trimmed page in CSS px; the cut-line margin is cropped.
+- Text is real text in the embedded fonts, so it can be selected, searched and read aloud. Formulas are inline SVG; pictures are files, each stored once.
+- `page-spread-left` and `page-spread-right` follow the page parity and the binding. A right-bound book (Arabic, vertical Chinese) has `rtl` page progression, and its pages run right to left.
+- Links work between pages: cross-references, footnotes, the printed contents and the index. Links to an element the book does not hold are dropped.
+- The table of contents comes from the headings and the part pages, the page list from the printed page labels (`iv`, `12`), and the landmarks point at the cover, the printed contents and the start of the body.
+
+### Reflowable
+
+- One XHTML document per chapter (`text/chapter-NNN.xhtml`). A part opens a document of its own.
+- Paragraphs are rebuilt from the laid-out lines: the hyphens the line breaks added are removed, hyphens that belong to the word are kept, and a paragraph split across pages or columns is one paragraph again.
+- Figures and tables follow the text that cites them, with their numbered captions and alt text. Tables are real tables with header rows and merged cells. Lists nest, boxes become `<aside>` with their titles, heading levels never skip, and formulas are SVG labelled with their TeX.
+- Footnotes link to the notes at the end of the chapter and back. Cross-references, citations and web links work. The printed contents link to the headings, and the index's page numbers link to page markers.
+- Each printed page leaves a page-break marker where its text starts, so the page list gives the print page numbers.
+- A stylesheet is derived from the configuration: sizes relative to the body text, the book's colours, justification with automatic hyphenation, indents, and styles for headings, boxes, tables, captions, lists and notes. Vertical Chinese keeps vertical writing; Arabic documents are `dir="rtl"`.
+- Paragraphs set in a paragraph style (`:::paragraphs{style=…}`, a `:::verse` fence's style) carry its class, inside boxes too, and index entries are classed by their level, both as the layout names them (`VDTBlock.paragraphStyleId`, `VDTBlock.indexLevel`). Documents laid out by an older engine fall back to telling them from the face and the indent.
+- The stylesheet follows the first chapter's configuration. A chapter configured otherwise (its own heading styles, say), and every document of a part whose `palette` recolours the book, links a second stylesheet after it (`styles/book-2.css`…) with only the rules that change; documents that change the same share it.
+- A pull quote repeats words of the text, so it would be read twice. A box with no title (or a title of marks alone, such as a hanging quotation mark) whose words the chapter's text also has is kept on the page as `<aside epub:type="pullquote" role="doc-pullquote" aria-hidden="true">`: readers see it, assistive technology and read-aloud skip it, and the words are read once, in the text. A box whose style id names it a pull quote but whose words are its own is marked `epub:type="pullquote"` and read.
+
+Both renditions carry the EPUB Accessibility 1.1 metadata (access modes, features such as the table of contents and print page numbers, hazards and a summary), and neither claims WCAG conformance by default.
+
+## Limitations
+
+- A part's palette recolours the colours equal to the palette entries it overrides, as the printed text does; two entries that share a colour take the last override.
+- A pull quote edited beyond leaving words out (an ellipsis) does not match the text, and is read as well.
+- Fonts are embedded as given. Respect the font licences: leave out families that may not be redistributed.
+- `renderToEpub` writes on the calling thread; use `createEpubWorker` in a page. The writer checks the signal between steps, so a call on the page's own thread stops at the next step, not at once.
+
+## Checking output with EPUBCheck
+
+Output is checked with [W3C EPUBCheck](https://www.w3.org/publishing/epubcheck/) 5.4. In this repository, with `epubcheck` on the `PATH`:
+
+```bash
+pnpm --filter postext-epub epubcheck   # sample books built in the tests
+pnpm --filter postext-epub validate    # the guide, the showcase presets and Cookbook books, both layouts
+node packages/postext-epub/scripts/epubcheck.mjs path/to/book.postext --lang es --layout both --out /tmp/epub
+```
+
+- `epubcheck` (`src/epubcheck.test.ts`) writes the test suite's sample books (fixed, fixed with a cover, reflowable, reflowable with a cover) and fails on any EPUBCheck error or warning. Without the command it is skipped; `EPUBCHECK_OUT=dir` keeps the files.
+- `scripts/epubcheck.mjs` lays out one `.postext` file or preset folder with its own fonts, writes the EPUB in one or both layouts and runs EPUBCheck on it. Options: `--lang`, `--layout fixed|reflowable|both`, `--out`, `--chapters 0,2`, `--report result.json`, `--no-cover`. For the reflowable book it also compares the letters of the laid-out text with those of the EPUB, so a lost or repeated paragraph shows.
+- `scripts/validate.mjs` runs `epubcheck.mjs` on the whole matrix of books and prints a table; `--only name,name`, `--jobs N`, `--full` (all of Hong Lou Meng). It exits with 1 when any book has an EPUBCheck error or warning.
+
+The scripts read this checkout's built dists: run `npx tsc` in `packages/postext`, `postext-pdf`, `postext-citeproc` and `postext-epub` first (`validate` builds `postext-epub` itself). The usage notes EPUBCheck leaves (`CSS-028` for `@font-face`, `OBS-001` for the NCX kept for older readers, `HTM_062` for `xlink:href` in formulas) are informational.
+
+## License
+
+MIT

package/dist/__tests__/sampleBook.d.ts

@@ -0,0 +1,17 @@
+import type { PostextConfig, VDTDocument } from 'postext';
+export declare const LORA: Uint8Array<ArrayBuffer>;
+export declare const PNG: Uint8Array<ArrayBuffer>;
+export declare const SAMPLE_CHAPTERS: string[];
+export declare function sampleBook(): VDTDocument[];
+/** Lay out chapters as a book with the sample page and a config of the
+ *  caller's on top. */
+export declare function layOutBook(chapters: string[], overrides?: PostextConfig): VDTDocument[];
+/** Amiri (OFL), the subset the PDF backend's Arabic tests embed. */
+export declare const AMIRI: Uint8Array<ArrayBuffer>;
+/** A right-to-left book (#402): Arabic chapters, right-bound, with Latin
+ *  and digit runs, an English isolate naming its language, «(١)» notes,
+ *  justified text stretched with kashidas, a `:::verse` poem and an
+ *  English block. */
+export declare const ARABIC_CHAPTERS: string[];
+export declare function arabicSampleBook(): VDTDocument[];
+//# sourceMappingURL=sampleBook.d.ts.map

package/dist/__tests__/sampleBook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampleBook.d.ts","sourceRoot":"","sources":["../../src/__tests__/sampleBook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAY,WAAW,EAAE,MAAM,SAAS,CAAC;AAwBpE,eAAO,MAAM,IAAI,yBAAkH,CAAC;AAEpI,eAAO,MAAM,GAAG,yBAA6I,CAAC;AA2B9J,eAAO,MAAM,eAAe,UAG3B,CAAC;AAEF,wBAAgB,UAAU,IAAI,WAAW,EAAE,CAE1C;AAED;uBACuB;AACvB,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,WAAW,EAAE,CAE3F;AAED,oEAAoE;AACpE,eAAO,MAAM,KAAK,yBAAmI,CAAC;AAEtJ;;;qBAGqB;AACrB,eAAO,MAAM,eAAe,UAoB3B,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,WAAW,EAAE,CAWhD"}

package/dist/__tests__/sampleBook.js

@@ -0,0 +1,103 @@
+// A real two-chapter book laid out in node for the integration tests and
+// the EPUBCheck samples: a figure with alternative text, headings at two
+// levels, a cross-reference into the other chapter and a page footer.
+import fs from 'node:fs';
+import { buildBundle } from 'postext';
+// Text measured with a fixed advance (half an em per character): stable
+// line breaks without a font file or a DOM.
+class StubCtx {
+    font = '';
+    letterSpacing = '0px';
+    measureText(s) {
+        const size = Number(/(\d+(?:\.\d+)?)px/.exec(this.font)?.[1] ?? 16);
+        return {
+            width: [...s].length * size * 0.5,
+            actualBoundingBoxAscent: size * 0.7,
+            actualBoundingBoxDescent: size * 0.2,
+            fontBoundingBoxAscent: size * 0.8,
+            fontBoundingBoxDescent: size * 0.2,
+        };
+    }
+}
+globalThis.OffscreenCanvas = class {
+    getContext() {
+        return new StubCtx();
+    }
+};
+export const LORA = new Uint8Array(fs.readFileSync(new URL('../../../../apps/web/public/fonts/Lora-Regular.ttf', import.meta.url)));
+// 1×1 PNG.
+export const PNG = Uint8Array.from(Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==', 'base64'));
+const pt = (value) => ({ value, unit: 'pt' });
+const config = {
+    page: { width: pt(360), height: pt(480), margins: { top: pt(24), bottom: pt(24), left: pt(24), right: pt(24) } },
+    locale: 'en-us',
+    footer: {
+        elements: [{
+                kind: 'text', id: 'pn', content: '{pageNumber}', fontSize: pt(8), overflow: 'ellipsis-end',
+                placement: { anchor: { to: 'container', edge: 'bottom' }, size: { width: 'auto', height: 'auto' } },
+            }],
+    },
+};
+const resources = [{
+        id: 'f1',
+        typeId: 'figure',
+        kind: 'bitmap',
+        caption: 'A square.',
+        altText: 'A red square on white',
+        createdAt: 0,
+        updatedAt: 0,
+        bitmap: { fileId: 'f1.png', format: 'png', width: 400, height: 300 },
+    }];
+const para = 'Body text that runs on for a while so the page fills and the paragraph wraps over several lines. ';
+export const SAMPLE_CHAPTERS = [
+    ['---', 'title: Sample book', 'author: Ada Lovelace', '---', '', '# Opening chapter {#opening}', '', `See :ref{id=f1} and the [closing words](#closing). ${para.repeat(3)}`, '', '::resource{id=f1}', '', '## A section', '', para.repeat(12)].join('\n'),
+    ['# Second chapter', '', `Back to the [opening](#opening). ${para.repeat(6)}`, '', '## Closing words {#closing}', '', para.repeat(4)].join('\n'),
+];
+export function sampleBook() {
+    return buildBundle({ chapters: SAMPLE_CHAPTERS.map((markdown) => ({ markdown })), config, resources });
+}
+/** Lay out chapters as a book with the sample page and a config of the
+ *  caller's on top. */
+export function layOutBook(chapters, overrides = {}) {
+    return buildBundle({ chapters: chapters.map((markdown) => ({ markdown })), config: { ...config, ...overrides } });
+}
+/** Amiri (OFL), the subset the PDF backend's Arabic tests embed. */
+export const AMIRI = new Uint8Array(fs.readFileSync(new URL('../../../postext-pdf/src/__tests__/fixtures/arabic/amiri-subset.ttf', import.meta.url)));
+/** A right-to-left book (#402): Arabic chapters, right-bound, with Latin
+ *  and digit runs, an English isolate naming its language, «(١)» notes,
+ *  justified text stretched with kashidas, a `:::verse` poem and an
+ *  English block. */
+export const ARABIC_CHAPTERS = [
+    [
+        '# الفصل الأول',
+        '',
+        `قال الراوي إن الملك AAA كان يحكم سنة ١٤٤٥ هـ (2024 م)[^a]. ${'قال الراوي إن الملك شهريار كان يحكم بلاد الهند والصين، وكان له أخ اسمه شاه زمان. '.repeat(4)}`,
+        '',
+        'وقال الشيخ :ltr[the old man]{lang=en} ثم سكت وكتب جمـيل.',
+        '',
+        ':::verse{ornament="٭"}',
+        'يا حرقة الدهر كفي || إن لم تكفي فعفي',
+        'فلا بحظي أعطي || ولا بصنعة كفي',
+        ':::',
+        '',
+        ':::paragraphs{dir=ltr}',
+        'An English paragraph with the word كتاب in it.',
+        ':::',
+        '',
+        '[^a]: حاشية NOTE-A.',
+    ].join('\n'),
+    ['# الفصل الثاني', '', 'قال الراوي إن الملك شهريار كان يحكم بلاد الهند والصين. '.repeat(10)].join('\n'),
+];
+export function arabicSampleBook() {
+    return buildBundle({
+        chapters: ARABIC_CHAPTERS.map((markdown) => ({ markdown })),
+        config: {
+            ...config,
+            locale: 'ar',
+            bodyText: { fontFamily: 'Amiri', textAlign: 'justify' },
+            headings: { fontFamily: 'Amiri' },
+            footnotes: { markerTemplate: '({n})', numbering: 'page' },
+        },
+    });
+}
+//# sourceMappingURL=sampleBook.js.map

package/dist/__tests__/sampleBook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampleBook.js","sourceRoot":"","sources":["../../src/__tests__/sampleBook.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,yEAAyE;AACzE,sEAAsE;AAEtE,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,wEAAwE;AACxE,4CAA4C;AAC5C,MAAM,OAAO;IACX,IAAI,GAAG,EAAE,CAAC;IACV,aAAa,GAAG,KAAK,CAAC;IACtB,WAAW,CAAC,CAAS;QACnB,MAAM,IAAI,GAAG,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpE,OAAO;YACL,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,GAAG,GAAG;YACjC,uBAAuB,EAAE,IAAI,GAAG,GAAG;YACnC,wBAAwB,EAAE,IAAI,GAAG,GAAG;YACpC,qBAAqB,EAAE,IAAI,GAAG,GAAG;YACjC,sBAAsB,EAAE,IAAI,GAAG,GAAG;SACnC,CAAC;IACJ,CAAC;CACF;AACA,UAAsD,CAAC,eAAe,GAAG;IACxE,UAAU;QACR,OAAO,IAAI,OAAO,EAAE,CAAC;IACvB,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,oDAAoD,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACpI,WAAW;AACX,MAAM,CAAC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kGAAkG,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9J,MAAM,EAAE,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAa,EAAE,CAAC,CAAC;AAE/D,MAAM,MAAM,GAAkB;IAC5B,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IAChH,MAAM,EAAE,OAAO;IACf,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC;gBACT,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc;gBAC1F,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;aACpG,CAAC;KACH;CACF,CAAC;AAEF,MAAM,SAAS,GAAe,CAAC;QAC7B,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,uBAAuB;QAChC,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;QACZ,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;KACrE,CAAC,CAAC;AAEH,MAAM,IAAI,GAAG,mGAAmG,CAAC;AACjH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,CAAC,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,KAAK,EAAE,EAAE,EAAE,8BAA8B,EAAE,EAAE,EAAE,sDAAsD,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACzP,CAAC,kBAAkB,EAAE,EAAE,EAAE,oCAAoC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,6BAA6B,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;CACjJ,CAAC;AAEF,MAAM,UAAU,UAAU;IACxB,OAAO,WAAW,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AACzG,CAAC;AAED;uBACuB;AACvB,MAAM,UAAU,UAAU,CAAC,QAAkB,EAAE,YAA2B,EAAE;IAC1E,OAAO,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,EAAE,CAAC,CAAC;AACpH,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,qEAAqE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEtJ;;;qBAGqB;AACrB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;QACE,eAAe;QACf,EAAE;QACF,8DAA8D,mFAAmF,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QAC7J,EAAE;QACF,0DAA0D;QAC1D,EAAE;QACF,wBAAwB;QACxB,sCAAsC;QACtC,gCAAgC;QAChC,KAAK;QACL,EAAE;QACF,wBAAwB;QACxB,gDAAgD;QAChD,KAAK;QACL,EAAE;QACF,qBAAqB;KACtB,CAAC,IAAI,CAAC,IAAI,CAAC;IACZ,CAAC,gBAAgB,EAAE,EAAE,EAAE,yDAAyD,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;CACxG,CAAC;AAEF,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC;QACjB,QAAQ,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE;YACN,GAAG,MAAM;YACT,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE;YACvD,QAAQ,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE;YACjC,SAAS,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE;SAC1D;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/epubcheck.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=epubcheck.test.d.ts.map

package/dist/epubcheck.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epubcheck.test.d.ts","sourceRoot":"","sources":["../src/epubcheck.test.ts"],"names":[],"mappings":""}

package/dist/epubcheck.test.js

@@ -0,0 +1,69 @@
+// W3C EPUBCheck on generated sample books. Runs only when asked
+// (`pnpm epubcheck`, or EPUBCHECK=1) and the `epubcheck` command is on the
+// PATH: it takes a few seconds of Java per book. Set EPUBCHECK_OUT to keep
+// the files.
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { renderToEpub } from './index';
+import { AMIRI, LORA, PNG, arabicSampleBook, sampleBook } from './__tests__/sampleBook';
+const available = process.env.EPUBCHECK === '1' && spawnSync('epubcheck', ['--version'], { encoding: 'utf8' }).status === 0;
+function epubcheck(file) {
+    const out = spawnSync('epubcheck', ['--json', '-', file], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const report = JSON.parse(out.stdout);
+    return report.messages.filter((m) => m.severity === 'ERROR' || m.severity === 'FATAL' || m.severity === 'WARNING');
+}
+const base = (layout) => ({
+    layout,
+    metadata: {
+        title: 'Sample book',
+        subtitle: 'A test of both renditions',
+        creators: ['Ada Lovelace'],
+        language: 'en-US',
+        date: '2026-10-04',
+        publisher: 'Postext',
+        modified: new Date(Date.UTC(2026, 9, 4)),
+    },
+    fonts: [{ family: 'Lora', weight: 400, style: 'normal', bytes: LORA, format: 'ttf' }],
+    resourceBytes: (fileId) => fileId === 'f1.png' ? { bytes: PNG, mediaType: 'image/png' } : undefined,
+});
+/** The right-to-left sample (#402), in Arabic. */
+const arabic = (layout) => ({
+    layout,
+    metadata: { title: 'كتاب تجريبي', creators: ['المؤلف'], language: 'ar', modified: new Date(Date.UTC(2026, 9, 4)) },
+    fonts: [{ family: 'Amiri', weight: 400, style: 'normal', bytes: AMIRI, format: 'ttf' }],
+    cover: { bytes: PNG, mediaType: 'image/png', alt: 'غلاف الكتاب' },
+});
+const samples = [
+    { name: 'fixed', options: base('fixed') },
+    { name: 'fixed-cover', options: { ...base('fixed'), cover: { bytes: PNG, mediaType: 'image/png', alt: 'A red square' } } },
+    { name: 'reflowable', options: base('reflowable') },
+    { name: 'reflowable-cover', options: { ...base('reflowable'), cover: { bytes: PNG, mediaType: 'image/png', alt: 'A red square' } } },
+    { name: 'arabic-fixed', options: arabic('fixed'), book: arabicSampleBook },
+    { name: 'arabic-reflowable', options: arabic('reflowable'), book: arabicSampleBook },
+];
+describe.skipIf(!available)('EPUBCheck', () => {
+    const dir = process.env.EPUBCHECK_OUT ?? fs.mkdtempSync(path.join(os.tmpdir(), 'postext-epub-'));
+    fs.mkdirSync(dir, { recursive: true });
+    for (const sample of samples) {
+        it(`${sample.name}: 0 errors, 0 warnings`, async () => {
+            let bytes;
+            try {
+                bytes = await renderToEpub((sample.book ?? sampleBook)(), sample.options);
+            }
+            catch (e) {
+                // A rendition still being written is not checked yet.
+                if (/not implemented/.test(String(e)))
+                    return;
+                throw e;
+            }
+            const file = path.join(dir, `${sample.name}.epub`);
+            fs.writeFileSync(file, bytes);
+            const messages = epubcheck(file);
+            expect(messages.map((m) => `${m.severity} ${m.ID} ${m.locations[0]?.path ?? ''}:${m.locations[0]?.line ?? ''} ${m.message}`)).toEqual([]);
+        }, 120_000);
+    }
+});
+//# sourceMappingURL=epubcheck.test.js.map

package/dist/epubcheck.test.js.map

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

package/dist/fixed/fixed.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fixed.test.d.ts.map

package/dist/fixed/fixed.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed.test.d.ts","sourceRoot":"","sources":["../../src/fixed/fixed.test.ts"],"names":[],"mappings":""}