cavu-page
The Cavu Reader
Star
Fork
Watch
cavu-page DESIGN.md
34 kB · 611 lines
Markdown
at main

Design: books on atproto via standard.site #

Status: architecture settled with standard.site team guidance, then revised July 2026 for Leaflet-first interop: every text chunk carries pub.leaflet.content (one linearDocument page per chapter; chunk = one release for serialized books); our block types (blocks/toc, blocks/verse) are injected into Leaflet's open page unions rather than wrapped in our own content type. page.cavu.content and blocks/chapterTitle are deleted. The lexicon surface is now just lexicons/page/cavu/: book (publication extension), pages (comic/fixed-layout content), blocks/toc, blocks/verse — codegen'd types match. The no-backend reader (reader/, TanStack Start, paginated

  • infinite scroll + two-page comic spreads) consumes the revised shapes, and the studio (/studio) is the only way to publish: the command-line publishers (publish-driftwood, publish-honeyguide-release, publish-release, publish-byline-book, update-cover, import-leaflet-comic) were removed in September 2026. "Implementation delta" at the end is kept as history.

Constraints #

  1. A book is split over multiple records. Sometimes a record holds one chapter, sometimes a subchapter, sometimes several chapters. Records are storage chunks sized for network limits, not units of meaning.
  2. A "chapter" is a TOC breakpoint, not a record. The start of a chapter exists at a specific point in a specific record.
  3. The TOC is multi-level; its leaf nodes are chapters. Inner nodes are groupings (parts, volumes, acts).
  4. Serialized writing and series must both be easy to subscribe to — adding chapters to a book, and adding books to a series.
  5. Two content formats from day one: EPUB-formatted text (a subset of EPUB XHTML) and comics (images for pages). Comics should consider multi-zoom-level images or image formats that support progressive zoom.
  6. Authors control layout and styling as far as possible — including odd and non-standard typesetting. Book design is part of the work.

Architecture (per standard.site team guidance) #

Thing Record Notes
Book site.standard.publication carries our extension object (spine, TOC, series link, cover)
Series site.standard.publication plain publication; books point at it
Content chunk site.standard.document one per release (a chunk may hold several chapters, one per page); main text in the content union; largely replicates book fields
Frontmatter site.standard.document one per book: cover, human-readable TOC, acknowledgments — the renderable front door for generic standard.site apps

The extension pattern #

The spine lives on the book publication as a pass-through property, not a sidecar record. standard.site explicitly blesses additional properties ("shared baseline, not a constraint"), and the ecosystem idiom — observed on real Leaflet and pckt.blog publications — is a bare key whose value is a $type-tagged object from the platform's own lexicon, alongside the standard fields kept populated as fallback (e.g. theme next to basicTheme).

We follow it with one bundled key:

{
  "$type": "site.standard.publication",
  "name": "...", "url": "...", "icon": ..., // standard fields as fallback
  "book": {
    "$type": "page.cavu.book",            // self-describing, validatable
    "spine": [                               // ordered chunk entries
      { "document": "at://...", "roles": ["frontmatter", "toc"] },
      { "document": "at://..." },
      { "document": "at://...", "roles": ["appendix"], "linear": false }
    ],
    "series": { "publication": "at://...", "index": 2 },  // optional
    "cover": { /* blob */ },                 // portrait; same blob CID as
                                             // frontmatter doc's coverImage
    "completionStatus": "ongoing"
  }
}

Spine entries are property bags, not bare AT-URIs — schema evolution (string → object later would break every record) and EPUB precedent (itemref attributes, manifest properties, landmarks). roles uses the EPUB structural-semantics vocabulary (toc marks the document holding the TOC block — readers find it with a free array scan of the record they already fetched); linear: false (absent = true, as in EPUB) marks supplementary material skipped in continuous reading.

  • One key means one collision surface, one schema def, and presence/absence of book distinguishes book publications from series publications.
  • $type inside the value keeps us in the typed regime: our lexicon validates it, codegen types it, anyone can resolve the schema over DNS.
  • Size guardrail: the publication record (~1MB ceiling) is fetched by every subscriber and indexer. Spine entries are lean property bags (the TOC with its titles lives in a document, not here) — even thousand-chapter serials stay small.
  • Blobs are CID-referenced, so the cover blob is shared with the frontmatter document's coverImage at no storage cost. Keep blobs within declared lexicon limits even though validation is lenient in the wild.

