oxide_browser/

capabilities.rs

//! Host capabilities and shared state for WebAssembly guests.
//!
//! This module defines [`HostState`] and the data structures the host and guest share
//! (console, canvas, timers, input, widgets, navigation, and more).
//! [`register_host_functions`] attaches the **`oxide`** Wasm import module to a Wasmtime
//! [`Linker`]: every host function that guest modules may call—`api_log`, `api_canvas_*`,
//! `api_storage_*`, `api_navigate`, audio and UI APIs, etc.—is registered there under the
//! import module name `oxide`.
//!
//! Guest code imports these symbols from `oxide`; implementations run on the host and
//! read or mutate the [`HostState`] held in the Wasmtime store attached to the linker.

use std::collections::{HashMap, HashSet};
use std::sync::atomic::AtomicBool;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
use image::GenericImageView;
use reqwest::header::{ACCEPT, CONTENT_TYPE};
use wasmtime::*;

use crate::audio_format;
use crate::bookmarks::SharedBookmarkStore;
use crate::download::DownloadManager;
use crate::engine::ModuleLoader;
use crate::history::SharedHistoryStore;
use crate::navigation::NavigationStack;
use crate::subtitle;
use crate::url as oxide_url;
use crate::video::{self, VideoPlaybackState};
use crate::video_format;

/// Per-channel audio state: a rodio Player plus metadata.
struct AudioChannel {
    player: rodio::Player,
    duration_ms: u64,
    looping: bool,
}

/// Multi-channel audio playback engine backed by [rodio](https://crates.io/crates/rodio).
///
/// Each logical channel has its own [`rodio::Player`] so guests can play overlapping
/// sounds (for example music on one channel and effects on another). The default channel
/// used by the single-channel `api_audio_*` imports is `0`.
pub struct AudioEngine {
    _device_sink: rodio::stream::MixerDeviceSink,
    channels: HashMap<u32, AudioChannel>,
}

impl AudioEngine {
    fn try_new() -> Option<Self> {
        let mut device_sink = rodio::DeviceSinkBuilder::open_default_sink().ok()?;
        device_sink.log_on_drop(false);
        Some(Self {
            _device_sink: device_sink,
            channels: HashMap::new(),
        })
    }

    fn ensure_channel(&mut self, id: u32) -> &mut AudioChannel {
        if !self.channels.contains_key(&id) {
            let player = rodio::Player::connect_new(self._device_sink.mixer());
            self.channels.insert(
                id,
                AudioChannel {
                    player,
                    duration_ms: 0,
                    looping: false,
                },
            );
        }
        self.channels.get_mut(&id).unwrap()
    }

    fn play_bytes_on(&mut self, channel_id: u32, data: Vec<u8>) -> bool {
        use rodio::Source;

        let cursor = std::io::Cursor::new(data);
        let reader = std::io::BufReader::new(cursor);
        let source = match rodio::Decoder::try_from(reader) {
            Ok(s) => s,
            Err(_) => return false,
        };

        let duration_ms = source
            .total_duration()
            .map(|d| d.as_millis() as u64)
            .unwrap_or(0);

        let ch = self.ensure_channel(channel_id);
        ch.player.clear();
        ch.duration_ms = duration_ms;

        if ch.looping {
            ch.player.append(source.repeat_infinite());
        } else {
            ch.player.append(source);
        }
        ch.player.play();
        true
    }
}

/// One-shot animation frame request. Queued by `api_request_animation_frame` and drained
/// every frame (before `on_frame`) in `LiveModule::tick`. Fires the guest `callback_id` via
/// the existing `on_timer` export exactly once.
#[derive(Clone, Debug)]
pub struct AnimationRequest {
    /// Host-assigned ID (for `cancel_animation_frame`). Mirrors timer ID scheme.
    pub id: u32,
    /// Guest-defined ID passed to `on_timer(callback_id)` when the frame fires.
    pub callback_id: u32,
}

/// Drain all pending animation frame requests (one-shot by design). Returns the
/// `callback_id`s to fire via `on_timer`. The queue is cleared after draining.
pub fn drain_animation_frame_requests(requests: &Arc<Mutex<Vec<AnimationRequest>>>) -> Vec<u32> {
    let mut guard = requests.lock().unwrap();
    let callback_ids: Vec<u32> = guard.iter().map(|r| r.callback_id).collect();
    guard.clear();
    callback_ids
}

/// All shared state between the browser host and a guest Wasm module (and dynamically loaded children).
///
/// Most fields are behind [`Arc`] and [`Mutex`] so the same state can be shared across
/// threads and nested module loads. Host code sets fields like [`HostState::memory`] and
/// [`HostState::current_url`] before or during execution; guest imports mutate the rest
/// through the registered `oxide` functions.
#[derive(Clone)]
pub struct HostState {
    /// Console log lines shown in the host UI, appended by [`console_log`] and `api_*` helpers.
    pub console: Arc<Mutex<Vec<ConsoleEntry>>>,
    /// Raster canvas: queued draw commands and decoded images for the current frame.
    pub canvas: Arc<Mutex<CanvasState>>,
    /// In-memory key/value session storage (string keys and values), similar to
    /// `sessionStorage`: it survives same-origin reloads but is cleared when the tab
    /// navigates to a different origin (see [`set_module_origin`]).
    pub storage: Arc<Mutex<HashMap<String, String>>>,
    /// Pending one-shot and interval timers; the host drains these and invokes `on_timer` on the guest.
    pub timers: Arc<Mutex<Vec<TimerEntry>>>,
    /// Pending one-shot animation frame requests. Drained every frame (before timers and `on_frame`)
    /// and fired via the existing `on_timer` export. See [`drain_animation_frame_requests`].
    pub animation_requests: Arc<Mutex<Vec<AnimationRequest>>>,
    /// Monotonic counter used to assign unique [`TimerEntry::id`] values for `api_set_timeout` / `api_set_interval`.
    pub timer_next_id: Arc<Mutex<u32>>,
    /// Last text written to or read from the clipboard via the guest API (when permitted).
    pub clipboard: Arc<Mutex<String>>,
    /// When `false`, `api_clipboard_read` / `api_clipboard_write` are blocked and log a warning.
    pub clipboard_allowed: Arc<Mutex<bool>>,
    /// Per-origin grants for sensitive APIs (camera, microphone, geolocation, screen capture)
    /// plus the prompt currently awaiting a user decision (rendered by the UI shell).
    pub permissions: crate::permissions::SharedPermissions,
    /// Manifest of the currently loaded app (`None` when the app ships without one).
    /// Set by the host on navigation; consulted for metadata and permission declarations.
    pub manifest: crate::manifest::SharedManifest,
    /// Optional embedded [`sled`] database for persistent per-origin key/value bytes (`api_kv_store_*`).
    pub kv_db: Option<Arc<sled::Db>>,
    /// The guest’s exported linear memory, used to read/write pointers passed to host imports.
    pub memory: Option<Memory>,
    /// Engine and limits used by `api_load_module` to fetch and instantiate child Wasm modules.
    pub module_loader: Option<Arc<ModuleLoader>>,
    /// Session history stack for `api_push_state`, `api_replace_state`, and back/forward navigation.
    pub navigation: Arc<Mutex<NavigationStack>>,
    /// Hit-test regions registered by the guest for link clicks in the canvas area.
    pub hyperlinks: Arc<Mutex<Vec<Hyperlink>>>,
    /// Set by guest `api_navigate` — consumed by the UI after module returns.
    pub pending_navigation: Arc<Mutex<Option<String>>>,
    /// The URL of the currently loaded module (set by the host before execution).
    pub current_url: Arc<Mutex<String>>,
    /// Stable origin of the currently loaded module (see [`crate::url::app_origin_of`]).
    ///
    /// Captured once per module load via [`set_module_origin`] and used to scope persistent
    /// KV storage and permissions. Unlike [`HostState::current_url`], this does not change
    /// when the guest calls `push_state` / `replace_state`.
    pub module_origin: Arc<Mutex<String>>,
    /// Input state polled by the guest each frame.
    pub input_state: Arc<Mutex<InputState>>,
    /// Widget commands issued by the guest during `on_frame`.
    pub widget_commands: Arc<Mutex<Vec<WidgetCommand>>>,
    /// Persistent widget values (checkbox, slider, text input state).
    pub widget_states: Arc<Mutex<HashMap<u32, WidgetValue>>>,
    /// Button IDs that were clicked during the last render pass.
    pub widget_clicked: Arc<Mutex<HashSet<u32>>>,
    /// Top-left corner of the canvas panel in GPUI screen coords.
    pub canvas_offset: Arc<Mutex<(f32, f32)>>,
    /// Persistent bookmark storage shared across tabs.
    pub bookmark_store: SharedBookmarkStore,
    /// Persistent browsing history shared across tabs.
    pub history_store: SharedHistoryStore,
    /// Audio playback engine (lazily initialised on first audio API call).
    pub audio: Arc<Mutex<Option<AudioEngine>>>,
    /// `Content-Type` from the last `api_audio_play_url` response (UTF-8), for codec negotiation introspection.
    pub last_audio_url_content_type: Arc<Mutex<String>>,
    /// Video playback, decode, subtitles, and HLS variant metadata (FFmpeg).
    pub video: Arc<Mutex<VideoPlaybackState>>,
    /// Last decoded video frame for picture-in-picture (RGBA, copied when PiP is enabled).
    pub video_pip_frame: Arc<Mutex<Option<DecodedImage>>>,
    /// Bumped when the PiP buffer is updated so the UI can refresh the floating texture.
    pub video_pip_serial: Arc<Mutex<u64>>,
    /// Camera, microphone, and screen capture (permission prompts + native APIs).
    pub media_capture: Arc<Mutex<crate::media_capture::MediaCaptureState>>,
    /// WebGPU-style GPU resource state (lazily initialised on first GPU API call).
    pub gpu: Arc<Mutex<Option<crate::gpu::GpuState>>>,
    /// WebRTC peer connections, data channels, and signaling (lazily initialised on first RTC call).
    pub rtc: Arc<Mutex<Option<crate::rtc::RtcState>>>,
    /// WebSocket connections (lazily initialised on first ws call).
    pub ws: Arc<Mutex<Option<crate::websocket::WsState>>>,
    /// MIDI input/output connections (lazily initialised on first midi_open call).
    pub midi: Arc<Mutex<Option<crate::midi::MidiState>>>,
    /// Streaming / non-blocking fetch state (lazily initialised on first `api_fetch_begin`).
    pub fetch: Arc<Mutex<Option<crate::fetch::FetchState>>>,
    /// Native file and folder picker handles. Paths never cross the sandbox;
    /// guests only see opaque `u32` handles allocated here.
    pub file_picker: Arc<Mutex<crate::file_picker::FilePickerState>>,
    /// Event listeners, queued events, and built-in event detector state
    /// (resize, focus, online/offline, touch, gamepad, drag-drop).
    pub events: Arc<Mutex<crate::events::EventState>>,
    /// Download manager for saving files and exporting canvas content.
    pub download_manager: DownloadManager,
    /// Whether the canvas currently has keyboard/window focus. Set by the UI
    /// layer each frame; consumed by the event system to fire `focus` /
    /// `blur` / `visibility_change`.
    pub focused: Arc<AtomicBool>,
    /// Per-frame GPUI [`WindowTextSystem`] used for synchronous text shaping
    /// from `api_canvas_measure_text`. The UI layer installs it right before
    /// calling `on_frame` and clears it immediately after, so this is only
    /// `Some` during guest frame callbacks.
    pub text_system: Arc<Mutex<Option<Arc<gpui::WindowTextSystem>>>>,
    /// Virtual width of guest content.
    pub content_width: Arc<Mutex<u32>>,
    /// Virtual height of guest content.
    pub content_height: Arc<Mutex<u32>>,
    /// Absolute scroll horizontal offset.
    pub scroll_x: Arc<Mutex<f32>>,
    /// Absolute scroll vertical offset.
    pub scroll_y: Arc<Mutex<f32>>,
    /// Background workers spawned by this guest, keyed by handle. Lazily
    /// initialised on the first `api_spawn_worker` call. See [`crate::worker`].
    pub workers: Arc<Mutex<Option<crate::worker::WorkerState>>>,
    /// Outbound message queue, present **only** inside a worker's own state.
    /// `api_worker_post` pushes here; the parent drains it via `api_worker_recv`.
    pub worker_outbox: Option<Arc<Mutex<std::collections::VecDeque<Vec<u8>>>>>,
    /// Message currently being delivered to a worker's `on_message` export,
    /// read by `api_worker_message_read` during the callback.
    pub worker_current_msg: Arc<Mutex<Option<Vec<u8>>>>,
}

/// A single console log line: local time, severity, and message text.
#[derive(Clone, Debug)]
pub struct ConsoleEntry {
    /// Time of day when the entry was recorded (`chrono` local format, e.g. `14:03:22.123`).
    pub timestamp: String,
    /// Severity bucket for styling in the host console.
    pub level: ConsoleLevel,
    /// UTF-8 message body.
    pub message: String,
}

/// Severity level for [`ConsoleEntry`] and [`console_log`].
#[derive(Clone, Debug)]
pub enum ConsoleLevel {
    /// Informational message (maps to `api_log`).
    Log,
    /// Warning (maps to `api_warn`).
    Warn,
    /// Error (maps to `api_error`).
    Error,
}

/// Current canvas snapshot for one frame: command list, dimensions, image atlas, and invalidation generation.
#[derive(Clone, Debug)]
pub struct CanvasState {
    /// Ordered draw operations accumulated since the last clear (or start of frame).
    pub commands: Vec<DrawCommand>,
    /// Canvas width in pixels.
    pub width: u32,
    /// Canvas height in pixels.
    pub height: u32,
    /// Decoded images indexed by position in this vector; [`DrawCommand::Image`] references them by `image_id`.
    pub images: Vec<DecodedImage>,
    /// Bumped when the canvas is cleared so the host can detect a full redraw.
    pub generation: u64,
}

