waterui-ffi 0.5.1

//! FFI bindings for the `GpuSurface` raw view.
//!
//! This module provides the FFI interface for high-performance GPU rendering
//! using wgpu. Uses a shared GPU context for efficient multi-view rendering.
//!
//! The native backend is responsible for:
//! 1. Creating persistent renderer state with `waterui_gpu_surface_create`
//! 2. Providing somewhere to draw, which differs by platform:
//!    - Android attaches a `SurfaceView`'s `ANativeWindow` with
//!      `waterui_gpu_surface_attach`, replaces it as its lifecycle demands, and
//!      renders into the swapchain with `waterui_gpu_surface_render`.
//!    - Apple owns the presentation memory itself: a pair of `IOSurface`-backed
//!      `MTLTexture`s shown as a plain layer's `contents`. It declares the
//!      target format once with `waterui_gpu_surface_prepare_metal_texture` and
//!      renders each frame with `waterui_gpu_surface_render_to_metal_texture`,
//!      so there is no swapchain to attach and `attach`, `detach` and `render`
//!      panic there.
//! 3. Calling into whichever of those applies when the redraw callback fires
//! 4. Calling `waterui_gpu_surface_drop` when the semantic view is destroyed
//!
//! # Thread affinity
//!
//! `WuiGpuSurfaceState` is single-threaded `Rc`/`RefCell` state. Every entry
//! point taking a `WuiGpuSurfaceState` pointer must run on the thread that
//! created the state (the renderer's owning thread), whether or not an
//! individual safety comment repeats it. The only cross-thread contracts are
//! the installed redraw callback (safe to fire from any thread) and the
//! capture-completion callback, which runs on the shared GPU completion
//! thread.

use core::ffi::c_void;
use std::cell::{Cell, RefCell};
use std::rc::Rc;
use std::sync::Arc;
use std::time::{Duration, Instant};

use alloc::boxed::Box;
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
use alloc::vec;
use executor_core::spawn_local;
use futures::FutureExt;

#[cfg(any(target_os = "macos", target_os = "ios"))]
use {
    objc2::{rc::Retained, runtime::ProtocolObject},
    objc2_metal::{MTLPixelFormat, MTLTexture, MTLTextureType},
    wgpu_hal::{Api, api::Metal as MetalApi},
};

use waterui_graphics::gpu_surface::{
    GestureState, GpuContext, GpuFrame, GpuSurface, PointerState, RedrawHandle,
};
use waterui_graphics::shared_context::{GpuRuntime, GpuSubmissionCompletionDriver};

use waterui_core::Str;

use crate::components::layouting::layout::{WuiProposalSize, WuiViewDimensions};
use crate::{IntoFFI, IntoRust, WuiStr};

/// FFI representation of a `GpuSurface` view.
///
/// This struct is passed to the native backend when rendering the view tree.
/// The native backend consumes it with `waterui_gpu_surface_create`, then owns
/// the returned state for the semantic view lifetime.
#[repr(C)]
#[derive(Debug)]
pub struct WuiGpuSurface {
    /// Opaque pointer to the boxed `GpuSurface`.
    /// This is consumed during state creation and should not be used after.
    pub surface: *mut c_void,
    /// Whether this surface should register as a picture-in-picture host.
    pub has_picture_in_picture_host_id: bool,
    /// Stable picture-in-picture host id when `has_picture_in_picture_host_id` is true.
    pub picture_in_picture_host_id: u64,
}

impl IntoFFI for GpuSurface {
    type FFI = WuiGpuSurface;

    fn into_ffi(self) -> Self::FFI {
        // Box the GpuSurface for FFI transfer.
        let boxed = Box::new(self);
        let picture_in_picture_host_id = boxed.picture_in_picture_host();
        let ptr = Box::into_raw(boxed).cast::<c_void>();
        WuiGpuSurface {
            surface: ptr,
            has_picture_in_picture_host_id: picture_in_picture_host_id.is_some(),
            picture_in_picture_host_id: picture_in_picture_host_id.unwrap_or(0),
        }
    }
}

// Generate waterui_gpu_surface_id() and waterui_force_as_gpu_surface()
ffi_view!(GpuSurface, WuiGpuSurface, gpu_surface);

/// Opaque state held by the native backend after initialization.
///
/// Owns the semantic renderer and environment GPU runtime independently of the
/// currently attached presentation surface.
pub struct WuiGpuSurfaceState {
    /// Explicit environment-owned GPU runtime used by this semantic view.
    runtime: GpuRuntime,
    /// Native presentation surface currently attached to this semantic GPU view.
    ///
    /// Android may replace the underlying `ANativeWindow` while preserving the
    /// `GpuView` and its persistent resources. Apple platforms present through
    /// host-owned textures instead and never attach a swapchain.
    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
    wgpu_surface: Option<wgpu::Surface<'static>>,
    /// Surface configuration
    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
    config: Option<wgpu::SurfaceConfiguration>,
    /// The `ANativeWindow` `layer` was — kept so the surface can be recreated
    /// on a rebuilt runtime after device loss without another attach call.
    /// Valid while `wgpu_surface` is `Some`; stale otherwise.
    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
    attached_layer: *mut c_void,
    /// The HDR preference `attach` configured the surface with.
    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
    attached_prefers_hdr: bool,
    /// The [`SharedGpuContext`] generation `wgpu_surface`, `config` and the
    /// renderer were built under. Anything else means they belong to a dead
    /// device and must be recreated before the next frame.
    #[cfg(not(any(target_os = "macos", target_os = "ios")))]
    context_generation: u64,
    /// The format selected when asynchronous renderer setup starts.
    renderer_format: Cell<Option<wgpu::TextureFormat>>,
    /// Where this surface's frame is drawn when an enclosing capture wants it.
    ///
    /// Android's HWUI records a `SurfaceView` as a cleared hole, so a surface
    /// inside a filtered or effected subtree is missing from that subtree's
    /// captured buffer and is drawn into it from here instead. Kept across
    /// frames and reallocated only when the size or the renderer's format
    /// changes.
    #[cfg(target_os = "android")]
    composite_texture: Option<wgpu::Texture>,
    /// Becomes true only after the local setup future has completed.
    setup_ready: Rc<Cell<bool>>,
    /// Maximum MSAA sample count requested by the public `GpuSurface` API.
    msaa_max_samples: core::num::NonZeroU32,
    /// Main-thread semantic renderer and environment. Setup temporarily moves
    /// this value into its local future, then returns it to the slot.
    semantic: Rc<RefCell<Option<GpuSurfaceSemantic>>>,
    /// Layout priority does not change during renderer setup.
    priority: i32,
    /// Current width from layout
    current_width: u32,
    /// Current height from layout
    current_height: u32,
    /// Current pointer/cursor state
    pointer_state: PointerState,
    /// Current gesture state (pinch, pan, double-tap)
    gesture_state: GestureState,
    /// Animation clock start for frame timing.
    start_time: Instant,
    /// Timestamp of the previous render.
    last_frame_time: Instant,
    /// Redraw handle for external redraw triggers.
    redraw_handle: RedrawHandle,
    /// Whether the semantic GPU view takes its own keyboard, IME and scroll
    /// input, captured once when this state is created.
    ///
    /// `GpuView::wants_input_events` answers a registration-time question, and
    /// hosts ask it before the asynchronous renderer setup has necessarily
    /// finished — while the semantic slot is temporarily empty. Caching the
    /// answer keeps it available for the whole life of the state.
    wants_input_events: bool,
}

impl core::fmt::Debug for WuiGpuSurfaceState {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("WuiGpuSurfaceState")
            .field("current_width", &self.current_width)
            .field("current_height", &self.current_height)
            .finish_non_exhaustive()
    }
}

