fix: improve reader progress, navigation and host-owned panels

AGENTS.md

@@ -4,9 +4,10 @@ This is an independent Flutter package and Git repository. The owning workspace
 is one level up; use its `tools/flutter` and `tools/dart` SDK wrappers when present.
 Read `docs/architecture.md` before changing architecture or expanding formats.
 
-- Domain types are host-facing and serializable. Keep version-1 locators readable.
+- Domain types are host-facing and serializable. Implement the current locator contract
+  without compatibility shims for older app versions.
   EPUB content offsets are chapter-local normalized UTF-16 offsets, never page
-  numbers. Legacy CFI strings are compatibility data, not conformant anchors.
+  numbers. Standardized EPUB CFI interoperability is not implemented.
 - The host owns bytes, persistence, routing and account/profile isolation.
   Package engines own transient resources and must release them on cancellation.
 - EPUB document processing is pure Dart in `lib/src/engine/epub/worker`. Native
@@ -18,8 +19,10 @@ Read `docs/architecture.md` before changing architecture or expanding formats.
   This package commits `pubspec.lock` and pins its CI SDK so the
   browser worker and third-party notices are reproducible.
 - UI text measurement belongs in Flutter. Preserve semantic runs, Unicode,
-  illustrations and content offsets when reflowing. Layout must use the space
-  left after panels, system insets and text scaling, not device width alone.
+  illustrations and content offsets when reflowing. Layout must use actual viewport
+  constraints, system insets and text scaling.
+  Temporary shell panels overlay the viewport without changing pagination or
+  the reading position; opening them must not trigger a reflow.
 - Keep custom engines/renderers/builders usable. Don't silently expose settings
   that the active engine cannot apply.
 - Use in-process transport in widget tests with fake clocks; exercise native and

README.md

@@ -46,12 +46,18 @@ provided `ReaderController` remains host-owned. With an external controller,
 omitted initial preferences remain controller-owned; an explicit value
 overrides them for the document load.
 
-Use **Hide controls** in the toolbar for distraction-free reading. Both bars
-collapse, expanding the page area without reopening the document. Page-turn
-keys, EPUB swipes and PDF scrolling remain available. The small **Show controls**
-button in the top corner or **Escape** restores the bars. This is temporary UI
-state; opening another document restores the controls. Custom toolbar builders
-can expose `ReaderToolbarContext.toggleControls`.
+Tap the reading surface or press **Escape** to hide or restore controls. The
+viewport stays the same size, so this does not repaginate or move the book.
+Page-turn keys, EPUB swipes and PDF scrolling remain available. Custom toolbar
+builders can expose `ReaderToolbarContext.toggleControls`.
+
+Hosts can supply `ReaderUiBuilders.compactPanelRoute` to put Contents and Reading
+settings inside their own sheet shell. The factory receives the panel title, kind,
+and a live `buildContent(context, scrollController)` builder without reader headers
+or framing. Return an unpushed `Route<void>`; the reader handles presentation,
+activity tracking and cleanup. Connect the builder's scroll controller to your
+sheet's scrolling coordinator. Omit this hook to use the standalone defaults.
+See [Architecture](docs/architecture.md) for the presentation contract.
 
 ## Example