/// An image decoded to RGBA8 pixels for compositing in the host canvas renderer.
#[derive(Clone, Debug)]
pub struct DecodedImage {
    /// Width in pixels.
    pub width: u32,
    /// Height in pixels.
    pub height: u32,
    /// Raw RGBA bytes, row-major (`width * height * 4` elements when full frame).
    pub pixels: Vec<u8>,
}

/// A single color stop inside a gradient (offset + RGBA).
#[derive(Clone, Debug)]
pub struct GradientStop {
    /// Position along the gradient axis, 0.0 to 1.0.
    pub offset: f32,
    pub r: u8,
    pub g: u8,
    pub b: u8,
    pub a: u8,
}

/// One canvas drawing operation produced by guest `api_canvas_*` imports and consumed by the host renderer.
#[derive(Clone, Debug)]
pub enum DrawCommand {
    /// Fill the entire canvas with a solid RGBA color and reset the command list (see `api_canvas_clear`).
    Clear { r: u8, g: u8, b: u8, a: u8 },
    /// Axis-aligned filled rectangle in canvas coordinates with RGBA fill.
    Rect {
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
    },
    /// Filled circle centered at `(cx, cy)` with the given radius and RGBA fill.
    Circle {
        cx: f32,
        cy: f32,
        radius: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
    },
    /// Text baseline position `(x, y)`, font size in pixels, RGBA color, and string payload.
    Text {
        x: f32,
        y: f32,
        size: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
        text: String,
    },
    /// Line from `(x1, y1)` to `(x2, y2)` with RGBA stroke color and stroke width in pixels.
    Line {
        x1: f32,
        y1: f32,
        x2: f32,
        y2: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
        thickness: f32,
    },
    /// Draw [`DecodedImage`] `image_id` from `images` into the axis-aligned rectangle `(x, y, w, h)`.
    Image {
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        image_id: usize,
    },
    /// Filled rounded rectangle with uniform corner radius.
    RoundedRect {
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        radius: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
    },
    /// Circular arc stroke from `start_angle` to `end_angle` (radians, CW from +X axis).
    Arc {
        cx: f32,
        cy: f32,
        radius: f32,
        start_angle: f32,
        end_angle: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
        thickness: f32,
    },
    /// Cubic Bézier curve stroke from `(x1,y1)` to `(x2,y2)` with two control points.
    Bezier {
        x1: f32,
        y1: f32,
        cp1x: f32,
        cp1y: f32,
        cp2x: f32,
        cp2y: f32,
        x2: f32,
        y2: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
        thickness: f32,
    },
    /// Linear gradient fill over an axis-aligned rectangle.
    Gradient {
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        /// 0 = linear, 1 = radial.
        kind: u8,
        /// Gradient axis start (linear) or center (radial) X, relative to the rect.
        ax: f32,
        /// Gradient axis start (linear) or center (radial) Y, relative to the rect.
        ay: f32,
        /// Gradient axis end X (linear) or ignored for radial.
        bx: f32,
        /// Gradient axis end Y (linear) or radius for radial.
        by: f32,
        /// Color stops: each entry is `(offset 0.0–1.0, r, g, b, a)`.
        stops: Vec<GradientStop>,
    },
    /// Push the current transform/clip/opacity state onto the stack.
    Save,
    /// Pop and restore the most recently saved state.
    Restore,
    /// Apply a 2D affine transform to subsequent draw commands (column-major: `[a,b,c,d,tx,ty]`).
    Transform {
        a: f32,
        b: f32,
        c: f32,
        d: f32,
        tx: f32,
        ty: f32,
    },
    /// Intersect the current clip with an axis-aligned rectangle.
    Clip { x: f32, y: f32, w: f32, h: f32 },
    /// Set layer opacity for subsequent draw commands (0.0 transparent – 1.0 opaque).
    Opacity { alpha: f32 },
    /// Text with explicit family, weight, style, and alignment. The baseline is
    /// at `(x, y)` for [`TextAlign::Left`]; for centre/right alignment, `x` is
    /// the right edge or centre respectively.
    TextEx {
        x: f32,
        y: f32,
        size: f32,
        r: u8,
        g: u8,
        b: u8,
        a: u8,
        /// CSS-style family name (e.g. `"Helvetica"`). Empty string falls back
        /// to the system UI font.
        family: String,
        /// Weight in the CSS range `100..=900`. `0` means the default (400).
        weight: u16,
        /// `0` = normal, `1` = italic, `2` = oblique.
        style: u8,
        /// `0` = left (x is left edge), `1` = centre (x is centre), `2` = right (x is right edge).
        align: u8,
        text: String,
    },
}

/// A scheduled timer: either a one-shot `setTimeout` or repeating `setInterval`.
#[derive(Clone, Debug)]
pub struct TimerEntry {
    /// Host-assigned id returned by `api_set_timeout` / `api_set_interval` for `api_clear_timer`.
    pub id: u32,
    /// Absolute time when this entry should fire next.
    pub fire_at: Instant,
    /// `None` for a one-shot timer; `Some(duration)` for an interval (rescheduled after each fire).
    pub interval: Option<Duration>,
    /// Guest-defined id passed to the exported `on_timer` callback when this timer fires.
    pub callback_id: u32,
}

/// Remove due timers from `timers`, collect each fired entry’s [`TimerEntry::callback_id`], and return them.
///
/// Compares each [`TimerEntry::fire_at`] against `Instant::now()`. **One-shot** entries
/// (`interval` is `None`) are removed from the vector after firing. **Interval** entries
/// are kept and their `fire_at` is advanced by `interval` so they fire again later. The
/// host typically calls the guest’s `on_timer` once per id in the returned vector.
pub fn drain_expired_timers(timers: &Arc<Mutex<Vec<TimerEntry>>>) -> Vec<u32> {
    let now = Instant::now();
    let mut guard = timers.lock().unwrap();
    let mut fired = Vec::new();
    let mut i = 0;
    while i < guard.len() {
        if guard[i].fire_at <= now {
            fired.push(guard[i].callback_id);
            if let Some(interval) = guard[i].interval {
                guard[i].fire_at = now + interval;
                i += 1;
            } else {
                guard.swap_remove(i);
            }
        } else {
            i += 1;
        }
    }
    fired
}

/// A clickable axis-aligned rectangle on the canvas that navigates to a URL when hit-tested.
///
/// Populated by `api_register_hyperlink` and cleared with `api_clear_hyperlinks`. Coordinates
/// are in the same space as canvas drawing (the host maps pointer position into this space).
#[derive(Clone, Debug)]
pub struct Hyperlink {
    /// Left edge of the hit region in canvas coordinates.
    pub x: f32,
    /// Top edge of the hit region in canvas coordinates.
    pub y: f32,
    /// Width of the hit region.
    pub w: f32,
    /// Height of the hit region.
    pub h: f32,
    /// Target URL (already resolved relative to the current page URL when registered).
    pub url: String,
}

/// Per-frame input snapshot from the host (GPUI) for guest polling via `api_mouse_*`, `api_key_*`, etc.
#[derive(Clone, Debug, Default)]
pub struct InputState {
    /// Pointer horizontal position in window/content coordinates before canvas offset subtraction in APIs.
    pub mouse_x: f32,
    /// Pointer vertical position in window/content coordinates before canvas offset subtraction in APIs.
    pub mouse_y: f32,
    /// Mouse buttons currently held: index 0 = primary, 1 = secondary, 2 = middle.
    pub mouse_buttons_down: [bool; 3],
    /// Mouse buttons that transitioned to pressed this frame (same indexing as `mouse_buttons_down`).
    pub mouse_buttons_clicked: [bool; 3],
    /// Key codes currently held (host-defined `u32` values, polled by `api_key_down`).
    pub keys_down: Vec<u32>,
    /// Key codes that registered a press this frame (`api_key_pressed`).
    pub keys_pressed: Vec<u32>,
    /// Shift modifier held this frame.
    pub modifiers_shift: bool,
    /// Control modifier held this frame.
    pub modifiers_ctrl: bool,
    /// Alt modifier held this frame.
    pub modifiers_alt: bool,
    /// Horizontal scroll delta for this frame.
    pub scroll_x: f32,
    /// Vertical scroll delta for this frame.
    pub scroll_y: f32,
}

/// Visual emphasis for buttons and badges; matches shadcn/ui variants.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum WidgetVariant {
    /// High-emphasis (light fill on dark theme).
    #[default]
    Default,
    /// Neutral fill on a muted surface.
    Secondary,
    /// Transparent fill with a visible border.
    Outline,
    /// Transparent fill, only shows on hover.
    Ghost,
    /// Red emphasis for destructive actions / errors.
    Destructive,
}

impl WidgetVariant {
    /// Decode the integer flag from SDK calls (`0=Default … 4=Destructive`).
    pub fn from_u32(v: u32) -> Self {
        match v {
            1 => Self::Secondary,
            2 => Self::Outline,
            3 => Self::Ghost,
            4 => Self::Destructive,
            _ => Self::Default,
        }
    }
}

/// UI control the guest requested for the current frame; the host GPUI layer renders these after canvas content.
///
/// Commands are queued during `on_frame`; stable `id` values tie widgets to [`WidgetValue`] state and click tracking.
#[derive(Clone, Debug)]
pub enum WidgetCommand {
    /// Clickable button with label; `api_ui_button` returns whether this `id` was clicked this pass.
    Button {
        id: u32,
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        label: String,
        variant: WidgetVariant,
    },
    /// Toggle with label; checked state lives in [`WidgetValue::Bool`] for this `id`.
    Checkbox {
        id: u32,
        x: f32,
        y: f32,
        label: String,
    },
    /// Horizontal slider between `min` and `max`; value stored in [`WidgetValue::Float`].
    Slider {
        id: u32,
        x: f32,
        y: f32,
        w: f32,
        min: f32,
        max: f32,
    },
    /// Single-line text field; current text stored in [`WidgetValue::Text`].
    TextInput {
        id: u32,
        x: f32,
        y: f32,
        w: f32,
        placeholder: String,
    },
    /// Multi-line text field with vertical scrolling.
    Textarea {
        id: u32,
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        placeholder: String,
    },
    /// Container with subtle border and rounded corners.
    Card {
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        title: String,
        description: String,
    },
    /// Small status pill.
    Badge {
        x: f32,
        y: f32,
        label: String,
        variant: WidgetVariant,
    },
    /// Pill-shaped on/off toggle; bool state in [`WidgetValue::Bool`].
    Switch {
        id: u32,
        x: f32,
        y: f32,
        label: String,
    },
    /// 1px divider (horizontal or vertical).
    Separator {
        x: f32,
        y: f32,
        length: f32,
        vertical: bool,
    },
    /// Horizontal progress bar; value 0.0..=1.0.
    Progress { x: f32, y: f32, w: f32, value: f32 },
    /// Static text label rendered with proper font shaping.
    Label {
        x: f32,
        y: f32,
        text: String,
        muted: bool,
        size: f32,
    },
}

/// Persistent control state for interactive widgets, keyed by widget `id` across frames.
#[derive(Clone, Debug)]
pub enum WidgetValue {
    /// Checkbox / switch on/off.
    Bool(bool),
    /// Slider current value.
    Float(f32),
    /// Text field contents.
    Text(String),
}

impl Default for HostState {
    fn default() -> Self {
        Self {
            console: Arc::new(Mutex::new(Vec::new())),
            canvas: Arc::new(Mutex::new(CanvasState {
                commands: Vec::new(),
                width: 800,
                height: 600,
                images: Vec::new(),
                generation: 0,
            })),
            storage: Arc::new(Mutex::new(HashMap::new())),
            timers: Arc::new(Mutex::new(Vec::new())),
            animation_requests: Arc::new(Mutex::new(Vec::new())),
            timer_next_id: Arc::new(Mutex::new(1)),
            clipboard: Arc::new(Mutex::new(String::new())),
            clipboard_allowed: Arc::new(Mutex::new(false)),
            permissions: Arc::new(Mutex::new(crate::permissions::PermissionsState::default())),
            manifest: Arc::new(Mutex::new(None)),
            kv_db: None,
            memory: None,
            module_loader: None,
            navigation: Arc::new(Mutex::new(NavigationStack::new())),
            hyperlinks: Arc::new(Mutex::new(Vec::new())),
            pending_navigation: Arc::new(Mutex::new(None)),
            current_url: Arc::new(Mutex::new(String::new())),
            module_origin: Arc::new(Mutex::new(String::new())),
            input_state: Arc::new(Mutex::new(InputState::default())),
            widget_commands: Arc::new(Mutex::new(Vec::new())),
            widget_states: Arc::new(Mutex::new(HashMap::new())),
            widget_clicked: Arc::new(Mutex::new(HashSet::new())),
            canvas_offset: Arc::new(Mutex::new((0.0, 0.0))),
            bookmark_store: crate::bookmarks::new_shared(),
            history_store: Arc::new(Mutex::new(None)),
            audio: Arc::new(Mutex::new(None)),
            last_audio_url_content_type: Arc::new(Mutex::new(String::new())),
            video: Arc::new(Mutex::new(VideoPlaybackState::default())),
            video_pip_frame: Arc::new(Mutex::new(None)),
            video_pip_serial: Arc::new(Mutex::new(0)),
            media_capture: Arc::new(Mutex::new(
                crate::media_capture::MediaCaptureState::default(),
            )),
            gpu: Arc::new(Mutex::new(None)),
            rtc: Arc::new(Mutex::new(None)),
            ws: Arc::new(Mutex::new(None)),
            midi: Arc::new(Mutex::new(None)),
            fetch: Arc::new(Mutex::new(None)),
            file_picker: Arc::new(Mutex::new(crate::file_picker::FilePickerState::default())),
            events: Arc::new(Mutex::new(crate::events::EventState::default())),
            download_manager: DownloadManager::new(),
            focused: Arc::new(AtomicBool::new(true)),
            text_system: Arc::new(Mutex::new(None)),
            content_width: Arc::new(Mutex::new(0)),
            content_height: Arc::new(Mutex::new(0)),
            scroll_x: Arc::new(Mutex::new(0.0)),
            scroll_y: Arc::new(Mutex::new(0.0)),
            workers: Arc::new(Mutex::new(None)),
            worker_outbox: None,
            worker_current_msg: Arc::new(Mutex::new(None)),
        }
    }
}

