Artstr-Studio/docs/BOOK_DESIGNER_FEATURE.md

Book Designer

Goals

A unified document type for designing books — a cross between InDesign and Illustrator inside Artstr Studio. One book combines a cover spread (front + spine + back), an ordered list of interior pages, and per-page design surfaces, all driven by a shared document spec (trim size, bleed, page count, paper thickness) so that changes propagate automatically (e.g. adding pages re-computes spine width).

The three existing workflows are the building blocks:

• Cover designer → renders the book's front / back / spine spread.
• Slide-deck overview → reorganises pages and gives a thumbnail-grid table of contents.
• Custom-art canvas → the per-page design surface.

A Book document type orchestrates all three around the shared spec, exports the whole thing as a multi-page PDF, and publishes to Nostr as a manifest event that references each page / cover / master as its own addressable kind-30078 event — the same sidecar pattern Linked Designs already uses.

Product goals

1. A Nostr-native book, not a monolithic blob. The manifest event carries the spec + an ordered list of naddr refs. Each page, each master, the cover, and each prose chapter (as a NIP-23 article) are separate addressable events. Edits to one event replace only that event; the manifest changes only on structural edits (order, list, spec).
2. A single Book document UX. End-users see one cohesive editor — the sidecar plumbing is invisible. Opening a book event fans out to resolve every referenced page (with progressive fetch and a localStorage disk cache, just like Linked Designs).
3. Auto-computed spine width from pageCount × paperThicknessIn. The cover designer's spine column is derived, not user-typed; the cover re-renders whenever pages are added or removed.
4. Uniform page artboards. Every interior page inherits trim width / height / bleed from the spec, so resizing the trim updates every page in one shot.
5. Pages overview that reuses the deck-sorter UI: drag-reorder, add-blank, duplicate, delete, label, jump-to-edit. Page numbers render on each thumbnail.
6. Per-page editor that reuses the Custom Art canvas — same tools, same layer model, same renderer — but knows it's inside a book so prev / next page navigation, page-number context, and a small "page X / N" header are present. Saving a page autosaves the per-page event; saving the book updates the manifest.
7. Master pages (Indesign-style inheritance) as reusable Nostr objects. A master is its own addressable event; one master can be referenced by many books (and forked by other authors). Masters render underneath every page that inherits from them — running headers / footers, page numbers, baseline grids, margin guides.
8. Multi-page PDF export that stamps each page in order then the cover spread on its own page, with optional bleed marks and crop marks for print.
9. Per-page premium / tips (free Phase D follow-on). A book's manifest can gate individual pages via the existing PREMIUM_DESIGNS pipeline, enabling "first chapter free, rest paid" flows. NIP-57 zaps on the manifest tip the whole book; zaps on a page tip a chapter.
10. Per-page reactions and comments — because each page is its own addressable event, NIP-25 reactions and kind-1 comments work per page for free, no extra plumbing.
11. Reflowable text via Markdown + NIP-23. Prose-heavy chapters are written as markdown and published as NIP-23 long-form articles (kind-30023). The book manifest references each chapter's article event and pours its markdown into per-page text frames at render time using a book-level stylesheet (H1 / H2 / H3 / body / blockquote / code / link typography). Designed pages and reflow segments interleave in the page sequence. The same NIP-23 article can be read standalone on Habla.news and presented as a designed chapter inside a book — one source, two presentations.

Non-goals (v1)

• Reflowable text beyond the v1 markdown subset. v1 supports paragraphs, h1-h6, bold / italic / inline code, code blocks, lists (ordered + unordered), blockquotes, links, hr, and inline images (one per line). Out of scope for v1: tables, footnotes / endnotes, definition lists, GFM task lists, embedded HTML, multi-column text frames, float-around-image, ligatures beyond the renderer's defaults. Each deferred feature can land later as its own phase with its own typography rules.
• Threaded text frames across non-adjacent pages. Reflow always fills frames in master-page order; you can't manually link a frame on page 12 to one on page 47.
• A WYSIWYG markdown editor. v1 ships a textarea + live preview. Rich syntax-highlighted editing is a Phase I follow-up.
• Auto-paginated tables of contents, indices, cross-references. All of these depend on a richer flow model. Manual TOC pages are fine; a {toc} magic token that auto-builds from chapter titles is on the open-questions list.
• CMYK colour management or ICC profile attachment. PDF export is sRGB. Pro-print colour fidelity is a phase E+ concern.
• Imposition / signatures / booklet print layouts. Pages export in reading order; if a printer needs imposition they'll handle it themselves.
• Page-size variance within a single book. Every interior page has the same trim / bleed (only the cover differs). Mixed-size books are out of scope.
• Spreads-as-design-units (facing-page editing). v1 is single-page layout per page. Facing-page guide overlays can come later.
• Chained master inheritance. A master can be inherited by a page but not by another master. Single level only in v1.

Implementation status

Not started. This document is the v1 spec.

---

Why this fits the repo

Most of the primitives are already in place; Book mode is glue + spec + manifest, not a new engine.

• Linked Designs gives us the sidecar architecture for free. The resolver IIFE, schema discriminator, progressive fetch, localStorage disk cache, batched relay queries, upstream-update notifications, attribution chain (p-tags + link-tags) — every piece transfers verbatim. A book manifest is functionally a deck of linked designs with cover + masters metadata layered on. Phases 1a–3d of Linked Designs are direct dependencies.
• Layer model + targets. Each layer already keys to a target (page / cover-trim / back / spine / designer-disc / canvas). Adding book-page / book-cover-front / book-cover-back / book-spine / book-master targets is additive.
• Per-target rendering. renderLayers already filters by target and delegates to the right host; the cover designer, deck, and custom-art all coexist in one document with no special-casing in the renderer.
• Deck overview grid. The deck sorter already does thumbnail-grid reordering with drag-and-drop. Reusing it for pages is a relabel + ref-shape rename away.
• Custom-art canvas as page editor. The page editor is the Custom Art canvas. The book wraps it in prev/next nav and a page-context bar.
• Cover designer. The cover view is the existing cover designer, except the spine width is computed from the spec instead of typed.
• PREMIUM_DESIGNS already implements per-event gating (watermarked preview + zap-unlocked content). A book gates individual page events with the same machinery — no new crypto path.
• NIP-23 long-form articles are already first-class Nostr citizens with rich tooling (Habla.news, Yakihonne, others). A book chapter is a NIP-23 article event — we reuse the kind, the editor ecosystem, and the discovery surface for free. Authors can write on whatever NIP-23 client they prefer and assemble the book later.
• Nostr publish + fork + embed. Books reuse the existing publish pipeline; each constituent event reuses the same kind-30078 with new tag names.

What's actually new:

