Cross-platform Flutter frontend

Build Shōsai as one Dart and Flutter application for desktop, phone, and tablet, with the document engines, the store, and the reading model in Dart rather than behind a native bridge, and define what that application ships first: one reading experience across formats and devices (see The first release). Preserve a credible web path without claiming that native dependencies already run in a browser.

Replace the unreleased Iced frontend with Flutter across Linux, macOS, Windows, Android, and iOS. The Iced application is historical reference, not a baseline the Flutter frontend must match: the first release is defined by the outcomes in The first release, and the Iced code is removed in its own change rather than kept until a parity gate.

The application is Dart only (decided 2026-10-21; see Decisions). The Rust core (crates/shosai-core), the flutter_rust_bridge crate and its generated Dart are replaced by Dart modules before the first-release reader work builds on them: the EPUB engine is already Dart (shosai_epub, adopted 2026-09-28), PDF moves to a Dart-owned PDFium binding, storage to a Dart SQLite binding, and library, bookmarks, reading state, annotations and search are ported with their tests. Rust stays a behavioural reference until each slice lands, then is deleted; nothing new is built in it. The replacement is tracked as milestone M3.0 in the checklist.

The application has not been released. Internal Dart APIs and the development SQLite schema may change without compatibility wrappers or dual-read periods. Once a release or synchronization wire format exists, its declared compatibility contract applies normally.

The first release is a reader that gives the same reading experience regardless of medium: a person reads, marks up, searches, and follows references the same way in an EPUB or a PDF, on a desktop, a tablet, or a phone. The outcomes below are what the Flutter frontend must deliver first. Where the current implementation disagrees with them, the outcomes win. (Folded in from a former proposal numbered 7 in the Shōsai repository on 2026-10-20; the product is unreleased, so the proposal lives here rather than in a superseding RFD.)

Iced’s desktop implementation proves important product behavior, but Iced does not officially support Android or iOS. Owning mobile bootstrap, lifecycle, packaging, software keyboards, accessibility, and platform services would turn Shōsai into a mobile GUI framework maintainer.

Flutter contributes more than wrappers around native APIs. It provides one widget, navigation, input, accessibility, localization, state-restoration, and testing model across form factors; adaptive layouts; touch, mouse, keyboard, and stylus input; hot reload; golden and integration tests; and a mature plugin ecosystem. Those capabilities can be reused by every format reader and by sync, annotation, notification, and settings experiences.

Keeping Iced on desktop and Flutter on mobile would preserve working code in the short term but permanently duplicate reader interaction, accessibility, and UI testing. Before release, replacing that duplication is cheaper than maintaining two frontends indefinitely.

The same reasoning applies one layer down. With the EPUB engine in Dart, what the Rust core still owned after the Iced removal was one PDFium wrapper, the SQLite store and the library, bookmark, reading-state, annotation and search records: ordinary application code with no shaping or layout in it. Keeping it in Rust cost a second language and test suite, a generated bridge pinned to a Rust toolchain and a bridge-generator version, a native library to cross-compile and package for five targets, and a WASM project before any web build. Every first-release feature (notes, search, references) would have crossed that bridge. Replacing the core before M3.2 builds on it is cheaper than building the reader twice. The evaluation’s measured findings (a Dart PDFium binding rasterised at least as fast on the tested corpus; SQLite needs eleven tables and no full-text extension) support the move; its named risks (binding version pinning, native asset provisioning, one permission-bit defect) are gates in M3.0, not reasons to keep the bridge.

One language, three layers: document engines, an application core, and the Flutter presentation. The layers are Dart packages and modules with explicit ownership, not processes or a bridge; the Elm-style controller boundary in the Flutter architecture contract is unchanged.

Migration is tracked as dependency-ordered milestones rather than as one frontend rewrite. Each milestone has an explicit exit gate in the implementation checklist. A phase is complete only when its exit gate is satisfied; checking individual tasks records progress but does not waive the gate.

M0 to M2 are complete and record the Rust-era boundary. M3.0 precedes M3.2: the reader by format is built on the Dart core, not on the bridge; M3.1 (the library slice) was delivered on the bridge and is re-pointed at the Dart core by M3.0. M4 is demand-driven and need not block M3. M5 follows the first-release outcomes on each platform. M6 is intentionally independent and may run in parallel once the Dart core is stable.

Using Iced everywhere maximizes Rust UI sharing but requires unsupported mobile platform ownership. Keeping Iced desktop plus Flutter mobile avoids an immediate desktop rewrite but creates two long-lived interaction and accessibility stacks. Separate SwiftUI and Android-native frontends maximize platform fidelity but add two UI languages and still need another desktop frontend. Reconsider separate native frontends only if the Flutter gate fails a required criterion.

Keeping the Rust core behind flutter_rust_bridge (the architecture from M0 to M3.1) preserved tested code and a memory-safe parsing boundary, and it is what M2 measured. It was rejected on 2026-10-21 because, once EPUB was Dart, the remaining Rust was application code whose only Rust-specific value was the PDFium wrapper, and that wrapper exists as a Dart binding; the bridge’s toolchain, cross-compilation, packaging and web costs then bought nothing. A hybrid that kept only PDF in Rust was not taken either: it keeps every cost of the bridge for one module. Rust may return for a specific, measured need (a format parser with no sound Dart binding) as a leaf native plugin, never as the application core.

RFD 9's parser, resource-security, stable-location, and bounded-layout decisions remain valid and now bind the Dart EPUB engine; its Iced implementation is historical evidence rather than the presentation boundary. RFD 10 format capabilities, including the comic archives that leave the first release, are Dart engines behind one Flutter reader shell. RFD 11 supplies portable identity and sync semantics independently of notification delivery and extends the Dart store. RFD 13 packages Flutter hosts with their pinned native libraries (PDFium, SQLite) instead of a Rust library and bridge. RFD 16 supplied the first cross-format interaction and persistence slice; its annotation store and PDF adapter move to Dart with M3.0.

The dependency-ordered spike, extraction, migration, web, and packaging work is tracked in RFD 12 implementation checklist.