ltk_webkit/wpe/

mod.rs

// SPDX-License-Identifier: LGPL-2.1-only
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>

//! The WPE WebKit engine: a `WebKitWebView` on the headless WPEPlatform display, its DMA-BUF frames imported as EGLImages into ltk's GLES context.

mod autoplay;
mod browsing;
mod clipboard;
mod content_filter;
mod context;
mod context_menu;
mod downloads;
mod favicon;
mod features;
mod file_chooser;
mod fullscreen;
mod hover;
mod input_method;
mod main_loop;
mod media_codecs;
mod modifiers;
mod navigation;
mod policy;
mod popups;
mod print;
mod privacy;
mod scripting;
mod session;
mod snapshot;
mod software;
mod termination;

pub use autoplay::set_autoplay;
pub use content_filter::{ remove_content_filters, set_content_filter };
pub use context::{ set_cache_model, set_memory_limit };
pub use downloads::{ cancel_download, poll_downloads, set_download_dir };
pub use features::set_feature;
pub use file_chooser::FileRequest;
pub use main_loop::wake_on_events;
pub use media_codecs::{ hardware_video_decoders, set_blocked_video_codecs };
pub use modifiers::set_modifiers;
pub use privacy::{ set_preferred_languages, set_third_party_cookies, set_tracking_prevention };
pub use session::{ prefetch_dns, set_data_directories };

use std::cell::RefCell;
use std::ffi::{ c_char, c_int, c_uint, c_void, CStr };
use std::ptr;
use std::sync::{ Arc, LazyLock, Mutex, Once };
use std::time::Instant;

use glib_sys::*;
use gobject_sys::*;
use wpe_platform_sys::*;
use wpe_platform_headless_sys::{ wpe_display_headless_new, wpe_view_headless_get_type };
use wpe_webkit_sys::*;

use glow::HasContext;

use ltk::{ CursorShape, External, ExternalSource };
use ltk::types::Rect;
use ltk::Element;

use crate::types::{ LoadEvent, PageTarget, Termination };

// ─── Extension entry points ──────────────────────────────────────────────────

type GlEglImageTargetTexture2DOes = unsafe extern "system" fn( target: u32, image: *const c_void );
type EglCreateImageKHR  = unsafe extern "system" fn(
	dpy:        *mut c_void,
	ctx:        *mut c_void,
	target:     u32,
	buffer:     *mut c_void,
	attrib_list: *const c_int,
) -> *mut c_void;
type EglDestroyImageKHR = unsafe extern "system" fn( dpy: *mut c_void, image: *mut c_void ) -> u32;
type EglGetCurrentDisplay = unsafe extern "system" fn() -> *mut c_void;

const GL_TEXTURE_2D: u32 = 0x0DE1;

// EGL_KHR_image_base + EGL_EXT_image_dma_buf_import constants we need.
const EGL_NONE:                            c_int = 0x3038;
const EGL_WIDTH:                           c_int = 0x3057;
const EGL_HEIGHT:                          c_int = 0x3056;
const EGL_LINUX_DMA_BUF_EXT:               u32   = 0x3270;
const EGL_LINUX_DRM_FOURCC_EXT:            c_int = 0x3271;
const EGL_DMA_BUF_PLANE0_FD_EXT:           c_int = 0x3272;
const EGL_DMA_BUF_PLANE0_OFFSET_EXT:       c_int = 0x3273;
const EGL_DMA_BUF_PLANE0_PITCH_EXT:        c_int = 0x3274;
const EGL_DMA_BUF_PLANE1_FD_EXT:           c_int = 0x3275;
const EGL_DMA_BUF_PLANE1_OFFSET_EXT:       c_int = 0x3276;
const EGL_DMA_BUF_PLANE1_PITCH_EXT:        c_int = 0x3277;
const EGL_DMA_BUF_PLANE2_FD_EXT:           c_int = 0x3278;
const EGL_DMA_BUF_PLANE2_OFFSET_EXT:       c_int = 0x3279;
const EGL_DMA_BUF_PLANE2_PITCH_EXT:        c_int = 0x327A;
const EGL_DMA_BUF_PLANE3_FD_EXT:           c_int = 0x3440;
const EGL_DMA_BUF_PLANE3_OFFSET_EXT:       c_int = 0x3441;
const EGL_DMA_BUF_PLANE3_PITCH_EXT:        c_int = 0x3442;
const EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT:  c_int = 0x3443;
const EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT:  c_int = 0x3444;
const EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT:  c_int = 0x3445;
const EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT:  c_int = 0x3446;
const EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT:  c_int = 0x3447;
const EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT:  c_int = 0x3448;
const EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT:  c_int = 0x3449;
const EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT:  c_int = 0x344A;

const PLANE_FD: [ c_int; 4 ]  = [ EGL_DMA_BUF_PLANE0_FD_EXT, EGL_DMA_BUF_PLANE1_FD_EXT, EGL_DMA_BUF_PLANE2_FD_EXT, EGL_DMA_BUF_PLANE3_FD_EXT ];
const PLANE_OFF: [ c_int; 4 ] = [ EGL_DMA_BUF_PLANE0_OFFSET_EXT, EGL_DMA_BUF_PLANE1_OFFSET_EXT, EGL_DMA_BUF_PLANE2_OFFSET_EXT, EGL_DMA_BUF_PLANE3_OFFSET_EXT ];
const PLANE_PITCH: [ c_int; 4 ] = [ EGL_DMA_BUF_PLANE0_PITCH_EXT, EGL_DMA_BUF_PLANE1_PITCH_EXT, EGL_DMA_BUF_PLANE2_PITCH_EXT, EGL_DMA_BUF_PLANE3_PITCH_EXT ];
const PLANE_MOD_LO: [ c_int; 4 ] = [ EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT, EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT, EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT, EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT ];
const PLANE_MOD_HI: [ c_int; 4 ] = [ EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT, EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT, EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT, EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT ];

/// Shared mutable state between the WPE callback thread (the main
/// thread, where the GMainLoop runs) and the LTK draw closure (also
/// the main thread).
struct Inner
{
	display:          *mut WPEDisplay,
	webview:          *mut WebKitWebView,
	view:             *mut WPEView,

	/// Current logical size of the embedded view, in widget pixels.
	/// Mutated by [`WebView::resize`] to keep the WPEView buffer
	/// dimensions in sync with the host widget rect.
	width:            f32,
	height:           f32,

	/// Last laid-out widget rect captured from the External widget's
	/// draw closure. Used to translate host pointer coordinates into
	/// view-local coordinates and to drive auto-resize when the host
	/// gives us a rect of a different size from the WebKit view.
	last_rect:        Rect,

	/// Device scale factor: physical widget pixels per WPE logical pixel.
	scale:            f64,

	/// Latest WPEBuffer produced by WPE, ref'd by us (we unref the
	/// previous one). `None` until the first `render_buffer` arrives.
	pending_buffer:   Option<*mut WPEBuffer>,

	/// Buffer that produced the currently bound EGLImage. Held to
	/// keep the underlying DMA-BUF fds alive while LTK samples.
	bound_buffer:     Option<*mut WPEBuffer>,

	/// EGLImage currently bound to `gl_texture`. Lives in LTK's
	/// EGLDisplay (we re-import the DMA-BUF on each new buffer); must
	/// be destroyed with `eglDestroyImageKHR` before being replaced.
	bound_image:      Option<*mut c_void>,