impl WuiGpuSurfaceState {
    /// Whether the semantic GPU view takes its own input.
    ///
    /// See the field of the same name for why the answer is cached rather than
    /// asked of the renderer on every call.
    pub(super) const fn wants_input_events(&self) -> bool {
        self.wants_input_events
    }

    /// The semantic GPU view's text caret, in logical surface-local coordinates.
    ///
    /// `None` while the renderer's asynchronous setup is still running, and
    /// whenever the view has no caret to place an input-method panel against.
    pub(super) fn ime_caret(&self) -> Option<kurbo::Rect> {
        self.semantic
            .borrow()
            .as_ref()
            .and_then(|semantic| semantic.gpu_surface.ime_caret())
    }

    /// What the semantic GPU view says about itself, for a screen reader.
    ///
    /// `None` while the renderer's asynchronous setup is still running, and
    /// whenever the view has nothing to say about its pixels.
    fn accessibility_label(&self) -> Option<Str> {
        self.semantic
            .borrow()
            .as_ref()
            .and_then(|semantic| semantic.gpu_surface.accessibility_label())
            .map(Str::from)
    }

    /// The semantic content the GPU view carries, for a screen reader.
    ///
    /// `None` while the renderer's asynchronous setup is still running, and
    /// whenever the view publishes no semantic value.
    fn accessibility_value(&self) -> Option<Str> {
        self.semantic
            .borrow()
            .as_ref()
            .and_then(|semantic| semantic.gpu_surface.accessibility_value())
            .map(Str::from)
    }
}

/// What this surface's content says about itself, for a screen reader.
///
/// A surface is an opaque rectangle to the platform's accessibility layer:
/// whatever the formula, chart or diagram inside it means, nothing outside the
/// content can read it back off the pixels. A host names the surface's element
/// with this when the application named it nothing, so an explicit label from
/// the application always wins.
///
/// Ask again after each frame. A view whose content follows a signal re-draws
/// and re-describes itself at the same moment, and the answer is empty until
/// asynchronous renderer setup finishes, which is before the first frame.
///
/// # Returns
///
/// An owning [`WuiStr`], empty when this surface has nothing to say — which a
/// host treats the same way it treats a view that never had a label. There is
/// deliberately no third state: "no label" and "the empty label" are the same
/// instruction to a screen reader, so the ABI does not carry a distinction
/// nothing acts on.
///
/// # Safety
///
/// `state` must be a valid pointer returned by
/// [`waterui_gpu_surface_create`], on the thread that created it.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_accessibility_label(
    state: *const WuiGpuSurfaceState,
) -> WuiStr {
    // SAFETY: the caller contract requires `state` to be a valid handle that stays
    // alive for this call; it is only borrowed.
    let state = unsafe { crate::borrow_ffi(state) };
    state.accessibility_label().unwrap_or_default().into_ffi()
}

/// The semantic value this surface's content carries, for a screen reader.
///
/// This is the value channel's counterpart to
/// [`waterui_gpu_surface_accessibility_label`]: the content's own semantic
/// payload — a formula's spoken mathematics, a chart's summary — which a host
/// publishes on the surface's element so an application-supplied label does not
/// have to stand in for it.
///
/// Ask again after each frame, for the same reason as the label: a view whose
/// content follows a signal re-draws and re-describes itself at the same
/// moment, and the answer is empty until asynchronous renderer setup finishes.
///
/// # Returns
///
/// An owning [`WuiStr`], empty when this surface publishes no value. There is
/// no third state: "no value" and "the empty value" are the same instruction
/// to a screen reader.
///
/// # Safety
///
/// `state` must be a valid pointer returned by
/// [`waterui_gpu_surface_create`], on the thread that created it.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_accessibility_value(
    state: *const WuiGpuSurfaceState,
) -> WuiStr {
    // SAFETY: the caller contract requires `state` to be a valid handle that stays
    // alive for this call; it is only borrowed.
    let state = unsafe { crate::borrow_ffi(state) };
    state.accessibility_value().unwrap_or_default().into_ffi()
}

struct GpuSurfaceSemantic {
    gpu_surface: GpuSurface,
    env: waterui::Environment,
}

/// Submission fence returned after encoding an external-texture capture.
///
/// The renderer state remains on its owning UI thread. Native consumes this
/// token by registering a completion with
/// [`waterui_gpu_capture_fence_on_complete`].
#[derive(Debug)]
pub struct WuiGpuCaptureFence {
    completion_driver: GpuSubmissionCompletionDriver,
    submission: wgpu::SubmissionIndex,
}

impl WuiGpuCaptureFence {
    /// Wraps one queue submission as the token native waits on.
    ///
    /// Every external capture path ends here, whichever platform primitive it
    /// started from, so `waterui_gpu_capture_fence_on_complete` is the one way a
    /// backend learns that the GPU is finished with the memory it lent us.
    // Only the platforms with an external capture path produce a fence: Metal
    // on Apple, `AHardwareBuffer` on Android. Elsewhere the type is consumed by
    // `waterui_gpu_capture_fence_on_complete` alone, so a constructor would be
    // dead code.
    #[cfg(any(
        target_os = "macos",
        target_os = "ios",
        all(target_os = "android", feature = "gpu")
    ))]
    pub(crate) const fn new(
        completion_driver: GpuSubmissionCompletionDriver,
        submission: wgpu::SubmissionIndex,
    ) -> Self {
        Self {
            completion_driver,
            submission,
        }
    }
}

/// Completion function invoked after an external GPU capture submission.
pub type WuiGpuCaptureCompletionCallback = unsafe extern "C" fn(context: *mut c_void);

/// Releases the foreign completion context after its callback returns.
pub type WuiGpuCaptureCompletionDrop = unsafe extern "C" fn(context: *mut c_void);

struct ForeignGpuCaptureCompletion {
    context: usize,
    callback: WuiGpuCaptureCompletionCallback,
    drop: WuiGpuCaptureCompletionDrop,
}

impl ForeignGpuCaptureCompletion {
    fn complete(self) {
        // SAFETY: `callback` and `context` were registered together by the backend,
        // and the context outlives this handle.
        unsafe { (self.callback)(self.context as *mut c_void) };
    }
}

impl Drop for ForeignGpuCaptureCompletion {
    fn drop(&mut self) {
        // SAFETY: `drop` and `context` are one registration from the backend, and
        // `Drop` runs once.
        unsafe { (self.drop)(self.context as *mut c_void) };
    }
}

fn advance_frame_timing(state: &mut WuiGpuSurfaceState) -> (Duration, Duration) {
    let now = Instant::now();
    let elapsed = now.duration_since(state.start_time);
    let delta = now
        .duration_since(state.last_frame_time)
        .min(Duration::from_millis(100));
    state.last_frame_time = now;
    (elapsed, delta)
}

/// Native callback invoked when an idle `GpuSurface` becomes dirty.
pub type WuiGpuSurfaceRedrawCallback = unsafe extern "C" fn(context: *mut c_void);

struct ForeignRedrawTarget {
    context: usize,
    wake: WuiGpuSurfaceRedrawCallback,
    drop: WuiGpuSurfaceRedrawCallback,
}

// SAFETY: native installs callbacks whose context is explicitly documented as
// callable and releasable from any thread. The target owns that context until
// its `drop` callback runs.
unsafe impl Send for ForeignRedrawTarget {}
// SAFETY: see the `Send` implementation. The wake callback must be thread-safe.
unsafe impl Sync for ForeignRedrawTarget {}

impl ForeignRedrawTarget {
    fn wake(&self) {
        // SAFETY: `wake` and `context` were registered together by the backend, and
        // the context outlives this waker.
        unsafe { (self.wake)(self.context as *mut c_void) };
    }
}