• state.book as a manifest plus a hydrated cache of referenced page / master / cover / chapter objects.
• Manifest publish flow that fans out per-page autosave events and separately versions the manifest.
• Spine derivation when page count or paper thickness changes.
• Master pages as a new event type with a single-level inheritance render pass.
• text-frame layer type on masters — a rectangular flow region the pagination engine fills with markdown content.
• Pagination engine. Markdown tokens → measured lines → page breaks, with widow / orphan rules to avoid bad page splits. Powers both on-screen render and PDF export.
• Book-level text stylesheet (spec.textStyles) that maps each markdown element to typography (font, size, weight, leading, alignment, top/bottom margin).
• Markdown editor surface in the page editor for reflow entries — a textarea with live preview of the rendered chapter, scrolled in sync with the source.
• Page-aware navigation (prev / next, page numbers).
• Multi-page PDF export. Currently there is no PDF export at all; Custom-art exports PNG/JPG and the cover designer exports per-panel PNG. Books need one PDF stamped with every page in order — with reflowed prose as real PDF text (searchable, copyable, not flattened-to-paths) where possible.
• Reader Mode (analogous to the Slide Decks' Presenter Mode) — a full-screen page-flip viewer driven off the manifest.
• Book embed — a flip-book player in the EXTERNAL_EMBED iframe transport.
• Document settings modal that owns the spec and propagates changes.

---

Framing within Template / Designer

The existing top-level modes:

Mode	Selector	Surfaces
Cover	templateMode: 'cover'	cover-trim / front / back / spine
Disc	templateMode: 'disc'	designer-disc
Custom Art	templateMode: 'customart'	canvas
Slide	templateMode: 'slide'	canvas (16:9 alias)
Deck	templateMode: 'deck'	embedded slides via deck.slides[]
Pixel-art	templateMode: 'pixelart'	canvas (palette-indexed)
Book (new)	templateMode: 'book'	book-cover-front / book-cover-back / book-spine / book-page / book-master

Book mode adds a third sidebar tab ("Pages") alongside Designer (per-page canvas) and Template (cover view). All three views read and write the same state.book document, which hydrates page / master / cover refs from Nostr via the Linked Designs resolver.

---

Data model

The book is a manifest event that references its constituent parts. Page, master, and cover events live as their own kind-30078 events and each carries a single design surface plus the metadata needed to render it.

Addressable refs

Every reference inside the manifest uses the existing addressable-event shape Linked Designs already speaks:

{ kind: 30078, pubkey: '<hex>', dTag: '<d-tag>' }

Convertible to / from naddr at the UI layer.

Book manifest (templateMode: 'book', tag casewrap-book)

{
  version: SCHEMA_VERSION,
  templateMode: 'book',
  templateType: 'book',
  meta: { … },                                  // title / category / language / tags
  book: {
    spec: {
      trimW: 6.0,                                // inches; common preset: US Trade
      trimH: 9.0,
      bleed: 0.125,                              // outside each trim edge
      paperThickness: 0.0042,                    // inches per page; default = uncoated 60# text
      spineFromPages: true,                      // false → spineWManual is used
      spineWManual: 0.5,
      coverHasSpine: true,                       // softcover yes, single-spread chapbook no
      coverHasBack: true,                        // wraparound vs front-only
      pageNumbering: {
        enabled: true,
        startAt: 1,
        firstNumberedPage: 1,                    // index into `pages` — skip cover, title, etc.
        format: '{n}',                           // '{n}' / 'Page {n}' / '— {n} —'
      },
      bookSize: 'US Trade 6×9',                  // label matching a preset
      defaultMasterRef: { … } | null,            // applied to new pages on creation
      textStyles: {                              // book-level markdown stylesheet (see "Reflowable text" below)
        body:       { fontFamily: 'Georgia', fontSize: 11, lineHeight: 1.5, color: '#111', marginAfter: 0.08, alignment: 'left' },
        h1:         { fontFamily: 'Helvetica', fontSize: 24, fontWeight: 700, marginBefore: 0.4, marginAfter: 0.2, alignment: 'center', keepWithNext: true },
        h2:         { fontFamily: 'Helvetica', fontSize: 18, fontWeight: 700, marginBefore: 0.3, marginAfter: 0.15, keepWithNext: true },
        h3:         { fontFamily: 'Helvetica', fontSize: 14, fontWeight: 700, marginBefore: 0.2, marginAfter: 0.1, keepWithNext: true },
        blockquote: { fontStyle: 'italic', marginLeft: 0.3, marginRight: 0.3 },
        codeBlock:  { fontFamily: 'monospace', fontSize: 10, background: '#f5f5f5', padding: 0.05 },
        inlineCode: { fontFamily: 'monospace', fontSize: 10, background: '#f5f5f5' },
        link:       { color: '#0066cc', underline: true },
        list:       { marginAfter: 0.08, indent: 0.2 },
        hr:         { color: '#cccccc', thickness: 0.5, marginBefore: 0.15, marginAfter: 0.15 },
      },
    },
    cover: { ref: { kind, pubkey, dTag } },      // a `casewrap-page` with role:'cover-spread'
    pages: [                                     // discriminated union; see GatingBlock + AnchorBlock below
      // 1) Designed page (fixed-layout):
      {
        id: 'entry:abc123',                      // stable opaque id, generated on insert — used by AnchorBlock and the editor's "which entry am I on"
        type: 'design',
        ref: { kind, pubkey, dTag },             // a `casewrap-page` with role:'interior'
        label: 'Title page',                     // optional sorter label override
        masterRef: { kind, pubkey, dTag } | null,// overrides spec.defaultMasterRef; null = use default
        skipNumber: false,                       // true = excluded from {page-number} sequence
        anchor: AnchorBlock | null,              // see below; null = "sits after the previous entry"
        gating: GatingBlock | null,
      },
      // 2) Reflow segment (markdown text poured into N pages):
      {
        id: 'entry:def456',
        type: 'reflow',
        textRef: { kind: 30023, pubkey, dTag },  // a NIP-23 article event carrying the chapter's markdown
        textPinnedEventId: '<hex>' | null,       // when set, lock to this exact revision (event id ref). null = always use latest addressable.
        masterRef: { kind, pubkey, dTag },       // master whose text-frame layer the markdown flows into; required, must reference a master with a text-frame layer
        chapterTitle: 'Chapter 3: The Threshold',// overrides article's title for {chapter-title} tokens
        chapterNumber: 3 | null,                 // explicit number for {chapter-number}; null = auto-numbered by reflow-segment ordinal
        startsOnPage: 'recto' | 'verso' | 'any', // bookbinding: chapter starts on right-hand page = 'recto'
        skipNumberOnFirstPage: false,            // common print convention: page number suppressed on a chapter's first page
        styleOverrides: TextStylesBlock | null,  // per-chapter overrides to spec.textStyles (rare)
        gating: GatingBlock | null,              // gates the textRef event in PREMIUM_DESIGNS pipeline
      },
      …                                          // ordered list, variable length
    ],
    masters: [                                   // refs the book wants surfaced in the Masters modal. A master ref used elsewhere (e.g. via masterRef on a page) doesn't have to appear here, but listing it makes it pickable from the UI.
      { ref: { kind, pubkey, dTag }, label: 'Body pages' },
      …
    ],
  },
}

Where:

// AnchorBlock: keeps a designed page's semantic position stable as
// reflow segments expand or contract. Without an anchor, a designed
// page sits at its array position — which can be ambiguous when a
// chapter ahead of it changes length.
AnchorBlock =
  | { mode: 'before-chapter',  entryId: 'entry:def456' }   // landed just before the named reflow entry
  | { mode: 'after-chapter',   entryId: 'entry:def456' }   // landed just after the named reflow entry's last paginated page
  | { mode: 'at-position',     after: 'entry:abc123' };    // sits right after the named designed entry (chains designed pages explicitly)

// GatingBlock: hint that this entry is paid content. Authoritative
// crypto state lives on the gated event itself; clients verify by
// reading the event, not by trusting the manifest.
GatingBlock = {
  mode: 'free' | 'premium',
  previewWatermark: true,                        // PREMIUM_DESIGNS pipeline renders watermarked preview when locked
  priceSats: 1000 | null,                        // hint only; truth is on the event
};

// TextStylesBlock: a partial map of element-name → typography
// object. Used in three places: book.spec.textStyles (the
// stylesheet), reflow entry's styleOverrides, and the master's
// text-frame.styleOverrides. Merged low-to-high precedence at
// render time.
TextStylesBlock = {
  body: TypographyObject,
  h1: TypographyObject, h2: …, h3: …, h4: …, h5: …, h6: …,
  blockquote: TypographyObject,
  codeBlock: TypographyObject, inlineCode: TypographyObject,
  link: TypographyObject,
  list: TypographyObject,
  hr: TypographyObject,
};

// TypographyObject keys (all optional):
// { fontFamily, fontSize, fontWeight, fontStyle, lineHeight, color,
//   alignment, marginBefore, marginAfter, marginLeft, marginRight,
//   underline, background, padding, indent, thickness,
//   keepWithNext, keepTogether }

Page event (kind-30078, tag casewrap-page)

{
  version: SCHEMA_VERSION,
  templateMode: 'book-page',
  templateType: 'book-page',
  meta: { … },                                  // page title / language / optional thumbnail hash
  page: {
    role: 'interior' | 'cover-spread' | 'master',
    // Sizing: a page snapshots the spec values that produced it so it
    // renders correctly even if opened standalone (e.g. via embed).
    trimW: 6.0,
    trimH: 9.0,
    bleed: 0.125,
    coverSpread: null | {                        // present only when role: 'cover-spread'
      spineW: 0.5,
      hasSpine: true,
      hasBack: true,
    },
    background: '',                              // '' = inherit master / spec; '#hex' overrides
    layers: [ … ],                               // standard layer array; targets are book-page, book-master, or book-cover-*
  },
}

Notes on the page event

• One surface per event. Whether interior, cover, or master, the event carries a single design surface so it can be opened standalone (Linked Designs viewer, embed iframe, etc.) without needing the parent book to interpret it.
• No order or numbering inside the page itself. Position in the book and skipNumber live on the manifest; the page is reusable.
• {page-number} tokens in text layers resolve at render time using context from whichever manifest is rendering the page (or show a placeholder when previewed standalone).
• Independent publish life-cycle. Page events have their own d-tag — a stable opaque id (e.g. book-page:abc123) generated at insert time, NOT derived from the page's title (titles change, d-tags shouldn't). NIP-33 replaceability works per page. Edit one page → that page event replaces; the book manifest is unaffected unless the user changes the page list or order.

