Product Specification

The full, current spec for Integral Flipbook. Click the button above to download it as Markdown.

# Integral Flipbook — Product Specification

_Last updated: September 17, 2026_

## Overview

Integral Flipbook turns a PDF into a realistic, embeddable, animated page-curl flipbook. Users upload a PDF, optionally add a mobile-optimized PDF, brand the viewer, and share a public link or paste an iframe snippet into any site (BookFunnels, WordPress, custom sites, etc.).

## Goals

- Give book authors and marketers a fast, unlimited, self-serve alternative to expensive flipbook services (e.g. Paperturn).
- Realistic 3D page-turn on desktop and mobile.
- Zero-friction sharing: public link + copy-paste iframe.
- Per-book branding and reader analytics.

## Tech stack

- **Frontend:** React 19, TanStack Start v1 (SSR), TanStack Router (file-based), Tailwind CSS v4.
- **Flipbook engine:** `page-flip` (StPageFlip) — realistic 3D curl, drag-to-turn, click, swipe, keyboard, double-page spreads on desktop.
- **PDF rendering:** `pdfjs-dist` runs in the browser and rasterizes each page to lossless PNG at upload time — the viewer never touches the PDF.
- **Backend:** Lovable Cloud (Postgres + Storage + Auth). RLS enabled on every table.
- **Hosting:** Cloudflare Workers via TanStack Start.

## Data model

- `books` — id, owner_id, title, slug, theme JSON (colors, logo), created_at.
- `book_pages` — book_id, variant ('desktop' | 'mobile'), page_number, image_url. One row per rendered page per variant.
- `book_toc` — book_id, title, page_number (auto-extracted from PDF outline).
- `book_events` — book_id, session_id, event_type ('open' | 'page_view' | 'close'), page_number, user_agent, timestamp.
- Storage buckets: `flipbook-pages` (public rendered images), `flipbook-assets` (logos).

## Auth

- Email + password sign-in via Lovable Cloud.
- `auto_confirm_email` = true (no email confirmation).
- HIBP password strength check disabled.
- No anonymous sign-ups. One admin account per registered user.

## Upload pipeline

1. User selects a PDF in the admin dashboard (desktop variant, optional mobile variant).
2. Browser loads PDF.js and rasterizes each page to a 3000px lossless PNG (or 2000px for mobile).
3. Each page uploads to a fresh revision folder in `flipbook-pages` storage; rows insert into `book_pages` with the correct variant. Fresh page URLs prevent old compressed images being reused from caches; book links and embeds remain unchanged.
4. PDF outline (bookmarks) parsed to `book_toc`.
5. Progress bar reports "page X of Y".

## Format from Word (`/admin/new-from-word`)

For authors without a print-ready PDF. A 5-step wizard: upload .docx + book details, check/rename/merge detected chapters and set each row's type (Part / Chapter / No number); markers are "PART I" or "CHAPTER N" lines (title on same or next line, blank lines ignored; numbers as digits, Roman numerals or words) or Heading 1, choose style (Times New Roman (default) or Garamond, paragraph indentation or spacing, drop caps, "CHAPTER N" label, title/copyright/contents pages, one chapter image for all chapters and/or per chapter), preview spreads, then download the 6x9 PDF and/or create the flipbook. Typesetting runs in the browser (mammoth + pdf-lib). The print PDF is stored privately per book and downloadable from the book's admin page.

## Viewer (`/book/:slug`)

- Renders standalone (no app chrome) — safe to iframe.
- Detects viewport width; serves the mobile variant when width < 768px if available.
- When both variants exist, a Desktop / Mobile pill toggle appears.
- Controls: prev / next buttons, keyboard arrows, click-to-turn, drag-to-turn, swipe on touch, page number readout, TOC sidebar, fullscreen.
- 1px inset black border on every page for a real-book edge.
- Applies per-book theme (background, accent) and optional logo.
- Emits open / page_view / close events to `book_events`.

## Admin dashboard

- `/admin` — list of the signed-in user's books, upload new book (desktop + optional mobile PDF), per-book stats at a glance.
- `/admin/:slug` — per-book:
  - Branding (background, accent, logo).
  - Versions section: replace or delete the desktop or mobile variant independently.
  - Analytics: opens over time, unique readers, page-by-page heatmap (drop-off), average session length.
  - Embed snippet: ready-to-paste `<iframe>` for the public viewer URL.
