Separate reader panels and controls from session coordination

AGENTS.md

@@ -2,7 +2,7 @@
 
 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/reader-plan.md` before changing architecture or expanding formats.
+Read `docs/architecture.md` before changing architecture or expanding formats.
 
 - Domain types are host-facing and serializable. Keep version-1 locators readable.
   EPUB content offsets are chapter-local normalized UTF-16 offsets, never page
@@ -15,7 +15,7 @@ Read `docs/reader-plan.md` before changing architecture or expanding formats.
 - Rebuild `assets/epub_worker.js` with `tool/build_epub_worker.sh` after modifying
   worker source. The packaged JS lets dependent applications build without a
   manual worker generation step. CI checks the generated asset for drift.
-  This private repository commits `pubspec.lock` and pins its CI SDK so the
+  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

README.md

@@ -72,7 +72,6 @@ return `ReaderErrorCode.unsupportedFixedLayout`. MOBI/AZW3, TXT, comic
 archives, search, bookmarks, highlights, and notes are planned extensions.
 
 - [Architecture](docs/architecture.md)
-- [Core release plan](docs/reader-plan.md)
 - [Client integration](docs/integration.md)
 - [Supported formats](docs/supported-formats.md)
 

docs/architecture.md

@@ -72,3 +72,41 @@ Material defaults are constructed from the reading palette rather than copying
 the host's resolved colors. This includes the legacy canvas color used by dropdown
 popup routes, field labels/borders and disabled controls. Host typography, control
 geometry, theme extensions and motion policy remain available to the reader.
+
+The presentation layer keeps session, keyboard and viewport coordination in
+`papyrus_reader.dart`. Toolbar/progress controls, contents, settings and the panel
+header live in separate presentation modules. These modules are implementation
+details and are not exported by the package entry point. Public builder contexts
+and custom-engine integration remain in the shell's existing public API.
+
+## Library decisions
+
+- Retain `epub_pro` 5.6 for EPUB container, metadata and navigation parsing behind
+  a worker boundary. Do not treat its TOC as the OPF spine.
+- Retain `pdfrx` 2.x for all six PDF targets. Its native/WASM viewer already owns
+  rendering and zoom; a facade keeps engine tests independent of PDFium.
+- Retain `flutter_html` for the injectable HTML scrolling renderer. Native rich
+  pagination must preserve semantic runs and images instead of extracting only
+  plain text. Reader preferences override publisher colors and text sizing.
+- Use Dart/Flutter SDK concurrency plus `web` for a packaged browser worker.
+  Flutter `compute` alone is insufficient: it uses the UI event loop on web.
+- Avoid adding platform WebViews for this release: desktop/Linux and web would
+  need different engines and bridges. Re-evaluate a browser EPUB renderer for
+  full publisher CSS, fixed-layout EPUB and standardized CFI interoperability.
+
+Sources: [Flutter isolate behavior](https://docs.flutter.dev/perf/isolates),
+[epub_pro API](https://pub.dev/documentation/epub_pro/5.6.0/epub_pro/EpubReader-class.html),
+[pdfrx](https://github.com/espresso3389/pdfrx/tree/master/packages/pdfrx).
+
+## UI and integration
+
+Keep a quiet reading canvas, readable line length, 48px controls, clear contents
+and appearance panels, and a progress scrubber. Typography and navigation must
+behave the same on phone and desktop. Respect reduced motion and e-ink hosts.
+Capability flags expose only controls implemented by the active engine.
+
+Existing `ReaderDocument`, controller ownership and observer callbacks remain
+compatible. EPUB locators gain optional content offsets; legacy CFI strings are
+compatibility data, not a claim of full EPUB CFI conformance. The Papyrus adapter
+already stores complete locator JSON, so optional locator fields need no database
+schema migration. Host preference and progress writes remain host-owned.

docs/supported-formats.md

@@ -13,5 +13,5 @@ and illustrations are preserved. Complex tables become readable rows; publisher
 stylesheets, embedded fonts, advanced SVG/math, RTL book progression and footnote
 interaction are not complete. Font choices use installed platform families.
 
-Search, bookmarks, highlights and notes are planned in `reader-plan.md`. Do not
+Search, bookmarks, highlights and notes are future extensions. Do not
 advertise them until their engines, UI and host persistence contracts exist.

docs/validation.md

@@ -63,5 +63,5 @@ remain necessary before declaring a production release. No cold-open or frame
 latency guarantee is claimed from the synthetic fixtures.
 
 Publisher CSS/fonts, RTL progression, complex tables/math and fixed-layout EPUB
-are outside this core implementation; see `supported-formats.md` and the release
-plan before evaluating books that rely on those features.
+are outside this core implementation; see `supported-formats.md` and the architecture
+reference before evaluating books that rely on those features.