Spine vs TOC (constraints 1–3) #

The EPUB 3 split, exactly:

  • Spine — ordered list of content-chunk entries ({document, roles, linear}) on the book publication object. Defines the continuous reading flow; chunk boundaries are invisible to the reader.
  • TOC — a block type (page.cavu.blocks.toc) inside a spine document, modeled on EPUB 3's navigation document: simultaneously machine-parseable structure and rendered content that sits at its natural place in the book (a printed TOC page). EPUB 2 kept the TOC as out-of-band metadata (NCX) and forced authors to duplicate a rendered TOC page; EPUB 3 unified them — navigation is content. The spine entry's toc role plays EPUB's properties="nav" manifest flag: readers fetch publication + the toc-tagged document (two reads) for full navigation.
  • TOC entries are flat and depth-annotated (flat-with-depth reconstructs any tree in one pass; no recursive lexicon refs). Leaf entries are chapters targeting (chunk AT-URI, page id) — the linearDocument page's own (standard) id field — with an optional finer block anchor; inner entries are groupings with optional targets. "Leaves must have targets" and "target pages must carry ids" are app-level validation.

Subscriptions (constraint 4) — solved natively #

site.standard.graph.subscription targets publications. Book = publication and series = publication, so both are directly subscribable:

  • New book in series → new book publication whose book.series points at the series publication.
  • New release → see below.

Chunk = release. standard.site documents are as much notification units as storage units: subscribers should get exactly one new-document event per release. So a serialized book releasing chapters in pairs puts the pair in one document — chapters are pages inside it, not documents of their own. The release ritual is one atomic com.atproto.repo.applyWrites batch, three writes:

  1. create the release document (pub.leaflet.content; one linearDocument page per chapter, pages carrying ids like ch-5; pages[0] is the release nav page with a blocks.page card per chapter when the release holds more than one).
  2. put the frontmatter/TOC document with a new leaf entry per chapter targeting (release doc, page id) (plus a grouping entry if the release is a named part).
  3. put the book publication with one new spine entry (and completionStatus flipped on the final release).

Atomicity means no window where the spine points at missing documents or new chapters are unreachable from navigation. Release-document title metadata covers the whole release ("The Second Tide & Undertow — Novella"); followers get one notification, and the document renders natively in anything leaflet-aware.

Reading progress (page.cavu.progress) #

The reader-side complement to subscriptions: the logged-in home page lists the user's site.standard.graph.subscription records, joined with their reading progress, showing progress-vs-content ("8 of 10 chapters, 2 new since you last read"). Progress is a record in the reader's own repo (the BookHive-shelf pattern: activity lives with the actor), one per book, updated in place:

  • Derived rkey. key: any; the rkey is the book publication's AT-URI with at:// stripped and / replaced by ~ (all legal rkey characters, reversible). Updates are idempotent putRecords with no read-before-write; one book's progress is a single getRecord; the whole shelf is one listRecords on the collection.
  • Position grammar, coarse to fine: document (spine doc AT-URI) → page (page id — same field for linearDocument and comic pages) → optional block index path + byte offset mirroring pub.leaflet.pages.linearDocument#position (Leaflet's own quote grammar). Fine fields are edit-fragile by nature; readers resolve what still exists and clamp the rest.
  • position vs furthest: position is the resume point, last-writer-wins across devices; furthest never regresses (clients max-merge), covering re-reads and stale-device writes.
  • Denormalized percent (integer 0–100, body-matter weighted — the bookProgress logic in book.ts), computed by the writing client, which has the book loaded. The home page renders progress bars from progress records + publication records alone; "N new chapters" = linear-spine entries after position.document — no spine-document fetches on the home page at all.
  • startedAt / finishedAt / updatedAt — shelf semantics (finishedAt marks finished regardless of percent; updatedAt doubles as last-read-at for a "continue reading" sort).
  • Public, therefore opt-in. Repo records are world-readable; writing progress must be a visible user choice, not ambient telemetry. Readers who decline keep progress in local storage only.
  • Why not buzz.bookhive.book as the progress record (checked before settling): hiveId is required and Cavu books aren't in the hive catalog; key: tid means list-and-match lookups, read-modify-write updates, and cross-device duplicate races; bookIdentifiers has no AT-URI field, so the record can't even name our book without a pass-through extension; and bookProgress (percent/currentPage/currentChapter) is display data with no resume point. It also carries the user's review and stars — rewriting it at reading cadence races their app's edits. The seams do line up for mirroring (their percent/startedAt/finishedAt/status map losslessly from our fields), so: page.cavu.progress is source of truth at reading cadence; mirror into buzz.bookhive.book at milestone cadence (start, chapter boundaries, finish) once the book has a hiveId.

