bookish-press 0.9.4 → 0.9.5

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.4",
+    "version": "0.9.5",
     "type": "module",
     "description": "A platform for reading and writing readable, accessible, beautiful online books.",
     "license": "MIT",