Master event

Same shape as a page event with role: 'master'. Masters snapshot the spec at publish time so a stand-alone preview is sane. A master intended for reflow MUST carry exactly one text-frame layer (the manifest UI refuses to pair a master without one). A master without a text-frame is still valid for designed pages — it just doesn't participate in reflow.

Cover event

Same shape as a page event with role: 'cover-spread'. The coverSpread block records the spine width and whether the spread includes spine / back. Layers carry book-cover-front / book-cover-back / book-spine targets so the renderer can lay them out side-by-side.

Chapter event (kind-30023 NIP-23 article)

Vanilla NIP-23. The book references it via the reflow entry's textRef. The article has no book-specific schema; it's a normal long-form article and opens cleanly on Habla, Yakihonne, or any other NIP-23 client.

{
  kind: 30023,
  pubkey: '<hex>',
  created_at: <unix>,
  tags: [
    ['d', 'chapter:<slug>'],                     // standard NIP-23 d-tag for replaceable addressing
    ['title', 'Chapter 3: The Threshold'],
    ['summary', '<optional short summary>'],
    ['published_at', '<unix>'],                  // when first published (NIP-23 convention)
    ['t', 'book-chapter'],                       // optional, for discoverability in book-aware clients
    // …any other normal NIP-23 tags (language, image, etc.)
  ],
  content: '<markdown body>',
}

A book can reference any author's existing NIP-23 article as a chapter — no special encoding required. Conversely, a chapter written for a book is a perfectly normal article that any NIP-23 reader can open.

Uniqueness rules

• A given chapter event (by textRef) may appear in at most one reflow entry per book. The Pages overview refuses to add a duplicate; if a user wants two appearances they must duplicate the chapter event under a new d-tag first.
• A given designed-page event (by ref) may appear at most once per manifest. Same rule.
• Every manifest entry has a unique id. Generated at insert time; stays stable across reorders so anchors don't break.

Why a separate event for each surface

Concern	Inline-blob book	Sidecar book
200-page book event size	Tens of MB; relays reject	Manifest stays small (~10 KB); pages fetched on demand
Edit one page	Re-publishes whole book	Replaces only that page's event
Reuse a master across books	Copy-paste each time	One master event, many manifests reference it
Forks of one chapter	Must clone whole book	Fork just the page event
Per-page comments / reactions	All collapse to the book	Each page receives its own
Per-page premium / tips	Whole book or nothing	First-chapter-free is natural
Reader fetches as you scroll	Must download everything up front	Progressive fetch via the resolver

Nostr

• Book manifest: kind-30078, tag casewrap-book, d-tag book:<title|id>.
• Page / master / cover: kind-30078, tag casewrap-page, d-tag book-page:<title|id> (or book-master:/book-cover: if we want three tags for easier filter UX). Decision: one tag (casewrap-page) with role differentiating — fewer filters for clients, the role field still discriminates.
• All four event types are forkable and editable-in-place via the existing NIP-33 flow.
• Schema-version bump; the new book block + new event types are additive. Old clients see an unknown templateMode and either skip or render a stub.
• Attribution. Manifest p-tags every author that contributed a referenced page / master / cover / chapter (already how Linked Designs Phase 3a handles attribution).
• NIP-89 / kind-31990 client recommendations: a future arc; for v1 Artstr is the only client that opens these by URL.
• Chapter events are vanilla NIP-23. A book chapter is just a kind-30023 article — same kind Habla.news and Yakihonne publish. No book-specific tag is required, though we'll add an optional t tag book-chapter for discoverability. A book can reference any author's existing NIP-23 article as a chapter, and any NIP-23 client can open a referenced chapter standalone.

Schema + compatibility

• The book feature bumps SCHEMA_VERSION to 6 (current is 5).
• The new book block on the project payload is additive; older clients that load a v6 project either skip Book mode entirely or fall back to a "Unsupported template — open in latest Artstr" notice (same fallback PIXEL_ART used at its v5 bump).
• Page, master, and cover events use templateMode: 'book-page' inside their payload (one shape, three roles).
• Chapter events have no templateMode — they're raw NIP-23 articles, opaque to the book code beyond their content and metadata tags.
• Old clients seeing a casewrap-book manifest can render the feed-card thumbnail (the cover ref resolves to a normal casewrap-page event they understand visually); only opening the full editor requires v6.

Privacy

Books can be published privately via the existing PRIVATE_PUBLISHING flow: every constituent event (manifest, pages, masters, cover, chapters) can be encrypted to the author's own pubkey or shared with a specific reader set. Per-event privacy is already the model, so nothing new is needed beyond making sure the publish UI offers the choice at the right granularity (default: public; opt-in to private at publish time, applied uniformly across all constituent events of that publish action).

---

Token substitution + page-count semantics

Magic tokens that resolve at render time using the manifest's context. Tokens are honored in two places only:

1. The HTML of a regular text layer on a designed page or a master.
2. Reflow entry fields that drive on-canvas display (chapterTitle, sorter labels).

