pixel8_runtime/

vm.rs

//! WASM game execution: sandbox, host ABI, and lifecycle calls.
//!
//! Carts are `wasm32-unknown-unknown` modules executed with wasmi. The
//! only way a cart can touch the outside world is through the small,
//! C-like import set in the `"pixel8"` module — no WASI, no filesystem,
//! no network. Fuel metering keeps runaway loops from hanging the
//! console; they surface as a friendly error screen instead.

use crate::{
    assets::{Assets, MapData, SpriteSheet},
    audio::AudioHandle,
    fb::Framebuffer,
    input::InputState,
    storage::Storage,
};
use anyhow::{anyhow, Context as _, Result};
use pixel8::physics::wire::{Record, CAP, EMPTY, RECORD};
use wasmi::{
    Caller, Config, Engine, Instance, Linker, Module, OperatorCost, Store, StoreLimits,
    StoreLimitsBuilder, TypedFunc,
};

/// A cart's logical frames per second when it doesn't say otherwise.
pub const DEFAULT_FPS: u32 = 60;

/// The console's own tick rate: editors, menus and cart pickers. Independent
/// of the cart rate, which the cart chooses via `pixel8_fps`.
pub const UI_FPS: u32 = 30;

/// Fuel budget for a single lifecycle call: a hard cap of 131,072 (128 K)
/// wasm instructions per call — one number shared with the memory and
/// cart-size limits. What counts as an instruction is set by
/// [`GameVm::operator_cost`]. A real frame uses a few thousand; exceeding this
/// means the cart is stuck or doing far too much, and surfaces as a friendly
/// error screen.
const FUEL_PER_CALL: u64 = 131_072;

/// Hard cap on a cart's total linear memory: 128 K, the same number as the
/// fuel and cart-size limits. Covers static data, the shadow stack and the
/// heap together (wasm cannot separate them). Carts default to a 32 KiB stack
/// reserve (set per-cart in `.cargo/config.toml`), leaving up to ~96 KiB for
/// static data and heap above it; carts may tune it.
const MAX_MEMORY: usize = crate::cart::MEMORY_CAP;

/// A loaded, running cart.
pub struct GameVm {
    store: Store<HostState>,
    _instance: Instance,
    update: TypedFunc<(), ()>,
    draw: TypedFunc<(), ()>,
}

macro_rules! link {
    ($linker:expr, $name:literal, $f:expr) => {
        $linker
            .func_wrap("pixel8", $name, $f)
            .with_context(|| format!("registering host fn {}", $name))?;
    };
}