impl Drop for ForeignRedrawTarget {
    fn drop(&mut self) {
        // SAFETY: `drop` and `context` are one registration from the backend, and
        // `Drop` runs once.
        unsafe { (self.drop)(self.context as *mut c_void) };
    }
}

/// Renderer-driven HDR preference exported to native backends before init.
///
/// `has_preference = false` means the surface should follow backend/global policy.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct WuiGpuSurfaceHdrPreference {
    /// Whether the renderer provided an explicit HDR/SDR preference.
    pub has_preference: bool,
    /// Explicit preferred dynamic range when `has_preference` is true.
    pub prefers_hdr: bool,
}

/// Returns the renderer-driven HDR preference for a `WuiGpuSurface`.
///
/// This must be called before `waterui_gpu_surface_create` consumes the surface.
///
/// # Safety
///
/// - `surface` must be a valid pointer obtained from `waterui_force_as_gpu_surface`
/// - `surface` must not have been consumed by `waterui_gpu_surface_create`
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_hdr_preference(
    surface: *const WuiGpuSurface,
) -> WuiGpuSurfaceHdrPreference {
    // SAFETY: the caller contract requires `surface` to be a valid descriptor alive
    // for this call.
    let wui_surface = unsafe { &*surface };
    // SAFETY: a descriptor that has not been consumed holds a live `GpuSurface`; the
    // consuming path below nulls the field, so a stale read cannot reach here.
    let gpu_surface = unsafe { &*(wui_surface.surface as *const GpuSurface) };
    let explicit = gpu_surface.resolved_hdr_preference();
    WuiGpuSurfaceHdrPreference {
        has_preference: explicit.is_some(),
        prefers_hdr: explicit.unwrap_or(false),
    }
}

#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn attached_surface_format(
    capabilities: &wgpu::SurfaceCapabilities,
    renderer_format: Option<wgpu::TextureFormat>,
    prefer_hdr: bool,
) -> wgpu::TextureFormat {
    renderer_format.map_or_else(
        || {
            waterui_graphics::gpu_surface::preferred_surface_format_with_preference(
                capabilities,
                prefer_hdr,
            )
        },
        |format| {
            assert!(
                capabilities.formats.contains(&format),
                "waterui_gpu_surface_attach: replacement surface does not support the renderer's established format {format:?}"
            );
            format
        },
    )
}

#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn create_attached_surface(
    gpu: &waterui_graphics::shared_context::SharedGpuContext,
    layer: *mut c_void,
    width: u32,
    height: u32,
    renderer_format: Option<wgpu::TextureFormat>,
    prefer_hdr: bool,
) -> (wgpu::Surface<'static>, wgpu::SurfaceConfiguration) {
    assert!(
        width > 0 && height > 0,
        "waterui_gpu_surface_attach: native surface dimensions must be non-zero, got {width}x{height}"
    );

    let wgpu_surface = create_surface_from_layer(&gpu.instance, layer);
    let surface_caps = wgpu_surface.get_capabilities(&gpu.adapter);

    let format = attached_surface_format(&surface_caps, renderer_format, prefer_hdr);

    assert!(
        surface_caps
            .present_modes
            .contains(&wgpu::PresentMode::Fifo),
        "waterui_gpu_surface_attach: surface does not support FIFO presentation"
    );

    let alpha_mode = [
        wgpu::CompositeAlphaMode::PreMultiplied,
        wgpu::CompositeAlphaMode::PostMultiplied,
        wgpu::CompositeAlphaMode::Inherit,
        wgpu::CompositeAlphaMode::Opaque,
    ]
    .into_iter()
    .find(|mode| surface_caps.alpha_modes.contains(mode))
    .unwrap_or_else(|| {
        panic!("waterui_gpu_surface_attach: surface reports no supported composite alpha mode")
    });

    let config = wgpu::SurfaceConfiguration {
        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
        format,
        width,
        height,
        present_mode: wgpu::PresentMode::Fifo,
        alpha_mode,
        view_formats: vec![],
        desired_maximum_frame_latency: 2,
    };
    super::checked_surface_configure(
        &wgpu_surface,
        &gpu.device,
        &config,
        "waterui_gpu_surface_attach",
    );
    (wgpu_surface, config)
}

fn start_renderer_setup(state: &WuiGpuSurfaceState, format: wgpu::TextureFormat) {
    if let Some(existing) = state.renderer_format.get() {
        assert_eq!(
            existing, format,
            "GpuSurface target format changed after renderer setup started"
        );
        return;
    }

    state.renderer_format.set(Some(format));
    spawn_renderer_setup(state, format);
}

/// Re-runs renderer setup after the runtime's device was lost and rebuilt.
///
/// The `GpuView`'s pipelines and textures all belonged to the dead device, so
/// `setup` runs again on the fresh context; `setup_ready` drops for the
/// duration and the redraw it schedules replaces whatever the last frame on
/// the dead device looked like.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn restart_renderer_setup(state: &WuiGpuSurfaceState, format: wgpu::TextureFormat) {
    // A setup already in flight read the rebuilt context when it started, so it
    // is the recovery; starting another one would panic on the empty slot.
    if state.semantic.borrow().is_none() {
        return;
    }
    state.setup_ready.set(false);
    spawn_renderer_setup(state, format);
}

fn spawn_renderer_setup(state: &WuiGpuSurfaceState, format: wgpu::TextureFormat) {
    let mut semantic = state
        .semantic
        .borrow_mut()
        .take()
        .expect("GpuSurface semantic renderer is unavailable before setup starts");
    let semantic_slot = Rc::clone(&state.semantic);
    let setup_ready = Rc::clone(&state.setup_ready);
    let runtime = state.runtime.clone();
    let redraw_handle = state.redraw_handle.clone();
    let msaa_max_samples = state.msaa_max_samples;

    spawn_local(async move {
        let GpuSurfaceSemantic { gpu_surface, env } = &mut semantic;
        // Setup retries until it completes on the context that is still the
        // runtime's current one. A device loss mid-setup leaves the just-built
        // pipelines bound to a dead device — installing them would panic the
        // next frame inside `wgpu`'s purged storage, so a stale or crashed
        // attempt loops around and runs again on the rebuilt context.
        loop {
            let gpu = runtime.context();
            let outcome = {
                let ctx = GpuContext::new(
                    &gpu.adapter,
                    &gpu.device,
                    &gpu.queue,
                    format,
                    gpu.shader_cache.as_ref(),
                    gpu.scene_renderer(),
                    msaa_max_samples,
                    redraw_handle.clone(),
                    gpu.device_loss(),
                );
                std::panic::AssertUnwindSafe(gpu_surface.setup(&ctx, env))
                    .catch_unwind()
                    .await
            };
            if let Err(payload) = outcome {
                if gpu.device_lost_reason().is_none() {
                    std::panic::resume_unwind(payload);
                }
                continue;
            }
            if gpu.device_lost_reason().is_none()
                && runtime.context().generation() == gpu.generation()
            {
                break;
            }
        }
        semantic_slot.replace(Some(semantic));
        setup_ready.set(true);
        redraw_handle.request_redraw();
    })
    .detach();
}

/// Whether the process was asked to fake one device loss, for end-to-end
/// recovery checks on real Android drivers that do not lose on demand.
///
/// `WATERUI_SIMULATE_GPU_LOSS` is a testing hook: when set, the first render
/// call marks the shared context lost and `ensure_current_context` takes the
/// same rebuild a driver-reported loss would.
#[cfg(target_os = "android")]
fn simulate_device_loss_requested() -> bool {
    static REQUESTED: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
    *REQUESTED.get_or_init(|| std::env::var_os("WATERUI_SIMULATE_GPU_LOSS").is_some())
}