Tokens are not substituted inside a chapter event's markdown body — chapter events are vanilla NIP-23 articles that must remain portable to other long-form clients. If you want a chapter title in a running header, put a {chapter-title} token on a text layer on the chapter's reflow master, not in the markdown.

• {page-number} → the current page's number under the manifest's pageNumbering config. A skipped page renders no number (its {page-number} token resolves to empty).
• {page-count} → total numbered pages (counts excluding any skipNumber: true entries). This is what users mean when they say "page 3 of 240."
• {physical-page-count} → total pages in the manifest after reflow pagination, including skipped ones. Rarely useful but exposed for completeness.
• {book-title} → manifest meta.title.
• {book-author} → manifest pubkey resolved to a profile name.
• {chapter-title} → the current reflow segment's chapterTitle, or the NIP-23 article's title when none is overridden. Useful for running headers on master pages — the value updates as the reader moves through chapters.
• {chapter-number} → the current reflow segment's chapterNumber, or its 1-based ordinal among reflow segments if not explicit.

Tokens resolve in both the editor preview and rendered output. Standalone preview (a page event opened without its manifest) shows tokens with a greyed-out placeholder ([page], [N]).

---

Reflowable text + Markdown

Prose chapters are stored as NIP-23 long-form articles (kind-30023, markdown body). A reflow entry on the book manifest references the chapter event and pairs it with a master that has a text-frame layer; at render time the pagination engine pours the chapter's markdown into copies of the master until the chapter is exhausted. Designed pages and reflow entries interleave in the page sequence.

Why markdown

• Markdown encodes paragraph + character styles without inventing a schema. # H1, ## H2, **bold**, > blockquote, ``` ``code``, lists, links, images. The book'sspec.textStyles` defines how each element renders — that's the entire "paragraph styles" feature.
• One source, many presentations. An author writes a chapter on Habla.news. It's published as a kind-30023 article. Readers on Habla see a clean reading view. The author later assembles a book on Artstr Studio that references the same article event; readers on Artstr see it laid out as designed book pages. Edit on Habla → the next book read picks up the change.
• Event size fits. A typical chapter is 3-5K words ≈ 20-30 KB of markdown. Well within relay event limits. A 100K-word novel splits cleanly into ~30 chapter events.

text-frame layer type (new)

A new shape-like layer that masters can carry. Has:

• x / y / w / h / rotate (same as any layer)
• padding (inside the frame, inches)
• verticalAlign: top | middle | bottom
• columns: 1 in v1 (multi-column deferred)
• styleOverrides: optional partial textStyles block; merges over the manifest's spec.textStyles for prose rendered into this frame only

A master with no text-frame is invalid for use as a reflow master (the manifest UI refuses the pairing). A master with text-frame can still be used for designed pages — the frame just doesn't get filled.

spec.textStyles (book-level stylesheet)

Maps each markdown element to typography. Inheritance order at render time, low → high precedence:

1. Built-in defaults (sane fallbacks per element)
2. book.spec.textStyles
3. Reflow entry's styleOverrides (per chapter)
4. Master's text-frame.styleOverrides (per frame)

Each style block is a plain typography object — same fields the existing text layer already speaks: fontFamily, fontSize, fontWeight, fontStyle, lineHeight, color, alignment, marginBefore, marginAfter, marginLeft, marginRight, plus boolean flow controls (keepWithNext, keepTogether) for the pagination engine.

Markdown subset (v1)

Supported:

