pixel8_console/

shell.rs

//! The console shell: boot screen, command prompt, mode switching, the
//! run loop, build orchestration and error screens. If Pixel8 has a
//! personality, it lives here.

use crate::{
    builder::{spawn_build, BuildJob},
    editor::{
        code::CodeEditor,
        file_picker::{FilePicker, PickerAction},
        map::MapEditor,
        music::MusicEditor,
        sfx::SfxEditor,
        sprite::SpriteEditor,
    },
    ui::{self, Mouse},
    watch::{FileChange, FileWatch, SourceTreeWatch},
};
use anyhow::{anyhow, bail, Result};
use pixel8_runtime::{
    assets::Assets,
    audio::AudioHandle,
    cart::{self, Cart},
    clipboard::Pasted,
    fb::Framebuffer,
    font,
    palette::col,
    project::{decode_assets, encode_assets, Project},
    storage::Storage,
    vm::{GameVm, RuntimeError, UI_FPS},
};
use std::{
    collections::VecDeque,
    path::PathBuf,
    time::{Duration, Instant, SystemTime},
};

pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Keys as the shell sees them, decoupled from the windowing library.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Key {
    Char(char),
    Left,
    Right,
    Up,
    Down,
    Backspace,
    Delete,
    Enter,
    Tab,
    Escape,
    Home,
    End,
    PageUp,
    PageDown,
    /// F6: capture the screen as the cart label while running.
    CaptureLabel,
    /// F1: toggle the resource-usage overlay (CPU, memory, fps).
    ToggleStats,
}

#[derive(Debug, Clone, Copy, Default)]
pub struct Mods {
    pub ctrl: bool,
    pub shift: bool,
    pub alt: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
    Console,
    Run,
    Code,
    Sprite,
    Map,
    Sfx,
    Music,
}

/// The editor tabs, in tab-bar order.
pub const EDITOR_MODES: [Mode; 5] = [Mode::Code, Mode::Sprite, Mode::Map, Mode::Sfx, Mode::Music];

/// What is currently loaded into the console.
enum Loaded {
    None,
    /// A project directory: full edit/build/run workflow.
    Project(Project),
    /// A PNG cart loaded directly: runs as-is; source (if any) is shown
    /// read-only until imported into a project with `import`.
    Cart {
        cart: Cart,
        path: PathBuf,
    },
}

fn assets_of(loaded: &mut Loaded) -> Option<&mut Assets> {
    match loaded {
        Loaded::None => None,
        Loaded::Project(p) => Some(&mut p.assets),
        Loaded::Cart { cart, .. } => Some(&mut cart.assets),
    }
}

fn assets_ref(loaded: &Loaded) -> Option<&Assets> {
    match loaded {
        Loaded::None => None,
        Loaded::Project(p) => Some(&p.assets),
        Loaded::Cart { cart, .. } => Some(&cart.assets),
    }
}

/// Disk watchers for the currently-loaded *project*: the two files pixel8
/// mirrors in memory plus the crate's source tree for build triggering.
struct ProjectWatch {
    code: FileWatch,
    assets: FileWatch,
    source_tree: SourceTreeWatch,
}

impl ProjectWatch {
    fn new(p: &Project) -> Self {
        let assets_baseline = encode_assets(&p.assets).unwrap_or_default();
        Self {
            code: FileWatch::new(p.dir.join("src/lib.rs"), p.code.clone().into_bytes()),
            assets: FileWatch::new(p.dir.join("assets.pixel8.json"), assets_baseline),
            source_tree: SourceTreeWatch::new(&p.dir),
        }
    }

    /// Re-baseline every watcher to the project's current in-memory state and
    /// the current source tree (after pixel8 saved the files itself).
    fn sync(&mut self, p: &Project) {
        self.code.mark_synced(p.code.clone().into_bytes());
        self.assets
            .mark_synced(encode_assets(&p.assets).unwrap_or_default());
        self.source_tree.sync();
    }
}

/// Disk watcher for a loaded PNG cart: re-parses on external change and
/// reconciles its assets against any in-console edits.
struct CartWatch {
    path: PathBuf,
    synced_mtime: Option<SystemTime>,
    /// Encoded assets as of the last sync (the editable, comparable part).
    baseline: Vec<u8>,
}

impl CartWatch {
    fn new(path: PathBuf, baseline: Vec<u8>) -> Self {
        let synced_mtime = std::fs::metadata(&path).and_then(|m| m.modified()).ok();
        Self {
            path,
            synced_mtime,
            baseline,
        }
    }

    /// Re-baseline after pixel8 wrote the cart itself (save), so our own write
    /// is not seen as an external change.
    fn mark_synced(&mut self, baseline: Vec<u8>) {
        self.baseline = baseline;
        self.synced_mtime = std::fs::metadata(&self.path)
            .and_then(|m| m.modified())
            .ok();
    }

    /// The new mtime if the file advanced past the last sync, else `None`.
    fn advanced(&mut self) -> Option<SystemTime> {
        let mtime = std::fs::metadata(&self.path)
            .and_then(|m| m.modified())
            .ok()?;
        let advanced = self.synced_mtime.map(|prev| mtime > prev).unwrap_or(true);
        if advanced {
            // Absorb the mtime now; a transiently-corrupt PNG mid-write is
            // ignored until the next write rather than retried every poll.
            self.synced_mtime = Some(mtime);
            Some(mtime)
        } else {
            None
        }
    }
}

/// Color a budget fraction: green with headroom, yellow from 70%, red above
/// 90%.
fn stat_color(frac: f32) -> u8 {
    if frac < 0.7 {
        col::GREEN
    } else if frac <= 0.9 {
        col::YELLOW
    } else {
        col::RED
    }
}

/// Color the fps reading by how close it is to the cart's target rate.
fn fps_color(measured: f32, target: u32) -> u8 {
    let ratio = if target > 0 {
        measured / target as f32
    } else {
        1.0
    };
    if ratio >= 0.95 {
        col::GREEN
    } else if ratio >= 0.8 {
        col::YELLOW
    } else {
        col::RED
    }
}

/// Draw the resource-usage overlay in the top-right: CPU (update and draw), memory and measured
/// fps, color-coded by how close each is to its budget. The CPU fractions and `used` are the
/// once-a-second peaks `StatsMeter` publishes rather than this frame's readings, so the digits
/// hold still long enough to read. `used` is the cart's committed-memory high-water in bytes; it
/// shows as KB and as a fraction of the 128 K cap (see `GameVm::mem_used_bytes`). Columns are
/// aligned: the memory KB sits under the per-call CPU labels and every percentage lines up. A
/// solid black panel keeps it legible over any cart output; it draws in screen space and accepts
/// whatever camera the cart left active (carts reset it each draw).
fn stats_overlay(fb: &mut Framebuffer, cpu_u: f32, cpu_d: f32, used: u32, fps: f32, target: u32) {
    let used_frac = used as f32 / 131_072.0;
    let lines = [
        format!("CPU U   {:>5.1}%", cpu_u * 100.0),
        format!("CPU D   {:>5.1}%", cpu_d * 100.0),
        format!(
            "MEM {:<4}{:>5.1}%",
            format!("{}K", used / 1024),
            used_frac * 100.0
        ),
        format!("FPS    {:>6.1}", fps),
    ];
    let colors = [
        stat_color(cpu_u),
        stat_color(cpu_d),
        stat_color(used_frac),
        fps_color(fps, target),
    ];
    let w = lines.iter().map(|l| l.len()).max().unwrap_or(0) as i32 * 4 + 1;
    let x0 = 127 - w;
    fb.rectfill(x0, 0, 127, 4 * 7, col::BLACK);
    for (i, (line, &color)) in lines.iter().zip(colors.iter()).enumerate() {
        fb.print(line, x0 + 1, 1 + i as i32 * 7, color);
    }
}

/// How long a reading stays on screen before the next window's peak replaces it.
const STATS_WINDOW: Duration = Duration::from_secs(1);

/// A one-second tumbling peak of the cart's CPU and memory usage, feeding the F1 overlay.
///
/// `GameVm::cpu_update`/`cpu_draw` report the fuel spent by the *last completed* call, which is
/// exactly what a cart wants but changes every single frame: fed straight into the overlay it
/// churns so hard that the digit left of the decimal point is unreadable. So the meter keeps the
/// worst sample of the window it is accumulating and publishes that when the window closes,
/// leaving the displayed numbers still for the whole second in between. The peak and not the mean
/// because the frame an author is hunting for is the one that blows the budget, and a mean buries
/// it among its well-behaved neighbours.
///
/// Memory rides the same beat but is deliberately *not* sampled per frame. `GameVm::mem_used_bytes`
/// is a call into the cart's `pixel8_mem_used` export under its own fuel budget, and the figure it
/// returns is a high-water mark that only ever ratchets up. The reading taken as the window closes
/// is therefore already that window's peak, and polling it every frame would spend a wasm call per
/// frame to learn nothing. So `sample` takes a closure over the VM instead of a figure, and calls
/// it only on the frame that closes a window — the once-a-second read is then impossible to forget
/// and impossible to do twice.
///
/// The first sample after a reset publishes immediately, so the overlay reads true the moment F1
/// turns it on rather than showing zeros until the first window closes; that sample stands for
/// itself alone and the window it opens starts empty.
#[derive(Debug)]
struct StatsMeter {
    /// When the window being accumulated started.
    t0: Instant,
    /// The worst fuel fractions seen so far in that window.
    peak_update: f32,
    peak_draw: f32,
    /// The peaks published by the last closed window, held until the next one closes. `None` until
    /// the first sample arrives, which publishes itself.
    published: Option<(f32, f32)>,
    /// The memory high-water read as the last window closed, in bytes.
    mem_used: u32,
}

impl StatsMeter {
    /// The worst fraction of `update`'s fuel budget the cart reached over the window.
    fn cpu_update(&self) -> f32 {
        self.published.map_or(0.0, |(u, _)| u)
    }

    /// The same, for `draw`.
    fn cpu_draw(&self) -> f32 {
        self.published.map_or(0.0, |(_, d)| d)
    }

    /// The cart's committed-memory high-water as of the last window boundary, in bytes.
    fn mem_used(&self) -> u32 {
        self.mem_used
    }

    /// Record one logical frame's fuel fractions, closing the window if this frame ends it. `mem`
    /// reads the cart's memory high-water and runs only on the frame that closes one; see the type
    /// docs for why that reading is worth exactly one wasm call a second. `now` is a parameter
    /// rather than an `Instant::now()` inside so tests can drive the boundaries without sleeping.
    fn sample<F>(&mut self, now: Instant, cpu_update: f32, cpu_draw: f32, mem: F)
    where
        F: FnOnce() -> u32,
    {
        self.peak_update = self.peak_update.max(cpu_update);
        self.peak_draw = self.peak_draw.max(cpu_draw);
        if self.published.is_none() || now.duration_since(self.t0) >= STATS_WINDOW {
            self.publish(now, mem);
        }
    }

    /// Forget everything measured so far. Called when the VM is replaced, so a freshly started or
    /// hot-reloaded cart never shows the numbers of the one before it.
    fn reset(&mut self) {
        *self = Self::default();
    }

    /// Close the current window: publish its peaks alongside one fresh memory reading, and start an
    /// empty window at `now`.
    fn publish<F>(&mut self, now: Instant, mem: F)
    where
        F: FnOnce() -> u32,
    {
        self.published = Some((self.peak_update, self.peak_draw));
        self.mem_used = mem();
        self.peak_update = 0.0;
        self.peak_draw = 0.0;
        self.t0 = now;
    }
}

impl Default for StatsMeter {
    fn default() -> Self {
        Self {
            // Overwritten by the first sample, which publishes on the spot.
            t0: Instant::now(),
            peak_update: 0.0,
            peak_draw: 0.0,
            published: None,
            mem_used: 0,
        }
    }
}

/// How long the F6 camera-flash overlay lasts, in frames (~0.1s at 60fps).
const CAPTURE_FLASH_FRAMES: u32 = 6;

/// Paint the camera-flash feedback over the running cart's screen: a bright
/// full-screen white pop, like a camera shutter. `cls` is used deliberately —
/// it ignores any camera offset or clip the cart left active, so the flash
/// always covers the whole screen and touches no cart-visible state.
fn capture_flash_overlay(fb: &mut Framebuffer) {
    fb.cls(col::WHITE);
}

enum ConsoleLine {
    Text {
        text: String,
        color: u8,
    },
    /// Decorative palette stripe shown at boot.
    Stripe,
}

pub struct Shell {
    pub mode: Mode,
    last_editor: Mode,
    loaded: Loaded,
    vm: Option<GameVm>,
    audio: AudioHandle,
    fb: Framebuffer,
    frame: u64,

    // Console state.
    lines: VecDeque<ConsoleLine>,
    input: String,
    cursor: usize,
    history: Vec<String>,
    history_pos: Option<usize>,
    scroll_back: usize,

    // Build state.
    build: Option<BuildJob>,
    run_after_build: bool,
    /// Transient feedback shown in the editor bottom bar:
    /// (text, color, frame it expires at).
    toast: Option<(String, u8, u64)>,

    // Hot reload.
    wasm_mtime: Option<SystemTime>,

    // Disk watching for external-edit live-reload.
    project_watch: Option<ProjectWatch>,
    cart_watch: Option<CartWatch>,

    // Mouse, shared with editors.
    pub mouse: Mouse,

