bookish-press 0.9.2 → 0.9.4

package/README.md

@@ -50,6 +50,22 @@ The content lives in `scripts/demo-book.js` and the images are drawn by `scripts
 
 It uses the offset emulator ports from `firebase.test.json`, so it doesn't collide with another project's emulators on the default ports, and it builds the app rather than running `vite dev` — the reader route's server render pulls the chapter model through a module cycle that Vite's dev SSR evaluator can't order, though the production build resolves it fine.
 
+## Storage CORS
+
+Book images live in Firebase Storage and are fetched by the browser when
+building an EPUB, which requires the bucket to send CORS headers. It does not
+by default, and without them every image is silently dropped from the export.
+`cors.json` holds the policy; apply it to a project's bucket with:
+
+```
+gcloud storage buckets update gs://<project>.appspot.com --cors-file=cors.json --project <project>
+```
+
+It is applied to both `bookish-prod` and `bookish-dev-21ac3`. The objects are
+already world-readable — the thumbnail function calls `makePublic()` on upload —
+so allowing `GET` from any origin grants nothing that a plain HTTP request
+couldn't already do.
+
 ## Deployment notes
 
 There are two major components to Bookish: the authoring platform and the reading front end. Changes to the authoring platform that do not affect reading can be verified and deployed to Firebase without any other coordination. However, changes to the reading experience have downstream dependencies that need to be managed. Here's the general deployment workflow, which I'm currently using as reminders for myself:

package/dist/epub/build.test.js

@@ -409,3 +409,45 @@ test('a reference whose fields are not strings still exports', async () => {
     expect(references).toContain('-370');
     expect(references).toContain('The Republic');
 });
+test("a chapter's header image is rendered, not just packaged", async () => {
+    // Edition.getEmbeds() collects chapter header images, so they were fetched
+    // and packaged, but chapterDocument never rendered one -- the reader saw
+    // the book cover and nothing else, and paid for the bytes anyway.
+    const edition = makeEdition({
+        chapters: [
+            chapter('one', 'One', 'Text with no images of its own.', {
+                image: '|header.jpg|A header image|A caption|A credit|',
+            }),
+        ],
+    });
+    const { entries } = await build(edition);
+    const one = textOf(entries, 'OEBPS/one.xhtml');
+    expect(one).toContain('<img');
+    expect(one).toContain('A header image');
+    // Above the title, as the web reader places it.
+    expect(one.indexOf('<img')).toBeLessThan(one.indexOf('<h1>'));
+});
+test('every packaged image is referenced by a document', async () => {
+    // The general form of the bug above: an image that is fetched, shrunk and
+    // written into the package but never pointed at is pure weight.
+    const edition = makeEdition({
+        images: { cover: '|cover.jpg|The cover|||' },
+        chapters: [
+            chapter('one', 'One', 'A body image: |body.jpg|Alt|||', {
+                image: '|chapterhead.jpg|A chapter header|||',
+            }),
+            chapter('two', 'Two', 'No images here.', {
+                image: '|another.jpg|Another header|||',
+            }),
+        ],
+    });
+    const { entries } = await build(edition);
+    const documents = [...entries.keys()].filter((path) => path.endsWith('.xhtml'));
+    const markup = documents.map((path) => textOf(entries, path)).join('\n');
+    const images = [...entries.keys()]
+        .filter((path) => path.startsWith('OEBPS/images/'))
+        .map((path) => path.replace('OEBPS/', ''));
+    expect(images.length).toBeGreaterThan(2);
+    const orphans = images.filter((image) => !markup.includes(`"${image}"`));
+    expect(orphans, `packaged but never referenced: ${orphans.join(', ')}`).toEqual([]);
+});

package/dist/epub/package.js

@@ -7,7 +7,8 @@
 import Reference from '../models/book/Reference';
 import FormatNode from '../models/chapter/FormatNode';
 import Parser from '../models/chapter/Parser';
-import { chapterPath, document_, endnoteSection, escapeAttribute, escapeText, serializeChapter, serializeFormat, } from './xhtml';
+import EmbedNode from '../models/chapter/EmbedNode';
+import { chapterPath, document_, endnoteSection, escapeAttribute, escapeText, serializeChapter, serializeEmbed, serializeFormat, } from './xhtml';
 export const MIMETYPE = 'application/epub+zip';
 /** Where the package's documents live inside the archive. */
 export const CONTENT_DIRECTORY = 'OEBPS';
@@ -149,6 +150,18 @@ export function safeFilename(title) {
         .toLowerCase();
     return cleaned.length > 0 ? cleaned.slice(0, 80) : 'book';
 }
+/**
+ * A chapter or back-matter page's header image, rendered the way the web
+ * reader does: above the title, with its caption and credit. The image is
+ * stored as Bookdown and already packaged by Edition.getEmbeds(), so this only
+ * has to render it.
+ */
+function headerImage(edition, image, context) {
+    if (image === null || image.trim().length === 0)
+        return '';
+    const node = Parser.parseEmbed(edition, image);
+    return node instanceof EmbedNode ? serializeEmbed(node, context) : '';
+}
 /** The plain-text form of a Bookdown string, for metadata. */
 function text(edition, bookdown) {
     return Parser.parseFormat(edition, bookdown).toText().trim();
@@ -203,6 +216,7 @@ export function chapterDocument(edition, chapter, context) {
     const section = chapter.getSection();
     const authors = chapter.getAuthors();
     const header = `<header>
