Packages

narrarium-astro-reader

Astro reader and reader scaffolding CLI for Narrarium book repositories.

Source: packages/astro-reader/README.md

narrarium-astro-reader

Astro reader and reader scaffolding CLI for Narrarium book repositories.

Install

npm install narrarium-astro-reader

Scaffold a reader app

npx narrarium-reader-init reader --book-root ..

Or directly from the published package:

npx narrarium-astro-reader reader --book-root .. --package-name my-book-reader

What the reader includes

  • book landing page plus chapter-by-chapter reading
  • previous, next, and jump chapter navigation
  • reading preferences, bookmark, and continue-reading state stored locally
  • live search across canon, chapters, and scenes
  • character, location, faction, item, secret, and timeline indexes
  • canon mention popups, backlinks, and asset rendering for book, entity, chapter, and scene art
  • a Full read chapter mode that opens an immersive browser-fullscreen reading view with continuous prose, auto-hiding minimal previous/jump/next navigation, a small ghost hint for rediscovering controls, and canon popups still available
  • dismissible Read Aloud controls that can be reopened from a subtle masthead speaker button and stay out of the way during Full read mode
  • automatic EPUB export to public/downloads/book.epub
  • live watcher for book markdown, canon, and assets during npm run dev
  • npm run doctor for broken references, spoiler thresholds, asset metadata, and stale plot.md, resumes/, or state/
  • optional EPUBCheck validation during export or build
  • starter GitHub Pages deployment workflow when scaffolded into a standalone app

Reader modes

The generated reader defaults to a spoiler-safe public mode.

In public mode:

  • secrets stay hidden from the public atlas and nav
  • direct canon pages fall back to teaser or locked views when known_from or reveal_in say a dossier is not safe yet
  • search, canon popups, and backlinks follow the same thresholds
  • chapter and scene prose should keep canon names as plain text; the reader upgrades visible mentions into canon popups and also rewrites legacy internal canon links at runtime

If you want an author-only or spoiler-friendly deployment, enable full canon mode:

NARRARIUM_READER_CANON_MODE=full
# or
NARRARIUM_READER_ALLOW_FULL_CANON=true

Local development

The scaffold creates .env with the computed book root already filled in. Update it if the reader should point somewhere else:

npm install
npm run dev

Typical .env values:

NARRARIUM_BOOK_ROOT=..
# NARRARIUM_READER_CANON_MODE=full
# EPUBCHECK_CMD=epubcheck
# EPUBCHECK_JAR=/absolute/path/to/epubcheck.jar

npm run dev watches the linked book repo, regenerates the EPUB on changes, and triggers a full browser reload. npm run build refreshes the EPUB automatically before Astro builds the site.

Validation and export

npm run doctor
npm run export:epub
npm run build

If EPUBCHECK_CMD or EPUBCHECK_JAR is set, EPUB export and build also run EPUBCheck.

npm run doctor also reports if the linked book repository has stale or missing structured story-state snapshots, so author-facing continuity drift shows up before deployment.

GitHub Pages

You can pass --pages-domain example.com when scaffolding to emit public/CNAME and a Pages workflow already pointed at that domain.