/// Marks the shared context lost exactly once per process when the
/// `WATERUI_SIMULATE_GPU_LOSS` test hook is set.
#[cfg(target_os = "android")]
fn simulate_device_loss_once(state: &WuiGpuSurfaceState) {
    static FIRED: core::sync::atomic::AtomicBool = core::sync::atomic::AtomicBool::new(false);
    if !FIRED.swap(true, core::sync::atomic::Ordering::Relaxed) && simulate_device_loss_requested()
    {
        state
            .runtime
            .context()
            .mark_device_lost_for_testing("simulated loss via WATERUI_SIMULATE_GPU_LOSS");
    }
}

/// The runtime's current context, recreating the attached surface and the
/// renderer when the generation this state was built under died with its
/// device.
///
/// The `ANativeWindow` outlives any `wgpu::Surface` made from it, so recovery
/// is a local rebuild: the frame this state was asked for still runs, just
/// against the fresh device.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
pub(crate) fn ensure_current_context(
    state: &mut WuiGpuSurfaceState,
) -> Arc<waterui_graphics::shared_context::SharedGpuContext> {
    let gpu = state.runtime.context();
    if gpu.generation() == state.context_generation {
        return gpu;
    }

    tracing::warn!(
        old = state.context_generation,
        new = gpu.generation(),
        "GPU device was replaced; recreating the surface and renderer"
    );
    state.context_generation = gpu.generation();
    #[cfg(target_os = "android")]
    {
        state.composite_texture = None;
    }

    // A detached surface has no `wgpu::Surface` to recreate, but its renderer —
    // set up back at the first attach — is still device-bound.
    if state.wgpu_surface.is_some() {
        drop(state.wgpu_surface.take());
        state.config = None;
        let (surface, config) = create_attached_surface(
            &gpu,
            state.attached_layer,
            state.current_width,
            state.current_height,
            state.renderer_format.get(),
            state.attached_prefers_hdr,
        );
        state.config = Some(config);
        state.wgpu_surface = Some(surface);
    }
    if let Some(format) = state.renderer_format.get() {
        restart_renderer_setup(state, format);
    }
    gpu
}

fn with_semantic_mut<T>(
    state: &WuiGpuSurfaceState,
    use_semantic: impl FnOnce(&mut GpuSurfaceSemantic) -> T,
) -> T {
    assert!(
        state.setup_ready.get(),
        "GpuSurface renderer used before asynchronous setup completed"
    );
    let mut semantic = state.semantic.borrow_mut();
    use_semantic(
        semantic
            .as_mut()
            .expect("GpuSurface ready state is missing its semantic renderer"),
    )
}

/// Runs `use_surface` against the semantic GPU view when one is available.
///
/// Unlike [`with_semantic_mut`], a missing renderer is not a contract
/// violation here: input can land on a surface whose asynchronous setup has not
/// finished, and the caller reports that to the host as "the event did not
/// reach the view" rather than crashing on the user's keystroke.
pub(super) fn with_semantic_input<T>(
    state: &WuiGpuSurfaceState,
    use_surface: impl FnOnce(&mut GpuSurface) -> T,
) -> Option<T> {
    state
        .semantic
        .borrow_mut()
        .as_mut()
        .map(|semantic| use_surface(&mut semantic.gpu_surface))
}

#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn attached_surface<'a>(
    state: &'a WuiGpuSurfaceState,
    scope: &'static str,
) -> &'a wgpu::Surface<'static> {
    state
        .wgpu_surface
        .as_ref()
        .unwrap_or_else(|| panic!("{scope}: native surface is detached"))
}

#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn attached_config<'a>(
    state: &'a WuiGpuSurfaceState,
    scope: &'static str,
) -> &'a wgpu::SurfaceConfiguration {
    state
        .config
        .as_ref()
        .unwrap_or_else(|| panic!("{scope}: native surface is detached"))
}

/// Creates the persistent state for one semantic `GpuSurface`.
///
/// This consumes the renderer exactly once. Native presentation surfaces are
/// attached and detached independently with [`waterui_gpu_surface_attach`] and
/// [`waterui_gpu_surface_detach`].
///
/// # Safety
///
/// - `surface` must be a valid, unconsumed descriptor returned by
///   `waterui_force_as_gpu_surface`.
/// - `env` must remain valid for this call; the state stores its own clone.
///
/// # Panics
///
/// Panics if `surface`'s inner `GpuSurface` pointer is null, meaning the
/// descriptor was already consumed by a previous call to this function.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_create(
    surface: *mut WuiGpuSurface,
    env: *const crate::WuiEnv,
) -> *mut WuiGpuSurfaceState {
    // SAFETY: the caller contract requires `surface` to be a valid descriptor that no
    // one else is borrowing for this call.
    let wui_surface = unsafe { &mut *surface };
    assert!(
        !wui_surface.surface.is_null(),
        "waterui_gpu_surface_create: descriptor was already consumed"
    );
    let gpu_surface: GpuSurface =
        // SAFETY: the assert above proves the descriptor still owns its `GpuSurface`,
        // and the field is nulled immediately after, so it is reclaimed once.
        unsafe { *Box::from_raw(wui_surface.surface.cast::<GpuSurface>()) };
    wui_surface.surface = core::ptr::null_mut();

    let msaa_max_samples = gpu_surface.msaa_sample_limit();
    let priority = gpu_surface.priority();
    let wants_input_events = gpu_surface.wants_input_events();
    // SAFETY: the caller contract requires `env` to be a valid handle alive for this
    // call; it is only borrowed before cloning.
    let env = unsafe { &*env }.0.clone();
    let runtime = super::gpu_runtime::gpu_runtime(&env);
    let now = Instant::now();
    Box::into_raw(Box::new(WuiGpuSurfaceState {
        runtime,
        #[cfg(not(any(target_os = "macos", target_os = "ios")))]
        wgpu_surface: None,
        #[cfg(not(any(target_os = "macos", target_os = "ios")))]
        attached_layer: core::ptr::null_mut(),
        #[cfg(not(any(target_os = "macos", target_os = "ios")))]
        attached_prefers_hdr: false,
        #[cfg(not(any(target_os = "macos", target_os = "ios")))]
        context_generation: 0,
        renderer_format: Cell::new(None),
        #[cfg(target_os = "android")]
        composite_texture: None,
        setup_ready: Rc::new(Cell::new(false)),
        msaa_max_samples,
        #[cfg(not(any(target_os = "macos", target_os = "ios")))]
        config: None,
        semantic: Rc::new(RefCell::new(Some(GpuSurfaceSemantic { gpu_surface, env }))),
        priority,
        current_width: 0,
        current_height: 0,
        pointer_state: PointerState::default(),
        gesture_state: GestureState::default(),
        start_time: now,
        last_frame_time: now
            .checked_sub(Duration::from_secs_f32(1.0 / 60.0))
            .unwrap(),
        redraw_handle: RedrawHandle::new(),
        wants_input_events,
    }))
}

/// Measures the semantic GPU view without touching presentation resources.
///
/// # Safety
///
/// `state` must be valid and this function must run on the renderer's owning
/// thread.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_measure(
    state: *const WuiGpuSurfaceState,
    proposal: WuiProposalSize,
) -> WuiViewDimensions {
    // SAFETY: the caller contract requires `state` to be a valid handle that stays
    // alive for this call; it is only borrowed.
    let state = unsafe { crate::borrow_ffi(state) };
    // SAFETY: the caller contract makes `proposal` an owning handle from the
    // matching FFI constructor; it is consumed here and not observed again.
    measure_state(state, unsafe { proposal.into_rust() }).into_ffi()
}

