refactor: code review cleanup, bug fixes, and RTC session persistence rtc session persistence: - add rtc_session module for deep sleep state preservation - save/restore nav stack, reader position, files scroll, home state - cache settings in RTC memory to skip SD reads on wake - keep RTC FAST memory powered during sleep (~1-2µA extra) - add collect_session/apply_session to AppLayer trait - add session state accessors to home, files, reader apps bugs: - fix typos in timing.rs (dookmark -> bookmark, dffset -> offset) - add spine bounds check in images.rs scan_chapter_for_image - add chapter validation after spine load in reader - log errors on pulp dir creation failure in main.rs - fix misleading comment in bitmap.rs (fallback is '?' not space) consolidation: - remove redundant extern crate alloc from files.rs, reader/mod.rs, images.rs - extract hint() helper in build.rs - extract is_power_event() helper in scheduler.rs - extract enter_error() helper in reader/mod.rs - add CONTENT_REGION constant in home.rs - trim unused layout constants clarity: - add rotation comment for SCREEN_W/H swap in board/mod.rs - add window bounds comment in strip.rs - rename cryptic vars in paging.rs (lc->line_count, ls->line_start, etc) - add state machine comment in reader/mod.rs simplification: - use if let instead of empty match in storage.rs - use map_or in app.rs render_ready - use .expect() for spawn failures in main.rs style: - convert /// doc comments to // in rtc_session.rs, layout.rs, utf8.rs

build.rs

···
     generate_bitmap_fonts();
 }
 