impl GameVm {
    /// Load a cart module, wire up the ABI, and run `pixel8_init`.
    ///
    /// `storage` is the cart's persistent key-value store, loaded before
    /// `pixel8_init` runs so the cart can read its save data from the first
    /// frame. Frontends without persistence pass `Storage::default()`.
    pub fn load(
        wasm: &[u8],
        assets: &Assets,
        audio: AudioHandle,
        storage: Storage,
    ) -> Result<Self> {
        // The single chokepoint every frontend runs a cart through: the
        // desktop console, the standalone player, the web player and headless
        // verify all land here. Reject mis-sized asset bundles before they
        // reach the renderer, regardless of where the cart came from (a PNG
        // cart, an on-disk project, or a hand-built module).
        crate::assets::validate(assets)?;

        let mut config = Config::default();
        config.consume_fuel(true);
        // Translate every function body up front. wasmi's default lazy mode defers
        // translation to a function's first call and bills it to whatever fuel budget
        // happens to be armed then — so the cart pays for the console's compiler out of
        // its frame budget, frame 0 spikes, and a function body over ~18 KiB can never
        // be entered at all (it exhausts the budget before executing an instruction, and
        // surfaces as the bogus "ran too long (infinite loop?)" screen). Eager
        // translation happens in `Module::new` below, which has no store and so is not
        // fuel-metered. That moves the cost to load time, where it is bounded by the
        // 128 K cart-size cap: a module filling that cap translates in about a
        // millisecond in a release build, well inside one frame, so there is nothing
        // here for a hostile cart to stretch.
        config.compilation_mode(wasmi::CompilationMode::Eager);
        config.operator_cost(Self::operator_cost());
        let engine = Engine::new(&config);
        let module = Module::new(&engine, wasm).map_err(|e| anyhow!("Invalid cart wasm: {e}"))?;

        audio.load(assets.sfx.clone(), assets.music.clone());
        let mut store = Store::new(&engine, HostState::new(assets, audio, storage));
        store.limiter(|state| &mut state.limits);
        let mut linker = <Linker<HostState>>::new(&engine);

        link!(linker, "clear", |mut c: Caller<'_, HostState>, col: i32| {
            c.data_mut().fb.cls(col as u8)
        });
        link!(linker, "camera", |mut c: Caller<'_, HostState>,
                                 x: i32,
                                 y: i32| {
            c.data_mut().fb.camera(x, y)
        });
        link!(linker, "clip", |mut c: Caller<'_, HostState>,
                               x: i32,
                               y: i32,
                               w: i32,
                               h: i32| {
            c.data_mut().fb.clip(x, y, w, h)
        });
        link!(
            linker,
            "set_pixel",
            |mut c: Caller<'_, HostState>, x: i32, y: i32, col: i32| {
                c.data_mut().fb.pset(x, y, col as u8)
            }
        );
        link!(linker, "pixel", |c: Caller<'_, HostState>,
                                x: i32,
                                y: i32|
         -> i32 {
            c.data().fb.pget(x, y) as i32
        });
        link!(linker, "line", |mut c: Caller<'_, HostState>,
                               x0: i32,
                               y0: i32,
                               x1: i32,
                               y1: i32,
                               col: i32| {
            c.data_mut().fb.line(x0, y0, x1, y1, col as u8)
        });
        link!(linker, "rect", |mut c: Caller<'_, HostState>,
                               x0: i32,
                               y0: i32,
                               x1: i32,
                               y1: i32,
                               col: i32| {
            c.data_mut().fb.rect(x0, y0, x1, y1, col as u8)
        });
        link!(
            linker,
            "rect_fill",
            |mut c: Caller<'_, HostState>, x0: i32, y0: i32, x1: i32, y1: i32, col: i32| {
                c.data_mut().fb.rectfill(x0, y0, x1, y1, col as u8)
            }
        );
        link!(
            linker,
            "circle",
            |mut c: Caller<'_, HostState>, x: i32, y: i32, r: i32, col: i32| {
                c.data_mut().fb.circ(x, y, r, col as u8)
            }
        );
        link!(
            linker,
            "circle_fill",
            |mut c: Caller<'_, HostState>, x: i32, y: i32, r: i32, col: i32| {
                c.data_mut().fb.circfill(x, y, r, col as u8)
            }
        );
        link!(linker, "print", |mut c: Caller<'_, HostState>,
                                ptr: u32,
                                len: u32,
                                x: i32,
                                y: i32,
                                col: i32|
         -> i32 {
            let s = read_guest_str(&c, ptr, len);
            c.data_mut().fb.print(&s, x, y, col as u8)
        });
        link!(linker, "is_button_down", |c: Caller<'_, HostState>,
                                         b: u32|
         -> i32 {
            c.data().input.btn(b) as i32
        });
        link!(linker, "is_button_pressed", |c: Caller<'_, HostState>,
                                            b: u32|
         -> i32 {
            c.data().input.btnp(b) as i32
        });
        link!(linker, "buttons_down", |c: Caller<'_, HostState>| -> i32 {
            c.data().input.btn_mask() as i32
        });
        link!(
            linker,
            "buttons_pressed",
            |c: Caller<'_, HostState>| -> i32 { c.data().input.btnp_mask() as i32 }
        );
        link!(
            linker,
            "sprite",
            |mut c: Caller<'_, HostState>,
             n: u32,
             x: i32,
             y: i32,
             w: i32,
             h: i32,
             flip_x: i32,
             flip_y: i32| {
                let HostState { fb, sprites, .. } = c.data_mut();
                fb.spr(sprites, n, x, y, w, h, flip_x != 0, flip_y != 0);
            }
        );
        link!(linker, "map", |mut c: Caller<'_, HostState>,
                              cel_x: i32,
                              cel_y: i32,
                              sx: i32,
                              sy: i32,
                              cel_w: i32,
                              cel_h: i32,
                              layers: u32| {
            let HostState {
                fb, sprites, map, ..
            } = c.data_mut();
            fb.map(
                map,
                sprites,
                cel_x,
                cel_y,
                sx,
                sy,
                cel_w,
                cel_h,
                layers as u8,
            );
        });
        link!(linker, "map_tile", |c: Caller<'_, HostState>,
                                   x: i32,
                                   y: i32|
         -> i32 {
            c.data().map.get(x, y) as i32
        });
        link!(
            linker,
            "set_map_tile",
            |mut c: Caller<'_, HostState>, x: i32, y: i32, v: u32| {
                c.data_mut().map.set(x, y, v as u8)
            }
        );
        link!(
            linker,
            "step_cast",
            |mut c: Caller<'_, HostState>, ptr: u32, len: u32, config: u32| {
                step_the_cast(&mut c, ptr, len, config)
            }
        );
        link!(
            linker,
            "draw_cast",
            |mut c: Caller<'_, HostState>, ptr: u32, len: u32, layers: u32| {
                draw_the_cast(&mut c, ptr, len, layers)
            }
        );
        link!(linker, "sprite_flags", |c: Caller<'_, HostState>,
                                       n: u32|
         -> i32 {
            c.data().sprites.flags(n) as i32
        });
        link!(
            linker,
            "set_sprite_flags",
            |mut c: Caller<'_, HostState>, n: u32, flags: u32| {
                c.data_mut().sprites.flags[(n as usize) % crate::assets::SPRITE_COUNT] =
                    flags as u8;
            }
        );
        link!(linker, "sfx", |c: Caller<'_, HostState>,
                              n: i32,
                              channel: i32| {
            c.data().audio.play_sfx(n, channel)
        });
        link!(linker, "music", |c: Caller<'_, HostState>,
                                n: i32,
                                fade: i32,
                                mask: i32,
                                token: i32|
         -> i32 {
            c.data().audio.play_music(n, fade, mask, token)
        });
        link!(linker, "cpu_update", |c: Caller<'_, HostState>| -> f32 {
            c.data().last_update_cpu
        });
        link!(linker, "cpu_draw", |c: Caller<'_, HostState>| -> f32 {
            c.data().last_draw_cpu
        });
        link!(linker, "fps", |c: Caller<'_, HostState>| -> f32 {
            c.data().measured_fps_or_target()
        });
        link!(linker, "time", |c: Caller<'_, HostState>| -> f32 {
            let st = c.data();
            st.frame as f32 / st.fps as f32
        });
        link!(linker, "rnd", |mut c: Caller<'_, HostState>| -> f32 {
            c.data_mut().next_rand()
        });
        link!(linker, "log", |mut c: Caller<'_, HostState>,
                              ptr: u32,
                              len: u32| {
            let s = read_guest_str(&c, ptr, len);
            c.data_mut().logs.push(s);
        });
        link!(linker, "panic", |mut c: Caller<'_, HostState>,
                                ptr: u32,
                                len: u32| {
            let s = read_guest_str(&c, ptr, len);
            c.data_mut().panic_message = Some(s);
        });
        link!(
            linker,
            "seed_rng",
            |mut c: Caller<'_, HostState>, seed: u32| { c.data_mut().seed_rand(seed) }
        );
        link!(linker, "sprite_pixel", |c: Caller<'_, HostState>,
                                       x: i32,
                                       y: i32|
         -> i32 {
            c.data().sprites.get(x, y) as i32
        });
        link!(
            linker,
            "set_sprite_pixel",
            |mut c: Caller<'_, HostState>, x: i32, y: i32, col: i32| {
                c.data_mut().sprites.set(x, y, col as u8)
            }
        );
        link!(
            linker,
            "sprite_stretch",
            |mut c: Caller<'_, HostState>,
             sx: i32,
             sy: i32,
             sw: i32,
             sh: i32,
             dx: i32,
             dy: i32,
             dw: i32,
             dh: i32,
             flip_x: i32,
             flip_y: i32| {
                let HostState { fb, sprites, .. } = c.data_mut();
                fb.sspr(
                    sprites,
                    sx,
                    sy,
                    sw,
                    sh,
                    dx,
                    dy,
                    dw,
                    dh,
                    flip_x != 0,
                    flip_y != 0,
                );
            }
        );
        link!(
            linker,
            "ellipse",
            |mut c: Caller<'_, HostState>, x0: i32, y0: i32, x1: i32, y1: i32, col: i32| {
                c.data_mut().fb.oval(x0, y0, x1, y1, col as u8)
            }
        );
        link!(
            linker,
            "ellipse_fill",
            |mut c: Caller<'_, HostState>, x0: i32, y0: i32, x1: i32, y1: i32, col: i32| {
                c.data_mut().fb.ovalfill(x0, y0, x1, y1, col as u8)
            }
        );
        link!(
            linker,
            "set_transparent_color",
            |mut c: Caller<'_, HostState>, col: i32, t: i32| {
                c.data_mut().fb.set_transparent_color(col as u8, t != 0)
            }
        );
        link!(linker, "reset_transparency", |mut c: Caller<
            '_,
            HostState,
        >| {
            c.data_mut().fb.reset_transparency()
        });
        link!(
            linker,
            "remap_color",
            |mut c: Caller<'_, HostState>, from: i32, to: i32, mode: i32| {
                let fb = &mut c.data_mut().fb;
                if mode == 0 {
                    fb.remap_color(from as u8, to as u8);
                } else {
                    fb.remap_display_color(from as u8, to as u8);
                }
            }
        );
        link!(linker, "reset_palette", |mut c: Caller<'_, HostState>| {
            c.data_mut().fb.reset_palette()
        });
        link!(
            linker,
            "set_fill_pattern",
            |mut c: Caller<'_, HostState>, pattern: i32, secondary: i32, transparent: i32| {
                c.data_mut()
                    .fb
                    .set_fill_pattern(pattern as u16, secondary as u8, transparent != 0)
            }
        );
        link!(
            linker,
            "set_pen_color",
            |mut c: Caller<'_, HostState>, col: i32| { c.data_mut().fb.set_pen_color(col as u8) }
        );
        link!(
            linker,
            "set_cursor",
            |mut c: Caller<'_, HostState>, x: i32, y: i32| { c.data_mut().fb.set_cursor(x, y) }
        );
        link!(linker, "print_pen", |mut c: Caller<'_, HostState>,
                                    ptr: u32,
                                    len: u32|
         -> i32 {
            let s = read_guest_str(&c, ptr, len);
            c.data_mut().fb.print_pen(&s)
        });
        link!(linker, "storage_set", |mut c: Caller<'_, HostState>,
                                      key_ptr: u32,
                                      key_len: u32,
                                      val_ptr: u32,
                                      val_len: u32|
         -> i32 {
            let key = read_guest_str(&c, key_ptr, key_len);
            let val = read_guest_str(&c, val_ptr, val_len);
            c.data_mut().storage.set_json(&key, &val) as i32
        });
        link!(linker, "storage_get", |mut c: Caller<'_, HostState>,
                                      key_ptr: u32,
                                      key_len: u32,
                                      buf_ptr: u32,
                                      buf_cap: u32|
         -> i32 {
            let key = read_guest_str(&c, key_ptr, key_len);
            let Some(json) = c.data().storage.get_json(&key) else {
                return -1;
            };
            // MAX_BYTES caps the whole store at 128 K, so the length
            // always fits an i32.
            if json.len() <= buf_cap as usize {
                write_guest_bytes(&mut c, buf_ptr, json.as_bytes());
            }
            json.len() as i32
        });
        link!(linker, "storage_remove", |mut c: Caller<'_, HostState>,
                                         key_ptr: u32,
                                         key_len: u32|
         -> i32 {
            let key = read_guest_str(&c, key_ptr, key_len);
            c.data_mut().storage.remove(&key) as i32
        });
        link!(linker, "storage_clear", |mut c: Caller<'_, HostState>| {
            c.data_mut().storage.clear()
        });

        store
            .set_fuel(FUEL_PER_CALL)
            .map_err(|e| anyhow!("Fuel setup: {e}"))?;
        let instance = linker
            .instantiate_and_start(&mut store, &module)
            .map_err(|e| {
                let s = e.to_string();
                if s.contains("resource limiter denied") {
                    anyhow!("Cart needs more than 128K of memory to start")
                } else {
                    anyhow!("Cart does not match the Pixel8 ABI: {e}")
                }
            })?;

        let init = instance
            .get_typed_func::<(), ()>(&store, "pixel8_init")
            .map_err(|e| anyhow!("Cart is missing pixel8_init: {e}"))?;
        let update = instance
            .get_typed_func::<(), ()>(&store, "pixel8_update")
            .map_err(|e| anyhow!("Cart is missing pixel8_update: {e}"))?;
        let draw = instance
            .get_typed_func::<(), ()>(&store, "pixel8_draw")
            .map_err(|e| anyhow!("Cart is missing pixel8_draw: {e}"))?;

        let mut vm = Self {
            store,
            _instance: instance,
            update,
            draw,
        };
        vm.call("init", init).map_err(|e| anyhow!(e.to_string()))?;
        vm.store.data_mut().fps = vm.query_fps();
        Ok(vm)
    }

    /// Read the cart's `pixel8_fps` export. The SDK emits it from every cart;
    /// 30 and 60 are honored, and anything else (or a hand-written cart with
    /// no such export) falls back to the default.
    fn query_fps(&mut self) -> u32 {
        let Ok(func) = self
            ._instance
            .get_typed_func::<(), u32>(&self.store, "pixel8_fps")
        else {
            return DEFAULT_FPS;
        };
        self.store.set_fuel(FUEL_PER_CALL).ok();
        match func.call(&mut self.store, ()) {
            Ok(30) => 30,
            Ok(60) => 60,
            _ => DEFAULT_FPS,
        }
    }

    fn call(
        &mut self,
        phase: &'static str,
        func: TypedFunc<(), ()>,
    ) -> std::result::Result<(), RuntimeError> {
        self.store.set_fuel(FUEL_PER_CALL).ok();
        let result = func.call(&mut self.store, ()).map_err(|err| {
            let message = match self.store.data_mut().panic_message.take() {
                Some(panic) => panic,
                None => {
                    let s = err.to_string();
                    if s.contains("fuel") {
                        format!("{phase}() ran too long\n(infinite loop?)")
                    } else if s.contains("growth operation limited") {
                        format!("{phase}() ran out of memory\n(128K limit)")
                    } else {
                        s
                    }
                }
            };
            RuntimeError { phase, message }
        });
        if result.is_ok() {
            let remaining = self.store.get_fuel().unwrap_or(0);
            let frac = FUEL_PER_CALL.saturating_sub(remaining) as f32 / FUEL_PER_CALL as f32;
            match phase {
                "update" => self.store.data_mut().last_update_cpu = frac,
                "draw" => self.store.data_mut().last_draw_cpu = frac,
                _ => {}
            }
        }
        result
    }

    /// Run one logical frame: tick input, call `pixel8_update`.
    pub fn call_update(&mut self) -> std::result::Result<(), RuntimeError> {
        self.store.data_mut().input.tick();
        let r = self.call("update", self.update);
        self.store.data_mut().frame += 1;
        r
    }

    /// Call `pixel8_draw`.
    pub fn call_draw(&mut self) -> std::result::Result<(), RuntimeError> {
        self.call("draw", self.draw)
    }

    /// The cart's logical frame rate: 30, or 60 if it opted in.
    pub fn fps(&self) -> u32 {
        self.store.data().fps
    }

    /// Fraction (0.0..1.0) of `update`'s fuel budget used last completed frame.
    pub fn cpu_update(&self) -> f32 {
        self.store.data().last_update_cpu
    }

    /// Fraction (0.0..1.0) of `draw`'s fuel budget used last completed frame.
    pub fn cpu_draw(&self) -> f32 {
        self.store.data().last_draw_cpu
    }

    /// Fraction (0.0..1.0) of the 128K memory cap currently in use.
    pub fn memory_used_fraction(&self) -> f32 {
        let Some(mem) = self._instance.get_memory(&self.store, "memory") else {
            return 0.0;
        };
        mem.data_size(&self.store) as f32 / MAX_MEMORY as f32
    }

    /// The cart's committed-memory high-water in bytes (shadow-stack reserve +
    /// statics + the highest the heap has reached), via its `pixel8_mem_used`
    /// export, or 0 for carts without it (hand-written or allocation-free).
    /// Tracks real pressure closely but is not an exact OOM line — the
    /// allocator keeps a small reserve above the last allocation.
    pub fn mem_used_bytes(&mut self) -> u32 {
        let Ok(func) = self
            ._instance
            .get_typed_func::<(), u32>(&self.store, "pixel8_mem_used")
        else {
            return 0;
        };
        self.store.set_fuel(FUEL_PER_CALL).ok();
        func.call(&mut self.store, ()).unwrap_or(0)
    }

    pub fn state(&self) -> &HostState {
        self.store.data()
    }

    pub fn state_mut(&mut self) -> &mut HostState {
        self.store.data_mut()
    }

    /// What one unit of fuel buys, as a price per wasm operator.
    ///
    /// wasmi meters the cart's input operators, and by default charges one
    /// fuel for every one of them except a few free structural markers
    /// (`block`, `loop`, `end`, `nop`...). Counted that way, reading a local
    /// costs the same as a multiply, so a loop like `acc = acc * 31 + i`
    /// costs 18 fuel an iteration for 6 operations of real work, and a host
    /// call with ten arguments costs eleven times a call with none.
    ///
    /// wasmi 0.51, which this budget was calibrated against, was a register
    /// machine and priced translated instructions instead. Locals and
    /// constants were operands there, not instructions, and cost nothing;
    /// that loop cost 7 fuel, and every host call one. Zero-pricing the same
    /// operand plumbing here keeps "one fuel, one instruction" true, and with
    /// it the stress cart's trip point and every figure in `docs/LIMITS.md`.
    ///
    /// Nothing that does work or repeats work is free: arithmetic, memory
    /// access, globals, `select`, every branch and every call still cost one,
    /// so a runaway loop cannot iterate without spending fuel.
    fn operator_cost() -> OperatorCost {
        OperatorCost {
            local_get: 0,
            local_set: 0,
            local_tee: 0,
            i32_const: 0,
            i64_const: 0,
            f32_const: 0,
            f64_const: 0,
            ..Default::default()
        }
    }
}