/// Captures the stable origin for a newly loaded module from its URL.
///
/// Called by the runtime once per load, before `start_app`. When the new origin differs from
/// the previous one, per-origin tab state is dropped: session storage is cleared (like
/// `sessionStorage` across origins in a shared tab) and live media-capture streams are
/// stopped so the new origin can't read camera frames or microphone samples opened under a
/// grant given to the previous origin.
pub fn set_module_origin(state: &HostState, url: &str) {
    let new_origin = crate::url::app_origin_of(url);
    let mut origin = state.module_origin.lock().unwrap();
    if *origin != new_origin {
        state.storage.lock().unwrap().clear();
        state.media_capture.lock().unwrap().reset();
        *origin = new_origin;
    }
}

#[allow(clippy::too_many_arguments)]
fn video_render_at(
    video: &Arc<Mutex<VideoPlaybackState>>,
    pip_frame: &Arc<Mutex<Option<DecodedImage>>>,
    pip_serial: &Arc<Mutex<u64>>,
    canvas: &Arc<Mutex<CanvasState>>,
    x: f32,
    y: f32,
    w: f32,
    h: f32,
) -> Result<(), String> {
    let t = {
        let g = video.lock().unwrap();
        g.current_position_ms()
    };
    let mut g = video.lock().unwrap();
    let player = g
        .player
        .as_mut()
        .ok_or_else(|| "no video loaded".to_string())?;
    let (pixels, pw, ph) = player.decode_frame_at(t)?;
    let pip_on = g.pip;
    let subtitle_text = subtitle::cue_text_at(&g.subtitles, t).map(|s| s.to_string());
    drop(g);

    let decoded = DecodedImage {
        width: pw,
        height: ph,
        pixels,
    };
    if pip_on {
        *pip_frame.lock().unwrap() = Some(decoded.clone());
        if let Ok(mut s) = pip_serial.lock() {
            *s = s.saturating_add(1);
        }
    }
    let mut canvas = canvas.lock().unwrap();
    let image_id = canvas.images.len();
    canvas.images.push(decoded);
    canvas.commands.push(DrawCommand::Image {
        x,
        y,
        w,
        h,
        image_id,
    });
    if let Some(text) = subtitle_text {
        let ty = (y + h - 24.0).max(y + 12.0);
        canvas.commands.push(DrawCommand::Text {
            x: x + 8.0,
            y: ty,
            size: 16.0,
            r: 255,
            g: 255,
            b: 255,
            a: 255,
            text,
        });
    }
    Ok(())
}

pub(crate) fn read_guest_string(
    memory: &Memory,
    store: &impl AsContext,
    ptr: u32,
    len: u32,
) -> Result<String> {
    let start = ptr as usize;
    let end = start
        .checked_add(len as usize)
        .context("guest string pointer arithmetic overflow")?;
    let data = memory
        .data(store)
        .get(start..end)
        .context("guest string out of bounds")?;
    String::from_utf8(data.to_vec()).context("guest string is not valid utf-8")
}

pub(crate) fn read_guest_bytes(
    memory: &Memory,
    store: &impl AsContext,
    ptr: u32,
    len: u32,
) -> Result<Vec<u8>> {
    let start = ptr as usize;
    let end = start
        .checked_add(len as usize)
        .context("guest buffer pointer arithmetic overflow")?;
    let data = memory
        .data(store)
        .get(start..end)
        .context("guest buffer out of bounds")?;
    Ok(data.to_vec())
}

pub(crate) fn write_guest_bytes(
    memory: &Memory,
    store: &mut impl AsContextMut,
    ptr: u32,
    bytes: &[u8],
) -> Result<()> {
    let start = ptr as usize;
    let end = start
        .checked_add(bytes.len())
        .context("guest write pointer arithmetic overflow")?;
    memory
        .data_mut(store)
        .get_mut(start..end)
        .context("guest buffer out of bounds")?
        .copy_from_slice(bytes);
    Ok(())
}

/// Clamp a guest-supplied font weight to the CSS `100..=900` range. A value of
/// `0` means "use the default" and maps to `400` (normal).
pub(crate) fn clamp_weight(weight: u32) -> u16 {
    if weight == 0 {
        400
    } else {
        weight.clamp(100, 900) as u16
    }
}

/// Build a [`gpui::Font`] from the guest-supplied family, weight, and style.
/// An empty family falls back to `.SystemUIFont`.
pub(crate) fn make_gpui_font(family: &str, weight: u16, style: u8) -> gpui::Font {
    let family_name = if family.is_empty() {
        ".SystemUIFont"
    } else {
        family
    };
    let mut f = gpui::font(family_name.to_string());
    f.weight = gpui::FontWeight(weight as f32);
    f.style = match style {
        1 => gpui::FontStyle::Italic,
        2 => gpui::FontStyle::Oblique,
        _ => gpui::FontStyle::Normal,
    };
    f
}

/// Append a [`ConsoleEntry`] with the current local timestamp to the shared console buffer.
///
/// Used by `api_log` / `api_warn` / `api_error` and by other host helpers that surface messages to the UI.
pub fn console_log(console: &Arc<Mutex<Vec<ConsoleEntry>>>, level: ConsoleLevel, message: String) {
    console.lock().unwrap().push(ConsoleEntry {
        timestamp: chrono::Local::now().format("%H:%M:%S%.3f").to_string(),
        level,
        message,
    });
}

fn audio_try_play(
    engine: &mut AudioEngine,
    channel: u32,
    data: Vec<u8>,
    format_hint: u32,
    console: &Arc<Mutex<Vec<ConsoleEntry>>>,
) -> bool {
    let sniffed = audio_format::sniff_audio_format(&data);
    if format_hint != 0
        && format_hint != audio_format::AUDIO_FORMAT_UNKNOWN
        && sniffed != audio_format::AUDIO_FORMAT_UNKNOWN
        && sniffed != format_hint
    {
        console_log(
            console,
            ConsoleLevel::Warn,
            format!("[AUDIO] Format hint {format_hint} does not match sniffed container {sniffed}"),
        );
    }
    engine.play_bytes_on(channel, data)
}

/// Minimal PDF writer — builds a PDF document byte-by-byte with standard
/// Type 1 fonts (no embedding needed). Supports text, rectangles, lines,
/// circles, arcs, beziers, and rounded rects.
fn render_canvas_to_pdf(canvas: &CanvasState, user_filename: &str) -> anyhow::Result<()> {
    use std::io::{Cursor, Seek, Write};

    const PT_PER_PX: f32 = 0.75;
    let w_pt = canvas.width as f32 * PT_PER_PX;
    let h_pt = canvas.height as f32 * PT_PER_PX;

    let mut buf = Cursor::new(Vec::new());
    let mut offsets: Vec<u64> = Vec::new();

    // Object 1: Catalog
    offsets.push(buf.stream_position()?);
    writeln!(buf, "1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj")?;

    // Object 2: Pages
    offsets.push(buf.stream_position()?);
    writeln!(buf, "2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj")?;

    // Object 5: Font (Helvetica)
    offsets.push(buf.stream_position()?);
    writeln!(
        buf,
        "5 0 obj<</Type/Font/Subtype/Type1/BaseFont/Helvetica>>endobj"
    )?;

    let mut content = Vec::new();
    let flip_y = |y: f32| -> f32 { h_pt - y };

    for cmd in &canvas.commands {
        match cmd {
            DrawCommand::Clear { r, g, b, a: _ } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                write!(content, "{rf:.3} {gf:.3} {bf:.3} rg ")?;
                writeln!(content, "0 0 {w_pt:.1} {h_pt:.1} re f")?;
            }
            DrawCommand::Rect {
                x,
                y,
                w: rw,
                h: rh,
                r,
                g,
                b,
                a: _,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let xp = *x * PT_PER_PX;
                let yp = flip_y((*y + *rh) * PT_PER_PX);
                let wp = *rw * PT_PER_PX;
                let hp = *rh * PT_PER_PX;
                write!(content, "{rf:.3} {gf:.3} {bf:.3} rg ")?;
                writeln!(content, "{xp:.1} {yp:.1} {wp:.1} {hp:.1} re f")?;
            }
            DrawCommand::Text {
                x,
                y,
                size,
                r,
                g,
                b,
                a: _,
                text,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let font_size = *size * PT_PER_PX;
                let xp = *x * PT_PER_PX;
                let yp = flip_y(*y * PT_PER_PX);
                let escaped = escape_pdf_string(text);
                write!(content, "BT {rf:.3} {gf:.3} {bf:.3} rg ")?;
                writeln!(
                    content,
                    "/F1 {font_size:.1} Tf {xp:.1} {yp:.1} Td ({escaped}) Tj ET"
                )?;
            }
            DrawCommand::Line {
                x1,
                y1,
                x2,
                y2,
                r,
                g,
                b,
                a: _,
                thickness,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let tp = *thickness * PT_PER_PX;
                let x1p = *x1 * PT_PER_PX;
                let y1p = flip_y(*y1 * PT_PER_PX);
                let x2p = *x2 * PT_PER_PX;
                let y2p = flip_y(*y2 * PT_PER_PX);
                write!(content, "{rf:.3} {gf:.3} {bf:.3} RG {tp:.1} w ")?;
                writeln!(content, "{x1p:.1} {y1p:.1} m {x2p:.1} {y2p:.1} l S")?;
            }
            DrawCommand::Circle {
                cx,
                cy,
                radius,
                r,
                g,
                b,
                a: _,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let cxp = *cx * PT_PER_PX;
                let cyp = flip_y(*cy * PT_PER_PX);
                let rp = *radius * PT_PER_PX;
                let k = 0.5522848f32;
                let kr = k * rp;
                write!(content, "{rf:.3} {gf:.3} {bf:.3} rg ")?;
                write!(content, "{:.1} {:.1} m ", cxp + rp, cyp)?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    cxp + rp,
                    cyp + kr,
                    cxp + kr,
                    cyp + rp,
                    cxp,
                    cyp + rp
                )?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    cxp - kr,
                    cyp + rp,
                    cxp - rp,
                    cyp + kr,
                    cxp - rp,
                    cyp
                )?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    cxp - rp,
                    cyp - kr,
                    cxp - kr,
                    cyp - rp,
                    cxp,
                    cyp - rp
                )?;
                writeln!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c f",
                    cxp + kr,
                    cyp - rp,
                    cxp + rp,
                    cyp - kr,
                    cxp + rp,
                    cyp
                )?;
            }
            DrawCommand::RoundedRect {
                x,
                y,
                w: rw,
                h: rh,
                radius,
                r,
                g,
                b,
                a: _,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let xp = *x * PT_PER_PX;
                let yp = flip_y(*y * PT_PER_PX);
                let wp = *rw * PT_PER_PX;
                let hp = *rh * PT_PER_PX;
                let rad = (*radius * PT_PER_PX).min(wp / 2.0).min(hp / 2.0);
                let k = 0.5522848f32;
                let kr = k * rad;
                let x0 = xp;
                let y0 = yp - hp;
                let x1 = xp + wp;
                let y1 = yp;
                write!(content, "{rf:.3} {gf:.3} {bf:.3} rg ")?;
                write!(content, "{:.1} {:.1} m ", x0 + rad, y0)?;
                write!(content, "{:.1} {:.1} l ", x1 - rad, y0)?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    x1 - rad + kr,
                    y0,
                    x1,
                    y0 + rad - kr,
                    x1,
                    y0 + rad
                )?;
                write!(content, "{:.1} {:.1} l ", x1, y1 - rad)?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    x1,
                    y1 - rad + kr,
                    x1 - rad + kr,
                    y1,
                    x1 - rad,
                    y1
                )?;
                write!(content, "{:.1} {:.1} l ", x0 + rad, y1)?;
                write!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c ",
                    x0 + rad - kr,
                    y1,
                    x0,
                    y1 - rad + kr,
                    x0,
                    y1 - rad
                )?;
                write!(content, "{:.1} {:.1} l ", x0, y0 + rad)?;
                writeln!(
                    content,
                    "{:.1} {:.1} {:.1} {:.1} {:.1} {:.1} c f",
                    x0,
                    y0 + rad - kr,
                    x0 + rad - kr,
                    y0,
                    x0 + rad,
                    y0
                )?;
            }
            DrawCommand::Arc {
                cx,
                cy,
                radius,
                start_angle,
                end_angle,
                r,
                g,
                b,
                a: _,
                thickness,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let tp = *thickness * PT_PER_PX;
                let cxp = *cx * PT_PER_PX;
                let cyp = flip_y(*cy * PT_PER_PX);
                let rp = *radius * PT_PER_PX;
                let segs = 32u32;
                let angle_range = if *end_angle > *start_angle {
                    *end_angle - *start_angle
                } else {
                    *end_angle + 2.0 * std::f32::consts::PI - *start_angle
                };
                write!(content, "{rf:.3} {gf:.3} {bf:.3} RG {tp:.1} w ")?;
                let a0 = *start_angle;
                let mut first = true;
                for i in 0..=segs {
                    let a = a0 + angle_range * i as f32 / segs as f32;
                    let px = cxp + rp * a.cos();
                    let py = cyp - rp * a.sin();
                    if first {
                        write!(content, "{px:.1} {py:.1} m ")?;
                        first = false;
                    } else {
                        write!(content, "{px:.1} {py:.1} l ")?;
                    }
                }
                writeln!(content, "S")?;
            }
            DrawCommand::Bezier {
                x1,
                y1,
                cp1x,
                cp1y,
                cp2x,
                cp2y,
                x2,
                y2,
                r,
                g,
                b,
                a: _,
                thickness,
            } => {
                let rf = *r as f32 / 255.0;
                let gf = *g as f32 / 255.0;
                let bf = *b as f32 / 255.0;
                let tp = *thickness * PT_PER_PX;
                let x1p = *x1 * PT_PER_PX;
                let y1p = flip_y(*y1 * PT_PER_PX);
                let cp1xp = *cp1x * PT_PER_PX;
                let cp1yp = flip_y(*cp1y * PT_PER_PX);
                let cp2xp = *cp2x * PT_PER_PX;
                let cp2yp = flip_y(*cp2y * PT_PER_PX);
                let x2p = *x2 * PT_PER_PX;
                let y2p = flip_y(*y2 * PT_PER_PX);
                write!(content, "{rf:.3} {gf:.3} {bf:.3} RG {tp:.1} w ")?;
                writeln!(content, "{x1p:.1} {y1p:.1} m {cp1xp:.1} {cp1yp:.1} {cp2xp:.1} {cp2yp:.1} {x2p:.1} {y2p:.1} c S")?;
            }
            DrawCommand::Image { .. }
            | DrawCommand::Gradient { .. }
            | DrawCommand::TextEx { .. }
            | DrawCommand::Save
            | DrawCommand::Restore
            | DrawCommand::Transform { .. }
            | DrawCommand::Clip { .. }
            | DrawCommand::Opacity { .. } => {}
        }
    }

    // Object 4: Page content stream
    let content_len = content.len();
    offsets.push(buf.stream_position()?);
    writeln!(buf, "4 0 obj<</Length {content_len}>>stream")?;
    buf.write_all(&content)?;
    writeln!(buf)?;
    writeln!(buf, "endstream")?;
    writeln!(buf, "endobj")?;

    // Object 3: Page
    offsets.push(buf.stream_position()?);
    writeln!(
        buf,
        "3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 {w_pt:.1} {h_pt:.1}]/Contents 4 0 R/Resources<</Font<</F1 5 0 R>>>>>>endobj"
    )?;

    // xref table
    let xref_offset = buf.stream_position()?;
    let obj_count = offsets.len() as u64 + 1;
    writeln!(buf, "xref\n0 {obj_count}\n0000000000 65535 f ")?;
    for off in &offsets {
        writeln!(buf, "{off:010} 00000 n ")?;
    }

    write!(
        buf,
        "trailer<</Size {obj_count}/Root 1 0 R>>\nstartxref\n{xref_offset}\n%%EOF\n"
    )?;

    let pdf_bytes = buf.into_inner();
    let dest_dir = dirs::download_dir()
        .unwrap_or_else(|| dirs::home_dir().unwrap_or_else(|| std::path::PathBuf::from(".")));
    let name_to_save = if user_filename.trim().is_empty() {
        format!(
            "{}",
            chrono::Local::now().format("oxide-canvas-%Y%m%d-%H%M%S.pdf")
        )
    } else if user_filename.to_lowercase().ends_with(".pdf") {
        user_filename.to_string()
    } else {
        format!("{}.pdf", user_filename)
    };
    let dest = crate::download::unique_path(&dest_dir, &name_to_save);
    std::fs::write(&dest, &pdf_bytes)?;
    Ok(())
}

