Repo Conventions

Repo Conventions

Subsystem conventions and invariants for KMReader. AGENTS.md holds repo-wide rules; this file holds the per-subsystem boundaries. Record boundaries, ownership, invariants, and explicit design rules; leave styling values (font sizes, point paddings, scale and opacity numbers) to LayoutConfig and the views, since they drift with design tweaks. When a change alters one of these boundaries, update this file in the same change (AGENTS.md rule 18).

Reader State Boundaries

Reader Settings vs Session

• ReaderSettingsSheet is for persisted preferences only. Session-only options (e.g. page rotation) belong in the reader controls menu / platform command menu. Rotation is session-only, paged DIVINA modes only, never Webtoon.

Position & Navigation

• ReaderViewModel owns the committed semantic position as a full ReaderViewItem plus its focused ReaderPageID.
• navigationTarget is reserved for explicit navigation commands; rebuilds restore from the committed position and adapter snapshots, never synthesize commands, and a later interactive commit supersedes any restoration anchor. When a command already resolves to the current position, clear navigationTarget synchronously before committing (committing first loops).
• Seamless cross-book navigation: the committed ReaderPositionAnchor is the source of truth; .end items retain their segment's final ReaderPageID; currentBook/ReaderSession.book follow the segment; currentBookId remains the whole-book load anchor.
• Split wide pages keep their committed side across layout rebuilds; propagate it via ReaderPositionAnchor.preferredSplitPart and ReaderViewItem.preferredSplitPart(preserving:) whenever adapters construct a new anchor.

Whole Spreads

• Whole-spread panning is opt-in: it applies only when Split Wide Pages is set to Scroll (ReaderViewModel.keepsSplitSpreadsWhole); every other mode pages through .first/.second halves, as macOS and tvOS always do. With Scroll on iOS, single-page presentation keeps a split wide page whole: generateViewItems emits one .split(id, .both), the same item dual presentation uses, and single-page engines render it uncut at the scale a single page gets (WholeSpreadLayout), panning across it at base zoom through SpreadPanningScrollView. Engines build WholeSpreadPresentation via ReaderViewModel.wholeSpreadPresentation(for:isDualPagePresentation:…) from their own mode, never the view model's dual flag.
• A whole spread has two stops, its start and end edges in reading order (ReaderSpreadEdge, mapped onto .first/.second). Paged steps (taps, keys, remote) go through ReaderViewModel.requestPagedStep(offset:): a step first pans to the edge it leaves through, as a navigation target on the same item that names that edge, and stepping back onto a spread lands on its end edge. Steps chain from an in-flight target. While the reader is zoomed, steps skip the stops and turn the page, as for any zoomed page. Engines apply a same-item target's edge to the current page host, clearing the target like any command that resolves to the current position.
• Swipes pan freely and never turn the page mid-gesture: the host's scroll view begins for a touch that catches the spread mid-glide (UIKit begins that pan at touch-down, before it has a direction) and otherwise only for horizontal drags it can still follow, and each engine's page-turn gesture (collection view pan, cover pan, curl pan) refuses drags the current spread can still follow. A turn needs a new drag from the far edge. Both sides judge a drag with UIPanGestureRecognizer.horizontalDrag(in:), so each drag goes to exactly one of them. A touch while the spread bounces back from past an edge is not caught: the touch ends the bounce and the drag is judged by its direction, so a swipe on past the edge still turns the page. Each engine's tap zone waits for the page host's scroll pan to fail (SpreadPanningScrollView.isPagePan), so a tap that catches a gliding page only stops it.
• Both page hosts (NativePagedPageContentView, NativeImagePageViewController) keep their zoom scroll view in a PageScrollController, which owns the content wiring, the spread's width, placement, panning, and resting edge; hosts supply only the displayed image size, whether they show the committed page, and what to do on zoom. A spread keeps its resting edge in reading order across item, viewport, and content-size changes, and a flipped start side moves it to where that edge now is.
• The shared controller reports the edges the spread rests at (recordWholeSpreadPosition(pageID:restingEdges:)) whenever it places the spread, a pan settles, or the host starts showing the committed item, but only while the host shows the committed page; a single resting edge becomes the committed split side, so rebuilds reopen the spread there. While a finger moves the spread or it glides, the controller reports no resting edge, so a step taken meanwhile pans to the edge it leaves through, and a pan that would stop just short of an edge settles on it (spreadRestingOffset(forTarget:)). A host starting to show a spread opens it at wholeSpreadArrivalEdge(for:relativeTo:): an explicit target's edge, the committed side for the current item, the end edge for the item right before the current one, else the start edge.

Page Image Preparation