/// Everything the host exposes to a running cart.
pub struct HostState {
    pub fb: Framebuffer,
    pub input: InputState,
    pub sprites: SpriteSheet,
    pub map: MapData,
    pub audio: AudioHandle,
    /// The cart's persistent key-value store (the save file). The frontend
    /// decides the backing: a cache-dir JSON file on the desktop console and
    /// player, in-memory in the browser and headless `verify`.
    pub storage: Storage,
    /// Messages from the cart's `log` calls, drained by the console.
    pub logs: Vec<String>,
    /// Message from the cart's panic hook, captured just before the trap.
    pub panic_message: Option<String>,
    pub frame: u64,
    /// The cart's logical frames per second (30 or 60), from its `pixel8_fps`
    /// export. Drives `time()` and the host's update/draw cadence.
    pub fps: u32,
    /// Fraction (0.0..1.0) of `update`'s fuel budget used last completed frame.
    last_update_cpu: f32,
    /// Fraction (0.0..1.0) of `draw`'s fuel budget used last completed frame.
    last_draw_cpu: f32,
    /// Real frames per second measured by the host frontend; `0.0` until fed.
    measured_fps: f32,
    rng: u64,
    /// Enforces `MAX_MEMORY` on linear-memory growth, including the initial
    /// allocation at instantiation.
    limits: StoreLimits,
}

impl HostState {
    fn new(assets: &Assets, audio: AudioHandle, storage: Storage) -> Self {
        Self {
            fb: Framebuffer::new(),
            input: InputState::default(),
            sprites: assets.sprites.clone(),
            map: assets.map.clone(),
            audio,
            storage,
            logs: Vec::new(),
            panic_message: None,
            frame: 0,
            fps: DEFAULT_FPS,
            last_update_cpu: 0.0,
            last_draw_cpu: 0.0,
            measured_fps: 0.0,
            rng: 0x2545_f491_4f6c_dd1d,
            limits: StoreLimitsBuilder::new()
                .memory_size(MAX_MEMORY)
                .trap_on_grow_failure(true)
                .build(),
        }
    }

    fn next_rand(&mut self) -> f32 {
        // xorshift64*; carts that need determinism can bring their own RNG.
        let mut x = self.rng;
        x ^= x >> 12;
        x ^= x << 25;
        x ^= x >> 27;
        self.rng = x;
        let bits = (x.wrapping_mul(0x2545_f491_4f6c_dd1d) >> 40) as u32;
        bits as f32 / (1u32 << 24) as f32
    }

    /// Feed the host frontend's measured frame rate, surfaced to carts via `fps`.
    pub fn set_measured_fps(&mut self, fps: f32) {
        self.measured_fps = fps;
    }

    /// The measured frame rate, or the cart's target rate until a frontend
    /// measures one. Keeps `fps()` sane on frontends that never measure.
    pub fn measured_fps_or_target(&self) -> f32 {
        if self.measured_fps > 0.0 {
            self.measured_fps
        } else {
            self.fps as f32
        }
    }

    fn seed_rand(&mut self, seed: u32) {
        // Force a nonzero xorshift state; all-zero is a fixed point.
        self.rng = (((seed as u64) << 32) | (seed as u64)) | 1;
    }
}

/// A cart-side runtime error, formatted for the error screen.
#[derive(Debug, Clone)]
pub struct RuntimeError {
    /// Which lifecycle call failed: "init", "update" or "draw".
    pub phase: &'static str,
    pub message: String,
}

impl std::fmt::Display for RuntimeError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Runtime error in {}:\n{}", self.phase, self.message)
    }
}