    // Editors.
    code_ed: CodeEditor,
    file_picker: FilePicker,
    /// The file edited just before the current one, for the picker's default
    /// selection (alt-tab style).
    previous_file: Option<String>,
    sprite_ed: SpriteEditor,
    map_ed: MapEditor,
    sfx_ed: SfxEditor,
    music_ed: MusicEditor,

    pub want_exit: bool,
    /// Where `new` creates projects and `ls` looks: the host working dir.
    cwd: PathBuf,
    sdk_path: PathBuf,
    /// Cart save files land under this directory instead of the user's
    /// cache directory when set. Tests use it to stay hermetic.
    storage_root: Option<PathBuf>,

    /// F1 toggles the CPU/memory/fps resource overlay.
    show_stats: bool,
    // Wall-clock fps, measured over a moving window, shown in the overlay.
    fps_frames: u32,
    fps_t0: Instant,
    fps_val: f32,
    /// The overlay's CPU and memory rows, peaked over one second so they stay readable.
    stats_meter: StatsMeter,

    /// Frames remaining of the camera-flash overlay shown after an F6 capture.
    capture_flash: u32,

    /// Suppress the software mouse cursor. The windowed console draws its own
    /// pixel-art cursor and hides the OS one; a terminal frontend can't hide
    /// the terminal's mouse pointer, so it hides this one instead to avoid a
    /// distracting double cursor.
    hide_cursor: bool,
}

const TEXT_COLS: usize = 31;
const PROMPT_COL: u8 = col::WHITE;

impl Shell {
    pub fn new(audio: AudioHandle, sdk_path: PathBuf) -> Self {
        let mut shell = Self {
            mode: Mode::Console,
            last_editor: Mode::Code,
            loaded: Loaded::None,
            vm: None,
            audio,
            fb: Framebuffer::new(),
            frame: 0,
            lines: VecDeque::new(),
            input: String::new(),
            cursor: 0,
            history: Vec::new(),
            history_pos: None,
            scroll_back: 0,
            build: None,
            run_after_build: false,
            toast: None,
            wasm_mtime: None,
            project_watch: None,
            cart_watch: None,
            mouse: Mouse::default(),
            code_ed: CodeEditor::new(),
            file_picker: FilePicker::new(),
            previous_file: None,
            sprite_ed: SpriteEditor::new(),
            map_ed: MapEditor::new(),
            sfx_ed: SfxEditor::new(),
            music_ed: MusicEditor::new(),
            want_exit: false,
            cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
            sdk_path,
            storage_root: None,
            show_stats: false,
            fps_frames: 0,
            fps_t0: Instant::now(),
            fps_val: 0.0,
            stats_meter: StatsMeter::default(),
            capture_flash: 0,
            hide_cursor: false,
        };
        shell.boot();
        shell
    }

    /// Hide the console's software mouse cursor (used by frontends that show
    /// the host's own pointer, like the terminal, to avoid a double cursor).
    pub fn set_hide_cursor(&mut self, hide: bool) {
        self.hide_cursor = hide;
    }

    fn boot(&mut self) {
        self.lines.push_back(ConsoleLine::Stripe);
        self.say(&format!("Pixel8 {VERSION}"), col::WHITE);
        self.say("A fantasy console for Rust", col::LIGHT_GREY);
        self.say("", col::WHITE);
        self.say("Type help for help", col::LIGHT_GREY);
        self.say("", col::WHITE);
    }

    /// Print a (wrapped) line to the console.
    pub fn say(&mut self, text: &str, color: u8) {
        if text.is_empty() {
            self.push_line(String::new(), color);
            return;
        }
        for raw in text.split('\n') {
            let mut rest = raw;
            loop {
                let take = rest
                    .char_indices()
                    .nth(TEXT_COLS)
                    .map(|(i, _)| i)
                    .unwrap_or(rest.len());
                self.push_line(rest[..take].to_string(), color);
                rest = &rest[take..];
                if rest.is_empty() {
                    break;
                }
            }
        }
    }

    /// Flash a message in the editor bottom bar for `secs` seconds.
    fn toast(&mut self, text: &str, color: u8, secs: f32) {
        self.toast = Some((text.to_string(), color, self.frame + (secs * 30.0) as u64));
    }

    fn push_line(&mut self, text: String, color: u8) {
        self.lines.push_back(ConsoleLine::Text { text, color });
        while self.lines.len() > 300 {
            self.lines.pop_front();
        }
        self.scroll_back = 0;
    }

    // -----------------------------------------------------------------
    // Loaded-state helpers
    // -----------------------------------------------------------------

    pub fn assets(&self) -> Option<&Assets> {
        match &self.loaded {
            Loaded::None => None,
            Loaded::Project(p) => Some(&p.assets),
            Loaded::Cart { cart, .. } => Some(&cart.assets),
        }
    }

    pub fn assets_mut(&mut self) -> Option<&mut Assets> {
        match &mut self.loaded {
            Loaded::None => None,
            Loaded::Project(p) => Some(&mut p.assets),
            Loaded::Cart { cart, .. } => Some(&mut cart.assets),
        }
    }

    fn code(&self) -> Option<&str> {
        match &self.loaded {
            Loaded::None => None,
            Loaded::Project(p) => Some(&p.code),
            Loaded::Cart { cart, .. } => cart.source.as_deref(),
        }
    }

    fn set_code(&mut self, code: String) {
        match &mut self.loaded {
            Loaded::None => {}
            Loaded::Project(p) => p.code = code,
            Loaded::Cart { cart, .. } => cart.source = Some(code),
        }
    }

    fn project_file_names(&self) -> Vec<String> {
        match &self.loaded {
            Loaded::Project(p) => p.file_names(),
            _ => Vec::new(),
        }
    }

    fn current_file_name(&self) -> String {
        match &self.loaded {
            Loaded::Project(p) => p.current.clone(),
            _ => String::new(),
        }
    }

    fn run_picker_action(&mut self, action: PickerAction) {
        match action {
            PickerAction::Switch(name) => self.select_file(&name),
            PickerAction::Create(name) => self.create_file_in_project(&name),
        }
    }

    /// Open the file picker for the current project, pre-selecting the most
    /// likely target (the previously edited file, else the first non-current).
    fn open_file_picker(&mut self) {
        let files = self.project_file_names();
        let refs: Vec<&str> = files.iter().map(String::as_str).collect();
        let current = self.current_file_name();
        self.file_picker
            .open(&refs, &current, self.previous_file.as_deref());
    }

    /// Persist the open file, switch to `name`, and re-point the code watcher.
    /// If saving the open file fails, surface the error and stay put rather than
    /// dropping the unsaved buffer.
    fn select_file(&mut self, name: &str) {
        enum R {
            NoOp,
            Err(String),
            Ok(String, PathBuf, String),
        }
        let r = match &mut self.loaded {
            Loaded::Project(p) if p.current != name => {
                let previous = p.current.clone();
                match p.save() {
                    Err(e) => R::Err(format!("could not save {previous}: {e}")),
                    Ok(()) => match p.switch_to(name) {
                        Ok(()) => R::Ok(p.code.clone(), p.dir.join("src").join(name), previous),
                        Err(e) => R::Err(format!("{e}")),
                    },
                }
            }
            _ => R::NoOp,
        };
        match r {
            R::Ok(code, path, previous) => {
                self.previous_file = Some(previous);
                self.code_ed.set_text(&code);
                if let Some(w) = &mut self.project_watch {
                    w.code = FileWatch::new(path, code.into_bytes());
                    // Saving the previous file bumped its mtime; absorb it so a
                    // plain file switch does not trigger a rebuild.
                    w.source_tree.sync();
                }
            }
            R::Err(msg) => {
                self.say(&msg, col::RED);
                self.toast(&msg, col::RED, 3.0);
            }
            R::NoOp => {}
        }
    }

    /// Create a new module, open it, and re-point the code watcher.
    fn create_file_in_project(&mut self, name: &str) {
        enum R {
            Err(String),
            Ok(String, PathBuf, String),
        }
        let r = match &mut self.loaded {
            Loaded::Project(p) => {
                let previous = p.current.clone();
                match p.save() {
                    Err(e) => R::Err(format!("could not save {previous}: {e}")),
                    Ok(()) => match p.create_file(name) {
                        Ok(new) => R::Ok(p.code.clone(), p.dir.join("src").join(&new), previous),
                        Err(e) => R::Err(format!("{e}")),
                    },
                }
            }
            _ => return,
        };
        match r {
            R::Ok(code, path, previous) => {
                self.previous_file = Some(previous);
                self.code_ed.set_text(&code);
                if let Some(w) = &mut self.project_watch {
                    w.code = FileWatch::new(path, code.into_bytes());
                    // We wrote lib.rs + the new file ourselves; absorb the bump.
                    w.source_tree.sync();
                }
            }
            R::Err(msg) => {
                self.say(&msg, col::RED);
                self.toast(&msg, col::RED, 3.0);
            }
        }
    }

    fn cart_name(&self) -> String {
        self.assets()
            .map(|a| a.meta.name.clone())
            .unwrap_or_else(|| "no cart".into())
    }

    /// The OS window title: the loaded cart's name plus the console name, or
    /// just the console name when nothing is loaded.
    pub fn window_title(&self) -> String {
        match &self.loaded {
            Loaded::None => "Pixel8".into(),
            _ => format!("{} - Pixel8", self.cart_name()),
        }
    }

    // -----------------------------------------------------------------
    // Input
    // -----------------------------------------------------------------

    /// Feed a game button (host already mapped keys to buttons 0..6).
    pub fn set_button(&mut self, b: usize, down: bool) {
        if let Some(vm) = &mut self.vm {
            vm.state_mut().input.set_button(b, down);
        }
    }

    pub fn key(&mut self, key: Key, mods: Mods) {
        // The file picker, when open, captures all keys.
        if self.file_picker.is_open() {
            let files = self.project_file_names();
            let refs: Vec<&str> = files.iter().map(String::as_str).collect();
            if let Some(action) = self.file_picker.key(key, mods, &refs) {
                self.run_picker_action(action);
            }
            return;
        }
        // Global shortcuts.
        if key == Key::ToggleStats {
            self.show_stats = !self.show_stats;
            return;
        }
        if mods.ctrl {
            match key {
                Key::Char('r') => {
                    self.cmd_run();
                    return;
                }
                Key::Char('s') => {
                    self.cmd_save_quiet();
                    return;
                }
                Key::Char('o') => {
                    if self.mode == Mode::Code && matches!(self.loaded, Loaded::Project(_)) {
                        self.open_file_picker();
                    }
                    return;
                }
                _ => {}
            }
        }

        match self.mode {
            Mode::Run => {
                if key == Key::Escape {
                    self.stop_run("");
                } else if key == Key::CaptureLabel {
                    self.capture_label();
                }
            }
            Mode::Console => self.console_key(key, mods),
            _ => self.editor_key(key, mods),
        }
    }

    fn editor_key(&mut self, key: Key, mods: Mods) {
        if key == Key::Escape {
            self.mode = Mode::Console;
            return;
        }
        // Alt+Left/Right cycles editor tabs.
        if mods.alt {
            let cur = EDITOR_MODES
                .iter()
                .position(|m| *m == self.mode)
                .unwrap_or(0);
            match key {
                Key::Left => {
                    self.switch_editor(
                        EDITOR_MODES[(cur + EDITOR_MODES.len() - 1) % EDITOR_MODES.len()],
                    );
                    return;
                }
                Key::Right => {
                    self.switch_editor(EDITOR_MODES[(cur + 1) % EDITOR_MODES.len()]);
                    return;
                }
                _ => {}
            }
        }
        // Ctrl+C/X/V move data through the system clipboard for every editor, including
        // the map (its tile region uses the native format).
        if mods.ctrl {
            match key {
                Key::Char('c')
                    if matches!(
                        self.mode,
                        Mode::Sprite | Mode::Sfx | Mode::Music | Mode::Code | Mode::Map
                    ) =>
                {
                    self.cmd_copy();
                    return;
                }
                Key::Char('x') if matches!(self.mode, Mode::Code | Mode::Map) => {
                    self.cmd_cut();
                    return;
                }
                Key::Char('v')
                    if matches!(
                        self.mode,
                        Mode::Sprite | Mode::Sfx | Mode::Music | Mode::Code | Mode::Map
                    ) =>
                {
                    self.cmd_paste();
                    return;
                }
                _ => {}
            }
        }
        if self.loaded_none() {
            return;
        }
        let audio = self.audio.clone();
        match self.mode {
            Mode::Code => {
                let mut code = self.code().unwrap_or_default().to_string();
                self.code_ed.key(key, mods, &mut code);
                self.set_code(code);
            }
            Mode::Sprite => {
                if let Some(a) = assets_of(&mut self.loaded) {
                    self.sprite_ed.key(key, mods, a);
                }
            }
            Mode::Map => {
                if let Some(a) = assets_of(&mut self.loaded) {
                    self.map_ed.key(key, mods, a);
                }
            }
            Mode::Sfx => {
                if let Some(a) = assets_of(&mut self.loaded) {
                    self.sfx_ed.key(key, mods, a, &audio);
                }
            }
            Mode::Music => {
                if let Some(a) = assets_of(&mut self.loaded) {
                    self.music_ed.key(key, mods, a, &audio);
                }
            }
            _ => {}
        }
    }

    pub fn switch_editor(&mut self, mode: Mode) {
        self.file_picker.close();
        // Abandon any in-progress map-editor drag so it can't commit a stale
        // selection or move once the editor regains focus.
        self.map_ed.cancel_drag();
        if self.loaded_none() {
            self.say("No cart loaded. Try: new mygame", col::RED);
            self.mode = Mode::Console;
            return;
        }
        if mode == Mode::Code {
            let code = self.code().unwrap_or_default().to_string();
            self.code_ed.set_text(&code);
        }
        self.mode = mode;
        self.last_editor = mode;
    }