• Paragraphs (blank-line separated)
• # H1 through ###### H6
• **bold**, *italic*, ***bold-italic***, ~~strikethrough~~
• `inline code`, fenced code blocks (```)
• > blockquote (single-level)
• Ordered (1.) and unordered (-, *) lists, single level
• [link text](url) — links render with the link style; URL is preserved as a layer attribute for PDF export
• ![alt](url) inline images — one per line, full-width-of-frame, with optional alt-text caption underneath (per stylesheet config). URLs may be nostr: (resolves to a NIP-94 file event) or https:
• --- horizontal rule
• Soft line break (two trailing spaces): renders as <br>
• Hard line break (blank line): paragraph break

Deferred (Phase I+):

• Tables (own typography rules + layout pass)
• Footnotes / endnotes (need a footnote-frame layer and per-page collection)
• Definition lists, GFM task lists
• Nested lists beyond one level
• HTML embedded in markdown (security + complexity)
• Multi-column text frames
• Float-around-image (text wraps around an inline figure)

Pagination engine

Pure function: takes (markdown, frame geometry, stylesheet, master, page-context) and returns ({ pageBreaks, lineLayout, overflow }).

1. Parse markdown into a token stream using marked (~30 KB minified, MIT, vendored as src/vendor/marked.min.js). We use the lexer output directly, not the HTML renderer — we want token shapes for measurement, not HTML strings.
2. Measure each token against the current frame's available width. Text wrapping uses a Canvas2D measurement context with the right font / size loaded.
3. Line-break greedily within paragraphs (no Knuth–Plass in v1).
4. Page-break when a line doesn't fit, with these rules:
   • keepWithNext: true on a heading style → if the heading would be the last line on the page, push it to the next page too.
   • keepTogether: true on a small block (e.g. an image with its caption) → don't split it across pages.
   • Widow rule: a paragraph's last line should not stand alone at the top of the next page. If it would, push the previous line too.
   • Orphan rule: a paragraph's first line should not stand alone at the bottom of the previous page. If it would, push the heading too.
5. Generate virtual page entries (master + filled text-frame) that feed into renderLayers exactly like designed pages.

Token substitution ({chapter-title} etc.) happens at the text-frame's containing-page level, not at the token-stream level — the engine emits placeholder tokens and the page renderer substitutes on draw.

Edge cases v1 documents (and does not fix):

• A word wider than the frame: render with horizontal overflow + a warning toast.
• A code block wider than the frame: same — no auto-hyphenation, no shrink-to-fit.
• An image wider than the frame: scale down to frame width.
• A page that has zero room (the master's text-frame has negative effective height due to padding overflow): refuse and surface an error.

Anchoring designed pages around reflow segments

A reflow segment expands to N pages at render time, so designed pages can't be addressed by absolute page index — N changes when prose changes. Each designed page on the manifest carries an anchor field that references another manifest entry's stable id so the relationship survives reorders and reflow:

{ type: 'design', id: 'entry:dedication',     ref: …, anchor: { mode: 'before-chapter', entryId: 'entry:chapter-1' } }
{ type: 'design', id: 'entry:epilogue',       ref: …, anchor: { mode: 'after-chapter',  entryId: 'entry:chapter-12' } }
{ type: 'design', id: 'entry:half-title',     ref: …, anchor: { mode: 'at-position',    after: 'entry:title-page' } }
{ type: 'design', id: 'entry:title-page',     ref: …, anchor: null }   // null = "sits at its array position"

The pagination pipeline interleaves anchored designed pages around reflow segments so the semantic order is stable even as page counts shift. A new designed page is given anchor: null by default (sits at insertion order); the user can promote it to a chapter anchor from the Pages overview's per-tile menu.

Pinning chapter revisions

Text drift is the biggest reflow tradeoff: if an author edits the NIP-23 article a book references, the book's pagination changes — designed pages may shift, the printed page count may differ from what was proofed. Two modes per reflow segment:

• Pinned (textPinnedEventId set): the manifest locks to a specific event id. kind-5 deletes or addressable replacements upstream don't affect this book. Updates are explicit: an "Update pinned chapter" command pulls the latest revision and re-runs pagination.
• Live (textPinnedEventId null): the manifest tracks the addressable ref — always the latest. Linked Designs' upstream- update notification surfaces when the chapter changes, and the reader prompts to refresh.

Default: pinned at publish time. Safe by default for print runs. Authors can opt a chapter into live mode if they want "latest-always" behaviour (e.g. for a serialised work in progress).

Markdown editor surface

For each reflow entry, the page editor switches to a two-pane layout:

• Left pane: markdown textarea (autosaves to the chapter's local draft; explicit "Save chapter" publishes a new revision of the NIP-23 event).
• Right pane: live preview rendered through the same pagination engine the book will use, showing the chapter as paginated pages with the selected master applied.

v1 ships a plain textarea + preview; a syntax-highlighted CodeMirror upgrade is a Phase I follow-up.

The editor also exposes:

• A "Import from Nostr" field that paste-fetches an existing kind-30023 article event and seeds the textarea with its content.
• A "Pin / Live" toggle.
• A "Re-paginate now" button (shows page count + warns about changes since last paginate).

---

The surfaces

1. Document settings modal

Owns the spec. Accessible from a "Document settings" button in every book view. Fields:

• Book size preset: US Trade 6×9, US Letter 8.5×11, A5 5.83×8.27, A4 8.27×11.69, Square 8×8, Custom. Picking a preset fills trim width/height + sensible default bleed and paper-thickness; switching to Custom unlocks them.
• Trim width / Trim height (inches, numeric).
• Bleed (inches, numeric, default 0.125).
• Paper thickness (inches per page) + Spine from pages? checkbox. When checked, spine width is derived; when unchecked, a manual Spine width field appears.
• Cover layout: wraparound (front + spine + back) / front-only.
• Page numbering: enabled toggle + start-at, first-numbered-page, format string.
• Default master: dropdown of refs registered in book.masters.

Editing trim prompts confirmation — "Page events that snapshotted the old trim won't auto-resize; you may need to re-publish each page." Apply re-runs cover surface fit and pushes the new spec into newly created pages.

2. Cover view

Reuses the existing cover designer host, bound to whatever event the manifest's cover.ref resolves to. Differences from the standalone cover designer:

• The spine column width is read-only when spineFromPages = true; shows the computed value with a hint ("derived from N pages × paper thickness"). When manual, the existing typed-in field is editable and writes back to the spec.
• Saving the cover publishes the cover event (via the page autosave flow); the manifest is updated only if the cover ref needs to change (e.g. forking a referenced cover into a local copy for edits).
• A "Replace cover with…" picker scoped to the casewrap-page events with role: 'cover-spread' category.

3. Pages overview

Reuses the deck-sorter component. Differences:

• Title says "Pages" with three counters: Numbered: N, Physical: M (after reflow pagination), Reflow segments: K.
• Two tile styles by entry type:
  • Designed-page tile: a thumbnail of the rendered page, just like the deck sorter shows slides today.
  • Reflow tile: a stack-of-pages icon with the chapter title, chapter number, a master-name pill, the latest paginated page count (e.g. "Chapter 3 — Body pages master — 14 pages"), and a tiny preview thumbnail of the chapter's first paginated page.
• Drag-reorder writes back to book.pages[]. Numbering and reflow re-paginate live; the manifest event is marked dirty for republish.
• Per-tile menu — designed: Edit, Duplicate, Delete (removes from manifest; the page event itself is left untouched on relays), Apply master…, Skip numbering, Rename, Open standalone.
• Per-tile menu — reflow: Edit chapter (opens the markdown editor), Change master…, Pin / Live toggle, Re-paginate, Open chapter on Habla (link to the NIP-23 article on a public long-form client for cross-checking), Delete from book.
• A toolbar above the grid: + Add designed page, + Add chapter (creates a new draft NIP-23 article + a reflow entry referencing it), Import chapter from Nostr (paste an existing kind-30023 article id; manifest gets a ref to it without republishing), Import designed page from Nostr, Manage masters…, Document settings.

4. Per-page editor

The existing Custom Art canvas with three wraps:

• A page-context bar at the top of the canvas: Page 12 / 248, prev / next arrows (← / →), a master-page badge ("Inheriting: Body pages"), and a "Back to Pages" button.
• A master layer underlay: master layers render under the page's own layers, with reduced opacity (~50 %) and a small "M" badge when a master layer is hovered, to make the inheritance obvious. Master layers are not editable from the page editor — they're click- through to the page layer below. To edit a master, the user opens it from the masters modal (which routes back to the same canvas in master-edit mode — the only difference is which target the editor binds new layers to).
• A trim + bleed guides overlay (already exists in cover designer conceptually). Trim is dashed red, bleed is dashed teal, optional margin / gutter from the spec is faint grey.

Editing a layer marks the page event as dirty for autosave. Saving publishes that page event (NIP-33 replace). The manifest is only marked dirty if the user changes the page's inheritsMasterRef, skipNumber, or label (manifest-owned fields).

5. Masters modal

Lists book.masters refs. Per-row Edit / Duplicate / Delete from list / Rename / Set-as-default. "+ New master" creates a new casewrap-page event with role: 'master' under the user's pubkey and appends its ref to the manifest. "Import master from Nostr" pastes in an existing master ref so the book can reuse another author's master.

6. Reader Mode

Analogous to the Slide Decks' Presenter Mode. A full-screen page-flip viewer driven off the manifest. Pulls page events progressively as the user moves forward (with prefetch of next 2 pages); previously-viewed pages cached in localStorage via the existing Linked Designs disk cache.

• Keyboard nav: → / Space / PageDown advance; ← / PageUp back; Home / End jump to first / last; Esc exits.
• Mouse / touch: click right half advances, left half retreats; swipe on touch.
• Sidebar TOC: scrollable list of page labels with current-page highlight; click to jump.
• Page count footer: 12 / 248 plus a thin progress bar.
• Premium-gated pages render the watermarked preview by default; an inline "Unlock with zap" CTA opens the existing PREMIUM_DESIGNS modal.

Launches from a ▶ Read button on the manifest's preview pane and a keyboard shortcut from the Pages overview.

7. Embed integration

The EXTERNAL_EMBED viewer learns a ?book=<naddr> mode that renders the manifest in a flip-book player (cut-down Reader Mode without the TOC sidebar; arrows + swipe only). Re-uses the same iframe transport and CSP rules; no new origin work needed.

---

Cross-surface reactivity rules

1. Page count changes (add / delete / reorder) → spec.spineW recomputed if spineFromPages → cover view re-renders with the new spine column width → cover layers re-clamped if any straddled the old spine boundary (warn but don't auto-move) → manifest marked dirty.
2. Trim size changes → cover surface sizes recompute. Existing page events keep their snapshotted trim (since their content was designed for that size); a "Re-publish snapshot" action regenerates the page event's trimW / trimH. Users get a one-time toast.
3. Bleed changes → guide overlays update; layer coordinates and page events untouched.
4. Master edit → master event republishes. Every page referencing that master re-renders on next view (the Linked Designs auto-update notification surfaces the new version).
5. Upstream page / master / cover updated externally → Linked Designs already does this: a "New version available" badge in the sorter tile / cover-view header; user clicks to accept and refetch.
6. Page-numbering format change → all numbered page thumbnails re-render their badges. Numbering is never baked into page layers; it lives only as {page-number} token text on a master (or wherever the author chose to place it). Manifest marked dirty.
7. Duplicate page → creates a new page event under the user's pubkey (not a manifest-internal copy); both the original and the duplicate are independent events going forward.

---

Premium, tipping, gating

PREMIUM_DESIGNS already implements per-event premium gating. Books layer on top with per-page gating as a v1 capability and manifest-level gating for whole-book paywalls.

• Free book. Default. Manifest and every page event publish without premium fields.
• Whole-book paywall. Gate the manifest event itself with PREMIUM_DESIGNS' encrypted-publish path. Readers see metadata + a cover thumbnail; unlocking the manifest gives them refs to (already free) page events. Cleanest model when the author wants to gate everything.
• First-chapter-free / rest paid. Gate individual page events. The manifest stays free (so previews / discovery work). When the reader hits a gated page, Reader Mode shows the watermarked preview and an unlock CTA. Each page can have its own price.
• Tips. NIP-57 zaps work on whatever event the user is zapping — manifest, individual page, or master. The author's lightning address on their profile is the destination as usual.

The manifest's per-page gating object is a hint to clients; it does not duplicate the crypto state, which lives on the page event itself. Clients should always verify gating by inspecting the page event when loading it.

---

PDF export

What v1 produces

• One PDF with N + (1 or 2) pages: every interior page in order, then the cover spread on its own landscape page. (Back / spine / front flow follows the cover designer's existing left-to-right layout.)
• Page size: trimW × trimH plus bleed margin if "include bleed" is on. Cover page size: full cover-spread width × trim height plus bleed.
• sRGB. No ICC embedding. Fonts on the embeddable allowlist (Georgia, Times, Helvetica, Arial, monospace family) are subset-embedded; layers using any other font fall back to vector paths and are listed in a per-export warning so authors can pick whether to swap fonts before re-exporting.
• Crop marks toggle: thin black L-marks at each trim corner, offset outside the trim by the bleed amount.

Library

pdf-lib (~80 KB minified, MIT). Pure-JS, runs in the browser, supports images, SVG paths (via converting our d strings into PDF path ops), text, fonts, page management. Vendored as src/vendor/pdf-lib.min.js the same way polygon-clipping is.

Pipeline

For each page (resolved via the manifest):

1. Build a virtual canvas at the page's pixel resolution (e.g. trimW × 300dpi).
2. Run the existing renderLayers pipeline against that virtual canvas. This already handles every layer type (shape, image, text, QR, pixelart, linked design, deck slide, pathfinder result).
3. Token-substitute {page-number} etc. at render time using the manifest's pageNumbering config.
4. Take the rendered output and stamp it into a new PDF page via pdf-lib. Text layers — both designed-page text layers and the pagination engine's reflowed prose — emit as real PDF text objects (vector, searchable, copyable) when the font is on the allowlist; otherwise fall back to vector paths with the per-export warning. This applies uniformly to both reflowed prose and designed-page text.
5. Cover page is single-PDF-page with the full spread; print shops typically want it as one wide spread, so a separate "Cover-only PDF" download is also offered.

Export UI

A new "Export PDF…" button in the Pages overview toolbar and the Cover view toolbar opens an export modal:

• Interior pages: All / range / current
• Include cover spread: yes / no
• Include crop marks: yes / no
• Include bleed: yes / no
• Output: Interior + Cover (single file) / Interior PDF + Cover PDF (two files). Print shops often want them separate.
• Filename pattern.

Limitations baked in v1

• Layers using fonts outside the embeddable allowlist fall back to vector-path text (still visually identical, just not selectable in the PDF). The per-export warning lists which layers were affected.
• No PDF bookmarks / outline / TOC links. Phase I+ adds bookmarks built from each reflow segment's chapterTitle and the {toc} token's targets.
• No press-quality CMYK profile.
• Premium-gated pages: by default the export refuses to include them if the user is not the author or hasn't unlocked them. A user exporting their own book gets everything; a reader who has zapped to unlock can export the unlocked subset.

---

Master pages

A master is a page-shaped Nostr event (kind-30078, casewrap-page, role: 'master') whose layers paint under every page that inherits it. Used for:

• Running headers / footers
• Page numbers (via {page-number} tokens — substituted per page at render time)
• Margin guides drawn as faint shape layers (optional)
• Background art / chapter dividers

Inheritance rule

• A page-list entry declares inheritsMasterRef: { kind, pubkey, dTag }. Render: master layers first (filtered by their book-master target), then page layers on top. Master layers are non-interactive in the page editor.
• Single level of inheritance only in v1 — masters cannot inherit from other masters. Chained inheritance is a follow-up.
• Default master: spec.defaultMasterRef — applied to any page whose inheritsMasterRef is null. New pages adopt it on creation.
• A master ref can point to any author's master event, enabling reuse: ship one "Body pages" master and many books reference it.

---

Phased delivery

MVP launch path

Book mode is a large feature. The phase order is set up so each phase ships independently and the project never sits in a half-done state. Two reasonable launch targets:

• MVP-A: Designed-only books. Phases A + B + D1 + D2. A user can lay out a fixed-layout book with cover + designed interior pages and publish it as a manifest + sidecar events. No reflow, no PDF, no Reader Mode. Useful for art books, zines, photo books, comic chapbooks.
• MVP-B: Books with prose. MVP-A + Phase C + C.5 + E. Adds masters, reflowable chapters via NIP-23, and PDF export. This is the full "book designer" experience.

Phases F (templates + deck-to-book import), G (Reader Mode + embed), H (premium gating), and I (markdown + extras) are strict enhancements — none of them block MVP-A or MVP-B.

Phase A — Spec + Book mode skeleton

• New templateMode: 'book' with state.book = { spec, cover: null, masters: [], pages: [] }. Default spec: US Trade 6×9, 0.125 bleed, 0 pages.
• Sidebar Template tab gets a "Book" entry alongside Cover / Disc / Custom Art / Slide / Deck.
• Empty Pages overview view (deck sorter clone, no pages yet) and Cover view (cover designer in spec-aware mode, spine derived).
• Document settings modal with all spec fields wired.
• Save / load / autosave: the book block round-trips alongside existing modes; refs are stored but no Nostr publish yet.

Phase B — Pages overview + per-page editor

• Add / duplicate / delete / drag-reorder pages. Pages exist as in-memory objects with provisional ids; not yet published.
• Per-page editor (Custom Art canvas bound to book-page target).
• Page-context bar (prev / next / Back to Pages).
• Page numbering live in thumbnails + the editor header. Token substitution implemented for {page-number} / {page-count} / {physical-page-count} / {book-title} / {book-author}.

Phase C — Master pages

• Masters modal, master-edit mode in the canvas, master-layer underlay in the page editor.
• Default master applied to new pages.
• text-frame layer type added — masters can carry a text-frame on the canvas (a new layer kind that renders as a labelled rectangle in the editor and is the future drop-target for prose). No reflow yet; the frame is purely structural.
• Masters still in-memory, not yet published.

Phase C.5 — Reflowable text (markdown + pagination)

• Vendor marked (~30 KB MIT) as src/vendor/marked.min.js.
• Implement the pagination engine (token stream → measured lines → page breaks, with widow / orphan + keepWithNext / keepTogether). Pure-function shape so it's testable in isolation.
• spec.textStyles editor in Document settings.
• reflow-type entries in book.pages[]; pages overview tiles render reflow segments with the "stack of pages" affordance and paginated page-count.
• Markdown editor pane in the per-page editor for reflow entries (textarea + live preview).
• Anchoring of designed pages around reflow segments (anchor.mode = 'before-chapter' | 'after-chapter' | 'at-position').
• {chapter-title} / {chapter-number} tokens substitute correctly in master text layers.
• Pin / Live revision tracking for chapter refs.
• text-frame layer is now functional — masters with one become valid reflow-master targets; masters without one are rejected by the "Set master" picker for reflow entries.
• NIP-23 import: paste a kind-30023 article id, get a reflow entry that references it.

Phase D1 — Publish individual page / cover / master / chapter events

• Per-page autosave publishes a casewrap-page event. Provisional ids are upgraded to real naddr refs on first publish.
• Cover save publishes its own casewrap-page event with role: 'cover-spread'.
• Master save publishes a casewrap-page event with role: 'master'.
• Chapter save publishes a kind-30023 (NIP-23) article event. Title comes from the reflow entry's chapterTitle; body is the markdown source. The article event is independent — readable on any NIP-23 client.
• Linked Designs resolver wired so opening a book on a second client / device fetches the referenced events progressively.
• Disk cache: page / master / cover / chapter events cached in localStorage so re-opens are instant offline.
• Upstream-update notifications surface on the sorter tiles + cover-view header when a referenced event has a newer version upstream; for chapters, the notice also reports the new word count delta.

Phase D2 — Publish the manifest

• Manifest publish path: casewrap-book event with the spec + list of naddr refs. Manifest is dirty whenever spec / page order / page list / per-page-manifest-fields change.
• Fork (community browser): clones the manifest under the user's pubkey; referenced pages stay as upstream refs unless the user explicitly "Make local copy" on a per-page basis.
• Attribution: manifest p-tags every author that contributed a referenced event (Linked Designs Phase 3a).
• Feed-card preview shows the cover spread thumbnail + page count.

Phase E — PDF export

• Vendor pdf-lib. Build the render-to-PDF pipeline.
• Reflowed prose exports as real PDF text (not flattened paths) using pdf-lib's font subsetting. Designed-page text layers whose font isn't embeddable fall back to vector-path text with a per-export warning listing which layers were flattened.
• Export modal in Pages + Cover toolbars.
• Bleed + crop marks options. Single-file and split (cover + interior) output modes.
• Gated-page export rules enforced.
• A "Proof one page" quick-export emits a single page or a single chapter as a PDF — useful for sending to a printer to test colour / paper before exporting the full book.

Phase F — Templates + import polish

• New book template category for the community browser; templates ship at common sizes (US Trade, A5, A4).
• Import a deck → convert to a book of N pages, each page seeded with one slide's layers (cross-aspect letterbox-fit). Letting users bootstrap a book from a deck is the cleanest reuse story.
• Import a single page from another book (already works via Phase D1's Linked Designs plumbing — formalise the UI).

Phase G — Reader Mode + embed

• Full-screen Reader Mode with TOC sidebar, page-flip nav, progressive fetch, premium-gate handling, NIP-57 zap inline.
• EXTERNAL_EMBED ?book=<naddr> mode — flip-book in the iframe.
• Per-page NIP-25 reactions + kind-1 comments surfaced in the reader (already work natively because pages are addressable; this phase is just UX surfacing).

Phase H — Premium / gating polish

• Per-page paywall toggle in the page editor. Manifest carries the gating hint; the page event carries the actual encrypted payload.
• Whole-book paywall via gating the manifest itself.
• "Unlock with zap" flow tested end-to-end in Reader Mode.

Phase I — Markdown editor + extended subset

• Replace the plain textarea with a syntax-highlighted CodeMirror instance (~150 KB minified, vendored). Adds inline rendering hints, smart quotes, list-continuation, drag-and-drop image insert.
• Extended markdown features, each added with its own typography rules and pagination handling:
  • Tables with column-width balancing and per-cell alignment.
  • Footnotes — a footnote-frame layer on masters collects references per page; reference markers in the flow render as superscripts.
  • Nested lists beyond one level (typography per level).
  • Definition lists, GFM task lists.
• Auto-generated TOC via {toc} magic token that walks every reflow segment's H1 / H2 / H3 headings and emits a styled list with page numbers.
• Auto-generated index via {index} and inline ^[term] markers in the markdown source.
• Cross-references: [See chapter 3](#chapter-3) resolves to a page number at render time.

---

Risks & tradeoffs

• Many small events instead of one big event. Fetching 200 page events is 200 relay round-trips' worth of overhead vs one fat download. Mitigation: the Linked Designs batched-query resolver (Phase 3d) already coalesces refs into bulk filters; localStorage disk cache keeps re-opens instant; Reader Mode prefetches the next two pages aggressively.
• Manifest atomicity. Manifest publish and per-page publish are not transactionally linked. If a user republishes a page and reorders pages in the same session, the manifest can land before the page event reaches all relays. Mitigate with: publish pages first, then manifest; show a "syncing" indicator until both land.
• Master-layer perf. Rendering master + page on every page-view switch is 2× the layer work. Acceptable in v1 with the existing renderer; if it bites, cache rasterised master snapshots.
• PDF correctness. This is the biggest correctness risk — print output that's slightly off can cost the user money at the printer. Mitigate with: clear preview before download, bleed / crop options explicit, and a "test page" download for proofing a single page before exporting the whole book.
• Trim-resize collateral. Resizing trim mid-design leaves layers out of bounds on pages that snapshotted the old trim. v1 warns and offers per-page re-snapshot; no auto-scale.
• Reference rot. A referenced master / page event's author can delete it (kind-5 tombstone) and the book breaks. Mitigation: the manifest's "Make local copy" action lifts a ref into a copy under the current user's pubkey. Encouraged at publish time for refs that aren't your own.
• Two-level navigation. Pages → Page editor → back to Pages — the user has to remember where they are. The page-context bar with prev / next / "Back to Pages" is essential and should never be hidden.
• Pagination is fiddly. Pagination engines have a long tail of edge cases — long words on narrow columns, code blocks wider than the frame, images that should keep with their caption, mid-line font changes. Mitigations:
  • Tight v1 subset. Document the supported markdown subset explicitly. Each deferred feature lands as a separate phase with its own tests.
  • Pure-function engine so it's testable in isolation: feed it a markdown string + frame geometry + stylesheet, assert page breaks. Build a small canonical corpus of "should paginate these ways" fixtures.
  • "Preview pagination" command before publish so the author sees the page count + any overflow warnings without committing.
  • Overflow warnings in the editor: a long word, a too-wide code block, a margin that swallows the frame — each emits a toast pointing at the offending line, rather than silently rendering wrong.
• Text drift breaking pagination. A chapter event updates upstream → its word count changes → physical page count shifts → designed pages anchored after that chapter move. Mitigations:
  • Pin chapters at publish time by default. Authors who want "latest-always" opt-in to live mode per chapter.
  • Re-paginate notice when a live chapter changes, with a diff (+12 pages / -3 pages) shown in the sorter so the author knows what shifted before accepting the update.
  • Anchor-based designed pages. Designed pages on the manifest use anchor.mode: 'before-chapter' | 'after-chapter' rather than absolute index, so they stay semantically in place even when page counts shift.
• PDF text fidelity for reflowed prose. Reflowed paragraphs must export as real PDF text objects (searchable, copyable) — the Phase E PDF pipeline uses pdf-lib font subsetting for this. Mitigations:
  • Font allowlist. Document settings restricts text-frame fonts to ones we know pdf-lib can subset cleanly (start with a small set of bundled web-safe fonts: Georgia, Times, Helvetica, Arial, monospace).
  • Fallback to vector paths for fonts outside the allowlist, with a per-export warning listing which paragraphs were flattened.
• Markdown editor scope. Building a full WYSIWYG markdown editor would eat the v1 timeline. Mitigation: ship a plain textarea + live preview for v1 (Phase C.5). CodeMirror upgrade is Phase I. A WYSIWYG editor is explicitly never in scope — markdown is the source of truth, not a transient representation.

---

Open questions

• Facing pages. Do we want a v1.5 facing-page preview (two pages side by side) even without facing-page editing? It's a small render addition; useful for previewing recto / verso bookbinding before print.
• Bleed guide in the per-page editor. Show as a guide always, or toggleable? Cover designer shows it always; recommend matching for consistency unless user research surfaces a reason not to.
• background precedence. Spec puts background on the page event, the master, and spec (implicitly). Proposed precedence: page event's background wins, then master's, then spec default (#ffffff). Lock this in code review of Phase B.
• Manifest event size at the extreme. A 1,000-page book's manifest is ~1,000 refs × ~80 bytes = ~80 KB. Approaching relay limits. If we ever hit them, the manifest itself can be sharded (chapter-manifests referenced from a top-level book event). Not worth solving until a real user runs into it.
• NIP-89 / client recommendations. Publishing a kind-31990 recommendation so other Nostr clients know to open casewrap-book / casewrap-page events with Artstr Studio is worth doing eventually but only matters once a competing viewer exists.
• Inline-image source resolution. v1 markdown images accept https:// URLs. Adding nostr: resolution (image events under NIP-94, profile pictures by npub) is a small Phase C.5 follow-up worth scoping once the engine is working.

Compatibility notes

• Linked Designs inside pages. A page can include a Linked Design layer (e.g. an illustration pulled from another author). The existing async resolver path handles it; no special book code needed. Worth a smoke test in Phase B since this is the first place we render a Linked Design inside a page that is itself fetched via the resolver — a two-level lookup.
• Layer types known to work on a book page. All existing layer types (shape, image, text, qr, pixelart, design, slide) render unchanged on book-page / book-master / book-cover-* targets — the renderer keys off layer type, not target. The new text-frame layer is the only book-specific layer type.

---

Acceptance summary

Phase A — Book mode skeleton

• templateMode: 'book' saves + restores via autosave.
• Document settings modal applies every spec field and the cover view's spine width updates live when paperThickness or page count changes.
• Cover view renders an empty front / back / spine surfaces sized to the spec.
• Pages overview view renders an empty grid with an Add Page button.

Phase B — Pages overview + per-page editor

• Add / duplicate / delete / drag-reorder writes back to book.pages and the numbering reflects the new order.
• Clicking a tile opens the per-page editor; prev / next walk the page list.
• Layers added in the editor are bound to book-page and persist across reloads.
• {page-number} / {page-count} / {physical-page-count} / {book-title} / {book-author} tokens substitute correctly in text layers (live in the editor + in thumbnails).

Phase C — Master pages

• At least one master exists; pages inheriting it render the master layers below their own.
• Master-layer underlay is non-interactive in the page editor (hover shows an "M" badge, click passes through).
• A master can carry a text-frame layer; the editor renders it as a labelled rectangle but the frame is empty (no reflow yet).

Phase C.5 — Reflowable text

• A reflow entry on the manifest renders the chapter's markdown into the chosen master's text-frame, paginating across as many pages as the prose needs.
• Each markdown element type (H1 / H2 / H3 / body / blockquote / code / list / link / image / hr) renders with the typography defined by spec.textStyles.
• keepWithNext on headings prevents a heading-as-last-line on any page; widow / orphan rules prevent single-line splits.
• {chapter-title} / {chapter-number} tokens on master text layers resolve to the containing chapter's values.
• Designed pages with anchor.mode: 'before-chapter' | 'after-chapter' interleave around reflow segments correctly, and stay in place semantically when prose changes.
• Pin / Live revision tracking: a pinned chapter ignores upstream updates; a live chapter surfaces an update notice with page-count delta.
• "Preview pagination" shows page count + overflow warnings before publish.

Phase D1 — Per-event publish

• Saving a page publishes a casewrap-page kind-30078 event under the user's pubkey.
• Saving a chapter publishes a kind-30023 NIP-23 article event; the same event opens cleanly on Habla.news as a long-form article.
• Reopening a book on a second device resolves every page / master / cover / chapter ref via the Linked Designs resolver.
• An upstream master update surfaces a "new version available" notice in the masters modal and (when accepted) propagates to every page that inherits it.

Phase D2 — Manifest publish

• A book publishes as casewrap-book and reopens losslessly across devices.
• Manifest p-tags every author of every referenced event (attribution chain).
• Community-browser feed-card shows the cover thumbnail + page count.

Phase E — PDF export

• Export modal produces a PDF with the expected page count + cover spread on a separate page.
• Reflowed prose exports as real PDF text (searchable + copyable) for fonts on the allowlist; a per-export warning lists any layers that fell back to vector paths.
• Bleed + crop-marks toggle work; output passes a visual diff against a hand-laid InDesign export of the same book at a single reference size.
• A premium-gated page included in the export is replaced by the watermarked preview when the user is not authorised to unlock it.
• "Proof one page" / "Proof one chapter" produces a single-page PDF in under 2 seconds end-to-end.

Phase F — Templates + import polish

• At least three book templates ship at common sizes (US Trade 6×9, A5, US Letter); each opens as a fresh book with master(s) configured.
• Import-from-deck produces a book of N designed pages whose layouts match the deck's slides (letterboxed when the deck aspect doesn't match the book trim).
• Import-single-page from another book lands a Linked-Designs ref in the manifest without re-publishing the page.

Phase G — Reader Mode + embed

• Reader Mode walks the manifest's pages with progressive fetch; prev / next page navigation works keyboard + touch + click.
• Reader Mode works on a book with no reflow segments (designed-only) and on a book with only reflow segments (prose-only).
• EXTERNAL_EMBED ?book=<naddr> opens the same book in an iframe flip-book.
• A gated page in Reader Mode shows the watermarked preview and a working "Unlock with zap" CTA.

Phase H — Premium gating

• A book with one gated chapter publishes; an unauthorised reader sees the preview; a reader who zaps to unlock sees the real content in Reader Mode without re-opening the book.
• A book whose manifest itself is gated shows only its cover thumbnail + price to unauthorised readers; the page list resolves after unlock.

Phase I — Markdown editor + extended subset

• CodeMirror editor replaces the plain textarea for reflow entries; syntax highlighting + smart list continuation + drag- and-drop image insert work.
• Each extended markdown feature (tables, footnotes, nested lists, definition lists) has typography rules in spec.textStyles, paginates correctly across page breaks, and is acceptance-tested with its own fixture set in the engine's canonical corpus.
• {toc} magic token expands into a styled list of chapter titles with page numbers; updates live as reflow re-paginates.
• Cross-references ([See chapter 3](#chapter-3)) resolve to the right page number in both Reader Mode and PDF output.
• PDF export includes a bookmarks outline built from chapterTitle per reflow segment.