fn escape_pdf_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for ch in s.chars() {
        match ch {
            '(' => out.push_str("\\("),
            ')' => out.push_str("\\)"),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if (c as u32) < 0x80 => out.push(c),
            _ => {} // Skip non-ASCII — standard PDF fonts only support Latin-1
        }
    }
    out
}

/// Register every `oxide` import on `linker` so guest modules can link against them.
///
/// This wires dozens of functions (console, canvas, storage, clipboard, timers, HTTP,
/// dynamic module loading, crypto helpers, navigation, hyperlinks, input, audio, UI
/// widgets, etc.) under the Wasm import module name **`oxide`**. Each closure captures
/// [`Caller`] to read [`HostState`] from the store: guest pointers are resolved through
/// [`HostState::memory`], and shared handles (`Arc<Mutex<…>>`) are updated in place.
///
/// Call this once when building the linker for a main or child instance; the dynamic loader
/// path also invokes it when instantiating a child module (see the `api_load_module` import).
pub fn register_host_functions(linker: &mut Linker<HostState>) -> Result<()> {
    // ── Console ──────────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_log",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let msg = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            console_log(&caller.data().console, ConsoleLevel::Log, msg);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_warn",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let msg = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            console_log(&caller.data().console, ConsoleLevel::Warn, msg);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_error",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let msg = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            console_log(&caller.data().console, ConsoleLevel::Error, msg);
        },
    )?;

    // ── Geolocation ──────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_get_location",
        // Returns bytes written (>= 0), `-1` when blocked (by the user or an undeclared
        // manifest permission), or `PERMISSION_PENDING` while the prompt awaits a decision.
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> i32 {
            if !crate::manifest::manifest_allows(
                &caller.data().manifest,
                crate::permissions::PermissionKind::Geolocation,
            ) {
                return -1; // not declared in the app manifest — denied without a prompt
            }
            let origin = caller.data().module_origin.lock().unwrap().clone();
            match crate::permissions::check_or_request(
                &caller.data().permissions,
                &origin,
                crate::permissions::PermissionKind::Geolocation,
            ) {
                crate::permissions::PermissionStatus::Granted => {}
                crate::permissions::PermissionStatus::Denied => return -1,
                // Prompt still showing — the guest should retry on a later frame.
                crate::permissions::PermissionStatus::Pending => {
                    return crate::permissions::PERMISSION_PENDING
                }
            }
            let location = "37.7749,-122.4194"; // mock: San Francisco
            let bytes = location.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as i32
        },
    )?;

    // ── File Picker ──────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_upload_file",
        |mut caller: Caller<'_, HostState>,
         name_ptr: u32,
         name_cap: u32,
         data_ptr: u32,
         data_cap: u32|
         -> u64 {
            let dialog = rfd::FileDialog::new()
                .set_title("Oxide: Select a file to upload")
                .pick_file();

            match dialog {
                Some(path) => {
                    let file_name = path
                        .file_name()
                        .map(|n| n.to_string_lossy().to_string())
                        .unwrap_or_default();
                    let file_data = std::fs::read(&path).unwrap_or_default();

                    let mem = caller.data().memory.expect("memory not set");

                    let name_bytes = file_name.as_bytes();
                    let name_written = name_bytes.len().min(name_cap as usize);
                    write_guest_bytes(&mem, &mut caller, name_ptr, &name_bytes[..name_written])
                        .ok();

                    let data_written = file_data.len().min(data_cap as usize);
                    write_guest_bytes(&mem, &mut caller, data_ptr, &file_data[..data_written]).ok();

                    ((name_written as u64) << 32) | (data_written as u64)
                }
                None => 0,
            }
        },
    )?;

    // ── Canvas Drawing ───────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_canvas_clear",
        |caller: Caller<'_, HostState>, r: u32, g: u32, b: u32, a: u32| {
            let mut canvas = caller.data().canvas.lock().unwrap();
            canvas.commands.clear();
            canvas.images.clear();
            canvas.generation += 1;
            canvas.commands.push(DrawCommand::Clear {
                r: r as u8,
                g: g as u8,
                b: b as u8,
                a: a as u8,
            });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_rect",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Rect {
                    x,
                    y,
                    w,
                    h,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_circle",
        |caller: Caller<'_, HostState>,
         cx: f32,
         cy: f32,
         radius: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Circle {
                    cx,
                    cy,
                    radius,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_text",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         size: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32,
         txt_ptr: u32,
         txt_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let text = read_guest_string(&mem, &caller, txt_ptr, txt_len).unwrap_or_default();
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Text {
                    x,
                    y,
                    size,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                    text,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_text_ex",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         size: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32,
         fam_ptr: u32,
         fam_len: u32,
         weight: u32,
         style: u32,
         align: u32,
         txt_ptr: u32,
         txt_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let family = read_guest_string(&mem, &caller, fam_ptr, fam_len).unwrap_or_default();
            let text = read_guest_string(&mem, &caller, txt_ptr, txt_len).unwrap_or_default();
            let weight = clamp_weight(weight);
            let style = (style.min(2)) as u8;
            let align = (align.min(2)) as u8;
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::TextEx {
                    x,
                    y,
                    size,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                    family,
                    weight,
                    style,
                    align,
                    text,
                });
        },
    )?;

    // Synchronous text measurement. Writes 3 × f32 (width, ascent, descent) in
    // pixels to `out_ptr` and returns 1 on success; returns 0 if the text
    // system isn't available yet or the out buffer is invalid.
    linker.func_wrap(
        "oxide",
        "api_canvas_measure_text",
        |mut caller: Caller<'_, HostState>,
         size: f32,
         fam_ptr: u32,
         fam_len: u32,
         weight: u32,
         style: u32,
         txt_ptr: u32,
         txt_len: u32,
         out_ptr: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let family = read_guest_string(&mem, &caller, fam_ptr, fam_len).unwrap_or_default();
            let text = read_guest_string(&mem, &caller, txt_ptr, txt_len).unwrap_or_default();
            let weight = clamp_weight(weight);
            let style = (style.min(2)) as u8;
            let ts = caller.data().text_system.lock().unwrap().clone();
            let Some(ts) = ts else { return 0 };
            let font = make_gpui_font(&family, weight, style);
            let run = gpui::TextRun {
                len: text.len(),
                font,
                color: gpui::rgba(0xffffffff).into(),
                background_color: None,
                underline: None,
                strikethrough: None,
            };
            let layout = ts.layout_line(&text, gpui::px(size), &[run], None);
            let mut buf = [0u8; 12];
            buf[0..4].copy_from_slice(&f32::from(layout.width).to_le_bytes());
            buf[4..8].copy_from_slice(&f32::from(layout.ascent).to_le_bytes());
            buf[8..12].copy_from_slice(&f32::from(layout.descent).to_le_bytes());
            if write_guest_bytes(&mem, &mut caller, out_ptr, &buf).is_ok() {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_line",
        |caller: Caller<'_, HostState>,
         x1: f32,
         y1: f32,
         x2: f32,
         y2: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32,
         thickness: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Line {
                    x1,
                    y1,
                    x2,
                    y2,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                    thickness,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_dimensions",
        |caller: Caller<'_, HostState>| -> u64 {
            let canvas = caller.data().canvas.lock().unwrap();
            ((canvas.width as u64) << 32) | (canvas.height as u64)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_set_content_size",
        |caller: Caller<'_, HostState>, w: u32, h: u32| {
            *caller.data().content_width.lock().unwrap() = w;
            *caller.data().content_height.lock().unwrap() = h;
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_get_scroll_position",
        |caller: Caller<'_, HostState>| -> u64 {
            let x = *caller.data().scroll_x.lock().unwrap();
            let y = *caller.data().scroll_y.lock().unwrap();
            ((x.to_bits() as u64) << 32) | (y.to_bits() as u64)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_set_scroll_position",
        |caller: Caller<'_, HostState>, x: f32, y: f32| {
            let content_w = *caller.data().content_width.lock().unwrap();
            let content_h = *caller.data().content_height.lock().unwrap();

            let viewport_w = caller.data().canvas.lock().unwrap().width;
            let viewport_h = caller.data().canvas.lock().unwrap().height;

            let max_x = (content_w as f32 - viewport_w as f32).max(0.0);
            let max_y = (content_h as f32 - viewport_h as f32).max(0.0);

            *caller.data().scroll_x.lock().unwrap() = x.clamp(0.0, max_x);
            *caller.data().scroll_y.lock().unwrap() = y.clamp(0.0, max_y);
        },
    )?;

    // ── Extended Shape Primitives ─────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_canvas_rounded_rect",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         radius: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::RoundedRect {
                    x,
                    y,
                    w,
                    h,
                    radius,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_arc",
        |caller: Caller<'_, HostState>,
         cx: f32,
         cy: f32,
         radius: f32,
         start_angle: f32,
         end_angle: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32,
         thickness: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Arc {
                    cx,
                    cy,
                    radius,
                    start_angle,
                    end_angle,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                    thickness,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_bezier",
        |caller: Caller<'_, HostState>,
         x1: f32,
         y1: f32,
         cp1x: f32,
         cp1y: f32,
         cp2x: f32,
         cp2y: f32,
         x2: f32,
         y2: f32,
         r: u32,
         g: u32,
         b: u32,
         a: u32,
         thickness: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Bezier {
                    x1,
                    y1,
                    cp1x,
                    cp1y,
                    cp2x,
                    cp2y,
                    x2,
                    y2,
                    r: r as u8,
                    g: g as u8,
                    b: b as u8,
                    a: a as u8,
                    thickness,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_gradient",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         kind: u32,
         ax: f32,
         ay: f32,
         bx: f32,
         by: f32,
         stops_ptr: u32,
         stops_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let bytes = read_guest_bytes(&mem, &caller, stops_ptr, stops_len).unwrap_or_default();
            let mut stops = Vec::new();
            // Each stop is 8 bytes: f32 offset + u8 r + u8 g + u8 b + u8 a (packed).
            let mut i = 0;
            while i + 8 <= bytes.len() {
                let offset =
                    f32::from_le_bytes([bytes[i], bytes[i + 1], bytes[i + 2], bytes[i + 3]]);
                let sr = bytes[i + 4];
                let sg = bytes[i + 5];
                let sb = bytes[i + 6];
                let sa = bytes[i + 7];
                stops.push(GradientStop {
                    offset,
                    r: sr,
                    g: sg,
                    b: sb,
                    a: sa,
                });
                i += 8;
            }
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Gradient {
                    x,
                    y,
                    w,
                    h,
                    kind: kind as u8,
                    ax,
                    ay,
                    bx,
                    by,
                    stops,
                });
        },
    )?;

    // ── Canvas State (transform / clip / opacity) ──────────────────────

    linker.func_wrap(
        "oxide",
        "api_canvas_save",
        |caller: Caller<'_, HostState>| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Save);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_restore",
        |caller: Caller<'_, HostState>| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Restore);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_transform",
        |caller: Caller<'_, HostState>, a: f32, b: f32, c: f32, d: f32, tx: f32, ty: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Transform { a, b, c, d, tx, ty });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_clip",
        |caller: Caller<'_, HostState>, x: f32, y: f32, w: f32, h: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Clip { x, y, w, h });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_opacity",
        |caller: Caller<'_, HostState>, alpha: f32| {
            caller
                .data()
                .canvas
                .lock()
                .unwrap()
                .commands
                .push(DrawCommand::Opacity { alpha });
        },
    )?;

    // ── Canvas Image ─────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_canvas_image",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         data_ptr: u32,
         data_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let raw = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            match image::load_from_memory(&raw) {
                Ok(img) => {
                    let (iw, ih) = img.dimensions();
                    const MAX_IMAGE_PIXELS: u32 = 4096 * 4096; // ~16M pixels
                    if iw.saturating_mul(ih) > MAX_IMAGE_PIXELS {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!(
                                "[IMAGE] Rejected: {iw}x{ih} exceeds maximum of {MAX_IMAGE_PIXELS} pixels"
                            ),
                        );
                        return;
                    }
                    let rgba = img.to_rgba8();
                    let (iw, ih) = (rgba.width(), rgba.height());
                    let decoded = DecodedImage {
                        width: iw,
                        height: ih,
                        pixels: rgba.into_raw(),
                    };
                    let mut canvas = caller.data().canvas.lock().unwrap();
                    let image_id = canvas.images.len();
                    canvas.images.push(decoded);
                    canvas.commands.push(DrawCommand::Image {
                        x,
                        y,
                        w,
                        h,
                        image_id,
                    });
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[IMAGE] Failed to decode: {e}"),
                    );
                }
            }
        },
    )?;

    // ── Local Storage ────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_storage_set",
        |caller: Caller<'_, HostState>, key_ptr: u32, key_len: u32, val_ptr: u32, val_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            let val = read_guest_string(&mem, &caller, val_ptr, val_len).unwrap_or_default();
            caller.data().storage.lock().unwrap().insert(key, val);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_storage_get",
        |mut caller: Caller<'_, HostState>,
         key_ptr: u32,
         key_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            let val = caller
                .data()
                .storage
                .lock()
                .unwrap()
                .get(&key)
                .cloned()
                .unwrap_or_default();
            let bytes = val.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_storage_remove",
        |caller: Caller<'_, HostState>, key_ptr: u32, key_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            caller.data().storage.lock().unwrap().remove(&key);
        },
    )?;

    // ── Clipboard ────────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_clipboard_write",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| {
            let allowed = *caller.data().clipboard_allowed.lock().unwrap();
            if !allowed {
                console_log(
                    &caller.data().console,
                    ConsoleLevel::Warn,
                    "[CLIPBOARD] Write blocked — clipboard access not permitted".into(),
                );
                return;
            }
            let mem = caller.data().memory.expect("memory not set");
            let text = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            *caller.data().clipboard.lock().unwrap() = text.clone();
            if let Ok(mut ctx) = arboard::Clipboard::new() {
                let _ = ctx.set_text(text);
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_clipboard_read",
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> u32 {
            let allowed = *caller.data().clipboard_allowed.lock().unwrap();
            if !allowed {
                console_log(
                    &caller.data().console,
                    ConsoleLevel::Warn,
                    "[CLIPBOARD] Read blocked — clipboard access not permitted".into(),
                );
                return 0;
            }
            let text = arboard::Clipboard::new()
                .and_then(|mut ctx| ctx.get_text())
                .unwrap_or_default();
            let bytes = text.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    // ── Timers (simplified: returns epoch millis) ────────────────────

    linker.func_wrap(
        "oxide",
        "api_time_now_ms",
        |_caller: Caller<'_, HostState>| -> u64 {
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap_or_default()
                .as_millis() as u64
        },
    )?;

    // ── Timers ────────────────────────────────────────────────────────
    // Timers fire via the guest-exported `on_timer(callback_id)` function,
    // which the host calls from the frame loop for each expired timer.

    linker.func_wrap(
        "oxide",
        "api_set_timeout",
        |caller: Caller<'_, HostState>, callback_id: u32, delay_ms: u32| -> u32 {
            let mut next = caller.data().timer_next_id.lock().unwrap();
            let id = *next;
            *next = next.wrapping_add(1).max(1);
            drop(next);

            let entry = TimerEntry {
                id,
                fire_at: Instant::now() + Duration::from_millis(delay_ms as u64),
                interval: None,
                callback_id,
            };
            caller.data().timers.lock().unwrap().push(entry);
            id
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_set_interval",
        |caller: Caller<'_, HostState>, callback_id: u32, interval_ms: u32| -> u32 {
            let mut next = caller.data().timer_next_id.lock().unwrap();
            let id = *next;
            *next = next.wrapping_add(1).max(1);
            drop(next);

            let interval = Duration::from_millis(interval_ms as u64);
            let entry = TimerEntry {
                id,
                fire_at: Instant::now() + interval,
                interval: Some(interval),
                callback_id,
            };
            caller.data().timers.lock().unwrap().push(entry);
            id
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_clear_timer",
        |caller: Caller<'_, HostState>, timer_id: u32| {
            caller
                .data()
                .timers
                .lock()
                .unwrap()
                .retain(|t| t.id != timer_id);
        },
    )?;

    // ── Animation Frames ──────────────────────────────────────────────
    // One-shot per request (call again from inside `on_timer` to continue). Drained
    // every frame in `LiveModule::tick` before regular timers/`on_frame`. Reuses
    // `timer_next_id` counter and `on_timer` callback mechanism.

    linker.func_wrap(
        "oxide",
        "api_request_animation_frame",
        |caller: Caller<'_, HostState>, callback_id: u32| -> u32 {
            let mut next = caller.data().timer_next_id.lock().unwrap();
            let id = *next;
            *next = next.wrapping_add(1).max(1);
            drop(next);

            let req = AnimationRequest { id, callback_id };
            caller.data().animation_requests.lock().unwrap().push(req);
            id
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_cancel_animation_frame",
        |caller: Caller<'_, HostState>, request_id: u32| {
            caller
                .data()
                .animation_requests
                .lock()
                .unwrap()
                .retain(|r| r.id != request_id);
        },
    )?;

    // ── Random ───────────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_random",
        |_caller: Caller<'_, HostState>| -> u64 {
            let mut buf = [0u8; 8];
            getrandom(&mut buf);
            u64::from_le_bytes(buf)
        },
    )?;

    // ── Notification (writes to console as a "notification") ─────────

    linker.func_wrap(
        "oxide",
        "api_notify",
        |caller: Caller<'_, HostState>,
         title_ptr: u32,
         title_len: u32,
         body_ptr: u32,
         body_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let title = read_guest_string(&mem, &caller, title_ptr, title_len).unwrap_or_default();
            let body = read_guest_string(&mem, &caller, body_ptr, body_len).unwrap_or_default();
            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[NOTIFICATION] {title}: {body}"),
            );
        },
    )?;

    // ── HTTP Fetch ───────────────────────────────────────────────────
    // Synchronous HTTP client exposed to guest wasm. The actual network
    // call runs on a dedicated OS thread to avoid blocking the tokio
    // runtime that the browser host lives on.

    linker.func_wrap(
        "oxide",
        "api_fetch",
        |mut caller: Caller<'_, HostState>,
         method_ptr: u32,
         method_len: u32,
         url_ptr: u32,
         url_len: u32,
         ct_ptr: u32,
         ct_len: u32,
         body_ptr: u32,
         body_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> i64 {
            let mem = caller.data().memory.expect("memory not set");
            let method =
                read_guest_string(&mem, &caller, method_ptr, method_len).unwrap_or_default();
            let url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();
            let content_type = read_guest_string(&mem, &caller, ct_ptr, ct_len).unwrap_or_default();
            let body = if body_len > 0 {
                read_guest_bytes(&mem, &caller, body_ptr, body_len).unwrap_or_default()
            } else {
                Vec::new()
            };

            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[FETCH] {method} {url}"),
            );

            let (resp_tx, resp_rx) =
                std::sync::mpsc::sync_channel::<Result<(u16, Vec<u8>), String>>(1);

            std::thread::spawn(move || {
                let result = (|| -> Result<(u16, Vec<u8>), String> {
                    let client = reqwest::blocking::Client::builder()
                        .timeout(Duration::from_secs(30))
                        .build()
                        .map_err(|e| e.to_string())?;
                    let parsed: reqwest::Method = method.parse().unwrap_or(reqwest::Method::GET);
                    let mut req = client.request(parsed, &url);
                    if !content_type.is_empty() {
                        req = req.header("Content-Type", &content_type);
                    }
                    if !body.is_empty() {
                        req = req.body(body);
                    }
                    let resp = req.send().map_err(|e| e.to_string())?;
                    let status = resp.status().as_u16();
                    let bytes = resp.bytes().map_err(|e| e.to_string())?.to_vec();
                    Ok((status, bytes))
                })();
                let _ = resp_tx.send(result);
            });

            match resp_rx.recv() {
                Ok(Ok((status, response_body))) => {
                    let write_len = response_body.len().min(out_cap as usize);
                    write_guest_bytes(&mem, &mut caller, out_ptr, &response_body[..write_len]).ok();
                    ((status as i64) << 32) | (write_len as i64)
                }
                Ok(Err(e)) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[FETCH ERROR] {e}"),
                    );
                    -1
                }
                Err(_) => -1,
            }
        },
    )?;

    // ── Dynamic Module Loading ───────────────────────────────────────
    // Allows a running wasm guest to fetch and execute another .wasm
    // module. The child module shares the same canvas, console, and
    // storage — similar to how a <script> tag loads code into the same
    // page context.

    linker.func_wrap(
        "oxide",
        "api_load_module",
        |caller: Caller<'_, HostState>, url_ptr: u32, url_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();
            let loader = match &caller.data().module_loader {
                Some(l) => l.clone(),
                None => return -1,
            };
            let mut child_state = caller.data().clone();
            child_state.memory = None;
            let console = caller.data().console.clone();

            console_log(
                &console,
                ConsoleLevel::Log,
                format!("[LOAD] Fetching module: {url}"),
            );

            let (tx, rx) = std::sync::mpsc::sync_channel::<Result<Vec<u8>, String>>(1);
            let fetch_url = url.clone();
            std::thread::spawn(move || {
                let result = (|| -> Result<Vec<u8>, String> {
                    let client = reqwest::blocking::Client::builder()
                        .timeout(Duration::from_secs(30))
                        .build()
                        .map_err(|e| e.to_string())?;
                    let resp = client
                        .get(&fetch_url)
                        .header("Accept", "application/wasm")
                        .send()
                        .map_err(|e| e.to_string())?;
                    if !resp.status().is_success() {
                        return Err(format!("HTTP {}", resp.status()));
                    }
                    resp.bytes().map(|b| b.to_vec()).map_err(|e| e.to_string())
                })();
                let _ = tx.send(result);
            });

            let wasm_bytes = match rx.recv() {
                Ok(Ok(bytes)) => bytes,
                Ok(Err(e)) => {
                    console_log(&console, ConsoleLevel::Error, format!("[LOAD ERROR] {e}"));
                    return -1;
                }
                Err(_) => return -1,
            };

            let module = match Module::new(&loader.engine, &wasm_bytes) {
                Ok(m) => m,
                Err(e) => {
                    console_log(
                        &console,
                        ConsoleLevel::Error,
                        format!("[LOAD ERROR] Compile: {e}"),
                    );
                    return -2;
                }
            };

            let mut store = Store::new(&loader.engine, child_state);
            if store.set_fuel(loader.fuel_limit).is_err() {
                return -3;
            }

            let mut child_linker = Linker::new(&loader.engine);
            if register_host_functions(&mut child_linker).is_err() {
                return -3;
            }

            let mem_type = MemoryType::new(1, Some(loader.max_memory_pages));
            let memory = match Memory::new(&mut store, mem_type) {
                Ok(m) => m,
                Err(_) => return -4,
            };

            if child_linker
                .define(&store, "oxide", "memory", memory)
                .is_err()
            {
                return -5;
            }
            store.data_mut().memory = Some(memory);

            let instance = match child_linker.instantiate(&mut store, &module) {
                Ok(i) => i,
                Err(e) => {
                    console_log(
                        &console,
                        ConsoleLevel::Error,
                        format!("[LOAD ERROR] Instantiate: {e}"),
                    );
                    return -6;
                }
            };

            // Use the child module's own exported memory for string I/O
            if let Some(guest_mem) = instance.get_memory(&mut store, "memory") {
                store.data_mut().memory = Some(guest_mem);
            }

            let start_fn = match instance.get_typed_func::<(), ()>(&mut store, "start_app") {
                Ok(f) => f,
                Err(_) => {
                    console_log(
                        &console,
                        ConsoleLevel::Error,
                        "[LOAD ERROR] Module missing start_app".into(),
                    );
                    return -7;
                }
            };

            match start_fn.call(&mut store, ()) {
                Ok(()) => {
                    console_log(
                        &console,
                        ConsoleLevel::Log,
                        format!("[LOAD] Module {url} executed successfully"),
                    );
                    0
                }
                Err(e) => {
                    let msg = if e.to_string().contains("fuel") {
                        "[LOAD ERROR] Child module fuel limit exceeded".to_string()
                    } else {
                        format!("[LOAD ERROR] Runtime: {e}")
                    };
                    console_log(&console, ConsoleLevel::Error, msg);
                    -8
                }
            }
        },
    )?;

    // ── SHA-256 Hashing ──────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_hash_sha256",
        |mut caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32, out_ptr: u32| -> u32 {
            use sha2::{Digest, Sha256};
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            let hash = Sha256::digest(&data);
            write_guest_bytes(&mem, &mut caller, out_ptr, &hash).ok();
            hash.len() as u32
        },
    )?;

    // ── Base64 Encoding / Decoding ───────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_base64_encode",
        |mut caller: Caller<'_, HostState>,
         data_ptr: u32,
         data_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            use base64::Engine;
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            let encoded = base64::engine::general_purpose::STANDARD.encode(&data);
            let bytes = encoded.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_base64_decode",
        |mut caller: Caller<'_, HostState>,
         data_ptr: u32,
         data_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            use base64::Engine;
            let mem = caller.data().memory.expect("memory not set");
            let encoded = read_guest_string(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            match base64::engine::general_purpose::STANDARD.decode(&encoded) {
                Ok(decoded) => {
                    let write_len = decoded.len().min(out_cap as usize);
                    write_guest_bytes(&mem, &mut caller, out_ptr, &decoded[..write_len]).ok();
                    write_len as u32
                }
                Err(_) => 0,
            }
        },
    )?;

    // ── Persistent Key-Value Store ───────────────────────────────────
    // Backed by a sled embedded database on the host's filesystem.
    // The guest has no direct access to the .db files.

    linker.func_wrap(
        "oxide",
        "api_kv_store_set",
        |caller: Caller<'_, HostState>,
         key_ptr: u32,
         key_len: u32,
         val_ptr: u32,
         val_len: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            let val = read_guest_bytes(&mem, &caller, val_ptr, val_len).unwrap_or_default();
            let origin = caller.data().module_origin.lock().unwrap().clone();
            let prefixed_key = format!("{origin}::{key}");
            match &caller.data().kv_db {
                Some(db) => match db.insert(prefixed_key.as_bytes(), val) {
                    Ok(_) => {
                        let _ = db.flush();
                        0
                    }
                    Err(e) => {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!("[KV] set failed: {e}"),
                        );
                        -1
                    }
                },
                None => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        "[KV] store not initialised".into(),
                    );
                    -1
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_kv_store_get",
        |mut caller: Caller<'_, HostState>,
         key_ptr: u32,
         key_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            let origin = caller.data().module_origin.lock().unwrap().clone();
            let prefixed_key = format!("{origin}::{key}");
            match &caller.data().kv_db {
                Some(db) => match db.get(prefixed_key.as_bytes()) {
                    Ok(Some(val)) => {
                        let bytes = val.as_ref();
                        let write_len = bytes.len().min(out_cap as usize);
                        write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
                        write_len as i32
                    }
                    Ok(None) => -1,
                    Err(e) => {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!("[KV] get failed: {e}"),
                        );
                        -2
                    }
                },
                None => -2,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_kv_store_delete",
        |caller: Caller<'_, HostState>, key_ptr: u32, key_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let key = read_guest_string(&mem, &caller, key_ptr, key_len).unwrap_or_default();
            let origin = caller.data().module_origin.lock().unwrap().clone();
            let prefixed_key = format!("{origin}::{key}");
            match &caller.data().kv_db {
                Some(db) => match db.remove(prefixed_key.as_bytes()) {
                    Ok(_) => {
                        let _ = db.flush();
                        0
                    }
                    Err(e) => {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!("[KV] delete failed: {e}"),
                        );
                        -1
                    }
                },
                None => -1,
            }
        },
    )?;

    // ── Navigation ──────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_navigate",
        |caller: Caller<'_, HostState>, url_ptr: u32, url_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let raw_url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();

            let resolved = {
                let cur = caller.data().current_url.lock().unwrap();
                if cur.is_empty() {
                    raw_url.clone()
                } else if let Ok(base) = oxide_url::OxideUrl::parse(&cur) {
                    base.join(&raw_url)
                        .map(|u| u.as_str().to_string())
                        .unwrap_or(raw_url.clone())
                } else {
                    raw_url.clone()
                }
            };

            if oxide_url::OxideUrl::parse(&resolved).is_err() {
                console_log(
                    &caller.data().console,
                    ConsoleLevel::Error,
                    format!("[NAV] invalid URL: {resolved}"),
                );
                return -1;
            }

            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[NAV] navigate → {resolved}"),
            );
            *caller.data().pending_navigation.lock().unwrap() = Some(resolved);
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_push_state",
        |caller: Caller<'_, HostState>,
         state_ptr: u32,
         state_len: u32,
         title_ptr: u32,
         title_len: u32,
         url_ptr: u32,
         url_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let state = read_guest_bytes(&mem, &caller, state_ptr, state_len).unwrap_or_default();
            let title = read_guest_string(&mem, &caller, title_ptr, title_len).unwrap_or_default();
            let url_arg = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();

            let resolved_url = if url_arg.is_empty() {
                caller.data().current_url.lock().unwrap().clone()
            } else {
                let cur = caller.data().current_url.lock().unwrap();
                if cur.is_empty() {
                    url_arg
                } else if let Ok(base) = oxide_url::OxideUrl::parse(&cur) {
                    base.join(&url_arg)
                        .map(|u| u.as_str().to_string())
                        .unwrap_or(url_arg)
                } else {
                    url_arg
                }
            };

            let entry = crate::navigation::HistoryEntry::new(&resolved_url)
                .with_title(title)
                .with_state(state);
            caller.data().navigation.lock().unwrap().push(entry);
            *caller.data().current_url.lock().unwrap() = resolved_url;
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_replace_state",
        |caller: Caller<'_, HostState>,
         state_ptr: u32,
         state_len: u32,
         title_ptr: u32,
         title_len: u32,
         url_ptr: u32,
         url_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let state = read_guest_bytes(&mem, &caller, state_ptr, state_len).unwrap_or_default();
            let title = read_guest_string(&mem, &caller, title_ptr, title_len).unwrap_or_default();
            let url_arg = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();

            let resolved_url = if url_arg.is_empty() {
                caller.data().current_url.lock().unwrap().clone()
            } else {
                let cur = caller.data().current_url.lock().unwrap();
                if cur.is_empty() {
                    url_arg
                } else if let Ok(base) = oxide_url::OxideUrl::parse(&cur) {
                    base.join(&url_arg)
                        .map(|u| u.as_str().to_string())
                        .unwrap_or(url_arg)
                } else {
                    url_arg
                }
            };

            let entry = crate::navigation::HistoryEntry::new(&resolved_url)
                .with_title(title)
                .with_state(state);
            caller
                .data()
                .navigation
                .lock()
                .unwrap()
                .replace_current(entry);
            *caller.data().current_url.lock().unwrap() = resolved_url;
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_get_url",
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> u32 {
            let url = caller.data().current_url.lock().unwrap().clone();
            let bytes = url.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_get_state",
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> i32 {
            let state_bytes = {
                let nav = caller.data().navigation.lock().unwrap();
                match nav.current() {
                    Some(entry) if !entry.state.is_empty() => Some(entry.state.clone()),
                    _ => None,
                }
            };
            match state_bytes {
                Some(bytes) => {
                    let write_len = bytes.len().min(out_cap as usize);
                    let mem = caller.data().memory.expect("memory not set");
                    write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
                    write_len as i32
                }
                None => -1,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_history_length",
        |caller: Caller<'_, HostState>| -> u32 {
            caller.data().navigation.lock().unwrap().len() as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_history_back",
        |caller: Caller<'_, HostState>| -> i32 {
            let mut nav = caller.data().navigation.lock().unwrap();
            match nav.go_back() {
                Some(entry) => {
                    let url = entry.url.clone();
                    *caller.data().current_url.lock().unwrap() = url.clone();
                    *caller.data().pending_navigation.lock().unwrap() = Some(url);
                    1
                }
                None => 0,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_history_forward",
        |caller: Caller<'_, HostState>| -> i32 {
            let mut nav = caller.data().navigation.lock().unwrap();
            match nav.go_forward() {
                Some(entry) => {
                    let url = entry.url.clone();
                    *caller.data().current_url.lock().unwrap() = url.clone();
                    *caller.data().pending_navigation.lock().unwrap() = Some(url);
                    1
                }
                None => 0,
            }
        },
    )?;

    // ── Hyperlinks ──────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_register_hyperlink",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         url_ptr: u32,
         url_len: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let raw_url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();

            let resolved = {
                let cur = caller.data().current_url.lock().unwrap();
                if cur.is_empty() {
                    raw_url.clone()
                } else if let Ok(base) = oxide_url::OxideUrl::parse(&cur) {
                    base.join(&raw_url)
                        .map(|u| u.as_str().to_string())
                        .unwrap_or(raw_url.clone())
                } else {
                    raw_url.clone()
                }
            };

            caller.data().hyperlinks.lock().unwrap().push(Hyperlink {
                x,
                y,
                w,
                h,
                url: resolved,
            });
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_clear_hyperlinks",
        |caller: Caller<'_, HostState>| {
            caller.data().hyperlinks.lock().unwrap().clear();
        },
    )?;

    // ── URL Utilities ───────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_url_resolve",
        |mut caller: Caller<'_, HostState>,
         base_ptr: u32,
         base_len: u32,
         rel_ptr: u32,
         rel_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let base_str = read_guest_string(&mem, &caller, base_ptr, base_len).unwrap_or_default();
            let rel_str = read_guest_string(&mem, &caller, rel_ptr, rel_len).unwrap_or_default();

            let base = match oxide_url::OxideUrl::parse(&base_str) {
                Ok(u) => u,
                Err(_) => return -1,
            };
            let resolved = match base.join(&rel_str) {
                Ok(u) => u,
                Err(_) => return -2,
            };

            let bytes = resolved.as_str().as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as i32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_url_encode",
        |mut caller: Caller<'_, HostState>,
         input_ptr: u32,
         input_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let input = read_guest_string(&mem, &caller, input_ptr, input_len).unwrap_or_default();
            let encoded = oxide_url::percent_encode(&input);
            let bytes = encoded.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_url_decode",
        |mut caller: Caller<'_, HostState>,
         input_ptr: u32,
         input_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let input = read_guest_string(&mem, &caller, input_ptr, input_len).unwrap_or_default();
            let decoded = oxide_url::percent_decode(&input);
            let bytes = decoded.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    // ── Input Polling ────────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_mouse_position",
        |caller: Caller<'_, HostState>| -> u64 {
            let input = caller.data().input_state.lock().unwrap();
            let offset = caller.data().canvas_offset.lock().unwrap();
            let x = input.mouse_x - offset.0;
            let y = input.mouse_y - offset.1;
            ((x.to_bits() as u64) << 32) | (y.to_bits() as u64)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_mouse_button_down",
        |caller: Caller<'_, HostState>, button: u32| -> u32 {
            let input = caller.data().input_state.lock().unwrap();
            if (button as usize) < 3 && input.mouse_buttons_down[button as usize] {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_mouse_button_clicked",
        |caller: Caller<'_, HostState>, button: u32| -> u32 {
            let input = caller.data().input_state.lock().unwrap();
            if (button as usize) < 3 && input.mouse_buttons_clicked[button as usize] {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_key_down",
        |caller: Caller<'_, HostState>, key: u32| -> u32 {
            let input = caller.data().input_state.lock().unwrap();
            if input.keys_down.contains(&key) {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_key_pressed",
        |caller: Caller<'_, HostState>, key: u32| -> u32 {
            let input = caller.data().input_state.lock().unwrap();
            if input.keys_pressed.contains(&key) {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_scroll_delta",
        |caller: Caller<'_, HostState>| -> u64 {
            let input = caller.data().input_state.lock().unwrap();
            ((input.scroll_x.to_bits() as u64) << 32) | (input.scroll_y.to_bits() as u64)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_modifiers",
        |caller: Caller<'_, HostState>| -> u32 {
            let input = caller.data().input_state.lock().unwrap();
            let mut flags = 0u32;
            if input.modifiers_shift {
                flags |= 1;
            }
            if input.modifiers_ctrl {
                flags |= 2;
            }
            if input.modifiers_alt {
                flags |= 4;
            }
            flags
        },
    )?;

    // ── Audio Playback ────────────────────────────────────────────
    // All single-argument functions operate on the default channel (0).
    // Channel-specific variants allow simultaneous playback on separate
    // channels (e.g. background music on 0, SFX on 1+).

    linker.func_wrap(
        "oxide",
        "api_audio_play",
        |caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            if data.is_empty() {
                return -1;
            }

            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            match guard.as_mut() {
                Some(engine) => {
                    if engine.play_bytes_on(0, data) {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Log,
                            "[AUDIO] Playing from bytes".into(),
                        );
                        0
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            "[AUDIO] Failed to decode audio data".into(),
                        );
                        -2
                    }
                }
                None => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        "[AUDIO] No audio device available".into(),
                    );
                    -3
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_detect_format",
        |caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32| -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            audio_format::sniff_audio_format(&data)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_play_with_format",
        |caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32, format_hint: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            if data.is_empty() {
                return -1;
            }

            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            match guard.as_mut() {
                Some(engine) => {
                    if audio_try_play(engine, 0, data, format_hint, &caller.data().console) {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Log,
                            "[AUDIO] Playing from bytes (with format hint)".into(),
                        );
                        0
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            "[AUDIO] Failed to decode audio data".into(),
                        );
                        -2
                    }
                }
                None => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        "[AUDIO] No audio device available".into(),
                    );
                    -3
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_play_url",
        |caller: Caller<'_, HostState>, url_ptr: u32, url_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();

            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[AUDIO] Fetching {url}"),
            );

            let (tx, rx) =
                std::sync::mpsc::sync_channel::<Result<(Vec<u8>, Option<String>), String>>(1);
            let fetch_url = url.clone();
            std::thread::spawn(move || {
                let result = (|| -> Result<(Vec<u8>, Option<String>), String> {
                    let client = reqwest::blocking::Client::builder()
                        .timeout(Duration::from_secs(30))
                        .build()
                        .map_err(|e| e.to_string())?;
                    let resp = client
                        .get(&fetch_url)
                        .header(ACCEPT, audio_format::AUDIO_HTTP_ACCEPT)
                        .send()
                        .map_err(|e| e.to_string())?;
                    if !resp.status().is_success() {
                        return Err(format!("HTTP {}", resp.status()));
                    }
                    let ct = resp
                        .headers()
                        .get(CONTENT_TYPE)
                        .and_then(|v| v.to_str().ok())
                        .map(|s| s.to_string());
                    let bytes = resp.bytes().map(|b| b.to_vec()).map_err(|e| e.to_string())?;
                    Ok((bytes, ct))
                })();
                let _ = tx.send(result);
            });

            let (data, content_type) = match rx.recv() {
                Ok(Ok(pair)) => pair,
                Ok(Err(e)) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[AUDIO] Fetch error: {e}"),
                    );
                    return -1;
                }
                Err(_) => return -1,
            };

            *caller.data().last_audio_url_content_type.lock().unwrap() =
                content_type.clone().unwrap_or_default();

            let sniffed = audio_format::sniff_audio_format(&data);
            if let Some(ref ct) = content_type {
                if audio_format::is_likely_non_audio_document(ct)
                    && sniffed == audio_format::AUDIO_FORMAT_UNKNOWN
                {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        "[AUDIO] Response is not a supported audio resource (document MIME, no audio signature)"
                            .into(),
                    );
                    return -4;
                }
                let mime_fmt = audio_format::mime_to_audio_format(ct);
                if mime_fmt != audio_format::AUDIO_FORMAT_UNKNOWN
                    && sniffed != audio_format::AUDIO_FORMAT_UNKNOWN
                    && mime_fmt != sniffed
                {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Warn,
                        format!(
                            "[AUDIO] Content-Type disagrees with sniffed container (MIME -> {mime_fmt}, sniff -> {sniffed})"
                        ),
                    );
                }
            }

            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            match guard.as_mut() {
                Some(engine) => {
                    if engine.play_bytes_on(0, data) {
                        let ct = content_type.as_deref().unwrap_or("(none)");
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Log,
                            format!("[AUDIO] Playing from URL: {url} (Content-Type: {ct})"),
                        );
                        0
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            "[AUDIO] Failed to decode fetched audio".into(),
                        );
                        -2
                    }
                }
                None => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        "[AUDIO] No audio device available".into(),
                    );
                    -3
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_last_url_content_type",
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> u32 {
            let s = caller
                .data()
                .last_audio_url_content_type
                .lock()
                .unwrap()
                .clone();
            let bytes = s.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_pause",
        |caller: Caller<'_, HostState>| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&0) {
                    ch.player.pause();
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_resume",
        |caller: Caller<'_, HostState>| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&0) {
                    ch.player.play();
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_stop",
        |caller: Caller<'_, HostState>| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&0) {
                    ch.player.stop();
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_set_volume",
        |caller: Caller<'_, HostState>, level: f32| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&0) {
                    ch.player.set_volume(level.clamp(0.0, 2.0));
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_get_volume",
        |caller: Caller<'_, HostState>| -> f32 {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            guard
                .as_ref()
                .and_then(|e| e.channels.get(&0))
                .map(|ch| ch.player.volume())
                .unwrap_or(1.0)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_is_playing",
        |caller: Caller<'_, HostState>| -> u32 {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            match guard.as_ref().and_then(|e| e.channels.get(&0)) {
                Some(ch) if !ch.player.is_paused() && !ch.player.empty() => 1,
                _ => 0,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_position",
        |caller: Caller<'_, HostState>| -> u64 {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            guard
                .as_ref()
                .and_then(|e| e.channels.get(&0))
                .map(|ch| ch.player.get_pos().as_millis() as u64)
                .unwrap_or(0)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_seek",
        |caller: Caller<'_, HostState>, position_ms: u64| -> i32 {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            match guard.as_ref().and_then(|e| e.channels.get(&0)) {
                Some(ch) => {
                    let pos = Duration::from_millis(position_ms);
                    match ch.player.try_seek(pos) {
                        Ok(_) => 0,
                        Err(e) => {
                            console_log(
                                &caller.data().console,
                                ConsoleLevel::Warn,
                                format!("[AUDIO] Seek failed: {e}"),
                            );
                            -1
                        }
                    }
                }
                None => -1,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_duration",
        |caller: Caller<'_, HostState>| -> u64 {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            guard
                .as_ref()
                .and_then(|e| e.channels.get(&0))
                .map(|ch| ch.duration_ms)
                .unwrap_or(0)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_set_loop",
        |caller: Caller<'_, HostState>, enabled: u32| {
            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            if let Some(engine) = guard.as_mut() {
                engine.ensure_channel(0).looping = enabled != 0;
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_channel_play",
        |caller: Caller<'_, HostState>, channel: u32, data_ptr: u32, data_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            if data.is_empty() {
                return -1;
            }

            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            match guard.as_mut() {
                Some(engine) => {
                    if engine.play_bytes_on(channel, data) {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Log,
                            format!("[AUDIO] Playing on channel {channel}"),
                        );
                        0
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!("[AUDIO] Failed to decode audio for channel {channel}"),
                        );
                        -2
                    }
                }
                None => -3,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_channel_play_with_format",
        |caller: Caller<'_, HostState>,
         channel: u32,
         data_ptr: u32,
         data_len: u32,
         format_hint: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            if data.is_empty() {
                return -1;
            }

            let audio = caller.data().audio.clone();
            let mut guard = audio.lock().unwrap();
            if guard.is_none() {
                *guard = AudioEngine::try_new();
            }
            match guard.as_mut() {
                Some(engine) => {
                    if audio_try_play(engine, channel, data, format_hint, &caller.data().console) {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Log,
                            format!("[AUDIO] Playing on channel {channel} (with format hint)"),
                        );
                        0
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            format!("[AUDIO] Failed to decode audio for channel {channel}"),
                        );
                        -2
                    }
                }
                None => -3,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_channel_stop",
        |caller: Caller<'_, HostState>, channel: u32| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&channel) {
                    ch.player.stop();
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_audio_channel_set_volume",
        |caller: Caller<'_, HostState>, channel: u32, level: f32| {
            let audio = caller.data().audio.clone();
            let guard = audio.lock().unwrap();
            if let Some(engine) = guard.as_ref() {
                if let Some(ch) = engine.channels.get(&channel) {
                    ch.player.set_volume(level.clamp(0.0, 2.0));
                }
            }
        },
    )?;

    // ── Video (FFmpeg) ─────────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_video_detect_format",
        |caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32| -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            video_format::sniff_video_format(&data)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_load",
        |caller: Caller<'_, HostState>, data_ptr: u32, data_len: u32, format_hint: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            if data.is_empty() {
                return -1;
            }
            let mut guard = caller.data().video.lock().unwrap();
            match guard.open_bytes(&data, format_hint) {
                Ok(()) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Log,
                        "[VIDEO] Loaded from bytes".into(),
                    );
                    0
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[VIDEO] Load failed: {e}"),
                    );
                    -2
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_load_url",
        |caller: Caller<'_, HostState>, url_ptr: u32, url_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();
            if url.is_empty() {
                return -1;
            }
            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[VIDEO] Opening {url}"),
            );

            let client = match reqwest::blocking::Client::builder()
                .timeout(Duration::from_secs(90))
                .build()
            {
                Ok(c) => c,
                Err(_) => return -3,
            };

            let mut ct = String::new();
            if let Ok(resp) = client.head(&url).send() {
                if let Some(h) = resp.headers().get(CONTENT_TYPE) {
                    if let Ok(s) = h.to_str() {
                        ct = s.to_string();
                    }
                }
            }

            let mut master_body: Option<String> = None;
            let fetch_master = url.to_ascii_lowercase().contains("m3u8")
                || ct.to_ascii_lowercase().contains("mpegurl")
                || ct.to_ascii_lowercase().contains("m3u8");
            if fetch_master {
                if let Ok(resp) = client
                    .get(&url)
                    .header(ACCEPT, video_format::VIDEO_HTTP_ACCEPT)
                    .timeout(Duration::from_secs(60))
                    .send()
                {
                    if resp.status().is_success() {
                        if let Ok(t) = resp.text() {
                            master_body = Some(t);
                        }
                    }
                }
            }

            let mut guard = caller.data().video.lock().unwrap();
            guard.stop();
            guard.last_url_content_type = ct.clone();
            guard.hls_base_url = url.clone();
            if let Some(ref body) = master_body {
                guard.hls_variants = video::parse_hls_master_variants(body);
            } else {
                guard.hls_variants.clear();
            }

            match video::VideoPlayer::open_url(&url) {
                Ok(p) => {
                    guard.player = Some(p);
                    let ctd = ct.as_str();
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Log,
                        format!("[VIDEO] Opened URL (Content-Type: {ctd})"),
                    );
                    0
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[VIDEO] Open failed: {e}"),
                    );
                    -2
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_last_url_content_type",
        |mut caller: Caller<'_, HostState>, out_ptr: u32, out_cap: u32| -> u32 {
            let s = caller
                .data()
                .video
                .lock()
                .unwrap()
                .last_url_content_type
                .clone();
            let bytes = s.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_hls_variant_count",
        |caller: Caller<'_, HostState>| -> u32 {
            caller.data().video.lock().unwrap().hls_variants.len() as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_hls_variant_url",
        |mut caller: Caller<'_, HostState>, index: u32, out_ptr: u32, out_cap: u32| -> u32 {
            let resolved = {
                let g = caller.data().video.lock().unwrap();
                g.hls_variants
                    .get(index as usize)
                    .and_then(|rel| video::resolve_against_base(&g.hls_base_url, rel))
                    .or_else(|| g.hls_variants.get(index as usize).cloned())
                    .unwrap_or_default()
            };
            let bytes = resolved.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            let mem = caller.data().memory.expect("memory not set");
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_hls_open_variant",
        |caller: Caller<'_, HostState>, index: u32| -> i32 {
            let url_opt = {
                let g = caller.data().video.lock().unwrap();
                g.hls_variants.get(index as usize).map(|rel| {
                    video::resolve_against_base(&g.hls_base_url, rel).unwrap_or_else(|| rel.clone())
                })
            };
            let Some(url) = url_opt else {
                return -1;
            };
            let mut guard = caller.data().video.lock().unwrap();
            guard.hls_base_url = url.clone();
            guard.hls_variants.clear();
            match video::VideoPlayer::open_url(&url) {
                Ok(p) => {
                    guard.player = Some(p);
                    guard.reset_playback_clock();
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Log,
                        format!("[VIDEO] Opened HLS variant {index}"),
                    );
                    0
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[VIDEO] Variant open failed: {e}"),
                    );
                    -2
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_play",
        |caller: Caller<'_, HostState>| {
            caller.data().video.lock().unwrap().play();
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_pause",
        |caller: Caller<'_, HostState>| {
            caller.data().video.lock().unwrap().pause();
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_stop",
        |caller: Caller<'_, HostState>| {
            caller.data().video.lock().unwrap().stop();
            *caller.data().video_pip_frame.lock().unwrap() = None;
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_seek",
        |caller: Caller<'_, HostState>, position_ms: u64| -> i32 {
            caller.data().video.lock().unwrap().seek(position_ms);
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_position",
        |caller: Caller<'_, HostState>| -> u64 {
            caller.data().video.lock().unwrap().current_position_ms()
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_duration",
        |caller: Caller<'_, HostState>| -> u64 {
            caller.data().video.lock().unwrap().duration_ms()
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_render",
        |caller: Caller<'_, HostState>, x: f32, y: f32, w: f32, h: f32| -> i32 {
            match video_render_at(
                &caller.data().video,
                &caller.data().video_pip_frame,
                &caller.data().video_pip_serial,
                &caller.data().canvas,
                x,
                y,
                w,
                h,
            ) {
                Ok(()) => 0,
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[VIDEO] Render: {e}"),
                    );
                    -1
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_set_volume",
        |caller: Caller<'_, HostState>, level: f32| {
            caller.data().video.lock().unwrap().volume = level.clamp(0.0, 2.0);
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_get_volume",
        |caller: Caller<'_, HostState>| -> f32 { caller.data().video.lock().unwrap().volume },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_set_loop",
        |caller: Caller<'_, HostState>, enabled: u32| {
            caller.data().video.lock().unwrap().looping = enabled != 0;
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_video_set_pip",
        |caller: Caller<'_, HostState>, enabled: u32| {
            caller.data().video.lock().unwrap().pip = enabled != 0;
            if enabled == 0 {
                *caller.data().video_pip_frame.lock().unwrap() = None;
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_subtitle_load_srt",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let s = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            caller.data().video.lock().unwrap().subtitles = subtitle::parse_srt(&s);
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_subtitle_load_vtt",
        |caller: Caller<'_, HostState>, ptr: u32, len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let s = read_guest_string(&mem, &caller, ptr, len).unwrap_or_default();
            caller.data().video.lock().unwrap().subtitles = subtitle::parse_vtt(&s);
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_subtitle_clear",
        |caller: Caller<'_, HostState>| {
            caller.data().video.lock().unwrap().subtitles.clear();
        },
    )?;

    // ── Interactive Widgets ─────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_ui_button",
        |caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         label_ptr: u32,
         label_len: u32,
         variant: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let label = read_guest_string(&mem, &caller, label_ptr, label_len).unwrap_or_default();
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Button {
                    id,
                    x,
                    y,
                    w,
                    h,
                    label,
                    variant: crate::capabilities::WidgetVariant::from_u32(variant),
                });
            if caller.data().widget_clicked.lock().unwrap().contains(&id) {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_checkbox",
        |caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         label_ptr: u32,
         label_len: u32,
         initial: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let label = read_guest_string(&mem, &caller, label_ptr, label_len).unwrap_or_default();
            let mut states = caller.data().widget_states.lock().unwrap();
            let entry = states
                .entry(id)
                .or_insert_with(|| WidgetValue::Bool(initial != 0));
            let checked = match entry {
                WidgetValue::Bool(b) => *b,
                _ => initial != 0,
            };
            drop(states);
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Checkbox { id, x, y, label });
            if checked {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_slider",
        |caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         w: f32,
         min: f32,
         max: f32,
         initial: f32|
         -> f32 {
            let mut states = caller.data().widget_states.lock().unwrap();
            let entry = states
                .entry(id)
                .or_insert_with(|| WidgetValue::Float(initial));
            let value = match entry {
                WidgetValue::Float(v) => *v,
                _ => initial,
            };
            drop(states);
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Slider {
                    id,
                    x,
                    y,
                    w,
                    min,
                    max,
                });
            value
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_text_input",
        |mut caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         w: f32,
         init_ptr: u32,
         init_len: u32,
         placeholder_ptr: u32,
         placeholder_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let placeholder = read_guest_string(&mem, &caller, placeholder_ptr, placeholder_len)
                .unwrap_or_default();
            let text = {
                let mut states = caller.data().widget_states.lock().unwrap();
                let entry = states.entry(id).or_insert_with(|| {
                    let init =
                        read_guest_string(&mem, &caller, init_ptr, init_len).unwrap_or_default();
                    WidgetValue::Text(init)
                });
                match entry {
                    WidgetValue::Text(t) => t.clone(),
                    _ => String::new(),
                }
            };
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::TextInput {
                    id,
                    x,
                    y,
                    w,
                    placeholder,
                });
            let bytes = text.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_textarea",
        |mut caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         init_ptr: u32,
         init_len: u32,
         placeholder_ptr: u32,
         placeholder_len: u32,
         out_ptr: u32,
         out_cap: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let placeholder = read_guest_string(&mem, &caller, placeholder_ptr, placeholder_len)
                .unwrap_or_default();
            let text = {
                let mut states = caller.data().widget_states.lock().unwrap();
                let entry = states.entry(id).or_insert_with(|| {
                    let init =
                        read_guest_string(&mem, &caller, init_ptr, init_len).unwrap_or_default();
                    WidgetValue::Text(init)
                });
                match entry {
                    WidgetValue::Text(t) => t.clone(),
                    _ => String::new(),
                }
            };
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Textarea {
                    id,
                    x,
                    y,
                    w,
                    h,
                    placeholder,
                });
            let bytes = text.as_bytes();
            let write_len = bytes.len().min(out_cap as usize);
            write_guest_bytes(&mem, &mut caller, out_ptr, &bytes[..write_len]).ok();
            write_len as u32
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_switch",
        |caller: Caller<'_, HostState>,
         id: u32,
         x: f32,
         y: f32,
         label_ptr: u32,
         label_len: u32,
         initial: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let label = read_guest_string(&mem, &caller, label_ptr, label_len).unwrap_or_default();
            let mut states = caller.data().widget_states.lock().unwrap();
            let entry = states
                .entry(id)
                .or_insert_with(|| WidgetValue::Bool(initial != 0));
            let checked = match entry {
                WidgetValue::Bool(b) => *b,
                _ => initial != 0,
            };
            drop(states);
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Switch { id, x, y, label });
            if checked {
                1
            } else {
                0
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_card",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         w: f32,
         h: f32,
         title_ptr: u32,
         title_len: u32,
         desc_ptr: u32,
         desc_len: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let title = read_guest_string(&mem, &caller, title_ptr, title_len).unwrap_or_default();
            let description =
                read_guest_string(&mem, &caller, desc_ptr, desc_len).unwrap_or_default();
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Card {
                    x,
                    y,
                    w,
                    h,
                    title,
                    description,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_badge",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         label_ptr: u32,
         label_len: u32,
         variant: u32| {
            let mem = caller.data().memory.expect("memory not set");
            let label = read_guest_string(&mem, &caller, label_ptr, label_len).unwrap_or_default();
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Badge {
                    x,
                    y,
                    label,
                    variant: crate::capabilities::WidgetVariant::from_u32(variant),
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_separator",
        |caller: Caller<'_, HostState>, x: f32, y: f32, length: f32, vertical: u32| {
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Separator {
                    x,
                    y,
                    length,
                    vertical: vertical != 0,
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_progress",
        |caller: Caller<'_, HostState>, x: f32, y: f32, w: f32, value: f32| {
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Progress {
                    x,
                    y,
                    w,
                    value: value.clamp(0.0, 1.0),
                });
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_ui_label",
        |caller: Caller<'_, HostState>,
         x: f32,
         y: f32,
         text_ptr: u32,
         text_len: u32,
         muted: u32,
         size: f32| {
            let mem = caller.data().memory.expect("memory not set");
            let text = read_guest_string(&mem, &caller, text_ptr, text_len).unwrap_or_default();
            let size = if size <= 0.0 { 14.0 } else { size };
            caller
                .data()
                .widget_commands
                .lock()
                .unwrap()
                .push(WidgetCommand::Label {
                    x,
                    y,
                    text,
                    muted: muted != 0,
                    size,
                });
        },
    )?;

    crate::media_capture::register_media_capture_functions(linker)?;

    // ── GPU / WebGPU-style API ───────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_gpu_create_buffer",
        |caller: Caller<'_, HostState>, size_lo: u32, size_hi: u32, usage: u32| -> u32 {
            let size = ((size_hi as u64) << 32) | (size_lo as u64);
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            let gpu = match gpu_lock.as_mut() {
                Some(g) => g,
                None => {
                    if let Some(g) = crate::gpu::init_gpu() {
                        *gpu_lock = Some(g);
                        gpu_lock.as_mut().unwrap()
                    } else {
                        console_log(
                            &caller.data().console,
                            ConsoleLevel::Error,
                            "[GPU] No suitable GPU adapter found".into(),
                        );
                        return 0;
                    }
                }
            };
            gpu.create_buffer(size, usage)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_create_texture",
        |caller: Caller<'_, HostState>, width: u32, height: u32| -> u32 {
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            let gpu = match gpu_lock.as_mut() {
                Some(g) => g,
                None => {
                    if let Some(g) = crate::gpu::init_gpu() {
                        *gpu_lock = Some(g);
                        gpu_lock.as_mut().unwrap()
                    } else {
                        return 0;
                    }
                }
            };
            gpu.create_texture(width, height)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_create_shader",
        |caller: Caller<'_, HostState>, src_ptr: u32, src_len: u32| -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let source = read_guest_string(&mem, &caller, src_ptr, src_len).unwrap_or_default();
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            let gpu = match gpu_lock.as_mut() {
                Some(g) => g,
                None => {
                    if let Some(g) = crate::gpu::init_gpu() {
                        *gpu_lock = Some(g);
                        gpu_lock.as_mut().unwrap()
                    } else {
                        return 0;
                    }
                }
            };
            gpu.create_shader(&source)
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_create_render_pipeline",
        |caller: Caller<'_, HostState>,
         shader: u32,
         vs_ptr: u32,
         vs_len: u32,
         fs_ptr: u32,
         fs_len: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let vs = read_guest_string(&mem, &caller, vs_ptr, vs_len).unwrap_or_default();
            let fs = read_guest_string(&mem, &caller, fs_ptr, fs_len).unwrap_or_default();
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            match gpu_lock.as_mut() {
                Some(g) => g.create_render_pipeline(shader, &vs, &fs),
                None => 0,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_create_compute_pipeline",
        |caller: Caller<'_, HostState>, shader: u32, ep_ptr: u32, ep_len: u32| -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let ep = read_guest_string(&mem, &caller, ep_ptr, ep_len).unwrap_or_default();
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            match gpu_lock.as_mut() {
                Some(g) => g.create_compute_pipeline(shader, &ep),
                None => 0,
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_write_buffer",
        |caller: Caller<'_, HostState>,
         handle: u32,
         offset_lo: u32,
         offset_hi: u32,
         data_ptr: u32,
         data_len: u32|
         -> u32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            let offset = ((offset_hi as u64) << 32) | (offset_lo as u64);
            let gpu_lock = caller.data().gpu.lock().unwrap();
            u32::from(
                gpu_lock
                    .as_ref()
                    .is_some_and(|g| g.write_buffer(handle, offset, &data)),
            )
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_draw",
        |caller: Caller<'_, HostState>,
         pipeline: u32,
         target: u32,
         vertex_count: u32,
         instance_count: u32|
         -> u32 {
            let gpu_lock = caller.data().gpu.lock().unwrap();
            u32::from(
                gpu_lock
                    .as_ref()
                    .is_some_and(|g| g.draw(pipeline, target, vertex_count, instance_count)),
            )
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_dispatch_compute",
        |caller: Caller<'_, HostState>, pipeline: u32, x: u32, y: u32, z: u32| -> u32 {
            let gpu_lock = caller.data().gpu.lock().unwrap();
            u32::from(
                gpu_lock
                    .as_ref()
                    .is_some_and(|g| g.dispatch_compute(pipeline, x, y, z)),
            )
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_destroy_buffer",
        |caller: Caller<'_, HostState>, handle: u32| -> u32 {
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            u32::from(gpu_lock.as_mut().is_some_and(|g| g.destroy_buffer(handle)))
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_gpu_destroy_texture",
        |caller: Caller<'_, HostState>, handle: u32| -> u32 {
            let mut gpu_lock = caller.data().gpu.lock().unwrap();
            u32::from(gpu_lock.as_mut().is_some_and(|g| g.destroy_texture(handle)))
        },
    )?;

    // ── WebRTC / Real-Time Communication API ─────────────────────────
    crate::rtc::register_rtc_functions(linker)?;

    // ── WebSocket API ─────────────────────────────────────────────────
    crate::websocket::register_ws_functions(linker)?;

    // ── MIDI API ──────────────────────────────────────────────────────
    crate::midi::register_midi_functions(linker)?;

    // ── Streaming / non-blocking Fetch API ────────────────────────────
    crate::fetch::register_fetch_functions(linker)?;

    // ── Event System ──────────────────────────────────────────────────
    crate::events::register_event_functions(linker)?;

    // ── Native File / Folder Picker API ───────────────────────────────
    crate::file_picker::register_file_picker_functions(linker)?;

    // ── Background Workers API ────────────────────────────────────────
    crate::worker::register_worker_functions(linker)?;

    // ── Download Manager API ──────────────────────────────────────────

    linker.func_wrap(
        "oxide",
        "api_download_data",
        |caller: Caller<'_, HostState>,
         data_ptr: u32,
         data_len: u32,
         filename_ptr: u32,
         filename_len: u32|
         -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let data = read_guest_bytes(&mem, &caller, data_ptr, data_len).unwrap_or_default();
            let filename =
                read_guest_string(&mem, &caller, filename_ptr, filename_len).unwrap_or_default();
            if data.is_empty() || filename.is_empty() {
                return -1;
            }
            match caller.data().download_manager.save_data(&data, &filename) {
                Ok(_) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Log,
                        format!("[DOWNLOAD] Saved {} bytes to {}", data.len(), filename),
                    );
                    0
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[DOWNLOAD] Failed to save {}: {e}", filename),
                    );
                    -1
                }
            }
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_download_url",
        |caller: Caller<'_, HostState>, url_ptr: u32, url_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let url = read_guest_string(&mem, &caller, url_ptr, url_len).unwrap_or_default();
            if url.is_empty() {
                return -1;
            }
            caller.data().download_manager.start_download(url.clone());
            console_log(
                &caller.data().console,
                ConsoleLevel::Log,
                format!("[DOWNLOAD] Started download for {url}"),
            );
            0
        },
    )?;

    linker.func_wrap(
        "oxide",
        "api_canvas_print_pdf",
        |caller: Caller<'_, HostState>, filename_ptr: u32, filename_len: u32| -> i32 {
            let mem = caller.data().memory.expect("memory not set");
            let filename =
                read_guest_string(&mem, &caller, filename_ptr, filename_len).unwrap_or_default();
            if filename.is_empty() {
                return -1;
            }
            let canvas = caller.data().canvas.lock().unwrap().clone();
            match render_canvas_to_pdf(&canvas, &filename) {
                Ok(_) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Log,
                        format!("[PRINT] Canvas exported to PDF: {filename}"),
                    );
                    0
                }
                Err(e) => {
                    console_log(
                        &caller.data().console,
                        ConsoleLevel::Error,
                        format!("[PRINT] PDF export failed: {e}"),
                    );
                    -1
                }
            }
        },
    )?;

    Ok(())
}