pub(crate) fn measure_state(
    state: &WuiGpuSurfaceState,
    proposal: waterui_core::layout::ProposalSize,
) -> waterui_core::layout::ViewDimensions {
    let semantic = state.semantic.borrow();
    semantic.as_ref().map_or_else(
        || {
            // Asynchronous setup owns the renderer right now, and hosts
            // legitimately lay out while it runs. Answer with `GpuView`'s own
            // default measurement (fill the proposal); setup completion wakes
            // the host, which re-measures custom-sized views.
            waterui_core::layout::ViewDimensions::new(waterui_core::layout::Size::new(
                proposal.width.unwrap_or(0.0),
                proposal.height.unwrap_or(0.0),
            ))
        },
        |semantic| semantic.gpu_surface.measure(proposal),
    )
}

/// Returns the layout priority declared by the semantic GPU view.
///
/// # Safety
///
/// `state` must be valid and this function must run on the renderer's owning
/// thread.
#[unsafe(no_mangle)]
pub const unsafe extern "C" fn waterui_gpu_surface_priority(
    state: *const WuiGpuSurfaceState,
) -> i32 {
    // SAFETY: the caller contract requires `state` to be a valid handle that stays
    // alive for this call; it is only borrowed.
    let state = unsafe { crate::borrow_ffi(state) };
    priority_state(state)
}

pub(crate) const fn priority_state(state: &WuiGpuSurfaceState) -> i32 {
    state.priority
}

/// Replaces the native presentation surface while preserving the semantic
/// `GpuView` and its persistent renderer resources.
///
/// Android calls this when `SurfaceView` receives a replacement `Surface`.
/// Apple platforms have no swapchain to replace and call
/// [`waterui_gpu_surface_prepare_metal_texture`] instead.
///
/// # Safety
///
/// - `state` must be a valid pointer returned by [`waterui_gpu_surface_create`].
/// - `layer` must remain valid until [`waterui_gpu_surface_detach`] is called.
/// - The state must currently be detached.
///
/// # Panics
///
/// Panics if `state` already has a native surface attached, or if `width` or
/// `height` is zero. Panics unconditionally on Apple platforms.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_attach(
    state: *mut WuiGpuSurfaceState,
    layer: *mut c_void,
    width: u32,
    height: u32,
    prefers_hdr: bool,
) {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    assert!(
        state.wgpu_surface.is_none(),
        "waterui_gpu_surface_attach: native surface is already attached"
    );

    let gpu = state.runtime.context();
    let (surface, config) = create_attached_surface(
        &gpu,
        layer,
        width,
        height,
        state.renderer_format.get(),
        prefers_hdr,
    );

    state.current_width = width;
    state.current_height = height;
    let format = config.format;
    state.config = Some(config);
    state.wgpu_surface = Some(surface);
    state.attached_layer = layer;
    state.attached_prefers_hdr = prefers_hdr;
    state.context_generation = gpu.generation();
    start_renderer_setup(state, format);
}

/// Attaches a native presentation surface (non-Apple only).
///
/// # Safety
///
/// `state` must come from [`waterui_gpu_surface_create`].
///
/// # Panics
///
/// Always panics: Apple hosts own their presentation memory and start the
/// renderer with [`waterui_gpu_surface_prepare_metal_texture`].
#[cfg(any(target_os = "macos", target_os = "ios"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_attach(
    _state: *mut WuiGpuSurfaceState,
    _layer: *mut c_void,
    _width: u32,
    _height: u32,
    _prefers_hdr: bool,
) {
    panic!(
        "waterui_gpu_surface_attach: Apple hosts start the renderer with waterui_gpu_surface_prepare_metal_texture"
    );
}

/// Detaches the current native presentation surface without destroying the
/// semantic `GpuView` or its persistent renderer resources.
///
/// # Safety
///
/// `state` must be valid and currently have an attached native surface.
///
/// # Panics
///
/// Panics if `state` does not currently have a native surface attached. Panics
/// unconditionally on Apple platforms, which never attach one.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_detach(state: *mut WuiGpuSurfaceState) {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    let surface = state
        .wgpu_surface
        .take()
        .expect("waterui_gpu_surface_detach: native surface is already detached");
    drop(surface);
    state.config = None;
}

/// Detaches the native presentation surface (non-Apple only).
///
/// # Safety
///
/// `state` must come from [`waterui_gpu_surface_create`].
///
/// # Panics
///
/// Always panics: an Apple host releases its own textures and has no swapchain
/// to detach.
#[cfg(any(target_os = "macos", target_os = "ios"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_detach(_state: *mut WuiGpuSurfaceState) {
    panic!("waterui_gpu_surface_detach: Apple hosts own their presentation textures");
}

/// Installs the native wake target for renderer-driven redraw requests.
///
/// The wake callback may be called from any thread. `drop_callback` releases
/// `context` after the callback is replaced or the GPU state is destroyed.
///
/// # Safety
///
/// - `state` and `context` must be valid.
/// - Both callbacks must be thread-safe and use `context` only for the lifetime
///   retained by `drop_callback`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_set_redraw_callback(
    state: *mut WuiGpuSurfaceState,
    context: *mut c_void,
    wake: WuiGpuSurfaceRedrawCallback,
    drop_callback: WuiGpuSurfaceRedrawCallback,
) {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    let target = ForeignRedrawTarget {
        context: context as usize,
        wake,
        drop: drop_callback,
    };
    state
        .redraw_handle
        .set_waker(Some(Arc::new(move || target.wake())));
}

/// Returns whether the renderer's asynchronous setup has completed.
///
/// Setup completion also triggers the installed redraw callback, so native
/// backends can use this value to resolve first-paint readiness without polling.
///
/// # Safety
///
/// `state` must be a valid pointer returned by [`waterui_gpu_surface_create`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_is_ready(state: *const WuiGpuSurfaceState) -> bool {
    // SAFETY: the caller contract requires `state` to be a valid handle that stays
    // alive for this call; it is only borrowed.
    let state = unsafe { crate::borrow_ffi(state) };
    state.setup_ready.get()
}

/// Render a single frame.
///
/// This function should be called when the surface is dirty (size/input/state changed)
/// and backend should schedule another frame when `needs_redraw` is true.
///
/// # Arguments
///
/// * `state` - Pointer to the persistent state from `waterui_gpu_surface_create`
/// * `width` - Current surface width in physical pixels (from layout)
/// * `height` - Current surface height in physical pixels (from layout)
/// * `scale` - Physical pixels per logical unit for this frame (2.0 on a
///   Retina display). It is passed per frame rather than at attach time
///   because it changes when the window moves between displays.
///
/// # Returns
///
/// Whether another frame should be scheduled immediately.
///
/// # Safety
///
/// `state` must be valid and have an attached native surface.
///
/// # Panics
///
/// Panics if `width` or `height` is zero, or if `scale` is not positive and
/// finite. Panics unconditionally on Apple platforms.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_render(
    state: *mut WuiGpuSurfaceState,
    width: u32,
    height: u32,
    scale: f64,
) -> bool {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    assert!(
        width > 0 && height > 0,
        "waterui_gpu_surface_render: dimensions must be non-zero"
    );
    assert!(
        scale.is_finite() && scale > 0.0,
        "waterui_gpu_surface_render: scale must be a positive, finite device-pixel ratio, got {scale}"
    );

    // Test hook first so the marked loss is recovered inside this same frame.
    #[cfg(target_os = "android")]
    simulate_device_loss_once(state);

    // A device loss between frames lands here: the runtime swaps in a rebuilt
    // context, and the surface — bound to the dead device — is recreated from
    // the retained `ANativeWindow` before this frame touches it.
    let gpu = ensure_current_context(state);

    // A `None` is the mid-frame device-loss path: the frame stays pending and
    // the next render call lands on the rebuilt context.
    super::run_gpu_frame(&gpu, "waterui_gpu_surface_render", || {
        render_frame_body(state, &gpu, width, height, scale)
    })
    .unwrap_or(true)
}