Content formats (constraint 5) #

Chunks are site.standard.document records; the format lives in the document's content open union as our $type-tagged objects, mixable within one spine:

  • Text: pub.leaflet.content — Leaflet's own wrapper, so every text document (frontmatter included) renders natively in leaflet-aware apps (see "Text content format" below); book-only blocks ride the open block unions. textContent gives indexers/previews plaintext. Target chunk size ~100–300KB.
  • Comics: page.cavu.pages — pre-paginated image content, the fixed-layout counterpart to a pub.leaflet.content text chunk (see "Comic content format" below). Zoom options:
    1. Renditions per page — blobs at multiple widths. Simple, works everywhere; start here.
    2. Progressive formats — JPEG XL / progressive JPEG decode low-res from a byte prefix; needs range-request support on blob endpoints (not guaranteed).
    3. Tiling (deep-zoom / IIIF-style) — best zoom UX, most complexity.

Chunks-as-documents also restores per-chapter interop: timeline previews, per-chunk bskyPostRef comment threads, and per-chunk labels.

Text content format (Leaflet-first) #

The ecosystem convention (confirmed on live Leaflet and pckt.blog records) is that each platform puts its own $type-tagged content wrapper in site.standard.document.content. We deliberately don't follow it for body text: a page.cavu-only wrapper would make every chapter unrenderable outside our reader. Body chunks carry pub.leaflet.content itself, so any leaflet-aware app renders them natively and our reader renders them with the same block components.

Structure conventions inside a body chunk:

  • Chapter = page. The chunk's pages array holds one pub.leaflet.pages.linearDocument per chapter. The page's own (standard, optional) id field is the chapter anchor — we require it by app-level rule (ch-5-style, human-legible). Page boundaries give our reader chapter boundaries with zero nonstandard vocabulary. A chunk never holds a partial chapter; an oversized chapter splits into more spine chunks, never into blobPages (which we honor when consuming leaflet content — the lexicon says consumers MUST — but never emit).
  • Reachability in Leaflet: the release nav page. Leaflet renders pages[0] and reaches other pages only through pub.leaflet.blocks.page portal blocks (Notion-style tree, no sequential next/prev — confirmed in their PostPages.tsx). So a multi-chapter chunk's first page is a short release landing page — the release title and one blocks.page card per chapter — and each chapter page is a portal target. Single-chapter chunks skip this; the chapter itself is pages[0]. Rule for our reader: pages targeted by TOC leaf entries are chapters in the reading flow; untargeted pages are auxiliary (nav) and skipped — our book TOC supersedes them.
  • Chapter title is content: the first block of a chapter page is a pub.leaflet.blocks.header with the chapter title as rendered in the book. Chapter-opening treatment (fresh page in paginated flows, the chapter drop, generous separation in continuous flows) is TOC-driven: our reader applies it to pages targeted by TOC leaf entries. The former page.cavu.blocks.chapterTitle block is dropped — a page boundary plus a TOC target carries the same information in standard vocabulary. Degradation in foreign renderers: an ordinary heading, which is fine. Ordinary in-chapter headings are also header; the TOC, not the heading level, distinguishes them.
  • Book blocks ride the open union. linearDocument's block union is open (no closed: true; the lexicon spec makes unions open by default), and Leaflet's published-view renderer confirms the skip behavior: its block dispatch ends in default: return null (PostContent.tsx). So page.cavu.blocks.verse (and toc, below) sit inside leaflet pages; foreign renderers show a silent hole (a chapter minus its lullaby, no indication) — accepted because a mostly-readable chapter beats an unrenderable one. Keep the document's textContent complete so skipped words still exist in previews and search. Corollary: never round-trip our documents through Leaflet's editor, which would drop unknown block types on save.
  • Sub-page anchors: standard #id facets. Leaflet's richtext facet lexicon includes an #id feature ("used for linking to a segment") — an inline anchor on a byte range, in standard vocabulary. Finer-than- page targets (deep links, the future page.cavu.position reading-position record) use (document, page id, facet id) — no nonstandard pass-through block ids needed. Not load-bearing today: chapters, the only current anchor consumers, are whole pages.

