feat(wxread): align pagination, rendering, and docs

2026-05-24 15:36:01 +08:00
parent a318c0e3d0
commit 2a94921e88
103 changed files with 6124 additions and 4623 deletions
@@ -0,0 +1,45 @@
+# Plan 08-03 Summary: Performance Sampling + Cache Integration
+
+## Status: COMPLETE
+
+## What Was Done
+
+### Task 1: Created RDEPUBTextPerformanceSampler.swift
+- **File**: `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPerformanceSampler.swift` (new)
+- `RDEPUBTextPerformanceSample` struct with `chapterHref`, `renderDuration`, `paginateDuration`, `pageCount`, `attributedStringLength`, `cacheHit`
+- `RDEPUBTextPerformanceSampler` class with `record(_:)`, `summary()`, `reset()`, `totalBuildDuration`, `samples`
+- Per-chapter `[PERF]` console logging with millisecond formatting
+
+### Task 2: Instrumented RDEPUBTextBookBuilder with cache + performance
+- **File**: `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` (modified)
+- Added `cache: RDEPUBTextBookCache?` (optional, defaults to nil for backward compat)
+- Added `sampler: RDEPUBTextPerformanceSampler` (always created)
+- Added `lastBuildPerformanceSamples: [RDEPUBTextPerformanceSample]`
+- Added `lastBuildCacheStats: (hits: Int, misses: Int)`
+- `build()` method now:
+  - Checks cache before building (cache HIT returns immediately)
+  - Wraps `renderer.renderChapter()` with `CFAbsoluteTimeGetCurrent()` timing
+  - Wraps `content.rd_paginatedFrames()` with timing
+  - Records per-chapter `RDEPUBTextPerformanceSample`
+  - Saves to cache on miss after successful build
+  - Prints `[PERF]` summary at end
+- Added `makeCacheKey()` helper using `publication.metadata.identifier ?? publication.metadata.title`
+
+### Pre-existing fixes (not in plan scope but required for clean build)
+- **RDEPUBTextBookCache.swift**: Changed 4 `private final class` to `final class` to fix NSCoding "unstable name" errors (Swift compiler change in newer SDK)
+- **RDEPUBSelectionOverlayView.swift**: Fixed empty array literal type annotation and commented-out code
+
+## Files Modified
+| File | Action |
+|------|--------|
+| `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPerformanceSampler.swift` | CREATED |
+| `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` | MODIFIED |
+| `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift` | MODIFIED (pre-existing NSCoding fix) |
+| `Sources/RDReaderView/EPUBUI/RDEPUBSelectionOverlayView.swift` | MODIFIED (pre-existing error fix) |
+
+## Build Verification
+- `xcodebuild build -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 17 Pro'` -- **BUILD SUCCEEDED**
+
+## Key Links Established
+- `RDEPUBTextBookBuilder` -> `RDEPUBTextBookCache` via `cache.load(key:)` / `cache.save(_:key:)`
+- `RDEPUBTextBookBuilder` -> `RDEPUBTextPerformanceSampler` via `sampler.record(sample)`