dowellhz · dowellhz · Aug 14, 2026 · Aug 14, 2026
diff --git a/docs/wiki/architecture.md b/docs/wiki/architecture.md
@@ -19,7 +19,8 @@ AppDelegate
 
 - `AppDelegate*.swift`: app lifecycle, menu, help, update UI.
 - `ReaderWindowController*.swift`: reader shell, document opening, navigation, search, AI integration, vocabulary, sessions.
-- `DocumentLoading*.swift`: EPUB/DOCX archive handling, shared document helpers, and cancellable DOCX streaming preparation. Prepared DOCX output is cached by a content fingerprint, verified before reuse, and published atomically so a stale or interrupted load cannot replace valid content.
+- `DocumentLoading*.swift` and `DOCXPreparedCache.swift`: EPUB/DOCX archive handling, shared document helpers, and cancellable DOCX streaming preparation. DOCX preparation extracts only rendering dependencies; prepared output is cached by a content fingerprint, verified before reuse, bounded by entry and byte quotas, and published atomically so concurrent, stale, or interrupted loads cannot replace valid content.
+- `ReaderContentBackend.swift`: typed PDFKit and WebKit adapters used by shared navigation and zoom commands while preserving renderer-native behavior.
 - `ProcessRunner.swift`: bounded external process execution for archive helpers and other command-line runtimes.
 - `PDFDocumentTextSnapshot.swift`: cancellable PDF text extraction and a verified, content-addressed cache reused by whole-document AI indexing. Background extraction and index construction pause briefly during reader interaction.
 - `AIChatPanel*.swift`: AI chat UI, request lifecycle, bubble layout, selection handling.
@@ -51,6 +52,8 @@ Reader selection and automatic background embedding work do not inspect Keychain
 - `mac-app/ReaderWindowController.swift`
 - `mac-app/ReaderWindowController+UI.swift`
 - `mac-app/DocumentLoading.swift`
+- `mac-app/DOCXPreparedCache.swift`
+- `mac-app/ReaderContentBackend.swift`
 - `mac-app/ProcessRunner.swift`
 - `mac-app/AIChatPanel.swift`
 - `mac-app/SpeechPlaybackCoordinator.swift`

diff --git a/docs/wiki/code-map.md b/docs/wiki/code-map.md
@@ -4,9 +4,9 @@ Generated by `./scripts/generate_code_wiki.sh`.
 
 ## Summary
 
-- Code files: 451
-- Main code lines: 62767
-- Swift app lines: 50849
+- Code files: 456
+- Main code lines: 63495
+- Swift app lines: 51375
 - Full Swift type index: [Type Index](type-index.md)
 
 ## Largest Files
@@ -42,6 +42,7 @@ Generated by `./scripts/generate_code_wiki.sh`.
 - `mac-app/ReaderWindowController+AIRetrieval.swift`
 - `mac-app/ReaderWindowController+AISourceAnnotations.swift`
 - `mac-app/ReaderWindowController+AIState.swift`
+- `mac-app/ReaderWindowController+Backend.swift`
 - `mac-app/ReaderWindowController+ChromeUI.swift`
 - `mac-app/ReaderWindowController+Document.swift`
 - `mac-app/ReaderWindowController+DocumentLoading.swift`

diff --git a/docs/wiki/development-tasks.md b/docs/wiki/development-tasks.md
@@ -8,6 +8,7 @@ Start with:
 
 - `mac-app/PDFReaderView.swift`
 - `mac-app/PDFPagingPolicy.swift`
+- `mac-app/ReaderContentBackend.swift`
 - `mac-app/ReaderWindowController+Navigation.swift`
 
 Run:
@@ -21,6 +22,7 @@ Watch for:
 - Duplicate page turns after one scroll gesture.
 - Losing native PDFKit scroll or rubber-band behavior.
 - Thresholds that work for short pages but fail on long technical books.
+- Bypassing the typed reader backend from shared navigation or zoom commands.
 
 ## Change PDF Text Indexing Or Vocabulary Marks
 
@@ -60,6 +62,7 @@ Start with:
 - `mac-app/DocumentLoading+Archive.swift`
 - `mac-app/DocumentLoading+DOCXStreaming.swift`
 - `mac-app/DocumentLoading+DOCXCache.swift`
+- `mac-app/DOCXPreparedCache.swift`
 - `mac-app/ReaderWindowController+DocumentLoading.swift`
 - `mac-app/Resources/reader-web-text.js`
 - `mac-app/Resources/reader-web-marks.js`