The frontmatter/TOC document is leaflet content too — page.cavu.content is deleted; there is no page.cavu text wrapper left. Its single linearDocument page is:

  • a level-1 header — the book title (title page, not a chapter);
  • the injected page.cavu.blocks.toc block — flat depth-annotated entries targeting (document, page id[, facet anchor]) — which our reader parses for navigation UI and renders as the printed TOC page.

The TOC is deliberately a cavu-only structure with no in-page fallback: Leaflet skips the block and shows a plain title page, which is fine — leaflet-aware apps already navigate the publication through their own chrome (chronological post feed, postsList, prev/next), so a hand-maintained card list would just duplicate that. The document's textContent carries a plaintext TOC and description a real blurb for preview cards.

Should a work someday need blocks whose omission would misrepresent it beyond tolerance, the answer is a new content type added to the spine's open content union — additive, not a revival of the wrapper.

Book-only blocks, now three:

  • page.cavu.blocks.verse — plaintext with significant newlines (\n = line break, \n\n = stanza break) + the same Leaflet facets. Mirrors pub.leaflet.blocks.text's shape so rich-text tooling carries over. Renderers keep stanzas together and style verse distinctly. (Survey basis: The Driftwood Library, 8 chapters, ~18k words — prose, quoted embedded tales, dialogue, and one lullaby in quatrains; verse was the only structure with no Leaflet block and no faithful markdown representation.)
  • page.cavu.blocks.toc — the table of contents as content, per EPUB 3's navigation-document unification.
  • page.cavu.blocks.screenplay — one screenplay element (scene heading, action, character, parenthetical, dialogue, lyric, transition, centered) as plaintext + facets, with an optional sceneNumber and a dual flag for dual dialogue. A script is a flat run of these — the paragraph-type model of Fountain and Final Draft — inside ordinary chapter pages, one page per act. See "Screenplays" below.

Title vs heading convention: a chunk document's title is metadata — self-contained for browser tabs, previews, feed cards, and subscription notifications, covering the whole release ("The Second Tide & Undertow — The Driftwood Library"). Chapter titles are content: header blocks opening each chapter page. The frontmatter document opens with a level-1 header of the book title (title page, not a chapter).

Importer note: markdown sources don't mark verse explicitly — detection is heuristic (runs of short hard-broken lines) or author-annotated.

Screenplays #

A book whose page.cavu.book form is screenplay is a script, set to the US industry standard: Courier Prime throughout, the standard element indents (cue 2.2in in, parenthetical 1.6in, dialogue 1in and 3.5in wide, transitions flush right), and in PDF the Letter script page exactly — 54 lines, scene numbers in both margins, page numbers top right, (MORE)/(CONT'D) where a speech crosses a page. Screen and EPUB keep the indents but fit them to the reading column. The source format is Fountain; # sections become chapters (acts).

form sits beside styling rather than in it: it changes what the importer reads and how every renderer sets the body, not a preference. Under it, the faces, paragraph style, justification, chapter drop and initial are fixed by convention; only page size and chapter break remain the author's.

This deliberately stretches the tolerance rule above. A screenplay rendered by a foreign Leaflet reader is a silent hole — act titles and nothing else — which is past "mostly readable". The rule's answer would be a new content type, but that buys nothing here: no foreign renderer can set a script either way, and a new type would duplicate every chapter-shaped path (TOC anchors, the reading route, bookState, exports, KOReader XPointer mapping, highlights, the studio block editor) for no gain in interop. textContent stays complete, so previews and search still see the whole script.

Leaflet's pub.leaflet.blocks.html was considered and rejected as the storage: it renders author HTML in a sandboxed iframe of fixed height (16–1600px), which clips a scene, can't flow through paginated columns, is opaque to highlights and KOReader positions, ignores the reader's theme, and gives the PDF nothing to break (MORE)/(CONT'D) from. It remains a possible additive Leaflet fallback — a per-scene HTML copy the Cavu reader skips — without touching records already published.