	/// GL texture allocated lazily on the first draw. Reused across
	/// frames; its target is retargeted at each new EGLImage.
	gl_texture:       Option<glow::Texture>,

	/// Whether frames are copied into `gl_texture` instead of imported as
	/// EGLImages. Decided on the first draw.
	copy_path:        Option<bool>,

	/// Size of the texture storage allocated by the copy path; `(0, 0)`
	/// until the first frame has been uploaded.
	copy_size:        ( i32, i32 ),

	/// Cached extension entry points.
	bind_image_fn:    Option<GlEglImageTargetTexture2DOes>,
	egl_create_fn:    Option<EglCreateImageKHR>,
	egl_destroy_fn:   Option<EglDestroyImageKHR>,
	egl_get_current_display_fn: Option<EglGetCurrentDisplay>,

	/// Cursor shape reported by WebKit's `mouse-target-changed`. Read
	/// by [`WebView::cursor_shape`] and surfaced through the host's
	/// [`ltk::App::cursor_override`].
	cursor_shape:     CursorShape,

	/// Set to `true` whenever WebKit hands us a new buffer; consumed
	/// by [`WebView::take_redraw_request`] so the host can return
	/// `InvalidationScope::All` only for the ticks that actually have
	/// new pixels to show.
	needs_redraw:     bool,

	/// `true` while the left mouse button is held — flipped by
	/// [`WebView::pointer_press`] / [`WebView::pointer_release`] and
	/// read by [`WebView::pointer_move`] to OR
	/// `WPE_MODIFIER_POINTER_BUTTON1` into the move event's
	/// modifiers, which is what WebKit looks at to distinguish a
	/// drag (text-select / slider drag) from a hover.
	button1_held:     bool,

	/// URIs of cancelled new-window navigations, drained by
	/// [`WebView::take_new_window_requests`].
	new_window_requests: Vec<String>,

	/// Views opened by `window.open()`, drained by [`WebView::take_created_views`].
	created_views:    Vec<WebView>,

	/// The page called `window.close()`; read by [`WebView::take_close_request`].
	close_requested:  bool,

	/// Read by [`WebView::take_file_request`].
	file_request:     Option<file_chooser::FileRequest>,

	/// The display clipboard's change count last reported or written by the host, see [`WebView::take_copied_text`].
	clipboard_seen:   i64,

	/// Read by [`WebView::take_fullscreen_request`].
	fullscreen_request: Option<bool>,

	/// While set, the view keeps the size it is printed at and new frames are not shown.
	print_job:        Option<print::Job>,

	/// Read by [`WebView::take_print_request`].
	print_requested:  bool,

	/// Read by [`WebView::take_termination`].
	termination:      Option<Termination>,

	/// Read by [`WebView::take_page_target`].
	page_target:      Option<PageTarget>,

	/// Read by [`WebView::hovered_link`].
	hovered_link:     Option<String>,

	favicon:          Option<ltk::ImageData>,

	/// Owned by `webview`; null when it could not be created.
	im_context:       *mut WebKitInputMethodContext,

	/// An editable element of the page holds the focus.
	editable_focused: bool,

	/// Consulted by `decide-policy`; see [`WebView::set_navigation_handler`].
	navigation_handler: Option<navigation::NavigationHandler>,

	/// The host started a load whose navigation has not been decided yet.
	host_load_pending: bool,

	/// Read by [`WebView::take_load_events`].
	load_events:      Vec<LoadEvent>,

	/// Held for the lifetime of `Inner` so EGL stays loaded.
	#[ allow( dead_code ) ]
	egl_instance:     khronos_egl::DynamicInstance<khronos_egl::EGL1_4>,
}

// SAFETY: the FFI pointers above are only ever touched from the main
// thread (see the module-level threading note). The `Send + Sync`
// bounds are required by [`ltk::widget::external::ExternalSource`] but
// we never actually move `Inner` between threads.
unsafe impl Send for Inner {}
unsafe impl Sync for Inner {}

/// A WebKit-rendered view that can be embedded into an LTK widget tree
/// via [`WebView::element`].
pub struct WebView
{
	inner: Arc<Mutex<Inner>>,
}

impl WebView
{
	/// Create a new WebView, connect it to the user's Wayland session,
	/// and start loading `url`. The view does not render until [`tick`]
	/// is pumped from the host application's event loop. An empty `url`
	/// loads nothing, for a view about to receive
	/// [`restore_session_state`](WebView::restore_session_state).
	///
	/// [`tick`]: WebView::tick
	pub fn new( width: f32, height: f32, url: &str ) -> Result<Self, String>
	{
		let this = Self::build( width, height, None )?;
		if !url.is_empty()
		{
			let url_c = std::ffi::CString::new( url ).map_err( |e| format!( "url contains NUL: {}", e ) )?;
			unsafe
			{
				let webview = this.inner.lock().unwrap().webview;
				webkit_web_view_load_uri( webview, url_c.as_ptr() );
			}
		}
		Ok( this )
	}

