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

Readest Project Memory

Key Reference Documents (aggregators)

• Bug Patterns · CSS & Style EPUB CSS + style.ts · TTS
• Layout & UI insets/z-index · Platform Compat · Annotator & Reader

Safety & Security

• In-place delete wiped originals never fs.removeFile external · Backup zip Windows paths #4703 normalize \ · download_file scope Android #4639
• Security advisories 2026-06 4 GHSA #4638; SSRF guard broke dev-LAN OPDS, dev-only exemption 2026-07 PR#5002

Paginator & Scroll

• Reading ruler: line-aware frame-offset map; vertical-rl backwards #4865
• Vertical-rl horizontal pagination (#624) — horizontal inputs + two-phase slide; rtl gated !vertical
• Slide/curl turn styles via VT (#555) — VT turns gated on nested-VT-groups support (iOS 18 WebKit crashes despite having the API); Tauri fallback = CapturedPageTurn capture pipeline (WebGL mesh curl + flat canvas slide, full-gridcell capture, instant nav = drop animated); MERGED #4940 (2026-07-05), verified live mac/iOS/Android (mobile = JPEG capped 2x, PNG was 1.5s/turn); Win/Linux capture still open
  • Captured turn ignored instant-highlight hold — captured slide/curl swipe path (app interceptor, no-swipe set) didn't honor renderer.scrollLocked; fix = foliate get scrollLocked() + gate useCapturedTurn move on it (push/VT-slide already gated); PR#5000 + foliate#51
• TOC: expand + auto-scroll; current-position row; table heading clip #4439; BooknoteView auto-scroll #4352
• Paginated bg: swipe flash; texture occlusion #4399; gutter bleed #4394; bg-replace reflow #4785
• Inline-block column overflow #demoteUnfragmentableBoxes
• FXL/PDF: fit-width scroll reset #4683; PDF spread seam #4587; spine seam #4857; portrait auto-spread off-center #4984 MERGED PR#4992+foliate#50 lone page kept one-sided auto margin -> stranded + taps turned page; computeSpreadInlineMargins
• Scrolled: PDF wheel double #4727; header title center #4436; Duokan fullscreen cover

Critical Files (Most Bug-Prone)

• src/utils/style.ts EPUB CSS hub · packages/foliate-js/paginator.js · src/services/tts/TTSController.ts
• src/hooks/useSafeAreaInsets.ts · src/app/reader/components/FoliateViewer.tsx · .../annotator/Annotator.tsx

Sync Notes

• Cloud Sync provider selection #4959/#4380 MERGED #4971+#4973+#4975+#4976: derived provider, exclusive routing, syncBooks auto-enable, fleet probe, chooser; i18n pass + live verify pending
• Grimmory native sync Booklore-fork REVERTED
• KOSync: CFI spine resolution; connect() false-positive #4692
• Empty-start CFI sync · Custom fonts vanish #4410 CRDT remove-wins
• koplugin: note deletion tombstone; stats #4666; bulk download #4751; dup book rows #4861
• Statusless re-pin #4677 · pull cursor synced_at #4678
• koplugin library stale #4934 pull cursor updated_at→synced_at + split push watermark + v2→v3 heal migration
• WebDAV: metadata #4756 LWW; group membership #4942 mergeBookMetadata dropped groupId/groupName; credentials #4810; connect nullified #4780 stale closure
• WebDAV deletion + upload-after-enable (#4860/#4856) edit-wins LWW + tombstone union
• File sync: refactor #4784 FileSyncEngine; third-party auto-sync #4835
• Transfer Queue clear not persisted hook mutated store directly, skipped persistQueue(); route clears through transferManager
• Multi-window settings clobber (#4580)
• Google Drive: research; multi-PR status; full walk every sync no-source books never recorded in uploadedHashes + focus refires pullLibrary
• S3/R2 provider third backend, aws4fetch SigV4 path-style, full slice on dev uncommitted; live R2 verify pending
• Hardcover edition_id (#4792)

Build, Testing & CI

• Nightly quick-sharun hang #4906 pin via cache pre-seed + step timeouts
• format:check separate gate · Worktree rebase submodule drift
• Android CDP: e2e lane pnpm test:android; WebView profiling; double-tap gesture
• Tauri Rust↔JS parser parity
• TTS tests: browser e2e harness; paragraph+RSVP sync #3235 TTS-is-clock
• fastlane App Store APPLE_API_KEY_PATH out of build env
• Turbopack cache OOM (#4619)
• Deps override workflow pnpm-workspace.yaml
• Xcode 26.2 broke iOS builds (swift-rs) — phantom Bundle.main/privacy: errors; vendored packages/swift-rs --triple/--sdk; Package.swift platforms floor now enforced
• pdfjs vendor wasm copy wasm/*
• CI/PR delivery + push keepalive

Platform Compat

• Android: hyphen selection #1553; NativeFile vs RemoteFile I/O
• Window-state sanitizer #4398 · Android themed icon #4733
• Open-with intent #4521 · dict lookup hijack #4559
• Large-PDF OOM range flood (#3470) MAX_CONCURRENT_RANGES=6
• Black screen external cache (#4853) FIXED PR#4889; drop $CACHE grants
• macOS 26 Tahoe close→black window (#4875) minimize() not hide()
• Linux app invisible after backup (#3682) FIXED PR#4904 opaque window
• Apple OAuth expired + deeplink swallowed (#4881)
• Annotation link ignored when reader open #4887 open-book-in-reader event
• iOS auto-brightness locks (#4885) brightness GLOBAL; release on bg
• iOS share .txt stuck #4917 drop SupportsText in project.yml (xcodegen src)
• Updater disable non-AppImage (#4874)
• Fullscreen no-op Phosh (#4034) drop isMaximized branch

Reader Features & UI

• Android Auto TTS #3919/PR#4907 MERGED; CarPlay blocked on entitlement
• Widgets: mobile reading #1602/PR#4842; iOS App Group stripped PR#4891; cover bright right-edge line fractional resize → round target to whole px
• PDF: scrolled lag #4795; scrolled pinch-zoom #4817; pinch vs two-finger scroll #4858; text selection misplaced w/ OS font scale #4480 OS font-scale inflates text-layer glyph size not positions; divide --text-scale-factor (font-size lever) by detected scale, NOT --total-scale-factor
• Search modes #4560
• OPDS groups carousel #4750 · WebDAV browser sort+search #4724
• Image zoom trackpad flicker (#4742) macOS pinch=ctrl+wheel
• Instant highlight: ate tap/swipe; delete orphan #4773; empty leak #4791
• Selection: keyboard adjust #4728; cross-page auto-turn #4741
• Click/tap: double-click word select; dblclick-drag #4524; tap open image/table #4600
• Annotator onLoad listener leak (#4735)
• Paragraph mode: toggle/resume #4717; accidental exit #4474
• #4584 tap-death UNFIXED; likely WebView-148
• PDF/CBZ Contrast view-menu ONE filter:
• Header/footer over light PDF in dark (#4901) mix-blend-difference, FIXED light anchor
• iOS instant-dict double popup once-per-gesture latch
• Dict: popup font size #4443; lemmatization #4574; popup speak button #4876 standalone wordPronouncer, Edge-direct + dedicated WebAudio ctx
• Word Lens: inline gloss CFI-safe ruby; en-en
• Stripe highest-active plan (#4694)
• Save image to gallery (#4680) MediaStore
• Webtoon Mode (#3647)
• Middle-click autoscroll #4951 Autoscroller RAF core; containerPosition +=; armed-books preventDefault
• Auto Scroll teleprompter #4998 MERGED PR#4999 PacedScroller + useAutoScroll + gridcell-centered pill; scrolled-only; tap=pause via iframe-single-click consume
• Biometric app-lock #4645 · Reference Pages #4542 · e-ink refresh page-turner #4687
• Share intent + toolbar (#4014)
• Customize Toolbar: global serializeConfig #4760; e-ink black bar #4839
• Edge TTS Web Audio engine (#3851) gapless WebAudioPlayer + WSOLA
• Background TTS sessions PR#4941 — hash-keyed session manager, detach/attach, NowPlayingBar; header X routes onCloseBook NOT onGoToLibrary
• TTS player redesign mini-player + Dialog sheet replaces icon/popup/TTSBar; MERGED #4996; open: isPlaying glyph desync at section transitions
• Android bg TTS media session fix — #4941/#4931 regression: startService() dies backgrounded → in-process instance calls; always request POST_NOTIFICATIONS; + lock-screen duration scrubber + onSeekTo (Edge-only)
• Native TTS: iOS #4676 pause==stop; offline halt #4613
• Edge TTS: word highlight #4017; drift
• TTS UX: highlight granularity; start-from-selection; reuse session
• RSVP: control-bar REVERT; font #4519; RTL word #4630
• Overlay z-index scale RSVP 100 → app-lock
• Global annotation page-turn lag (#4575)
• Overlayer splitRange text nodes
• Android image callout freeze .no-context-menu ANCESTOR
• Inline-img vertical-align (#4866) gated on computed valign
• Table dark-mode tint #4419 · footnote aside border #4438
• Proofread: enhancements #4700; per-book CRDT #4781; edit Find + toggle #4859
• Russian NBSP (#4769)
• OPDS: Firefox strict-XML #4479; JSON search #4502; HTML desc #4503; self-link #4749; popular dedup #4782; auto-download subdir crawl #4272 bounded BFS, never crawl newest-feed catalogs; preemptive Basic 400s digest Calibre bare-retry on 400 PR#5002; auto-download TLS #4988 skipSslVerification parity PR#5002
• D-pad Navigation
• koplugin cover upload (#4374)
• koplugin Library slow open #4954 group mosaics recomposed every paint; PR#4974 availability-keyed cache + async compose + cache nil result
• Calibre plugin push #4863 OAuth localhost relay
• Calibre custom columns #4811 metadata.calibreColumns

Library Fixes

• Book action platform surfaces · menu append race #4389
• TXT: author recognition #4390; chapter measure-word FP #4658
• Cover stale (in-place mutation)
• Series/author back no-op (#4437)
• Library/reader separate texture #4743 · list view series overflow #4796
• Recently-read shelf (#3797)
• Auto-import watched folders (#3889) per-folder opt-in

Architecture & Patterns

• foliate-js submodule at packages/foliate-js/; multiview paginator preloads adjacent sections
• Turso "concurrent use forbidden" op_lock async mutex
• Markdown: .md support #774; resume position #4862
• Style: getLayoutStyles() always, getColorStyles() when overriding; transformStylesheet() rewrites EPUB CSS
• TTS #ttsSectionIndex; insets: native plugin → useSafeAreaInsets → styles; Dropdowns DropdownContext
• Stale settings closure: persist useSettingsStore.getState().settings (#4780)
• Page margins not live #4898 in-place mutation froze memo
• Foliate touch-listener capture phase
• iframe cross-realm instanceof duck-type 'closest'
• Virtuoso + OverlayScrollbars
• Design system → DESIGN.md never pl/pr/ml/mr (RTL)

Workflow & Feedback

• Commit messages English-only no CJK, no em/en dashes
• PR flow: rebase onto origin/main; fresh branch per PR; always pnpm worktree:new; commit locally, don't push until confirmed
• Test file filter pnpm test <path> no --
• No test seams in prod · no lookbehind regex
• i18n: en plurals manual; i18n:extract prunes keys
• Dependabot transitive fixes pnpm-workspace.yaml overrides:
• Upgrade gstack locally