- Main user menu links to the User Guide for creation and embedding instructions.
- No hard limits on number of books per user.

## Mobile variant

- Optional per-book. Recommended source PDF size: standard smaller iPhone page (~375×667pt); scales up cleanly on larger phones.
- Stored as a separate set of pages under `variant = 'mobile'`.
- Viewer auto-selects on phone widths and offers a manual toggle when both variants exist.

## Embedding

Every book exposes:

```html
<iframe src="https://integralflipbook.com/book/YOUR-SLUG"
        width="100%" height="700" frameborder="0" allowfullscreen>
</iframe>
```

The viewer route is public and iframe-friendly (no auth, no app chrome).

## Analytics

Lightweight, first-party (no third-party trackers). Events written directly to `book_events`. The admin dashboard aggregates:

- Opens over time.
- Unique reader sessions.
- Pages viewed per session.
- Page-by-page heatmap showing where readers drop off.
- Average time on book.

## Branding / theme

Global product design follows the Integral Style Guide:

- Light foundation, near-black foreground.
- Display font: Poppins. Body: Inter.
- Hero accents: yellow #FFD329, pink #FF5CB8, mint #7CEDC0, cyan #5CE4FF, blue #387CFF.

Per-book branding lets authors override background, accent, and logo inside their own viewer.

## Aesthetics

- Contents appendix labels (October 18, 2026): preserve uppercase identifiers in Appendix A:, Appendix B:, and Appendix C: while retaining Title Case titles, the approved smaller Contents font, and full-title wrapping. An appendix identifier is not the lowercase article "a".
- Site identity (October 13, 2026): the favicon uses the exact blue open-book outline from the masthead. Homepage sharing titles and descriptions identify Integral Flipbook and its PDF/Word-to-flipbook offering; other pages must not inherit homepage-specific Twitter titles. The hosted social image was visually inspected: it shows the flipbook site and its offering, not a Lovable advertisement, so it is retained.
- Appendix pagination (October 17, 2026): headings and fully bold standalone paragraphs travel with the following content. Reserve the actual repeated table header and first body row, not a generic two prose lines; consecutive labels travel together. Prefer white space at the previous page bottom over a label separated from its table. Inline bold emphasis remains ordinary prose.
- High-density reader check (Compass, October 12, 2026): saved pages remained 2000×3000, but page-flip drew its canvas at one pixel per CSS pixel on a 2.5× screen, softening text. The reader now scales its backing canvas to screen density (up to 3×), while retaining the same visible page size, drag coordinates, and animated curl. This display correction does not replace saved book pages or change embed addresses.
- User-facing guide pages use the Integral light foundation, bold Poppins headings, compact Inter body text, clean instructional bands, and restrained accent blocks.
- Guide layout prioritizes fast scanning: short sections, numbered steps, practical checklists, and downloadable PDF / Markdown actions at the top.
- Flipbook clarity test (Founder Leadership, pages 30–31): at identical visible page size, 1400px JPEG at 82% blurred small serif strokes and fine map lines; 1400px JPEG at 95% reduced artifacts; 2000px JPEG at 94% and 2000px lossless pages kept the cleanest details. Two-page samples were ~625 KB, ~943 KB, ~1491 KB, and ~696 KB (lossless WebP) respectively. In the actual browser renderer, 2000px PNG was ~2395 KB for the pair, without a meaningful visible improvement over 2000px JPEG. High-quality JPEG is the more practical choice; the embedded map in the source PDF is raster artwork, so page resolution cannot add detail absent from the drawing.
- October 12 quality escalation: Compass's actual saved desktop pages measured 2000×3000 (pages 10/30: ~893/~870 KB), compared with older 1400×2100 Leadership/Journey pages. Its density transform remained 2.5× after a turn; the engine does not reset it each frame, and Compass has no lower-resolution mobile variant. Do not call a reported regression solved solely because pixel dimensions are higher. Test matched body pages, not covers or different books' typography.
- New uploads and Edit & re-format now use 3000px lossless PNG desktop pages and 2000px lossless PNG mobile pages. Compass source tests at pages 10/30 were ~1.28/~1.23 MB per 3000px PNG versus ~854/~833 KB per 2000px JPEG: 2.25× as many source pixels, no JPEG artifacts, approximately 48–49% more bytes for these text samples. This is a deliberate clarity-over-size choice, not a claim that every manuscript grows by the same amount. Existing books retain their pages until deliberately regenerated; book links, embed codes, proportions, typography, and curls stay unchanged. Each output uses fresh asset URLs so cached previous revisions cannot replace new pages.

