bookish-press 0.9.3 → 0.9.5

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/components/page/DownloadEPUB.svelte

@@ -5,6 +5,7 @@ import { DEFAULT_SIZE, SIZES } from "../../epub/images";
 let edition = getEdition();
 let base = getBase();
 let sizeID = $state(DEFAULT_SIZE.id);
+let grayscale = $state(false);
 let building = $state(false);
 let progress = $state(void 0);
 let error = $state(void 0);
@@ -17,12 +18,19 @@ function release() {
     url = void 0;
   }
 }
-function chooseSize(id) {
-  sizeID = id;
+function invalidate() {
   release();
   warnings = [];
   error = void 0;
 }
+function chooseSize(id) {
+  sizeID = id;
+  invalidate();
+}
+function chooseGrayscale(on) {
+  grayscale = on;
+  invalidate();
+}
 async function build() {
   if ($edition === void 0 || building) return;
   building = true;
@@ -34,6 +42,7 @@ async function build() {
     const result = await buildEPUB($edition, {
       base: $base ?? "",
       size: SIZES[sizeID] ?? DEFAULT_SIZE,
+      grayscale,
       onProgress: (update) => progress = update
     });
     url = URL.createObjectURL(result.blob);
@@ -76,6 +85,19 @@ onDestroy(release);
                 </select>
             </span>
         </label>
+        <label class="greyscale">
+            <input
+                type="checkbox"
+                checked={grayscale}
+                disabled={building}
+                onchange={(event) =>
+                    chooseGrayscale(event.currentTarget.checked)}
+            />
+            Greyscale
+            <span class="note"
+                >(a little smaller; e-readers convert anyway)</span
+            >
+        </label>
         <!-- A plain button rather than the app's, whose --app-* variables are
              only defined in the (app) layout, so it renders unstyled here and
              in books compiled by bookish-reader. -->
@@ -226,6 +248,14 @@ onDestroy(release);
         text-decoration: underline;
     }
 
+    .greyscale {
+        gap: 0.35em;
+    }
+
+    .greyscale .note {
+        color: var(--bookish-muted-color);
+    }
+
     .warnings {
         font-size: var(--bookish-small-font-size);
         font-style: italic;

package/dist/components/page/TableOfContents.svelte

@@ -268,33 +268,41 @@ onMount(() => {
         <Acknowledgements />
         <License />
 
-        <EditableHeader id="print" label="Edit print header" />
+        <!-- Both of these are ways of getting the book off the screen, so
+             neither belongs on a printed page: one points at the print view you
+             would already be looking at, and the other is a dropdown, a
+             checkbox and a button. -->
+        <div class="screen-only">
+            <EditableHeader id="print" label="Edit print header" />
 
-        <Instructions {editable}>
-            This link will generate the entire book on a single page, suitable
-            for printing.
-        </Instructions>
+            <Instructions {editable}>
+                This link will generate the entire book on a single page,
+                suitable for printing.
+            </Instructions>
 
-        <PageParagraph>
-            Want to print this book or generate a PDF? See <Link
-                to="{$base}/print">all chapters on a single page</Link
-            > and then print or export. Long books can take some time to render.
-        </PageParagraph>
+            <PageParagraph>
+                Want to print this book or generate a PDF? See <Link
+                    to="{$base}/print">all chapters on a single page</Link
+                > and then print or export. Long books can take some time to render.
+            </PageParagraph>
+        </div>
 
-        <EditableHeader id="epub" label="Edit e-book header" />
+        <div class="screen-only">
+            <EditableHeader id="epub" label="Edit e-book header" />
 
-        <Instructions {editable}>
-            This builds an EPUB in the reader's browser. Nothing is uploaded and
-            no server is involved.
-        </Instructions>
+            <Instructions {editable}>
+                This builds an EPUB in the reader's browser. Nothing is uploaded
+                and no server is involved.
+            </Instructions>
 
-        <PageParagraph>
-            Reading on an e-reader? Build an EPUB of this book. Images are
-            shrunk to fit the size you choose, so pick the one closest to your
-            device. Long books with many images can take a minute.
-        </PageParagraph>
+            <PageParagraph>
+                Reading on an e-reader? Build an EPUB of this book. Images are
+                shrunk to fit the size you choose, so pick the one closest to
+                your device. Long books with many images can take a minute.
+            </PageParagraph>
 
-        <DownloadEPUB />
+            <DownloadEPUB />
+        </div>
 
         <EditableHeader id="citation" label="Edit citation header" />
 
@@ -370,4 +378,10 @@ onMount(() => {
     .etc {
         white-space: nowrap;
     }
+
+    @media print {
+        .screen-only {
+            display: none;
+        }
+    }
 </style>

package/dist/epub/build.d.ts

@@ -25,6 +25,12 @@ export type BuildOptions = {
     /** The book's base path, for resolving local image URLs. */
     base?: string;
     size?: ImageSize;
+    /**
+     * Discard color from every image. Off by default: it saves under a tenth of
+     * the bytes, and an e-ink reader desaturates on display anyway, so throwing
+     * colour away here only costs it on every other device.
+     */
+    grayscale?: boolean;
     onProgress?: (progress: BuildProgress) => void;
     /** Fixed timestamp, so tests can compare output. */
     modified?: Date;

package/dist/epub/build.js

@@ -27,7 +27,7 @@ export function identifierFor(edition) {
 }
 /** Build an EPUB for the given edition. */
 export async function buildEPUB(edition, options = {}) {
-    const { base = '', size = DEFAULT_SIZE, onProgress, modified = new Date(), } = options;
+    const { base = '', size = DEFAULT_SIZE, grayscale = false, onProgress, modified = new Date(), } = options;
     const warnings = [];
     const chapters = includedChapters(edition);
     // Collect every distinct image the book uses. getEmbeds walks the cover,
@@ -36,17 +36,30 @@ export async function buildEPUB(edition, options = {}) {
     const embeds = new Map();
     if (coverEmbed)
         embeds.set(coverEmbed.getURL(), coverEmbed);
-    for (const { embed } of edition.getEmbeds())
+    // Only the pages that actually make it into the package. getEmbeds() also
+    // returns header images for the index, search and media pages, and for
+    // forthcoming chapters, none of which are exported -- fetching and shrinking
+    // those costs the reader time and bytes for something never shown.
+    const included = new Set([
+        ...chapters.map((chapter) => chapter.getID()),
+        'references',
+        'glossary',
+    ]);
+    for (const { embed, chapterID } of edition
+        .getEmbeds()
+        .filter(({ chapterID }) => chapterID === undefined || included.has(chapterID))) {
+        void chapterID;
         // Videos are links in the package, not files, and an embed with no URL
         // is an empty placeholder the author hasn't filled in yet.
         if (!embed.isVideo() && embed.getURL().trim().length > 0)
             if (!embeds.has(embed.getURL()))
                 embeds.set(embed.getURL(), embed);
+    }
     const urls = [...embeds.keys()];
     onProgress?.({ phase: 'images', done: 0, total: urls.length });
     let fetched = 0;
     const prepared = await mapWithLimit(urls, IMAGE_CONCURRENCY, async (url) => {
-        const image = await prepareImage(resolveImageURL(url, base), size);
+        const image = await prepareImage(resolveImageURL(url, base), size, grayscale);
         onProgress?.({
             phase: 'images',
             done: ++fetched,

package/dist/epub/build.test.js

@@ -451,3 +451,68 @@ test('every packaged image is referenced by a document', async () => {
     const orphans = images.filter((image) => !markup.includes(`"${image}"`));
     expect(orphans, `packaged but never referenced: ${orphans.join(', ')}`).toEqual([]);
 });
+test('a reference url that is not a URL does not become a broken link', async () => {
+    // Real books put bare DOIs, ISBNs and stray prose in the url field. Emitting
+    // those as an href produces a relative link that resolves against the
+    // package, which epubcheck reports as a missing resource.
+    const edition = makeEdition({
+        chapters: [chapter('one', 'One', 'Claims<doi><bare><isbn><prose>.')],
+        references: {
+            doi: ['A', '2020', 'Prefixed DOI', 'S', 'doi: 10.3390/s22134794'],
+            bare: ['B', '2020', 'Bare DOI', 'S', '10.21606/dma.2017.679'],
+            isbn: ['C', '2020', 'An ISBN', 'S', 'ISBN 9780128053904'],
+            prose: [
+                'D',
+                '2020',
+                'Prose',
+                'S',
+                ' In Proceedings of CHI (pp. 1)',
+            ],
+        },
+    });
+    const { entries } = await build(edition);
+    const references = textOf(entries, 'OEBPS/references.xhtml');
+    // Both DOI forms resolve through doi.org.
+    expect(references).toContain('href="https://doi.org/10.3390/s22134794"');
+    expect(references).toContain('href="https://doi.org/10.21606/dma.2017.679"');
+    // The others keep their titles but gain no link.
+    expect(references).toContain('An ISBN');
+    expect(references).toContain('Prose');
+    // No link in the reference list is relative; a relative one would resolve
+    // against the package and be reported as a missing resource.
+    for (const [, href] of references.matchAll(/<a href="([^"]+)"/g))
+        expect(href, `relative href: ${href}`).toMatch(/^(https?:|#)/);
+});
+test('images are not packaged for pages the export leaves out', async () => {
+    // getEmbeds() also returns header images for the index, search and media
+    // pages and for forthcoming chapters, none of which are exported. Fetching
+    // and shrinking those costs the reader bytes for something never shown.
+    const edition = makeEdition({
+        images: {
+            cover: '|cover.jpg|Cover|||',
+            index: '|indexhead.jpg|Index header|||',
+            search: '|searchhead.jpg|Search header|||',
+            media: '|mediahead.jpg|Media header|||',
+        },
+        chapters: [
+            chapter('one', 'One', 'Text.', {
+                image: '|onehead.jpg|One header|||',
+            }),
+            chapter('soon', 'Soon', '', {
+                forthcoming: true,
+                image: '|soonhead.jpg|Forthcoming header|||',
+            }),
+        ],
+    });
+    await build(edition);
+    const fetched = vi.mocked(fetch).mock.calls.map((call) => String(call[0]));
+    expect(fetched.some((url) => url.includes('cover.jpg'))).toBe(true);
+    expect(fetched.some((url) => url.includes('onehead.jpg'))).toBe(true);
+    for (const skipped of [
+        'indexhead.jpg',
+        'searchhead.jpg',
+        'mediahead.jpg',
+        'soonhead.jpg',
+    ])
+        expect(fetched.some((url) => url.includes(skipped)), `${skipped} was fetched for a page that is not exported`).toBe(false);
+});

package/dist/epub/images.d.ts

@@ -20,14 +20,16 @@ export type ImageSize = {
     maxHeight: number;
     /** JPEG quality, 0 to 1. */
     quality: number;
-    /** Whether to discard color. E-ink panels below ~1000px are greyscale. */
-    grayscale: boolean;
 };
 /**
  * The presets offered to readers. Standard covers the common 6-7" e-ink panels
  * at native resolution (Kobo Clara 1072x1448, Kindle Paperwhite 1236x1648);
- * Compact targets pocket-sized greyscale readers; Large leaves room to zoom
- * into diagrams on a tablet.
+ * Compact targets pocket-sized readers; Large leaves room to zoom into diagrams
+ * on a tablet.
+ *
+ * A preset governs how large an image may be, not what colour it is. Discarding
+ * colour is a separate choice, because an EPUB is read on whatever device is to
+ * hand and colour thrown away here cannot be recovered there.
  */
 export declare const SIZES: Record<string, ImageSize>;
 export declare const DEFAULT_SIZE: ImageSize;
@@ -71,7 +73,7 @@ export declare function resolveImageURL(url: string, base: string): string;
  * or that are simply gone. Callers report those as warnings and drop the image,
  * keeping its caption.
  */
-export declare function prepareImage(url: string, size: ImageSize): Promise<PreparedImage | undefined>;
+export declare function prepareImage(url: string, size: ImageSize, grayscale?: boolean): Promise<PreparedImage | undefined>;
 /**
  * Run tasks with a bounded number in flight, so a book with a hundred images
  * doesn't open a hundred connections at once.

package/dist/epub/images.js

@@ -13,8 +13,12 @@
 /**
  * The presets offered to readers. Standard covers the common 6-7" e-ink panels
  * at native resolution (Kobo Clara 1072x1448, Kindle Paperwhite 1236x1648);
- * Compact targets pocket-sized greyscale readers; Large leaves room to zoom
- * into diagrams on a tablet.
+ * Compact targets pocket-sized readers; Large leaves room to zoom into diagrams
+ * on a tablet.
+ *
+ * A preset governs how large an image may be, not what colour it is. Discarding
+ * colour is a separate choice, because an EPUB is read on whatever device is to
+ * hand and colour thrown away here cannot be recovered there.
  */
 export const SIZES = {
     compact: {
@@ -23,7 +27,6 @@ export const SIZES = {
         maxWidth: 480,
         maxHeight: 640,
         quality: 0.7,
-        grayscale: true,
     },
     standard: {
         id: 'standard',
@@ -33,7 +36,6 @@ export const SIZES = {
         maxWidth: 1280,
         maxHeight: 1720,
         quality: 0.8,
-        grayscale: false,
     },
     large: {
         id: 'large',
@@ -41,7 +43,6 @@ export const SIZES = {
         maxWidth: 1600,
         maxHeight: 2200,
         quality: 0.85,
-        grayscale: false,
     },
 };
 export const DEFAULT_SIZE = SIZES.standard;
@@ -110,7 +111,7 @@ const FETCH_TIMEOUT_MS = 20000;
  * or that are simply gone. Callers report those as warnings and drop the image,
  * keeping its caption.
  */
-export async function prepareImage(url, size) {
+export async function prepareImage(url, size, grayscale = false) {
     let bytes;
     let mediaType;
     try {
@@ -134,7 +135,7 @@ export async function prepareImage(url, size) {
     // wasteful and unreliable across browsers.
     if (mediaType === 'image/svg+xml')
         return passThrough(bytes, mediaType);
-    const reencoded = await reencode(bytes, mediaType, size);
+    const reencoded = await reencode(bytes, mediaType, size, grayscale);
     if (reencoded === undefined)
         return passThrough(bytes, mediaType);
     // Keep whichever is smaller, since re-encoding can inflate a file: resizing
@@ -142,8 +143,12 @@ export async function prepareImage(url, size) {
     // be larger than the crisp original. But an image far past the budget is
     // shrunk regardless, because decoding it costs a small reader memory it may
     // not have, and a few extra kilobytes are the cheaper price.
+    //
+    // Greyscale overrides the size comparison too: it was asked for, and an
+    // image small enough to pass through untouched would otherwise come out in
+    // colour while everything around it was grey.
     const { oversize, ...prepared } = reencoded;
-    return oversize || prepared.bytes.length < bytes.length
+    return oversize || grayscale || prepared.bytes.length < bytes.length
         ? prepared
         : passThrough(bytes, mediaType);
 }
@@ -153,7 +158,7 @@ export async function prepareImage(url, size) {
  * size. Returns undefined if the platform lacks the canvas APIs or the bytes
  * don't decode.
  */
-async function reencode(bytes, mediaType, size) {
+async function reencode(bytes, mediaType, size, grayscale) {
     if (typeof createImageBitmap === 'undefined' ||
         typeof document === 'undefined')
         return undefined;
@@ -173,7 +178,7 @@ async function reencode(bytes, mediaType, size) {
         if (context === null)
             return undefined;
         context.drawImage(bitmap, 0, 0, width, height);
-        if (size.grayscale)
+        if (grayscale)
             desaturate(context, width, height);
         // PNG first, while any transparency is still intact.
         const png = await toBlob(canvas, 'image/png');

package/dist/epub/images.test.js

@@ -34,17 +34,12 @@ test('treats a degenerate image as empty rather than dividing by zero', () => {
     expect(fitWithin(0, 0, 1200, 1600)).toEqual({ width: 0, height: 0 });
     expect(fitWithin(-5, 10, 1200, 1600)).toEqual({ width: 0, height: 0 });
 });
-test('every preset is smaller than the next and shaped for its device', () => {
+test('every preset is smaller than the next', () => {
     const { compact, standard, large } = SIZES;
     expect(compact.maxWidth).toBeLessThan(standard.maxWidth);
     expect(standard.maxWidth).toBeLessThan(large.maxWidth);
     expect(compact.maxHeight).toBeLessThan(standard.maxHeight);
     expect(standard.maxHeight).toBeLessThan(large.maxHeight);
-    // Pocket e-ink panels are greyscale; the bigger presets are read on
-    // devices that can show color.
-    expect(compact.grayscale).toBe(true);
-    expect(standard.grayscale).toBe(false);
-    expect(large.grayscale).toBe(false);
     for (const size of Object.values(SIZES)) {
         expect(size.quality).toBeGreaterThan(0);
         expect(size.quality).toBeLessThanOrEqual(1);
@@ -127,3 +122,10 @@ test('never asks to shrink an image that already fits', () => {
         expect(exceedsBudget(size.maxWidth, size.maxHeight, size)).toBe(false);
     expect(exceedsBudget(100, 100, SIZES.compact)).toBe(false);
 });
+test('a preset says nothing about colour', () => {
+    // Colour is a separate choice: a preset is about how large an image may be,
+    // and an EPUB is read on whatever device is to hand, so colour discarded
+    // here cannot be recovered there.
+    for (const size of Object.values(SIZES))
+        expect(size).not.toHaveProperty('grayscale');
+});

package/dist/epub/package.js

@@ -237,6 +237,27 @@ ${authors.length > 0
             : chapter.getTitle(),
     };
 }
+/**
+ * A reference's url field as an absolute address, or undefined if it isn't one.
+ *
+ * Real books put all sorts of things in that field: a bare DOI, a DOI with a
+ * "doi:" prefix, an ISBN, sometimes a fragment of the citation itself. Emitting
+ * those as an href produces a *relative* link that resolves against the package
+ * and fails validation, so only something that can be made absolute is linked.
+ */
+function referenceURL(url) {
+    const value = String(url ?? '').trim();
+    if (value.length === 0)
+        return undefined;
+    if (/^https?:\/\//i.test(value))
+        return encodeURI(value);
+    // A DOI is unambiguous and resolvable, so it's worth turning into a link.
+    const doi = value.replace(/^doi:\s*/i, '').trim();
+    if (/^10\.\d{4,9}\/\S+$/.test(doi))
+        return `https://doi.org/${encodeURI(doi)}`;
+    // An ISBN, a stray sentence, anything else: render it as text, not a link.
+    return undefined;
+}
 /** Render a reference the way the web reader's Reference.svelte does. */
 function referenceContent(reference, context) {
     if (reference instanceof FormatNode)
@@ -244,9 +265,10 @@ function referenceContent(reference, context) {
     const title = escapeText(reference.title);
     // The web reader omits the period when the title already ends in one.
     const period = reference.title.trim().endsWith('?') ? '' : '.';
-    return `${escapeText(reference.authors)} (${escapeText(reference.year)}). ${reference.url
-        ? `<a href="${escapeAttribute(encodeURI(String(reference.url)))}">${title}</a>`
-        : title}${period} <em>${escapeText(reference.source)}</em>${reference.summary ? ` ${escapeText(reference.summary)}` : ''}`;
+    return `${escapeText(reference.authors)} (${escapeText(reference.year)}). ${(() => {
+        const href = referenceURL(reference.url);
+        return href ? `<a href="${escapeAttribute(href)}">${title}</a>` : title;
+    })()}${period} <em>${escapeText(reference.source)}</em>${reference.summary ? ` ${escapeText(reference.summary)}` : ''}`;
 }
 /** The references back matter, whose anchors the citations link to. */
 export function referencesDocument(edition, context) {

package/package.json

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