Flipbook Recording

BrowserBox can record a browsing session as a flipbook—a self-contained static site of sequential JPEG frames with a JavaScript viewer. Flipbook recordings are produced directly from the internal screencast pipeline with negligible overhead: when recording is off, the only cost is a single boolean check per frame.

17.1 Quick start #

bbx setup --flipbook-record ~/my-recording \
          --flipbook-description "Onboarding walkthrough"
bbx run
# ... use BrowserBox normally ...
bbx stop

When bbx stop is called, BrowserBox compiles the captured frames into a complete flipbook static site and (if Cloudflare wrangler is available) offers to deploy it to Cloudflare Pages.

17.2 How it works #

1. bbx setup writes BBX_FLIPBOOK_DIR and optionally BBX_FLIPBOOK_DESCRIPTION to .

2. At runtime, each screencast frame is written as a JPEG + JSON metadata pair to a temporary directory inside the BrowserBox config directory ().

3. On bbx stop, the built-in browserbox flipbook-generate command compiles the raw frames into a flipbook static site under the directory provided by --flipbook-record.

When recording is disabled (no --flipbook-record flag), there is zero overhead on the frame pipeline—only a single falsy-value check is evaluated per frame.

17.3 Output structure #

Each recording produces a timestamped directory inside the flipbook base directory:

~/my-recording/
  2026-04-14T02-25-00-000Z--2026-04-14T02-30-00-000Z/
    site/
      index.html          # self-contained viewer
      manifest.json       # flipbook v1 manifest
      pages/
        000000.jpg        # contiguous, zero-padded frames
        000001.jpg
        ...
      assets/
        viewer.css
        viewer.js
        sw.js             # service worker for offline caching
      meta/
        provenance.json   # full per-frame metadata + recording info

Multiple runs with the same --flipbook-record directory produce separate timestamped subdirectories, each a self-contained flipbook site.

17.4 Frame normalization #

Frame IDs from the internal pipeline may contain gaps (due to cast restarts or tab switches). The site generator performs a normalization pass: frames are sorted, paired by basename (JPEG with its JSON metadata), and re-indexed as a contiguous zero-padded sequence (000000, 000001, …). The original frame IDs are preserved in for traceability.

17.5 Cloudflare Pages deployment #

If wrangler (the Cloudflare CLI) is available or can be installed, bbx stop will offer to deploy the generated flipbook site to Cloudflare Pages:

# Install wrangler if not already present
npm install -g wrangler

# Authenticate (one-time)
wrangler login

# Deployment happens automatically on bbx stop

The Pages project name is derived from the flipbook directory basename. If wrangler is not available, the site is still generated locally and can be served with any static file server.

17.6 Relevant environment variables #

17.7 Direct site generation #

The flipbook site generator is available as a standalone command on the BrowserBox binary:

browserbox flipbook-generate <flipbookDir>

This reads raw frames from the config directory, compiles the flipbook site into a timestamped subdirectory of <flipbookDir>, and cleans up the temporary recording data. This is called automatically by bbx stop but can also be invoked manually.