/// The console's half of the SDK's `World::step` — the `step_cast` import.
///
/// The cast arrives as `pixel8::physics::wire` records in cart memory. The engine that steps them
/// is the SDK's own — this crate depends on the SDK precisely so the two sides of the wire are one
/// implementation — run here natively, with the console's map and sprite sheet bound in directly
/// instead of through a host call apiece. The answers go back into the same records.
///
/// Anything malformed — a range off the end of cart memory, a length past the wire's capacity —
/// steps nothing, exactly as the rest of the ABI shrugs off bad arguments rather than trapping.
fn step_the_cast(caller: &mut Caller<'_, HostState>, ptr: u32, len: u32, config: u32) {
    use pixel8::{
        physics::{wire::Recast, Kinetic, World},
        BitFlags, SpriteFlag,
    };

    let Some(mut records) = read_cast(caller, ptr, len) else {
        return;
    };
    let members = len as usize;

    let mut cast: Vec<Recast> = records[..members].iter().map(Recast::of).collect();
    {
        let state = caller.data();
        // Every one of the eight bits names a flag, so the sheet's byte always converts.
        let flags = |sprite: u32| {
            BitFlags::<SpriteFlag>::from_bits(state.sprites.flags(sprite))
                .expect("all eight sprite-flag bits are flags")
        };
        // The SDK's own reading of the map, natively: off the map is nothing, and an on-map tile
        // answers with its cell's flags — cell 0 included, exactly as `Context::map_tile` has it.
        let tiles = |x: i16, y: i16| {
            if x < 0
                || y < 0
                || x as usize >= crate::assets::MAP_W
                || y as usize >= crate::assets::MAP_H
            {
                return BitFlags::empty();
            }
            flags(state.map.get(x as i32, y as i32) as u32)
        };
        // A world of no seats of its own: the cast is the one handed in, decoded out of cart
        // memory, so the host's world is nothing but the two words of configuration below.
        let world: World<0> = if config & 1 != 0 {
            World::new()
        } else {
            World::mapless()
        };
        let mut entities: Vec<&mut dyn Kinetic> =
            cast.iter_mut().map(|e| e as &mut dyn Kinetic).collect();
        world.step_hosted(&mut entities, tiles, |sprite| flags(sprite.0 as u32));
    }

    for (recast, record) in cast.iter().zip(records.iter_mut()) {
        recast.report(record);
    }
    // The answers go back into the very bytes each record arrived in, and only the answers:
    // everything the cart wrote and the step never decides — bounds, confines, flags — must come
    // back exactly as it went, for a raw ABI caller that reuses its buffer as much as for the
    // SDK. `Record::write` touches nothing but the output fields.
    let Some(memory) = caller
        .get_export("memory")
        .and_then(wasmi::Extern::into_memory)
    else {
        return;
    };
    let data = memory.data_mut(&mut *caller);
    let start = ptr as usize;
    if start + members * RECORD > data.len() {
        return;
    }
    for (slot, record) in records[..members].iter().enumerate() {
        let at = start + slot * RECORD;
        record.write(
            (&mut data[at..at + RECORD])
                .try_into()
                .expect("sized just above"),
        );
    }
}

/// The console's half of the SDK's `World::draw` — the `draw_cast` import.
///
/// The very same records `step_cast` answers into, read the same way and never written back — a
/// draw has nothing to report. What each one shows, and in which order, is the SDK's own
/// `wire::looks`; every look it walks over goes through the very blit the `sprite` import uses, so
/// the camera, the clip, the transparency and the draw palette hold for a cast exactly as they do
/// for a sprite drawn by hand.
///
/// Anything malformed draws nothing, exactly as `step_cast` steps nothing.
fn draw_the_cast(caller: &mut Caller<'_, HostState>, ptr: u32, len: u32, layers: u32) {
    use pixel8::{physics::wire::looks, BitFlags, SpriteFlag, SpriteId};

    let Some(records) = read_cast(caller, ptr, len) else {
        return;
    };
    // Every one of the eight bits names a flag, so the raw mask always converts — `map` takes its
    // layers the very same way.
    let layers = BitFlags::<SpriteFlag>::from_bits(layers as u8)
        .expect("all eight sprite-flag bits are flags");

    let HostState { fb, sprites, .. } = caller.data_mut();
    let sheet = &*sprites;
    let carried = |sprite: SpriteId| {
        BitFlags::<SpriteFlag>::from_bits(sheet.flags(sprite.0 as u32))
            .expect("all eight sprite-flag bits are flags")
    };
    for look in looks(&records[..len as usize], layers, carried) {
        fb.spr(
            sheet,
            u32::from(look.sprite.0),
            i32::from(look.x),
            i32::from(look.y),
            i32::from(look.width),
            i32::from(look.height),
            look.flip_x,
            look.flip_y,
        );
    }
}

/// The records out of cart memory, decoded: the read half `step_the_cast` and `draw_the_cast`
/// share, so what counts as a malformed call can never differ between the two imports.
///
/// `None` for a length past `CAP`, a missing `memory` export, or a range off the end of it —
/// nothing rather than a trap, exactly as the rest of the ABI answers a malformed call.
fn read_cast(caller: &Caller<'_, HostState>, ptr: u32, len: u32) -> Option<[Record; CAP]> {
    let members = len as usize;
    if members > CAP {
        return None;
    }
    let memory = caller
        .get_export("memory")
        .and_then(wasmi::Extern::into_memory)?;
    let data = memory.data(caller);
    let start = ptr as usize;
    let end = start.checked_add(members * RECORD)?;
    if end > data.len() {
        return None;
    }
    let mut records = [EMPTY; CAP];
    for (slot, record) in records[..members].iter_mut().enumerate() {
        let at = start + slot * RECORD;
        *record = Record::read(data[at..at + RECORD].try_into().expect("sized just above"));
    }
    Some(records)
}

fn read_guest_str(caller: &Caller<'_, HostState>, ptr: u32, len: u32) -> String {
    let Some(mem) = caller
        .get_export("memory")
        .and_then(wasmi::Extern::into_memory)
    else {
        return String::new();
    };
    let data = mem.data(caller);
    let start = ptr as usize;
    let end = start.saturating_add(len as usize).min(data.len());
    if start >= end {
        return String::new();
    }
    String::from_utf8_lossy(&data[start..end]).into_owned()
}

/// Copy `bytes` into guest memory at `ptr`. Writes nothing when the
/// destination range does not fit the guest's linear memory.
fn write_guest_bytes(caller: &mut Caller<'_, HostState>, ptr: u32, bytes: &[u8]) {
    let Some(mem) = caller
        .get_export("memory")
        .and_then(wasmi::Extern::into_memory)
    else {
        return;
    };
    let data = mem.data_mut(caller);
    let start = ptr as usize;
    let Some(end) = start.checked_add(bytes.len()) else {
        return;
    };
    if end <= data.len() {
        data[start..end].copy_from_slice(bytes);
    }
}

/// What the frame budget buys, pinned against the figures `docs/LIMITS.md` quotes.
#[cfg(test)]
mod fuel_costs;

#[cfg(test)]
mod tests {
    use super::*;
    use pixel8::physics::wire::{FLIP_X, FLIP_Y, HIDDEN, UNWORN};

    /// A minimal hand-written cart exercising the ABI from WAT.
    const TEST_CART: &str = r#"
        (module
          (import "pixel8" "clear" (func $cls (param i32)))
          (import "pixel8" "set_pixel" (func $pset (param i32 i32 i32)))
          (import "pixel8" "pixel" (func $pget (param i32 i32) (result i32)))
          (import "pixel8" "is_button_down" (func $btn (param i32) (result i32)))
          (import "pixel8" "print" (func $print (param i32 i32 i32 i32 i32) (result i32)))
          (import "pixel8" "log" (func $log (param i32 i32)))
          (memory (export "memory") 1)
          (data (i32.const 16) "hi from cart")
          (global $x (mut i32) (i32.const 5))
          (func (export "pixel8_init")
            (call $log (i32.const 16) (i32.const 12)))
          (func (export "pixel8_update")
            (if (i32.ne (call $btn (i32.const 1)) (i32.const 0))
              (then (global.set $x (i32.add (global.get $x) (i32.const 1))))))
          (func (export "pixel8_draw")
            (call $cls (i32.const 1))
            (call $pset (global.get $x) (i32.const 7) (i32.const 8))
            (drop (call $print (i32.const 16) (i32.const 2) (i32.const 0) (i32.const 0) (i32.const 7))))
        )
    "#;

    const LOOPING_CART: &str = r#"
        (module
          (func (export "pixel8_init"))
          (func (export "pixel8_update") (loop $l (br $l)))
          (func (export "pixel8_draw"))
        )
    "#;