    fn loaded_none(&self) -> bool {
        matches!(self.loaded, Loaded::None)
    }

    fn console_key(&mut self, key: Key, _mods: Mods) {
        match key {
            Key::Char(c) => {
                self.input.insert(self.byte_at(self.cursor), c);
                self.cursor += 1;
            }
            Key::Backspace => {
                if self.cursor > 0 {
                    self.cursor -= 1;
                    let at = self.byte_at(self.cursor);
                    self.input.remove(at);
                }
            }
            Key::Delete => {
                if self.cursor < self.input.chars().count() {
                    let at = self.byte_at(self.cursor);
                    self.input.remove(at);
                }
            }
            Key::Left => self.cursor = self.cursor.saturating_sub(1),
            Key::Right => self.cursor = (self.cursor + 1).min(self.input.chars().count()),
            Key::Home => self.cursor = 0,
            Key::End => self.cursor = self.input.chars().count(),
            Key::Up => {
                if !self.history.is_empty() {
                    let pos = match self.history_pos {
                        None => self.history.len() - 1,
                        Some(p) => p.saturating_sub(1),
                    };
                    self.history_pos = Some(pos);
                    self.input = self.history[pos].clone();
                    self.cursor = self.input.chars().count();
                }
            }
            Key::Down => {
                if let Some(p) = self.history_pos {
                    if p + 1 < self.history.len() {
                        self.history_pos = Some(p + 1);
                        self.input = self.history[p + 1].clone();
                    } else {
                        self.history_pos = None;
                        self.input.clear();
                    }
                    self.cursor = self.input.chars().count();
                }
            }
            Key::PageUp => self.scroll_back = (self.scroll_back + 5).min(self.lines.len()),
            Key::PageDown => self.scroll_back = self.scroll_back.saturating_sub(5),
            Key::Enter => {
                let cmd = self.input.clone();
                self.say(&format!("> {cmd}"), col::LIGHT_GREY);
                if !cmd.trim().is_empty() {
                    self.history.push(cmd.clone());
                }
                self.history_pos = None;
                self.input.clear();
                self.cursor = 0;
                self.exec(&cmd);
            }
            Key::Escape => {
                if !self.loaded_none() {
                    self.switch_editor(self.last_editor);
                }
            }
            Key::Tab | Key::CaptureLabel | Key::ToggleStats => {}
        }
    }

    fn byte_at(&self, char_idx: usize) -> usize {
        self.input
            .char_indices()
            .nth(char_idx)
            .map(|(i, _)| i)
            .unwrap_or(self.input.len())
    }

    // -----------------------------------------------------------------
    // Commands
    // -----------------------------------------------------------------

    fn exec(&mut self, cmd: &str) {
        let parts: Vec<&str> = cmd.split_whitespace().collect();
        let Some(&verb) = parts.first() else { return };
        let args = &parts[1..];
        let result = match verb.to_ascii_lowercase().as_str() {
            "help" => {
                self.cmd_help(args);
                Ok(())
            }
            "new" => self.cmd_new(args),
            "load" => self.cmd_load(args),
            "reload" => self.cmd_reload(),
            "save" => self.cmd_save(args),
            "run" => {
                self.cmd_run();
                Ok(())
            }
            "export" => self.cmd_export(args),
            "import" => self.cmd_import(args),
            "import-pico8" | "importp8" => self.cmd_import_pico8(args),
            "info" => {
                self.cmd_info();
                Ok(())
            }
            "ls" | "dir" => self.cmd_ls(),
            "cls" => {
                self.lines.clear();
                Ok(())
            }
            "title" => self.cmd_meta(args, |a, v| a.meta.name = v),
            "author" => self.cmd_meta(args, |a, v| a.meta.author = v),
            "code" => {
                self.switch_editor(Mode::Code);
                Ok(())
            }
            "sprite" | "gfx" => {
                self.switch_editor(Mode::Sprite);
                Ok(())
            }
            "map" => {
                self.switch_editor(Mode::Map);
                Ok(())
            }
            "sfx" => {
                self.switch_editor(Mode::Sfx);
                Ok(())
            }
            "music" => {
                self.switch_editor(Mode::Music);
                Ok(())
            }
            "keys" => {
                self.cmd_keys();
                Ok(())
            }
            "reboot" => {
                self.vm = None;
                self.audio.stop_all();
                self.loaded = Loaded::None;
                self.lines.clear();
                self.boot();
                Ok(())
            }
            "exit" | "quit" | "shutdown" => {
                self.want_exit = true;
                Ok(())
            }
            other => Err(anyhow!("Syntax error: {other}\nType help for help")),
        };
        if let Err(e) = result {
            self.say(&e.to_string(), col::RED);
        }
    }

    fn cmd_help(&mut self, args: &[&str]) {
        if args.first() == Some(&"keys") {
            self.cmd_keys();
            return;
        }
        for (c, d) in [
            ("new <name>", "Create a project"),
            ("load <dir|cart.png>", "Load a cart"),
            ("reload", "Re-read from disk, drop edits"),
            ("save", "Save project to disk"),
            ("run", "Build + run (esc stops)"),
            ("export <f.png|f.html>", "Export cart (PNG or web)"),
            ("import <f.png> <dir>", "Cart -> project"),
            ("import-pico8 <f> [dir]", "PICO-8 cart -> new project"),
            (
                "import-pico8 <f> --into ...",
                "Append assets to loaded project",
            ),
            ("info", "Cart metadata"),
            ("title/author <text>", "Set metadata"),
            ("code/sprite/map/sfx/music", "Editors (esc)"),
            ("ls, cls, keys, reboot, exit", ""),
        ] {
            self.say(c, col::WHITE);
            if !d.is_empty() {
                self.say(&format!("  {d}"), col::LIGHT_GREY);
            }
        }
    }

    fn cmd_keys(&mut self) {
        for (k, d) in [
            ("esc", "Console <-> editor / stop"),
            ("ctrl+r", "Run cart"),
            ("ctrl+s", "Save + build check"),
            ("ctrl+z / ctrl+y", "Undo / redo (in editors)"),
            ("alt+left/right", "Switch editor"),
            ("arrows + z/x", "Game buttons"),
            ("f1", "Toggle resource stats"),
            ("f6", "Capture label (running)"),
        ] {
            self.say(&format!("{k:14} {d}"), col::LIGHT_GREY);
        }
    }

    fn cmd_new(&mut self, args: &[&str]) -> Result<()> {
        let Some(name) = args.first() else {
            bail!("Usage: new <name>");
        };
        let dir = self.cwd.join(name);
        let project = Project::create(&dir, name)?;
        self.say(&format!("Created ./{name}"), col::GREEN);
        self.code_ed.set_text(&project.code);
        self.project_watch = Some(ProjectWatch::new(&project));
        self.cart_watch = None;
        self.loaded = Loaded::Project(project);
        Ok(())
    }

    /// Load a cart/project given on the command line at boot.
    pub fn startup_load(&mut self, path: &str) {
        if let Err(e) = self.cmd_load(&[path]) {
            self.say(&e.to_string(), col::RED);
        }
    }

    /// Run the cart/project loaded at boot, as if the user typed `run`. Used by
    /// the `pixel8 run <path>` launch mode. A cart enters Run mode immediately; a
    /// project spawns its build and enters Run mode once it succeeds.
    pub fn startup_run(&mut self) {
        self.cmd_run();
    }

    fn cmd_load(&mut self, args: &[&str]) -> Result<()> {
        let Some(path) = args.first() else {
            bail!("Usage: load <dir|cart.png>");
        };
        let path = self.cwd.join(path);
        if path.extension().is_some_and(|e| e == "png") {
            let cart = cart::load_png(&path)?;
            let name = cart.assets.meta.name.clone();
            let has_src = cart.source.is_some();
            self.code_ed.set_text(
                cart.source
                    .as_deref()
                    .unwrap_or("// No source in this cart"),
            );
            self.project_watch = None;
            let cart_baseline = encode_assets(&cart.assets).unwrap_or_default();
            self.cart_watch = Some(CartWatch::new(path.clone(), cart_baseline));
            self.loaded = Loaded::Cart { cart, path };
            self.say(&format!("Loaded cart: {name}"), col::GREEN);
            if !has_src {
                self.say("(Playable cart, no source)", col::LIGHT_GREY);
            }
        } else {
            let project = Project::load(&path)?;
            self.code_ed.set_text(&project.code);
            self.say(&format!("Loaded {}", project.name), col::GREEN);
            self.project_watch = Some(ProjectWatch::new(&project));
            self.cart_watch = None;
            self.loaded = Loaded::Project(project);
        }
        Ok(())
    }

    /// Re-read the current project/cart from disk, discarding in-console edits.
    /// Resolves a conflict in favour of the external version.
    fn cmd_reload(&mut self) -> Result<()> {
        let path = match &self.loaded {
            Loaded::None => bail!("Nothing loaded"),
            Loaded::Project(p) => p.dir.clone(),
            Loaded::Cart { path, .. } => path.clone(),
        };
        let path_str = path.to_string_lossy().into_owned();
        self.cmd_load(&[&path_str])
    }

    fn cmd_save(&mut self, _args: &[&str]) -> Result<()> {
        let message = match &mut self.loaded {
            Loaded::None => bail!("Nothing to save"),
            Loaded::Project(p) => {
                p.save()?;
                "Saved".to_string()
            }
            Loaded::Cart { cart, path } => {
                cart::save_png(cart, path)?;
                format!("Saved {}", path.display())
            }
        };
        // After saving a project, pixel8's own write must not look external.
        if let (Loaded::Project(p), Some(w)) = (&self.loaded, &mut self.project_watch) {
            w.sync(p);
        }
        // After saving a PNG cart, pixel8's own write must not look external.
        if let (Loaded::Cart { cart, .. }, Some(w)) = (&self.loaded, &mut self.cart_watch) {
            w.mark_synced(encode_assets(&cart.assets).unwrap_or_default());
        }
        self.say(&message, col::GREEN);
        Ok(())
    }

    /// Read the system clipboard, decode a PICO-8 asset blob, and paste it into
    /// the active editor. Any failure shows a short message in the editor's bar.
    fn cmd_paste(&mut self) {
        // Bar messages are short fixed strings so they always fit the 31-char bar.
        let text = match crate::clipboard::read_text() {
            Ok(t) => t,
            Err(_) => return self.set_editor_status("no text on clipboard".into()),
        };
        if self.mode == Mode::Code {
            if self.code().is_none() {
                return self.set_editor_status("load a project first".into());
            }
            let mut code = self.code().unwrap_or_default().to_string();
            self.code_ed.paste_text(&mut code, &text);
            self.set_code(code);
            return;
        }
        match pixel8_runtime::clipboard::parse(&text) {
            Ok(pasted) => self.apply_paste(pasted),
            Err(_) => self.set_editor_status("nothing to paste".into()),
        }
    }

    /// Encode the active editor's current item and put it on the system clipboard.
    fn cmd_copy(&mut self) {
        let blob = match self.mode {
            Mode::Code => {
                if self.code().is_none() {
                    return self.set_editor_status("load a project first".into());
                }
                let code = self.code().unwrap_or_default().to_string();
                self.code_ed.copy(&code)
            }
            Mode::Sprite | Mode::Sfx | Mode::Music | Mode::Map => {
                let Some(a) = assets_of(&mut self.loaded) else {
                    return self.set_editor_status("load a project first".into());
                };
                match self.mode {
                    Mode::Sprite => Some(self.sprite_ed.copy(a)),
                    Mode::Sfx => Some(self.sfx_ed.copy(a)),
                    Mode::Music => Some(self.music_ed.copy(a)),
                    Mode::Map => self.map_ed.copy_selection(a, false),
                    _ => unreachable!(),
                }
            }
            _ => None,
        };
        if let Some(text) = blob {
            if crate::clipboard::write_text(&text).is_err() {
                self.set_editor_status("clipboard unavailable".into());
            }
        }
    }

    /// Cut the current selection to the system clipboard (code text or map tiles).
    fn cmd_cut(&mut self) {
        let blob = match self.mode {
            Mode::Code => {
                if self.code().is_none() {
                    return self.set_editor_status("load a project first".into());
                }
                let mut code = self.code().unwrap_or_default().to_string();
                let cut = self.code_ed.cut(&mut code);
                if cut.is_some() {
                    self.set_code(code);
                }
                cut
            }
            Mode::Map => {
                let Some(a) = assets_of(&mut self.loaded) else {
                    return self.set_editor_status("load a project first".into());
                };
                self.map_ed.copy_selection(a, true)
            }
            _ => None,
        };
        if let Some(text) = blob {
            if crate::clipboard::write_text(&text).is_err() {
                self.set_editor_status("clipboard unavailable".into());
            }
        }
    }

    /// Dispatch a decoded clipboard blob to the active editor. Separated from
    /// the clipboard read so it can be tested without a display server.
    fn apply_paste(&mut self, pasted: Pasted) {
        let Some(a) = assets_of(&mut self.loaded) else {
            return self.set_editor_status("load a project first".into());
        };
        match self.mode {
            Mode::Sprite => self.sprite_ed.paste(&pasted, a),
            Mode::Sfx => self.sfx_ed.paste(&pasted, a),
            Mode::Music => self.music_ed.paste(&pasted, a),
            Mode::Map => self.map_ed.paste(&pasted),
            _ => {}
        }
    }