@@ -78,6 +81,8 @@ Watch for:
 - A superseded EPUB or DOCX load mutating the current document or leaving temporary resources behind.
 - Reusing prepared DOCX output after the source bytes change, even when path, size, or timestamp are unchanged.
 - Publishing an incomplete DOCX cache entry after cancellation or extraction failure.
+- Extracting unrelated DOCX package entries or letting prepared cache data exceed its byte quota.
+- Letting concurrent DOCX builders replace a complete cache entry with partial output.
 - Forgetting to invalidate normalized Web text indexes after a DOM text mutation.
 - Relying on CSS Custom Highlight without retaining the DOM-span fallback required by older WebKit versions.
 - Starting PDF table-of-contents, cover, or persisted-mark restoration before the first visible reader update.

diff --git a/docs/wiki/feature-map.md b/docs/wiki/feature-map.md
@@ -14,13 +14,16 @@ Use this page when the task starts from a product feature instead of a file name
 
 - `mac-app/PDFReaderView.swift`: PDFKit view subclass and edge paging events.
 - `mac-app/PDFPagingPolicy.swift`: page turn thresholds and duplicate-turn guard.
+- `mac-app/ReaderContentBackend.swift`: typed PDFKit/WebKit navigation and zoom adapters.
 - `mac-app/ReaderWindowController+Navigation.swift`: page navigation commands.
 
 ## EPUB And DOCX Reading
 
 - `mac-app/DocumentLoading.swift`: shared document model and loader entry point.
 - `mac-app/DocumentLoading+EPUB.swift`: EPUB package, cover, TOC, and resources.
 - `mac-app/DocumentLoading+DOCX.swift`: DOCX paragraph, table, and media rendering.
+- `mac-app/DocumentLoading+DOCXStreaming.swift`: cancellable streaming XML rendering.
+- `mac-app/DocumentLoading+DOCXCache.swift` and `mac-app/DOCXPreparedCache.swift`: selective extraction, verified prepared output, concurrent publication, and bounded cache cleanup.
 - `mac-app/DocumentLoading+HTML.swift`: generated HTML wrapper and rewriting.
 - `mac-app/Resources/reader-web.js`: WebKit reader behavior, selection, and highlights.
 

diff --git a/docs/wiki/type-index.md b/docs/wiki/type-index.md
@@ -107,6 +107,8 @@ Generated by `./scripts/generate_code_wiki.sh`.
 | `mac-app/AppText.swift` | 3 | `struct ChatMessage` |
 | `mac-app/ArchiveSafetyValidator.swift` | 3 | `struct ArchiveSafetyPolicy {` |
 | `mac-app/ArchiveSafetyValidator.swift` | 40 | `enum ArchiveSafetyValidator {` |
+| `mac-app/DOCXPreparedCache.swift` | 46 | `enum DOCXPreparedCache {` |
+| `mac-app/DOCXPreparedCache.swift` | 4 | `struct DOCXPreparedCachePolicy {` |
 | `mac-app/DebouncedTask.swift` | 3 | `final class DebouncedTask {` |
 | `mac-app/DiagnosticsPanelController.swift` | 3 | `final class DiagnosticsPanelController` |
 | `mac-app/DiagnosticsPanelTheme.swift` | 3 | `struct DiagnosticsPanelTheme {` |
@@ -119,20 +121,22 @@ Generated by `./scripts/generate_code_wiki.sh`.
 | `mac-app/DictionaryLookupService.swift` | 8 | `struct VocabularyDictionaryAnswer {` |
 | `mac-app/DocumentContentIdentity.swift` | 4 | `enum DocumentContentIdentity {` |
 | `mac-app/DocumentIdentity.swift` | 4 | `enum DocumentIdentity {` |
+| `mac-app/DocumentLoadMeasurement.swift` | 13 | `struct DocumentLoadMeasurement` |
+| `mac-app/DocumentLoadMeasurement.swift` | 3 | `enum DocumentLoadStage` |
 | `mac-app/DocumentLoading+Archive.swift` | 3 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading+DOCX.swift` | 11 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading+DOCX.swift` | 3 | `struct DOCXParagraph {` |