• ReaderPageLoadScheduler decodes page bitmaps under a short-edge budget: screen width in pixels × a fixed zoom headroom (pageDecodeZoomHeadroom, 2), via ImageIO in loadImageFromFile. Pages within budget decode at full resolution; larger ones downsample uniformly, staying sharp through a 2× zoom. The short edge is the binding axis so the same decode stays valid for paged fit-screen, webtoon fit-width, split halves, and 90° rotation, and aspect preservation keeps webtoonPixelSize layout and the rotate → border-crop → split preparation unchanged. The budget applies to whatever file the pipeline resolves, including cached upscaled @2x pages (auto mode only fires on pages smaller than the screen, so a fresh upscale always lands inside the budget). Originals on disk are never rewritten, and Share actions export original pixels via ReaderViewModel.originalPageImage, which reloads from the resolved source file and bypasses the preloaded bitmap. Animated-page posters decode at full size — the inline player streams frames from the source file anyway.
• NativePageItem prepares a displayed page in one fixed order: rotate, border-crop the whole page, then split into halves. Border cropping never runs on an individual split half — the halves of a wide page must share the whole page's crop rect so a rejoined spread (fillEqually slots, one per half) stays seamless.

Page Curl & Cover Adapters

• Page Curl adapters must not publish a position while mounting or dismantling.
• Page Curl indices are local to one coordinator-owned immutable snapshot; cross update/preload/rotation/teardown boundaries by stable reader-item identity, never array indices or view tags.
• Programmatic turns keep their setViewControllers completion authoritative; willTransitionTo must not invalidate the in-flight transition token. Programmatic setViewControllers must never land while a pan gesture is active (willTransitionTo only fires once a curl starts); coordinators gate on the pan recognizers' live state and stash work until the pan ends, like isTransitioning.
• Cover adapters (NativeCoverPageView) never finalize a page-turn transition across an item-list rebuild; teardown() invalidates in-flight tokens, and a viewport size change cancels an in-flight drag.
• EPUB paged modes (iOS WebPubPagedCurlView/WebPubPagedCoverView) run one live EpubPageViewController web view per chapter plus preloaded boundary neighbors (≤3 web views), never one per page; in-chapter turns are JS scrolls on the live view. In curl, UIPageViewController slots are dumb shells (CurlPageShellViewController): a chapter-internal flip covers the front shell with a snapshot of the current page and migrates the web view's view into a pre-sized target shell (a zero-size pass would trigger a throwaway re-pagination), so the reveal and the committed page are the same live view; a cross-chapter flip keeps the live leaf and reveals the preloaded neighbor. Interactive turns commit or restore in didFinishAnimating, programmatic turns in their own setViewControllers completion, and the internal pan recognizers carry a target that discards dataSource prefetches which never became a curl (handleInternalPanState).
• A curl flip's backside mirrors the current page when moving forward and the target page when moving backward (so the curl lands seamlessly on the revealed destination). The target page's pixels are resolved in order: a small LRU cache of half-scale images captured as each page becomes the committed page (scheduleBacksideImageCapture, the only synchronous source for a neighbor that has not finished loading; the chapter-page-keyed cache is dropped whenever pagination re-runs on changed geometry, via onRepagination), then a live capture of the settled view (makeBacksideSnapshotImage — renders through the render server with a forced commit, since a covered web view's latest scroll is not composited yet), then the mirrored current page as the transient fallback, which is swapped to the target page once it renders (updateMirroredSnapshot): an in-chapter backward flip captures the live view once its scroll settles, a cross-chapter backward flip captures the neighbor once its pagination becomes ready (onPaginationReady).
• Chapter identity for reload decisions is the resource-scheme URL: the web view loads kmreader-resource:// URLs via loadEPUBDocument, so loadContentIfNeeded must compare webView.url against EpubResourceScheme.url(for:rootURL:), never the raw chapter file URL (which never matches and would force a full reload on every ensure call).

EPUB Pagination Settling

• Chapter pagination (the shared WebPubPagedJavaScriptBuilder.makePaginationScript behind every paged engine, and the scrolled views' inline scripts) must not finalize a target whose offset depends on the full content extent — a last-page jump (preferLast/jumpToLastPage) or any target past page 0 — while images are still in flight: the layout check waits for document.images to complete (forcing loading=lazy images eager), bounded by the layout-check attempt cap. The guard and its cap live in one shared fragment (WebPubPagedJavaScriptBuilder.fullExtentGuardScript) interpolated by all three scripts. Finalizing early measures a short document, and the content growth that follows silently strands the position mid-chapter. Page-0 targets finalize without the image wait since their offset does not depend on content size.

Scroll Engine

• ScrollReaderEngine restores anchors strictly by page identity across item-list rebuilds, carrying the pending position as a full ReaderPositionAnchor (never a bare ReaderViewItem). Unresolvable anchors are discarded (nil), never positionally substituted.

Page Load Failure State

• DIVINA page image load failures are recorded in ReaderPageLoadScheduler as a typed ReaderPageLoadFailure per page (cancellation never counts as failure), cleared on success and surfaced through the page-presentation invalidation channel; NativePageData.failure (paged/scroll/curl) and the Webtoon cell error state render failure.title / failure.detail with a retry button. Retry goes through ReaderViewModel.retryImageLoad(for:) — never re-enter the load pipeline from view code directly.
• The failure value comes from the load pipeline itself: a server/HTTP status from the remote page fetch, a network error description, a local read failure from archive materialization (OfflineManager.getOfflinePageImageURL throws; the try? callers treat it as plain absence), or offline unavailability. View code never invents its own reason text.

Book-Level Unavailable State

• Book-level reader failures (deleted or unsupported media, missing offline file, load error, no pages, no content) all render through the shared ReaderUnavailableView: icon, title, optional message, an optional prominent Retry, and Close. Engines never hand-draw their own error layout or hardcode reader-context colors — the view's adaptive colors already handle the dark reader context.

Next-Book Offline State

• In offline-first reading, ReaderViewModel.nextBookOfflineState is the single observable for the next book's offline readiness, rendered by end-page/footer UIs.
• The status row is a permanently reserved constant-height slot toggled by alpha — never isHidden, which would re-lay out the page; in streaming mode the slot collapses entirely.
• Adapters refresh end content only via the page-presentation invalidation channel. The next-segment preload trigger distance must stay ahead of the download, not just the page turn.

End-Page Remaining Unread

• ReaderViewModel.remainingUnreadCount(forSegmentBookId:) backs the end page's remaining-unread line with the series unread count from the local projection. It refreshes when a segment loads and again after a completing progress snapshot settles (the projection only moves then), publishing through the page-presentation invalidation channel like nextBookOfflineState.
• The line renders only in a series context — hidden in a read-list context, where the page reports list order, not series membership — and only while the count is positive.

Next Book Suggestions

• With "Suggest Next Unread Book" on (suggestNextUnreadBook, on by default), the next book skips books already read, like the dashboard: the first later book in series order (or the read list's order in a read-list context) that isn't read, else the plain next book, so re-reading still moves forward. With it off, the plain next book. The previous book always stays plain order. This covers the reader's next book (end page, next segment and its preload) and the series continue-reading target after the last read book.
• Online, NextBookToReadResolver makes the single /next request with skipRead=true (servers that support it skip read books themselves); when the returned book is read (servers that ignore the parameter, such as Komga), the local projection supplies the first unread book after the current one, never adding a request. Offline, and for the local continue-reading target, the same rule runs on the local projection (Collection.nextToRead(after:isRead:)). An appended next segment records the book it follows as its previous book, so a skipped book never lands between two segments.

Read List Continuation

• Read list continuation is opt-in (readListContinuationEnabled, default off): ReaderPresentationManager.present resolves a nil read list context through ReadListReadingService.ownerContext(forBookId:), so a book owned by a read list the user is reading continues in read-list order from any entry point; an explicit context (opened from that read list) always wins and works regardless of the setting.
• Every non-incognito session with a context records the entry point while the setting is on, including seamless cross-book moves (updatePresentedBook records only when the book id changes, not on refreshes of the same book).

Tap Zones, Chrome & Boundary Feedback

• Single-tap zone actions globally wait out the double-tap zoom window via a static singleTap.require(toFail: doubleTap) in every engine; with zoom disabled the recognizer auto-fails, so taps stay immediate. Do not make arbitration zone-dependent — page-turn zones must still honor double-tap zoom, which works anywhere on the page.
• Drag gestures win over single taps: tap recognizers require the engine's pan/scroll recognizer to fail, so a recognized drag cannot fall through as a tap after the gesture ends. PDF uses its explicit movement/duration validation for the same invariant.
• Chrome visibility animates split: opacity on a quick curve (appCurve), bar slide on appSpring; tvOS keeps conditional insertion so the focus engine never sees hidden chrome, and the always-on mini progress bar keeps its conditional matched-geometry morph. The readability scrim extends past the bars with hit-testing disabled there, and stays gated on showGradientBackground.
• A denied first/last-page turn (no adjacent book) answers with a two-phase nudge along the attempted direction plus HapticFeedback.light() (tap path performBoundaryNudge, cover rubber-band path, scroll flick path); a successful cross-book turn fires the same light haptic. Haptics fire only on discrete boundary crossings, never on continuous motion.
• Paged DIVINA modes show PageFilmstripView above the bottom bar's page button while controls are visible (never tvOS, webtoon, or the always-on mini bar). It follows the committed page index — engines expose no per-frame turn progress — is not independently scrollable, jumps on tap, and scrubs pages on drag with selectionChanged() per crossed page. Drag tracking is immediate: the strip's offset and its per-page re-centering bypass implicit animation (offset sits outside the .animation(value:) scope, re-centering runs in a nil-animation transaction, and the bottom bar's page/progress animations are scoped to the page button and progress bar, never the filmstrip) so the strip never glides behind the finger; only the lens width/opacity animate. Per-page re-centering uses the base item advance, so a crossing can overshoot the finger by a few points while the lens is expanded. The lens grows in both dimensions with its width derived from the page's own aspect (BookPage.width/height, 2:3 fallback when missing), so the full page stays visible; only ultra-wide pages center-crop at the lens cap.

Sync, Offline & Caching

SSE

• SSE callbacks are single-assignment closures; implement dispatchers when multiple components need the same event.

Read Progress

• Read progress has a per-session recording threshold (progressRecordingThreshold, default 3, 0 = record immediately): for a book that was unread or finished when the session reached it, page-change submissions and the close/background flush are withheld until the position moves at least that many pages from the session's first page, unless the page completes the book. A book already in progress records any page turn, and once a book records in a session it keeps recording; opening a book without turning a page never records.
• All three engines apply the policy through one ReaderProgressRecordingGate per book and measure the distance from the session start themselves (DIVINA per book id, PDF by page number, EPUB from the start chapter and page, with both ends recomputed from the current chapter page counts), so an accidental reader open never creates progress or resets a finished book.
• The session start is the page the reader settles on, never a provisional one: the PDF document view reports no page change while it is moving to its start page or a jump target (PDFKit shows the first page meanwhile), and the EPUB reader restarts its start once the saved position is applied to a freshly measured chapter.
• Any path that pulls reading progress after coming online must first await ProgressSyncService.syncPendingProgress (it waits for an in-flight push), so a pull never overwrites newer offline-queued local progress.

Downloads & Caches

• Cancelling a download removes its on-disk book directory; failed downloads keep partial content for resume.
• Series/read-list download rollups (SeriesDownloadStatus) fold per-book states into one aggregate: any pending book makes it pending; with nothing in flight, any failed book surfaces as failed (red status icon, like the book-level failure state); otherwise downloaded / partially downloaded / not downloaded. Full recounts (syncSeriesDownloadStatus, applyReadListDownloadSummary) own the rollup including failures; the delta fast paths (applySeriesDownloadDelta/applyReadListDownloadDelta) adjust only downloaded/pending counts and defer to a full recount whenever a failed state is involved or the aggregate currently is failed.
• Only download/extraction write paths create the on-disk book or instance directory (bookDirectory/offlineDirectory); read-only lookups go through the non-creating bookDirectoryURL/offlineDirectoryURL/webPubRootDirectoryURL so opening a book never leaves an empty shell behind.
• OfflineManager.cleanupOrphanedFiles sweeps every instance namespace under OfflineBooks/, skipping in-flight downloads of the current instance: directories of books with no download intent (notDownloaded or no local row) are deleted; pending/failed books keep directories that hold files (resume on retry) and lose empty shells; downloaded books whose directory holds no files are deleted and reset to .notDownloaded; empty instance directories are pruned at the end. It runs once at launch after the database opens, after stale-book reconcile during full sync, and from the Offline page's manual action.
• Clearing caches or server data goes through CacheManager and the GRDB stores only.
• ThumbnailCache is the multi-level cover cache (memory → disk → network): image consumers call ThumbnailCache.shared.image(id:type:page:) and get a decoded image without juggling tiers; view initializers seed synchronously from the memory tier via ThumbnailCache.cachedImage(id:type:), so cells recreated by lazy grids/lists never re-read disk or flash the loading placeholder. Cover loads join one in-flight task per key, so a cell recreated while its first load is still running shares the download and decode, and a cancelled cell load still lands its result in the memory tier. A force refresh or cache clear drops the in-flight registration, so a stale decode can never be written back over fresh state. The memory tier (ThumbnailMemoryCache, NSCache, per-instance keys, honoring the cover-cache expiration) is its private concern and holds covers only — page thumbnails skip it, since jump sheets stream them by the hundreds and would churn the cover cache out. A successful force download evicts the key centrally, and the cache-clear paths empty it. Cover refreshes must go through ThumbnailCache.refreshThumbnail (it posts .thumbnailDidRefresh), never a bare ensureThumbnail(force:). File-level consumers (widgets, Spotlight indexing, tint extraction) still use ensureThumbnail.
• Queueing a download backfills the book's KomgaSeries row from the server when missing (OfflineManager.ensureSeriesRow, with a startDownload backstop): single-book download entries don't guarantee the series row, and Offline series browse plus series download rollups query the series table.
• Deleting downloads is staged behind an undo toast, on every entry path: the Offline pages (downloaded-book swipe, group Delete All, Remove All/Read, task-row cancel), series/read-list detail download sections and context menus (removeSeriesOfflineWithUndo/removeReadListOfflineWithUndo), and single-book download toggles (toggleDownload → deleteBookWithUndo for downloaded books, cancelDownloadWithUndo for pending ones; toggling a staged book cancels its pending deletion instead). OfflineManager holds PendingDownloadDeletion records and the Offline pages filter staged books out of their snapshots, so rows vanish immediately while data stays intact. The commit fires when the toast settles (timeout, replacement, swipe-away) and deletes exactly the books captured at staging — anything downloaded during the undo window survives; Undo runs the toast's cancel closure, which just drops the record (the books were never touched), and an explicit (re)download of a staged book cancels its pending deletion the same way. Background flows (auto-delete read books, sync cleanup) never stage.

Local Database

• Runtime GRDB migrations in LocalDatabase are immutable once committed: never mutate an already-registered migration (e.g. create_runtime_schema_v1, 00002_add_protected_server_flag) or its helpers; they are the frozen baseline. Any table shape change is a new numbered migration after the latest one; fresh installs run baseline + all later migrations in order.
• New persisted field: update the record model and CodingKeys, then add a migration backfilling a safe default. Validate both upgrade and fresh-install paths.

Read List Reading State

• Read list reading state (read_list_reading_states) is user state, kept apart from the KomgaReadList server mirror.
• It syncs through Komga's per-user client settings, one key per read list (kmreader.readlist.<lowercased id>; keys must match Komga's lowercase namespace pattern), piggybacking on the reading-progress catch-up. Requires Komga 1.20.0+, the app's minimum server version.
• Reconcile pulls first and keeps, per read list, whichever change happened last on any device — a read or a stop (a stop records its time on its isStopped tombstone) — then pushes the local changes that won, so neither a pull nor an offline stop discards a newer change.
• Remote states are applied and pending changes pushed only while the sync's instance is still current; a server switch mid-sync drops the round.
• Only ordered read lists count as being read, including for Stop Reading, whatever another device synced.
• The local snapshot loads with each instance in ContentView's per-instance startup task, independent of the network catch-up (which is offline-gated and debounced), so continuation works on offline launches and with On Deck hidden.
• While the setting is off, ReadListReadingService records, syncs, and resolves nothing and publishes an empty snapshot (no local reads or writes, no client-settings requests).

Reading Stats

• Reading stats prefer the server's /api/v1/stats/reading/* endpoints (kmrs 0.17.0+; absent on Komga) and fall back to local GRDB aggregation. The first fetch of the three endpoints doubles as the capability probe: a 404 from any of them records the instance as unsupported and the same load is then served locally. Per-instance verdicts live in AppConfig.serverReadingStatsCapability (UserDefaults); an unsupported verdict expires after 24h so a server upgrade is picked up automatically, and offline mode never probes. The fetch result carries its ReadingStatsDataSource, persisted on the cached snapshot, so the view can hide local-sync hints whenever the data came from the server.

Smart Lists

• Smart lists (/api/v1/smart-lists/*) are kmrs-private saved searches evaluated live server-side, absent on Komga (the whole API 404s). Support is probed per instance: the first SmartListsViewModel load doubles as the probe, a 404 records ServerSmartListCapability in AppConfig.serverSmartListCapability for 24h (the same verdict pattern as komf/reading stats), and a marked-unsupported instance skips the doomed request.
• Smart lists are DTO-driven and online-only: the lists themselves are NOT mirrored into GRDB (no tables, no pinning, no offline branch), so the view model holds plain DTOs and re-fetches on .smartListsDidChange. Fetched members DO upsert into the books/series tables like every other fetched page (SyncService.syncSmartListBooks/syncSmartListSeries).
• Member loads POST a BookSearch/SeriesSearch overlay that narrows the stored filter server-side, built from the browse options via BookBrowseOptions.toSearchFilters()/SeriesBrowseOptions.toSearchFilters() + buildCondition (the same mapping the browse endpoints use; scoping ids stay with the caller).
• Remote smart-list SSE events debounce (5s) through ListProjectionSyncService.scheduleSmartListSync, which posts .smartListsDidChange per accumulated id — there is no projection to sync, but observers filter the post by smartListId, so ids accumulate like the other families. SmartListThumbnailChanged force-refreshes the cover through ThumbnailCache.refreshThumbnail(id:type: .smartList). Remote read-progress SSE events debounce separately into .smartListMembershipDidChange (no id — any read-status-based list may move), which member lists revalidate on.
• UI surfaces: a third strip on the Lists page (ListsBrowseView, hidden when unsupported/empty/offline — the library scope does not filter it), the full browseSmartLists page (SmartListsBrowseView, client-side name search, no sort/filter/library scope — the endpoint is name-sorted with no query params), and SmartListDetailView (browse + read + edit/delete for owner/admin; no pin, download, or selection mode). Create/edit goes through SmartListEditSheet (entry points: the browse page's trailing + and its empty state, the detail-page menu, card/row context menus): the target is fixed after creation, no sort is stored (chosen at browse time — the options sheets take showsSort: false, which also hides preset saving since presets write the shared browse-options keys), and visibility/share-target picking is admin-only (non-admins always create private lists). On update the sheet sends search only when the filter subsection diverges from its parsed baseline, and the reverse mapping's lossy flag shows a warning that any filter change replaces the whole stored document — web-UI-built filters the editor cannot represent survive a rename. Member lists revalidate on every book/series projection change and on .smartListMembershipDidChange, never gated on isSensitiveToReadingProgress: the stored server-side filter may be read-status-based even when the overlay options are not.

Browse & Dashboard

Library Selection

• Two separate concepts share the library scope UI: the pinned set (dashboard.libraryIds, empty = all libraries) is the persisted aggregate scope — per-instance via DashboardLibrarySelectionStore (UserDefaults dashboard config + GRDB komga_instances.selected_library_ids_raw), edited through the checklist in LibraryPickerSheet and consumed by the Dashboard, the iPhone Library/Search tab roots, Offline, search, and widgets. The session scope (a LibraryBrowseScope of .pinned/.all/.library(id), default .pinned, resolved via resolvedIds(pinned:)) is per-surface view state: the Dashboard keeps it in DashboardLibraryScopeStore.shared, the iPhone Library/Search tabs, Offline, and pushed browse pages keep it in local @State, and iPad/macOS browse roots take it from the shell (next bullet); never persisted, the dashboard's resets in DashboardLibrarySelectionStore.loadSelection (app start and server switch) and when the scoped library vanishes from the loaded list (browse pages reset the same way); dashboard sections fetch with effectiveLibraryIds(pinned:) while widgets always follow the pinned set.
• Scope identity renders in two forms, both fed by LibraryBrowseScope.title(pinnedIds:libraries:) / .facts(pinnedIds:libraries:allLibrariesEntry:) (the shared title text and covered-metrics item; metrics are admin-only: .all/empty-.pinned read the server's all-libraries entry since overlapping roots make client-side sums overstate file size, a non-empty .pinned sums the covered libraries client-side, .library(id) uses the library's own row). The Dashboard shows LibraryScopeHeader (Dashboard/Views): icon matching the scope menu (books.vertical for All/a library, pin for Pinned), the title, and a single truncating facts line (file size first, then series/books — no sidecars — via LibraryMetricsText.sizeAndMetrics). Browse pages and Offline instead show a caption trailing the content-type chip — the scope title set off from the facts that follow in secondary: just the file size on browse pages (the series/books counts ride the chip itself in parentheses, from the same scope facts item; collections/read lists carry no counts), just the total downloaded size on Offline (the downloaded series/books counts ride the chip in parentheses, from fetchDownloadedSeriesCount and fetchOfflineBooksStats(instanceId:libraryIds:) — both matching their offline list filters, refreshed on scope/instance change and on DownloadProgressTracker.queueUpdateToken). LibraryScopeStore.refreshMetrics reloads the metrics (admin-gated, no-op offline) on every dashboard refresh and browse-page library refresh; full reloads stay with LibraryPickerSheet and Settings → Libraries. Library metrics prefer the kmrs-native stats endpoints (/api/v1/stats/libraries for per-library counts and the all-libraries total) and fall back to the Komga actuator metrics (komga.books.filesize/komga.series/komga.books, untagged totals plus per-library tags) when they 404 — the fallback covers only library size/series/books, so sidecar counts simply never appear on Komga; per-instance verdicts live in AppConfig.serverStatsCapability (24h recheck, the same probe pattern as reading stats), and the stored numbers are cleared only when both sources fail, so previously stored numbers never linger. Server metrics come only from /api/v1/stats/server — task, process, and global stats — with no actuator fallback. Sidecar counts (per-library and total) ride the /stats/libraries payload but are only sent to admins; the payload carries no collections/read lists counts, and library-level RL/C counts are not surfaced anywhere. The Server Info page works on both servers: on kmrs it loads /stats/server (process snapshot, content totals, per-type task metrics) plus the actuator info/health endpoints, and on Komga the same rows fall back to per-metric actuator reads (process.* for CPU/uptime/start/memory — CPU percent vs 0-1 ratio told apart by the meter's baseUnit — and the komga.* gauges for content); the shared /stats/server 404 probe (AppConfig.serverStatsCapability) picks the path. The overview shows server identity (version, commit, OS), process and resources (start time, uptime, CPU, memory, disk), and content totals, plus maintenance actions (log file download via share sheet, hidden when the HEAD probe 404s as on stock Komga; server shutdown behind confirmation); the task queue, sessions, and scheduled tasks are sub-pages — Tasks pairs the SSE live queue and Cancel All with the per-type execution metrics (runs/total/longest/failures, from /stats/server on kmrs and the komga.tasks.* meters on Komga), Sessions lists /actuator/sessions with per-session kick (kmrs lists all users, Komga rejects the cross-user listing and falls back to the current user's ?username= query), Scheduled Tasks lists the actuator fixed-rate registrations (Java FQN targets shortened to their meaningful tail). A failed load keeps the previously stored numbers.
• Browsing a single library is navigation on all platforms (the sidebar/tab bar selects NavDestination.browseLibrary). On iPad/macOS the Libraries section leads with the aggregate entries — "All Libraries" (NavDestination.browse(scope: .all)) and, only while the pinned set is non-empty, "Pinned" (.browse(scope: .pinned)) — inside the same section as the individual libraries, because the tab bar's Libraries item opens the section's first tab (a separate aggregate section would land on the first library instead); the aggregate rows are plain text like the library rows (no icons, no separator — the iPad TabSection accepts only tabs), and the shells redirect a live pinned-aggregate selection to All when the last pin is removed. Browse roots on those platforms take their scope from the shell through the \.libraryScopeBinding environment key (a value-type Binding<LibraryBrowseScope> provided by PadTabView/MainSplitView): the scope menu writes through to the shell's selection, so an in-page pick switches sidebar row/tab and the highlight follows. Pushed browse pages get the binding cleared to nil (in View+Navigation) and keep a page-local session scope, the pushed selection only its initial value; on iPhone, pushed single-library pages carry no scope menu.

Selection Mode

• Selection mode exists on the series detail books list, the books and series browse pages, and the read list/collection membership lists (remove-only, admin). Entry is a trailing checkmark.circle button next to the filter chip row; tvOS always disables it (supportsSelectionMode), and the online-only modes hide it while offline.
• Two toolbars: SelectionActionsToolbar (select all, mark read/unread, one list-membership add action, cancel) for the books/series lists, and SelectionToolbar (remove-only) for read list/collection membership, which keeps full selection disabled so the list can never be emptied through it.
• Select-all scope: detail lists cover full membership from GRDB; browse pages cover only the loaded window (kmweb parity).
• The membership pickers (ReadListPickerSheet/CollectionPickerSheet) take id arrays, not single ids; a row is alreadyIn (disabled) only when it contains every selected id. Batch add goes through ReadListService.addBooksToReadList/CollectionService.addSeriesToCollection (GET + full-replace PATCH), then syncs and posts the projection change.
• Batch mark read/unread runs per-item requests in a task group, then re-syncs the succeeded items (series-scoped lists: syncSeriesDetail/syncAllSeriesBooks + postSeriesBooksDidChange; the cross-series books browse: syncVisitedItems + postBooksAndSeriesDidChange), followed by one DashboardSectionRefreshNotifier.postReadStatusChanged and a full list reload.

Page Structure

• Browse pages split shell from content: BrowseContentView is the scrollable content (optional library header, content-type menu, search placeholder, per-type lists) and owns no chrome; the content-type switcher is BrowseContentTypeMenu, a leading-aligned chip-style dropdown (current type icon + name + chevron, same chrome as LayoutModeMenu/FilterChip), never a segmented picker. BrowseView is the standalone-page shell around it (search field + onSubmit query state, toolbar, navigation title, refresh triggers), the Dashboard search overlay is DashboardSearchResultsView, which feeds the Dashboard's submitted query straight to BrowseContentView, filtered by the dashboard's session scope, and the Lists page's single-type detail pages use ListsBrowseDetailView (Collections/Read Lists/Smart Lists fixed content, scope menu except smart lists, layout/filter actions, inline navigation title) — split from BrowseView so that shell keeps only the tab-root and search modes plus metadata-filtered series/books pages. The overlay appears only once a query is submitted — there is no placeholder state on iPad/macOS; while typing or after clearing the field, the dashboard stays visible. Embedded content never gets its own search field or toolbar — they would duplicate the enclosing page's chrome. Every shell wires real filter-sheet state into BrowseContentView (the in-content filter bars drive those bindings; a .constant leaves the sort/preset chips dead), and the effective content type resolves through BrowseContentType.effective(fixed:offered:persisted:).

Pagination & Ordering

• Browse pages paginate with PaginationState(pageSize: 50). Notification-driven refreshes revalidate the loaded window in place via PaginationState.replaceItems; full pagination.reset() is reserved for initial loads and explicit user actions.
• .task/.task(id:) re-runs when a view re-appears after a pushed navigation child pops back to it, so initial-load tasks (detail pages and their book/series list views) guard on a loadedXxxId state key and skip re-fires for the same id; returning from a child must not re-sync or reset pagination.
• User-facing metadata lists (authors, publishers, genres, tags, languages) sort with Collection.localizedSorted(); authors via Author.sortedByRole(). Never revert to raw .sorted(). (MetadataIndex encode keys and SQL clause ordering intentionally keep plain .sorted().)
• Online ordering is server-side; the app-local pinned flag is invisible to the server, so online pages prepend pinned items and filter them out of the server stream.

Empty & Error States

• Empty and error states render through ContentUnavailableView (icon label, description, actions) — never hand-drawn icon + text stacks. Browse lists go through the shared BrowseStateView (loading/empty/content wrapper), which owns the ContentUnavailableView empty state internally; retry actions use .adaptiveButtonStyle(.borderedProminent). Search-with-no-results uses ContentUnavailableView.search(text:).

Dashboard Rows

• Section chrome is shared: DashboardSectionLayout owns the gradient band, the header navigation link (title + chevron, optional DashboardCardKindMenu), the horizontal card strip, and the empty-collapse (opacity + zero height while isEmpty). Item mutations animate through withAnimation in the loading view models (applyPage/removeItem/cache seed), which drives both the band's collapse/expand and the strip's per-item interpolation. The band's vertical rhythm comes from LayoutConfig — top padding above the header (dashboardSectionTopPadding) and bottom padding below the cards (dashboardSectionBottomPadding(gradientBackground:), which shrinks to the top value without the gradient since the band edge is invisible), a tighter header-to-cards gap (dashboardSectionHeaderSpacing), and no inter-band spacing, so adjacent gradient bands touch and each band's gray gradient edge is the section separator (Apple Books style). The scope header (LibraryScopeHeader) is a plain row above the bands, not a band itself; its padding stays minimal so it reads as a caption under the navigation title, not as another section. On macOS the strip's vertical padding sits outside the ScrollView so the hover scroll arrows' (macHorizontalScrollButtons) overlay hugs the cards — iOS/tvOS keep it in the scroll content so the padding area still drags the strip; the arrows center on the cover block, which DashboardSectionLayout derives from the section's effective card kind (grid cards carry metadata below the cover, horizontal cards are cover-tall and center on the strip).
• Strips on the Dashboard and Lists outer pages show the first page only — there is no in-strip pagination; deeper browsing lives in the section's detail page. Besides the header chevron, pulling a strip past its trailing edge and releasing pushes the same destination (trailingOverscrollTrigger, iOS 18+ only: a chevron hint arms past the threshold with a haptic and fires on release; the header link stays the entry elsewhere). The push goes through the \.pushNavDestination environment action published by PushableNavigationStack at each tab/split stack root, so an overscroll push resolves through the same navigationDestination(for:) mapping as the header link.
• Dashboard progress sections always revalidate on .readingProgress; other sections skip unless browse options are progress-sensitive (isSensitiveToReadingProgress).
• Dashboard rows load through the central DashboardViewModel that DashboardView owns, never in a view .task and never in the section views: switching the macOS split-view sidebar back to Home adds, removes, and re-adds the dashboard within milliseconds with its state kept, which cancels view-scoped loads mid-request. Section views are pure renderers with no lifecycle or notification modifiers of their own — loads and reloads must not depend on a section view's lifetime. DashboardView starts loads (ensureLoaded) on appear and when the section list changes, awaits the view model directly for its own refreshes, and observes .dashboardSectionsShouldReload once at the root, dispatching commands (applyReloadCommand) with the rendered sections and effective library ids; the read-lists-in-progress section is special-cased there (ReadListReadingService sync/refresh).
• Appearing starts a load only for sections where none has completed or is running; a reload supersedes a load in flight (newest wins) instead of being dropped. Do not reintroduce load-once flags or isLoading guards that drop a re-run.

Pull-to-Refresh

• .refreshable closures must await the reload they trigger, so the refresh control dismisses onto settled content instead of racing in-flight view updates.
• An active refresh action is cancelled as soon as the view carrying .refreshable re-renders, taking the action's child tasks (and their network requests) down with it. The refreshable-carrying body must therefore read no state the reload mutates: refreshing view models stay on the shell, while the content that reads them is a child view (ListsBrowseView shell + ListsBrowseContentView strips). The Dashboard's body DOES read scopeStore while refreshDashboard mutates it — it survives because LibraryScopeStore.load() skips no-change assignments, so in practice the body does not re-evaluate; keep that guard intact when touching the store. Its body must likewise never read DashboardViewModel's section state — only the section views may. Re-evaluating a child's body during the refresh is fine — only the carrier's body matters.
• Dashboard manual refreshes await the central DashboardViewModel.reload directly (refreshable dismisses onto settled content, no per-section acknowledgement). DashboardRefreshCoordinator remains only for auto-refresh debounce (5s) and reader-session deferral of auto/projection refreshes; externally posted reload commands (reconnect, SSE auto, projections, read-status changes) arrive as notifications the dashboard root observes once. A dashboard that is recreated later loads fresh on appear, so off-dashboard refreshes (e.g. the Settings/Server offline toggle) are not lost.
• The Dashboard has no toolbar refresh affordance at all — pull-to-refresh covers iOS/macOS and tvOS keeps its header button (disabled while a refresh is in flight). Pages whose reload can finish near-instantly (Dashboard, Offline, Lists) use refreshableWithMinimumHold so the control stays up for a minimum visible time instead of snapping back.
• On iPhone the Offline page pins its search bar (navigationBarDrawer(displayMode: .always)): in automatic mode the drawer's hide/reveal animation fights the refresh control during the pull. iPad/macOS keep .automatic — their search field lives in the toolbar and never conflicts.
• OfflineView awaits the browse view models it owns and shares with OfflineSeriesBrowseView/OfflineBooksBrowseView, whose refreshBrowse() re-runs the view model's current query; library-selection and account-switch reloads instead bump a refreshTrigger passed to those child views, so the reload runs through the child and captures the current libraryIds rather than replaying the view model's stale query.

Read Lists in Progress

• Read lists continue like series: only ordered read lists with reading state and a book to continue with take part (a book in progress, or once a book is finished the next unread one, searching forward from the last book read).
• They surface only in their own readListsInProgress dashboard section, first by default, driven directly by ReadListReadingService.continuations; On Deck and Keep Reading stay Komga-native, never merged or filtered.
• ReadListsInProgressSectionView renders one card per list, most recently read first, with no pagination or detail page; the header links to the read lists browse page.
• Cards follow the section's card kind. ReadListContinuationHorizontalCardView is the default: it shares Keep Reading's horizontal-card chrome through HorizontalCardSkeleton, and its text column follows the horizontal-card contract — semibold title line (the list's name), primary book line, secondary progress line.
• ReadListContinuationCardView renders large/small, with the list's name in the series slot, cover-only when small.
• Both share ReadListContinuationContextMenu, ReadListContinuationProgressText, and ReaderActions.open(continuation:).
• The library scope hides a card by its continuation book's library without changing which book a list resolves to.
• The section is opt-in: it is not in DashboardSection.defaultSections, the setting's toggle (SettingsReadListContinuationToggle) adds and removes it, DashboardSection.isAvailable hides it from the settings lists and Reset while off, and DashboardView renders it only while on.
• While off, ordered, non-empty read list pages show ReadListContinuationHintView pointing to the setting, injected through the detail view's actions slot.