/// Runs one frame's worth of work against `gpu` on an attached surface.
///
/// Split from [`waterui_gpu_surface_render`] so the frame body can run inside
/// [`super::run_gpu_frame`]'s `catch_unwind`: a driver-reported device loss
/// mid-call purges `wgpu`'s storage while the frame is still using it, and the
/// resulting internal panic is what the caller catches — but only when the
/// context confirms the loss.
#[cfg(not(any(target_os = "macos", target_os = "ios")))]
fn render_frame_body(
    state: &mut WuiGpuSurfaceState,
    gpu: &Arc<waterui_graphics::shared_context::SharedGpuContext>,
    width: u32,
    height: u32,
    scale: f64,
) -> bool {
    // Handle resize if needed
    if width != state.current_width || height != state.current_height {
        {
            let config = state
                .config
                .as_mut()
                .expect("waterui_gpu_surface_render: native surface is detached");
            config.width = width;
            config.height = height;
        }

        super::checked_surface_configure(
            attached_surface(state, "waterui_gpu_surface_render"),
            &gpu.device,
            attached_config(state, "waterui_gpu_surface_render"),
            "waterui_gpu_surface_render",
        );
        state.current_width = width;
        state.current_height = height;
    }

    let format = attached_config(state, "waterui_gpu_surface_render").format;
    if !state.setup_ready.get() {
        // The renderer is mid-setup — first attach or a device-loss rebuild —
        // so the frame stays pending and the host comes back for it.
        return true;
    }

    let Some(output) = super::acquire_surface_texture(
        attached_surface(state, "waterui_gpu_surface_render"),
        gpu,
        attached_config(state, "waterui_gpu_surface_render"),
        "waterui_gpu_surface_render",
    ) else {
        // Nothing was drawn, so the frame this call was asked for is still
        // pending: the host must come back for it once the surface can be
        // acquired again. Reporting it done here would strand a view whose only
        // clock is its own render loop.
        return true;
    };
    let view = output.texture.create_view(&wgpu::TextureViewDescriptor {
        label: Some("GpuSurface Frame View"),
        format: Some(format),
        ..Default::default()
    });

    let (elapsed, delta) = advance_frame_timing(state);

    // Create frame data
    let mut frame = GpuFrame::new(
        &gpu.device,
        &gpu.queue,
        &output.texture,
        view,
        format,
        width,
        height,
        scale,
        state.pointer_state,
        state.gesture_state,
        elapsed,
        delta,
    );

    // The dirty request that scheduled this frame is now satisfied. A new
    // request arriving during the renderer callback remains pending below.
    let _ = state.redraw_handle.take_dirty();
    with_semantic_mut(state, |semantic| {
        semantic.gpu_surface.render(&mut frame);
    });
    let needs_redraw = frame.was_redraw_requested() || state.redraw_handle.take_dirty();

    output.present();
    // Queue order retires this marker only after the frame's real work and
    // the present, so resolving it is what records this generation as having
    // presented — the signal the rebuild budget reads after a device loss.
    gpu.note_presented_submission(gpu.queue.submit([]));

    needs_redraw
}

/// Renders one frame into the attached swapchain (non-Apple only).
///
/// # Safety
///
/// `state` must come from [`waterui_gpu_surface_create`].
///
/// # Panics
///
/// Always panics: Apple hosts render with
/// [`waterui_gpu_surface_render_to_metal_texture`].
#[cfg(any(target_os = "macos", target_os = "ios"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_render(
    _state: *mut WuiGpuSurfaceState,
    _width: u32,
    _height: u32,
    _scale: f64,
) -> bool {
    panic!(
        "waterui_gpu_surface_render: Apple hosts render with waterui_gpu_surface_render_to_metal_texture"
    );
}

#[cfg(any(target_os = "macos", target_os = "ios"))]
fn metal_texture_format(texture: &ProtocolObject<dyn MTLTexture>) -> wgpu::TextureFormat {
    match texture.pixelFormat() {
        MTLPixelFormat::BGRA8Unorm => wgpu::TextureFormat::Bgra8Unorm,
        MTLPixelFormat::BGRA8Unorm_sRGB => wgpu::TextureFormat::Bgra8UnormSrgb,
        MTLPixelFormat::RGBA16Float => wgpu::TextureFormat::Rgba16Float,
        other => panic!("GpuSurface external Metal texture has unsupported format {other:?}"),
    }
}

/// Starts asynchronous renderer setup for an external Metal render target.
///
/// Completion triggers the installed redraw callback. Native must wait until
/// [`waterui_gpu_surface_is_ready`] returns true before rendering into the texture.
///
/// # Safety
///
/// `state` must be valid and `texture` must point to a live `MTLTexture`.
#[cfg(any(target_os = "macos", target_os = "ios"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_prepare_metal_texture(
    state: *mut WuiGpuSurfaceState,
    texture: *mut c_void,
) {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    // SAFETY: the caller contract requires `texture` to be a live `MTLTexture` that
    // stays alive for this call; it is only borrowed to read its pixel format.
    let texture = unsafe { &*texture.cast::<ProtocolObject<dyn MTLTexture>>() };
    start_renderer_setup(state, metal_texture_format(texture));
}

/// Render a single frame into an external Metal texture (Apple only).
///
/// `width` and `height` are physical pixels; `scale` is how many of them one
/// logical unit spans, so the renderer can work in the coordinate space the
/// view was laid out in.
///
/// # Safety
/// `state` must be valid, `texture` must point to a `MTLTexture`.
///
/// # Panics
///
/// Panics if `texture` is null, or if `scale` is not positive and finite.
#[cfg(any(target_os = "macos", target_os = "ios"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_render_to_metal_texture(
    state: *mut WuiGpuSurfaceState,
    texture: *mut core::ffi::c_void,
    width: u32,
    height: u32,
    scale: f64,
) -> *mut WuiGpuCaptureFence {
    assert!(
        scale.is_finite() && scale > 0.0,
        "waterui_gpu_surface_render_to_metal_texture: scale must be a positive, finite device-pixel ratio, got {scale}"
    );
    // SAFETY: the caller contract requires `state` to be a valid handle that no one
    // else is borrowing for this call.
    let state = unsafe { &mut *state };
    // SAFETY: the caller contract requires `texture` to be a live `MTLTexture`;
    // `retain` takes its own reference, so it stays alive for the render below.
    let metal_texture = unsafe {
        Retained::<ProtocolObject<dyn MTLTexture>>::retain(texture.cast())
            .expect("waterui_gpu_surface_render_to_metal_texture received a null texture")
    };

    let target_format = metal_texture_format(&metal_texture);
    assert_eq!(
        state.renderer_format.get(),
        Some(target_format),
        "waterui_gpu_surface_render_to_metal_texture called before preparing this target format"
    );
    assert!(
        state.setup_ready.get(),
        "waterui_gpu_surface_render_to_metal_texture called before asynchronous setup completed"
    );

    // SAFETY: `metal_texture` is the retained texture above, and the format and size
    // passed alongside it are read from that same texture, so the HAL description
    // matches the real resource.
    let hal_texture = unsafe {
        <MetalApi as Api>::Device::texture_from_raw(
            metal_texture,
            target_format,
            MTLTextureType::Type2D,
            1,
            1,
            wgpu_hal::CopyExtent {
                width,
                height,
                depth: 1,
            },
        )
    };
    let texture_desc = wgpu::TextureDescriptor {
        label: Some("GpuSurface Imported Metal Texture"),
        size: wgpu::Extent3d {
            width,
            height,
            depth_or_array_layers: 1,
        },
        mip_level_count: 1,
        sample_count: 1,
        dimension: wgpu::TextureDimension::D2,
        format: target_format,
        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
        view_formats: &[],
    };

    // SAFETY: the HAL texture above was created from this runtime's device, which is
    // the device the wgpu texture is being created on.
    let wgpu_texture = unsafe {
        state
            .runtime
            .context()
            .device
            .create_texture_from_hal::<MetalApi>(hal_texture, &texture_desc)
    };
    let view = wgpu_texture.create_view(&wgpu::TextureViewDescriptor {
        label: Some("GpuSurface Metal Frame View"),
        format: Some(target_format),
        ..Default::default()
    });
    render_into_texture(
        state,
        &wgpu_texture,
        view,
        target_format,
        width,
        height,
        scale,
    );
    let submission = state.runtime.context().queue.submit([]);
    let fence = WuiGpuCaptureFence::new(
        state.runtime.context().submission_completion_driver(),
        submission,
    );
    Box::into_raw(Box::new(fence))
}

