bookish-press 0.8.2 → 0.9.2

package/README.md

@@ -12,6 +12,44 @@ The app is a SvelteKit app. Server-side rendering runs on a [Cloud Run](https://
 
 One-time setup on a new machine: install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) and run `gcloud auth login`. (This replaced the experimental Firebase Hosting "web frameworks" integration, which required `firebase experiments:enable webframeworks` and capped the Vite version; the old auto-generated `ssrbookishprod` Cloud Function can be deleted once the Cloud Run deploy is verified.)
 
+## The demo book
+
+`npm run demo` seeds a book that uses every feature Bookish has into a set of
+dedicated emulators, then serves it at <http://localhost:5173/demo>. Nothing is
+uploaded and no sign-in is needed to read it; sign in as `demo@example.com` at
+`/login` to edit it at `/write/demo/1`.
+
+It exists so a change to the reading experience can be checked against
+something real without hunting for a book that happens to exercise it. The
+chapters cover every Bookdown construct — formatting, links of each kind,
+footnotes, citations, definitions, lists, tables, quotes, callouts, code,
+symbols, labels, comments — and the images are chosen to stress a small screen:
+a photograph with fine texture, a diagram of hairlines, a stepped grey wedge,
+extreme aspect ratios, transparency, and an SVG. That makes it the fastest way
+to see what an EPUB export actually looks like on an e-reader.
+
+The content lives in `scripts/demo-book.js` and the images are drawn by
+`scripts/demo-images.js` rather than committed. Chapters must not use the ids
+the reader reserves for its built-in pages (`references`, `search`, `media`,
+`index`, `glossary`, `unknown`, `cover`); the seed script refuses to run if one
+does.
+
+It uses the offset emulator ports from `firebase.test.json`, so it does not
+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 cannot
+order, though the production build resolves it fine.
+
+## The demo book
+
+`npm run demo` seeds a book that uses every feature Bookish has into a set of dedicated emulators, then serves it at <http://localhost:5173/demo>. Nothing is uploaded and no sign-in is needed to read it; sign in as `demo@example.com` at `/login` to edit it at `/write/demo/1`.
+
+It exists so a change to the reading experience can be checked against something real without hunting for a book that happens to exercise it. The chapters cover every Bookdown construct — formatting, links of each kind, footnotes, citations, definitions, lists, tables, quotes, callouts, code, symbols, labels, comments — and the images are chosen to stress a small screen: a photograph with fine texture, a diagram of hairlines, a stepped grey wedge, extreme aspect ratios, transparency, and an SVG. That makes it the fastest way to see what an EPUB export actually looks like on an e-reader.
+
+The content lives in `scripts/demo-book.js` and the images are drawn by `scripts/demo-images.js` rather than committed. Chapters must not use the ids the reader reserves for its built-in pages (`references`, `search`, `media`, `index`, `glossary`, `unknown`, `cover`); the seed script refuses to run if one does.
+
+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.
+
 ## 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:
@@ -19,14 +57,15 @@ There are two major components to Bookish: the authoring platform and the readin
 0. Ensure you're working in the `dev` branch
 1. Fix bugs, add features
 2. Ensure there are no type errors (`npm run check`) or failed tests (`npm run test`).