	/// A view that loads nothing; with `opener`, related to it, as WebKit's `create` signal requires.
	pub( crate ) fn build( width: f32, height: f32, opener: Option<popups::Opener> ) -> Result<Self, String>
	{
		// SAFETY: every call below crosses an FFI boundary into
		// libwpewebkit / libglib. We check for null returns and propagate
		// GError contents through `Result`. None of the pointers we
		// produce escape the constructor before being moved into `Inner`,
		// which then keeps them alive until `Drop`.
		let inner = unsafe
		{
			// Headless backend: WPE renders straight into DMA-BUF
			// buffers without creating its own Wayland toplevel, so the
			// page only appears wherever LTK composites the texture.
			let display = match &opener
			{
				Some( o ) => g_object_ref( o.display as *mut GObject ) as *mut WPEDisplay,
				None      => wpe_display_headless_new(),
			};
			if display.is_null()
			{
				return Err( "wpe_display_headless_new returned NULL".into() );
			}

			let mut err: *mut GError = ptr::null_mut();
			if opener.is_none() && wpe_display_connect( display, &mut err ) == 0
			{
				let msg = error_message_or_default( err, "unknown" );
				if !err.is_null() { g_error_free( err ); }
				g_object_unref( display as *mut _ );
				return Err( format!( "wpe_display_connect: {}", msg ) );
			}

			let display_prop: *const c_char = b"display\0".as_ptr() as _;
			let related_prop: *const c_char = b"related-view\0".as_ptr() as _;
			let context_prop: *const c_char = b"web-context\0".as_ptr() as _;
			let session_prop: *const c_char = b"network-session\0".as_ptr() as _;
			let content_prop: *const c_char = b"user-content-manager\0".as_ptr() as _;
			let policy_prop:  *const c_char = b"website-policies\0".as_ptr() as _;
			let null_terminator: *const c_char = ptr::null();
			let policies = autoplay::website_policies();
			let webview = match &opener
			{
				Some( o ) => g_object_new(
					webkit_web_view_get_type(),
					display_prop,
					display,
					related_prop,
					o.webview,
					content_prop,
					content_filter::user_content_manager(),
					policy_prop,
					policies,
					null_terminator,
				),
				None => g_object_new(
					webkit_web_view_get_type(),
					display_prop,
					display,
					context_prop,
					context::web_context(),
					session_prop,
					session::network_session(),
					content_prop,
					content_filter::user_content_manager(),
					policy_prop,
					policies,
					null_terminator,
				),
			} as *mut WebKitWebView;
			if !policies.is_null() { g_object_unref( policies as *mut _ ); }
			if webview.is_null()
			{
				g_object_unref( display as *mut _ );
				return Err( "g_object_new(WebKitWebView) returned NULL".into() );
			}
			// Its first request leaves before the host sees the view.
			if let Some( o ) = &opener { browsing::copy_user_agent( o.webview, webview ); }
			scripting::console_to_stdout_if_asked( webview );
			features::apply( webview );

			let view = webkit_web_view_get_wpe_view( webview );
			if view.is_null()
			{
				g_object_unref( webview as *mut _ );
				g_object_unref( display as *mut _ );
				return Err( "webkit_web_view_get_wpe_view returned NULL".into() );
			}

			let egl_instance = khronos_egl::DynamicInstance::<khronos_egl::EGL1_4>::load_required()
				.map_err( |e| format!( "EGL load: {}", e ) )?;

			Inner
			{
				display,
				webview,
				view,
				width,
				height,
				last_rect:      Rect { x: 0.0, y: 0.0, width, height },
				scale:          1.0,
				pending_buffer: None,
				bound_buffer:   None,
				bound_image:    None,
				gl_texture:     None,
				copy_path:      None,
				copy_size:      ( 0, 0 ),
				bind_image_fn:  None,
				egl_create_fn:  None,
				egl_destroy_fn: None,
				egl_get_current_display_fn: None,
				cursor_shape:   CursorShape::Default,
				// First frame must redraw so the page appears as soon
				// as WebKit produces it.
				needs_redraw:   true,
				button1_held:   false,
				new_window_requests: Vec::new(),
				created_views:  Vec::new(),
				close_requested: false,
				file_request:   None,
				clipboard_seen: 0,
				fullscreen_request: None,
				print_job:      None,
				print_requested: false,
				termination:    None,
				page_target:    None,
				hovered_link:   None,
				favicon:        None,
				im_context:     ptr::null_mut(),
				editable_focused: false,
				navigation_handler: None,
				host_load_pending: false,
				load_events:    Vec::new(),
				egl_instance,
			}
		};

		let inner = Arc::new( Mutex::new( inner ) );

		// Frame delivery happens through the `render_buffer` class vfunc
		// override installed below — WebKit calls it for every produced
		// frame. (The `buffers-changed` signal only reports buffer-pool
		// changes, which is why it fires on resize but not on damage.)

		// Tell WPE the view has keyboard/pointer focus so WebKit
		// processes input events instead of dropping them, and resize
		// it to match the host widget so click coordinates map 1:1.
		// SAFETY: `view` is alive for the lifetime of `inner`.
		unsafe
		{
			let view = inner.lock().unwrap().view;
			// Without map + visible WebKit treats the page as hidden and
			// freezes it outright: no compositor frames beyond the first,
			// rAF and DOM timers stopped — only forced relayouts paint.
			wpe_view_map( view );
			wpe_view_set_visible( view, 1 );
			wpe_view_focus_in( view );
			let top = wpe_view_get_toplevel( view );
			if !top.is_null()
			{
				wpe_toplevel_resize( top, width as i32, height as i32 );
			}

			// Install the global vfunc override so set_cursor_from_name
			// reaches our handler, then attach a per-view back-pointer
			// to the Inner so the override knows which WebView to
			// notify.
			install_view_overrides();
			let qdata_box = Box::into_raw( Box::new( Arc::downgrade( &inner ) ) ) as gpointer;
			g_object_set_data_full(
				view as *mut GObject,
				CURSOR_INNER_QDATA_KEY.as_ptr() as *const c_char,
				qdata_box,
				Some( drop_weak_qdata ),
			);

			let webview = inner.lock().unwrap().webview;
			policy::connect( webview, Arc::downgrade( &inner ) );
			navigation::connect( webview, Arc::downgrade( &inner ) );
			popups::connect( webview, Arc::downgrade( &inner ) );
			file_chooser::connect( webview, Arc::downgrade( &inner ) );
			print::connect( webview, Arc::downgrade( &inner ) );
			termination::connect( webview, Arc::downgrade( &inner ) );
			fullscreen::connect( webview, Arc::downgrade( &inner ) );
			context_menu::connect( webview, Arc::downgrade( &inner ) );
			hover::connect( webview, Arc::downgrade( &inner ) );
			let im_context = input_method::install( webview, Arc::downgrade( &inner ) );
			inner.lock().unwrap().im_context = im_context;
			downloads::track( webview );
		}

		Ok( Self { inner } )
	}