### Typesetting rules (Word formatter)

- Contents entries show running chapter numbers (1., 2., 3.) independently of the chapter-label checkbox, and bold Part I: / Part II: labels for manuscript-detected parts. Introduction and Conclusion remain unnumbered even when explicitly marked as chapters and never consume a chapter number. Other unnumbered sections remain unnumbered. Existing PDFs and flipbooks adopt this on deliberate re-formatting, not automatically.
- Chapter artwork (shared or individually chosen) applies to numbered chapters plus Introduction and Conclusion (including titles with a colon-separated subtitle). Introduction and Conclusion keep the chapter-style centered opener but no chapter number and no drop cap. Parts and other unnumbered back matter never receive chapter artwork. The image choices and PDF output use the same eligibility rule. Heading styles alone do not create chapters, even in manuscripts with no chapter markers. On first editing a legacy book, re-detect section types rather than restoring obsolete guesses such as a false Chapter 17; preserve titles and all other settings. Subsequent edits retain reviewed section types.
- 6x9in trim (432x648pt), mirrored margins (inside 0.875in, outside ~0.7in), body serif 11/15.4pt, justified. Default: flush-left prose with 7pt space after each paragraph (not between lines), matching the author's existing books. Unchecking the "7 pt space between paragraphs" checkbox switches to 18pt first-line indents with no extra paragraph gap, and no indent after headings. This is a mutually exclusive choice, not two independently stackable styles.
- Chapters open on a right-hand page, sunk ~1.5in, optional image, letter-spaced bold 12pt "CHAPTER N" (no colon) on its own line, a blank line, then the bold 20pt centered title, 3-line drop cap. N is the book's own running count (parts and unnumbered sections skipped); any "Chapter N" text the manuscript left in a title is stripped so it never appears twice.
- Parts get their own right-hand divider page: "PART I" and the part title, both centered, no drop cap, no chapter label. In the contents page, part rows are bold ("PART I: Title").
- Drop caps apply only to numbered chapters (sections marked "Chapter X:"). Appendices, Introduction, Conclusion, parts, and all other unnumbered sections never get a drop cap, regardless of the book-wide option.
- Detection: blank paragraphs are ignored; a lone marker line takes the next short line (even Heading 1) as its title; body sentences that merely start with "Part"/"Chapter" are not markers. Only "Chapter N" lines become numbered chapters; every other heading (back matter, resources, about the author) is an unnumbered section.
- Page numbers centered at the foot from chapter 1; none on openers, blanks, or front matter. No single orphan/widow lines; headings and fully bold paragraphs kept with following prose or the table header plus first body row. Oversized rows may continue across pages beneath their heading.
- Ligatures disabled (text split after "f") so measured and drawn widths always match.
- Word tables retain separate rows, cells, bold/italic text, and paragraph breaks. Original column proportions are adapted to the 319pt text width (never into the gutter), with readable minimum column widths, 10pt type, 13pt leading, 7pt cell padding, fine gray rules, and subtle shading only for detected header rows. Headers repeat across pages; ordinary rows stay together, while a row taller than one page continues safely. Tested against The Founder's Gauntlet's five appendices, including two-column reference grids and single-cell callouts; the manuscript's four-column table uses the same width-safe layout. Tables do not trigger chapter detection or drop caps. Complex vertically merged cells, nested tables, and pictures inside cells are not supported in this version.

## Routes

- `/` — marketing landing page.
- `/auth` — sign in / sign up.
- `/admin` — book list + upload.
- `/admin/:slug` — per-book admin (branding, versions, analytics, embed).
- `/book/:slug` — public flipbook viewer (embed target).
- `/spec` — this specification, downloadable as Markdown.
- `/guide` — user guide, downloadable as PDF and Markdown, linked from the user dashboard menu.

## Non-goals / out of scope (current version)

- Password-protected or email-gated books (planned).
- Server-side PDF rendering for very large books (300+ pages); current pipeline is browser-based.
- Download / print toggles inside the viewer.
- Team accounts and multi-user book ownership.

## Known constraints

- Very large PDFs (300+ pages, heavy images) may render slowly in the browser during upload — acceptable tradeoff for zero server-side rendering cost.
- Flipbook curl realism is excellent but not pixel-identical to Paperturn.