-2. Test with emulator (`npm run emu`), if possible. (Some features aren't possible to perfectly emulate, such as authentication, hosting configurations, permissions.)
-3. Test on the [staging server](https://bookish-dev-21ac3.web.app/`) (`npm run stage`).
-4. Bump the version in `package.json`
-5. Describe the changes in `CHANGELOG.md`, linking to any issues closed
-6. Commit changes to `dev`, referring to any issues addressed
-7. Release to production (`npm run release`)
-8. Verify the change in production on [bookish.press](https://bookish.press)
-9. Merge dev to main (`npm run merge`)
+3. Test with emulator (`npm run emu`), if possible. (Some features aren't possible to perfectly emulate, such as authentication, hosting configurations, permissions.)
+4. Test on the [staging server](https://bookish-dev-21ac3.web.app/`) (`npm run stage`).
+5. Bump the version in `package.json`
+6. Describe the changes in `CHANGELOG.md`, linking to any issues closed
+7. Commit changes to `dev`, referring to any issues addressed
+8. Release to production (`npm run release`)
+9. Verify the change in production on [bookish.press](https://bookish.press)
+10. Merge dev to main (`npm run merge`)
+
 > **Svelte 5 note**: as of 0.8.0, `bookish-press` requires Svelte 5 (declared as a peer dependency), which is a breaking change for consumers. Until `bookish-reader` has been migrated to Svelte 5, publish with `npm publish --tag next` so `latest` keeps pointing at the last Svelte 4 compatible release; flip the tag once the reader has migrated. The `0.7.x` branch exists for emergency maintenance releases of the Svelte 4 line.
 
 10. If any of the changes affected the reading experience (essentially if any `.svelte` file or its dependencies in `/src/lib/components` changed), then we need to update the reader package for authors who pre-build their books manually:
@@ -41,4 +80,4 @@ There are two major components to Bookish: the authoring platform and the readin
         1. Cloning the reader repo: `git clone https://github.com/amyjko/bookish-reader`
         2. Entering the repo directory: `cd bookish-reader`
         3. Binding the book: `bind.sh`
-        4. Deploying the bound book in the newly created `build` folder to wherever it's hosted.
+        4. Deploying the bound book in the newly created `build` folder to wherever it's hosted.

package/dist/components/chapter/Code.svelte

@@ -136,7 +136,7 @@ function handleChange() {
         .token.char,
         .token.builtin,
         .token.inserted {
-            color: var(--bookish-pragraph-color);
+            color: var(--bookish-paragraph-color);
         }
 
         .token.operator,

package/dist/components/editor/EmbedEditor.svelte

@@ -123,7 +123,7 @@ function handleImageSelection(image) {
     }
 
     .file-upload {
-        font-family: var(--bookish-app-font);
+        font-family: var(--app-font);
         font-size: var(--app-chrome-font-size);
     }
 

package/dist/components/page/DownloadEPUB.svelte

@@ -0,0 +1,234 @@
+<script lang="ts">import { onDestroy } from "svelte";
+import { getBase, getEdition } from "./Contexts";
+import { buildEPUB } from "../../epub/build";
+import { DEFAULT_SIZE, SIZES } from "../../epub/images";
+let edition = getEdition();
+let base = getBase();
+let sizeID = $state(DEFAULT_SIZE.id);
+let building = $state(false);
+let progress = $state(void 0);
+let error = $state(void 0);
+let warnings = $state([]);
+let url = $state(void 0);
+let filename = $state("book.epub");
+function release() {
+  if (url !== void 0) {
+    URL.revokeObjectURL(url);
+    url = void 0;
+  }
+}
+function chooseSize(id) {
+  sizeID = id;
+  release();
+  warnings = [];
+  error = void 0;
+}
+async function build() {
+  if ($edition === void 0 || building) return;
+  building = true;
+  release();
+  error = void 0;
+  warnings = [];
+  progress = { phase: "images", done: 0, total: 0 };
+  try {
+    const result = await buildEPUB($edition, {
+      base: $base ?? "",
+      size: SIZES[sizeID] ?? DEFAULT_SIZE,
+      onProgress: (update) => progress = update
+    });
+    url = URL.createObjectURL(result.blob);
+    filename = result.filename;
+    warnings = result.warnings;
+  } catch (problem) {
+    console.error(problem);
+    error = "Something went wrong building the e-book.";
+  } finally {
+    building = false;
+    progress = void 0;
+  }
+}
+let status = $derived.by(() => {
+  if (progress === void 0) return void 0;
+  if (progress.phase === "images")
+    return progress.total === 0 ? "Gathering images\u2026" : `Shrinking image ${progress.done} of ${progress.total}\u2026`;
+  if (progress.phase === "chapters")
+    return `Preparing chapter ${progress.done} of ${progress.total}\u2026`;
+  return "Packaging the book\u2026";
+});
+onDestroy(release);
+</script>
+
+{#if $edition}
+    <div class="epub">
+        <label>
+            Image size
+            <!-- The wrapper carries the disclosure arrow: turning off native
+                 appearance to get the book's font also removes the browser's. -->
+            <span class="select">
+                <select
+                    value={sizeID}
+                    disabled={building}
+                    onchange={(event) => chooseSize(event.currentTarget.value)}
+                >
+                    {#each Object.values(SIZES) as size}
+                        <option value={size.id}>{size.label}</option>
+                    {/each}
+                </select>
+            </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. -->
+        <button
+            type="button"
+            title="Build an EPUB of this book to read on an e-reader"
+            aria-label="Build an EPUB of this book to read on an e-reader"
+            disabled={building}
+            onclick={build}>↓ EPUB</button
+        >
+    </div>
+
+    {#if error}
+        <p class="message error" role="alert">{error}</p>
+    {:else if status}
+        <p class="message" role="status" aria-live="polite">{status}</p>
+    {:else if url}
+        <!-- Rendered only once the blob exists, so this link is never present
+             in prerendered HTML for SvelteKit's crawler to follow. -->
+        <p class="ready">
+            <a href={url} download={filename}>Download {filename}</a>
+        </p>
+        {#if warnings.length > 0}
+            <p class="warnings">
+                {warnings.length}
+                {warnings.length === 1 ? 'image' : 'images'} couldn't be included,
+                usually because they're hosted somewhere that doesn't allow downloads.
+                Their captions are still in the book.
+            </p>
+        {/if}
+    {/if}
+{/if}
+
+<style>
+    /* Everything here is drawn with the book's own --bookish-* variables, which
+       are defined on the .bookish ancestor in Edition.svelte and so are in
+       scope in both the app and in books compiled by bookish-reader. The
+       --app-* chrome variables are not: they exist only in the (app) layout. */
+
+    .epub {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.5em;
+        margin-block: var(--bookish-paragraph-spacing);
+    }
+
+    label {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.5em;
+        font-family: var(--bookish-paragraph-font-family);
+        font-size: var(--bookish-small-font-size);
+        color: var(--bookish-muted-color);
+    }
+
+    .select {
+        position: relative;
+        display: inline-block;
+    }
+
+    /* The disclosure arrow, in place of the native one. It inherits the text
+       color, so it follows the theme into dark mode. */
+    .select::after {
+        content: '▾';
+        position: absolute;
+        right: 0.6em;
+        top: 50%;
+        transform: translateY(-50%);
+        pointer-events: none;
+        font-size: 0.9em;
+        color: var(--bookish-paragraph-color);
+    }
+
+    /* A <select> is a native menulist, and WebKit renders its face in the
+       system font whatever the cascade says until appearance is turned off. */
+    select {
+        appearance: none;
+        -webkit-appearance: none;
+        font-family: var(--bookish-paragraph-font-family);
+        font-size: var(--bookish-small-font-size);
+        font-weight: var(--bookish-paragraph-font-weight);
+        color: var(--bookish-paragraph-color);
+        background: var(--bookish-block-background-color);
+        border: 1px solid var(--bookish-border-color-light);
+        border-radius: var(--bookish-roundedness);
+        padding: var(--bookish-inline-padding);
+        padding-right: 2em;
+        max-width: 18em;
+    }
+
+    button {
+        font-family: var(--bookish-paragraph-font-family);
+        font-size: var(--bookish-small-font-size);
+        font-weight: var(--bookish-bold-font-weight);
+        color: var(--bookish-link-color);
+        background: var(--bookish-block-background-color);
+        border: 1px solid var(--bookish-border-color-light);
+        border-radius: var(--bookish-roundedness);
+        padding: var(--bookish-inline-padding)
+            calc(var(--bookish-inline-padding) * 3);
+        cursor: pointer;
+    }
+
+    button:hover:not(:disabled) {
+        border-color: var(--bookish-highlight-color);
+    }
+
+    /* focus-visible, so a mouse click doesn't leave the ring behind while
+       keyboard users still get one. */
+    select:focus-visible,
+    button:focus-visible {
+        outline: none;
+        border-color: var(--bookish-highlight-color);
+        box-shadow: 0 0 0 2px var(--bookish-highlight-color);
+    }
+
+    select:disabled,
+    button:disabled {
+        opacity: 0.5;
+        cursor: auto;
+    }
+
+    .message,
+    .ready,
+    .warnings {
+        font-family: var(--bookish-paragraph-font-family);
+        line-height: var(--bookish-paragraph-line-height);
+    }
+
+    .message {
+        color: var(--bookish-muted-color);
+    }
+
+    .error {
+        color: var(--bookish-error-color);
+    }
+
+    /* Matches a book link, from components/Link.svelte. */
+    .ready a {
+        color: var(--bookish-link-color);
+        font-weight: var(--bookish-link-font-weight);
+        text-decoration: none;
+    }
+
+    .ready a:hover {
+        text-decoration: underline;
+    }
+
+    .warnings {
+        font-size: var(--bookish-small-font-size);
+        font-style: italic;
+        color: var(--bookish-muted-color);
+    }
+</style>

package/dist/components/page/DownloadEPUB.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const DownloadEPUB: import("svelte").Component<Record<string, never>, {}, "">;
+type DownloadEPUB = ReturnType<typeof DownloadEPUB>;
+export default DownloadEPUB;

package/dist/components/page/Rows.svelte

@@ -28,7 +28,7 @@
     table :global(tr:first-child th) {
         font-weight: bold;
         border: 0;
-        border-bottom: 1px solid var(--bookish-border-color);
+        border-bottom: 1px solid var(--bookish-border-color-light);
     }
 
     table :global(tr:nth-child(even)) {

package/dist/components/page/Search.svelte

@@ -139,7 +139,7 @@ let results = $derived.by(() => {
 <style>
     .query {
         font-family: var(--bookish-header-font-family);
-        font-size: var(--bookish-header-font-size);
+        font-size: var(--bookish-header-1-font-size);
         border: none;
         border-bottom: 3px solid var(--bookish-border-color-light);
         padding: var(--bookish-inline-padding);

package/dist/components/page/TableOfContents.svelte

@@ -24,6 +24,7 @@ import {
 } from "./Contexts";
 import Muted from "./Muted.svelte";
 import Button from "../app/Button.svelte";
+import DownloadEPUB from "./DownloadEPUB.svelte";
 import PageHeader from "./PageHeader.svelte";
 import Rows from "./Rows.svelte";
 import PageParagraph from "./PageParagraph.svelte";
@@ -84,21 +85,18 @@ onMount(() => {
                 $edition ? edition.set($edition.withTitle(text)) : undefined}
         >
             {#snippet before()}
-                    
-                    {#if editable}
-                        <SubdomainEditor />
-                    {/if}
-                
-                    {/snippet}
+                {#if editable}
+                    <SubdomainEditor />
+                {/if}
+            {/snippet}
             {#snippet outline()}
-                        <Outline
-                    
+                <Outline
                     previous={null}
                     next={$edition.getNextChapterID('', editable)}
                 />
-                    {/snippet}
+            {/snippet}
             {#snippet after()}
-                        <div >
+                <div>
                     <Authors
                         editable={isBookEditable()}
                         authors={$edition.getAuthors()}
@@ -108,7 +106,9 @@ onMount(() => {
                                 : undefined}
                         edit={(index, text) =>
                             $edition
-                                ? edition.set($edition.withAuthorName(index, text))
+                                ? edition.set(
+                                      $edition.withAuthorName(index, text),
+                                  )
                                 : undefined}
                         remove={(index) =>
                             $edition
@@ -118,7 +118,7 @@ onMount(() => {
                     />
                     <Note>{$edition.getEditionLabel()} edition</Note>
                 </div>
-                    {/snippet}
+            {/snippet}
         </Header>
 
         <Instructions {editable}>
@@ -130,8 +130,8 @@ onMount(() => {
 
         <Instructions {editable}>
             This will appear on the <Link to="/read">book browsing</Link>
-            page and in your table of contents. Write an informative description
-            of what your book is about.
+            page and in your table of contents. Write an informative description of
+            what your book is about.
         </Instructions>
 
         <Instructions {editable}>
@@ -183,7 +183,7 @@ onMount(() => {
                     forthcoming={chapter.isForthcoming()}
                 >
                     {#snippet annotation()}
-                                        <span >
+                        <span>
                             {#if editable}
                                 <TextEditor
                                     label={'Chapter section editor'}
@@ -202,9 +202,9 @@ onMount(() => {
                                 You can edit this chapter.
                             {/if}
                         </span>
-                                    {/snippet}
+                    {/snippet}
                     {#snippet etc()}
-                                        <span class="etc" >
+                        <span class="etc">
                             <Muted>
                                 {#if editable}
                                     <Toggle
@@ -223,44 +223,44 @@ onMount(() => {
                                 {/if}
                             </Muted>
                         </span>
-                                    {/snippet}
+                    {/snippet}
                 </TableOfContentsRow>
             {/each}
             {#if $edition.hasReferences() || editable}
                 <TableOfContentsRow chapter={ChapterIDs.ReferencesID}>
                     {#snippet annotation()}
-                                        <span >Everything cited</span>
-                                    {/snippet}
+                        <span>Everything cited</span>
+                    {/snippet}
                 </TableOfContentsRow>
             {/if}
             {#if ($edition.getGlossary() && Object.keys($edition.getGlossary()).length > 0) || editable}
                 <TableOfContentsRow chapter={ChapterIDs.GlossaryID}>
                     {#snippet annotation()}
-                                        <span >Definitions</span>
-                                    {/snippet}
+                        <span>Definitions</span>
+                    {/snippet}
                 </TableOfContentsRow>
             {/if}
             <TableOfContentsRow chapter={ChapterIDs.IndexID}>
                 {#snippet annotation()}
-                                <span >Common words and where they are</span>
-                            {/snippet}
+                    <span>Common words and where they are</span>
+                {/snippet}
             </TableOfContentsRow>
             <TableOfContentsRow chapter={ChapterIDs.SearchID}>
                 {#snippet annotation()}
-                                <span >Find where words occur</span>
-                            {/snippet}
+                    <span>Find where words occur</span>
+                {/snippet}
             </TableOfContentsRow>
 
             <TableOfContentsRow chapter={ChapterIDs.MediaID}>
                 {#snippet annotation()}
-                                <span >Images and video in the book</span>
-                            {/snippet}
+                    <span>Images and video in the book</span>
+                {/snippet}
             </TableOfContentsRow>
             {#if editable}
                 <TableOfContentsRow chapter={ChapterIDs.UnknownID}>
                     {#snippet annotation()}
-                                        <span >Customize bad links</span>
-                                    {/snippet}
+                        <span>Customize bad links</span>
+                    {/snippet}
                 </TableOfContentsRow>
             {/if}
         </Rows>
@@ -281,6 +281,21 @@ onMount(() => {
             > and then print or export. Long books can take some time to render.
         </PageParagraph>
 
+        <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>
+
+        <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 />
+
         <EditableHeader id="citation" label="Edit citation header" />
 
         <Instructions {editable}>

package/dist/epub/build.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Builds a complete EPUB from a loaded edition, entirely in the browser.
+ *
+ * No server is involved: the whole book's text is already in memory by the time
+ * the table of contents renders, and images are fetched directly (Firebase's
+ * download URLs allow cross-origin reads, and compiled books serve theirs from
+ * the same origin).
+ */
+import type Edition from '../models/book/Edition';
+import { type ImageSize } from './images';
+import { chapterPath } from './xhtml';
+export type BuildPhase = 'images' | 'chapters' | 'packaging';
+export type BuildProgress = {
+    phase: BuildPhase;
+    done: number;
+    total: number;
+};
+export type BuildResult = {
+    blob: Blob;
+    filename: string;
+    /** Images that couldn't be included, so the reader knows what's missing. */
+    warnings: string[];
+};
+export type BuildOptions = {
+    /** The book's base path, for resolving local image URLs. */
+    base?: string;
+    size?: ImageSize;
+    onProgress?: (progress: BuildProgress) => void;
+    /** Fixed timestamp, so tests can compare output. */
+    modified?: Date;
+};
+/**
+ * A stable, unique identifier for this edition. EPUB requires one, and readers
+ * use it to recognize the same book across downloads.
+ */
+export declare function identifierFor(edition: Edition): string;
+/** Build an EPUB for the given edition. */
+export declare function buildEPUB(edition: Edition, options?: BuildOptions): Promise<BuildResult>;
+export { chapterPath };