Kindle Preview Review

Preview the book's EPUB in Kindle Previewer 3, capture screenshots of how it renders on different Kindle devices, and analyze with Gemini's vision API.

Prerequisites

Kindle Previewer 3 must be installed manually (requires sudo):

# Option 1: Homebrew (requires sudo password prompt)
brew install --cask kindle-previewer

# Option 2: Direct download from Amazon
# https://www.amazon.com/Kindle-Previewer/b?ie=UTF8&node=21381691011

Other requirements:

• •GEMINI_API_KEY in .env file
• •@google/genai npm package installed
• •macOS (uses AppleScript for automation)

Quick Start

# Full review (all devices, 10 pages each)
source .env && GEMINI_API_KEY=$GEMINI_API_KEY npx tsx scripts/kindle-preview.ts

# Specific EPUB file
source .env && GEMINI_API_KEY=$GEMINI_API_KEY npx tsx scripts/kindle-preview.ts \
  --epub output/the-meta-engineer.epub

# Single device
source .env && GEMINI_API_KEY=$GEMINI_API_KEY npx tsx scripts/kindle-preview.ts \
  --device "Kindle Paperwhite 5"

# More pages
source .env && GEMINI_API_KEY=$GEMINI_API_KEY npx tsx scripts/kindle-preview.ts \
  --pages 20

# Screenshots only (no Gemini)
npx tsx scripts/kindle-preview.ts --screenshots-only

Supported Devices

The script tests on these Kindle devices/apps:

Workflow

1. •

   Open in Kindle Previewer:

   • •Launches Kindle Previewer 3 via AppleScript
   • •Opens the EPUB file
   • •Waits for rendering to complete
2. •

   Capture Screenshots:

   • •Uses macOS screencapture to capture the preview window
   • •Navigates through pages using keyboard simulation
   • •Saves PNGs to .kindle-review/screenshots/<device>/
3. •

   Gemini Analysis:

   • •Sends screenshots to gemini-2.5-flash vision model
   • •Analyzes Kindle-specific rendering issues:
     • •Code block readability on e-ink
     • •Font sizing and typography
     • •Table rendering on small screens
     • •Image clarity and sizing
     • •Page breaks and navigation
   • •Saves report to .kindle-review-report.md
4. •

   Create Tasks (manual step after review):

   • •Read .kindle-review-report.md
   • •For critical Kindle issues, create tasks in tasks.json
   • •Priority: issues affecting e-ink readability = high

Output Files

All output files are gitignored.

Common Kindle Issues

After reviewing the report, common fixes include:

E-ink Readability

• •Increase code block font size
• •Ensure sufficient contrast
• •Avoid color-dependent information

Code Blocks

• •May need wider margins on Paperwhite
• •Consider shorter line lengths for better wrapping
• •Test syntax highlighting visibility on e-ink

Tables

• •Wide tables may need horizontal scrolling
• •Consider responsive table CSS
• •Test column alignment on narrow screens

Images

• •Verify diagrams are readable on e-ink
• •Check image sizing on different devices
• •Ensure alt text is meaningful

Differences from epub-review

Troubleshooting

"Kindle Previewer 3 not installed"

Install with Homebrew (requires sudo):

brew install --cask kindle-previewer

AppleScript Accessibility

Grant Terminal/Claude Code accessibility permissions in: System Settings > Privacy & Security > Accessibility

Screenshots Not Capturing

Ensure Kindle Previewer window is visible and not minimized.

EPUB Not Found

Build the EPUB first:

./scripts/build-asciidoc.sh --epub