    /// A raw ABI client of `step_cast`: one record at address 64, a prop with distinctive bytes
    /// in the input-only fields, stepped every update. `draw` copies four of those bytes into the
    /// framebuffer's top row, which is how the test reads them back out.
    ///
    /// The record: 24 zero bytes (position, velocity, drawn pixel, bounds corner), then bw = 5 at
    /// offset 24, zeros to sprite = 9 at 36, solid = 3 at 38, heeds = 0, meta = PROP at 40.
    const STEP_CAST_CART: &str = r#"
        (module
          (import "pixel8" "step_cast" (func $step (param i32 i32 i32)))
          (import "pixel8" "set_pixel" (func $pset (param i32 i32 i32)))
          (memory (export "memory") 1)
          (data (i32.const 64)
            "\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\05\00\00\00\00\00\00\00\00\00\00\00\09\00\03\00\01\00\00\00")
          (func (export "pixel8_init"))
          (func (export "pixel8_update")
            (call $step (i32.const 64) (i32.const 1) (i32.const 1)))
          (func (export "pixel8_draw")
            (call $pset (i32.const 0) (i32.const 0) (i32.load8_u (i32.const 88)))
            (call $pset (i32.const 1) (i32.const 0) (i32.load8_u (i32.const 100)))
            (call $pset (i32.const 2) (i32.const 0) (i32.load8_u (i32.const 102)))
            (call $pset (i32.const 3) (i32.const 0) (i32.load8_u (i32.const 104))))
        )
    "#;

    const FPS30_CART: &str = r#"
        (module
          (func (export "pixel8_init"))
          (func (export "pixel8_fps") (result i32) (i32.const 30))
          (func (export "pixel8_update"))
          (func (export "pixel8_draw")))
    "#;

    const MEM_EXPORT_CART: &str = r#"
        (module
          (func (export "pixel8_init"))
          (func (export "pixel8_update"))
          (func (export "pixel8_draw"))
          (func (export "pixel8_mem_used") (result i32) (i32.const 32768)))
    "#;

    /// Update loops ~10k times — well under the 131,072-fuel budget.
    const BUDGET_OK_CART: &str = r#"
        (module
          (func (export "pixel8_init"))
          (func (export "pixel8_update")
            (local $i i32)
            (local.set $i (i32.const 10000))
            (loop $l
              (local.set $i (i32.add (local.get $i) (i32.const -1)))
              (br_if $l (local.get $i))))
          (func (export "pixel8_draw")))
    "#;

    /// Update loops ~100k times — comfortably over the 131,072-fuel budget.
    const BUDGET_OVER_CART: &str = r#"
        (module
          (func (export "pixel8_init"))
          (func (export "pixel8_update")
            (local $i i32)
            (local.set $i (i32.const 100000))
            (loop $l
              (local.set $i (i32.add (local.get $i) (i32.const -1)))
              (br_if $l (local.get $i))))
          (func (export "pixel8_draw")))
    "#;

    /// 1-page initial + grow by 1 page = 2 pages = exactly the 128 K cap (allowed).
    const GROW_TO_CAP_CART: &str = r#"
        (module
          (memory (export "memory") 1)
          (func (export "pixel8_init"))
          (func (export "pixel8_update") (drop (memory.grow (i32.const 1))))
          (func (export "pixel8_draw")))
    "#;

    /// Update grows linear memory far past the 128 K cap (denied -> trap).
    const GROW_PAST_CAP_CART: &str = r#"
        (module
          (memory (export "memory") 1)
          (func (export "pixel8_init"))
          (func (export "pixel8_update") (drop (memory.grow (i32.const 10))))
          (func (export "pixel8_draw")))
    "#;

    /// Declares 3 pages (192 KiB) of initial memory — over the 128 K cap, so it
    /// is denied at instantiation before the cart ever runs.
    const HUGE_INITIAL_MEMORY_CART: &str = r#"
        (module
          (memory (export "memory") 3)
          (func (export "pixel8_init"))
          (func (export "pixel8_update"))
          (func (export "pixel8_draw")))
    "#;

    const PARITY_CART: &str = r#"
        (module
          (import "pixel8" "ellipse" (func $ovalo (param i32 i32 i32 i32 i32)))
          (import "pixel8" "ellipse_fill" (func $oval (param i32 i32 i32 i32 i32)))
          (import "pixel8" "set_transparent_color" (func $palt (param i32 i32)))
          (import "pixel8" "reset_transparency" (func $paltr))
          (import "pixel8" "remap_color" (func $pal (param i32 i32 i32)))
          (import "pixel8" "reset_palette" (func $palr))
          (import "pixel8" "set_fill_pattern" (func $fillp (param i32 i32 i32)))
          (import "pixel8" "set_sprite_pixel" (func $sset (param i32 i32 i32)))
          (import "pixel8" "sprite_pixel" (func $sget (param i32 i32) (result i32)))
          (import "pixel8" "sprite_stretch"
            (func $sspr (param i32 i32 i32 i32 i32 i32 i32 i32 i32 i32)))
          (import "pixel8" "seed_rng" (func $srand (param i32)))
          (import "pixel8" "set_pen_color" (func $color (param i32)))
          (import "pixel8" "set_cursor" (func $cursor (param i32 i32)))
          (import "pixel8" "print_pen" (func $printp (param i32 i32) (result i32)))
          (import "pixel8" "cpu_update" (func $cpuu (result f32)))
          (import "pixel8" "cpu_draw" (func $cpud (result f32)))
          (import "pixel8" "fps" (func $fps (result f32)))
          (memory (export "memory") 1)
          (data (i32.const 0) "hi")
          (func (export "pixel8_init"))
          (func (export "pixel8_update")
            (call $srand (i32.const 42))
            (call $sset (i32.const 0) (i32.const 0) (i32.const 9))
            (drop (call $sget (i32.const 0) (i32.const 0))))
          (func (export "pixel8_draw")
            (call $pal (i32.const 8) (i32.const 12) (i32.const 0))
            (call $palt (i32.const 0) (i32.const 1))
            (call $paltr)
            (call $fillp (i32.const 0) (i32.const 0) (i32.const 0))
            (call $color (i32.const 7))
            (call $cursor (i32.const 0) (i32.const 0))
            (drop (call $printp (i32.const 0) (i32.const 2)))
            (call $sspr (i32.const 0) (i32.const 0) (i32.const 8) (i32.const 8)
                        (i32.const 64) (i32.const 0) (i32.const 8) (i32.const 8)
                        (i32.const 0) (i32.const 0))
            (call $ovalo (i32.const 20) (i32.const 20) (i32.const 28) (i32.const 28)
                         (i32.const 7))
            (call $palr)
            (call $oval (i32.const 0) (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8))
            (drop (call $cpuu))
            (drop (call $cpud))
            (drop (call $fps))))
    "#;

