bookish-press 0.7.4 → 0.9.2

package/README.md

@@ -6,6 +6,50 @@ Bookish is a framework and platform for writing and publishing web-based books.
 
 I'm working on a 1.0 of the platform at [bookish.press](https://bookish.press) and expect to maintain the platform for the foreseeable future. Let me know if you'd like to help!
 
+## Hosting architecture
+
+The app is a SvelteKit app. Server-side rendering runs on a [Cloud Run](https://cloud.google.com/run) service named `bookish-ssr` (region `us-central1`) in each Firebase project; Firebase Hosting serves the static client assets from `build/client` and rewrites everything else to that service (see `firebase.json`). The `stage` and `release` scripts handle both: they build the app locally with the environment-specific `.env` (which is inlined at build time), deploy the resulting `build/` to Cloud Run (see `Dockerfile` and `.gcloudignore`), and then run `firebase deploy` for hosting, rules, and functions.
+
+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:
@@ -13,14 +57,17 @@ 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:
     1. Update the bookish package with the Sveltekit package tooling (`npm run package`)
     2. Publish the package to npm (`npm publish`)
@@ -33,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/Auth.svelte

@@ -1,55 +1,45 @@
-<script>import { sendSignInLinkToEmail } from 'firebase/auth';
-import { onDestroy, setContext } from 'svelte';
-import { writable } from 'svelte/store';
-import { auth } from '../models/Firebase';
-import { USER } from './page/Contexts';
-// Track the user and user loading status in state
-let loading = true;
-// The store that tracks the auth context.
+<script lang="ts">import { sendSignInLinkToEmail } from "firebase/auth";
+import { onDestroy, setContext } from "svelte";
+import { writable } from "svelte/store";
+import { auth } from "../models/Firebase";
+import { USER } from "./page/Contexts";
+let { children } = $props();
+let loading = $state(true);
 const authentication = writable({
-    user: null,
-    loading: loading,
-    login,
-    logout,
+  user: null,
+  loading: true,
+  login,
+  logout
 });
-// Login using Firebase's password-less email verification
 async function login(email) {
-    // If connected to firebase...
-    if (auth) {
-        const actionCodeSettings = {
-            url: location.origin + '/confirm',
-            handleCodeInApp: true,
-        };
-        // Ask Firebase to log in with the given email
-        await sendSignInLinkToEmail(auth, email, actionCodeSettings);
-        // Remember the email in local storage so we don't have to ask for it again
-        // after returning to the link above.
-        window.localStorage.setItem('email', email);
-    }
+  if (auth) {
+    const actionCodeSettings = {
+      url: location.origin + "/confirm",
+      handleCodeInApp: true
+    };
+    await sendSignInLinkToEmail(auth, email, actionCodeSettings);
+    window.localStorage.setItem("email", email);
+  }
 }
 function updateAuth(user) {
-    authentication.set({ user, loading: loading, login, logout });
+  authentication.set({ user, loading, login, logout });
 }
-// Logout using Firebase's authentication framework.
 function logout() {
-    if (auth) {
-        return auth.signOut().then(() => updateAuth(null));
-    }
+  if (auth) {
+    return auth.signOut().then(() => updateAuth(null));
+  }
 }
-// On mount, subscribe to authentication changes.
 if (auth) {
-    const unsubscribe = auth.onAuthStateChanged((user) => {
-        loading = false;
-        updateAuth(user);
-    });
-    // On unmount, stop subscribing.
-    onDestroy(unsubscribe);
+  const unsubscribe = auth.onAuthStateChanged((user) => {
+    loading = false;
+    updateAuth(user);
+  });
+  onDestroy(unsubscribe);
 }
-// Expose the state and the login/logout functionality.
 setContext(USER, authentication);
 </script>
 
 <!-- Wrap whatever children are given in this context. -->
 {#if loading === false}
-    <slot />
+    {@render children?.()}
 {/if}

package/dist/components/Auth.svelte.d.ts

@@ -1,18 +1,6 @@
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: Record<string, never>;
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type AuthProps = typeof __propDef.props;
-export type AuthEvents = typeof __propDef.events;
-export type AuthSlots = typeof __propDef.slots;
-export default class Auth extends SvelteComponent<AuthProps, AuthEvents, AuthSlots> {
+interface Props {
+    children?: import('svelte').Snippet;
 }
-export {};
+declare const Auth: import("svelte").Component<Props, {}, "">;
+type Auth = ReturnType<typeof Auth>;
+export default Auth;

package/dist/components/BookPreview.svelte

@@ -1,23 +1,17 @@
-<script>import EmbedNode from '../models/chapter/EmbedNode';
-import Parser from '../models/chapter/Parser';
-import ChapterBody from './chapter/ChapterBody.svelte';
-import Embed from './chapter/Embed.svelte';
-import Link from './app/Link.svelte';
-export let book;
-export let write = false;
-$: refID = book.getID();
-$: cover = book.getCover();
-$: authors = book.getAuthors();
-$: description = book.getDescription();
-$: subdomain = book.getSubdomain();
-$: title = book.getTitle();
-$: embed = cover === null ? null : Parser.parseEmbed(undefined, cover);
-$: url =
-    subdomain === null || write
-        ? refID === undefined
-            ? ''
-            : (write ? '/write/' : '/') + refID
-        : `/${subdomain}`;
+<script lang="ts">import EmbedNode from "../models/chapter/EmbedNode";
+import Parser from "../models/chapter/Parser";
+import ChapterBody from "./chapter/ChapterBody.svelte";
+import Embed from "./chapter/Embed.svelte";
+import Link from "./app/Link.svelte";
+let { book, write = false } = $props();
+let refID = $derived(book.getID());
+let cover = $derived(book.getCover());
+let authors = $derived(book.getAuthors());
+let description = $derived(book.getDescription());
+let subdomain = $derived(book.getSubdomain());
+let title = $derived(book.getTitle());
+let embed = $derived(cover === null ? null : Parser.parseEmbed(void 0, cover));
+let url = $derived(subdomain === null || write ? refID === void 0 ? "" : (write ? "/write/" : "/") + refID : `/${subdomain}`);
 </script>
 
 <article class="book-preview">

package/dist/components/BookPreview.svelte.d.ts

@@ -1,20 +1,8 @@
-import { SvelteComponent } from "svelte";
 import type Book from '../models/book/Book';
-declare const __propDef: {
-    props: {
-        book: Book;
-        write?: boolean;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type BookPreviewProps = typeof __propDef.props;
-export type BookPreviewEvents = typeof __propDef.events;
-export type BookPreviewSlots = typeof __propDef.slots;
-export default class BookPreview extends SvelteComponent<BookPreviewProps, BookPreviewEvents, BookPreviewSlots> {
+interface Props {
+    book: Book;
+    write?: boolean;
 }
-export {};
+declare const BookPreview: import("svelte").Component<Props, {}, "">;
+type BookPreview = ReturnType<typeof BookPreview>;
+export default BookPreview;

package/dist/components/Link.svelte

@@ -1,41 +1,30 @@
-<script>import { page } from '$app/stores';
-export let to;
-export let linked = true;
-let link;
+<script lang="ts">import { page } from "$app/state";
+let { to, linked = true, children } = $props();
+let link = $state();
 function scroll(event) {
-    // No element? Bail.
-    if (link === undefined)
-        return;
-    // No hash? No scroll.
-    const hash = new URL(link.href).hash;
-    if (hash === '')
-        return;
-    // Prevent the browser from scrolling.
-    event.preventDefault();
-    // Get the anchor
-    const anchorId = new URL(link.href).hash.replace('#', '');
-    const anchor = document.getElementById(anchorId);
-    // No anchor? Bail.
-    if (anchor === null)
-        return;
-    // Scroll to the anchor.
-    window.scrollTo({
-        top: anchor.offsetTop,
-        behavior: 'smooth',
-    });
-    // Update the hash (without scrolling)
-    history.pushState({}, '', hash);
+  if (link === void 0) return;
+  const hash = new URL(link.href).hash;
+  if (hash === "") return;
+  event.preventDefault();
+  const anchorId = new URL(link.href).hash.replace("#", "");
+  const anchor = document.getElementById(anchorId);
+  if (anchor === null) return;
+  window.scrollTo({
+    top: anchor.offsetTop,
+    behavior: "smooth"
+  });
+  history.pushState({}, "", hash);
 }
 </script>
 
-{#if !linked || $page.url.pathname === (to.charAt(to.length - 1) === '/' ? to.substring(0, to.length - 1) : to)}
-    <slot />
+{#if !linked || page.url.pathname === (to.charAt(to.length - 1) === '/' ? to.substring(0, to.length - 1) : to)}
+    {@render children?.()}
 {:else}
     <a
         href={to}
         bind:this={link}
-        on:click={(event) => scroll(event)}
-        target={to.startsWith('http') ? '_blank' : null}><slot /></a
+        onclick={(event) => scroll(event)}
+        target={to.startsWith('http') ? '_blank' : null}>{@render children?.()}</a
     >
 {/if}
 

package/dist/components/Link.svelte.d.ts

@@ -1,21 +1,8 @@
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        to: string;
-        linked?: boolean;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type LinkProps = typeof __propDef.props;
-export type LinkEvents = typeof __propDef.events;
-export type LinkSlots = typeof __propDef.slots;
-export default class Link extends SvelteComponent<LinkProps, LinkEvents, LinkSlots> {
+interface Props {
+    to: string;
+    linked?: boolean;
+    children?: import('svelte').Snippet;
 }
-export {};
+declare const Link: import("svelte").Component<Props, {}, "">;
+type Link = ReturnType<typeof Link>;
+export default Link;

package/dist/components/app/BookList.svelte

@@ -1,6 +1,5 @@
-<script>import BookPreview from '../BookPreview.svelte';
-export let books;
-export let write;
+<script lang="ts">import BookPreview from "../BookPreview.svelte";
+let { books, write } = $props();
 </script>
 
 <section class="previews">

package/dist/components/app/BookList.svelte.d.ts

@@ -1,20 +1,8 @@
-import { SvelteComponent } from "svelte";
 import type Book from '../../models/book/Book';
-declare const __propDef: {
-    props: {
-        books: Book[];
-        write: boolean;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {};
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type BookListProps = typeof __propDef.props;
-export type BookListEvents = typeof __propDef.events;
-export type BookListSlots = typeof __propDef.slots;
-export default class BookList extends SvelteComponent<BookListProps, BookListEvents, BookListSlots> {
+interface Props {
+    books: Book[];
+    write: boolean;
 }
-export {};
+declare const BookList: import("svelte").Component<Props, {}, "">;
+type BookList = ReturnType<typeof BookList>;
+export default BookList;

package/dist/components/app/Button.svelte

@@ -1,20 +1,24 @@
-<script>export let type = null;
-export let tooltip;
-export let disabled = false;
-export let command;
+<script lang="ts">let {
+  type = null,
+  tooltip,
+  disabled = false,
+  command,
+  class: classes,
+  children
+} = $props();
 </script>
 
 <button
-    class={$$props.class}
+    class={classes}
     title={tooltip}
     aria-label={tooltip}
     {type}
     {disabled}
-    on:mousedown={command}
-    on:keypress={(event) =>
+    onmousedown={command}
+    onkeypress={(event) =>
         event.key === ' ' || event.key === 'Enter' ? command() : undefined}
 >
-    <slot />
+    {@render children?.()}
 </button>
 
 <style>

package/dist/components/app/Button.svelte.d.ts

@@ -1,24 +1,11 @@
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        [x: string]: any;
-        type?: "submit" | "button" | null | undefined;
-        tooltip: string;
-        disabled?: boolean | undefined;
-        command: () => void;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: undefined;
-    bindings?: undefined;
-};
-export type ButtonProps = typeof __propDef.props;
-export type ButtonEvents = typeof __propDef.events;
-export type ButtonSlots = typeof __propDef.slots;
-export default class Button extends SvelteComponent<ButtonProps, ButtonEvents, ButtonSlots> {
+interface Props {
+    type?: 'submit' | 'button' | null;
+    tooltip: string;
+    disabled?: boolean;
+    command: () => void;
+    class?: string;
+    children?: import('svelte').Snippet;
 }
-export {};
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/components/app/Feedback.svelte

@@ -1,11 +1,11 @@
-<script>import Large from './Large.svelte';
-export let error = false;
+<script lang="ts">import Large from "./Large.svelte";
+let { error = false, children } = $props();
 </script>
 
 {#if error}
-    <p role="alert"><slot /></p>
+    <p role="alert">{@render children?.()}</p>
 {:else}
-    <p role="status" aria-live="polite"><Large><slot /></Large></p>
+    <p role="status" aria-live="polite"><Large>{@render children?.()}</Large></p>
 {/if}
 
 <style>

package/dist/components/app/Feedback.svelte.d.ts

@@ -1,20 +1,7 @@
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        error?: boolean;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type FeedbackProps = typeof __propDef.props;
-export type FeedbackEvents = typeof __propDef.events;
-export type FeedbackSlots = typeof __propDef.slots;
-export default class Feedback extends SvelteComponent<FeedbackProps, FeedbackEvents, FeedbackSlots> {
+interface Props {
+    error?: boolean;
+    children?: import('svelte').Snippet;
 }
-export {};
+declare const Feedback: import("svelte").Component<Props, {}, "">;
+type Feedback = ReturnType<typeof Feedback>;
+export default Feedback;

package/dist/components/app/Head.svelte

@@ -1,7 +1,7 @@
-<script>export let id = null;
+<script lang="ts">let { id = null, children } = $props();
 </script>
 
-<h2 {id}><slot /></h2>
+<h2 {id}>{@render children?.()}</h2>
 
 <style>
     h2 {

package/dist/components/app/Head.svelte.d.ts

@@ -1,20 +1,7 @@
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        id?: string | null;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type HeadProps = typeof __propDef.props;
-export type HeadEvents = typeof __propDef.events;
-export type HeadSlots = typeof __propDef.slots;
-export default class Head extends SvelteComponent<HeadProps, HeadEvents, HeadSlots> {
+interface Props {
+    id?: string | null;
+    children?: import('svelte').Snippet;
 }
-export {};
+declare const Head: import("svelte").Component<Props, {}, "">;
+type Head = ReturnType<typeof Head>;
+export default Head;

package/dist/components/app/Large.svelte

@@ -1,4 +1,7 @@
-<span><slot /></span>
+<script lang="ts">let { children } = $props();
+</script>
+
+<span>{@render children?.()}</span>
 
 <style>
     span {

package/dist/components/app/Large.svelte.d.ts

@@ -1,29 +1,6 @@
-/** @typedef {typeof __propDef.props}  LargeProps */
-/** @typedef {typeof __propDef.events}  LargeEvents */
-/** @typedef {typeof __propDef.slots}  LargeSlots */
-export default class Large extends SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {
-    default: {};
-}> {
+interface Props {
+    children?: import('svelte').Snippet;
 }
-export type LargeProps = typeof __propDef.props;
-export type LargeEvents = typeof __propDef.events;
-export type LargeSlots = typeof __propDef.slots;
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        [x: string]: never;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: undefined;
-    bindings?: undefined;
-};
-export {};
+declare const Large: import("svelte").Component<Props, {}, "">;
+type Large = ReturnType<typeof Large>;
+export default Large;

package/dist/components/app/Lead.svelte

@@ -1,4 +1,7 @@
-<h1><slot /></h1>
+<script lang="ts">let { children } = $props();
+</script>
+
+<h1>{@render children?.()}</h1>
 
 <style>
     h1 {

package/dist/components/app/Lead.svelte.d.ts

@@ -1,29 +1,6 @@
-/** @typedef {typeof __propDef.props}  LeadProps */
-/** @typedef {typeof __propDef.events}  LeadEvents */
-/** @typedef {typeof __propDef.slots}  LeadSlots */
-export default class Lead extends SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {
-    default: {};
-}> {
+interface Props {
+    children?: import('svelte').Snippet;
 }
-export type LeadProps = typeof __propDef.props;
-export type LeadEvents = typeof __propDef.events;
-export type LeadSlots = typeof __propDef.slots;
-import { SvelteComponent } from "svelte";
-declare const __propDef: {
-    props: {
-        [x: string]: never;
-    };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: undefined;
-    bindings?: undefined;
-};
-export {};
+declare const Lead: import("svelte").Component<Props, {}, "">;
+type Lead = ReturnType<typeof Lead>;
+export default Lead;