/// Renders one frame of the semantic GPU view into a texture it does not own.
///
/// Every path that captures a surface into foreign memory ends here: Apple's
/// imported `MTLTexture` and Android's compositing of a surface nested inside a
/// captured subtree both hand in a texture of the renderer's established format
/// and take whatever the renderer draws into it. The redraw bookkeeping is a
/// presented frame's, so a renderer that asks for another frame from inside its
/// own draw is woken the same way whether it was presenting or being captured.
///
/// Nothing is submitted here: the renderer submits its own work, and the caller
/// decides what the frame is ordered against.
///
/// # Panics
///
/// Panics if the renderer's asynchronous setup has not completed.
#[cfg(any(target_os = "macos", target_os = "ios", target_os = "android"))]
pub(super) fn render_into_texture(
    state: &mut WuiGpuSurfaceState,
    texture: &wgpu::Texture,
    view: wgpu::TextureView,
    format: wgpu::TextureFormat,
    width: u32,
    height: u32,
    scale: f64,
) {
    let (elapsed, delta) = advance_frame_timing(state);
    let gpu = state.runtime.context();
    let mut frame = GpuFrame::new(
        &gpu.device,
        &gpu.queue,
        texture,
        view,
        format,
        width,
        height,
        scale,
        state.pointer_state,
        state.gesture_state,
        elapsed,
        delta,
    );

    let _ = state.redraw_handle.take_dirty();
    with_semantic_mut(state, |semantic| {
        semantic.gpu_surface.render(&mut frame);
    });
    if frame.was_redraw_requested() || state.redraw_handle.take_dirty() {
        state.redraw_handle.request_redraw();
    }
}

/// The GPU runtime this surface renders on, for a caller that needs its own
/// handle on the device and queue while the surface state is borrowed.
#[cfg(target_os = "android")]
pub(super) fn composite_runtime(state: &WuiGpuSurfaceState) -> GpuRuntime {
    state.runtime.clone()
}

/// Whether the surface's renderer setup has completed — `false` while a
/// device-loss rebuild is re-running it, when a composite would panic inside
/// `with_semantic_mut` instead of drawing.
#[cfg(target_os = "android")]
pub(super) fn composite_source_ready(state: &WuiGpuSurfaceState) -> bool {
    state.setup_ready.get()
}

/// Renders this surface's next frame into the texture a capture reads it from.
///
/// The returned texture holds one frame of the semantic GPU view at
/// `width`x`height` in the renderer's established format, ready to be drawn
/// into the enclosing capture's texture. It belongs to this state and is reused
/// for every frame of the same size.
///
/// # Panics
///
/// Panics if the renderer has no established format yet — a surface that has
/// never been attached has drawn nothing and cannot be composited — or if its
/// asynchronous setup has not completed.
#[cfg(target_os = "android")]
pub(super) fn render_composite_source(
    state: &mut WuiGpuSurfaceState,
    width: u32,
    height: u32,
    scale: f64,
) -> &wgpu::Texture {
    assert!(
        width > 0 && height > 0,
        "GpuSurface composite source must be non-zero, got {width}x{height}"
    );
    let format = state
        .renderer_format
        .get()
        .expect("GpuSurface cannot be composited into a capture before it has been attached once");
    let matches_request = state.composite_texture.as_ref().is_some_and(|texture| {
        texture.width() == width && texture.height() == height && texture.format() == format
    });
    if !matches_request {
        state.composite_texture = Some(state.runtime.context().device.create_texture(
            &wgpu::TextureDescriptor {
                label: Some("GpuSurface Composite Source"),
                size: wgpu::Extent3d {
                    width,
                    height,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT
                    | wgpu::TextureUsages::TEXTURE_BINDING,
                view_formats: &[],
            },
        ));
    }

    // Lent out for the render so the renderer's own `&mut` borrow of the state
    // and the texture do not overlap, then returned to its slot.
    let texture = state
        .composite_texture
        .take()
        .expect("GpuSurface composite source was just ensured");
    let view = texture.create_view(&wgpu::TextureViewDescriptor {
        label: Some("GpuSurface Composite Source View"),
        format: Some(format),
        ..Default::default()
    });
    render_into_texture(state, &texture, view, format, width, height, scale);
    state.composite_texture = Some(texture);
    state
        .composite_texture
        .as_ref()
        .expect("GpuSurface composite source was just returned")
}

/// Schedules one external capture submission completion and consumes its fence.
///
/// `callback` runs exactly once on the shared GPU completion thread. `drop`
/// then runs exactly once on that same thread, including if the completion
/// driver fails before invoking `callback`. Native callbacks should only
/// enqueue their next platform-specific stage and return immediately.
///
/// # Safety
///
/// `fence` must be a valid owning pointer returned by an external capture entry
/// point — `waterui_gpu_surface_render_to_metal_texture` on Apple,
/// `waterui_applied_filter_set_capture_hardware_buffer` or
/// `waterui_view_effect_set_input_hardware_buffer` on Android — and must be
/// consumed once.
/// `context`, `callback`, and `drop` must remain valid until completion; Rust
/// consumes the context and releases it through `drop`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_capture_fence_on_complete(
    fence: *mut WuiGpuCaptureFence,
    context: *mut c_void,
    callback: WuiGpuCaptureCompletionCallback,
    drop: WuiGpuCaptureCompletionDrop,
) {
    // A null fence is what a capture entry point returns when the device was
    // lost mid-copy: there is no submission to wait on, so the completion runs
    // immediately and the backend can release the buffer it lent.
    if fence.is_null() {
        // SAFETY: `callback`, `drop`, and `context` were registered together and
        // the context is still live — the copy never submitted, so nothing else
        // consumed it.
        unsafe {
            callback(context);
            drop(context);
        }
        return;
    }
    // SAFETY: the caller contract makes `fence` an owning pointer from the matching
    // FFI constructor, so reclaiming the box frees it exactly once.
    let fence = unsafe { Box::from_raw(fence) };
    let completion = ForeignGpuCaptureCompletion {
        context: context as usize,
        callback,
        drop,
    };
    fence
        .completion_driver
        .on_complete(fence.submission, move || completion.complete());
}