-| `mac-app/DocumentLoading+DOCXCache.swift` | 236 | `extension WebDocumentLoader {` |
+| `mac-app/DocumentLoading+DOCXCache.swift` | 3 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading+DOCXStreaming.swift` | 3 | `struct DOCXStreamingResult {` |
 | `mac-app/DocumentLoading+DOCXStreaming.swift` | 433 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading+DOCXStreaming.swift` | 9 | `enum DOCXMediaReferenceStyle {` |
 | `mac-app/DocumentLoading+EPUB.swift` | 3 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading+HTML.swift` | 3 | `extension WebDocumentLoader {` |
 | `mac-app/DocumentLoading.swift` | 26 | `struct WebReadableDocument {` |
 | `mac-app/DocumentLoading.swift` | 3 | `final class DocumentLoadCancellationToken {` |
-| `mac-app/DocumentLoading.swift` | 60 | `struct ReaderTOCItem {` |
-| `mac-app/DocumentLoading.swift` | 66 | `struct HTMLBodyFragment {` |
-| `mac-app/DocumentLoading.swift` | 72 | `enum WebDocumentLoader {` |
+| `mac-app/DocumentLoading.swift` | 63 | `struct ReaderTOCItem {` |
+| `mac-app/DocumentLoading.swift` | 69 | `struct HTMLBodyFragment {` |
+| `mac-app/DocumentLoading.swift` | 75 | `enum WebDocumentLoader {` |
 | `mac-app/DocumentOpenPanelConfiguration.swift` | 4 | `enum DocumentOpenPanelConfiguration {` |
 | `mac-app/DocumentQuestionPromptRequest.swift` | 3 | `struct DocumentQuestionPromptRequest {` |
 | `mac-app/ECDICTDictionary.swift` | 16 | `struct ECDICTDiagnosticInfo {` |
@@ -249,6 +253,16 @@ Generated by `./scripts/generate_code_wiki.sh`.
 | `mac-app/ReaderChromeViews.swift` | 3 | `final class FlippedStackView` |
 | `mac-app/ReaderChromeViews.swift` | 426 | `final class PassthroughOverlayView` |
 | `mac-app/ReaderChromeViews.swift` | 7 | `final class GradientButton` |
+| `mac-app/ReaderContentBackend.swift` | 10 | `enum ReaderZoomStep` |
+| `mac-app/ReaderContentBackend.swift` | 139 | `final class WebKitReaderAdapter` |
+| `mac-app/ReaderContentBackend.swift` | 15 | `enum ReaderPageScrollDirection` |
+| `mac-app/ReaderContentBackend.swift` | 20 | `enum ReaderPagePlacement` |
+| `mac-app/ReaderContentBackend.swift` | 25 | `struct ReaderPagedViewportAnchor` |
+| `mac-app/ReaderContentBackend.swift` | 30 | `protocol ReaderContentBackend` |
+| `mac-app/ReaderContentBackend.swift` | 40 | `protocol ReaderPagedBackend` |
+| `mac-app/ReaderContentBackend.swift` | 49 | `protocol ReaderContinuousBackend` |
+| `mac-app/ReaderContentBackend.swift` | 55 | `final class PDFKitReaderAdapter` |
+| `mac-app/ReaderContentBackend.swift` | 5 | `enum ReaderContentBackendKind` |
 | `mac-app/ReaderDocumentImportCoordinator.swift` | 3 | `enum ReaderDocumentImportCoordinator {` |
 | `mac-app/ReaderDocumentKind.swift` | 3 | `enum ReaderDocumentKind {` |
 | `mac-app/ReaderDocumentState.swift` | 4 | `struct ReaderDocumentState {` |
@@ -279,6 +293,7 @@ Generated by `./scripts/generate_code_wiki.sh`.
 | `mac-app/ReaderWindowController+AIRetrieval.swift` | 3 | `extension ReaderWindowController {` |
 | `mac-app/ReaderWindowController+AISourceAnnotations.swift` | 4 | `extension ReaderWindowController {` |
 | `mac-app/ReaderWindowController+AIState.swift` | 3 | `extension ReaderWindowController {` |
+| `mac-app/ReaderWindowController+Backend.swift` | 1 | `extension ReaderWindowController {` |
 | `mac-app/ReaderWindowController+ChromeUI.swift` | 3 | `extension ReaderWindowController {` |
 | `mac-app/ReaderWindowController+Document.swift` | 3 | `extension ReaderWindowController {` |
 | `mac-app/ReaderWindowController+DocumentLoading.swift` | 11 | `extension ReaderWindowController {` |