    /// Show a transient message in the active editor's bottom bar.
    fn set_editor_status(&mut self, msg: String) {
        match self.mode {
            Mode::Sprite => self.sprite_ed.set_status(msg),
            Mode::Sfx => self.sfx_ed.set_status(msg),
            Mode::Music => self.music_ed.set_status(msg),
            Mode::Code => self.code_ed.set_status(msg),
            Mode::Map => self.map_ed.set_status(msg),
            _ => {}
        }
    }

    /// Ctrl+S: save, flash feedback where the user is looking, and (for
    /// projects) start a background build so compile errors show up
    /// while editing instead of at `run` time.
    fn cmd_save_quiet(&mut self) {
        if let Err(e) = self.cmd_save(&[]) {
            let msg = e.to_string();
            self.say(&msg, col::RED);
            self.toast(&msg, col::RED, 3.0);
            return;
        }
        self.toast("Saved", col::GREEN, 1.5);
        if self.build.is_none() {
            if let Loaded::Project(p) = &self.loaded {
                let dir = p.dir.clone();
                self.build = Some(spawn_build(&dir));
                self.run_after_build = false;
            }
        }
    }

    pub fn cmd_run(&mut self) {
        self.audio.stop_all();
        self.vm = None;
        match &self.loaded {
            Loaded::None => self.say("No cart loaded", col::RED),
            Loaded::Cart { .. } => match self.start_vm_from_loaded() {
                Ok(()) => {}
                Err(e) => self.show_error("boot", &e.to_string()),
            },
            Loaded::Project(p) => {
                let dir = p.dir.clone();
                if self.build.is_some() {
                    self.say("Already compiling...", col::ORANGE);
                    self.toast("Already building...", col::ORANGE, 1.5);
                    return;
                }
                // Pick up external edits and flush in-console edits without
                // clobbering either. Abort the run on an unresolved conflict.
                if !self.reconcile_for_build() {
                    self.say("Disk & editor both changed", col::ORANGE);
                    self.say("Save or reload to resolve", col::ORANGE);
                    self.toast("Conflict: save or reload", col::ORANGE, 3.0);
                    return;
                }
                self.mode = Mode::Console;
                self.say("Compiling...", col::LIGHT_GREY);
                self.build = Some(spawn_build(&dir));
                self.run_after_build = true;
            }
        }
    }

    /// Reconcile a project's disk and in-memory copies in preparation for a
    /// build. Adopts clean external changes, flushes in-console edits to disk,
    /// and returns `false` (build should abort) on an unresolved conflict.
    fn reconcile_for_build(&mut self) -> bool {
        let Loaded::Project(_) = &self.loaded else {
            return true;
        };
        // Snapshot the in-memory bytes to feed the watchers.
        let (code_mem, assets_mem) = match &self.loaded {
            Loaded::Project(p) => (
                p.code.clone().into_bytes(),
                encode_assets(&p.assets).unwrap_or_default(),
            ),
            _ => return true,
        };
        let Some(w) = &mut self.project_watch else {
            return true;
        };
        // Adopt external changes first (clean memory), or bail on conflict.
        let code_change = w.code.poll(&code_mem);
        let assets_change = w.assets.poll(&assets_mem);
        // Absorb the source-tree high-water mark so the flush below + the build
        // it triggers are not re-detected as an external change next poll.
        w.source_tree.poll();
        // Bail on a conflict — including a *standing* one from an earlier poll.
        // A later poll returns `None` once the mtime is absorbed, so the latch
        // is what keeps `run` from flushing the stale copy over disk until the
        // user resolves it with `save` (keep mine) or `reload` (take disk).
        if matches!(code_change, FileChange::Conflict)
            || matches!(assets_change, FileChange::Conflict)
            || w.code.in_conflict()
            || w.assets.in_conflict()
        {
            return false;
        }
        if let FileChange::Adopt(bytes) = code_change {
            let text = String::from_utf8_lossy(&bytes).into_owned();
            self.code_ed.set_text(&text);
            if let Loaded::Project(p) = &mut self.loaded {
                p.code = text;
            }
        }
        if let FileChange::Adopt(bytes) = assets_change {
            match decode_assets(&bytes) {
                Ok(assets) => {
                    if let Loaded::Project(p) = &mut self.loaded {
                        p.assets = assets;
                    }
                }
                // Malformed disk file: re-sync the watcher to the current
                // in-memory encoding so we do not flush over it.
                Err(_) => self.resync_assets_watcher(),
            }
        }
        // Flush any in-console edits that are not yet on disk, so cargo builds
        // exactly what the editors show. (No-op when nothing is dirty.)
        let needs_flush = match (&self.loaded, &self.project_watch) {
            (Loaded::Project(p), Some(w)) => {
                p.code.as_bytes() != w.code.baseline()
                    || encode_assets(&p.assets).unwrap_or_default() != w.assets.baseline()
            }
            _ => false,
        };
        if needs_flush {
            if let Loaded::Project(p) = &self.loaded {
                let _ = p.save();
            }
            if let (Loaded::Project(p), Some(w)) = (&self.loaded, &mut self.project_watch) {
                w.sync(p);
            }
        }
        true
    }

    /// Re-baseline the assets watcher to the current in-memory encoding. Used
    /// when an external `assets.pixel8.json` is unreadable, so we neither flush over
    /// it nor keep re-detecting it.
    fn resync_assets_watcher(&mut self) {
        if let (Loaded::Project(p), Some(w)) = (&self.loaded, &mut self.project_watch) {
            w.assets
                .mark_synced(encode_assets(&p.assets).unwrap_or_default());
        }
    }

    fn start_vm_from_loaded(&mut self) -> Result<()> {
        // Drop any previous VM first: dropping saves its storage, and the
        // new VM must load the freshest save from disk.
        self.vm = None;
        let (wasm, assets) = match &self.loaded {
            Loaded::None => bail!("No cart loaded"),
            Loaded::Cart { cart, .. } => (cart.wasm.clone(), cart.assets.clone()),
            Loaded::Project(p) => {
                let path = p.wasm_path();
                let wasm = std::fs::read(&path)
                    .map_err(|_| anyhow!("Cart not built yet ({})", path.display()))?;
                self.wasm_mtime = std::fs::metadata(&path).and_then(|m| m.modified()).ok();
                (wasm, p.assets.clone())
            }
        };
        let storage = match &self.storage_root {
            Some(root) => Storage::for_cart_in(root, &assets.meta.name),
            None => Storage::for_cart(&assets.meta.name),
        };
        let vm = GameVm::load(&wasm, &assets, self.audio.clone(), storage)?;
        self.vm = Some(vm);
        // Every VM swap lands here — `run` and hot reload alike — so this is the one place the
        // meter must forget the previous cart's peaks and memory figure.
        self.stats_meter.reset();
        self.mode = Mode::Run;
        Ok(())
    }

    fn cmd_export(&mut self, args: &[&str]) -> Result<()> {
        let mut include_source = true;
        let mut controls = true;
        let mut file = None;
        for a in args {
            match *a {
                "-nosrc" => include_source = false,
                "-noctrl" => controls = false,
                _ => file = Some(*a),
            }
        }
        let file = file
            .map(|f| f.to_string())
            .unwrap_or_else(|| format!("{}.png", self.cart_name()));
        let out = self.cwd.join(&file);
        if file.ends_with(".html") {
            // Web export: one self-contained playable page.
            let cart = self.make_cart(false)?;
            self.say("Exporting for web...", col::LIGHT_GREY);
            let web_dir = crate::webexport::web_crate_dir(&self.sdk_path);
            crate::webexport::export_html(&cart, &out, &web_dir, controls)?;
        } else {
            let cart = self.make_cart(include_source)?;
            cart::save_png(&cart, &out)?;
        }
        self.say(&format!("Exported {file}"), col::GREEN);
        Ok(())
    }

    fn make_cart(&self, include_source: bool) -> Result<Cart> {
        match &self.loaded {
            Loaded::None => bail!("No cart loaded"),
            Loaded::Cart { cart, .. } => Ok(Cart {
                wasm: cart.wasm.clone(),
                assets: cart.assets.clone(),
                source: if include_source {
                    cart.source.clone()
                } else {
                    None
                },
            }),
            Loaded::Project(p) => {
                let wasm = std::fs::read(p.wasm_path())
                    .map_err(|_| anyhow!("Cart not built yet. Type run first"))?;
                Ok(Cart {
                    wasm,
                    assets: p.assets.clone(),
                    source: include_source.then(|| p.lib_source()),
                })
            }
        }
    }

    fn cmd_import(&mut self, args: &[&str]) -> Result<()> {
        let (Some(png), Some(dir)) = (args.first(), args.get(1)) else {
            bail!("Usage: import <cart.png> <dir>");
        };
        let cart = cart::load_png(&self.cwd.join(png))?;
        let Some(source) = &cart.source else {
            bail!("Cart has no source (playable-only)");
        };
        let dir = self.cwd.join(dir);
        let mut project = Project::create(&dir, &cart.assets.meta.name)?;
        project.code = source.clone();
        project.assets = cart.assets.clone();
        project.save()?;
        self.say(&format!("Imported into {}", dir.display()), col::GREEN);
        self.code_ed.set_text(&project.code);
        self.loaded = Loaded::Project(project);
        if let Loaded::Project(p) = &self.loaded {
            self.project_watch = Some(ProjectWatch::new(p));
        }
        self.cart_watch = None;
        Ok(())
    }

    /// Import a PICO-8 cart's assets into a fresh project. Only the graphics,
    /// map, sound and music transfer; the cart's Lua code is ignored.
    fn cmd_import_pico8(&mut self, args: &[&str]) -> Result<()> {
        if args.contains(&"--into") {
            return self.cmd_import_pico8_into(args);
        }
        let Some(src) = args.first() else {
            bail!("Usage: import-pico8 <cart.p8|cart.p8.png> [dir]");
        };
        let src = self.cwd.join(src);
        // The destination defaults to the cart's name when omitted.
        let dir = match args.get(1) {
            Some(d) => self.cwd.join(d),
            None => self.cwd.join(pixel8_runtime::pico8::default_dir_name(&src)),
        };
        let project = pixel8_runtime::pico8::import_project(&src, &dir)?;
        self.say(
            &format!("Imported assets into {}", dir.display()),
            col::GREEN,
        );
        self.code_ed.set_text(&project.code);
        self.loaded = Loaded::Project(project);
        if let Loaded::Project(p) = &self.loaded {
            self.project_watch = Some(ProjectWatch::new(p));
        }
        self.cart_watch = None;
        Ok(())
    }

    /// Append selected PICO-8 assets into the currently-loaded project.
    /// `import-pico8 <src> --into [--sprites R] [--sfx R] [--music R]`.
    fn cmd_import_pico8_into(&mut self, args: &[&str]) -> Result<()> {
        let (mut src, mut sprites, mut sfx, mut music) = (None, None, None, None);
        let mut it = args.iter();
        while let Some(&a) = it.next() {
            match a {
                "--into" => {} // marks additive mode; the target is the loaded project.
                "--sprites" => sprites = Some(flag_value(it.next(), "--sprites")?),
                "--sfx" => sfx = Some(flag_value(it.next(), "--sfx")?),
                "--music" => music = Some(flag_value(it.next(), "--music")?),
                flag if flag.starts_with("--") => bail!("unknown flag {flag}"),
                pos if src.is_none() => src = Some(pos),
                pos => bail!("unexpected argument {pos}"),
            }
        }
        let Some(src) = src else {
            bail!("Usage: import-pico8 <cart> --into [--sprites R] [--sfx R] [--music R]");
        };
        let sel = pixel8_runtime::pico8::Selection::parse(sprites, sfx, music)?;

        let report = {
            let Loaded::Project(project) = &mut self.loaded else {
                bail!("import-pico8 --into needs a project loaded; use `new` or `load` first");
            };
            let assets = pixel8_runtime::pico8::parse_file(&self.cwd.join(src))?;
            let report =
                pixel8_runtime::pico8::append_pico8_assets(&mut project.assets, &assets, &sel)?;
            project.save()?;
            report
        };
        // The save rewrote src/lib.rs too; re-baseline the whole watcher (code +
        // assets + source tree) so pixel8's own write isn't seen as an external edit.
        if let (Loaded::Project(p), Some(w)) = (&self.loaded, &mut self.project_watch) {
            w.sync(p);
        }
        for line in report.summary_lines() {
            self.say(&format!("Imported {line}"), col::GREEN);
        }
        for w in &report.warnings {
            self.say(w, col::YELLOW);
        }
        Ok(())
    }

    fn cmd_info(&mut self) {
        match self.assets() {
            None => self.say("No cart loaded", col::RED),
            Some(a) => {
                let (name, author, version) = (
                    a.meta.name.clone(),
                    a.meta.author.clone(),
                    a.meta.version.clone(),
                );
                let label = if a.label.is_some() {
                    "Captured"
                } else {
                    "Default"
                };
                let kind = match &self.loaded {
                    Loaded::Project(p) => format!("Project {}", p.dir.display()),
                    Loaded::Cart { path, .. } => format!("Cart {}", path.display()),
                    Loaded::None => unreachable!(),
                };
                self.say(&format!("Title:   {name}"), col::WHITE);
                self.say(&format!("Author:  {author}"), col::WHITE);
                self.say(&format!("Version: {version}"), col::WHITE);
                self.say(&format!("Label:   {label}"), col::LIGHT_GREY);
                self.say(&kind, col::LIGHT_GREY);
            }
        }
    }