+fn hint(msg: &str) {
+    eprintln!();
+    eprintln!("hint: {msg}");
+    eprintln!();
+}
+
 fn linker_be_nice() {
     let args: Vec<String> = std::env::args().collect();
     // --error-handling-script passes two args: kind and symbol
···
 
         match kind.as_str() {
             "undefined-symbol" => match what.as_str() {
-                what if what.starts_with("_defmt_") => {
-                    eprintln!();
-                    eprintln!(
-                        "hint: `defmt` not found - make sure `defmt.x` is added as a linker script and you have included `use defmt_rtt as _;`"
-                    );
-                    eprintln!();
-                }
-                "_stack_start" => {
-                    eprintln!();
-                    eprintln!("hint: is the linker script `linkall.x` missing?");
-                    eprintln!();
-                }
-                what if what.starts_with("esp_rtos_") => {
-                    eprintln!();
-                    eprintln!(
-                        "hint: `esp-radio` has no scheduler enabled. make sure you have initialized `esp-rtos` or provided an external scheduler."
-                    );
-                    eprintln!();
-                }
-                "embedded_test_linker_file_not_added_to_rustflags" => {
-                    eprintln!();
-                    eprintln!(
-                        "hint: `embedded-test` not found - make sure `embedded-test.x` is added as a linker script for tests"
-                    );
-                    eprintln!();
-                }
+                what if what.starts_with("_defmt_") => hint(
+                    "`defmt` not found - make sure `defmt.x` is added as a linker script and you have included `use defmt_rtt as _;`"
+                ),
+                "_stack_start" => hint("is the linker script `linkall.x` missing?"),
+                what if what.starts_with("esp_rtos_") => hint(
+                    "`esp-radio` has no scheduler enabled. make sure you have initialized `esp-rtos` or provided an external scheduler."
+                ),
+                "embedded_test_linker_file_not_added_to_rustflags" => hint(
+                    "`embedded-test` not found - make sure `embedded-test.x` is added as a linker script for tests"
+                ),
                 "free"
                 | "malloc"
                 | "calloc"
···
                 | "malloc_internal"
                 | "realloc_internal"
                 | "calloc_internal"
-                | "free_internal" => {
-                    eprintln!();
-                    eprintln!(
-                        "hint: did you forget the `esp-alloc` dependency or didn't enable the `compat` feature on it?"
-                    );
-                    eprintln!();
-                }
+                | "free_internal" => hint(
+                    "did you forget the `esp-alloc` dependency or didn't enable the `compat` feature on it?"
+                ),
                 _ => (),
             },
             _ => {

kernel/src/board/mod.rs

···
 pub use crate::drivers::strip::StripBuffer;
 pub use button::{Button, ROW1_THRESHOLDS, ROW2_THRESHOLDS, decode_ladder};
 
+// logical screen size (portrait mode via 270-degree rotation of 800x480 panel)
 pub const SCREEN_W: u16 = HEIGHT; // 480
-pub const SCREEN_H: u16 = WIDTH; // 800
+pub const SCREEN_H: u16 = WIDTH;  // 800
 
 use core::cell::RefCell;
 

kernel/src/drivers/input.rs

···
                 if !self.long_press_fired && held >= Duration::from_millis(timing::LONG_PRESS_MS) {
                     self.long_press_fired = true;
                     self.last_repeat = now;
+                    log::info!("input: LongPress({:?}) after {}ms", btn, held.as_millis());
                     return Some(Event::LongPress(btn));
                 }
 
···
     }
 
     fn read_raw(&mut self) -> Option<Button> {
-        if crate::board::power_button_is_low() {
+        let power_low = crate::board::power_button_is_low();
+        if power_low {
             return Some(Button::Power);
         }
 

kernel/src/drivers/storage.rs

···
     let mut guard = borrow(sd)?;
     let inner = &mut *guard;
 
-    match inner.mgr.open_dir(inner.root, PULP_DIR).await {
-        Ok(dir) => {
-            let _ = inner.mgr.close_dir(dir);
-            return Ok(());
-        }
-        Err(_) => {}
+    if let Ok(dir) = inner.mgr.open_dir(inner.root, PULP_DIR).await {
+        let _ = inner.mgr.close_dir(dir);
+        return Ok(());
     }
     match inner.mgr.make_dir_in_dir(inner.root, PULP_DIR).await {
         Ok(()) => Ok(()),

kernel/src/drivers/strip.rs

···
         gy: i32,
         black: bool,
     ) {
+        // window bounds (wx, wy = origin; wx2, wy2 = extent; rb = row bytes)
         let wx = self.win_x as i32;
         let wy = self.win_y as i32;
         let wx2 = wx + self.win_w as i32;

kernel/src/kernel/app.rs

···
             Redraw::None => false,
             Redraw::Full => true,
             Redraw::Partial(_) => {
-                self.immediate
-                    || self
-                        .coalesce_until
-                        .map(|t| Instant::now() >= t)
-                        .unwrap_or(true)
+                self.immediate || self.coalesce_until.map_or(true, |t| Instant::now() >= t)
             }
         }
     }
···
         }
     }
 
+    #[inline]
     pub fn active(&self) -> Id {
         self.stack[self.depth - 1]
+    }
+
+    #[inline]
+    pub fn depth(&self) -> usize {
+        self.depth
+    }
+
+    #[inline]
+    pub fn stack_at(&self, index: usize) -> Id {
+        self.stack[index]
+    }
+
+    /// Check if an app ID is anywhere in the stack
+    pub fn contains(&self, id: Id) -> bool {
+        self.stack[..self.depth].iter().any(|&i| i == id)
+    }
+
+    /// Restore stack from saved session data
+    ///
+    /// The `convert` function maps u8 values to Id.
+    pub fn restore_stack<F>(&mut self, depth: usize, stack: &[u8], convert: F)
+    where
+        F: Fn(u8) -> Id,
+    {
+        self.depth = depth.min(MAX_STACK_DEPTH).max(1);
+        for i in 0..self.depth {
+            self.stack[i] = convert(stack[i]);
+        }
     }
 
     pub fn apply(&mut self, transition: Transition<Id>) -> Option<NavEvent<Id>> {
···
     fn load_eager_settings(&mut self, k: &mut KernelHandle<'_>);
     fn load_initial_state(&mut self, k: &mut KernelHandle<'_>);
     fn enter_initial(&mut self, k: &mut KernelHandle<'_>);
+
+    // session persistence: save/restore active app across sleep/wake
+    // using RTC FAST memory (survives deep sleep, zeroed on power-on)
+    //
+    // collect_session writes app state to the provided RtcSession struct
+    // apply_session restores app state from RtcSession, returns true if successful
+    fn collect_session(&self, session: &mut super::rtc_session::RtcSession);
+    fn apply_session(&mut self, session: &super::rtc_session::RtcSession, k: &mut KernelHandle<'_>) -> bool;
 
     // true when the active app wants to take over the main loop
     // (e.g. wifi upload mode bypasses the normal event dispatch)

kernel/src/kernel/mod.rs

···
 pub mod console;
 pub mod dir_cache;
 pub mod handle;
+pub mod rtc_session;
 pub mod scheduler;
 pub mod tasks;
 pub mod timing;

kernel/src/kernel/rtc_session.rs

···
+// RTC FAST memory session persistence
+//
+// stores session state in RTC FAST memory (8KB on ESP32-C3) which
+// survives deep sleep but is zeroed on power-on reset. this enables
+// instant wake restoration without SD card I/O.
+//
+// the session struct is placed in .rtc_fast.persistent via link_section;
+// esp-hal's linker scripts ensure this memory is only zeroed on power-on,
+// not on deep sleep wake.
+
+use core::sync::atomic::{AtomicU32, Ordering};
+
+// magic value to validate RTC session data: "PLPS" (PuLP Session)
+const RTC_SESSION_MAGIC: u32 = 0x504C5053;
+
+// max navigation stack depth (must match app::MAX_STACK_DEPTH)
+pub const MAX_NAV_STACK: usize = 4;
+
+// max filename length for reader state
+pub const MAX_FILENAME_LEN: usize = 32;
+
+// RTC-persistent session state
+// stored in RTC FAST memory; survives deep sleep
+// all fields use fixed-size types for stable memory layout
+#[derive(Clone, Copy)]
+#[repr(C, align(4))]
+pub struct RtcSession {
+    // header (16 bytes)
+    magic: u32,      // must equal RTC_SESSION_MAGIC for valid data
+    wake_count: u32, // incremented each successful wake
+    flags: u32,      // reserved
+    _header_pad: u32,
+
+    // navigation stack (8 bytes)
+    pub nav_depth: u8,                  // stack depth (1-4)
+    pub nav_stack: [u8; MAX_NAV_STACK], // app ids: Home=0, Files=1, Reader=2, Settings=3, Upload=4
+    _nav_pad: [u8; 3],
+
+    // reader state (48 bytes)
+    pub reader_filename: [u8; MAX_FILENAME_LEN],
+    pub reader_filename_len: u8,
+    pub reader_is_epub: u8,
+    pub reader_chapter: u16,
+    pub reader_page: u16,
+    pub reader_byte_offset: u32,
+    pub reader_font_size: u8,
+    _reader_pad: [u8; 5],
+
+    // files state (8 bytes)
+    pub files_scroll: u16,
+    pub files_selected: u8,
+    pub files_total: u16,
+    _files_pad: [u8; 3],
+
+    // home state (8 bytes)
+    pub home_state: u8, // 0=Menu, 1=ShowBookmarks
+    pub home_selected: u8,
+    pub home_bm_selected: u8,
+    pub home_bm_scroll: u8,
+    _home_pad: [u8; 4],
+
+    // settings cache (16 bytes) - avoid SD reads on wake
+    pub settings_sleep_timeout: u16,
+    pub settings_ghost_clear: u8,
+    pub settings_book_font: u8,
+    pub settings_ui_font: u8,
+    pub settings_valid: u8,
+    _settings_pad: [u8; 10],
+
+    // reserved (24 bytes)
+    _reserved: [u8; 24],
+}
+
+// Compile-time size check: ensure struct fits comfortably in RTC FAST (8KB)
+// and doesn't grow unexpectedly
+const _: () = assert!(core::mem::size_of::<RtcSession>() <= 256);
+
+impl RtcSession {
+    // create zeroed session (invalid until populated)
+    pub const fn zeroed() -> Self {
+        Self {
+            magic: 0,
+            wake_count: 0,
+            flags: 0,
+            _header_pad: 0,
+
+            nav_depth: 0,
+            nav_stack: [0; MAX_NAV_STACK],
+            _nav_pad: [0; 3],
+
+            reader_filename: [0; MAX_FILENAME_LEN],
+            reader_filename_len: 0,
+            reader_is_epub: 0,
+            reader_chapter: 0,
+            reader_page: 0,
+            reader_byte_offset: 0,
+            reader_font_size: 0,
+            _reader_pad: [0; 5],
+
+            files_scroll: 0,
+            files_selected: 0,
+            files_total: 0,
+            _files_pad: [0; 3],
+
+            home_state: 0,
+            home_selected: 0,
+            home_bm_selected: 0,
+            home_bm_scroll: 0,
+            _home_pad: [0; 4],
+
+            settings_sleep_timeout: 0,
+            settings_ghost_clear: 0,
+            settings_book_font: 0,
+            settings_ui_font: 0,
+            settings_valid: 0,
+            _settings_pad: [0; 10],
+
+            _reserved: [0; 24],
+        }
+    }
+
+    #[inline]
+    pub fn is_valid(&self) -> bool {
+        self.magic == RTC_SESSION_MAGIC
+    }
+
+    #[inline]
+    pub fn mark_valid(&mut self) {
+        self.magic = RTC_SESSION_MAGIC;
+    }
+
+    pub fn clear(&mut self) {
+        self.magic = 0;
+    }
+
+    pub fn increment_wake_count(&mut self) {
+        self.wake_count = self.wake_count.wrapping_add(1);
+    }
+
+    #[inline]
+    pub fn wake_count(&self) -> u32 {
+        self.wake_count
+    }
+}
+
+// RTC FAST persistent storage
+//
+// This static is placed in .rtc_fast.persistent section which:
+// - Survives deep sleep (RTC domain stays powered)
+// - Is zeroed only on power-on reset (not deep sleep wake)
+// - Requires RTC FAST memory to remain powered during sleep
+//
+// Safety: Access is through save()/load() which use volatile operations
+// and are only called from single-threaded boot/sleep contexts.
+#[unsafe(link_section = ".rtc_fast.persistent")]
+static mut RTC_SESSION: RtcSession = RtcSession::zeroed();
+
+// Atomic flag to track if we've detected a valid session this boot
+// (prevents re-reading stale data after initial restore)
+static SESSION_CONSUMED: AtomicU32 = AtomicU32::new(0);
+
+// check if RTC session data is valid and available for restore
+// returns true only once per boot (subsequent calls return false)
+// must be called from main thread during boot, before async tasks
+pub fn is_valid_session() -> bool {
+    // Only allow one restore per boot
+    if SESSION_CONSUMED.load(Ordering::Relaxed) != 0 {
+        return false;
+    }
+
+    // Safety: single-threaded boot context, volatile read via raw pointer
+    let valid = unsafe {
+        let ptr = core::ptr::addr_of!(RTC_SESSION);
+        core::ptr::read_volatile(core::ptr::addr_of!((*ptr).magic))
+    } == RTC_SESSION_MAGIC;
+
+    if valid {
+        SESSION_CONSUMED.store(1, Ordering::Relaxed);
+    }
+
+    valid
+}
+
+// load session data (caller should check is_valid_session() first)
+// must be called from main thread during boot
+pub fn load() -> RtcSession {
+    // Safety: single-threaded context, volatile read via raw pointer
+    unsafe {
+        let ptr = core::ptr::addr_of!(RTC_SESSION);
+        core::ptr::read_volatile(ptr)
+    }
+}
+
+// save session data before entering deep sleep
+// must be called from main thread before sleep, after tasks stopped
+pub fn save(session: &RtcSession) {
+    unsafe {
+        let ptr = core::ptr::addr_of_mut!(RTC_SESSION);
+        // Copy all fields
+        core::ptr::write_volatile(ptr, *session);
+        // Ensure magic is set (caller may have forgotten)
+        core::ptr::write_volatile(core::ptr::addr_of_mut!((*ptr).magic), RTC_SESSION_MAGIC);
+    }
+}
+
+// clear RTC session data
+pub fn clear() {
+    unsafe {
+        let ptr = core::ptr::addr_of_mut!(RTC_SESSION);
+        core::ptr::write_volatile(core::ptr::addr_of_mut!((*ptr).magic), 0);
+    }
+}
+
+// get wake count for debugging (doesn't consume session)
+pub fn wake_count() -> u32 {
+    unsafe {
+        let ptr = core::ptr::addr_of!(RTC_SESSION);
+        core::ptr::read_volatile(core::ptr::addr_of!((*ptr).wake_count))
+    }
+}

kernel/src/kernel/scheduler.rs

···
 
 use super::timing;
 
+#[inline]
+fn is_power_event(ev: Event) -> bool {
+    matches!(ev, Event::Press(Button::Power) | Event::Release(Button::Power))
+}
+
 impl super::Kernel {
     // render boot console to EPD; call before boot() to show
     // hardware init progress in the built-in mono font
···
     }
 
     // one-time boot: load caches, settings, render the home screen
+    // if waking from deep sleep with valid RTC session, restore it
     pub async fn boot<A: AppLayer>(&mut self, app_mgr: &mut A) {
+        use super::rtc_session;
+
         self.bm_cache.ensure_loaded(&self.sd);
 
+        // check for valid RTC session before loading settings
+        // (session may contain cached settings to skip SD reads)
+        let has_rtc_session = rtc_session::is_valid_session();
+        let rtc_session_data = if has_rtc_session {
+            let session = rtc_session::load();
+            info!(
+                "boot: RTC session valid (wake count {})",
+                session.wake_count()
+            );
+            Some(session)
+        } else {
+            info!("boot: no RTC session (power-on or first boot)");
+            None
+        };
+
+        // load settings - may use cached values from RTC session
         {
             let mut handle = self.handle();
             app_mgr.load_eager_settings(&mut handle);
···
 
         tasks::set_idle_timeout(app_mgr.system_settings().sleep_timeout);
         self.log_stats();
-        app_mgr.enter_initial(&mut self.handle());
+
+        // try to restore session from RTC memory
+        let restored = if let Some(session) = rtc_session_data {
+            app_mgr.apply_session(&session, &mut self.handle())
+        } else {
+            false
+        };
+
+        if !restored {
+            app_mgr.enter_initial(&mut self.handle());
+        }
 
         {
             let draw = |s: &mut StripBuffer| app_mgr.draw(s);
···
             };
 
             if let Some(ev) = hw_event {
+                if matches!(ev, Event::LongPress(_)) {
+                    info!("scheduler: received {:?}", ev);
+                }
                 if self.handle_input(ev, app_mgr) {
-                    self.enter_sleep("power held").await;
+                    self.sleep_with_session(app_mgr, "power held").await;
                     continue;
                 }
             }
···
 
             if let Some(ev) = bg_input {
                 if self.handle_input(ev, app_mgr) {
-                    self.enter_sleep("power held").await;
+                    self.sleep_with_session(app_mgr, "power held").await;
                     continue;
                 }
 
···
             }
 
             if self.poll_housekeeping(app_mgr) {
-                self.enter_sleep("idle timeout").await;
+                self.sleep_with_session(app_mgr, "idle timeout").await;
                 continue;
             }
 
             if app_mgr.ctx_mut().render_ready() {
                 let redraw = app_mgr.take_redraw();
-                self.render(app_mgr, redraw).await;
+                if self.render(app_mgr, redraw).await {
+                    self.sleep_with_session(app_mgr, "power held").await;
+                    continue;
+                }
             }
         }
     }
···
         let _ = tasks::IDLE_SLEEP_DUE.try_take();
 
         if hw_event == Event::LongPress(Button::Power) {
+            info!("handle_input: LongPress(Power) detected, triggering sleep");
             return true;
         }
 
         let suppressed_before = app_mgr.suppress_deferred_input();
         let transition = app_mgr.dispatch_event(hw_event, &mut *self.bm_cache);
+        let power = is_power_event(hw_event);
 
         if transition != Transition::None {
             app_mgr.apply_transition(transition, &mut self.handle());
-            tasks::request_hold_reset();
+            // don't consume hold for power button - we still want LongPress for sleep
+            if !power {
+                tasks::request_hold_reset();
+            }
         } else if app_mgr.suppress_deferred_input() != suppressed_before {
-            tasks::request_hold_reset();
+            // quick menu opened/closed; don't consume hold for power button
+            if !power {
+                tasks::request_hold_reset();
+            }
         }
 
         false
···
 
     // partial refreshes use DU waveform (~400 ms); after ghost_clear_every
     // partials, a full GC refresh (~1.6 s) clears ghosting
-    async fn render<A: AppLayer>(&mut self, app_mgr: &mut A, redraw: Redraw) {
+    //
+    // returns true if power-long-press arrived during the waveform and
+    // the caller should enter sleep
+    async fn render<A: AppLayer>(&mut self, app_mgr: &mut A, redraw: Redraw) -> bool {
+        let mut sleep_requested = false;
+
         'render: {
             if let Redraw::Partial(r) = redraw {
                 let ghost_clear_every = app_mgr.ghost_clear_every();
···
 
                     if let Some(rs) = rs {
                         self.epd.partial_start_du(&rs);
-                        let deferred = self.busy_wait_with_background(app_mgr).await;
+                        let (deferred, sleep) = self.busy_wait_with_background(app_mgr).await;
+                        sleep_requested = sleep;
 
                         if app_mgr.has_redraw() {
                             // content changed mid-DU; leave RED stale
···
 
                 self.epd.start_full_update();
 
-                let deferred = self.busy_wait_with_background(app_mgr).await;
+                let (deferred, sleep) = self.busy_wait_with_background(app_mgr).await;
+                sleep_requested = sleep;
 
                 self.epd.finish_full_update();
                 self.partial_refreshes = 0;
···
                 }
             }
         } // 'render
+
+        sleep_requested
     }
 
     // collect input and run background work while EPD is busy refreshing
···
     //
     // first non-None transition wins; hold reset prevents the held
     // button from re-firing LongPress/Repeat for the waveform
+    //
+    // returns (deferred_transition, sleep_requested) so the caller
+    // can enter sleep after the EPD finishes if power-long-press
+    // arrived during the waveform
     async fn busy_wait_with_background<A: AppLayer>(
         &mut self,
         app_mgr: &mut A,
-    ) -> Option<Transition<A::Id>> {
+    ) -> (Option<Transition<A::Id>>, bool) {
         let mut deferred: Option<Transition<A::Id>> = None;
+        let mut sleep_requested = false;
 
         loop {
             if !self.epd.is_busy() {
···
             if let Some(hw_event) = ev {
                 let _ = tasks::IDLE_SLEEP_DUE.try_take();
 
+                // power long-press triggers sleep after EPD finishes
+                if hw_event == Event::LongPress(Button::Power) {
+                    info!("busy_wait: LongPress(Power) during waveform, will sleep after");
+                    sleep_requested = true;
+                    continue;
+                }
+
                 let suppressed_before = app_mgr.suppress_deferred_input();
                 if !suppressed_before {
                     let t = app_mgr.dispatch_event(hw_event, &mut *self.bm_cache);
+                    let power = is_power_event(hw_event);
+
                     if t != Transition::None && deferred.is_none() {
                         deferred = Some(t);
-                        tasks::request_hold_reset();
+                        if !power {
+                            tasks::request_hold_reset();
+                        }
                     } else if app_mgr.suppress_deferred_input() != suppressed_before {
-                        tasks::request_hold_reset();
+                        if !power {
+                            tasks::request_hold_reset();
+                        }
                     }
                 }
             }
···
             self.poll_housekeeping_waveform(app_mgr);
         }
 
-        deferred
+        (deferred, sleep_requested)
+    }
+
+    // save session to RTC memory and enter deep sleep; call this
+    // instead of enter_sleep directly to ensure session state is persisted
+    async fn sleep_with_session<A: AppLayer>(&mut self, app_mgr: &mut A, reason: &str) {
+        use super::rtc_session;
+
+        // collect session state from app layer
+        let mut session = rtc_session::RtcSession::zeroed();
+        app_mgr.collect_session(&mut session);
+
+        // increment wake count for debugging
+        session.increment_wake_count();
+
+        // save to RTC memory (will be valid on next wake)
+        rtc_session::save(&session);
+        info!("session: saved to RTC memory");
+
+        self.enter_sleep(reason).await;
     }
 
     // flush bookmarks, render sleep screen, enter MCU deep sleep;
     // on real hardware this never returns (wake = full MCU reset)
-    pub async fn enter_sleep(&mut self, reason: &str) {
+    //
+    // uses a custom sleep config that keeps RTC FAST memory powered
+    // so session state survives the sleep cycle (~1-2µA extra)
+    async fn enter_sleep(&mut self, reason: &str) {
         use embedded_graphics::mono_font::MonoTextStyle;
         use embedded_graphics::mono_font::ascii::FONT_9X18;
         use embedded_graphics::pixelcolor::BinaryColor;
···
         use embedded_graphics::text::Text;
         use esp_hal::gpio::RtcPinWithResistors;
         use esp_hal::rtc_cntl::Rtc;
-        use esp_hal::rtc_cntl::sleep::{RtcioWakeupSource, WakeupLevel};
+        use esp_hal::rtc_cntl::sleep::{RtcSleepConfig, RtcioWakeupSource, WakeupLevel};
 
         info!("{}: entering sleep...", reason);
 
···
             &mut [(&mut gpio3, WakeupLevel::Low)];
         let rtcio = RtcioWakeupSource::new(wakeup_pins);
 
-        info!("mcu: entering deep sleep (power button to wake)");
-        rtc.sleep_deep(&[&rtcio]);
+        // custom sleep config: keep RTC FAST memory powered for session
+        // persistence. this adds ~1-2µA to deep sleep current but enables
+        // instant wake restoration without SD card I/O.
+        let mut sleep_config = RtcSleepConfig::deep();
+        sleep_config.set_rtc_fastmem_pd_en(false); // keep RTC FAST powered
 
-        // deep sleep resets the MCU; backstop if sleep_deep returns
+        info!("mcu: entering deep sleep (power button to wake, RTC FAST retained)");
+        rtc.sleep(&sleep_config, &[&rtcio]);
+
+        // deep sleep resets the MCU; backstop if sleep returns
         #[allow(unreachable_code)]
         loop {
             core::hint::spin_loop();

kernel/src/kernel/timing.rs

···
 // timing constants for the kernel scheduler and tasks
 //
-// timing values that control polling intervals, debouncing, 
+// timing values that control polling intervals, debouncing,
 // coalescing, and housekeeping. some of these may
-// become runtime-configurable settings in the future, idk
+// may become runtime-configurable in the future
 
 // main scheduler tick interval (ms)
 // controls how often the event loop wakes to check for work
···
 // bookmark flush interval (seconds)
 pub const BOOKMARK_FLUSH_INTERVAL_SECS: u64 = 30;
 
-// dookmark flush stagger delay (seconds)
-// dffset from SD check to avoid simultaneous SD operations
+// bookmark flush stagger delay (seconds)
+// offset from sd check to avoid simultaneous sd operations
 pub const BOOKMARK_FLUSH_STAGGER_SECS: u64 = 2;
 
 // initial housekeeping delay (seconds)

kernel/src/lib.rs

···
 pub mod error;
 pub mod kernel;
 pub mod ui;
+pub mod util;
 
 // re-export core error types at crate root
 pub use error::{Error, ErrorKind, Result, ResultExt};

kernel/src/ui/layout.rs

···
-// common layout constants for UI rendering
+// shared layout constants for UI rendering
 //
-// centralizes magic layout values used across apps and widgets.
-// some of these may become runtime-configurable settings in the
-// future (e.g., margin sizes based on font size preferences).
+// only constants used by 2+ apps belong here.
+// single-use layout values should be defined locally.
 
 use super::statusbar::BAR_HEIGHT;
-use crate::board::{SCREEN_H, SCREEN_W};
-
-// ── Content area ────────────────────────────────────────────────
+use crate::board::SCREEN_W;
 
-/// Top of the content area (below status bar).
 pub const CONTENT_TOP: u16 = BAR_HEIGHT;
-
-/// Height of the content area (screen minus status bar).
-pub const CONTENT_H: u16 = SCREEN_H - BAR_HEIGHT;
-
-// ── Standard spacing ────────────────────────────────────────────
-
-/// Standard margin for content edges (left/right).
-pub const STANDARD_MARGIN: u16 = 8;
-
-/// Large margin for content edges (used in some UIs).
 pub const LARGE_MARGIN: u16 = 16;
-
-/// Standard gap between items.
-pub const STANDARD_GAP: u16 = 4;
-
-/// Larger gap between sections or after headers.
 pub const SECTION_GAP: u16 = 8;
-
-// ── Title/header layout ─────────────────────────────────────────
-
-/// Y offset for titles below CONTENT_TOP.
 pub const TITLE_Y_OFFSET: u16 = 4;
-
-/// Standard title Y position.
 pub const TITLE_Y: u16 = CONTENT_TOP + TITLE_Y_OFFSET;
-
-/// Full-width for content spanning most of the screen.
-/// Used for headers and wide content areas.
-pub const FULL_CONTENT_W: u16 = SCREEN_W - 2 * LARGE_MARGIN; // 448
-
-/// Width for header/title regions (leaves room for status on right).
+pub const FULL_CONTENT_W: u16 = SCREEN_W - 2 * LARGE_MARGIN;
 pub const HEADER_W: u16 = 300;
-
-/// Width for status regions (battery, page number, etc.).
-pub const STATUS_W: u16 = 144;
-
-/// X position for right-aligned status in header.
-pub const STATUS_X: u16 = SCREEN_W - LARGE_MARGIN - STATUS_W; // 320
-
-// ── List/menu layout ────────────────────────────────────────────
-
-/// Standard row height for list items.
-pub const LIST_ROW_H: u16 = 52;
-
-/// Gap between list rows.
-pub const LIST_ROW_GAP: u16 = 4;
-
-/// Combined row stride (row + gap).
-pub const LIST_ROW_STRIDE: u16 = LIST_ROW_H + LIST_ROW_GAP;
-
-/// Menu/settings row height (slightly smaller than list).
-pub const MENU_ROW_H: u16 = 40;
-
-/// Gap between menu rows.
-pub const MENU_ROW_GAP: u16 = 6;
-
-/// Combined menu row stride.
-pub const MENU_ROW_STRIDE: u16 = MENU_ROW_H + MENU_ROW_GAP;
-
-// ── Progress and overlays ───────────────────────────────────────
-
-/// Height of progress bars.
-pub const PROGRESS_H: u16 = 2;
-
-/// Position overlay dimensions (for page/chapter display).
-pub const POSITION_OVERLAY_W: u16 = 280;
-pub const POSITION_OVERLAY_H: u16 = 40;
-
-// ── Loading indicator ───────────────────────────────────────────
-
-/// Default height for loading indicator region.
-pub const LOADING_H: u16 = 24;
-
-// ── Footer layout ───────────────────────────────────────────────
-
-/// Standard footer height from bottom.
-pub const FOOTER_MARGIN: u16 = 60;
-
-/// Footer Y position.
-pub const FOOTER_Y: u16 = SCREEN_H - FOOTER_MARGIN;

kernel/src/ui/mod.rs

···
 mod widget;
 
 pub use layout::{
-    CONTENT_H, CONTENT_TOP, FOOTER_MARGIN, FOOTER_Y, FULL_CONTENT_W, HEADER_W, LARGE_MARGIN,
-    LIST_ROW_GAP, LIST_ROW_H, LIST_ROW_STRIDE, LOADING_H, MENU_ROW_GAP, MENU_ROW_H,
-    MENU_ROW_STRIDE, POSITION_OVERLAY_H, POSITION_OVERLAY_W, PROGRESS_H, SECTION_GAP, STANDARD_GAP,
-    STANDARD_MARGIN, STATUS_W, STATUS_X, TITLE_Y, TITLE_Y_OFFSET,
+    CONTENT_TOP, FULL_CONTENT_W, HEADER_W, LARGE_MARGIN, SECTION_GAP, TITLE_Y, TITLE_Y_OFFSET,
 };
 pub use stack_fmt::{stack_fmt, StackFmt};
 pub use statusbar::{free_stack_bytes, paint_stack, stack_high_water_mark, BAR_HEIGHT};

kernel/src/util/mod.rs

···
+// utility modules: small, reusable components without hardware dependencies
+
+mod utf8;
+
+pub use utf8::{Utf8Iter, decode_utf8_char};

kernel/src/util/utf8.rs

···
+// UTF-8 decoding utilities for no_std environments
+//
+// provides both iterator-based and single-char decoding interfaces
+// for processing UTF-8 byte slices without std::str
+
+// decode one UTF-8 character at buf[pos]
+// returns (char, byte_length); malformed sequences yield '\u{FFFD}'
+// panics if pos >= buf.len()
+#[inline]
+pub fn decode_utf8_char(buf: &[u8], pos: usize) -> (char, usize) {
+    let b0 = buf[pos];
+
+    // ASCII fast path
+    if b0 < 0x80 {
+        return (b0 as char, 1);
+    }
+
+    // Determine expected sequence length from lead byte
+    let (mut cp, expected) = if b0 < 0xC0 {
+        // Stray continuation byte
+        return ('\u{FFFD}', 1);
+    } else if b0 < 0xE0 {
+        ((b0 as u32) & 0x1F, 2)
+    } else if b0 < 0xF0 {
+        ((b0 as u32) & 0x0F, 3)
+    } else if b0 < 0xF8 {
+        ((b0 as u32) & 0x07, 4)
+    } else {
+        // Invalid lead byte
+        return ('\u{FFFD}', 1);
+    };
+
+    // Check if we have enough bytes
+    let len = buf.len();
+    if pos + expected > len {
+        return ('\u{FFFD}', len - pos);
+    }
+
+    // Decode continuation bytes
+    for i in 1..expected {
+        let cont = buf[pos + i];
+        if cont & 0xC0 != 0x80 {
+            // Invalid continuation byte
+            return ('\u{FFFD}', i);
+        }
+        cp = (cp << 6) | (cont as u32 & 0x3F);
+    }
+
+    let ch = char::from_u32(cp).unwrap_or('\u{FFFD}');
+    (ch, expected)
+}
+
+// iterator over UTF-8 characters in a byte slice
+// invalid sequences yield U+FFFD
+pub struct Utf8Iter<'a> {
+    data: &'a [u8],
+    pos: usize,
+}
+
+impl<'a> Utf8Iter<'a> {
+    #[inline]
+    pub fn new(data: &'a [u8]) -> Self {
+        Self { data, pos: 0 }
+    }
+
+    #[inline]
+    pub fn position(&self) -> usize {
+        self.pos
+    }
+
+    #[inline]
+    pub fn remaining(&self) -> &'a [u8] {
+        &self.data[self.pos..]
+    }
+}
+
+impl Iterator for Utf8Iter<'_> {
+    type Item = char;
+
+    fn next(&mut self) -> Option<char> {
+        if self.pos >= self.data.len() {
+            return None;
+        }
+
+        let (ch, len) = decode_utf8_char(self.data, self.pos);
+        self.pos += len;
+        Some(ch)
+    }
+}

src/apps/files.rs

···
 // paginated file browser for SD card root directory
 // background title scanner resolves EPUB titles from OPF metadata
 
-extern crate alloc;
-
 use alloc::vec::Vec;
 use core::fmt::Write as _;
 
···
 use crate::fonts;
 use crate::kernel::KernelHandle;
 use crate::ui::{
-    Alignment, BitmapDynLabel, BitmapLabel, CONTENT_TOP, FULL_CONTENT_W, HEADER_W,
-    LARGE_MARGIN, LIST_ROW_GAP, LIST_ROW_H, Region, SECTION_GAP, STATUS_W, STATUS_X,
-    TITLE_Y_OFFSET,
+    Alignment, BitmapDynLabel, BitmapLabel, CONTENT_TOP, FULL_CONTENT_W, HEADER_W, LARGE_MARGIN,
+    Region, SECTION_GAP, TITLE_Y_OFFSET,
 };
 use smol_epub::epub::{self, EpubMeta, EpubSpine};
 use smol_epub::zip::ZipIndex;
···
 
 const TITLE_Y: u16 = CONTENT_TOP + TITLE_Y_OFFSET;
 
+const STATUS_W: u16 = 144;
+const STATUS_X: u16 = SCREEN_W - LARGE_MARGIN - STATUS_W;
 const FILES_STATUS_Y: u16 = TITLE_Y;
 const FILES_STATUS_H: u16 = 28;
 const STATUS_REGION: Region = Region::new(STATUS_X, FILES_STATUS_Y, STATUS_W, FILES_STATUS_H);
 
-const ROW_H: u16 = LIST_ROW_H;
-const ROW_GAP: u16 = LIST_ROW_GAP;
+const ROW_H: u16 = 52;
+const ROW_GAP: u16 = 4;
 
 const HEADER_LIST_GAP: u16 = SECTION_GAP;
 
···
     pub fn set_ui_font_size(&mut self, idx: u8) {
         self.ui_fonts = fonts::UiFonts::for_size(idx);
         self.list_y = TITLE_Y + self.ui_fonts.heading.line_height + HEADER_LIST_GAP;
+    }
+
+    // Session state accessors for RTC persistence
+    #[inline]
+    pub fn scroll(&self) -> usize {
+        self.scroll
+    }
+
+    #[inline]
+    pub fn selected(&self) -> usize {
+        self.selected
+    }
+
+    #[inline]
+    pub fn total(&self) -> usize {
+        self.total
+    }
+
+    /// Restore files state from RTC session data
+    pub fn restore_state(&mut self, scroll: usize, selected: usize, total: usize) {
+        self.scroll = scroll;
+        self.selected = selected;
+        self.total = total;
+        self.needs_load = true; // trigger page reload
+        log::info!(
+            "files: restore_state scroll={} selected={} total={}",
+            scroll,
+            selected,
+            total
+        );
     }
 
     fn selected_entry(&self) -> Option<&DirEntry> {

src/apps/home.rs

···
 const BM_HEADER_GAP: u16 = 4;
 const BM_BOTTOM: u16 = SCREEN_H - BUTTON_BAR_H;
 
+const CONTENT_REGION: Region = Region::new(0, CONTENT_TOP, SCREEN_W, SCREEN_H - CONTENT_TOP);
+
 fn compute_item_regions(heading_line_h: u16) -> [Region; MAX_ITEMS] {
     let item_y = CONTENT_TOP + 8 + heading_line_h + TITLE_ITEM_GAP;
     [
···
     ]
 }
 
-#[derive(Clone, Copy, PartialEq)]
+#[derive(Clone, Copy, PartialEq, Debug)]
 enum HomeState {
     Menu,
     ShowBookmarks,
···
         self.item_regions = compute_item_regions(self.ui_fonts.heading.line_height);
     }
 
+    // Session state accessors for RTC persistence
+    #[inline]
+    pub fn state_id(&self) -> u8 {
+        match self.state {
+            HomeState::Menu => 0,
+            HomeState::ShowBookmarks => 1,
+        }
+    }
+
+    #[inline]
+    pub fn selected(&self) -> usize {
+        self.selected
+    }
+
+    #[inline]
+    pub fn bm_selected(&self) -> usize {
+        self.bm_selected
+    }
+
+    #[inline]
+    pub fn bm_scroll(&self) -> usize {
+        self.bm_scroll
+    }
+
+    /// Restore home state from RTC session data
+    pub fn restore_state(
+        &mut self,
+        state_id: u8,
+        selected: usize,
+        bm_selected: usize,
+        bm_scroll: usize,
+    ) {
+        self.state = match state_id {
+            1 => HomeState::ShowBookmarks,
+            _ => HomeState::Menu,
+        };
+        self.selected = selected;
+        self.bm_selected = bm_selected;
+        self.bm_scroll = bm_scroll;
+        if self.state == HomeState::ShowBookmarks {
+            self.needs_load_bookmarks = true;
+        }
+        log::info!(
+            "home: restore_state state={:?} selected={}",
+            self.state,
+            selected
+        );
+    }
+
     pub fn load_recent(&mut self, k: &mut KernelHandle<'_>) {
         let mut buf = [0u8; 32];
         match k.read_app_data_start(RECENT_FILE, &mut buf) {
···
         ctx.clear_message();
         self.state = HomeState::Menu;
         self.selected = 0;
-        ctx.mark_dirty(Region::new(
-            0,
-            CONTENT_TOP,
-            SCREEN_W,
-            SCREEN_H - CONTENT_TOP,
-        ));
+        ctx.mark_dirty(CONTENT_REGION);
     }
 
     fn on_resume(&mut self, ctx: &mut AppContext, _k: &mut KernelHandle<'_>) {
         self.state = HomeState::Menu;
         self.selected = 0;
         self.needs_load_recent = true;
-        ctx.mark_dirty(Region::new(
-            0,
-            CONTENT_TOP,
-            SCREEN_W,
-            SCREEN_H - CONTENT_TOP,
-        ));
+        ctx.mark_dirty(CONTENT_REGION);
     }
 
     async fn background(&mut self, ctx: &mut AppContext, k: &mut KernelHandle<'_>) {

src/apps/manager.rs

···
         self.home.on_enter(&mut self.launcher.ctx, k);
     }
 
+    // collect session state to RTC memory struct before sleep
+    pub fn collect_session(&self, session: &mut crate::kernel::rtc_session::RtcSession) {
+        use crate::kernel::rtc_session::MAX_NAV_STACK;
+
+        // save navigation stack
+        session.nav_depth = self.launcher.depth() as u8;
+        for i in 0..MAX_NAV_STACK {
+            session.nav_stack[i] = if i < self.launcher.depth() {
+                self.launcher.stack_at(i) as u8
+            } else {
+                0
+            };
+        }
+
+        // save reader state
+        session.reader_filename_len = self.reader.filename_len() as u8;
+        let len = session.reader_filename_len as usize;
+        session.reader_filename[..len].copy_from_slice(self.reader.filename_bytes());
+        session.reader_is_epub = self.reader.is_epub() as u8;
+        session.reader_chapter = self.reader.chapter();
+        session.reader_page = self.reader.page() as u16;
+        session.reader_byte_offset = self.reader.byte_offset();
+        session.reader_font_size = self.reader.font_size_idx();
+
+        // save files state
+        session.files_scroll = self.files.scroll() as u16;
+        session.files_selected = self.files.selected() as u8;
+        session.files_total = self.files.total() as u16;
+
+        // save home state
+        session.home_state = self.home.state_id();
+        session.home_selected = self.home.selected() as u8;
+        session.home_bm_selected = self.home.bm_selected() as u8;
+        session.home_bm_scroll = self.home.bm_scroll() as u8;
+
+        // save settings cache
+        let ss = self.settings.system_settings();
+        session.settings_sleep_timeout = ss.sleep_timeout;
+        session.settings_ghost_clear = ss.ghost_clear_every;
+        session.settings_book_font = ss.book_font_size_idx;
+        session.settings_ui_font = ss.ui_font_size_idx;
+        session.settings_valid = 1;
+
+        log::info!(
+            "session: collected nav_depth={} active={:?}",
+            session.nav_depth,
+            self.launcher.active()
+        );
+    }
+
+    // restore session from RTC memory; returns true if successful
+    pub fn apply_session(
+        &mut self,
+        session: &crate::kernel::rtc_session::RtcSession,
+        k: &mut KernelHandle<'_>,
+    ) -> bool {
+        // validate session data
+        if session.nav_depth == 0 || session.nav_depth > 4 {
+            log::warn!("session: invalid nav_depth {}", session.nav_depth);
+            return false;
+        }
+
+        // restore navigation stack
+        self.launcher.restore_stack(
+            session.nav_depth as usize,
+            &session.nav_stack,
+            |id| match id {
+                0 => AppId::Home,
+                1 => AppId::Files,
+                2 => AppId::Reader,
+                3 => AppId::Settings,
+                _ => AppId::Home,
+            },
+        );
+
+        log::info!(
+            "session: restored nav stack depth={} active={:?}",
+            session.nav_depth,
+            self.launcher.active()
+        );
+
+        // restore home state (always in stack)
+        self.home.restore_state(
+            session.home_state,
+            session.home_selected as usize,
+            session.home_bm_selected as usize,
+            session.home_bm_scroll as usize,
+        );
+
+        // restore files state if in stack
+        if self.launcher.contains(AppId::Files) {
+            self.files.restore_state(
+                session.files_scroll as usize,
+                session.files_selected as usize,
+                session.files_total as usize,
+            );
+        }
+
+        // restore reader state if active or in stack
+        if self.launcher.active() == AppId::Reader || self.launcher.contains(AppId::Reader) {
+            let filename = &session.reader_filename[..session.reader_filename_len as usize];
+            self.reader.restore_state(
+                filename,
+                session.reader_is_epub != 0,
+                session.reader_chapter,
+                session.reader_page as usize,
+                session.reader_byte_offset,
+                session.reader_font_size,
+            );
+        }
+
+        // propagate fonts before entering apps
+        self.propagate_fonts();
+
+        // enter apps in stack order (bottom to top)
+        // Home is always at bottom
+        self.home.on_enter(&mut self.launcher.ctx, k);
+
+        // for apps above Home, call on_suspend for suspended ones, on_enter for active
+        let depth = self.launcher.depth();
+        for i in 1..depth {
+            let app_id = self.launcher.stack_at(i);
+            let is_active = i == depth - 1;
+
+            match app_id {
+                AppId::Files => {
+                    if is_active {
+                        self.files.on_enter(&mut self.launcher.ctx, k);
+                    } else {
+                        // Files was pushed then another app pushed on top
+                        self.files.on_enter(&mut self.launcher.ctx, k);
+                        self.files.on_suspend();
+                    }
+                }
+                AppId::Reader => {
+                    if is_active {
+                        // set message for reader to know filename
+                        let filename =
+                            &session.reader_filename[..session.reader_filename_len as usize];
+                        self.launcher.ctx.set_message(filename);
+                        self.reader.on_enter(&mut self.launcher.ctx, k);
+                    }
+                }
+                AppId::Settings => {
+                    if is_active {
+                        self.settings.on_enter(&mut self.launcher.ctx, k);
+                    }
+                }
+                _ => {}
+            }
+
+            // suspend apps that aren't the top
+            if !is_active {
+                match app_id {
+                    AppId::Home => self.home.on_suspend(),
+                    AppId::Files => {} // already handled above
+                    _ => {}
+                }
+            }
+        }
+
+        // mark full redraw needed
+        self.launcher.ctx.request_full_redraw();
+
+        true
+    }
+
     // power-button long-press must be intercepted by the scheduler
     // before calling this method
     pub fn dispatch_event(&mut self, hw_event: Event, bm_cache: &mut BookmarkCache) -> Transition {
···
 
     fn enter_initial(&mut self, k: &mut KernelHandle<'_>) {
         AppManager::enter_initial(self, k);
+    }
+
+    fn collect_session(&self, session: &mut crate::kernel::rtc_session::RtcSession) {
+        AppManager::collect_session(self, session);
+    }
+
+    fn apply_session(
+        &mut self,
+        session: &crate::kernel::rtc_session::RtcSession,
+        k: &mut KernelHandle<'_>,
+    ) -> bool {
+        AppManager::apply_session(self, session, k)
     }
 
     fn needs_special_mode(&self) -> bool {

src/apps/reader/images.rs

···
 // (small images); both epub_find_and_dispatch_image (background scan)
 // and dispatch_one_image_in_chapter (nearby prefetch) call through it
 
-extern crate alloc;
-
 use alloc::vec::Vec;
 use core::cell::RefCell;
 
-use smol_epub::DecodedImage;
 use smol_epub::cache;
 use smol_epub::epub;
 use smol_epub::html_strip::{IMG_REF, MARKER};
 use smol_epub::zip::{self, ZipIndex};
+use smol_epub::DecodedImage;
 
 use crate::error::{Error, ErrorKind};
-use crate::kernel::KernelHandle;
 use crate::kernel::work_queue;
+use crate::kernel::KernelHandle;
 
 use super::{
-    IMAGE_DISPLAY_H, NO_PREFETCH, PAGE_BUF, PRECACHE_IMG_MAX, ReaderApp, TEXT_AREA_H, TEXT_W,
+    ReaderApp, IMAGE_DISPLAY_H, NO_PREFETCH, PAGE_BUF, PRECACHE_IMG_MAX, TEXT_AREA_H, TEXT_W,
 };
 
 // result of scanning a chapter for the next uncached image
···
         ch: usize,
         start_offset: usize,
     ) -> crate::error::Result<ScanResult> {
-        if ch >= cache::MAX_CACHE_CHAPTERS || !self.epub.ch_cached[ch] {
+        if ch >= self.epub.spine.len()
+            || ch >= cache::MAX_CACHE_CHAPTERS
+            || !self.epub.ch_cached[ch]
+        {
             return Ok(ScanResult::NoneFound);
         }
         let ch_size = self.epub.chapter_sizes[ch] as usize;

src/apps/reader/mod.rs

···
 mod images;
 mod paging;
 
-extern crate alloc;
-
-use paging::decode_utf8_char;
+pub use pulp_kernel::util::decode_utf8_char;
 
 use crate::apps::PendingSetting;
 use crate::fonts::bitmap::{self, BitmapFont};
···
 use crate::kernel::QuickAction;
 use crate::kernel::bookmarks;
 use crate::kernel::work_queue;
-use crate::ui::{
-    Alignment, CONTENT_TOP, HEADER_W, LOADING_H, POSITION_OVERLAY_H, POSITION_OVERLAY_W,
-    PROGRESS_H, Region, STANDARD_MARGIN, StackFmt, TITLE_Y_OFFSET,
-};
+use crate::ui::{Alignment, CONTENT_TOP, HEADER_W, Region, StackFmt, TITLE_Y_OFFSET};
 use smol_epub::DecodedImage;
 use smol_epub::cache;
 use smol_epub::epub::{self, EpubMeta, EpubSpine, EpubToc, TocSource};
···
 };
 use smol_epub::zip::{self, ZipIndex};
 
-pub(super) const MARGIN: u16 = STANDARD_MARGIN;
+pub(super) const MARGIN: u16 = 8;
 
 pub(super) const HEADER_Y: u16 = CONTENT_TOP + TITLE_Y_OFFSET - 2; // slightly tighter
 pub(super) const HEADER_H: u16 = 16;
···
 // images > this size are decoded on main loop via streaming SD reads
 pub(super) const PRECACHE_IMG_MAX: u32 = 30 * 1024;
 
-pub(super) const READER_PROGRESS_H: u16 = PROGRESS_H;
+pub(super) const READER_PROGRESS_H: u16 = 2;
 pub(super) const PROGRESS_Y: u16 = SCREEN_H - READER_PROGRESS_H - 1;
 pub(super) const PROGRESS_W: u16 = SCREEN_W - 2 * MARGIN;
 
+const POSITION_OVERLAY_W: u16 = 280;
+const POSITION_OVERLAY_H: u16 = 40;
 pub(super) const POSITION_OVERLAY: Region = Region::new(
     (SCREEN_W - POSITION_OVERLAY_W) / 2,
     (SCREEN_H - POSITION_OVERLAY_H) / 2,
···
 );
 
 const LOADING_W: u16 = SCREEN_W - 2 * MARGIN - 16;
+const LOADING_H: u16 = 24;
 pub(super) const LOADING_REGION: Region = Region::new(MARGIN, TEXT_Y, LOADING_W, LOADING_H);
 
 pub const QA_FONT_SIZE: u8 = 1;
···
 
 pub(super) const QA_MAX: usize = 4;
 
+// reader state machine:
+// NeedBookmark -> NeedInit -> NeedOpf -> NeedToc -> NeedCache -> NeedIndex -> NeedPage -> Ready
+// Ready <-> ShowToc (toc overlay); any state -> Error on failure
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub(super) enum State {
     NeedBookmark,
···
         ctx.set_loading(LOADING_REGION, lbuf.as_str(), pct);
     }
 
+    // transition to error state with consistent handling
+    fn enter_error(&mut self, ctx: &mut AppContext, e: Error) {
+        self.error = Some(e);
+        self.state = State::Error;
+        ctx.clear_loading();
+        ctx.mark_dirty(PAGE_REGION);
+    }
+
     // run one step of image work queue polling while suspended;
     // chapter caching is async and only runs during active background,
     // so this only handles the sync image recv states
···
         (buf, self.filename_len)
     }
 
+    // Session state accessors for RTC persistence
+    #[inline]
+    pub fn filename_len(&self) -> usize {
+        self.filename_len
+    }
+
+    #[inline]
+    pub fn filename_bytes(&self) -> &[u8] {
+        &self.filename[..self.filename_len]
+    }
+
+    #[inline]
+    pub fn is_epub(&self) -> bool {
+        self.is_epub
+    }
+
+    #[inline]
+    pub fn chapter(&self) -> u16 {
+        self.epub.chapter
+    }
+
+    #[inline]
+    pub fn page(&self) -> usize {
+        self.pg.page
+    }
+
+    #[inline]
+    pub fn byte_offset(&self) -> u32 {
+        if self.pg.page < self.pg.total_pages {
+            self.pg.offsets[self.pg.page]
+        } else {
+            0
+        }
+    }
+
+    #[inline]
+    pub fn font_size_idx(&self) -> u8 {
+        self.book_font_size_idx
+    }
+
+    /// Restore reader state from RTC session data
+    pub fn restore_state(
+        &mut self,
+        filename: &[u8],
+        is_epub: bool,
+        chapter: u16,
+        _page: usize,
+        byte_offset: u32,
+        font_size: u8,
+    ) {
+        let len = filename.len().min(32);
+        self.filename[..len].copy_from_slice(&filename[..len]);
+        self.filename_len = len;
+        self.is_epub = is_epub;
+        self.epub.chapter = chapter;
+        self.restore_offset = if byte_offset > 0 {
+            Some(byte_offset)
+        } else {
+            None
+        };
+        self.book_font_size_idx = font_size;
+
+        log::info!(
+            "reader: restore_state file={} ch={} off={}",
+            self.name(),
+            chapter,
+            byte_offset
+        );
+    }
+
     pub fn save_position(&self, bm: &mut bookmarks::BookmarkCache) {
         if self.state == State::Ready {
             bm.save(
···
                     }
                     Err(e) => {
                         log::info!("reader: epub init (zip) failed: {}", e);
-                        self.error = Some(e);
-                        self.state = State::Error;
-                        ctx.clear_loading();
-                        ctx.mark_dirty(PAGE_REGION);
+                        self.enter_error(ctx, e);
                     }
                 },
 
                 State::NeedOpf => match self.epub_init_opf(k) {
                     Ok(()) => {
+                        // clamp restored chapter to valid spine range
+                        let spine_len = self.epub.spine.len();
+                        if spine_len > 0 && self.epub.chapter as usize >= spine_len {
+                            self.epub.chapter = (spine_len - 1) as u16;
+                        }
                         self.state = State::NeedToc;
                         ctx.set_loading(LOADING_REGION, "Loading", 40);
                     }
                     Err(e) => {
                         log::info!("reader: epub init (opf) failed: {}", e);
-                        self.error = Some(e);
-                        self.state = State::Error;
-                        ctx.clear_loading();
-                        ctx.mark_dirty(PAGE_REGION);
+                        self.enter_error(ctx, e);
                     }
                 },
 
···
                             }
                             Err(e) => {
                                 log::info!("reader: cache ch{} failed: {}", ch, e);
-                                self.error = Some(e);
-                                self.state = State::Error;
-                                ctx.clear_loading();
-                                ctx.mark_dirty(PAGE_REGION);
+                                self.enter_error(ctx, e);
                             }
                         }
                     }
                     Err(e) => {
                         log::info!("reader: cache check failed: {}", e);
-                        self.error = Some(e);
-                        self.state = State::Error;
-                        ctx.clear_loading();
-                        ctx.mark_dirty(PAGE_REGION);
+                        self.enter_error(ctx, e);
                     }
                 },
 
···
                             .epub_cache_chapter_async(k, self.epub.chapter as usize)
                             .await
                         {
-                            self.error = Some(e);
-                            self.state = State::Error;
-                            ctx.clear_loading();
-                            ctx.mark_dirty(PAGE_REGION);
+                            self.enter_error(ctx, e);
                             break;
                         }
                     }
···
                                 ctx.clear_loading();
                                 ctx.mark_dirty(PAGE_REGION);
                             }
-                            Err(e) => {
-                                self.error = Some(e);
-                                self.state = State::Error;
-                                ctx.clear_loading();
-                                ctx.mark_dirty(PAGE_REGION);
-                            }
+                            Err(e) => self.enter_error(ctx, e),
                         }
                     } else {
                         self.state = State::NeedPage;
···
                             match self.load_and_prefetch(k) {
                                 Ok(()) => {}
                                 Err(e) => {
-                                    self.error = Some(e);
-                                    self.state = State::Error;
-                                    ctx.clear_loading();
-                                    ctx.mark_dirty(PAGE_REGION);
+                                    self.enter_error(ctx, e);
                                     break;
                                 }
                             }
···
                             }
                             Err(e) => {
                                 log::info!("reader: load failed: {}", e);
-                                self.error = Some(e);
-                                self.state = State::Error;
-                                ctx.clear_loading();
-                                ctx.mark_dirty(PAGE_REGION);
+                                self.enter_error(ctx, e);
                             }
                         }
                     }
···
             if filled_w > 0 {
                 Rectangle::new(
                     Point::new(MARGIN as i32, PROGRESS_Y as i32),
-                    Size::new(filled_w, PROGRESS_H as u32),
+                    Size::new(filled_w, READER_PROGRESS_H as u32),
                 )
                 .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
                 .draw(strip)

src/apps/reader/paging.rs

···
 use crate::kernel::KernelHandle;
 
 use super::{
-    IMAGE_DISPLAY_H, INDENT_PX, LINES_PER_PAGE, LineSpan, MAX_PAGES, NO_PREFETCH, PAGE_BUF,
-    ReaderApp, State, TEXT_W,
+    decode_utf8_char, LineSpan, ReaderApp, State, IMAGE_DISPLAY_H, INDENT_PX, LINES_PER_PAGE,
+    MAX_PAGES, NO_PREFETCH, PAGE_BUF, TEXT_W,
 };
 
 impl ReaderApp {
···
     }
 }
 
-// decode one utf-8 character starting at buf[pos]
-// returns (char, byte_length); malformed input yields ('\u{FFFD}', consumed)
-pub(super) fn decode_utf8_char(buf: &[u8], pos: usize) -> (char, usize) {
-    let b0 = buf[pos];
-    let (mut cp, expected) = if b0 < 0xE0 {
-        ((b0 as u32) & 0x1F, 2)
-    } else if b0 < 0xF0 {
-        ((b0 as u32) & 0x0F, 3)
-    } else {
-        ((b0 as u32) & 0x07, 4)
-    };
-    let len = buf.len();
-    if pos + expected > len {
-        return ('\u{FFFD}', len - pos);
-    }
-    for i in 1..expected {
-        let cont = buf[pos + i];
-        if cont & 0xC0 != 0x80 {
-            return ('\u{FFFD}', i);
-        }
-        cp = (cp << 6) | (cont as u32 & 0x3F);
-    }
-    let ch = char::from_u32(cp).unwrap_or('\u{FFFD}');
-    (ch, expected)
-}
+// UTF-8 decoding is provided by pulp_kernel::util::decode_utf8_char
+// (re-exported via super::decode_utf8_char)
 
 pub(super) fn trim_trailing_cr(buf: &[u8], start: usize, end: usize) -> usize {
     if end > start && buf[end - 1] == b'\r' {
···
 ) -> (usize, usize) {
     let max_l = max_lines.min(lines.len());
     let base_max_w = max_width_px;
-    let mut lc: usize = 0;
-    let mut ls: usize = 0;
-    let mut px: u32 = 0;
-    let mut sp: usize = 0;
-    let mut sp_px: u32 = 0;
+    let mut line_count: usize = 0;
+    let mut line_start: usize = 0;
+    let mut cursor_x: u32 = 0;
+    let mut last_space: usize = 0;
+    let mut cursor_at_space: u32 = 0;
 
     let mut bold = false;
     let mut italic = false;
···
 
     macro_rules! emit {
         ($start:expr, $end:expr) => {
-            if lc < max_l {
+            if line_count < max_l {
                 let e = trim_trailing_cr(buf, $start, $end);
-                lines[lc] = LineSpan {
+                lines[line_count] = LineSpan {
                     start: ($start) as u16,
                     len: (e - ($start)) as u16,
                     flags: LineSpan::pack_flags(bold, italic, heading),
                     indent,
                 };
-                lc += 1;
+                line_count += 1;
             }
         };
     }
···
                 let path_len = buf[i + 2] as usize;
                 let path_start = i + 3;
                 if path_start + path_len <= n && path_len > 0 {
-                    if ls < i {
-                        emit!(ls, i);
-                        if lc >= max_l {
-                            return (i, lc);
+                    if line_start < i {
+                        emit!(line_start, i);
+                        if line_count >= max_l {
+                            return (i, line_count);
                         }
                     }
 
                     let line_h = fonts.line_height(fonts::Style::Regular);
                     let img_lines = (IMAGE_DISPLAY_H / line_h).max(1) as usize;
 
-                    if lc < max_l {
-                        lines[lc] = LineSpan {
+                    if line_count < max_l {
+                        lines[line_count] = LineSpan {
                             start: path_start as u16,
                             len: path_len as u16,
                             flags: LineSpan::FLAG_IMAGE,
                             indent: 0,
                         };
-                        lc += 1;
+                        line_count += 1;
                     }
 
                     for _ in 1..img_lines {
-                        if lc >= max_l {
+                        if line_count >= max_l {
                             break;
                         }
-                        lines[lc] = LineSpan {
+                        lines[line_count] = LineSpan {
                             start: 0,
                             len: 0,
                             flags: LineSpan::FLAG_IMAGE,
                             indent: 0,
                         };
-                        lc += 1;
+                        line_count += 1;
                     }
 
                     i = path_start + path_len;
-                    ls = i;
-                    px = 0;
-                    sp = ls;
-                    sp_px = 0;
-                    if lc >= max_l {
-                        return (ls, lc);
+                    line_start = i;
+                    cursor_x = 0;
+                    last_space = line_start;
+                    cursor_at_space = 0;
+                    if line_count >= max_l {
+                        return (line_start, line_count);
                     }
                     continue;
                 }
···
         }
 
         if b == b'\n' {
-            emit!(ls, i);
-            ls = i + 1;
-            px = 0;
-            sp = ls;
-            sp_px = 0;
-            if lc >= max_l {
-                return (ls, lc);
+            emit!(line_start, i);
+            line_start = i + 1;
+            cursor_x = 0;
+            last_space = line_start;
+            cursor_at_space = 0;
+            if line_count >= max_l {
+                return (line_start, line_count);
             }
             i += 1;
             continue;
···
 
             // soft hyphen (U+00AD): zero-width break opportunity
             if ch == '\u{00AD}' {
-                sp = i + seq_len;
-                sp_px = px;
+                last_space = i + seq_len;
+                cursor_at_space = cursor_x;
                 i += seq_len;
                 continue;
             }
···
             // NBSP and regular spaces: word-break opportunity
             if is_wrap_space(ch) {
                 let sty = current_style(bold, italic, heading);
-                px += fonts.advance(' ', sty) as u32;
-                sp = i + seq_len;
-                sp_px = px;
-                if px > max_w {
-                    emit!(ls, i);
-                    ls = i + seq_len;
-                    px = 0;
-                    sp = ls;
-                    sp_px = 0;
-                    if lc >= max_l {
-                        return (ls, lc);
+                cursor_x += fonts.advance(' ', sty) as u32;
+                last_space = i + seq_len;
+                cursor_at_space = cursor_x;
+                if cursor_x > max_w {
+                    emit!(line_start, i);
+                    line_start = i + seq_len;
+                    cursor_x = 0;
+                    last_space = line_start;
+                    cursor_at_space = 0;
+                    if line_count >= max_l {
+                        return (line_start, line_count);
                     }
                 }
                 i += seq_len;
···
 
             let sty = current_style(bold, italic, heading);
             let adv = fonts.advance(ch, sty) as u32;
-            px += adv;
-            if px > max_w {
-                if sp > ls {
-                    emit!(ls, sp);
-                    px -= sp_px;
-                    ls = sp;
+            cursor_x += adv;
+            if cursor_x > max_w {
+                if last_space > line_start {
+                    emit!(line_start, last_space);
+                    cursor_x -= cursor_at_space;
+                    line_start = last_space;
                 } else {
-                    emit!(ls, i);
-                    ls = i;
-                    px = adv;
+                    emit!(line_start, i);
+                    line_start = i;
+                    cursor_x = adv;
                 }
-                sp = ls;
-                sp_px = 0;
-                if lc >= max_l {
-                    return (ls, lc);
+                last_space = line_start;
+                cursor_at_space = 0;
+                if line_count >= max_l {
+                    return (line_start, line_count);
                 }
             }
             i += seq_len;
···
         let adv = fonts.advance_byte(b, sty) as u32;
 
         if b == b' ' {
-            px += adv;
-            sp = i + 1;
-            sp_px = px;
-            if px > max_w {
-                emit!(ls, i);
-                ls = i + 1;
-                px = 0;
-                sp = ls;
-                sp_px = 0;
-                if lc >= max_l {
-                    return (ls, lc);
+            cursor_x += adv;
+            last_space = i + 1;
+            cursor_at_space = cursor_x;
+            if cursor_x > max_w {
+                emit!(line_start, i);
+                line_start = i + 1;
+                cursor_x = 0;
+                last_space = line_start;
+                cursor_at_space = 0;
+                if line_count >= max_l {
+                    return (line_start, line_count);
                 }
             }
             i += 1;
             continue;
         }
 
-        px += adv;
-        if px > max_w {
-            if sp > ls {
-                emit!(ls, sp);
-                px -= sp_px;
-                ls = sp;
+        cursor_x += adv;
+        if cursor_x > max_w {
+            if last_space > line_start {
+                emit!(line_start, last_space);
+                cursor_x -= cursor_at_space;
+                line_start = last_space;
             } else {
-                emit!(ls, i);
-                ls = i;
-                px = adv;
+                emit!(line_start, i);
+                line_start = i;
+                cursor_x = adv;
             }
-            sp = ls;
-            sp_px = 0;
-            if lc >= max_l {
-                return (ls, lc);
+            last_space = line_start;
+            cursor_at_space = 0;
+            if line_count >= max_l {
+                return (line_start, line_count);
             }
         }
 
         i += 1;
     }
 
-    if ls < n && lc < max_l {
-        let e = trim_trailing_cr(buf, ls, n);
-        if e > ls {
-            lines[lc] = LineSpan {
-                start: ls as u16,
-                len: (e - ls) as u16,
+    if line_start < n && line_count < max_l {
+        let e = trim_trailing_cr(buf, line_start, n);
+        if e > line_start {
+            lines[line_count] = LineSpan {
+                start: line_start as u16,
+                len: (e - line_start) as u16,
                 flags: LineSpan::pack_flags(bold, italic, heading),
                 indent,
             };
-            lc += 1;
+            line_count += 1;
         }
     }
 
-    (n, lc)
+    (n, line_count)
 }

src/apps/settings.rs

···
     SLEEP_TIMEOUT_STEP, SystemSettings, WifiConfig, parse_settings_txt, write_settings_txt,
 };
 use crate::ui::{
-    Alignment, BitmapLabel, CONTENT_TOP, FULL_CONTENT_W, LARGE_MARGIN, MENU_ROW_GAP, MENU_ROW_H,
-    Region, SECTION_GAP, StackFmt, TITLE_Y, wrap_next, wrap_prev,
+    Alignment, BitmapLabel, CONTENT_TOP, FULL_CONTENT_W, LARGE_MARGIN, Region, SECTION_GAP,
+    StackFmt, TITLE_Y, wrap_next, wrap_prev,
 };
 
-// ── Settings layout constants ───────────────────────────────────
-
-const ROW_H: u16 = MENU_ROW_H;
-const ROW_GAP: u16 = MENU_ROW_GAP;
+const ROW_H: u16 = 40;
+const ROW_GAP: u16 = 6;
 const ROW_STRIDE: u16 = ROW_H + ROW_GAP;
 
 const LABEL_X: u16 = LARGE_MARGIN;

src/apps/upload.rs

···
 use crate::kernel::config::WifiConfig;
 use crate::kernel::tasks;
 use crate::ui::{
-    Alignment, BitmapLabel, ButtonFeedback, CONTENT_TOP, FOOTER_Y, LARGE_MARGIN, Region, stack_fmt,
+    Alignment, BitmapLabel, ButtonFeedback, CONTENT_TOP, LARGE_MARGIN, Region, stack_fmt,
 };
 
 const HEADING_X: u16 = LARGE_MARGIN;
···
 const BODY_X: u16 = 24;
 const BODY_W: u16 = SCREEN_W - BODY_X * 2;
 const BODY_LINE_GAP: u16 = 10;
+const FOOTER_Y: u16 = SCREEN_H - 60;
 
 const HTTP_200_HTML: &[u8] =
     b"HTTP/1.0 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\n\r\n";

src/bin/main.rs

···
     let sd_ok = sd.probe_ok();
     if sd_ok {
         console.push("sd: fat32 mounted");
-        let _ = storage::ensure_pulp_dir_async(&sd).await;
+        if let Err(e) = storage::ensure_pulp_dir_async(&sd).await {
+            console.push("sd: pulp dir failed");
+            log::warn!("ensure_pulp_dir: {:?}", e);
+        }
     }
 
     let mut input = InputDriver::new(board.input);
···
 
     kernel.boot(&mut app_mgr).await;
 
-    spawner.spawn(tasks::input_task(input)).unwrap();
-    spawner.spawn(tasks::housekeeping_task()).unwrap();
-    spawner.spawn(tasks::idle_timeout_task()).unwrap();
-    spawner.spawn(work_queue::worker_task()).unwrap();
+    spawner.spawn(tasks::input_task(input)).expect("spawn input_task");
+    spawner.spawn(tasks::housekeeping_task()).expect("spawn housekeeping_task");
+    spawner.spawn(tasks::idle_timeout_task()).expect("spawn idle_timeout_task");
+    spawner.spawn(work_queue::worker_task()).expect("spawn worker_task");
     info!("kernel ready.");
 
     kernel.run(&mut app_mgr).await

src/fonts/bitmap.rs

···
 use crate::drivers::strip::StripBuffer;
 use crate::ui::{Alignment, Region};
 
+// re-export UTF-8 iterator from kernel util for convenience
+pub use pulp_kernel::util::Utf8Iter;
+
 pub const FIRST_CHAR: u8 = 0x20;
 pub const LAST_CHAR: u8 = 0x7E;
 pub const GLYPH_COUNT: usize = (LAST_CHAR - FIRST_CHAR + 1) as usize;
···
 impl BitmapFont {
     // look up a character, return glyph metrics
     // ascii: direct array index; extended: binary search
-    // unknown chars fall back to space glyph (index 0)
+    // unknown chars fall back to '?' glyph
     #[inline]
     pub fn glyph(&self, ch: char) -> &BitmapGlyph {
         self.resolve(ch).glyph
···
     );
 }
 
-// minimal utf-8 byte-slice iterator
-// decodes &[u8] one char at a time; invalid sequences replaced with U+FFFD
-// (which renders as '?' via the font fallback)
-pub struct Utf8Iter<'a> {
-    data: &'a [u8],
-    pos: usize,
-}
-
-impl<'a> Utf8Iter<'a> {
-    #[inline]
-    pub fn new(data: &'a [u8]) -> Self {
-        Self { data, pos: 0 }
-    }
-}
-
-impl Iterator for Utf8Iter<'_> {
-    type Item = char;
-
-    fn next(&mut self) -> Option<char> {
-        if self.pos >= self.data.len() {
-            return None;
-        }
-
-        let b0 = self.data[self.pos];
-
-        // single-byte ascii
-        if b0 < 0x80 {
-            self.pos += 1;
-            return Some(b0 as char);
-        }
-
-        // determine expected sequence length from lead byte
-        let (mut cp, expected) = if b0 < 0xC0 {
-            // stray continuation byte
-            self.pos += 1;
-            return Some('\u{FFFD}');
-        } else if b0 < 0xE0 {
-            ((b0 as u32) & 0x1F, 2)
-        } else if b0 < 0xF0 {
-            ((b0 as u32) & 0x0F, 3)
-        } else if b0 < 0xF8 {
-            ((b0 as u32) & 0x07, 4)
-        } else {
-            self.pos += 1;
-            return Some('\u{FFFD}');
-        };
-
-        if self.pos + expected > self.data.len() {
-            self.pos = self.data.len();
-            return Some('\u{FFFD}');
-        }
-
-        // decode continuation bytes
-        for i in 1..expected {
-            let cont = self.data[self.pos + i];
-            if cont & 0xC0 != 0x80 {
-                self.pos += i;
-                return Some('\u{FFFD}');
-            }
-            cp = (cp << 6) | (cont as u32 & 0x3F);
-        }
-
-        self.pos += expected;
-        Some(char::from_u32(cp).unwrap_or('\u{FFFD}'))
-    }
-}
+// UTF-8 iteration is provided by pulp_kernel::util::Utf8Iter (re-exported above)