fn getrandom(buf: &mut [u8]) {
    ::getrandom::getrandom(buf).expect("OS random number generator unavailable");
}

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

    #[test]
    fn module_origin_ignores_path_changes() {
        let state = HostState::default();
        set_module_origin(&state, "https://example.com/apps/a.wasm");
        let first = state.module_origin.lock().unwrap().clone();
        // Same origin, different path (e.g. after navigating to a sibling module).
        set_module_origin(&state, "https://example.com/other/b.wasm");
        assert_eq!(*state.module_origin.lock().unwrap(), first);
    }

    #[test]
    fn session_storage_survives_same_origin_reload() {
        let state = HostState::default();
        set_module_origin(&state, "https://example.com/app.wasm");
        state
            .storage
            .lock()
            .unwrap()
            .insert("k".to_string(), "v".to_string());
        set_module_origin(&state, "https://example.com/app.wasm");
        assert_eq!(
            state.storage.lock().unwrap().get("k").map(String::as_str),
            Some("v")
        );
    }

    #[test]
    fn session_storage_cleared_on_cross_origin_navigation() {
        let state = HostState::default();
        set_module_origin(&state, "https://a.com/app.wasm");
        state
            .storage
            .lock()
            .unwrap()
            .insert("k".to_string(), "v".to_string());
        set_module_origin(&state, "https://b.com/app.wasm");
        assert!(state.storage.lock().unwrap().is_empty());
    }

    #[test]
    fn local_apps_in_different_directories_have_different_origins() {
        let state = HostState::default();
        set_module_origin(&state, "file:///tmp/app-one/index.wasm");
        let one = state.module_origin.lock().unwrap().clone();
        set_module_origin(&state, "file:///tmp/app-two/index.wasm");
        assert_ne!(*state.module_origin.lock().unwrap(), one);
    }
}