readest/apps/readest-app/.claude/memory/MEMORY.md

Readest Project Memory

Key Reference Documents

• Bug Fixing Patterns - Common bug categories, root causes, and fix strategies
• CSS & Style Fixes - EPUB CSS override patterns and the style.ts pipeline
• TTS Fixes - Text-to-Speech architecture and bug patterns
• Layout & UI Fixes - Safe insets, z-index, platform-specific UI issues
• Platform Compat Fixes - Android, iOS, Linux, macOS platform-specific bugs
• Annotator & Reader Fixes - Highlight, selection, accessibility bugs

Critical Files (Most Bug-Prone)

• src/utils/style.ts - Central EPUB CSS transformation hub (14+ bug fixes)
• packages/foliate-js/paginator.js - Page layout, image sizing, backgrounds
• src/services/tts/TTSController.ts - TTS state machine, section tracking
• src/hooks/useSafeAreaInsets.ts - Safe area inset management
• src/app/reader/components/FoliateViewer.tsx - Reader view orchestration
• src/app/reader/components/annotator/Annotator.tsx - Annotation lifecycle

Feature Notes

• D-pad Navigation — Android TV remote / keyboard arrow navigation design, key files, and pitfalls
• Cloudflare Workers WebSocket — use fetch() Upgrade pattern (not ws npm); CF delivers binary frames as Blob (must serialize async decodes)

Architecture Notes

• foliate-js is a git submodule at packages/foliate-js/
• Multiview paginator: loads adjacent sections in background, multiple View/Overlayer instances per book
• Style overrides: getLayoutStyles() (always), getColorStyles() (when overriding color)
• transformStylesheet() does regex-based EPUB CSS rewriting at load time
• TTS uses independent section tracking (#ttsSectionIndex) decoupled from view
• Safe area insets flow: Native plugin -> useSafeAreaInsets hook -> component styles
• Dropdown menus use DropdownContext (not blur-based) for screen reader compat

Workflow

• Test file filter — use pnpm test <path> without -- to run a single file
• Always rebase before PR — rebase onto origin/main before creating PRs
• New branch per PR — always create a fresh branch from main for each new PR/issue
• Upgrade gstack locally — always upgrade from the project's .claude/skills/gstack, not global
• No lookbehind regex — never use (?<=) or (?<!) in JS/TS; build check rejects them
• Use worktree — always pnpm worktree:new before PR review, issue fix, or feature work