    fn cmd_ls(&mut self) -> Result<()> {
        let mut entries: Vec<_> = std::fs::read_dir(&self.cwd)?
            .filter_map(|e| e.ok())
            .map(|e| {
                let name = e.file_name().to_string_lossy().into_owned();
                let is_dir = e.file_type().map(|t| t.is_dir()).unwrap_or(false);
                (name, is_dir)
            })
            .filter(|(n, _)| !n.starts_with('.'))
            .collect();
        entries.sort();
        for (name, is_dir) in entries.into_iter().take(40) {
            if is_dir {
                self.say(&format!("{name}/"), col::BLUE);
            } else if name.ends_with(".png") {
                self.say(&name, col::PINK);
            } else {
                self.say(&name, col::LIGHT_GREY);
            }
        }
        Ok(())
    }

    fn cmd_meta(&mut self, args: &[&str], set: impl FnOnce(&mut Assets, String)) -> Result<()> {
        if args.is_empty() {
            bail!("Missing text");
        }
        let value = args.join(" ");
        match self.assets_mut() {
            None => bail!("No cart loaded"),
            Some(a) => {
                set(a, value);
                self.say("OK", col::GREEN);
                Ok(())
            }
        }
    }

    fn capture_label(&mut self) {
        let Some(vm) = &self.vm else { return };
        let pixels = vm.state().fb.pixels().to_vec();
        if let Some(a) = self.assets_mut() {
            a.label = Some(pixels);
        }
        // A brief on-screen camera flash, plus a console line for the record.
        self.capture_flash = CAPTURE_FLASH_FRAMES;
        self.say("Label captured", col::GREEN);
    }

    fn stop_run(&mut self, message: &str) {
        self.vm = None;
        self.audio.stop_all();
        self.mode = Mode::Console;
        if !message.is_empty() {
            self.say(message, col::RED);
        }
    }

    fn show_error(&mut self, phase: &str, message: &str) {
        self.stop_run("");
        self.say("", col::WHITE);
        self.say(&format!("** Error in {phase} **"), col::RED);
        for line in message.lines().take(12) {
            self.say(line, col::ORANGE);
        }
    }

    fn runtime_error(&mut self, e: RuntimeError) {
        self.show_error(e.phase, &e.message);
    }

    // -----------------------------------------------------------------
    // Per-frame logic
    // -----------------------------------------------------------------

    /// The rate the host should tick at: a running cart's frame rate (30 or
    /// 60), else 30. Running the whole Run-mode tick at the cart's rate is
    /// what gets the display to refresh at 60 too.
    pub fn tick_fps(&self) -> u32 {
        match (self.mode, &self.vm) {
            (Mode::Run, Some(vm)) => vm.fps(),
            _ => UI_FPS,
        }
    }

    pub fn tick(&mut self) {
        self.frame += 1;

        // Poll the background build.
        if let Some(job) = &self.build {
            if let Some(result) = job.poll() {
                self.build = None;
                if result.success {
                    let msg = format!("Build ok ({:.1}s)", result.duration.as_secs_f32());
                    self.say(&msg, col::GREEN);
                    self.toast(&msg, col::GREEN, 2.0);
                    for w in &result.warnings {
                        self.say(w, col::ORANGE);
                    }
                    if self.run_after_build {
                        self.run_after_build = false;
                        if let Err(e) = self.start_vm_from_loaded() {
                            self.show_error("boot", &e.to_string());
                        }
                    }
                } else {
                    self.run_after_build = false;
                    // A failed build must never pass silently: whether it was
                    // kicked off from an editor or by an external edit while a
                    // cart is running, drop straight back to the console (and
                    // stop the now-stale cart) so the whole error list is on
                    // screen, rather than relying on a toast that the editor
                    // clips off the right edge of the screen.
                    self.stop_run("");
                    let n = result
                        .errors
                        .iter()
                        .filter(|l| l.starts_with("error"))
                        .count();
                    self.say(&format!("Build failed ({n} errors)"), col::RED);
                    for line in &result.errors {
                        let color = if line.starts_with("error") {
                            col::RED
                        } else {
                            col::ORANGE
                        };
                        self.say(line, color);
                    }
                }
            }
        }

        self.poll_project_watch();
        self.poll_cart_watch();
        self.check_hot_reload();

        match self.mode {
            Mode::Run => {
                if self.vm.is_some() {
                    let fps_val = self.fps_val;
                    let vm = self.vm.as_mut().unwrap();
                    vm.state_mut().set_measured_fps(fps_val);
                    let logs = std::mem::take(&mut vm.state_mut().logs);
                    let result = vm.call_update().and_then(|()| vm.call_draw());
                    let (cpu_u, cpu_d) = (vm.cpu_update(), vm.cpu_draw());
                    // Sample per *logical* frame, not per presented one: the presenter runs at its
                    // own cadence, so sampling in `draw` would count a 30 fps cart's frames twice
                    // on a 60 Hz window. Sample whether or not the overlay is showing, so F1
                    // reveals a settled reading straight away. The closure is the once-a-second
                    // memory read, and the meter calls it only when a window closes.
                    self.stats_meter
                        .sample(Instant::now(), cpu_u, cpu_d, || vm.mem_used_bytes());
                    for l in logs {
                        self.say(&l, col::LIGHT_GREY);
                    }
                    if let Err(e) = result {
                        self.runtime_error(e);
                    }
                } else {
                    self.mode = Mode::Console;
                }
            }
            Mode::Console => {}
            _ => {
                // Tab bar clicks work in every editor (but not while the picker is open).
                if !self.file_picker.is_open() {
                    if let Some(target) = ui::tab_bar_click(&self.mouse) {
                        self.switch_editor(EDITOR_MODES[target]);
                    }
                }
                let mouse = self.mouse;
                let audio = self.audio.clone();
                match self.mode {
                    Mode::Code => {
                        if self.file_picker.is_open() {
                            let files = self.project_file_names();
                            let refs: Vec<&str> = files.iter().map(String::as_str).collect();
                            if let Some(action) = self.file_picker.tick(&mouse, &refs) {
                                self.run_picker_action(action);
                            }
                        } else if !self.loaded_none() {
                            // Click the top-left filename to open the picker (projects only).
                            if ui::filename_clicked(&mouse, &self.current_file_name())
                                && matches!(self.loaded, Loaded::Project(_))
                            {
                                self.open_file_picker();
                            } else {
                                let code = self.code().unwrap_or_default().to_string();
                                self.code_ed.tick(&mouse, &code);
                            }
                        }
                    }
                    Mode::Sprite => {
                        if let Some(a) = assets_of(&mut self.loaded) {
                            self.sprite_ed.tick(&mouse, a);
                        }
                    }
                    Mode::Map => {
                        if let Some(a) = assets_of(&mut self.loaded) {
                            self.map_ed.tick(&mouse, a);
                        }
                    }
                    Mode::Sfx => {
                        if let Some(a) = assets_of(&mut self.loaded) {
                            self.sfx_ed.tick(&mouse, a, &audio);
                        }
                    }
                    Mode::Music => {
                        if let Some(a) = assets_of(&mut self.loaded) {
                            self.music_ed.tick(&mouse, a, &audio);
                        }
                        // The pencil on a channel jumps to that SFX for editing.
                        if let Some(n) = self.music_ed.take_edit_request() {
                            self.sfx_ed.select(n);
                            self.switch_editor(Mode::Sfx);
                        }
                    }
                    _ => {}
                }
            }
        }
        self.mouse.end_frame();
    }

    fn check_hot_reload(&mut self) {
        if !self.frame.is_multiple_of(30) {
            return;
        }
        let Loaded::Project(p) = &self.loaded else {
            return;
        };
        let Ok(meta) = std::fs::metadata(p.wasm_path()) else {
            return;
        };
        let Ok(mtime) = meta.modified() else {
            return;
        };
        match self.wasm_mtime {
            Some(prev) if mtime > prev => {
                self.wasm_mtime = Some(mtime);
                // Only swap the running VM; in other modes the fresh wasm is
                // simply ready for the next run.
                if self.mode == Mode::Run {
                    match self.start_vm_from_loaded() {
                        Ok(()) => self.say("Hot reloaded", col::GREEN),
                        Err(e) => self.show_error("reload", &e.to_string()),
                    }
                }
            }
            Some(_) => {}
            None => self.wasm_mtime = Some(mtime),
        }
    }

    /// Poll project watchers and react to external edits: adopt clean changes,
    /// warn on conflicts, and kick off a rebuild (code/source) or VM reload
    /// (assets). Runs on a 30-frame cadence; skipped while a build is in flight.
    fn poll_project_watch(&mut self) {
        if !self.frame.is_multiple_of(30) || self.build.is_some() {
            return;
        }
        let (code_mem, assets_mem) = match &self.loaded {
            Loaded::Project(p) => (
                p.code.clone().into_bytes(),
                encode_assets(&p.assets).unwrap_or_default(),
            ),
            _ => return,
        };
        let Some(w) = &mut self.project_watch else {
            return;
        };
        let assets_change = w.assets.poll(&assets_mem);
        let code_change = w.code.poll(&code_mem);
        let source_changed = w.source_tree.poll();
        let code_conflicted = w.code.in_conflict();

        // Assets: no rebuild needed; adopt and reload the running VM.
        match assets_change {
            FileChange::Adopt(bytes) => match decode_assets(&bytes) {
                Ok(assets) => {
                    if let Loaded::Project(p) = &mut self.loaded {
                        p.assets = assets;
                    }
                    self.say("Assets reloaded from disk", col::GREEN);
                    if self.mode == Mode::Run {
                        if let Err(e) = self.start_vm_from_loaded() {
                            self.show_error("reload", &e.to_string());
                        }
                    }
                }
                // Malformed disk file: re-sync so we do not loop on it.
                Err(_) => {
                    self.resync_assets_watcher();
                    self.say("assets.pixel8.json on disk is unreadable", col::ORANGE);
                }
            },
            FileChange::Conflict => {
                self.say("assets.pixel8.json changed on disk;", col::ORANGE);
                self.say("You have unsaved edits", col::ORANGE);
            }
            FileChange::None => {}
        }

        // Code: adopt into the editor; build is driven by source_changed below.
        match code_change {
            FileChange::Adopt(bytes) => {
                let text = String::from_utf8_lossy(&bytes).into_owned();
                self.code_ed.set_text(&text);
                if let Loaded::Project(p) = &mut self.loaded {
                    p.code = text;
                }
            }
            FileChange::Conflict => {
                self.say(
                    &format!("src/{} changed on disk;", self.current_file_name()),
                    col::ORANGE,
                );
                self.say("Save or reload to resolve", col::ORANGE);
            }
            FileChange::None => {}
        }

        // Any source change (lib.rs or another module) rebuilds — unless the
        // mirrored code is in an unresolved conflict (we must not build a state
        // the user has not chosen).
        if source_changed && !code_conflicted {
            let dir = match &self.loaded {
                Loaded::Project(p) => p.dir.clone(),
                _ => return,
            };
            self.say("Source changed, rebuilding...", col::LIGHT_GREY);
            self.toast("Rebuilding...", col::LIGHT_GREY, 1.5);
            self.build = Some(spawn_build(&dir));
            // Re-run from the console or while already running; stay put if the
            // user is in an editor.
            self.run_after_build = matches!(self.mode, Mode::Run | Mode::Console);
        }
    }

    /// Poll a loaded PNG cart's file: on external change re-parse and adopt it
    /// (when there are no in-console asset edits), else warn about a conflict.
    fn poll_cart_watch(&mut self) {
        if !self.frame.is_multiple_of(30) {
            return;
        }
        let (path, in_memory, baseline) = match (&self.loaded, &mut self.cart_watch) {
            (Loaded::Cart { cart, .. }, Some(w)) => {
                if w.advanced().is_none() {
                    return;
                }
                (
                    w.path.clone(),
                    encode_assets(&cart.assets).unwrap_or_default(),
                    w.baseline.clone(),
                )
            }
            _ => return,
        };
        let new_cart = match cart::load_png(&path) {
            Ok(c) => c,
            Err(e) => {
                self.show_error("reload", &e.to_string());
                return;
            }
        };
        let disk = encode_assets(&new_cart.assets).unwrap_or_default();
        match crate::watch::reconcile(&baseline, &disk, &in_memory) {
            crate::watch::Reconcile::Unchanged => {}
            crate::watch::Reconcile::Adopt(_) => {
                self.code_ed.set_text(
                    new_cart
                        .source
                        .as_deref()
                        .unwrap_or("// No source in this cart"),
                );
                if let Some(w) = &mut self.cart_watch {
                    w.baseline = disk;
                }
                self.loaded = Loaded::Cart {
                    cart: new_cart,
                    path,
                };
                self.say("Cart reloaded from disk", col::GREEN);
                if self.mode == Mode::Run {
                    if let Err(e) = self.start_vm_from_loaded() {
                        self.show_error("reload", &e.to_string());
                    }
                }
            }
            crate::watch::Reconcile::Conflict => {
                // No latch: each new external write re-warns. The `reload`
                // command (next task) takes the disk version to resolve this.
                self.say("Cart changed on disk;", col::ORANGE);
                self.say("You have unsaved edits", col::ORANGE);
            }
        }
    }

    // -----------------------------------------------------------------
    // Drawing
    // -----------------------------------------------------------------