+${headerImage(edition, chapter.getImage(), context)}
 ${number !== undefined
         ? `<span class="chapter-number">Chapter ${number}</span>`
         : ''}
@@ -242,6 +256,7 @@ export function referencesDocument(edition, context) {
         return undefined;
     const header = edition.getHeader('references');
     const body = `<section epub:type="bibliography">
+${headerImage(edition, edition.getImage('references'), context)}
 <h1>${escapeText(header)}</h1>
 ${ids
         .map((id) => `<p class="reference" id="ref-${escapeAttribute(id)}">${referenceContent(references[id], context)}</p>`)
@@ -267,6 +282,7 @@ export function glossaryDocument(edition, context) {
     // content, so there is no way to put a block inside it that would survive.
     // The semantics are carried by the classes instead.
     const body = `<section epub:type="glossary">
+${headerImage(edition, edition.getImage('glossary'), context)}
 <h1>${escapeText(header)}</h1>
 ${ids
         .map((id) => {

package/dist/epub/xhtml.d.ts

@@ -13,6 +13,7 @@
  */
 import type Edition from '../models/book/Edition';
 import type ChapterNode from '../models/chapter/ChapterNode';
+import EmbedNode from '../models/chapter/EmbedNode';
 import FormatNode from '../models/chapter/FormatNode';
 /**
  * Escape text content. Order matters: ampersands first, or we escape our own
@@ -56,6 +57,11 @@ export declare function serializeChapter(chapter: ChapterNode, context: Serializ
 };
 /** The document filename for a chapter. */
 export declare function chapterPath(chapterID: string): string;
+/**
+ * Serialize a standalone embed, for the header images that a chapter and the
+ * back matter pages carry. Those are stored as Bookdown, parsed by the caller.
+ */
+export declare function serializeEmbed(node: EmbedNode, context: SerializationContext): string;
 /** Serialize a standalone format node, for titles, captions and definitions. */
 export declare function serializeFormat(node: FormatNode, context: SerializationContext): string;
 /** Render gathered footnotes as an endnote section with links back to the text. */

package/dist/epub/xhtml.js

@@ -326,6 +326,18 @@ function definition(node, local) {
         ? phrase
         : `<a class="definition" href="glossary.xhtml#gloss-${escapeAttribute(id)}">${phrase}</a>`;
 }
+/**
+ * Serialize a standalone embed, for the header images that a chapter and the
+ * back matter pages carry. Those are stored as Bookdown, parsed by the caller.
+ */
+export function serializeEmbed(node, context) {
+    return embed(node, {
+        ...context,
+        footnotes: [],
+        headers: [],
+        endnotes: [],
+    });
+}
 /** Serialize a standalone format node, for titles, captions and definitions. */
 export function serializeFormat(node, context) {
     return inline(node, {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "bookish-press",
     "private": false,
-    "version": "0.9.2",
+    "version": "0.9.4",
     "type": "module",
     "description": "A platform for reading and writing readable, accessible, beautiful online books.",
     "license": "MIT",