bookish-press 0.8.2 → 0.9.2

package/dist/epub/xhtml.test.js

@@ -0,0 +1,283 @@
+import { expect, test } from 'vitest';
+import Parser from '../models/chapter/Parser';
+import Edition from '../models/book/Edition';
+import { document_, endnoteSection, escapeAttribute, escapeText, serializeChapter, } from './xhtml';
+/** An edition with just enough in it to resolve references and definitions. */
+function makeEdition(options = {}) {
+    return Edition.fromJSON(undefined, {
+        title: 'Test',
+        authors: [],
+        number: 1,
+        summary: '',
+        published: null,
+        images: {},
+        description: '',
+        chapters: [],
+        license: '',
+        acknowledgements: '',
+        tags: [],
+        sources: {},
+        references: options.references ?? {},
+        symbols: {},
+        glossary: options.glossary ?? {},
+        theme: null,
+        uids: [],
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+}
+function context(overrides = {}) {
+    return {
+        edition: makeEdition(),
+        images: new Map(),
+        chapters: new Set(),
+        ...overrides,
+    };
+}
+/** Serialize Bookdown to chapter body markup. */
+function html(bookdown, ctx = context()) {
+    return serializeChapter(Parser.parseChapter(ctx.edition, bookdown), ctx)
+        .body;
+}
+/** Parse as XML and return the parse error, if any. This is the property that
+ *  actually matters: EPUB readers reject documents that are not well-formed. */
+function xmlErrorIn(xhtml) {
+    const parsed = new DOMParser().parseFromString(xhtml, 'application/xhtml+xml');
+    const error = parsed.getElementsByTagName('parsererror')[0];
+    return error ? (error.textContent ?? 'parse error') : undefined;
+}
+test.each([
+    ['Hello.', '<p>Hello.</p>'],
+    ['# A header', '<h2 id="header-0">A header</h2>'],
+    ['## Deeper', '<h3 id="header-0">Deeper</h3>'],
+    ['*bold*', '<p><strong>bold</strong></p>'],
+    ['_italic_', '<p><em>italic</em></p>'],
+    ['^super^', '<p><sup>super</sup></p>'],
+    ['^vsub^', '<p><sub>sub</sub></p>'],
+    ['-', '<hr/>'],
+    ['* One\n\n* Two', '<ul><li>One</li><li>Two</li></ul>'],
+    ['1. One\n\n2. Two', '<ol><li>One</li><li>Two</li></ol>'],
+    ['`code`python', '<p><code>code</code></p>'],
+    [
+        '[label|https://example.com]',
+        '<p><a href="https://example.com">label</a></p>',
+    ],
+])('%s serializes to %s', (bookdown, expected) => {
+    expect(html(bookdown)).toBe(expected);
+});
+test('escapes text content, every occurrence', () => {
+    expect(escapeText('a < b & c > d & e')).toBe('a &lt; b &amp; c &gt; d &amp; e');
+});
+test('escapes ampersands before the escapes it introduces', () => {
+    // The bug in TextNode.toHTML(): escaping < first turns &lt; into &amp;lt;.
+    expect(escapeText('<')).toBe('&lt;');
+    expect(escapeText('&lt;')).toBe('&amp;lt;');
+});
+test('escapes quotes in attributes but not in text', () => {
+    expect(escapeAttribute('say "hi" & \'bye\'')).toBe('say &quot;hi&quot; &amp; &#39;bye&#39;');
+    expect(escapeText('say "hi"')).toBe('say "hi"');
+});
+test('a comment is omitted', () => {
+    // A comment opens on a '%' preceded by a space.
+    const out = html('Before %an editorial note% after');
+    expect(out).not.toContain('editorial');
+    expect(out).toContain('Before');
+    expect(out).toContain('after');
+});
+test('a label becomes an anchor rather than vanishing', () => {
+    expect(html(':spot Text')).toContain('<span id="spot"></span>');
+});
+test('a code block keeps its code, not its language', () => {
+    // The bug in InlineCodeNode.toHTML() was emitting the language instead.
+    // The language goes on the opening line, the caption after the closing tick.
+    const out = html('`python\nprint(1)\n`A caption');
+    expect(out).toContain('<code>print(1)</code>');
+    expect(out).toContain('language-python');
+    // CodeNode.toHTML() emitted a second opening <pre> instead of closing it.
+    expect(out).toContain('</pre>');
+    expect(out).toContain('<figcaption>A caption</figcaption>');
+});
+test('a code block escapes markup in the code', () => {
+    expect(html('`\n<script>&\n`')).toContain('&lt;script&gt;&amp;');
+});
+test('a quote with a credit becomes a figure with a citation', () => {
+    const out = html('"\nQuoted.\n"Someone');
+    expect(out).toContain('<blockquote><p>Quoted.</p></blockquote>');
+    expect(out).toContain('<cite>Someone</cite>');
+});
+test('a callout becomes an aside', () => {
+    expect(html('=\nAttention.\n=')).toBe('<aside class="callout"><p>Attention.</p></aside>');
+});
+test('a table has a header row, a body, and closed rows', () => {
+    // TableNode.toHTML() never closed its <tr> elements.
+    const out = html(',a|b\n,c|d\nA caption');
+    expect(out).toContain('<thead><tr><th>a</th><th>b</th></tr></thead>');
+    expect(out).toContain('<tbody><tr><td>c</td><td>d</td></tr></tbody>');
+    expect(out).toContain('<caption><p>A caption</p></caption>');
+});
+test('a footnote becomes a linked reference plus an endnote', () => {
+    const ctx = context();
+    const chapter = Parser.parseChapter(ctx.edition, 'Text{the note}.');
+    const { body, endnotes } = serializeChapter(chapter, ctx);
+    expect(body).toContain('epub:type="noteref"');
+    expect(body).toContain('href="#fn-0"');
+    expect(body).toContain('id="fnref-0"');
+    expect(body).toContain('<sup>a</sup>');
+    expect(endnotes).toHaveLength(1);
+    expect(endnotes[0].symbol).toBe('a');
+    expect(endnotes[0].content).toBe('the note');
+    const section = endnoteSection(endnotes);
+    expect(section).toContain('id="fn-0"');
+    // The endnote links back to where it was referenced.
+    expect(section).toContain('href="#fnref-0"');
+});
+test('footnotes are lettered in document order', () => {
+    const ctx = context();
+    const { endnotes } = serializeChapter(Parser.parseChapter(ctx.edition, 'A{first} B{second}'), ctx);
+    expect(endnotes.map((n) => n.symbol)).toEqual(['a', 'b']);
+});
+test('a citation links to its reference', () => {
+    const ctx = context({
+        edition: makeEdition({ references: { ko2020: 'Ko, A. (2020).' } }),
+    });
+    expect(html('Text<ko2020>.', ctx)).toContain('<a href="references.xhtml#ref-ko2020">ko2020</a>');
+});
+test('an unknown citation degrades to plain text', () => {
+    const out = html('Text<nope>.');
+    expect(out).toContain('<sup class="citation">nope</sup>');
+    expect(out).not.toContain('<a ');
+});
+test('a definition links to the glossary', () => {
+    const ctx = context({
+        edition: makeEdition({
+            glossary: {
+                bug: { phrase: 'bug', definition: 'A defect', synonyms: [] },
+            },
+        }),
+    });
+    expect(html('A ~bug~bug here.', ctx)).toContain('<a class="definition" href="glossary.xhtml#gloss-bug">bug</a>');
+});
+test('an unknown definition degrades to plain text', () => {
+    expect(html('A ~bug~nope here.')).toBe('<p>A bug here.</p>');
+});
+test('a chapter link points at the chapter document', () => {
+    const ctx = context({ chapters: new Set(['intro']) });
+    expect(html('[go|intro]', ctx)).toBe('<p><a href="intro.xhtml">go</a></p>');
+});
+test('a chapter link with a label points at the label', () => {
+    const ctx = context({ chapters: new Set(['intro']) });
+    expect(html('[go|intro:spot]', ctx)).toBe('<p><a href="intro.xhtml#spot">go</a></p>');
+});
+test('a label-only link stays within the document', () => {
+    expect(html('[go|:spot]')).toBe('<p><a href="#spot">go</a></p>');
+});
+test('a link to a chapter not in the package keeps the words but drops the link', () => {
+    expect(html('[go|missing]')).toBe('<p>go</p>');
+});
+test('an image points at its packaged path', () => {
+    const ctx = context({
+        images: new Map([['photo.jpg', 'images/0.jpg']]),
+    });
+    const out = html('|photo.jpg|A photo|A caption|A credit|', ctx);
+    expect(out).toContain('<img src="images/0.jpg" alt="A photo"/>');
+    // Caption and credit are paragraphs, so they can't run together on a
+    // reader that drops the tags it doesn't know but keeps their contents.
+    expect(out).toContain('<p class="caption">A caption</p>');
+    expect(out).toContain('<p class="credit">A credit</p>');
+});
+test('an image that could not be packaged keeps its caption', () => {
+    const out = html('|photo.jpg|A photo|A caption|A credit|');
+    expect(out).not.toContain('<img');
+    expect(out).toContain('A caption');
+});
+test('a video embed becomes a link rather than disappearing', () => {
+    const out = html('|https://www.youtube.com/embed/abc|A video|Watch this||');
+    expect(out).toContain('<a href="https://www.youtube.com/embed/abc">');
+    expect(out).not.toContain('<iframe');
+});
+test('an image alt attribute cannot break out of its quotes', () => {
+    const ctx = context({ images: new Map([['p.jpg', 'images/0.jpg']]) });
+    // The parser curls straight quotes, so markup characters are what matter
+    // here; escapeAttribute covers quoting directly.
+    const out = html('|p.jpg|A & <angled> alt|||', ctx);
+    expect(out).toContain('alt="A &amp; &lt;angled&gt; alt"');
+    expect(xmlErrorIn(document_('T', out))).toBeUndefined();
+});
+// The property that decides whether an e-reader will open the file at all.
+test.each([
+    ['a paragraph', 'Hello.'],
+    ['a header', '# Header'],
+    ['formatting', '*bold* and _italic_ and ^sup^'],
+    ['a list', '* One\n\n* Two'],
+    ['a nested list', '* One\n\n** Nested\n\n* Two'],
+    ['a numbered list', '1. One\n\n2. Two'],
+    ['a rule', '-'],
+    ['a line break', 'One\\\ntwo'],
+    ['a table', ',a|b\n,c|d\nCaption'],
+    ['a code block', '`html\n<div>&amp;</div>\n`'],
+    ['inline code', 'Try `x < y`js here'],
+    ['a quote', '"\nQuoted.\n"Someone'],
+    ['a callout', '=\nAttention.\n='],
+    ['an image', '|p.jpg|Alt|Caption|Credit|'],
+    ['a footnote', 'Text{a note} more'],
+    ['a citation', 'Text<ref> more'],
+    ['a definition', 'A ~term~id here'],
+    ['a label', ':spot Text'],
+    ['a link', '[text|https://example.com/?a=1&b=2]'],
+    ['a comment', 'Before %a note% after'],
+    ['unescaped characters', 'Less < greater > amp & quote " apostrophe \''],
+])('%s produces well-formed XML', (_name, bookdown) => {
+    const ctx = context({ images: new Map([['p.jpg', 'images/0.jpg']]) });
+    const chapter = Parser.parseChapter(ctx.edition, bookdown);
+    const { body, endnotes } = serializeChapter(chapter, ctx);
+    const xhtml = document_('Title', body + endnoteSection(endnotes));
+    expect(xmlErrorIn(xhtml)).toBeUndefined();
+});
+test('a document declares the epub namespace its footnotes use', () => {
+    expect(document_('T', '')).toContain('xmlns:epub="http://www.idpf.org/2007/ops"');
+});
+test('a document escapes its title', () => {
+    expect(document_('A & B', '')).toContain('<title>A &amp; B</title>');
+});
+test('a video link is labelled distinctly from its caption', () => {
+    // The caption was previously used both as the link text and as the
+    // figcaption, so it appeared twice in a row on the page.
+    const out = html('|https://www.youtube.com/embed/abc|A description|A caption||');
+    expect(out).toContain('>A description</a>');
+    expect(out).toContain('<p class="caption">A caption</p>');
+    expect(out.match(/A caption/g)).toHaveLength(1);
+});
+test('a video link falls back to its URL when it has no description', () => {
+    const out = html('|https://www.youtube.com/embed/abc||A caption||');
+    expect(out).toContain('>https://www.youtube.com/embed/abc</a>');
+});
+test('a code block carries its line breaks as markup', () => {
+    // A reader that ignores `white-space` reflows a <pre> into a paragraph, so
+    // the breaks are carried by <br/> instead of literal newlines. The
+    // newlines are dropped rather than kept alongside, which would double-space
+    // the block on a reader that honours both.
+    const out = html('`\nfirst\nsecond\n`');
+    expect(out).toContain('first<br/>second');
+    expect(out).not.toContain('first\nsecond');
+});
+test('a code block keeps its indentation without relying on white-space', () => {
+    const out = html('`python\nif x:\n    return 1\n`');
+    // Leading spaces become non-breaking, so they survive whitespace collapsing.
+    expect(out).toContain('if x:<br/>\u00a0\u00a0\u00a0\u00a0return 1');
+});
+test('a code block still escapes markup after the line-break rewrite', () => {
+    expect(html('`\n<script>&\n`')).toContain('&lt;script&gt;&amp;');
+});
+test('a link URL carrying Bookdown escapes is unescaped', () => {
+    // Authors write escaped punctuation inside URLs; the parser keeps a link's
+    // address verbatim, and a backslash is never valid in one. epubcheck
+    // rejects it as a bad path segment delimiter.
+    expect(html('[text|https://medium\\.com/a-post]')).toContain('href="https://medium.com/a-post"');
+});
+test('an unclosed link cannot make the whole book invalid', () => {
+    // A missing ']' swallows what follows into the address. The link is wrong
+    // either way, but the characters are encoded so the document stays valid
+    // rather than the typo making the book unopenable.
+    const out = html('[text|https://example.com/a b, [other|https://x.com]');
+    expect(out).not.toMatch(/href="[^"]* [^"]*"/);
+    expect(xmlErrorIn(document_('T', out))).toBeUndefined();
+});

package/dist/epub/zip.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A minimal ZIP writer, sufficient for EPUB and dependency-free.
+ *
+ * EPUB requires that the first entry in the archive be an uncompressed
+ * `mimetype` file, which most convenience wrappers don't expose, so we write
+ * the format directly. Only the pieces EPUB needs are implemented: no Zip64
+ * (books are nowhere near 4GB), no encryption, no directory entries.
+ *
+ * Everything here is portable between the browser and Node, so it can be unit
+ * tested and is safe to import during server rendering. `CompressionStream` is
+ * used when available and entries fall back to stored otherwise.
+ */
+/** The CRC-32 of the given bytes, as the ZIP spec defines it. */
+export declare function crc32(bytes: Uint8Array): number;
+export default class Zip {
+    #private;
+    /**
+     * @param modified the timestamp recorded for every entry. Defaults to now;
+     * tests pass a fixed date so output is byte-for-byte reproducible.
+     */
+    constructor(modified?: Date);
+    /**
+     * Queue a file. Entries are written in the order added, which is how the
+     * EPUB `mimetype` requirement is met: add it first, stored.
+     *
+     * @param store true to skip compression. Pass it for `mimetype` (required)
+     * and for already-compressed payloads like JPEGs, where deflating costs
+     * time and saves nothing.
+     */
+    add(path: string, bytes: Uint8Array | string, store?: boolean): void;
+    /** The number of files queued. */
+    get size(): number;
+    /** Assemble the archive. */
+    toBlob(type?: string): Promise<Blob>;
+}

package/dist/epub/zip.js

@@ -0,0 +1,202 @@
+/**
+ * A minimal ZIP writer, sufficient for EPUB and dependency-free.
+ *
+ * EPUB requires that the first entry in the archive be an uncompressed
+ * `mimetype` file, which most convenience wrappers don't expose, so we write
+ * the format directly. Only the pieces EPUB needs are implemented: no Zip64
+ * (books are nowhere near 4GB), no encryption, no directory entries.
+ *
+ * Everything here is portable between the browser and Node, so it can be unit
+ * tested and is safe to import during server rendering. `CompressionStream` is
+ * used when available and entries fall back to stored otherwise.
+ */
+const LOCAL_HEADER = 0x04034b50;
+const CENTRAL_HEADER = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+/** Deflated, per the ZIP spec's compression method field. */
+const DEFLATED = 8;
+/** Stored (no compression). */
+const STORED = 0;
+/** Bit 11 of the general purpose flags declares the filename to be UTF-8. */
+const UTF8_NAMES = 0x0800;
+const CRC_TABLE = makeCRCTable();
+function makeCRCTable() {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let bit = 0; bit < 8; bit++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[i] = c >>> 0;
+    }
+    return table;
+}
+/** The CRC-32 of the given bytes, as the ZIP spec defines it. */
+export function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Compress with raw DEFLATE, or return undefined if the platform can't.
+ *
+ * The bytes are pushed through the stream directly rather than via
+ * `Blob.stream()`, which keeps this working everywhere web streams exist --
+ * including jsdom, whose Blob has no `stream()`.
+ */
+async function deflate(bytes) {
+    if (typeof CompressionStream === 'undefined')
+        return undefined;
+    try {
+        const stream = new CompressionStream('deflate-raw');
+        // Typed explicitly: a bare Uint8Array is generic over its buffer, and
+        // the DOM types require one that is not shared.
+        const writer = stream.writable.getWriter();
+        // Deliberately not awaited before reading: a large chunk can exceed the
+        // stream's queue, and the write only settles once the reader drains it.
+        const written = writer.write(bytes).then(() => writer.close());
+        const reader = stream.readable.getReader();
+        const chunks = [];
+        let length = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            length += value.length;
+        }
+        await written;
+        const deflated = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            deflated.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return deflated;
+    }
+    catch {
+        // A platform with the constructor but without 'deflate-raw'.
+        return undefined;
+    }
+}
+/**
+ * DOS date and time, which is what ZIP stores. Seconds have two-second
+ * resolution and years are relative to 1980; both are the format's, not ours.
+ */
+function dosDateTime(date) {
+    return {
+        date: (Math.max(0, date.getFullYear() - 1980) << 9) |
+            ((date.getMonth() + 1) << 5) |
+            date.getDate(),
+        time: (date.getHours() << 11) |
+            (date.getMinutes() << 5) |
+            (date.getSeconds() >> 1),
+    };
+}
+export default class Zip {
+    #encoder = new TextEncoder();
+    #pending = [];
+    #modified;
+    /**
+     * @param modified the timestamp recorded for every entry. Defaults to now;
+     * tests pass a fixed date so output is byte-for-byte reproducible.
+     */
+    constructor(modified = new Date()) {
+        this.#modified = modified;
+    }
+    /**
+     * Queue a file. Entries are written in the order added, which is how the
+     * EPUB `mimetype` requirement is met: add it first, stored.
+     *
+     * @param store true to skip compression. Pass it for `mimetype` (required)
+     * and for already-compressed payloads like JPEGs, where deflating costs
+     * time and saves nothing.
+     */
+    add(path, bytes, store = false) {
+        this.#pending.push({
+            path,
+            bytes: typeof bytes === 'string' ? this.#encoder.encode(bytes) : bytes,
+            store,
+        });
+    }
+    /** The number of files queued. */
+    get size() {
+        return this.#pending.length;
+    }
+    /** Assemble the archive. */
+    async toBlob(type = 'application/zip') {
+        const { date, time } = dosDateTime(this.#modified);
+        const entries = [];
+        const parts = [];
+        let offset = 0;
+        for (const { path, bytes, store } of this.#pending) {
+            const name = this.#encoder.encode(path);
+            const compressed = store ? undefined : await deflate(bytes);
+            // Only take the compressed form if it actually helped.
+            const useDeflate = compressed !== undefined && compressed.length < bytes.length;
+            const data = useDeflate ? compressed : bytes;
+            const entry = {
+                name,
+                data,
+                crc: crc32(bytes),
+                size: bytes.length,
+                method: useDeflate ? DEFLATED : STORED,
+                offset,
+            };
+            entries.push(entry);
+            const header = new Uint8Array(30 + name.length);
+            const view = new DataView(header.buffer);
+            view.setUint32(0, LOCAL_HEADER, true);
+            view.setUint16(4, 20, true); // version needed
+            view.setUint16(6, UTF8_NAMES, true);
+            view.setUint16(8, entry.method, true);
+            view.setUint16(10, time, true);
+            view.setUint16(12, date, true);
+            view.setUint32(14, entry.crc, true);
+            view.setUint32(18, data.length, true); // compressed size
+            view.setUint32(22, entry.size, true); // uncompressed size
+            view.setUint16(26, name.length, true);
+            view.setUint16(28, 0, true); // extra field length
+            header.set(name, 30);
+            parts.push(header, data);
+            offset += header.length + data.length;
+        }
+        const directoryOffset = offset;
+        for (const entry of entries) {
+            const header = new Uint8Array(46 + entry.name.length);
+            const view = new DataView(header.buffer);
+            view.setUint32(0, CENTRAL_HEADER, true);
+            view.setUint16(4, 20, true); // version made by
+            view.setUint16(6, 20, true); // version needed
+            view.setUint16(8, UTF8_NAMES, true);
+            view.setUint16(10, entry.method, true);
+            view.setUint16(12, time, true);
+            view.setUint16(14, date, true);
+            view.setUint32(16, entry.crc, true);
+            view.setUint32(20, entry.data.length, true);
+            view.setUint32(24, entry.size, true);
+            view.setUint16(28, entry.name.length, true);
+            view.setUint16(30, 0, true); // extra field length
+            view.setUint16(32, 0, true); // comment length
+            view.setUint16(34, 0, true); // disk number
+            view.setUint16(36, 0, true); // internal attributes
+            view.setUint32(38, 0, true); // external attributes
+            view.setUint32(42, entry.offset, true);
+            header.set(entry.name, 46);
+            parts.push(header);
+            offset += header.length;
+        }
+        const end = new Uint8Array(22);
+        const endView = new DataView(end.buffer);
+        endView.setUint32(0, END_OF_CENTRAL_DIRECTORY, true);
+        endView.setUint16(4, 0, true); // disk number
+        endView.setUint16(6, 0, true); // disk with directory
+        endView.setUint16(8, entries.length, true);
+        endView.setUint16(10, entries.length, true);
+        endView.setUint32(12, offset - directoryOffset, true);
+        endView.setUint32(16, directoryOffset, true);
+        endView.setUint16(20, 0, true); // comment length
+        parts.push(end);
+        return new Blob(parts, { type });
+    }
+}

package/dist/epub/zip.test.d.ts

@@ -0,0 +1 @@
+export {};