    /// Draw the current mode and return the framebuffer to present.
    /// Count presented frames over ~0.5 s windows for the fps meter. The
    /// cart can't measure this itself — `time()` is a logical clock — so the
    /// host counts real draws against the wall clock.
    fn meter_fps(&mut self) {
        self.fps_frames += 1;
        let elapsed = self.fps_t0.elapsed();
        if elapsed >= Duration::from_millis(500) {
            self.fps_val = self.fps_frames as f32 / elapsed.as_secs_f32();
            self.fps_frames = 0;
            self.fps_t0 = Instant::now();
        }
    }

    pub fn draw(&mut self) -> &Framebuffer {
        self.meter_fps();
        match self.mode {
            Mode::Run => {
                if self.show_stats {
                    let fps = self.fps_val;
                    // Everything but the fps comes from the one-second meter `tick` feeds, so the
                    // presenter's own cadence cannot make the rows churn.
                    let cpu_u = self.stats_meter.cpu_update();
                    let cpu_d = self.stats_meter.cpu_draw();
                    let used = self.stats_meter.mem_used();
                    if let Some(vm) = self.vm.as_mut() {
                        let target = vm.fps();
                        stats_overlay(&mut vm.state_mut().fb, cpu_u, cpu_d, used, fps, target);
                    }
                }
                if self.capture_flash > 0 {
                    if let Some(vm) = self.vm.as_mut() {
                        capture_flash_overlay(&mut vm.state_mut().fb);
                    }
                    self.capture_flash -= 1;
                }
                if let Some(vm) = &self.vm {
                    return &vm.state().fb;
                }
                &self.fb
            }
            Mode::Console => {
                self.draw_console();
                &self.fb
            }
            _ => {
                self.fb.reset_state();
                self.fb.cls(col::DARK_GREY);
                let mouse = self.mouse;
                match self.mode {
                    Mode::Code => {
                        let code = self.code().unwrap_or_default().to_string();
                        self.code_ed.draw(&mut self.fb, &code);
                        if self.file_picker.is_open() {
                            let files = self.project_file_names();
                            let refs: Vec<&str> = files.iter().map(String::as_str).collect();
                            let current = self.current_file_name();
                            self.file_picker.draw(&mut self.fb, &refs, &current);
                        }
                    }
                    Mode::Sprite => {
                        if let Some(a) = assets_ref(&self.loaded) {
                            self.sprite_ed.draw(&mut self.fb, a);
                        }
                    }
                    Mode::Map => {
                        if let Some(a) = assets_ref(&self.loaded) {
                            self.map_ed.draw(&mut self.fb, a);
                        }
                    }
                    Mode::Sfx => {
                        if let Some(a) = assets_ref(&self.loaded) {
                            self.sfx_ed.draw(&mut self.fb, a, &self.audio);
                        }
                    }
                    Mode::Music => {
                        if let Some(a) = assets_ref(&self.loaded) {
                            self.music_ed.draw(&mut self.fb, a, &self.audio);
                        }
                    }
                    _ => {}
                }
                ui::draw_tab_bar(&mut self.fb, self.mode);
                // Per-editor top-left content: the code filename (click to pick
                // a file), the SFX mode buttons, and the sprite/map view buttons.
                match self.mode {
                    Mode::Code => {
                        let name = self.current_file_name();
                        ui::code_filename(&mut self.fb, &name);
                    }
                    Mode::Sfx => ui::mode_buttons(&mut self.fb, self.sfx_ed.is_pitch()),
                    Mode::Sprite => ui::view_buttons(&mut self.fb, self.sprite_ed.is_fullscreen()),
                    Mode::Map => ui::view_buttons(&mut self.fb, self.map_ed.is_fullscreen()),
                    Mode::Music => {
                        ui::mode_buttons(&mut self.fb, !self.music_ed.is_grid());
                        if self.music_ed.is_grid() {
                            ui::pat_sfx_toggle(&mut self.fb, self.music_ed.grid_sfx());
                        }
                    }
                    _ => {}
                }
                self.draw_toast();
                // Name the hovered view in the bottom bar, but not while the
                // file picker is open — its tabs are inert then, so a hint
                // would invite a click that does nothing.
                if !self.file_picker.is_open() {
                    if let Some(i) = ui::tab_bar_hover(&mouse) {
                        ui::status_bar(&mut self.fb, ui::tab_name(i));
                    }
                }
                if !self.hide_cursor {
                    ui::draw_cursor(&mut self.fb, &mouse);
                }
                &self.fb
            }
        }
    }

    /// Bottom-bar feedback in editor modes: a live "building..." while a
    /// build runs, otherwise the most recent toast until it expires.
    fn draw_toast(&mut self) {
        let msg = if self.build.is_some() {
            let dots = ".".repeat(1 + (self.frame as usize / 10) % 3);
            Some((format!("Building{dots}"), col::ORANGE))
        } else {
            match &self.toast {
                Some((text, color, expires)) if self.frame < *expires => {
                    Some((text.clone(), *color))
                }
                _ => {
                    self.toast = None;
                    None
                }
            }
        };
        if let Some((text, color)) = msg {
            self.fb.rectfill(0, 120, 127, 127, col::BLACK);
            self.fb.print(&text, 2, 121, color);
        }
    }

    fn draw_console(&mut self) {
        self.fb.reset_state();
        self.fb.cls(col::BLACK);
        // Lines fit between the top margin and the bottom status line, scaled
        // to the font's line height.
        let rows = ((120 - 2) / font::GLYPH_H) as usize;

        // Gather visible lines: history tail + prompt line.
        let total = self.lines.len();
        let end = total.saturating_sub(self.scroll_back);
        let start = end.saturating_sub(rows);
        let mut y = 2;
        for line in self.lines.iter().skip(start).take(end - start) {
            match line {
                ConsoleLine::Text { text, color } => {
                    self.fb.print(text, 2, y, *color);
                }
                ConsoleLine::Stripe => {
                    for (i, c) in [8u8, 9, 10, 11, 12, 13, 14, 15].iter().enumerate() {
                        self.fb
                            .rectfill(2 + i as i32 * 6, y, 2 + i as i32 * 6 + 4, y + 3, *c);
                    }
                }
            }
            y += font::GLYPH_H;
        }

        // Prompt with blinking cursor (skipped while compiling).
        if self.build.is_some() {
            let dots = ".".repeat(1 + (self.frame as usize / 10) % 3);
            self.fb
                .print(&format!("Compiling{dots}"), 2, y, col::ORANGE);
            return;
        }
        let prompt = format!("> {}", self.input);
        self.fb.print(&prompt, 2, y, PROMPT_COL);
        if (self.frame / 8).is_multiple_of(2) {
            let cx = 2 + (2 + self.cursor as i32) * 4;
            self.fb
                .rectfill(cx, y, cx + 3, y + font::GLYPH_H - 2, col::RED);
        }
    }
}