    /// A cart whose `pixel8_update` body is `reps` copies of a counter bump: a knob
    /// for the size of a function body in BYTES, which is what the lazy translator
    /// bills for. The bump survives translation — a folded-away no-op would leave
    /// the body costing nothing to run and the tests below measuring nothing — while
    /// staying far cheaper per byte than the 7 fuel translating it would cost.
    fn bulky_update_cart(reps: usize) -> String {
        let body = "(global.set $n (i32.add (global.get $n) (i32.const 1)))".repeat(reps);
        format!(
            r#"(module
                 (global $n (mut i32) (i32.const 0))
                 (func (export "pixel8_init"))
                 (func (export "pixel8_update") {body})
                 (func (export "pixel8_draw")))"#
        )
    }

    fn load_test_vm(wat_src: &str) -> Result<GameVm> {
        let wasm = wat::parse_str(wat_src).unwrap();
        GameVm::load(
            &wasm,
            &Assets::default(),
            AudioHandle::dummy(),
            Storage::default(),
        )
    }

    /// One record's wire bytes, touching only what a draw reads — `rx`/`ry` at 16/18 (`i16` LE),
    /// `sprite` at 36 (`u16` LE), `meta` at 40, `span` at 43 — and zero everywhere else, the way
    /// a raw client that only ever sets a member's look would leave it.
    fn draw_record(rx: i16, ry: i16, sprite: u16, meta: u8, span: u8) -> [u8; RECORD] {
        let mut bytes = [0u8; RECORD];
        bytes[16..18].copy_from_slice(&rx.to_le_bytes());
        bytes[18..20].copy_from_slice(&ry.to_le_bytes());
        bytes[36..38].copy_from_slice(&sprite.to_le_bytes());
        bytes[40] = meta;
        bytes[43] = span;
        bytes
    }

    /// A raw ABI client of `draw_cast`: `records`' bytes concatenated into one data segment at
    /// address 64, drawn every frame with `layers`. `camera_xy`, given, is set with one `camera`
    /// call right before the draw.
    fn draw_cast_wat(
        records: &[[u8; RECORD]],
        layers: u32,
        camera_xy: Option<(i32, i32)>,
    ) -> String {
        let data: String = records
            .iter()
            .flatten()
            .map(|b| format!("\\{b:02x}"))
            .collect();
        let camera_call = match camera_xy {
            Some((x, y)) => format!("(call $camera (i32.const {x}) (i32.const {y}))"),
            None => String::new(),
        };
        format!(
            r#"(module
              (import "pixel8" "draw_cast" (func $draw (param i32 i32 i32)))
              (import "pixel8" "camera" (func $camera (param i32 i32)))
              (memory (export "memory") 1)
              (data (i32.const 64) "{data}")
              (func (export "pixel8_init"))
              (func (export "pixel8_update"))
              (func (export "pixel8_draw")
                {camera_call}
                (call $draw (i32.const 64) (i32.const {count}) (i32.const {layers}))))"#,
            count = records.len(),
        )
    }

    /// Like [`load_test_vm`], but with a caller-supplied `Assets` (a painted or flagged sheet)
    /// instead of the all-blank default.
    fn load_draw_vm(wat_src: &str, assets: &Assets) -> GameVm {
        let wasm = wat::parse_str(wat_src).unwrap();
        GameVm::load(&wasm, assets, AudioHandle::dummy(), Storage::default()).unwrap()
    }

    #[test]
    fn parity_imports_link_and_run() {
        let mut vm = load_test_vm(PARITY_CART).unwrap();
        vm.call_update().unwrap();
        vm.call_draw().unwrap();
        // sset wrote sprite-sheet pixel (0,0) = 9.
        assert_eq!(vm.state().sprites.get(0, 0), 9);
        // ellipse_fill drew color 8 after reset_palette, so no remap applies.
        assert_eq!(vm.state().fb.pget(4, 4), 8, "oval filled the box center");
    }

    #[test]
    fn step_cast_answers_in_place_and_leaves_the_cart_s_bytes_alone() {
        // The wire contract: only the answers — body, velocity, contacts — are written back, and
        // every input-only byte comes back exactly as the cart wrote it. A raw client that reuses
        // its buffer across updates depends on that; zeroing the inputs would turn its entity
        // into a zero-sized, unworn nothing on the second call.
        let mut vm = load_test_vm(STEP_CAST_CART).unwrap();
        for _ in 0..3 {
            vm.call_update().unwrap();
        }
        vm.call_draw().unwrap();
        let fb = &vm.state().fb;
        // The bytes draw copied out: bw at offset 24, sprite at 36, solid at 38, meta at 40.
        assert_eq!(fb.pget(0, 0), 5, "bw was not preserved");
        assert_eq!(fb.pget(1, 0), 9, "sprite was not preserved");
        assert_eq!(fb.pget(2, 0), 3, "solid was not preserved");
        assert_eq!(fb.pget(3, 0), 1, "meta was not preserved");
    }

    #[test]
    fn a_record_draws_its_cell_at_its_drawn_pixel() {
        let mut assets = Assets::default();
        assets.sprites.set(3, 4, 7); // cell 0's local (3, 4)
        let record = draw_record(50, 60, 0, 0, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[record], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(53, 64),
            7,
            "the painted pixel landed at rx+3, ry+4"
        );
        assert_eq!(
            vm.state().fb.pget(50, 60),
            0,
            "an unpainted pixel of the cell stayed clear"
        );
    }

    #[test]
    fn flip_x_and_flip_y_mirror_the_cell() {
        // An asymmetric cell: only diagonal corners painted, so a flip is unmistakable.
        let mut assets = Assets::default();
        assets.sprites.set(8, 0, 8); // cell 1's local (0, 0)
        assets.sprites.set(15, 7, 12); // cell 1's local (7, 7)

        let flipped_x = draw_record(0, 0, 1, FLIP_X, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[flipped_x], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(7, 0),
            8,
            "FLIP_X moved local (0,0) to the right edge"
        );
        assert_eq!(
            vm.state().fb.pget(0, 7),
            12,
            "FLIP_X moved local (7,7) to the left edge"
        );

        let flipped_y = draw_record(0, 0, 1, FLIP_Y, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[flipped_y], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(0, 7),
            8,
            "FLIP_Y moved local (0,0) to the bottom edge"
        );
        assert_eq!(
            vm.state().fb.pget(7, 0),
            12,
            "FLIP_Y moved local (7,7) to the top edge"
        );
    }

    #[test]
    fn a_span_of_one_extra_column_draws_the_neighbour_to_the_right() {
        let mut assets = Assets::default();
        assets.sprites.set(8, 0, 6); // cell 1's local (0, 0), immediately right of cell 0
        let record = draw_record(0, 0, 0, 0, 0x01);
        let mut vm = load_draw_vm(&draw_cast_wat(&[record], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(8, 0),
            6,
            "the block's second column is cell 1"
        );
    }

    #[test]
    fn a_span_of_one_extra_row_draws_the_neighbour_below() {
        let mut assets = Assets::default();
        assets.sprites.set(0, 8, 6); // cell 16's local (0, 0), immediately below cell 0
        let record = draw_record(0, 0, 0, 0, 0x10);
        let mut vm = load_draw_vm(&draw_cast_wat(&[record], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(0, 8),
            6,
            "the block's second row is cell 16"
        );
    }

    #[test]
    fn hidden_and_unworn_records_draw_nothing() {
        let mut assets = Assets::default();
        assets.sprites.set(0, 0, 9); // cell 0's local (0, 0): would be visible if drawn
                                     // And the cell an unworn record's `0xFFFF` would wrap to, were
                                     // it ever taken for a cell:
                                     // the blit reads its index modulo the sheet, which lands on
                                     // cell 255.
        assets.sprites.set(120, 120, 9);
        let hidden = draw_record(10, 10, 0, HIDDEN, 0);
        let unworn = draw_record(20, 20, UNWORN, 0, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[hidden, unworn], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(10, 10),
            0,
            "a hidden record is never drawn"
        );
        assert_eq!(
            vm.state().fb.pget(20, 20),
            0,
            "an unworn record is never drawn"
        );
    }

    #[test]
    fn layers_zero_draws_everything_and_a_mask_only_flagged_cells() {
        let mut assets = Assets::default();
        assets.sprites.set(0, 0, 4); // cell 0: unflagged
        assets.sprites.set(8, 0, 5); // cell 1: flagged
        assets.sprites.set_flag(1, 0, true);
        let plain = draw_record(0, 0, 0, 0, 0);
        let flagged = draw_record(20, 0, 1, 0, 0);

        let mut all = load_draw_vm(&draw_cast_wat(&[plain, flagged], 0, None), &assets);
        all.call_draw().unwrap();
        assert_eq!(
            all.state().fb.pget(0, 0),
            4,
            "layers 0 draws the unflagged cell too"
        );
        assert_eq!(
            all.state().fb.pget(20, 0),
            5,
            "layers 0 draws the flagged cell too"
        );

        let mut masked = load_draw_vm(&draw_cast_wat(&[plain, flagged], 1, None), &assets);
        masked.call_draw().unwrap();
        assert_eq!(
            masked.state().fb.pget(0, 0),
            0,
            "an unflagged cell is never picked by a mask"
        );
        assert_eq!(
            masked.state().fb.pget(20, 0),
            5,
            "the flagged cell survives the mask"
        );
    }

    #[test]
    fn a_later_record_is_drawn_over_an_earlier_one() {
        let mut assets = Assets::default();
        for py in 0..8 {
            for px in 0..8 {
                assets.sprites.set(16 + px, py, 5); // cell 2: solid color 5
            }
        }
        assets.sprites.set(24, 0, 9); // cell 3's local (0, 0); the rest of cell 3 stays 0
        let under = draw_record(40, 40, 2, 0, 0);
        let over = draw_record(40, 40, 3, 0, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[under, over], 0, None), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(40, 40),
            9,
            "the later record's opaque pixel wins"
        );
        assert_eq!(
            vm.state().fb.pget(41, 40),
            5,
            "the earlier record shows through elsewhere"
        );
    }

    #[test]
    fn the_camera_offsets_the_whole_cast() {
        let mut assets = Assets::default();
        assets.sprites.set(0, 0, 6);
        let record = draw_record(20, 20, 0, 0, 0);
        let mut vm = load_draw_vm(&draw_cast_wat(&[record], 0, Some((5, 5))), &assets);
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(15, 15),
            6,
            "the camera shifted the whole block"
        );
        assert_eq!(
            vm.state().fb.pget(20, 20),
            0,
            "nothing was drawn at the unshifted position"
        );
    }

    #[test]
    fn a_malformed_cast_draws_nothing_without_trapping() {
        // A drawable record leads the buffer, so a host that clamped the length instead of
        // refusing it would draw it.
        let mut assets = Assets::default();
        assets.sprites.set(0, 0, 9);
        let data: String = draw_record(10, 10, 0, 0, 0)
            .iter()
            .map(|b| format!("\\{b:02x}"))
            .collect();
        let bad_len = format!(
            r#"(module
              (import "pixel8" "draw_cast" (func $draw (param i32 i32 i32)))
              (memory (export "memory") 1)
              (data (i32.const 64) "{data}")
              (func (export "pixel8_init"))
              (func (export "pixel8_update"))
              (func (export "pixel8_draw")
                (call $draw (i32.const 64) (i32.const 65) (i32.const 0))))"#
        );
        let mut vm = load_draw_vm(&bad_len, &assets);
        assert!(vm.call_draw().is_ok(), "a length past CAP must not trap");
        assert_eq!(
            vm.state().fb.pget(10, 10),
            0,
            "a length past CAP must draw nothing, not the records that would fit"
        );

        // 1 page = 65536 bytes; a record is 44, so a pointer with fewer than 44 bytes left is a
        // range off the end of memory.
        let bad_ptr = r#"(module
              (import "pixel8" "draw_cast" (func $draw (param i32 i32 i32)))
              (memory (export "memory") 1)
              (func (export "pixel8_init"))
              (func (export "pixel8_update"))
              (func (export "pixel8_draw")
                (call $draw (i32.const 65500) (i32.const 1) (i32.const 0))))"#;
        let mut vm = load_draw_vm(bad_ptr, &Assets::default());
        assert!(
            vm.call_draw().is_ok(),
            "a range off the end of memory must not trap"
        );
    }

    #[test]
    fn abi_lifecycle_and_drawing() {
        let mut vm = load_test_vm(TEST_CART).unwrap();
        assert_eq!(vm.state_mut().logs.pop().as_deref(), Some("hi from cart"));

        vm.call_update().unwrap();
        vm.call_draw().unwrap();
        assert_eq!(vm.state().fb.pget(5, 7), 8, "set_pixel through ABI");
        assert_eq!(vm.state().fb.pget(0, 0), 7, "print drew a glyph pixel");

        // Hold right; update should move the pixel.
        vm.state_mut().input.set_button(1, true);
        vm.call_update().unwrap();
        vm.call_draw().unwrap();
        assert_eq!(
            vm.state().fb.pget(6, 7),
            8,
            "is_button_down(right) moved pixel"
        );
    }

    #[test]
    fn default_fps_is_60() {
        // A cart with no pixel8_fps export (e.g. hand-written WAT) takes the
        // default rate.
        let vm = load_test_vm(TEST_CART).unwrap();
        assert_eq!(vm.fps(), 60);
    }

    #[test]
    fn cart_can_select_30fps() {
        let vm = load_test_vm(FPS30_CART).unwrap();
        assert_eq!(vm.fps(), 30);
    }

    #[test]
    fn mem_used_reads_export_else_zero() {
        // A cart exporting pixel8_mem_used reports that many bytes used.
        let mut vm = load_test_vm(MEM_EXPORT_CART).unwrap();
        assert_eq!(vm.mem_used_bytes(), 32768);
        // A cart without the export reports 0 (hand-written / allocation-free).
        let mut vm2 = load_test_vm(TEST_CART).unwrap();
        assert_eq!(vm2.mem_used_bytes(), 0);
    }

    #[test]
    fn infinite_loop_is_trapped() {
        let mut vm = load_test_vm(LOOPING_CART).unwrap();
        let err = vm.call_update().unwrap_err();
        assert_eq!(err.phase, "update");
        assert!(err.message.contains("ran too long"), "{}", err.message);
    }

    #[test]
    fn missing_exports_is_a_load_error() {
        let wasm = wat::parse_str("(module)").unwrap();
        let err = match GameVm::load(
            &wasm,
            &Assets::default(),
            AudioHandle::dummy(),
            Storage::default(),
        ) {
            Err(e) => e,
            Ok(_) => panic!("empty module should not load"),
        };
        assert!(err.to_string().contains("pixel8_init"));
    }

    #[test]
    fn unknown_imports_are_rejected() {
        let wasm = wat::parse_str(
            r#"(module (import "env" "evil" (func))
                 (func (export "pixel8_init"))
                 (func (export "pixel8_update"))
                 (func (export "pixel8_draw")))"#,
        )
        .unwrap();
        assert!(GameVm::load(
            &wasm,
            &Assets::default(),
            AudioHandle::dummy(),
            Storage::default()
        )
        .is_err());
    }

    #[test]
    fn fuel_budget_allows_modest_work() {
        let mut vm = load_test_vm(BUDGET_OK_CART).unwrap();
        assert!(
            vm.call_update().is_ok(),
            "10k-iteration frame must fit the 128K-fuel budget"
        );
    }

    #[test]
    fn fuel_budget_traps_runaway_work() {
        let mut vm = load_test_vm(BUDGET_OVER_CART).unwrap();
        let err = vm.call_update().unwrap_err();
        assert!(err.message.contains("ran too long"), "got: {}", err.message);
    }

    #[test]
    fn oversized_function_body_still_runs() {
        // Lazy translation bills 7 fuel per byte of a function body the first time
        // it is entered, so any body over 131_072 / 7 = 18_724 bytes could never be
        // called: it burned the whole budget before executing an instruction and
        // surfaced as "ran too long". This body is ~84 KB — 588 K fuel to translate,
        // four and a half frame budgets — but only 36 K fuel to run, so with
        // translation off the meter it fits with room to spare.
        let mut vm = load_test_vm(&bulky_update_cart(12_000)).unwrap();
        assert!(
            vm.call_update().is_ok(),
            "an 84 KB function body must be callable, not billed as a runaway loop"
        );
        // Three fuel a repetition, so this also says the body was entered and run
        // rather than merely not trapping.
        let spent = vm.cpu_update() * FUEL_PER_CALL as f32;
        assert!(
            spent > 12_000.0,
            "all 12 K repetitions should have run, but the frame cost {spent} fuel"
        );
    }

    #[test]
    fn first_frame_costs_the_same_as_later_frames() {
        // A ~10 KB update body costs 4.2 K fuel to run but 69 K — over half the frame
        // budget — to translate at the lazy 7 fuel a byte, and lazily that charge
        // landed on whichever frame called it first. Translation now happens in
        // `Module::new`, off the meter, so frame 0 costs what every frame after it
        // does.
        let mut vm = load_test_vm(&bulky_update_cart(1_400)).unwrap();
        vm.call_update().unwrap();
        let first = vm.cpu_update();
        vm.call_update().unwrap();
        let steady = vm.cpu_update();
        assert!(steady > 0.0, "the frame has to cost something to compare");
        assert!(
            (first - steady).abs() < 1e-6,
            "frame 0 used {first} of the budget against a steady state of {steady}"
        );
    }

    #[test]
    fn eager_translation_of_a_cart_sized_module_is_quick() {
        // Eager translation moves the compiler off the frame budget and onto load,
        // which is only a good trade if load stays quick. A cart's wasm is capped at
        // 128 KiB, and translating a body that size measures in the low milliseconds
        // — the deadline here is three orders of magnitude above that, so it catches
        // a pathological translator without flaking on a loaded machine.
        let wasm = wat::parse_str(bulky_update_cart(128 * 1024 / 7).as_str()).unwrap();
        assert!(wasm.len() >= 128 * 1024, "the probe fills the cart cap");
        let started = std::time::Instant::now();
        let vm = GameVm::load(
            &wasm,
            &Assets::default(),
            AudioHandle::dummy(),
            Storage::default(),
        );
        let elapsed = started.elapsed();
        assert!(vm.is_ok(), "a cart-sized module must load");
        assert!(
            elapsed < std::time::Duration::from_secs(5),
            "translating a cart-sized module took {elapsed:?}"
        );
    }

    #[test]
    fn bad_cart_bytes_are_a_friendly_load_error() {
        // `Module::new` is where a cart's wasm is checked and, now that translation
        // is eager, where its function bodies are compiled as well. Whichever stage
        // rejects the bytes, the user gets one sentence rather than wasmi internals.
        let valid = wat::parse_str(TEST_CART).unwrap();
        let cases = [
            ("not wasm at all", b"definitely not a wasm module".to_vec()),
            ("a module cut in half", valid[..valid.len() / 2].to_vec()),
            (
                "a module missing its last byte",
                valid[..valid.len() - 1].to_vec(),
            ),
        ];
        for (name, bytes) in cases {
            let err = match GameVm::load(
                &bytes,
                &Assets::default(),
                AudioHandle::dummy(),
                Storage::default(),
            ) {
                Err(e) => e,
                Ok(_) => panic!("{name} should not load"),
            };
            assert!(
                err.to_string().contains("Invalid cart wasm"),
                "{name}: got {err}"
            );
        }
    }

    #[test]
    fn memory_growth_up_to_cap_is_allowed() {
        let mut vm = load_test_vm(GROW_TO_CAP_CART).unwrap();
        assert!(
            vm.call_update().is_ok(),
            "growing to exactly 128 K must succeed"
        );
    }

    #[test]
    fn memory_growth_past_cap_is_a_friendly_error() {
        let mut vm = load_test_vm(GROW_PAST_CAP_CART).unwrap();
        let err = vm.call_update().unwrap_err();
        assert!(
            err.message.contains("out of memory"),
            "got: {}",
            err.message
        );
    }

    #[test]
    fn oversized_initial_memory_is_rejected_at_load() {
        let wasm = wat::parse_str(HUGE_INITIAL_MEMORY_CART).unwrap();
        let err = match GameVm::load(
            &wasm,
            &Assets::default(),
            AudioHandle::dummy(),
            Storage::default(),
        ) {
            Err(e) => e,
            Ok(_) => panic!("oversized cart should not load"),
        };
        assert!(err.to_string().contains("128K of memory"), "got: {err}");
    }

    #[test]
    fn reports_cpu_usage_per_phase() {
        // BUDGET_OK_CART loops ~10k times in update and has an empty draw, so
        // the update phase must report a higher CPU fraction than draw.
        let mut vm = load_test_vm(BUDGET_OK_CART).unwrap();
        vm.call_update().unwrap();
        vm.call_draw().unwrap();
        let u = vm.cpu_update();
        let d = vm.cpu_draw();
        assert!(u > 0.0 && u < 1.0, "update cpu fraction in range: {u}");
        assert!(u > d, "heavy update beats empty draw: {u} vs {d}");
    }

    #[test]
    fn reports_memory_usage() {
        // TEST_CART declares one 64 KiB page of the 128 KiB cap.
        let vm = load_test_vm(TEST_CART).unwrap();
        let frac = vm.memory_used_fraction();
        assert!(
            (frac - 0.5).abs() < 0.01,
            "one page is half the cap: {frac}"
        );
    }

    /// Exercises all four storage imports from a cart. Init proves a
    /// checked remove (pixel (2,0)), wipes the store with `storage_clear`,
    /// and leaves `"score" = 42` behind. Draw probes every `storage_get`
    /// branch: value length at (0,0), missing key at (1,0), cleared key at
    /// (3,0), cap-0 size query at (4,0), too-small buffer leaving memory
    /// untouched at (5,0), and an exact-fit write at (6,0).
    const STORAGE_CART: &str = r#"
        (module
          (import "pixel8" "storage_set" (func $sset (param i32 i32 i32 i32) (result i32)))
          (import "pixel8" "storage_get" (func $sget (param i32 i32 i32 i32) (result i32)))
          (import "pixel8" "storage_remove" (func $srem (param i32 i32) (result i32)))
          (import "pixel8" "storage_clear" (func $sclr))
          (import "pixel8" "set_pixel" (func $pset (param i32 i32 i32)))
          (memory (export "memory") 1)
          (data (i32.const 0) "score")
          (data (i32.const 8) "42")
          (data (i32.const 16) "gone")
          (data (i32.const 24) "tmp")
          (data (i32.const 28) "1")
          (data (i32.const 63) "\05")
          (func (export "pixel8_init")
            ;; Removing an existing key returns 1 -> (2,0) = 5.
            (drop (call $sset (i32.const 24) (i32.const 3) (i32.const 28) (i32.const 1)))
            (if (i32.eq (call $srem (i32.const 24) (i32.const 3)) (i32.const 1))
              (then (call $pset (i32.const 2) (i32.const 0) (i32.const 5))))
            ;; Re-add "tmp", wipe everything, then store the real value.
            (drop (call $sset (i32.const 24) (i32.const 3) (i32.const 28) (i32.const 1)))
            (call $sclr)
            (drop (call $sset (i32.const 0) (i32.const 5) (i32.const 8) (i32.const 2))))
          (func (export "pixel8_update"))
          (func (export "pixel8_draw")
            ;; (0,0) = the JSON length of the "score" value (2).
            (call $pset (i32.const 0) (i32.const 0)
              (call $sget (i32.const 0) (i32.const 5) (i32.const 64) (i32.const 16)))
            ;; A key never stored returns -1 -> (1,0) = 7.
            (if (i32.eq (call $sget (i32.const 16) (i32.const 4) (i32.const 64) (i32.const 16))
                        (i32.const -1))
              (then (call $pset (i32.const 1) (i32.const 0) (i32.const 7))))
            ;; "tmp" was wiped by storage_clear -> (3,0) = 7.
            (if (i32.eq (call $sget (i32.const 24) (i32.const 3) (i32.const 64) (i32.const 16))
                        (i32.const -1))
              (then (call $pset (i32.const 3) (i32.const 0) (i32.const 7))))
            ;; Cap 0 still reports the length -> (4,0) = 2.
            (call $pset (i32.const 4) (i32.const 0)
              (call $sget (i32.const 0) (i32.const 5) (i32.const 64) (i32.const 0)))
            ;; A too-small buffer gets nothing written: the sentinel byte at
            ;; 63 survives a cap-1 read of the 2-byte value -> (5,0) = 5.
            (drop (call $sget (i32.const 0) (i32.const 5) (i32.const 63) (i32.const 1)))
            (call $pset (i32.const 5) (i32.const 0) (i32.load8_u (i32.const 63)))
            ;; An exactly-sized buffer is filled: "42" lands at 80..82 -> (6,0) = 7.
            (drop (call $sget (i32.const 0) (i32.const 5) (i32.const 80) (i32.const 2)))
            (if (i32.and
                  (i32.eq (i32.load8_u (i32.const 80)) (i32.const 52))
                  (i32.eq (i32.load8_u (i32.const 81)) (i32.const 50)))
              (then (call $pset (i32.const 6) (i32.const 0) (i32.const 7))))))
    "#;

    #[test]
    fn storage_abi_set_get_remove_clear() {
        let mut vm = load_test_vm(STORAGE_CART).unwrap();
        vm.call_update().unwrap();
        vm.call_draw().unwrap();
        // The host sees what the cart stored, as canonical JSON — and only
        // that: storage_clear wiped the earlier "tmp" key.
        assert_eq!(vm.state().storage.get_json("score").as_deref(), Some("42"));
        assert_eq!(vm.state().storage.get_json("tmp"), None);
        let px = |x| vm.state().fb.pget(x, 0);
        assert_eq!(px(0), 2, "storage_get returned the value length");
        assert_eq!(px(1), 7, "missing key returned -1");
        assert_eq!(px(2), 5, "removing an existing key returned 1");
        assert_eq!(px(3), 7, "storage_clear wiped the store");
        assert_eq!(px(4), 2, "cap-0 call sized the read");
        assert_eq!(px(5), 5, "too-small buffer left guest memory untouched");
        assert_eq!(px(6), 7, "exact-fit buffer was filled");
    }

    #[test]
    fn storage_persists_across_vm_loads() {
        let path =
            std::env::temp_dir().join(format!("pixel8_vm_storage_{}.json", std::process::id()));
        let _ = std::fs::remove_file(&path);
        let wasm = wat::parse_str(STORAGE_CART).unwrap();
        {
            let _vm = GameVm::load(
                &wasm,
                &Assets::default(),
                AudioHandle::dummy(),
                Storage::at_path(path.clone()),
            )
            .unwrap();
            // Dropping the VM drops (and saves) the storage.
        }
        let reloaded = Storage::at_path(path.clone());
        assert_eq!(reloaded.get_json("score").as_deref(), Some("42"));
        std::fs::remove_file(&path).unwrap();
    }

    /// A hand-written cart that only works out its rate while `pixel8_init` runs: what the
    /// documented query order — `pixel8_fps` once, after init — exists for.
    const FPS_FROM_INIT_CART: &str = r#"
        (module
          (global $rate (mut i32) (i32.const 0))
          (func (export "pixel8_init") (global.set $rate (i32.const 30)))
          (func (export "pixel8_fps") (result i32) (global.get $rate))
          (func (export "pixel8_update"))
          (func (export "pixel8_draw")))
    "#;

    #[test]
    fn a_carts_rate_may_be_worked_out_by_its_init() {
        // The raw-ABI contract: `pixel8_fps` is asked once, after `pixel8_init`, so a cart is
        // free to compute its rate from state init builds. (The SDK's `boot` is answered the
        // target cart-side, from the game's own constant, precisely so this order can stand.)
        let vm = load_test_vm(FPS_FROM_INIT_CART).unwrap();
        assert_eq!(vm.state().measured_fps_or_target(), 30.0);
    }

    #[test]
    fn fps_falls_back_to_target_until_measured() {
        // No frontend measurement yet: report the cart's target rate (30).
        let mut vm = load_test_vm(FPS30_CART).unwrap();
        assert_eq!(vm.state().measured_fps_or_target(), 30.0);
        // Once a frontend feeds a real rate, report that.
        vm.state_mut().set_measured_fps(58.0);
        assert_eq!(vm.state().measured_fps_or_target(), 58.0);
    }
}