	/// Resize the embedded view. Updates both the reserved space the
	/// LTK [`External`] widget claims and the WPEView buffer
	/// dimensions, so click coordinates keep mapping 1:1 and WebKit
	/// re-renders to the new size.
	pub fn resize( &self, width: f32, height: f32 )
	{
		let ( view, ( lw, lh ) ) = match self.inner.lock()
		{
			Ok( mut g )  =>
			{
				g.width  = width;
				g.height = height;
				if g.print_job.is_some() { return; }
				( g.view, g.logical_size() )
			}
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		// SAFETY: view is alive for the lifetime of `inner`. The
		// public path to resize a view is via its toplevel — calling
		// `wpe_view_resized` directly is reserved for backend-derived
		// classes and silently accepts the new size without
		// re-laying-out WebKit.
		unsafe
		{
			let top = wpe_view_get_toplevel( view );
			if top.is_null() { return; }
			wpe_toplevel_resize( top, lw, lh );
		}
	}

	/// Drive WPE's GMainLoop forward by one non-blocking iteration. Call
	/// this from the host application's per-frame poll (LTK's
	/// `App::poll_external` is the obvious place), or when
	/// [`wake_on_events`] wakes it, whose watch it re-arms.
	pub fn tick( &self )
	{
		// SAFETY: `g_main_context_iteration` on the default context with
		// `may_block = FALSE` is safe to call any number of times from
		// the thread that owns the main context (us, by the threading
		// contract).
		unsafe
		{
			while g_main_context_iteration( ptr::null_mut(), 0 ) != 0
			{
				// drain pending events
			}
		}
		main_loop::rearm();
	}

	/// Forward a left-button press to the embedded view at WPEView
	/// pixel coordinates `(x, y)`. Pair with [`Self::pointer_release`]
	/// for a click; intermediate [`Self::pointer_move`] calls between
	/// the two construct a drag (which WebKit interprets as text
	/// selection over selectable content).
	pub fn pointer_press( &self, x: f64, y: f64 )
	{
		self.send_button( WPE_EVENT_POINTER_DOWN, WPE_BUTTON_PRIMARY, x, y );
	}

	/// Forward a left-button release to the embedded view.
	pub fn pointer_release( &self, x: f64, y: f64 )
	{
		self.send_button( WPE_EVENT_POINTER_UP, WPE_BUTTON_PRIMARY, x, y );
	}

	/// Convenience: synthesise a complete press + release click at
	/// `(x, y)`. Useful for tests / scripted interactions; real user
	/// clicks should go through [`Self::pointer_press`] /
	/// [`Self::pointer_release`] so drags work.
	pub fn click_at( &self, x: f64, y: f64 )
	{
		self.pointer_press( x, y );
		self.pointer_release( x, y );
	}

	/// Forward a touchscreen finger-down to the embedded view. The
	/// touch stream (`touch_down` / `touch_move` / `touch_up` per
	/// finger id) feeds WebKit's own gesture recognition: tap becomes
	/// click, drag becomes kinetic scroll, two fingers pinch-zoom —
	/// none of which the mouse-event path can express.
	pub fn touch_down( &self, id: u32, x: f64, y: f64 )
	{
		self.send_touch( WPE_EVENT_TOUCH_DOWN, id, x, y );
	}

	/// See [`Self::touch_down`].
	pub fn touch_move( &self, id: u32, x: f64, y: f64 )
	{
		self.send_touch( WPE_EVENT_TOUCH_MOVE, id, x, y );
	}

	/// See [`Self::touch_down`].
	pub fn touch_up( &self, id: u32, x: f64, y: f64 )
	{
		self.send_touch( WPE_EVENT_TOUCH_UP, id, x, y );
	}

	/// End a finger's sequence without a release: the page gets no tap out of it.
	pub fn touch_cancel( &self, id: u32, x: f64, y: f64 )
	{
		self.send_touch( WPE_EVENT_TOUCH_CANCEL, id, x, y );
	}

	fn send_touch( &self, ev_type: WPEEventType, id: u32, x: f64, y: f64 )
	{
		let ( view, x, y ) = match self.inner.lock()
		{
			Ok( g )  =>
			{
				let ( lx, ly ) = g.to_view( x, y );
				( g.view, lx, ly )
			}
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		// SAFETY: see `send_button` — same lifetime / refcount reasoning.
		unsafe
		{
			let ev = wpe_event_touch_new(
				ev_type,
				view,
				WPE_INPUT_SOURCE_TOUCHSCREEN,
				elapsed_ms(),
				0,
				id,
				x, y,
			);
			if !ev.is_null() { wpe_view_event( view, ev ); wpe_event_unref( ev ); }
		}
	}

	pub( crate ) fn send_button( &self, ev_type: WPEEventType, button: c_int, x: f64, y: f64 )
	{
		let ( view, x, y ) = match self.inner.lock()
		{
			Ok( mut g )  =>
			{
				// Track left-button state so subsequent `pointer_move`s
				// can stamp the BUTTON1 modifier on the way out and
				// WebKit recognises the move as part of a drag.
				if button == WPE_BUTTON_PRIMARY
				{
					if ev_type == WPE_EVENT_POINTER_DOWN
					{
						g.button1_held = true;
					} else if ev_type == WPE_EVENT_POINTER_UP {
						g.button1_held = false;
					}
				}
				let ( lx, ly ) = g.to_view( x, y );
				( g.view, lx, ly )
			}
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		let time = elapsed_ms();
		// `press_count` carries 1/2/3 for single/double/triple click on
		// DOWN events; WPE asserts it is 0 for everything else. The
		// view exposes a helper that walks its history of recent
		// presses (position + time + button match) and returns the
		// right count automatically.
		let press_count = if ev_type == WPE_EVENT_POINTER_DOWN
		{
			// SAFETY: view is alive; the helper only reads the view's
			// own gesture state.
			unsafe { wpe_view_compute_press_count( view, x, y, button as c_uint, time ) }
		} else {
			0
		};
		// SAFETY: view is alive for the lifetime of `self` (held by
		// Inner). The button-event ctor returns a refcounted WPEEvent
		// which `wpe_view_event` keeps a ref on; we drop our caller-
		// side ref with `wpe_event_unref` after dispatch.
		unsafe
		{
			let ev = wpe_event_pointer_button_new(
				ev_type,
				view,
				WPE_INPUT_SOURCE_MOUSE,
				time,
				modifiers::held(),
				button as c_uint,
				x, y,
				press_count,
			);
			if !ev.is_null() { wpe_view_event( view, ev ); wpe_event_unref( ev ); }
		}
	}

	/// Forward a wheel / touchpad scroll event to the embedded view.
	/// `x`, `y` are in WPEView pixel coordinates (same as the host
	/// pointer), `dx`/`dy` are scroll deltas in pixels (positive =
	/// down/right, matching WPE convention).
	pub fn scroll( &self, x: f64, y: f64, dx: f64, dy: f64 )
	{
		let ( view, x, y ) = match self.inner.lock()
		{
			Ok( g )  =>
			{
				let ( lx, ly ) = g.to_view( x, y );
				( g.view, lx, ly )
			}
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		// SAFETY: see `click_at` — same lifetime / refcount reasoning.
		unsafe
		{
			let ev = wpe_event_scroll_new(
				view,
				WPE_INPUT_SOURCE_MOUSE,
				0, modifiers::held(),
				dx, dy,
				1,    // precise_deltas
				0,    // is_stop
				x, y,
			);
			if !ev.is_null() { wpe_view_event( view, ev ); wpe_event_unref( ev ); }
		}
	}

	/// Forward a pointer-move event to the embedded view at WPEView
	/// pixel coordinates `(x, y)`. WebKit needs this to update hover
	/// state, fire `mouseenter` / `mouseleave`, and decide which
	/// cursor it wants — without it the cursor query through
	/// [`Self::cursor_shape`] stays at `Default`.
	pub fn pointer_move( &self, x: f64, y: f64 )
	{
		let ( view, x, y, mods ) = match self.inner.lock()
		{
			Ok( g )  =>
			{
				let ( lx, ly ) = g.to_view( x, y );
				let mods = modifiers::held() | if g.button1_held { WPE_MODIFIER_POINTER_BUTTON1 } else { 0 };
				( g.view, lx, ly, mods )
			}
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		// SAFETY: same reasoning as `click_at` — view is alive for the
		// lifetime of `self`; the move-event ctor gives us a refcounted
		// WPEEvent and we balance the ref after dispatch.
		unsafe
		{
			let ev = wpe_event_pointer_move_new(
				WPE_EVENT_POINTER_MOVE,
				view,
				WPE_INPUT_SOURCE_MOUSE,
				elapsed_ms(),
				mods,
				x, y,
				0.0, 0.0,
			);
			if !ev.is_null() { wpe_view_event( view, ev ); wpe_event_unref( ev ); }
		}
	}

	/// Forward a keyboard event to the embedded view. `keysym` is the
	/// xkbcommon keysym (the symbol the user effectively pressed,
	/// after xkb layout translation); `keycode` is the raw hardware
	/// scancode the compositor delivered. `pressed` selects DOWN vs
	/// UP; `ctrl` and `shift` populate the `WPEModifiers` bitfield.
	pub fn send_key( &self, keysym: u32, keycode: u32, pressed: bool, ctrl: bool, shift: bool )
	{
		let view = match self.inner.lock()
		{
			Ok( g )  => g.view,
			Err( _ ) => return,
		};
		if view.is_null() { return; }
		let mut mods: WPEModifiers = 0;
		if ctrl  { mods |= WPE_MODIFIER_KEYBOARD_CONTROL; }
		if shift { mods |= WPE_MODIFIER_KEYBOARD_SHIFT;   }
		let ev_type = if pressed { WPE_EVENT_KEYBOARD_KEY_DOWN } else { WPE_EVENT_KEYBOARD_KEY_UP };
		// SAFETY: same lifetime / refcount reasoning as the other
		// event helpers; view stays alive for the lifetime of `self`.
		unsafe
		{
			let ev = wpe_event_keyboard_new(
				ev_type,
				view,
				WPE_INPUT_SOURCE_KEYBOARD,
				0, mods,
				keycode,
				keysym,
			);
			if !ev.is_null() { wpe_view_event( view, ev ); wpe_event_unref( ev ); }
		}
	}

	/// Returns `true` once for every new buffer WebKit has produced
	/// since the previous call. The host's `invalidate_after` should
	/// return `InvalidationScope::All` whenever this is `true` so LTK
	/// redraws and the new frame becomes visible — keeping the
	/// surface from getting stuck on a stale (sometimes black) frame
	/// when the compositor's frame-callback chain pauses during a
	/// resize. Idle ticks return `false`, so static pages cost zero
	/// redraws.
	pub fn take_redraw_request( &self ) -> bool
	{
		let was = self.inner.lock()
			.map( | mut g |
			{
				let was = g.needs_redraw;
				g.needs_redraw = false;
				was
			} )
			.unwrap_or( false );
		if was { dbg_log( "redraw request consumed" ); }
		was
	}

	/// The cursor shape WebKit currently wants for the embedded view.
	/// Mirrors the most recent `mouse-target-changed` signal payload.
	/// The host application surfaces this through
	/// [`ltk::App::cursor_override`].
	pub fn cursor_shape( &self ) -> CursorShape
	{
		self.inner.lock().map( |g| g.cursor_shape ).unwrap_or( CursorShape::Default )
	}

	/// Build an LTK [`Element`] that composites this WebView's pixels
	/// into the parent widget tree. Uses the dimensions most recently
	/// passed to [`Self::resize`] (or the constructor) as the
	/// preferred size; the actual laid-out rect is captured by the
	/// draw closure on every frame and used to drive auto-resize +
	/// input coordinate translation.
	pub fn element<Msg: Clone + 'static>( &self ) -> Element<Msg>
	{
		let ( width, height ) = match self.inner.lock()
		{
			Ok( g )  => ( g.width, g.height ),
			Err( _ ) => ( 0.0, 0.0 ),
		};
		let inner = Arc::clone( &self.inner );
		External::new(
			width,
			height,
			ExternalSource::Frame( Arc::new( move | gl: &glow::Context, rect: Rect | -> Option<( glow::Texture, u32, u32 )>
			{
				dbg_log( &format!( "draw rect=({},{} {}x{})", rect.x, rect.y, rect.width, rect.height ) );
				let mut guard = inner.lock().ok()?;
				// Capture the laid-out rect for input translation, and
				// resize the WPEToplevel when the rect's size diverges
				// from the WebKit view's current size — keeps WebKit's
				// buffer matching the LTK rect so the imported texture
				// fills it 1:1 (no stretching → no click offsets).
				guard.last_rect = rect;
				let new_w = rect.width;
				let new_h = rect.height;
				if ( new_w - guard.width ).abs() > 0.5 || ( new_h - guard.height ).abs() > 0.5
				{
					guard.width  = new_w;
					guard.height = new_h;
					if !guard.view.is_null() && guard.print_job.is_none()
					{
						let view       = guard.view;
						let ( lw, lh ) = guard.logical_size();
						drop( guard );
						unsafe
						{
							let top = wpe_view_get_toplevel( view );
							if !top.is_null()
							{
								wpe_toplevel_resize( top, lw, lh );
							}
						}
						let mut guard = inner.lock().ok()?;
						return guard.frame( gl );
					}
				}
				guard.frame( gl )
			} ) ),
		).into()
	}
}

impl Inner
{
	/// Host surface coordinates (physical pixels) to view-local logical ones.
	fn to_view( &self, x: f64, y: f64 ) -> ( f64, f64 )
	{
		( ( x - self.last_rect.x as f64 ) / self.scale, ( y - self.last_rect.y as f64 ) / self.scale )
	}

	fn to_host( &self, x: f64, y: f64 ) -> ( f64, f64 )
	{
		( x * self.scale + self.last_rect.x as f64, y * self.scale + self.last_rect.y as f64 )
	}

	fn logical_size( &self ) -> ( i32, i32 )
	{
		( ( self.width as f64 / self.scale ) as i32, ( self.height as f64 / self.scale ) as i32 )
	}

	/// The latest frame and its size in pixels, which lags behind the rect while the window is resized.
	fn frame( &mut self, gl: &glow::Context ) -> Option<( glow::Texture, u32, u32 )>
	{
		let texture = self.refresh_texture( gl )?;
		let ( width, height ) = if self.copy_path == Some( true )
		{
			( self.copy_size.0 as u32, self.copy_size.1 as u32 )
		} else {
			let buffer = self.bound_buffer?;
			// SAFETY: the bound buffer holds our reference until a newer one replaces it.
			unsafe { ( wpe_buffer_get_width( buffer ) as u32, wpe_buffer_get_height( buffer ) as u32 ) }
		};
		// `logical_size` rounds down, so a frame made for the current rect may fall short of it by the scale.
		let fit = |size: u32, extent: f32| if ( extent - size as f32 ).abs() <= self.scale as f32 + 1.0 { extent.round() as u32 } else { size };
		Some( ( texture, fit( width, self.last_rect.width ), fit( height, self.last_rect.height ) ) )
	}

	/// Called from the LTK draw closure with LTK's GLES context current.
	/// Lazy-initialises the GL texture and the extension entry point on
	/// first call, then re-targets the texture at the latest EGLImage
	/// from WPE.
	fn refresh_texture( &mut self, gl: &glow::Context ) -> Option<glow::Texture>
	{
		// Lazy-load the four extension entry points.
		if self.bind_image_fn.is_none()
		{
			self.bind_image_fn      = self.load_proc::<GlEglImageTargetTexture2DOes>( "glEGLImageTargetTexture2DOES" );
			self.egl_create_fn      = self.load_proc::<EglCreateImageKHR>( "eglCreateImageKHR" );
			self.egl_destroy_fn     = self.load_proc::<EglDestroyImageKHR>( "eglDestroyImageKHR" );
			self.egl_get_current_display_fn = self.load_proc::<EglGetCurrentDisplay>( "eglGetCurrentDisplay" );
		}
		let bind        = self.bind_image_fn?;
		let egl_create  = self.egl_create_fn?;
		let egl_destroy = self.egl_destroy_fn?;
		let egl_dpy_fn  = self.egl_get_current_display_fn?;

		// SAFETY: LTK's GLES context is current at draw time, so
		// eglGetCurrentDisplay returns LTK's display.
		let ltk_egl_display = unsafe { egl_dpy_fn() };
		if ltk_egl_display.is_null()
		{
			static mut WARNED: bool = false;
			// SAFETY: single-threaded contract.
			unsafe { if !WARNED { eprintln!( "[ltk-webkit] eglGetCurrentDisplay returned NULL" ); WARNED = true; } };
			return None;
		}
		release_orphans( gl, ltk_egl_display, egl_destroy );

		if *self.copy_path.get_or_insert_with( || software::wanted( gl ) )
		{
			return self.copy_pending( gl );
		}

		// Promote a pending buffer into the bound slot, importing it as
		// an EGLImage in LTK's EGLDisplay. Atomic swap: only destroy
		// the previously-bound buffer/image once the new import has
		// succeeded — failing imports during a resize transient
		// (mid-flight buffers with unfamiliar format/modifier) would
		// otherwise leave the widget with nothing to draw and flash
		// to black until the next good buffer arrives.
		if let Some( pending ) = self.take_shown_buffer()
		{
			match unsafe { import_dmabuf_as_image( pending, ltk_egl_display, egl_create ) }
			{
				Ok( image ) =>
				{
					if let Some( old_image ) = self.bound_image.take()
					{
						// SAFETY: old image was created by us with
						// `egl_create` against the same display.
						unsafe { egl_destroy( ltk_egl_display, old_image ); }
					}
					if let Some( old_buf ) = self.bound_buffer.take()
					{
						// SAFETY: we held a ref via g_object_ref in
						// the signal handler; balance it now.
						// Releasing returns it to WebKit's pool.
						unsafe
						{
							if !self.view.is_null()
							{
								wpe_view_buffer_released( self.view, old_buf );
							}
							g_object_unref( old_buf as *mut _ );
						}
					}
					self.bound_buffer = Some( pending );
					self.bound_image  = Some( image );
					dbg_log( "buffer imported" );
				}
				Err( msg ) =>
				{
					eprintln!( "[ltk-webkit] DMA-BUF import failed: {}", msg );
					// Drop the failing buffer; keep the previous
					// bound pair so the widget keeps drawing the last
					// good frame instead of flashing to black.
					unsafe
					{
						if !self.view.is_null()
						{
							wpe_view_buffer_released( self.view, pending );
						}
						g_object_unref( pending as *mut _ );
					}
				}
			}
		}

		let image = self.bound_image?;

		// Lazy-allocate the GL texture.
		if self.gl_texture.is_none()
		{
			// SAFETY: GLES create_texture is a wrapper around
			// glGenTextures; safe with a current context.
			let tex = unsafe { gl.create_texture() }.ok()?;
			unsafe
			{
				gl.bind_texture( GL_TEXTURE_2D, Some( tex ) );
				gl.tex_parameter_i32( GL_TEXTURE_2D, glow::TEXTURE_MIN_FILTER, glow::LINEAR as i32 );
				gl.tex_parameter_i32( GL_TEXTURE_2D, glow::TEXTURE_MAG_FILTER, glow::LINEAR as i32 );
				gl.tex_parameter_i32( GL_TEXTURE_2D, glow::TEXTURE_WRAP_S,    glow::CLAMP_TO_EDGE as i32 );
				gl.tex_parameter_i32( GL_TEXTURE_2D, glow::TEXTURE_WRAP_T,    glow::CLAMP_TO_EDGE as i32 );
			}
			self.gl_texture = Some( tex );
		}
		let tex = self.gl_texture?;

		// SAFETY: bind the texture and retarget at the imported EGLImage.
		// Both pointers are valid by the lazy checks above.
		unsafe
		{
			gl.bind_texture( GL_TEXTURE_2D, Some( tex ) );
			bind( GL_TEXTURE_2D, image );
			let err = gl.get_error();
			if err != 0
			{
				static mut WARNED_BIND: bool = false;
				if !WARNED_BIND
				{
					eprintln!( "[ltk-webkit] glEGLImageTargetTexture2DOES error: 0x{:x}", err );
					WARNED_BIND = true;
				}
			}
		}

		static mut FIRST: bool = true;
		// SAFETY: single-threaded contract.
		unsafe { if FIRST { eprintln!( "[ltk-webkit] first texture composited" ); FIRST = false; } };

		Some( tex )
	}

	/// Uploads the pending buffer, if any, and hands it back to WebKit's
	/// pool right away: nothing keeps sampling it afterwards.
	/// None while printing, so the host keeps the frame from before the page was laid out for paper.
	fn take_shown_buffer( &mut self ) -> Option<*mut WPEBuffer>
	{
		if self.print_job.is_some() { None } else { self.pending_buffer.take() }
	}

	fn copy_pending( &mut self, gl: &glow::Context ) -> Option<glow::Texture>
	{
		if let Some( pending ) = self.take_shown_buffer()
		{
			match software::upload( gl, &mut self.gl_texture, &mut self.copy_size, pending )
			{
				Ok( () )   => dbg_log( "buffer copied" ),
				Err( msg ) => eprintln!( "[ltk-webkit] buffer copy failed: {}", msg ),
			}
			// SAFETY: we held a ref via g_object_ref in the signal handler;
			// balance it now.
			unsafe
			{
				if !self.view.is_null()
				{
					wpe_view_buffer_released( self.view, pending );
				}
				g_object_unref( pending as *mut _ );
			}
		}
		if self.copy_size == ( 0, 0 ) { None } else { self.gl_texture }
	}

	fn load_proc<F>( &self, name: &str ) -> Option<F>
	{
		let raw = self.egl_instance.get_proc_address( name )?;
		// SAFETY: the EGL spec guarantees `eglGetProcAddress` returns
		// a callable function pointer of the requested name's documented
		// signature; transmuting to our typed alias is sound provided
		// the alias matches the spec, which we maintain at the type defs.
		Some( unsafe { std::mem::transmute_copy::<extern "system" fn(), F>( &raw ) } )
	}
}

/// Build an `EGLImageKHR` from a `WPEBufferDMABuf` in `egl_display`.
/// The buffer must already be ref'd by the caller; this function does
/// not take ownership.
unsafe fn import_dmabuf_as_image(
	buffer:      *mut WPEBuffer,
	egl_display: *mut c_void,
	egl_create:  EglCreateImageKHR,
) -> Result<*mut c_void, String>
{
	// SAFETY: the caller guarantees `buffer` is a live WPEBuffer pointer.
	let is_dmabuf = unsafe
	{
		g_type_check_instance_is_a(
			buffer as *mut GTypeInstance,
			wpe_buffer_dma_buf_get_type(),
		)
	} != 0;
	if !is_dmabuf
	{
		return Err( "buffer is not WPEBufferDMABuf (SHM not supported here)".into() );
	}
	let dmabuf = buffer as *mut WPEBufferDMABuf;

	let ( w, h, fourcc, n_planes, modifier ) = unsafe
	{
		(
			wpe_buffer_get_width( buffer ),
			wpe_buffer_get_height( buffer ),
			wpe_buffer_dma_buf_get_format( dmabuf ),
			wpe_buffer_dma_buf_get_n_planes( dmabuf ),
			wpe_buffer_dma_buf_get_modifier( dmabuf ),
		)
	};
	if !( 1..=4 ).contains( &n_planes )
	{
		return Err( format!( "unsupported plane count {}", n_planes ) );
	}
	dbg_log( &format!(
		"dmabuf {}x{} fourcc=0x{:08x} modifier={:#x} planes={} pitch={}",
		w, h, fourcc, modifier, n_planes, unsafe { wpe_buffer_dma_buf_get_stride( dmabuf, 0 ) },
	) );

	let mut attribs: Vec<c_int> = Vec::with_capacity( 7 + ( n_planes as usize ) * 10 + 1 );
	attribs.push( EGL_WIDTH );                  attribs.push( w );
	attribs.push( EGL_HEIGHT );                 attribs.push( h );
	attribs.push( EGL_LINUX_DRM_FOURCC_EXT );   attribs.push( fourcc as c_int );
	let mod_lo = ( modifier        & 0xFFFF_FFFF ) as c_int;
	let mod_hi = ( ( modifier >> 32 ) & 0xFFFF_FFFF ) as c_int;
	for i in 0..n_planes as usize
	{
		let fd     = unsafe { wpe_buffer_dma_buf_get_fd    ( dmabuf, i as u32 ) };
		let offset = unsafe { wpe_buffer_dma_buf_get_offset( dmabuf, i as u32 ) };
		let pitch  = unsafe { wpe_buffer_dma_buf_get_stride( dmabuf, i as u32 ) };
		attribs.push( PLANE_FD[ i ] );    attribs.push( fd );
		attribs.push( PLANE_OFF[ i ] );   attribs.push( offset as c_int );
		attribs.push( PLANE_PITCH[ i ] ); attribs.push( pitch as c_int );
		if modifier != 0 && modifier != u64::MAX
		{
			attribs.push( PLANE_MOD_LO[ i ] ); attribs.push( mod_lo );
			attribs.push( PLANE_MOD_HI[ i ] ); attribs.push( mod_hi );
		}
	}
	attribs.push( EGL_NONE );

	// SAFETY: attribs is a valid EGL_LINUX_DMA_BUF_EXT attrib list
	// terminated by EGL_NONE; the buffer is non-null; the display is
	// LTK's current EGLDisplay (also non-null).
	let image = unsafe
	{
		egl_create(
			egl_display,
			ptr::null_mut(),
			EGL_LINUX_DMA_BUF_EXT,
			ptr::null_mut(),
			attribs.as_ptr(),
		)
	};
	if image.is_null()
	{
		return Err( format!( "eglCreateImageKHR returned NULL ({}x{}, fourcc=0x{:08x}, mod={:#x}, planes={})", w, h, fourcc, modifier, n_planes ) );
	}
	Ok( image )
}

impl Drop for Inner
{
	fn drop( &mut self )
	{
		// SAFETY: pointer fields are owned by `Inner` and have not been
		// freed elsewhere. unref is safe to call on a non-null GObject
		// from the main thread (our threading contract).
		unsafe
		{
			if let Some( buf ) = self.pending_buffer.take() { g_object_unref( buf as *mut _ ); }
			if let Some( buf ) = self.bound_buffer.take()   { g_object_unref( buf as *mut _ ); }
			if !self.webview.is_null() { g_object_unref( self.webview as *mut _ ); }
			if !self.display.is_null() { g_object_unref( self.display as *mut _ ); }
		}
		let _ = ORPHANS.try_with( |orphans|
		{
			let mut orphans = orphans.borrow_mut();
			orphans.images.extend( self.bound_image.take() );
			orphans.textures.extend( self.gl_texture.take() );
		} );
	}
}

/// GL objects of dropped views: a drop has no context to free them in, the next draw does.
#[ derive( Default ) ]
struct Orphans
{
	images:   Vec<*mut c_void>,
	textures: Vec<glow::Texture>,
}

thread_local!
{
	static ORPHANS: RefCell<Orphans> = RefCell::new( Orphans::default() );
}

/// Must run with LTK's GLES context current.
fn release_orphans( gl: &glow::Context, egl_display: *mut c_void, egl_destroy: EglDestroyImageKHR )
{
	let orphans = ORPHANS.with( |orphans| std::mem::take( &mut *orphans.borrow_mut() ) );
	for texture in orphans.textures
	{
		// SAFETY: the texture was created in this context by the dropped view.
		unsafe { gl.delete_texture( texture ); }
	}
	for image in orphans.images
	{
		// SAFETY: the image was created against this display by the dropped view.
		unsafe { egl_destroy( egl_display, image ); }
	}
}

// ─── Frame delivery: render_buffer vfunc override ────────────────────────────

/// Class-vfunc override on `WPEViewHeadlessClass.render_buffer` — WebKit
/// calls it once per produced frame. Captures the buffer for the next LTK
/// draw and acks it immediately (mailbox style) so WebKit keeps rendering.
unsafe extern "C" fn render_buffer_override(
	view:           *mut WPEView,
	buffer:         *mut WPEBuffer,
	_damage_rects:  *const WPERectangle,
	_n_damage:      c_uint,
	_error:         *mut *mut GError,
) -> gboolean
{
	if view.is_null() || buffer.is_null() { return 1; }

	// SAFETY: qdata key is NUL-terminated; missing key yields null.
	let raw = unsafe
	{
		g_object_get_data( view as *mut GObject, CURSOR_INNER_QDATA_KEY.as_ptr() as *const c_char )
	};
	let inner = if raw.is_null()
	{
		None
	} else {
		unsafe { &*( raw as *const std::sync::Weak<Mutex<Inner>> ) }.upgrade()
	};
	let Some( inner ) = inner else
	{
		// No host attached — ack so WebKit keeps cycling.
		unsafe { wpe_view_buffer_rendered( view, buffer ); }
		return 1;
	};

	// Replace any previously-pending buffer (we never imported it) and
	// hold a ref so the new one survives until LTK's draw imports it.
	let replaced = match inner.lock()
	{
		Ok( mut guard ) =>
		{
			let old = guard.pending_buffer.take();
			// SAFETY: ref/unref are thread-safe on GObject.
			unsafe { g_object_ref( buffer as *mut _ ); }
			guard.pending_buffer = Some( buffer );
			guard.needs_redraw   = true;
			old
		}
		Err( _ ) => None,
	};
	// The WPE calls below may re-enter through GLib signal emission — the
	// lock must not be held across them.
	if let Some( old ) = replaced
	{
		// SAFETY: we ref'd it on a previous callback; balance it now.
		// Releasing hands the buffer back to WebKit's pool for reuse.
		unsafe
		{
			wpe_view_buffer_released( view, old );
			g_object_unref( old as *mut _ );
		}
	}
	// Ack the frame right away or WebKit throttles the pipeline waiting
	// for it and never produces a second one (the one-frame-behind /
	// black-until-input failure).
	unsafe { wpe_view_buffer_rendered( view, buffer ); }
	dbg_log( "buffer arrived" );
	1
}

/// Diagnostic trace, enabled by setting `LTK_WEBKIT_DEBUG` in the
/// environment. Traces the buffer → draw → import pipeline so a stall
/// (blank widget) can be attributed to the missing stage.
fn dbg_log( msg: &str )
{
	static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
	if *ON.get_or_init( || std::env::var_os( "LTK_WEBKIT_DEBUG" ).is_some() )
	{
		eprintln!( "[ltk-webkit dbg] {}", msg );
	}
}

// ─── Cursor: vfunc override on WPEViewHeadlessClass ──────────────────────────

/// Key under which each WPEView stores its `Weak<Mutex<Inner>>` via
/// `g_object_set_data_full`, so the global cursor override can route
/// the call back to the right `WebView` instance.
const CURSOR_INNER_QDATA_KEY: &[ u8 ] = b"ltk-webkit-inner\0";

fn install_view_overrides()
{
	static ONCE: Once = Once::new();
	ONCE.call_once( ||
	{
		// SAFETY: `g_type_class_ref` is a refcount-incrementing
		// accessor for the type's class struct. We deliberately do
		// not `g_type_class_unref` it: keeping the ref alive for the
		// lifetime of the process keeps the vtable patched. The
		// overrides read stable per-view data from `g_object_get_data`
		// and dispatch by `inner` upgrade, so they are sound across
		// WebView lifetimes.
		unsafe
		{
			let class = g_type_class_ref( wpe_view_headless_get_type() ) as *mut WPEViewClass;
			if !class.is_null()
			{
				( *class ).set_cursor_from_name = Some( cursor_from_name_override );
				( *class ).render_buffer        = Some( render_buffer_override );
			}
		}
	} );
}

unsafe extern "C" fn cursor_from_name_override( view: *mut WPEView, name: *const c_char )
{
	if view.is_null() { return; }
	// SAFETY: qdata key is NUL-terminated; missing key yields null.
	let raw = unsafe
	{
		g_object_get_data( view as *mut GObject, CURSOR_INNER_QDATA_KEY.as_ptr() as *const c_char )
	};
	if raw.is_null() { return; }
	let weak = unsafe { &*( raw as *const std::sync::Weak<Mutex<Inner>> ) };
	let Some( inner ) = weak.upgrade() else { return; };
	let mut guard = match inner.lock()
	{
		Ok( g )  => g,
		Err( _ ) => return,
	};

	let shape = if name.is_null()
	{
		CursorShape::Default
	} else {
		// SAFETY: caller provides a NUL-terminated cursor name string
		// (CSS-style: "default", "pointer", "text", …).
		let s = unsafe { CStr::from_ptr( name ).to_string_lossy() };
		cursor_name_to_shape( &s )
	};
	guard.cursor_shape = shape;
}

fn cursor_name_to_shape( name: &str ) -> CursorShape
{
	use CursorShape::*;
	match name
	{
		"default"       => Default,
		"context-menu"  => ContextMenu,
		"help"          => Help,
		"pointer"       => Pointer,
		"progress"      => Progress,
		"wait"          => Wait,
		"cell"          => Cell,
		"crosshair"     => Crosshair,
		"text"          => Text,
		"vertical-text" => VerticalText,
		"alias"         => Alias,
		"copy"          => Copy,
		"move"          => Move,
		"no-drop"       => NoDrop,
		"not-allowed"   => NotAllowed,
		"grab"          => Grab,
		"grabbing"      => Grabbing,
		"e-resize"      => EResize,
		"n-resize"      => NResize,
		"ne-resize"     => NeResize,
		"nw-resize"     => NwResize,
		"s-resize"      => SResize,
		"se-resize"     => SeResize,
		"sw-resize"     => SwResize,
		"w-resize"      => WResize,
		"ew-resize"     => EwResize,
		"ns-resize"     => NsResize,
		"nesw-resize"   => NeswResize,
		"nwse-resize"   => NwseResize,
		"col-resize"    => ColResize,
		"row-resize"    => RowResize,
		"all-scroll"    => AllScroll,
		"zoom-in"       => ZoomIn,
		"zoom-out"      => ZoomOut,
		// Names LTK does not enumerate (none, …) fall back to the
		// host's per-widget default rather than overriding it.
		_               => Default,
	}
}

/// Wall-clock timestamp the input helpers stamp into WPE events. WPE
/// uses this as the "now" reference for double-click windows and for
/// distinguishing repeats from fresh presses. Anchored at process
/// start so the value monotonically increases.
static APP_START: LazyLock<Instant> = LazyLock::new( Instant::now );

fn elapsed_ms() -> u32
{
	APP_START.elapsed().as_millis() as u32
}

unsafe extern "C" fn drop_weak_qdata( data: gpointer )
{
	if data.is_null() { return; }
	// SAFETY: `data` was produced by `Box::into_raw` in `WebView::new`
	// and is reclaimed exactly once when the host GObject is finalised
	// (or when `g_object_set_data_full` replaces it).
	drop( unsafe { Box::from_raw( data as *mut std::sync::Weak<Mutex<Inner>> ) } );
}

unsafe fn error_message_or_default( err: *mut GError, default: &str ) -> String
{
	if err.is_null() { return default.to_string(); }
	// SAFETY: caller guarantees `err` points at a valid GError.
	unsafe { CStr::from_ptr( ( *err ).message ).to_string_lossy().to_string() }
}

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

	// `cursor_name_to_shape` is the pure mapping between CSS cursor
	// names WebKit emits via `set_cursor_from_name` and LTK's
	// [`CursorShape`]. Pure → unit-testable without a WPE process.

	#[ test ]
	fn cursor_default_is_default()
	{
		assert_eq!( cursor_name_to_shape( "default" ), CursorShape::Default );
	}

	#[ test ]
	fn cursor_pointer_is_pointer()
	{
		assert_eq!( cursor_name_to_shape( "pointer" ), CursorShape::Pointer );
	}

	#[ test ]
	fn cursor_text_is_text()
	{
		assert_eq!( cursor_name_to_shape( "text" ), CursorShape::Text );
	}

	#[ test ]
	fn cursor_grab_grabbing()
	{
		assert_eq!( cursor_name_to_shape( "grab"     ), CursorShape::Grab     );
		assert_eq!( cursor_name_to_shape( "grabbing" ), CursorShape::Grabbing );
	}

	#[ test ]
	fn cursor_resize_edges()
	{
		assert_eq!( cursor_name_to_shape( "n-resize"  ), CursorShape::NResize  );
		assert_eq!( cursor_name_to_shape( "s-resize"  ), CursorShape::SResize  );
		assert_eq!( cursor_name_to_shape( "e-resize"  ), CursorShape::EResize  );
		assert_eq!( cursor_name_to_shape( "ne-resize" ), CursorShape::NeResize );
		assert_eq!( cursor_name_to_shape( "se-resize" ), CursorShape::SeResize );
		assert_eq!( cursor_name_to_shape( "sw-resize" ), CursorShape::SwResize );
		assert_eq!( cursor_name_to_shape( "w-resize"  ), CursorShape::WResize  );
	}

	#[ test ]
	fn cursor_resize_axes()
	{
		assert_eq!( cursor_name_to_shape( "ew-resize"   ), CursorShape::EwResize   );
		assert_eq!( cursor_name_to_shape( "ns-resize"   ), CursorShape::NsResize   );
		assert_eq!( cursor_name_to_shape( "nesw-resize" ), CursorShape::NeswResize );
		assert_eq!( cursor_name_to_shape( "nwse-resize" ), CursorShape::NwseResize );
		assert_eq!( cursor_name_to_shape( "col-resize"  ), CursorShape::ColResize  );
		assert_eq!( cursor_name_to_shape( "row-resize"  ), CursorShape::RowResize  );
	}

	#[ test ]
	fn cursor_scroll_and_zoom()
	{
		assert_eq!( cursor_name_to_shape( "all-scroll" ), CursorShape::AllScroll );
		assert_eq!( cursor_name_to_shape( "zoom-in"    ), CursorShape::ZoomIn    );
		assert_eq!( cursor_name_to_shape( "zoom-out"   ), CursorShape::ZoomOut   );
	}

	#[ test ]
	fn cursor_unknown_falls_back_to_default()
	{
		// Names LTK does not enumerate (none, ...) fall back to `Default`
		// rather than overriding the host's per-widget choice with garbage.
		assert_eq!( cursor_name_to_shape( "none"  ), CursorShape::Default );
		assert_eq!( cursor_name_to_shape( "bogus" ), CursorShape::Default );
		assert_eq!( cursor_name_to_shape( ""      ), CursorShape::Default );
	}

	// `elapsed_ms` is monotonic by construction (anchored at process
	// start). Smoke-test the order rather than absolute values, since
	// the static is shared across the whole test binary.
	#[ test ]
	fn elapsed_ms_is_monotonic()
	{
		let a = elapsed_ms();
		std::thread::sleep( std::time::Duration::from_millis( 2 ) );
		let b = elapsed_ms();
		assert!( b >= a );
	}
}