/// The value following a flag, rejecting a missing value or another flag taken
/// as the value (e.g. `--into --sfx 0`).
fn flag_value<'a>(next: Option<&'a &'a str>, flag: &str) -> Result<&'a str> {
    match next {
        Some(&v) if !v.starts_with("--") => Ok(v),
        _ => bail!("{flag} needs a value"),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::Path;

    #[test]
    fn stats_overlay_draws_top_right_panel() {
        let text_pixels = |fb: &Framebuffer, xr: std::ops::Range<i32>| {
            let mut n = 0;
            for y in 0..28 {
                for x in xr.clone() {
                    if fb.pget(x, y) != col::BLACK {
                        n += 1;
                    }
                }
            }
            n
        };
        let mut fb = Framebuffer::new();
        stats_overlay(&mut fb, 0.342, 0.51, 32768, 30.0, 30);
        // With one-decimal CPU the panel widens (12-char rows -> x0=78), so the
        // decimal digit shows colored text in 78..86 — blank with the old
        // integer panel (x0=86). This is what makes the test red-before-green.
        assert!(
            text_pixels(&fb, 78..86) > 0,
            "decimal CPU widened the panel left"
        );
        assert_eq!(
            text_pixels(&fb, 0..60),
            0,
            "overlay leaves the top-left untouched"
        );
    }

    /// A blank meter plus the instant its first window starts from. Tests step that instant by
    /// hand so nothing has to sleep.
    fn stats_meter() -> (StatsMeter, Instant) {
        (StatsMeter::default(), Instant::now())
    }

    /// Drive one logical frame the way `tick` does, with `mem` standing in for the wasm call.
    /// `reads` collects every reading the meter asks for, so a test can see both how often the VM
    /// would have been called and what it answered.
    fn stats_frame(
        m: &mut StatsMeter,
        now: Instant,
        cpu: (f32, f32),
        mem: u32,
        reads: &mut Vec<u32>,
    ) {
        m.sample(now, cpu.0, cpu.1, || {
            reads.push(mem);
            mem
        });
    }

    #[test]
    fn stats_meter_publishes_its_first_sample_at_once() {
        let (mut m, t) = stats_meter();
        let mut reads = Vec::new();
        assert_eq!((m.cpu_update(), m.mem_used()), (0.0, 0));
        stats_frame(&mut m, t, (0.4, 0.2), 4096, &mut reads);
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.4, 0.2));
        // Without this the overlay would read 0K for the cart's first second.
        assert_eq!(m.mem_used(), 4096);
    }

    /// The bug this meter exists for: within one window the reading must not move, however wildly
    /// the per-frame fuel fractions swing.
    #[test]
    fn stats_meter_holds_its_reading_within_the_window() {
        let (mut m, t) = stats_meter();
        m.sample(t, 0.4, 0.2, || 0);
        for (i, cpu) in [0.9_f32, 0.05, 0.7, 0.01, 0.99].iter().enumerate() {
            m.sample(
                t + Duration::from_millis(100 * (i as u64 + 1)),
                *cpu,
                *cpu,
                || 0,
            );
            let held = (m.cpu_update(), m.cpu_draw());
            assert_eq!(held, (0.4, 0.2), "ratcheted mid-window");
        }
    }

    #[test]
    fn stats_meter_publishes_the_window_peak_at_the_boundary() {
        let (mut m, t) = stats_meter();
        // The first sample publishes on the spot, opening an empty window at `t`; of the three
        // that follow, only the worst of each column survives to the boundary.
        m.sample(t, 0.9, 0.9, || 0);
        m.sample(t + Duration::from_millis(200), 0.2, 0.5, || 0);
        m.sample(t + Duration::from_millis(500), 0.6, 0.3, || 0);
        m.sample(t + Duration::from_millis(1000), 0.4, 0.1, || 0);
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.6, 0.5));
    }

    #[test]
    fn stats_meter_starts_a_fresh_window_after_publishing() {
        let (mut m, t) = stats_meter();
        m.sample(t, 1.0, 1.0, || 0);
        m.sample(t + Duration::from_millis(1000), 1.0, 1.0, || 0);
        // A second window of nothing but 0.1 must read 0.1: the 1.0s of the window before it are
        // gone, not carried forward as a high-water mark.
        m.sample(t + Duration::from_millis(1500), 0.1, 0.1, || 0);
        m.sample(t + Duration::from_millis(2000), 0.1, 0.1, || 0);
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.1, 0.1));
    }

    /// A cart that goes idle after a busy spell must fall back to 0.0 rather than keep showing the
    /// 0.5 of the window before it: the published peak is that window's own, not a high-water mark
    /// over the whole session.
    #[test]
    fn stats_meter_publishes_a_window_of_zeros_as_zero() {
        let (mut m, t) = stats_meter();
        m.sample(t, 0.5, 0.5, || 0);
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.5, 0.5));
        for i in 1..=10 {
            m.sample(t + Duration::from_millis(100 * i), 0.0, 0.0, || 0);
        }
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.0, 0.0));
    }

    /// A cart stalling for longer than the whole window leaves that window a single sample, which
    /// must still publish rather than wait for company.
    #[test]
    fn stats_meter_publishes_a_frame_longer_than_the_window() {
        let (mut m, t) = stats_meter();
        let mut reads = Vec::new();
        stats_frame(&mut m, t, (0.1, 0.1), 1024, &mut reads);
        stats_frame(
            &mut m,
            t + Duration::from_secs(4),
            (0.8, 0.7),
            2048,
            &mut reads,
        );
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.8, 0.7));
        assert_eq!(reads, [1024, 2048]);
    }

    #[test]
    fn stats_meter_publishes_memory_on_the_window_beat() {
        let (mut m, t) = stats_meter();
        let mut reads = Vec::new();
        stats_frame(&mut m, t, (0.1, 0.1), 1024, &mut reads);
        stats_frame(
            &mut m,
            t + Duration::from_millis(500),
            (0.1, 0.1),
            8192,
            &mut reads,
        );
        assert_eq!(m.mem_used(), 1024, "mid-window memory must not move");
        stats_frame(
            &mut m,
            t + Duration::from_millis(1000),
            (0.1, 0.1),
            8192,
            &mut reads,
        );
        assert_eq!(m.mem_used(), 8192);
    }

    /// Memory costs a wasm call into `pixel8_mem_used`, and the figure it returns only ratchets
    /// up, so the boundary reading is already the window's peak: one call a second, not one a
    /// frame.
    #[test]
    fn stats_meter_reads_memory_once_per_window() {
        let (mut m, t) = stats_meter();
        let mut reads = Vec::new();
        // Three seconds of 60 fps frames, the last landing exactly on the third boundary.
        for i in 0..=180 {
            let now = t + Duration::from_millis(1000 * i / 60);
            stats_frame(&mut m, now, (0.1, 0.1), 1024 * (i as u32 + 1), &mut reads);
        }
        // The immediate first publish, then one per second closed — not one per frame.
        assert_eq!(reads.len(), 4, "read memory {} times, not 4", reads.len());
    }

    #[test]
    fn stats_meter_reset_clears_the_reading() {
        let (mut m, t) = stats_meter();
        let mut reads = Vec::new();
        stats_frame(&mut m, t, (0.5, 0.5), 4096, &mut reads);
        m.reset();
        assert_eq!((m.cpu_update(), m.cpu_draw()), (0.0, 0.0));
        assert_eq!(m.mem_used(), 0, "kept the old cart's memory figure");
        // Reset re-arms the publish-at-once path, so the new cart's very first frame shows
        // immediately instead of waiting out a window.
        stats_frame(
            &mut m,
            t + Duration::from_millis(10),
            (0.3, 0.7),
            512,
            &mut reads,
        );
        assert_eq!(
            (m.cpu_update(), m.cpu_draw(), m.mem_used()),
            (0.3, 0.7, 512)
        );
    }

    fn test_shell() -> Shell {
        let sdk = Path::new(env!("CARGO_MANIFEST_DIR")).join("../pixel8");
        let mut shell = Shell::new(AudioHandle::dummy(), sdk);
        // Keep cart saves out of the real user cache directory: tests that
        // run carts must be hermetic.
        shell.storage_root =
            Some(std::env::temp_dir().join(format!("pixel8_test_storage_{}", std::process::id())));
        shell
    }

    /// Restarting a cart must save the old VM's storage *before* the new VM
    /// loads its copy from disk — the `self.vm = None` at the top of
    /// `start_vm_from_loaded` is load-bearing. The cart increments a stored
    /// counter in `pixel8_init`; two starts must produce 2, not 1.
    #[test]
    fn restart_saves_storage_before_the_new_vm_loads() {
        use pixel8_runtime::{assets::Assets, cart::Cart, storage::Storage};
        const COUNTER_CART: &str = r#"
            (module
              (import "pixel8" "storage_get" (func $sget (param i32 i32 i32 i32) (result i32)))
              (import "pixel8" "storage_set" (func $sset (param i32 i32 i32 i32) (result i32)))
              (memory (export "memory") 1)
              (data (i32.const 0) "n")
              (func (export "pixel8_init")
                (local $n i32)
                (if (i32.eq (call $sget (i32.const 0) (i32.const 1) (i32.const 8) (i32.const 1))
                            (i32.const 1))
                  (then (local.set $n (i32.sub (i32.load8_u (i32.const 8)) (i32.const 48)))))
                (i32.store8 (i32.const 8) (i32.add (i32.const 49) (local.get $n)))
                (drop (call $sset (i32.const 0) (i32.const 1) (i32.const 8) (i32.const 1))))
              (func (export "pixel8_update"))
              (func (export "pixel8_draw")))
        "#;
        let root = std::env::temp_dir().join(format!("pixel8_restart_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        let mut shell = test_shell();
        shell.storage_root = Some(root.clone());
        shell.loaded = Loaded::Cart {
            cart: Cart {
                wasm: wat::parse_str(COUNTER_CART).unwrap(),
                assets: Assets::default(),
                source: None,
            },
            path: PathBuf::from("counter.png"),
        };
        shell.start_vm_from_loaded().expect("first start"); // n = 1
        shell.start_vm_from_loaded().expect("restart"); // saves 1, reads it, n = 2
        shell.vm = None; // Final save.
        let s = Storage::for_cart_in(&root, &Assets::default().meta.name);
        assert_eq!(
            s.get_json("n").as_deref(),
            Some("2"),
            "the restart must persist the first run's write before the second reads"
        );
        std::fs::remove_dir_all(&root).unwrap();
    }

    /// The once-a-second memory read is a decision about the *call sites*: `tick` asks the VM only
    /// on the frame that closes a window, and `draw` no longer asks it at all. Neither is visible
    /// to `StatsMeter`'s own tests, so drive a real `Shell` over a cart that counts the calls.
    #[test]
    fn running_a_cart_reads_its_memory_once_a_second() {
        use pixel8_runtime::{assets::Assets, cart::Cart};
        // `pixel8_mem_used` answers 1K times the number of times it has been called, so whatever
        // figure the shell ends up holding names the call it came from.
        const COUNTING_CART: &str = r#"
            (module
              (memory (export "memory") 1)
              (global $calls (mut i32) (i32.const 0))
              (func (export "pixel8_init"))
              (func (export "pixel8_update"))
              (func (export "pixel8_draw"))
              (func (export "pixel8_mem_used") (result i32)
                (global.set $calls (i32.add (global.get $calls) (i32.const 1)))
                (i32.mul (global.get $calls) (i32.const 1024))))
        "#;
        let mut shell = test_shell();
        shell.loaded = Loaded::Cart {
            cart: Cart {
                wasm: wat::parse_str(COUNTING_CART).unwrap(),
                assets: Assets::default(),
                source: None,
            },
            path: PathBuf::from("counting.png"),
        };
        shell.show_stats = true;
        shell.start_vm_from_loaded().expect("start");
        // Thirty logical frames all land inside the first window, each with a presented frame over
        // the top of it.
        for _ in 0..30 {
            shell.tick();
            shell.draw();
        }
        assert_eq!(
            shell.stats_meter.mem_used(),
            1024,
            "the overlay is not holding the first frame's reading"
        );
        // The cart's counter is the ground truth: exactly one call so far makes this probe the
        // second, whatever the meter chose to keep.
        let probe = shell.vm.as_mut().unwrap().mem_used_bytes();
        assert_eq!(
            probe,
            2048,
            "pixel8_mem_used ran {} times over 30 frames, not once",
            probe / 1024 - 1
        );
    }

    /// Rewrite a freshly-scaffolded project's `pixel8` git dep to a path dep on the
    /// in-tree SDK, so test builds match this host's ABI and stay offline.
    fn point_cart_at_local_sdk(project_dir: &Path) {
        let sdk = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../pixel8")
            .canonicalize()
            .unwrap();
        let manifest_path = project_dir.join("Cargo.toml");
        let manifest = std::fs::read_to_string(&manifest_path).unwrap();
        // A scaffolded project depends on the released SDK; tests must build against the working
        // tree instead. Every workspace crate shares one version, so this crate's major.minor is
        // the requirement the template wrote.
        let dep = format!(
            "version = \"{}.{}\"",
            env!("CARGO_PKG_VERSION_MAJOR"),
            env!("CARGO_PKG_VERSION_MINOR"),
        );
        let patched = manifest.replace(&dep, &format!("path = {:?}", sdk.display().to_string()));
        assert_ne!(patched, manifest, "no `{dep}` to redirect in:\n{manifest}");
        std::fs::write(&manifest_path, patched).unwrap();
    }

    #[test]
    fn window_title_reflects_loaded_cart() {
        let dir = std::env::temp_dir().join(format!("pixel8_title_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        assert_eq!(shell.window_title(), "Pixel8");

        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        assert_eq!(shell.window_title(), "game - Pixel8");
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// Ctrl+S in an editor saves, flashes feedback, kicks off a real
    /// background build, and reports the result in the bottom bar.
    #[test]
    fn ctrl_s_saves_and_builds_with_feedback() {
        let dir = std::env::temp_dir().join(format!("pixel8_shell_test_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        point_cart_at_local_sdk(&project_dir);

        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        shell.switch_editor(Mode::Code);

        // Add a comment line at the top (keeping the code valid), then Ctrl+S.
        for c in "//x".chars() {
            shell.key(Key::Char(c), Mods::default());
        }
        shell.key(Key::Enter, Mods::default());
        shell.key(
            Key::Char('s'),
            Mods {
                ctrl: true,
                ..Default::default()
            },
        );

        // Saved to disk, toast shown, build started.
        let code = std::fs::read_to_string(project_dir.join("src/lib.rs")).unwrap();
        assert!(code.starts_with("//x\n"), "edit was saved");
        assert_eq!(shell.toast.as_ref().unwrap().0, "Saved");
        assert!(shell.build.is_some(), "background build spawned");

        // While building, the editor bottom bar shows progress.
        shell.draw();
        assert_eq!(shell.fb.pget(0, 120), col::BLACK, "toast bar drawn");

        // Wait for the real cargo build (template code must compile).
        for _ in 0..(120 * 30) {
            shell.tick();
            if shell.build.is_none() {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(33));
        }
        assert!(shell.build.is_none(), "build finished in time");
        let (text, color, _) = shell.toast.as_ref().unwrap();
        assert!(text.starts_with("Build ok"), "got: {text}");
        assert_eq!(*color, col::GREEN);
        assert!(
            shell.mode == Mode::Code,
            "stays in the editor; no mode switch"
        );
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// A broken cart reports a failing build without leaving the editor.
    #[test]
    fn save_build_failure_is_reported() {
        let dir = std::env::temp_dir().join(format!("pixel8_shell_fail_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        let mut project = Project::create(&project_dir, "game").unwrap();
        project.code = "fn broken( {".into();
        project.save().unwrap();

        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        shell.switch_editor(Mode::Code);
        shell.key(
            Key::Char('s'),
            Mods {
                ctrl: true,
                ..Default::default()
            },
        );
        assert!(shell.build.is_some());
        for _ in 0..(120 * 30) {
            shell.tick();
            if shell.build.is_none() {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(33));
        }
        // The build-failure summary is now printed to the console buffer (not
        // the toast), and the mode drops back to Console.
        assert_eq!(
            shell.mode,
            Mode::Console,
            "expected console mode after build failure"
        );
        let summary = shell.lines.iter().find_map(|l| match l {
            ConsoleLine::Text { text, color } if text.starts_with("Build failed") => {
                Some((text.clone(), *color))
            }
            _ => None,
        });
        let (text, color) = summary.expect("Build failed summary not found in console lines");
        assert!(text.starts_with("Build failed"), "got: {text}");
        assert_eq!(color, col::RED);
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// `run` after an external edit (clean in-console state) builds the
    /// external version and does NOT overwrite it with the stale in-memory copy.
    #[test]
    fn run_does_not_clobber_external_edits() {
        let dir = std::env::temp_dir().join(format!("pixel8_run_noclobber_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load");

        // Simulate an external editor changing src/lib.rs to a still-valid file.
        let lib = project_dir.join("src/lib.rs");
        let original = std::fs::read_to_string(&lib).unwrap();
        let edited = format!("// EXTERNAL EDIT\n{original}");
        // Bump mtime so the watcher sees it as newer than load time.
        std::fs::write(&lib, &edited).unwrap();
        let later = std::time::SystemTime::now() + std::time::Duration::from_secs(10);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&lib)
            .unwrap()
            .set_modified(later)
            .unwrap();

        shell.cmd_run();

        // The on-disk file must still contain the external edit — not be
        // reverted to the stale in-memory copy.
        let after = std::fs::read_to_string(&lib).unwrap();
        assert!(
            after.starts_with("// EXTERNAL EDIT\n"),
            "external edit survived run; got:\n{after}"
        );

        // Let the build finish so we leave no thread dangling.
        for _ in 0..(120 * 30) {
            shell.tick();
            if shell.build.is_none() {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(33));
        }
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// `startup_run` (the `pixel8 run <path>` launch mode) loads-then-runs: on a
    /// project it kicks off the async build and arms the deferred run, exactly
    /// as the in-console `run` verb does.
    #[test]
    fn startup_run_arms_the_deferred_run() {
        let dir = std::env::temp_dir().join(format!("pixel8_startup_run_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();

        shell.startup_load(project_dir.to_str().unwrap());
        assert_eq!(shell.mode, Mode::Console, "loaded, still at the console");

        shell.startup_run();
        assert!(shell.build.is_some(), "startup_run spawns the build");
        assert!(
            shell.run_after_build,
            "and arms the run to start once it is built"
        );

        // The build runs on a detached thread; don't wait for cargo, just clean up.
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// `new` must arm the disk watcher, otherwise in-console edits are dropped
    /// before the build (reconcile_for_build skips the flush when unwatched).
    #[test]
    fn new_arms_the_project_watcher() {
        let dir = std::env::temp_dir().join(format!("pixel8_new_watch_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        shell.cwd = dir.clone();
        shell.cmd_new(&["game"]).expect("new");
        assert!(shell.project_watch.is_some(), "new should arm the watcher");
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// Editing project source externally while idle at the console triggers an
    /// automatic build and starts the cart running.
    #[test]
    fn external_edit_auto_builds_and_runs() {
        let dir = std::env::temp_dir().join(format!("pixel8_autobuild_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        point_cart_at_local_sdk(&project_dir);

        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load");
        assert_eq!(shell.mode, Mode::Console);

        // External edit, mtime bumped so the watcher sees it.
        let lib = project_dir.join("src/lib.rs");
        let original = std::fs::read_to_string(&lib).unwrap();
        std::fs::write(&lib, format!("// auto\n{original}")).unwrap();
        let later = std::time::SystemTime::now() + std::time::Duration::from_secs(10);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&lib)
            .unwrap()
            .set_modified(later)
            .unwrap();

        // Drive ticks: poll fires on a 30-frame cadence, then the build runs.
        let mut entered_run = false;
        for _ in 0..(180 * 30) {
            shell.tick();
            if shell.mode == Mode::Run {
                entered_run = true;
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(33));
        }
        assert!(entered_run, "external edit should auto-build and run");
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// Re-exporting a loaded PNG cart on disk reloads it (assets adopted) when
    /// there are no in-console edits.
    #[test]
    fn external_png_change_reloads_cart() {
        use pixel8_runtime::cart::{self, Cart};
        let dir = std::env::temp_dir().join(format!("pixel8_pngreload_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let mut shell = test_shell();

        let project_dir = dir.join("game");
        let project = Project::create(&project_dir, "game").unwrap();
        let png = dir.join("game.png");

        // A valid cart needs the 4-byte wasm magic (plus version); the codec
        // checks for it on save and load. The VM never runs here.
        let mut cart = Cart {
            wasm: b"\0asm\x01\0\0\0".to_vec(),
            assets: project.assets.clone(),
            source: Some("// v1".into()),
        };
        cart::save_png(&cart, &png).unwrap();
        shell.cmd_load(&[png.to_str().unwrap()]).expect("load png");
        let before = shell.cart_name();

        // Re-export with a different cart name, bump mtime.
        cart.assets.meta.name = "renamed".into();
        cart::save_png(&cart, &png).unwrap();
        let later = std::time::SystemTime::now() + std::time::Duration::from_secs(10);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&png)
            .unwrap()
            .set_modified(later)
            .unwrap();

        for _ in 0..(60 * 30) {
            shell.tick();
            if shell.cart_name() != before {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(33));
        }
        assert_eq!(shell.cart_name(), "renamed", "external PNG change adopted");
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// Saving a PNG cart re-baselines its watcher, so the next poll does not
    /// mistake pixel8's own write for an external change (no false conflict).
    #[test]
    fn saving_png_does_not_self_conflict() {
        use pixel8_runtime::{
            cart::{self, Cart},
            project::encode_assets,
        };
        let dir = std::env::temp_dir().join(format!("pixel8_pngsave_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let mut shell = test_shell();
        let project = Project::create(&dir.join("game"), "game").unwrap();
        let png = dir.join("game.png");
        let cart = Cart {
            wasm: b"\0asm\x01\0\0\0".to_vec(),
            assets: project.assets.clone(),
            source: Some("// v1".into()),
        };
        cart::save_png(&cart, &png).unwrap();
        shell.cmd_load(&[png.to_str().unwrap()]).expect("load png");

        // Edit the loaded cart's assets in-console, then save.
        if let Some(a) = shell.assets_mut() {
            a.meta.name = "edited".into();
        }
        shell.cmd_save(&[]).expect("save");

        // The watcher baseline must now match the saved in-memory assets.
        let in_mem = encode_assets(shell.assets().unwrap()).unwrap_or_default();
        assert_eq!(
            shell.cart_watch.as_ref().unwrap().baseline,
            in_mem,
            "save re-baselined the cart watcher"
        );

        // Ticking must not flip into a conflict / reload state.
        for _ in 0..(2 * 30) {
            shell.tick();
        }
        assert_eq!(shell.cart_name(), "edited");
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// `reload` discards in-console edits and re-reads the project from disk,
    /// resolving a conflict in favour of the external version.
    #[test]
    fn reload_takes_disk_version() {
        let dir = std::env::temp_dir().join(format!("pixel8_reload_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load");

        // External edit on disk.
        let lib = project_dir.join("src/lib.rs");
        std::fs::write(&lib, "// DISK VERSION\n").unwrap();

        shell.cmd_reload().expect("reload");
        let code = shell.code().unwrap_or_default().to_string();
        assert!(
            code.starts_with("// DISK VERSION"),
            "reload took disk; got:\n{code}"
        );
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// A conflict (both disk and editor changed) must abort `run` and keep
    /// aborting on a *second* `run` until resolved — never flushing the stale
    /// in-console copy over the external edit.
    #[test]
    fn run_aborts_on_conflict_and_does_not_clobber() {
        let dir = std::env::temp_dir().join(format!("pixel8_run_conflict_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load");

        // In-console edit: make the in-memory copy dirty.
        if let Loaded::Project(p) = &mut shell.loaded {
            p.code = "// IN-CONSOLE EDIT\n".into();
        }
        // External edit on disk, mtime bumped so the watcher sees it.
        let lib = project_dir.join("src/lib.rs");
        std::fs::write(&lib, "// EXTERNAL EDIT\n").unwrap();
        let later = std::time::SystemTime::now() + std::time::Duration::from_secs(10);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&lib)
            .unwrap()
            .set_modified(later)
            .unwrap();

        // First run: conflict → abort, no build, disk keeps the external edit.
        shell.cmd_run();
        assert_eq!(shell.mode, Mode::Console, "first run aborts on conflict");
        assert!(shell.build.is_none(), "no build started on conflict");
        assert_eq!(
            std::fs::read_to_string(&lib).unwrap(),
            "// EXTERNAL EDIT\n",
            "disk untouched after the first run"
        );

        // Second run without resolving: must STILL abort and STILL not clobber.
        shell.cmd_run();
        assert_eq!(shell.mode, Mode::Console, "second run still aborts");
        assert!(shell.build.is_none(), "second run starts no build");
        assert_eq!(
            std::fs::read_to_string(&lib).unwrap(),
            "// EXTERNAL EDIT\n",
            "disk still untouched after the second run"
        );

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn picker_creates_and_switches_files_in_the_shell() {
        let dir = std::env::temp_dir().join(format!("pixel8_pick_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        shell.switch_editor(Mode::Code);

        // Ctrl+O opens the picker; create a new file from it.
        let ctrl = Mods {
            ctrl: true,
            ..Default::default()
        };
        shell.key(Key::Char('o'), ctrl);
        assert!(shell.file_picker.is_open());
        shell.key(Key::Down, Mods::default()); // -> "+ new file"
        shell.key(Key::Enter, Mods::default()); // -> new-file input
        for c in "enemy".chars() {
            shell.key(Key::Char(c), Mods::default());
        }
        shell.key(Key::Enter, Mods::default()); // create

        assert!(!shell.file_picker.is_open());
        assert!(project_dir.join("src/enemy.rs").exists());
        let lib = std::fs::read_to_string(project_dir.join("src/lib.rs")).unwrap();
        // `mod` is wired in after the template's `#![no_std]` inner attribute.
        assert!(lib.starts_with("#![no_std]"), "lib.rs:\n{lib}");
        assert!(lib.contains("\nmod enemy;\n"), "lib.rs:\n{lib}");
        // The new (empty) file is now the open buffer.
        assert_eq!(shell.code().unwrap(), "");

        // Switch back to lib.rs via the picker.
        shell.key(Key::Char('o'), ctrl);
        shell.key(Key::Enter, Mods::default()); // sel 0 == lib.rs
        assert!(shell.code().unwrap().contains("\nmod enemy;\n"));
        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn clicking_the_filename_opens_the_picker() {
        let dir = std::env::temp_dir().join(format!("pixel8_fnclick_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();
        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        shell.switch_editor(Mode::Code);

        assert!(!shell.file_picker.is_open());
        // A left-press on the top-left filename.
        let name = shell.current_file_name();
        shell.mouse = Mouse {
            x: 3,
            y: 2,
            left_pressed: true,
            ..Default::default()
        };
        assert!(ui::filename_clicked(&shell.mouse, &name));
        shell.tick();
        assert!(
            shell.file_picker.is_open(),
            "filename click opens the picker"
        );
        std::fs::remove_dir_all(&dir).unwrap();
    }

    /// A save failure during a file switch aborts the switch and surfaces the
    /// error via both the console log and the toast bar.
    #[test]
    fn select_file_save_failure_aborts_and_reports() {
        let dir = std::env::temp_dir().join(format!("pixel8_savefail_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut shell = test_shell();
        let project_dir = dir.join("game");
        Project::create(&project_dir, "game").unwrap();

        // Write a second source file so there is something to switch to.
        std::fs::write(project_dir.join("src/other.rs"), "").unwrap();

        shell
            .cmd_load(&[project_dir.to_str().unwrap()])
            .expect("load project");
        shell.switch_editor(Mode::Code);

        // Sabotage save: replace src/lib.rs (file) with a directory of the
        // same name so that fs::write fails with EISDIR.
        let lib_path = project_dir.join("src/lib.rs");
        std::fs::remove_file(&lib_path).unwrap();
        std::fs::create_dir(&lib_path).unwrap();

        // Attempt to switch to other.rs — save fails, switch must be aborted.
        shell.select_file("other.rs");

        // The current file must not have changed.
        assert_eq!(
            shell.current_file_name(),
            "lib.rs",
            "switch must be aborted when save fails"
        );

        // The error must be surfaced via the toast bar in red.
        let toast = shell
            .toast
            .as_ref()
            .expect("toast must be set on save error");
        assert_eq!(toast.1, col::RED, "toast must be red");
        assert!(
            toast.0.contains("lib.rs"),
            "toast must name the file that failed to save; got: {}",
            toast.0
        );

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn import_pico8_into_appends_to_loaded_project() {
        let dir = std::env::temp_dir().join(format!("pixel8_shell_into_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();

        // A source cart with sprite 0 pixel (0,0) = 0xc.
        let mut row0 = vec![b'0'; 128];
        row0[0] = b'c';
        let p8 = format!(
            "pico-8 cartridge // http://www.pico-8.com\nversion 41\n__gfx__\n{}\n",
            String::from_utf8(row0).unwrap()
        );
        std::fs::write(dir.join("src.p8"), p8).unwrap();

        let mut shell = test_shell();
        shell.cwd = dir.clone();
        // `new` creates the project under cwd and loads it as the destination.
        shell.cmd_new(&["dest"]).expect("new");
        // Mark sprite 0 of the loaded project as used, so an additive import must
        // land the imported sprite at slot 1 (after the last used slot).
        shell.assets_mut().expect("loaded").sprites.set(0, 0, 5);

        shell.exec("import-pico8 src.p8 --into --sprites 0");

        // The command must append INTO the loaded `dest` project, not replace it
        // with a freshly-created one: the loaded project is still `dest`...
        match &shell.loaded {
            Loaded::Project(p) => assert_eq!(p.name, "dest"),
            _ => panic!("expected the dest project to remain loaded"),
        }
        let assets = shell.assets().expect("a project is loaded");
        // ...the pre-existing sprite 0 is untouched...
        assert_eq!(assets.sprites.get(0, 0), 5);
        // ...and the imported sprite landed at slot 1 (sheet (8, 0)).
        assert_eq!(assets.sprites.get(8, 0), 0xc);

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn additive_import_does_not_trigger_a_rebuild() {
        let dir =
            std::env::temp_dir().join(format!("pixel8_into_norebuild_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();

        let mut row0 = vec![b'0'; 128];
        row0[0] = b'c';
        let p8 = format!(
            "pico-8 cartridge // http://www.pico-8.com\nversion 41\n__gfx__\n{}\n",
            String::from_utf8(row0).unwrap()
        );
        std::fs::write(dir.join("src.p8"), p8).unwrap();

        let mut shell = test_shell();
        shell.cwd = dir.clone();
        shell.cmd_new(&["dest"]).expect("new");

        shell.exec("import-pico8 src.p8 --into --sprites 0");

        // The save rewrote src/lib.rs too; the import must re-baseline the whole
        // watcher. Tick past the source-tree poll interval and confirm no rebuild was
        // triggered and we stayed at the console (no spontaneous run into Run mode).
        for _ in 0..40 {
            shell.tick();
        }
        assert!(
            shell.build.is_none(),
            "additive import must not spawn a build"
        );
        assert_eq!(shell.mode, Mode::Console, "must stay at the console");
        assert!(!shell.run_after_build, "must not arm a run");

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn apply_paste_routes_map_blobs_to_the_map_editor() {
        use pixel8_runtime::clipboard::Pasted;
        let dir = std::env::temp_dir().join(format!("pixel8_mappaste_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();

        let mut shell = test_shell();
        shell.cwd = dir.clone();
        shell.cmd_new(&["dest"]).expect("new");
        shell.mode = Mode::Map;

        shell.apply_paste(Pasted::Map {
            w: 1,
            h: 1,
            tiles: vec![7],
        });
        assert!(shell.map_ed.has_paste_buffer());

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn apply_paste_routes_sfx_to_the_sfx_editor() {
        use pixel8_runtime::clipboard::{Pasted, SfxClip, Slotted};
        let dir = std::env::temp_dir().join(format!("pixel8_paste_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();

        let mut shell = test_shell();
        shell.cwd = dir.clone();
        shell.cmd_new(&["dest"]).expect("new");
        shell.mode = Mode::Sfx; // the SFX editor's slot defaults to 0.

        let mut sfx = pixel8_runtime::assets::Sfx::default();
        sfx.notes[0].pitch = 21;
        sfx.notes[0].volume = 4;
        let clip = SfxClip {
            records: vec![Slotted { src: 0, value: sfx }],
            patterns: vec![],
        };
        shell.apply_paste(Pasted::Sfx(clip));

        let assets = assets_ref(&shell.loaded).unwrap();
        assert_eq!(assets.sfx[0].notes[0].pitch, 21);

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn hide_cursor_suppresses_the_software_cursor() {
        let mut shell = test_shell();
        // An editor mode: the software mouse cursor is drawn there.
        shell.mode = Mode::Sprite;
        shell.mouse.x = 40;
        shell.mouse.y = 40;
        let with_cursor = shell.draw().pixels().to_vec();

        shell.set_hide_cursor(true);
        let hidden = shell.draw().pixels().to_vec();
        assert_ne!(
            with_cursor, hidden,
            "hiding the cursor must change the frame"
        );

        // Hiding the cursor draws exactly what the mouse being off-screen does.
        shell.set_hide_cursor(false);
        shell.mouse = Mouse::default();
        let no_pointer = shell.draw().pixels().to_vec();
        assert_eq!(
            hidden, no_pointer,
            "a hidden cursor leaves no pointer behind"
        );
    }
}