/// Clean up GPU resources.
///
/// This function should be called when the `GpuSurface` view is destroyed.
///
/// # Safety
///
/// `state` must be a valid pointer from `waterui_gpu_surface_create`,
/// and must not be used after this call.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_drop(state: *mut WuiGpuSurfaceState) {
    // SAFETY: the caller contract makes `state` an owning handle from the matching
    // constructor that has not been dropped; clearing the waker before it falls out of
    // scope releases the backend's context first.
    unsafe {
        let state = Box::from_raw(state);
        state.redraw_handle.set_waker(None);
    }
}

/// FFI-safe pointer state for passing from native.
///
/// Native backends should update this before each render call to provide
/// current pointer/cursor information to the GPU renderer.
#[repr(C)]
#[derive(Debug)]
pub struct WuiPointerState {
    /// Whether the pointer is currently over this surface.
    pub has_position: bool,
    /// X coordinate in surface-local pixels.
    pub x: f32,
    /// Y coordinate in surface-local pixels.
    pub y: f32,
    /// Whether there's an active hit (press/touch in progress).
    pub has_hit: bool,
    /// X coordinate where hit started.
    pub hit_x: f32,
    /// Y coordinate where hit started.
    pub hit_y: f32,
}

#[inline]
const fn pointer_state_from_ffi(pointer: &WuiPointerState) -> PointerState {
    PointerState {
        position: if pointer.has_position {
            Some(waterui_core::layout::Point::new(pointer.x, pointer.y))
        } else {
            None
        },
        hit: if pointer.has_hit {
            Some(waterui_core::layout::Point::new(
                pointer.hit_x,
                pointer.hit_y,
            ))
        } else {
            None
        },
    }
}

/// FFI-safe gesture state for zoom/pan interactions.
///
/// Native backends should update this when pinch, pan, or double-tap
/// gestures are detected to enable interactive chart zoom/pan.
#[repr(C)]
#[derive(Debug)]
pub struct WuiGestureState {
    /// Whether a gesture is currently active.
    pub active: bool,
    /// Cumulative pinch scale factor (1.0 = no scaling).
    pub pinch_scale: f32,
    /// Whether a pinch center is present.
    pub has_pinch_center: bool,
    /// X coordinate of pinch center in surface-local pixels.
    pub pinch_center_x: f32,
    /// Y coordinate of pinch center in surface-local pixels.
    pub pinch_center_y: f32,
    /// Pan offset X in pixels since gesture began.
    pub pan_offset_x: f32,
    /// Pan offset Y in pixels since gesture began.
    pub pan_offset_y: f32,
    /// Whether a double-tap was detected this frame.
    pub double_tap: bool,
}

#[inline]
const fn gesture_state_from_ffi(gesture: &WuiGestureState) -> GestureState {
    GestureState {
        pinch_scale: gesture.pinch_scale,
        pinch_center: if gesture.has_pinch_center {
            Some(waterui_core::layout::Point::new(
                gesture.pinch_center_x,
                gesture.pinch_center_y,
            ))
        } else {
            None
        },
        pan_offset: waterui_core::layout::Point::new(gesture.pan_offset_x, gesture.pan_offset_y),
        double_tap: gesture.double_tap,
        active: gesture.active,
    }
}

/// FFI-safe combined input state for a `GpuSurface`.
///
/// This keeps the native bridge minimal by forwarding pointer and gesture
/// snapshots in one call.
#[repr(C)]
#[derive(Debug)]
pub struct WuiGpuSurfaceInput {
    /// Current pointer snapshot.
    pub pointer: WuiPointerState,
    /// Current gesture snapshot.
    pub gesture: WuiGestureState,
}

/// Update both pointer and gesture state for a `GpuSurface`.
///
/// Native backends should prefer this API to minimize bridge calls.
///
/// # Arguments
///
/// * `state` - Pointer to the persistent state from `waterui_gpu_surface_create`
/// * `input` - Combined pointer + gesture snapshot
///
/// # Safety
///
/// `state` must be a valid pointer from `waterui_gpu_surface_create`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn waterui_gpu_surface_set_input(
    state: *mut WuiGpuSurfaceState,
    input: WuiGpuSurfaceInput,
) {
    // SAFETY: the caller contract requires `state` to be a valid handle, alive and
    // not otherwise borrowed for this call; the exclusive borrow ends here.
    let state = unsafe { crate::borrow_ffi_mut(state) };
    state.pointer_state = pointer_state_from_ffi(&input.pointer);
    state.gesture_state = gesture_state_from_ffi(&input.gesture);
}

/// Create a wgpu Surface from a platform-specific layer pointer.
///
/// Apple has no arm here on purpose: nothing on those platforms presents
/// through a swapchain any more. A `CAMetalLayer`'s drawable is readable only
/// by the pipeline that presented it, so every Apple host now renders into a
/// host-owned `IOSurface` texture instead (#519, #579).
#[cfg(target_os = "android")]
pub(crate) fn create_surface_from_layer(
    instance: &wgpu::Instance,
    layer: *mut c_void,
) -> wgpu::Surface<'static> {
    use raw_window_handle::{AndroidNdkWindowHandle, RawWindowHandle};
    use std::ptr::NonNull;

    // On Android, layer is an ANativeWindow*
    let window_ptr = NonNull::new(layer).expect("ANativeWindow pointer must be non-null");
    let handle = AndroidNdkWindowHandle::new(window_ptr);

    // SAFETY: `create_surface_unsafe` requires the raw handle to stay valid for as
    // long as the returned surface. `layer` is the `ANativeWindow*` the Android
    // backend holds for this surface and releases only after dropping it.
    unsafe {
        instance
            .create_surface_unsafe(wgpu::SurfaceTargetUnsafe::RawHandle {
                raw_display_handle: Some(raw_window_handle::RawDisplayHandle::Android(
                    raw_window_handle::AndroidDisplayHandle::new(),
                )),
                raw_window_handle: RawWindowHandle::AndroidNdk(handle),
            })
            .expect("failed to create wgpu surface from ANativeWindow")
    }
}

#[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "android")))]
pub(crate) fn create_surface_from_layer(
    _instance: &wgpu::Instance,
    _layer: *mut c_void,
) -> wgpu::Surface<'static> {
    panic!("native GpuSurface presentation is unsupported on this platform")
}

#[cfg(all(test, not(any(target_os = "macos", target_os = "ios"))))]
mod tests {
    use super::*;

    fn surface_capabilities() -> wgpu::SurfaceCapabilities {
        wgpu::SurfaceCapabilities {
            formats: vec![
                wgpu::TextureFormat::Bgra8UnormSrgb,
                wgpu::TextureFormat::Rgba16Float,
            ],
            ..wgpu::SurfaceCapabilities::default()
        }
    }

    #[test]
    fn first_surface_uses_dynamic_range_preference() {
        let capabilities = surface_capabilities();
        assert_eq!(
            attached_surface_format(&capabilities, None, false),
            wgpu::TextureFormat::Bgra8UnormSrgb
        );
        assert_eq!(
            attached_surface_format(&capabilities, None, true),
            wgpu::TextureFormat::Rgba16Float
        );
    }

    #[test]
    fn replacement_surface_reuses_established_renderer_format() {
        let capabilities = surface_capabilities();
        assert_eq!(
            attached_surface_format(&capabilities, Some(wgpu::TextureFormat::Rgba16Float), false,),
            wgpu::TextureFormat::Rgba16Float
        );
    }

    #[test]
    #[should_panic(
        expected = "replacement surface does not support the renderer's established format"
    )]
    fn replacement_surface_rejects_unsupported_renderer_format() {
        let capabilities = wgpu::SurfaceCapabilities {
            formats: vec![wgpu::TextureFormat::Bgra8UnormSrgb],
            ..wgpu::SurfaceCapabilities::default()
        };
        let _ =
            attached_surface_format(&capabilities, Some(wgpu::TextureFormat::Rgba16Float), true);
    }
}