Comic content format #

page.cavu.pages is the pre-paginated counterpart to a pub.leaflet.content text chunk, modeled on EPUB fixed-layout: an ordered array of page objects, each one image blob + aspectRatio (reusing pub.leaflet.blocks.image#aspectRatio)

  • alt (ideally a panel/dialogue transcript) + optional id + optional spread hint. Same chunking rules as text — a chunk is usually a chapter or issue, boundaries invisible to the reader — and both content types mix freely in one spine (a prose foreword before comic chapters).

Survey of a real Leaflet comic (aavia-comic.leaflet.pub, 18 pages) found one site.standard.document per page with a single pub.leaflet.blocks.image block (~2.5MB webp, 2480×3508) — fine for a feed-style site, but no spine order, no spreads, no reading direction. Importing that shape means converting it into chapter-sized page.cavu.pages chunks (grouping "Prologue p.N"-style titles into chapters, re-uploading blobs); a one-off script once did this, and a studio comic import would have to do the same.

Two-page spreads. Print-comic conventions, EPUB's vocabulary:

  • pageProgression: ltr | rtl on page.cavu.book (EPUB's spine-level page-progression-direction; absent = ltr, rtl for manga) decides which slot of a spread comes first in reading order and which way pages turn.
  • Per-page spread: left | right | center mirrors EPUB's page-spread-* properties. left/right pin a page to a physical side — renderers insert a blank slot when the natural flow disagrees, exactly as print does (e.g. right on page 1 makes it open alone like a proper recto); center gives a page the whole spread. Absent means pages fill spreads in reading order. Pages wider than tall are center regardless — a double-page spread drawn as one image.

Anchor grammar (resolves the former open question): the page id is the anchor — TOC entries and intra-book links target (document AT-URI, page id), the same grammar as linearDocument page ids in text chunks. One grammar for both content types.

Zoom, deferred: single full-resolution blob per page for now (maxSize 20MB; the wild runs ~2.5MB/page). The lexicon can grow an optional per-page renditions array additively when needed.

Ecosystem: byline.pub and BookHive #

byline.pub publishes CC0, venue-neutral pub.byline.* lexicons (vendored in lexicons/pub/byline/) for the catalog layer: book is author-signed listing metadata — title/subtitle/tagline, tiered descriptions, cover + coverAlt, genres/tags, publication status (draft/forthcoming/published/outOfPrint as token defs), editions (format, ISBN-10/13, retailer links, audiobook duration), external identifiers (ASIN, Goodreads, and hiveBookUri — an AT-URI into BookHive's buzz.bookhive.catalogBook, revealing a third ecosystem player for reader tracking/reviews), plus series, profile, and comment (reader comments in the commenter's own repo, strongRef to the book, threaded via parent).

No content anywhere — no spine, no text. Byline answers "what is this book and where do you get it"; we answer "here is the book, read it." The integration seam:

  • Don't duplicate the catalog. page.cavu.book stays a reading-format object; editions/retailers/genres belong in a companion pub.byline.book record. A Cavu book can be its own byline listing where the "edition" is natively readable on atproto.
  • Correlate, both directions. Their identifiers pattern (hiveBookUri) is the template: an identifier/link pointing at our book publication is the natural ask to byline; a listing AT-URI on page.cavu.book pointing at the pub.byline.book record is ours.
  • Validation: their series design matches ours exactly ("Book points at the series; the series record never points back"), with two ideas worth stealing: denormalized series name on the membership object (render without a fetch) and their contributor def (name required, DID optional — friendlier than site.standard's DID-required contributor for crediting off-protocol co-authors/narrators).
  • Social layer for free: pub.byline.comment (book-level, threaded) + standard.site's per-chunk bskyPostRef cover book and chapter discussion without us minting a comment lexicon.

Adopted into page.cavu.book (baked-in byline dependency, deliberate): contributors reuses pub.byline.defs#contributor; listing AT-URI points at the companion pub.byline.book catalog record; coverAlt added; seriesRef.name denormalized.

BookHive (buzz.bookhive.*, vendored in lexicons/buzz/bookhive/) is the reader-shelf layer: book is a record in the reader's repo — status tokens (wantToRead/reading/finished/abandoned), 1–10 stars, review text, started/finished dates, and a bookProgress object (percent / currentPage / currentChapter) — correlated to the catalog via bookIdentifiers and hiveBookUri. buzz is their threaded comment record; catalogBook is their scraped canonical catalog (in the bookhive.buzz repo, keyed by hive id). Implications for our reader:

  • Write buzz.bookhive.book records on the user's behalf (status, stars, review, coarse progress) so Cavu reading activity shows up on BookHive shelves — interop instead of a competing shelf lexicon.
  • Their bookProgress is page-granularity; our fine-grained record is page.cavu.progress (see "Reading progress"), with coarse sync mirrored into bookProgress.
  • Getting Cavu books into their catalog (so readers can shelve them) goes through their hive-id pipeline — same conversation as the byline identifier ask.

Author styling (constraint 6) #

Semantics are the floor; styling is progressive enhancement. Records must render legibly with zero author styling (other apps, screen readers, reader-mode); above that floor, the author owns presentation in escalating layers:

  1. Book theme — page.cavu.theme-style object on the publication (the theme/basicTheme pattern): typography with embedded font blobs (EPUB's book-identity feature), palette, page background, paragraph style (indent vs spaced), justification, chapter-drop depth, scene-break ornament. Covers the design identity of most books entirely.
  2. Block attributes — declarative, enumerable hints on the block wrapper: alignment (Leaflet precedent), inset, size variant. Safely ignorable by simple renderers.
  3. Author stylesheet — a CSS blob on the publication + a class hook on block wrappers. The "odd typesetting" unlock. Safer for us than publisher CSS ever was for EPUB reading systems: atproto structurally forbids external fetches (fonts/images are blobs), and our reader renders into a container we control — sanitize with a property allowlist and let authors go wild.
  4. Freeform layout content types — for concrete poetry and House-of-Leaves pages: a positioned-canvas content type (pub.leaflet.pages.canvas is precedent) or SVG pages with textContent fallback, mixable into the spine chapter by chapter via the open content union.

Reader-side policy, exactly one: reader-mode always available — user accessibility overrides author art on demand (EPUB's "publisher defaults" toggle, done deliberately). Author styling is on by default.

Presentation defaults documented in block descriptions (e.g. the chapter drop) are what the absence of author styling produces — the floor, not a ceiling.

URL resolution & hosting (standard.site verification) #

How https URLs and records point at each other, per the standard.site verification spec and Bluesky's shipped integration (researched July 2026):

  • Documents: per-page <link rel="site.standard.document" href="at://…"> in the page head. Fully path-scoped. There is also a rel="site.standard.publication" link tag, but the spec marks it "a hint only — always confirm via the .well-known endpoint". The reader emits both.
  • Publications: /.well-known/site.standard.publication returns the publication's AT-URI as plaintext — and it is path-capable ("Non-root Publications"): a publication whose url is https://example.com/books/foo verifies at https://example.com/.well-known/site.standard.publication/books/foo. Live precedent: atproto.com/blog. The publication url field is format: uri; nothing forbids a path, and Leaflet's own resolver longest-prefix-matches path-based publication urls.
  • So: no subdomain-per-book. One reader domain can host many books at paths. Leaflet mints a subdomain per publication, but that's their product choice (and matches atproto's strictly host-scoped identity layers — handles and did:web reject paths), not a spec requirement. Caveat: non-root support is newer spec text, and Bluesky's appview keeps a hardcoded subpath-friendly domain allowlist (packages/bsky/src/util/standard-site.ts) for document-URL validation — serve both the path-suffixed well-known and the hint link tags for maximum indexer compatibility.
  • Verification is bidirectional and consumer-side (indexers like docs.surf, Bluesky's cardyb link-card service): record's url + path must equal the page URL, and the well-known must return the record's AT-URI. Consequence for a shared reader domain: only affirm publications whose record url actually points at us — echoing an AT-URI for every path would falsely claim every book on the network. Known race: records published before the site deploys need indexer re-verification.

Open questions #

  • Series ordering — is index on the book→series link enough, or does the series publication want its own ordered list (and what does a series "TOC" look like for generic apps)?
  • Version pinning / editions — spine references are floating AT-URIs; strongRefs would pin immutable editions at the cost of an update fan-out on every typo fix.
  • Comic zoom mechanics — PDS blob size limits in the wild, range-request support on getBlob/CDNs, JPEG XL client support; when a per-page renditions array earns its complexity.
  • Verse detection on import — heuristic vs author annotation in markdown sources.

Implementation delta (July 2026 revision → code) #

Done: lexicons match the revision (page.cavu.content and blocks/chapterTitle deleted; blocks/toc entries target (document, page[, facet anchor]); scripts/codegen.ts roots updated and src/lexicons regenerated — pub.leaflet.content, both page types, and the full block set are now typed). Still to apply — these files currently import the deleted page/cavu/content types and fail typecheck:

  1. Reader: render pub.leaflet.content chunks (multi-page linearDocument, portal-block cards, blobPages honoring, open-union verse/toc); TOC-driven chapter-opening treatment keyed on (document, page id); skip TOC-untargeted (nav) pages in the reading flow; drop the chapterTitle render case (Blocks.tsx); update book.ts content discrimination and docs.tsx prose.
  2. Importers: publish-driftwood.ts/publish-honeyguide.ts emit pub.leaflet.content — one linearDocument page per chapter, nav page first when a chunk holds several chapters, headers instead of chapterTitle blocks; the frontmatter doc becomes leaflet content (title header + injected toc block). import-leaflet-comic.ts and smoke.ts also import deleted types. Done for the web importer (July 28): reader/src/routes/import.tsx (+ lib/markdown.ts, lib/publish.ts) is a browser importer — cover + markdown files in, atomic applyWrites of the revised shapes, same-name re-import replacement — and writes a buzz.bookhive.book shelf record with BookHive's deterministic hiveId (bk_ + sha256base64(objectHash({title, author} lowercased))[:20], ohash@1 — verified byte-identical against their production catalog). Auth is atproto OAuth with granular scopes at two grant levels (lib/oauth.ts + lib/useAuth.ts, @atproto/oauth-client-browser): the /login reader grant is atproto include:site.standard.authSocial repo:buzz.bookhive.book?action=create&action=update (subscriptions/recommends + shelf progress tracking); the publisher grant — asked for only via "Publish my work" on /login (the logged-in profile view) or the upgrade prompt on /import — swaps in include:site.standard.authFull and adds blob:image/*. Client metadata (served /oauth/client-metadata.json; loopback client id in dev — browse via http://127.0.0.1:3000) declares the union of both scopes and redirect URIs /login + /import. DPoP sessions persist in IndexedDB. This covers delta item 4's OAuth login; the logged-in home page joining subscriptions × publications × shelf progress is still to build. The script importers remained pre-revision until they were removed (September 2026) in favor of the studio.
  3. New: release-pair.ts — the three-write serialized-release batch (create release doc, put TOC doc, put publication).
  4. Subscription flow (pre-launch requirement): reader login (atproto OAuth), subscribe/unsubscribe writing site.standard.graph.subscription records, a logged-in home page joining subscriptions × publications × page.cavu.progress (progress bars, "N new chapters", continue reading), and opt-in progress writing from the reading views.