tessera_ui/

headless.rs

//! Offscreen rendering, input injection, and resource observations.

use std::{
    io::{BufRead, BufReader, Write},
    num::NonZero,
    path::Path,
    time::Duration,
};

use serde::Deserialize;
use serde_json::{Value, json};
use tracing::info;

use crate::{
    NodeId, Px, PxPosition, PxSize,
    build_tree::build_component_tree,
    component_tree::{ComponentNodeMetaDatas, ComponentNodeTree, ComputeMode, ComputeParams},
    context::reset_context_read_dependencies,
    cursor::{
        CursorEventContent, CursorState, GestureState, MOUSE_POINTER_ID, PointerChange, PointerId,
        PressKeyEventType, ScrollDeltaUnit, ScrollEventContent, ScrollEventSource,
    },
    dp::set_scale_factor,
    focus::flush_pending_focus_callbacks,
    ime_state::ImeState,
    keyboard_state::KeyboardState,
    pipeline_context::PipelineContext,
    render_module::RenderModule,
    renderer::{
        MAX_FRAME_SETTLING_RETRIES, RenderCore, TesseraConfig, core::OffscreenReadbackError,
        frame_settling_can_progress,
    },
    runtime::{
        TesseraRuntime, begin_frame_build_invalidations, begin_frame_clock,
        clear_persistent_focus_handles, clear_redraw_waker, has_pending_build_invalidations,
        has_pending_layout_invalidations, has_ready_build_invalidations,
        prune_persistent_focus_handles, reset_build_invalidations, reset_component_replay_tracking,
        reset_focus_read_dependencies, reset_frame_clock, reset_layout_dirty_tracking,
        reset_render_slot_read_dependencies, reset_state_read_dependencies,
        take_layout_dirty_nodes, tick_frame_nanos_receivers,
    },
    time::Instant,
};

#[cfg(feature = "profiling")]
use crate::profiler::{
    FrameMeta, begin_frame as profiler_begin_frame, begin_frame_summary,
    end_frame as profiler_end_frame, submit_frame_meta, submit_frame_summary,
};

/// Environment variable that switches a Tessera application into headless mode.
pub const HEADLESS_ENV: &str = "TESSERA_HEADLESS";
/// Environment variable overriding the initial headless surface width.
pub const HEADLESS_WIDTH_ENV: &str = "TESSERA_HEADLESS_WIDTH";
/// Environment variable overriding the initial headless surface height.
pub const HEADLESS_HEIGHT_ENV: &str = "TESSERA_HEADLESS_HEIGHT";
/// Environment variable overriding physical pixels per density-independent
/// pixel.
pub const HEADLESS_SCALE_FACTOR_ENV: &str = "TESSERA_HEADLESS_SCALE_FACTOR";
/// Environment variable overriding the virtual frame step in milliseconds.
pub const HEADLESS_FRAME_TIME_MS_ENV: &str = "TESSERA_HEADLESS_FRAME_TIME_MS";

/// Returns whether the current process should run in headless mode.
pub fn headless_mode_requested() -> bool {
    match std::env::var(HEADLESS_ENV) {
        Ok(value) => {
            let value = value.trim();
            !value.is_empty() && value != "0" && !value.eq_ignore_ascii_case("false")
        }
        Err(_) => false,
    }
}

/// Errors produced by headless session setup and the JSONL worker loop.
#[derive(Debug)]
pub enum HeadlessError {
    /// An I/O error while reading commands or writing responses.
    Io(std::io::Error),
    /// A malformed JSONL command.
    Json(serde_json::Error),
    /// The GPU render core could not be initialized.
    GpuInit(String),
    /// Reading pixels back from the offscreen target failed.
    Readback(OffscreenReadbackError),
}

impl std::fmt::Display for HeadlessError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(err) => write!(f, "headless io error: {err}"),
            Self::Json(err) => write!(f, "headless protocol error: {err}"),
            Self::GpuInit(err) => write!(f, "headless gpu init failed: {err}"),
            Self::Readback(err) => write!(f, "headless readback failed: {err}"),
        }
    }
}

impl std::error::Error for HeadlessError {}

impl From<std::io::Error> for HeadlessError {
    fn from(err: std::io::Error) -> Self {
        Self::Io(err)
    }
}

impl From<serde_json::Error> for HeadlessError {
    fn from(err: serde_json::Error) -> Self {
        Self::Json(err)
    }
}

impl From<OffscreenReadbackError> for HeadlessError {
    fn from(err: OffscreenReadbackError) -> Self {
        Self::Readback(err)
    }
}

/// Configuration for a headless renderer session.
#[derive(Clone, Debug)]
pub struct HeadlessConfig {
    /// Offscreen target width in physical pixels.
    pub width: u32,
    /// Offscreen target height in physical pixels.
    pub height: u32,
    /// Physical pixels per density-independent pixel; invalid values use 1.0.
    pub scale_factor: f64,
    /// MSAA sample count for render pipelines.
    pub sample_count: u32,
    /// Positive D3D12 non-sampler binding capacity; defaults to 65,536.
    pub max_non_sampler_bindings: u32,
    /// Output texture format; RGBA8 is required for sRGB-encoded readback and
    /// PNG output.
    pub format: wgpu::TextureFormat,
    /// Virtual time advanced per rendered frame.
    pub frame_time: Duration,
}

impl Default for HeadlessConfig {
    fn default() -> Self {
        Self {
            width: 800,
            height: 600,
            scale_factor: 1.0,
            sample_count: 1,
            max_non_sampler_bindings: crate::renderer::DEFAULT_MAX_NON_SAMPLER_BINDINGS,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            frame_time: Duration::from_nanos(16_666_667),
        }
    }
}

/// A deterministic, non-interactive Tessera renderer session.
///
/// Frames advance on a virtual clock, so a fixed input script always produces
/// the same output regardless of wall-clock timing.
pub struct HeadlessRenderer {
    session: crate::RuntimeSession,
    core: RenderCore,
    entry: Box<dyn Fn()>,
    cursor: CursorState,
    keyboard: KeyboardState,
    ime: ImeState,
    size: PxSize,
    physical_size: winit::dpi::PhysicalSize<u32>,
    frame_index: u64,
    frame_origin: Instant,
    current_frame_nanos: u64,
    frame_time: Duration,
    diagnostics: crate::component_tree::LayoutFrameDiagnostics,
    work: crate::FrameWork,
    work_totals: crate::WorkTotals,
    frame_clock_diagnostics: crate::FrameClockDiagnostics,
    frame_graphics_work: crate::GraphicsWorkDiagnostics,

    #[cfg(feature = "profiling")]
    profile_summary: bool,
}

impl HeadlessRenderer {
    /// Returns the GPU instance for resource observations across renderer lifetimes.
    pub fn gpu_instance(&self) -> &wgpu::Instance {
        &self.core.instance
    }

    /// Waits for GPU completion and reports held resource handles and allocator usage.
    ///
    /// Allocator reservations include unused capacity and are not resident VRAM.
    /// Unsupported byte counters and allocator reports are null.
    pub fn resource_snapshot(&self) -> Result<Value, wgpu::PollError> {
        let device = self.core.device();
        device.poll(wgpu::PollType::wait_indefinitely())?;
        let adapter = device.adapter_info();
        let byte_counters = matches!(adapter.backend, wgpu::Backend::Vulkan | wgpu::Backend::Dx12);
        let counters = device.get_internal_counters().hal;
        let resources = self.core.instance.generate_report();
        let allocator = device.generate_allocator_report().map(|report| {
            json!({
                "allocated_bytes": report.total_allocated_bytes,
                "reserved_bytes": report.total_reserved_bytes,
                "allocations": report.allocations.iter().map(|allocation| json!({
                    "name": allocation.name,
                    "bytes": allocation.size,
                })).collect::<Vec<_>>(),
            })
        });
        Ok(json!({
            "adapter": adapter.name,
            "backend": format!("{:?}", adapter.backend),
            "max_non_sampler_bindings": device.limits().max_non_sampler_bindings,
            "buffers": resources.as_ref().map(|r| r.hub.buffers.num_kept_from_user),
            "textures": resources.as_ref().map(|r| r.hub.textures.num_kept_from_user),
            "texture_views": resources.as_ref().map(|r| r.hub.texture_views.num_kept_from_user),
            "bind_groups": resources.as_ref().map(|r| r.hub.bind_groups.num_kept_from_user),
            "render_pipelines": resources.as_ref().map(|r| r.hub.render_pipelines.num_kept_from_user),
            "compute_pipelines": resources.as_ref().map(|r| r.hub.compute_pipelines.num_kept_from_user),
            "buffer_bytes": byte_counters.then(|| counters.buffer_memory.read()),
            "texture_bytes": byte_counters.then(|| counters.texture_memory.read()),
            "allocator": allocator,
            "graphics_work": self.graphics_work(),
        }))
    }

    /// Captures cumulative resource creation and uploads performed by pipelines.
    pub fn graphics_work(&self) -> crate::GraphicsWorkDiagnostics {
        self.core.resources().graphics.diagnostics()
    }

    /// Returns actual resource operations performed in the last completed frame.
    pub fn frame_graphics_work(&self) -> &crate::GraphicsWorkDiagnostics {
        &self.frame_graphics_work
    }
    /// Returns the runtime identity shared by this session's snapshots and diagnostics.
    pub fn session_id(&self) -> crate::RuntimeSessionId {
        self.session.identity()
    }

    /// Runs state or controller operations in this renderer's session.
    pub fn run<R>(&self, work: impl FnOnce() -> R) -> R {
        self.session.run(work)
    }

    /// Creates a headless renderer for the given entry point and render
    /// modules.
    pub fn new<Output: 'static>(
        entry: Box<dyn Fn() -> Output>,
        modules: Vec<Box<dyn RenderModule>>,
        config: HeadlessConfig,
    ) -> Result<Self, HeadlessError> {
        let session = crate::RuntimeSession::for_root();
        session.activate();
        let width = config.width.max(1);
        let height = config.height.max(1);
        let physical_size = winit::dpi::PhysicalSize::new(width, height);

        let mut core = pollster::block_on(RenderCore::new_offscreen(
            physical_size,
            config.format,
            config.sample_count,
            config.max_non_sampler_bindings,
        ));

        let scale_factor = normalize_scale_factor(config.scale_factor);
        set_scale_factor(scale_factor);

        {
            let mut context = PipelineContext::new(&mut core);
            for module in &modules {
                module.register_pipelines(&mut context);
            }
        }

        reset_headless_runtime(physical_size);

        info!(
            "Headless renderer initialized at {}x{} ({} samples, {:?})",
            width, height, config.sample_count, config.format
        );

        Ok(Self {
            session,
            core,
            entry: Box::new(move || {
                entry();
            }),
            cursor: CursorState::default(),
            keyboard: KeyboardState::default(),
            ime: ImeState::default(),
            size: PxSize::new(Px(width as i32), Px(height as i32)),
            physical_size,
            frame_index: 0,
            frame_origin: Instant::now(),
            current_frame_nanos: 0,
            frame_time: config.frame_time.max(Duration::from_nanos(1)),
            diagnostics: Default::default(),
            work: Default::default(),
            work_totals: Default::default(),
            frame_clock_diagnostics: Default::default(),
            frame_graphics_work: Default::default(),

            #[cfg(feature = "profiling")]
            profile_summary: false,
        })
    }

    /// Returns the current offscreen size in physical pixels.
    pub fn physical_size(&self) -> winit::dpi::PhysicalSize<u32> {
        let _session = self.session.enter();
        self.physical_size
    }

    /// Returns the number of frames rendered so far.
    pub fn frame_index(&self) -> u64 {
        let _session = self.session.enter();
        self.frame_index
    }

    /// Returns the work performed by the most recently rendered frame.
    pub fn diagnostics(&self) -> crate::component_tree::LayoutFrameDiagnostics {
        let _session = self.session.enter();
        self.diagnostics
    }

    /// Queues a synthetic pointer change.
    ///
    /// Movement changes also update the tracked cursor position so hit testing
    /// observes the new location on the next frame.
    pub fn inject_pointer(&mut self, change: PointerChange) {
        let _session = self.session.enter();
        if let Some(position) = change.position_snapshot() {
            self.cursor
                .update_pointer_position(change.pointer_id, position);
        }
        self.cursor.push_event(change);
    }

    /// Moves the given pointer to `position`.
    pub fn pointer_move(&mut self, pointer_id: PointerId, position: PxPosition) {
        let _session = self.session.enter();
        self.cursor.update_pointer_position(pointer_id, position);
        self.cursor.push_event(PointerChange {
            timestamp: Instant::now(),
            pointer_id,
            content: CursorEventContent::Moved(position),
            gesture_state: GestureState::TapCandidate,
            sampled_position: Default::default(),
            consumed: false,
            tap_claimed: false,
            scroll_discrete: None,
        });
    }

    /// Presses a pointer button at `position`.
    pub fn pointer_press(
        &mut self,
        pointer_id: PointerId,
        position: PxPosition,
        button: PressKeyEventType,
    ) {
        let _session = self.session.enter();
        self.cursor.update_pointer_position(pointer_id, position);
        self.cursor.push_event(PointerChange {
            timestamp: Instant::now(),
            pointer_id,
            content: CursorEventContent::Pressed(button),
            gesture_state: GestureState::TapCandidate,
            sampled_position: Default::default(),
            consumed: false,
            tap_claimed: false,
            scroll_discrete: None,
        });
    }

    /// Releases a pointer button at `position`.
    pub fn pointer_release(
        &mut self,
        pointer_id: PointerId,
        position: PxPosition,
        button: PressKeyEventType,
    ) {
        let _session = self.session.enter();
        self.cursor.update_pointer_position(pointer_id, position);
        self.cursor.push_event(PointerChange {
            timestamp: Instant::now(),
            pointer_id,
            content: CursorEventContent::Released(button),
            gesture_state: GestureState::TapCandidate,
            sampled_position: Default::default(),
            consumed: false,
            tap_claimed: false,
            scroll_discrete: None,
        });
    }

    /// Queues a mouse-wheel scroll at `position`.
    pub fn pointer_scroll(
        &mut self,
        pointer_id: PointerId,
        position: PxPosition,
        delta_x: f32,
        delta_y: f32,
    ) {
        let _session = self.session.enter();
        self.cursor.update_pointer_position(pointer_id, position);
        self.cursor.push_event(PointerChange {
            timestamp: Instant::now(),
            pointer_id,
            content: CursorEventContent::Scroll(ScrollEventContent {
                delta_x,
                delta_y,
                unit: ScrollDeltaUnit::Pixel,
                source: ScrollEventSource::Wheel,
            }),
            gesture_state: GestureState::TapCandidate,
            sampled_position: Default::default(),
            consumed: false,
            tap_claimed: false,
            scroll_discrete: None,
        });
    }

    /// Starts a touch contact at the given window position.
    pub fn touch_start(&mut self, touch_id: u64, position: PxPosition) {
        let _session = self.session.enter();
        self.cursor.handle_touch_start(touch_id, position);
    }

    /// Moves a touch contact, generating scrolling after touch slop is crossed.
    pub fn touch_move(&mut self, touch_id: u64, position: PxPosition) {
        let _session = self.session.enter();
        if let Some(scroll) = self.cursor.handle_touch_move(touch_id, position) {
            self.cursor.push_event(scroll);
        }
    }

    /// Releases a touch contact and completes its gesture.
    pub fn touch_end(&mut self, touch_id: u64) {
        let _session = self.session.enter();
        self.cursor.handle_touch_end(touch_id);
    }

    /// Cancels a touch contact without producing a tap or fling.
    pub fn touch_cancel(&mut self, touch_id: u64) {
        let _session = self.session.enter();
        self.cursor.handle_touch_cancel(touch_id);
    }

    /// Queues a native or owned keyboard sample for the next frame.
    pub fn inject_key_event(&mut self, event: impl Into<crate::KeyboardEvent>) {
        let _session = self.session.enter();
        let event = event.into();
        TesseraRuntime::with_mut(|runtime| {
            runtime
                .component_tree
                .focus_owner_mut()
                .record_keyboard_input(event.state, Instant::now())
        });
        self.keyboard.push_event(event);
    }

    /// Queues a non-repeating press of a named key for the next frame.
    pub fn press_key(&mut self, key: winit::keyboard::NamedKey) {
        self.inject_key_event(crate::KeyboardEvent::named(
            key,
            winit::event::ElementState::Pressed,
        ));
    }

    /// Sets the modifier state captured by subsequent keyboard events.
    pub fn set_key_modifiers(&mut self, modifiers: winit::keyboard::ModifiersState) {
        let _session = self.session.enter();
        self.keyboard.update_modifiers(modifiers);
    }

    /// Queues an IME event, used for synthetic text entry.
    pub fn inject_ime_event(&mut self, event: winit::event::Ime) {
        let _session = self.session.enter();
        self.ime.push_event(event);
    }

    /// Commits `text` as IME input for the next frame.
    pub fn inject_text(&mut self, text: &str) {
        let _session = self.session.enter();
        self.ime
            .push_event(winit::event::Ime::Commit(text.to_string()));
    }

    /// Advances the virtual clock by one frame and renders it.
    pub fn step_frame(&mut self) {
        let _session = self.session.enter();
        #[cfg(feature = "profiling")]
        let wait_timer = Instant::now();
        // Offscreen rendering has no swapchain to bound frames in flight.
        if self.frame_index.is_multiple_of(2) {
            self.core
                .device()
                .poll(wgpu::PollType::wait_indefinitely())
                .expect("headless GPU frame completion failed");
        }
        #[cfg(feature = "profiling")]
        let wait_duration = wait_timer.elapsed();
        TesseraRuntime::with_mut(|runtime| runtime.component_tree.begin_frame_diagnostics());
        let graphics_before = self.graphics_work();
        crate::work::begin();
        self.current_frame_nanos = self
            .current_frame_nanos
            .saturating_add(self.frame_time.as_nanos().min(u64::MAX as u128) as u64);
        let frame_time = self.frame_origin + Duration::from_nanos(self.current_frame_nanos);
        #[cfg(feature = "profiling")]
        if self.profile_summary {
            begin_frame_summary(self.frame_index);
        } else {
            profiler_begin_frame(self.frame_index);
        }
        #[cfg(feature = "profiling")]
        let frame_timer = Instant::now();
        begin_frame_clock(frame_time);
        begin_frame_build_invalidations();
        crate::asset::settle();
        // Tick frame-nanos receivers before the build so their state writes are
        // consumed by the current recomposition pass.
        tick_frame_nanos_receivers();

        let mut _build_tree_result = build_component_tree(&self.entry);

        #[cfg(feature = "profiling")]
        let initial_build_duration = _build_tree_result.duration();
        #[cfg(feature = "profiling")]
        let draw_timer = Instant::now();
        let cursor_position = self.cursor.position();
        let mut pointer_changes = Some(self.cursor.take_events());
        let mut keyboard_events = Some(self.keyboard.take_events());
        let mut ime_events = Some(self.ime.take_events());
        let modifiers = self.keyboard.modifiers();
        let screen_size = self.size;
        let mut retry_focus_move = None;
        let mut retry_focus_reveal = false;
        let mut retries = 0;
        let mut _record_cost = Duration::ZERO;
        let mut _diagnostics = crate::component_tree::LayoutFrameDiagnostics::default();
        let graph = loop {
            let layout_dirty_nodes = take_layout_dirty_nodes();
            let (graph, _requests, diagnostics, record_cost, next_move, next_reveal, next_keyboard) =
                TesseraRuntime::with_mut(|runtime| {
                    runtime.component_tree.compute(
                        ComputeParams {
                            screen_size,
                            cursor_position,
                            pointer_changes: pointer_changes.take().unwrap_or_default(),
                            keyboard_events: keyboard_events.take().unwrap_or_default(),
                            ime_events: ime_events.take().unwrap_or_default(),
                            retry_focus_move,
                            retry_focus_reveal,
                            modifiers,
                            layout_dirty_nodes,
                        },
                        ComputeMode::Full,
                    )
                });
            _record_cost += record_cost;
            _diagnostics.accumulate_pass(diagnostics);
            flush_pending_focus_callbacks();
            crate::component_tree::flush_pending_globally_positioned_callbacks();
            let next_keyboard = next_keyboard
                || TesseraRuntime::with(|runtime| {
                    runtime.component_tree.has_pending_focus_reveal()
                });
            let focus_retry = next_move.is_some() || next_reveal || next_keyboard;
            if !focus_retry && !frame_settling_can_progress(false) {
                break graph;
            }
            if retries >= MAX_FRAME_SETTLING_RETRIES
                || (focus_retry && !frame_settling_can_progress(next_keyboard))
            {
                if next_reveal
                    && (has_pending_build_invalidations() || has_pending_layout_invalidations())
                {
                    TesseraRuntime::with_mut(|runtime| {
                        runtime
                            .component_tree
                            .focus_owner_mut()
                            .retain_reveal_retry();
                    });
                }
                break graph;
            }
            retries += 1;
            retry_focus_move = next_move;
            retry_focus_reveal = next_reveal;
            if focus_retry || has_ready_build_invalidations() {
                _build_tree_result.absorb_retry(build_component_tree(&self.entry));
            }
        };
        self.diagnostics = _diagnostics;
        prune_persistent_focus_handles();
        #[cfg(feature = "profiling")]
        let draw_duration = draw_timer.elapsed().saturating_sub(
            _build_tree_result
                .duration()
                .saturating_sub(initial_build_duration),
        );

        #[cfg(feature = "profiling")]
        let render_timer = Instant::now();
        #[cfg(feature = "debug-dirty-overlay")]
        self.core.render(graph, &[]);
        #[cfg(not(feature = "debug-dirty-overlay"))]
        self.core.render(graph);
        #[cfg(feature = "profiling")]
        let render_duration = render_timer.elapsed();
        self.cursor.frame_cleanup();
        #[cfg(feature = "profiling")]
        {
            let breakdown = self.core.last_render_breakdown();
            let metadata_timer = tracing::enabled!(tracing::Level::DEBUG).then(Instant::now);
            let nodes = if self.profile_summary {
                Vec::new()
            } else {
                TesseraRuntime::with_mut(|rt| rt.component_tree.profiler_nodes())
            };
            if let Some(metadata_timer) = metadata_timer {
                tracing::debug!(
                    frame_index = self.frame_index,
                    elapsed_us = metadata_timer.elapsed().as_micros(),
                    "headless_profiler_metadata_cpu"
                );
            }
            let frame_duration = frame_timer.elapsed();
            #[cfg(not(target_arch = "wasm32"))]
            let render_gpu_ns = self.core.read_gpu_time().map(|time| time.as_nanos());
            #[cfg(target_arch = "wasm32")]
            let render_gpu_ns = None;
            let metadata = FrameMeta {
                frame_idx: self.frame_index,
                build_mode: _build_tree_result.profiler_build_mode(),
                redraw_reasons: Vec::new(),
                inter_frame_wait_ns: Some(wait_duration.as_nanos()),
                partial_replay_nodes: _build_tree_result.partial_replay_nodes(),
                total_nodes_before_build: _build_tree_result.total_nodes_before_build(),
                render_time_ns: Some(render_duration.as_nanos()),
                render_prepare_ns: None,
                render_acquire_ns: breakdown.map(|timing| timing.acquire.as_nanos()),
                render_build_passes_ns: breakdown.map(|timing| timing.build_passes.as_nanos()),
                render_encode_ns: breakdown.map(|timing| timing.encode.as_nanos()),
                render_submit_ns: breakdown.map(|timing| timing.submit.as_nanos()),
                render_present_ns: breakdown.map(|timing| timing.present.as_nanos()),
                render_gpu_ns,
                build_tree_time_ns: Some(_build_tree_result.duration().as_nanos()),
                draw_time_ns: Some(draw_duration.as_nanos()),
                record_time_ns: Some(_record_cost.as_nanos()),
                frame_total_ns: Some(frame_duration.as_nanos()),
                layout_diagnostics: Some(_diagnostics),
                nodes,
            };
            if self.profile_summary {
                submit_frame_summary(metadata);
            } else {
                submit_frame_meta(metadata);
            }
            profiler_end_frame();
        }

        self.frame_clock_diagnostics = crate::runtime::frame_clock_diagnostics();

        self.work = crate::work::finish();
        self.work_totals.record(&self.work);
        self.frame_graphics_work = self.graphics_work().since(&graphics_before);
        self.frame_index = self.frame_index.wrapping_add(1);
    }

    /// Renders exactly `frames` frames (at least one).
    pub fn render_frames(&mut self, frames: u32) {
        let _session = self.session.enter();
        for _ in 0..frames.max(1) {
            self.step_frame();
        }
    }

    /// Renders frames until at least `duration` of virtual time has elapsed.
    pub fn render_for_duration(&mut self, duration: Duration) {
        let _session = self.session.enter();
        let mut elapsed = Duration::ZERO;
        loop {
            self.step_frame();
            elapsed += self.frame_time;
            if elapsed >= duration {
                break;
            }
        }
    }

    /// Reads the last rendered frame back as tightly packed RGBA8 pixels.
    pub fn read_pixels(&self) -> Result<Vec<u8>, HeadlessError> {
        let _session = self.session.enter();
        Ok(self.core.read_offscreen_rgba()?)
    }

    /// Resizes the offscreen target and updates the runtime window size.
    pub fn resize(&mut self, width: u32, height: u32) {
        let _session = self.session.enter();
        let width = width.max(1);
        let height = height.max(1);
        let physical_size = winit::dpi::PhysicalSize::new(width, height);
        self.physical_size = physical_size;
        self.size = PxSize::new(Px(width as i32), Px(height as i32));
        self.core.resize(physical_size);
        self.core.resize_surface();
        TesseraRuntime::with_mut(|runtime| runtime.window_size = [width, height]);
    }

    /// Returns actual component, layout, and paint work in the last frame.
    pub fn work(&self) -> &crate::FrameWork {
        &self.work
    }

    /// Returns cumulative work for this fixture's lifetime.
    pub fn work_totals(&self) -> &crate::WorkTotals {
        &self.work_totals
    }

    /// Returns frame-clock work and remaining subscriptions for the last frame.
    pub fn frame_clock_diagnostics(&self) -> &crate::FrameClockDiagnostics {
        &self.frame_clock_diagnostics
    }

    /// Captures typed component bounds, labels, and test tags for inspection.
    #[cfg(any(test, feature = "testing"))]
    pub fn inspect_components(&self) -> crate::testing::ComponentSnapshot {
        let _session = self.session.enter();
        crate::testing::ComponentSnapshot::capture()
    }

    /// Captures the complete published accessibility tree with typed queries.
    #[cfg(any(test, feature = "testing"))]
    pub fn inspect_accessibility(&self) -> Option<crate::testing::AccessibilitySnapshot> {
        self.accessibility_snapshot()
            .map(|tree| crate::testing::AccessibilitySnapshot::new(tree, self.session.identity()))
    }

    /// Captures a semantic snapshot of the component tree as JSON.
    ///
    /// Each node reports its component function name, role, absolute bounds and
    /// accessibility metadata (role, label, value, key and state flags), which
    /// is what an automated agent needs to locate and target widgets.
    pub fn snapshot(&self) -> Value {
        let _session = self.session.enter();
        TesseraRuntime::with(|runtime| {
            let tree = runtime.component_tree.tree();
            let metadatas = runtime.component_tree.metadatas();
            let root = tree.get_node_id_at(NonZero::new(1).expect("root index is non-zero"));
            let mut counter = 0u64;
            let root_value = match root {
                Some(root) => snapshot_node(tree, metadatas, root, &mut counter),
                None => Value::Null,
            };
            json!({
                "width": self.physical_size.width,
                "height": self.physical_size.height,
                "scale_factor": crate::dp::scale_factor(),
                "frame_index": self.frame_index,
                "node_count": counter,
                "root": root_value,
            })
        })
    }

    /// Returns the accessibility tree published to assistive technologies.
    ///
    /// Use this after rendering a frame to verify semantic roles, reading
    /// order, visibility, actions, and focus independently of layout
    /// snapshots.
    pub fn accessibility_snapshot(&self) -> Option<accesskit::TreeUpdate> {
        let _session = self.session.enter();
        TesseraRuntime::with_mut(|runtime| runtime.component_tree.accessibility_update(None, true))
    }

    /// Dispatches an assistive-technology action to a published node.
    ///
    /// Returns whether a focus target or action handler received the request.
    /// Render another frame to publish resulting state and focus changes.
    pub fn dispatch_accessibility_action(&mut self, request: accesskit::ActionRequest) -> bool {
        let _session = self.session.enter();
        let handled = TesseraRuntime::with_mut(|runtime| {
            let (tree, metadatas, focus_owner) =
                runtime.component_tree.accessibility_dispatch_context();
            crate::accessibility::dispatch_action(tree, metadatas, focus_owner, request)
        });
        flush_pending_focus_callbacks();
        handled
    }
}

fn snapshot_coordinate(value: f32) -> Value {
    if value.fract() == 0.0 {
        json!(value as i64)
    } else {
        json!(value)
    }
}

fn snapshot_node(
    tree: &ComponentNodeTree,
    metadatas: &ComponentNodeMetaDatas,
    node_id: NodeId,
    counter: &mut u64,
) -> Value {
    *counter += 1;
    let node = tree.get(node_id);
    let fn_name = node.map_or("<unknown>", |node| node.get().fn_name);
    let role = node
        .map(|node| format!("{:?}", node.get().role))
        .unwrap_or_else(|| "<unknown>".to_string());

    let metadata = metadatas.get(&node_id);
    let bounds = metadata
        .and_then(|metadata| {
            let position = metadata.abs_position?;
            let size = metadata.computed_data?;
            let transform = metadata.local_to_window.unwrap_or_else(|| {
                crate::LocalToWindow::new(1.0, position).expect("Placed origin must be finite")
            });
            let bounds = transform.map_rect(crate::FloatRect::from_position_size(
                PxPosition::ZERO,
                PxSize::new(size.width, size.height),
            ));
            Some(json!({
                "x": snapshot_coordinate(bounds.x),
                "y": snapshot_coordinate(bounds.y),
                "width": snapshot_coordinate(bounds.width),
                "height": snapshot_coordinate(bounds.height),
            }))
        })
        .unwrap_or(Value::Null);

    let accessibility = metadata
        .and_then(|metadata| metadata.accessibility.as_ref())
        .map(|accessibility| {
            let accessibility = accessibility.snapshot();
            json!({
                "role": accessibility.role.map(|role| format!("{role:?}")),
                "label": accessibility.label,
                "value": accessibility.value,
                "key": accessibility.key,
                "focusable": accessibility.focusable,
                "focused": accessibility.focused,
                "disabled": accessibility.disabled,
                "expanded": accessibility.expanded,
                "has_popup": accessibility.has_popup.map(|popup| format!("{popup:?}")),
                "hidden": accessibility.hidden,
            })
        })
        .unwrap_or(Value::Null);

    let children: Vec<Value> = node_id
        .children(tree)
        .map(|child| snapshot_node(tree, metadatas, child, counter))
        .collect();

    json!({
        "fn_name": fn_name,
        "role": role,
        "bounds": bounds,
        "accessibility": accessibility,
        "children": children,
    })
}

fn reset_headless_runtime(size: winit::dpi::PhysicalSize<u32>) {
    TesseraRuntime::with_mut(|runtime| {
        runtime.component_tree.reset();
        runtime.cursor_icon_request = None;
        runtime.window_minimized = false;
        runtime.window_size = [size.width, size.height];
    });
    reset_layout_dirty_tracking();
    reset_component_replay_tracking();
    reset_focus_read_dependencies();
    reset_render_slot_read_dependencies();
    reset_state_read_dependencies();
    reset_context_read_dependencies();
    reset_build_invalidations();
    reset_frame_clock();
    clear_redraw_waker();
    clear_persistent_focus_handles();
    crate::runtime::reset_component_slots();
}

/// Runs the worker side of the `cargo tessera headless` protocol.
///
/// Reads one JSON command per line from stdin and writes one JSON response per
/// line to stdout. Diagnostics are written to stderr so stdout stays a clean
/// JSONL stream.
pub fn run_headless(
    entry: Box<dyn Fn()>,
    modules: Vec<Box<dyn RenderModule>>,
    config: TesseraConfig,
) -> Result<(), HeadlessError> {
    init_headless_tracing();

    let headless_config = HeadlessConfig {
        width: env_u32(HEADLESS_WIDTH_ENV).unwrap_or(800),
        height: env_u32(HEADLESS_HEIGHT_ENV).unwrap_or(600),
        scale_factor: std::env::var(HEADLESS_SCALE_FACTOR_ENV)
            .ok()
            .and_then(|value| value.trim().parse().ok())
            .map(normalize_scale_factor)
            .unwrap_or(1.0),
        sample_count: config.sample_count.max(1),
        max_non_sampler_bindings: config.max_non_sampler_bindings,
        ..HeadlessConfig::default()
    };
    let mut frame_time = headless_config.frame_time;
    if let Some(ms) = env_u32(HEADLESS_FRAME_TIME_MS_ENV) {
        frame_time = Duration::from_millis(ms.max(1) as u64);
    }

    let mut renderer = HeadlessRenderer::new(entry, modules, headless_config)?;
    renderer.frame_time = frame_time;
    #[cfg(feature = "profiling")]
    {
        crate::profiler::set_output_path(crate::renderer::resolve_profiler_output_path(&config));
        renderer.profile_summary = std::env::var("TESSERA_HEADLESS_PROFILE")
            .is_ok_and(|value| value.eq_ignore_ascii_case("summary"));
    }

    let stdout = std::io::stdout();
    let mut out = stdout.lock();
    write_line(
        &mut out,
        json!({
            "event": "ready",
            "width": renderer.physical_size.width,
            "height": renderer.physical_size.height,
            "scale_factor": crate::dp::scale_factor(),
        }),
    )?;

    let stdin = std::io::stdin();
    let reader = BufReader::new(stdin.lock());
    for line in reader.lines() {
        let line = line?;
        let line = line.trim();
        if line.is_empty() {
            continue;
        }

        let request = match serde_json::from_str::<WorkerRequest>(line) {
            Ok(request) => request,
            Err(err) => {
                write_line(
                    &mut out,
                    json!({"ok": false, "error": format!("invalid command: {err}")}),
                )?;
                continue;
            }
        };

        let is_shutdown = matches!(&request, WorkerRequest::Shutdown { .. });
        let (id, mut response) = handle_request(&mut renderer, request)?;
        if let Some(map) = response.as_object_mut() {
            if let Some(id) = id {
                map.insert("id".to_string(), json!(id));
            }
        }
        write_line(&mut out, response)?;

        if is_shutdown {
            break;
        }
    }

    Ok(())
}

fn handle_request(
    renderer: &mut HeadlessRenderer,
    request: WorkerRequest,
) -> Result<(Option<u64>, Value), HeadlessError> {
    match request {
        WorkerRequest::Input {
            id,
            kind,
            pointer_id,
            x,
            y,
            delta_x,
            delta_y,
            button,
        } => {
            let pointer_id = pointer_id.unwrap_or(MOUSE_POINTER_ID);
            let position = PxPosition::from_f32_xy(x.unwrap_or(0.0), y.unwrap_or(0.0));
            let button = button.unwrap_or_default().to_press_key();
            match kind {
                InputKind::Press => renderer.pointer_press(pointer_id, position, button),
                InputKind::Release => renderer.pointer_release(pointer_id, position, button),
                InputKind::Move => renderer.pointer_move(pointer_id, position),
                InputKind::Scroll => renderer.pointer_scroll(
                    pointer_id,
                    position,
                    delta_x.unwrap_or(0.0),
                    delta_y.unwrap_or(0.0),
                ),
            }
            Ok((id, json!({"ok": true, "kind": kind.as_str()})))
        }
        WorkerRequest::Text { id, text } => {
            renderer.inject_text(&text);
            Ok((id, json!({"ok": true, "chars": text.chars().count()})))
        }
        WorkerRequest::Render {
            id,
            frames,
            duration_ms,
            out,
        } => {
            let rendered = if let Some(duration_ms) = duration_ms {
                renderer.render_for_duration(Duration::from_millis(duration_ms.max(1)));
                None
            } else {
                let frames = frames.unwrap_or(1).max(1);
                renderer.render_frames(frames);
                Some(frames)
            };

            let size = renderer.physical_size();
            let mut response = json!({
                "ok": true,
                "width": size.width,
                "height": size.height,
                "frame_index": renderer.frame_index(),
            });
            if let Some(frames) = rendered {
                response["frames"] = json!(frames);
            }

            if let Some(out_path) = out {
                let pixels = renderer.read_pixels()?;
                let png = encode_png_rgba(size.width, size.height, &pixels);
                std::fs::write(&out_path, &png)?;
                response["path"] = json!(out_path);
                response["bytes"] = json!(png.len());
            }
            Ok((id, response))
        }
        WorkerRequest::Snapshot { id } => {
            let snapshot = renderer.snapshot();
            Ok((id, json!({"ok": true, "snapshot": snapshot})))
        }
        WorkerRequest::Resources { id } => {
            let response = match renderer.resource_snapshot() {
                Ok(resources) => json!({"ok": true, "resources": resources}),
                Err(error) => json!({"ok": false, "error": error.to_string()}),
            };
            Ok((id, response))
        }
        WorkerRequest::Resize { id, width, height } => {
            renderer.resize(width, height);
            let size = renderer.physical_size();
            Ok((
                id,
                json!({"ok": true, "width": size.width, "height": size.height}),
            ))
        }
        WorkerRequest::Shutdown { id } => {
            let _ = id;
            Ok((id, json!({"ok": true, "event": "shutdown"})))
        }
    }
}

fn write_line(out: &mut impl Write, value: Value) -> Result<(), HeadlessError> {
    let encoded = serde_json::to_string(&value)?;
    out.write_all(encoded.as_bytes())?;
    out.write_all(b"\n")?;
    out.flush()?;
    Ok(())
}

fn env_u32(key: &str) -> Option<u32> {
    std::env::var(key)
        .ok()
        .and_then(|value| value.trim().parse::<u32>().ok())
}

fn normalize_scale_factor(value: f64) -> f64 {
    if value.is_finite() && value > 0.0 {
        value
    } else {
        1.0
    }
}

fn init_headless_tracing() {
    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("error,tessera_ui=info"));
    // Keep stdout reserved for the JSONL protocol.
    let _ = tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_writer(std::io::stderr)
        .try_init();
}

#[derive(Clone, Copy, Debug, Default, Deserialize)]
#[serde(rename_all = "snake_case")]
enum InputKind {
    #[default]
    Press,
    Release,
    Move,
    Scroll,
}

impl InputKind {
    fn as_str(self) -> &'static str {
        match self {
            Self::Press => "press",
            Self::Release => "release",
            Self::Move => "move",
            Self::Scroll => "scroll",
        }
    }
}

#[derive(Clone, Copy, Debug, Default, Deserialize)]
#[serde(rename_all = "snake_case")]
enum ButtonKind {
    #[default]
    Left,
    Right,
    Middle,
}

impl ButtonKind {
    fn to_press_key(self) -> PressKeyEventType {
        match self {
            Self::Left => PressKeyEventType::Left,
            Self::Right => PressKeyEventType::Right,
            Self::Middle => PressKeyEventType::Middle,
        }
    }
}

#[derive(Debug, Deserialize)]
#[serde(tag = "cmd", rename_all = "snake_case")]
enum WorkerRequest {
    Input {
        #[serde(default)]
        id: Option<u64>,
        kind: InputKind,
        #[serde(default)]
        pointer_id: Option<u64>,
        #[serde(default)]
        x: Option<f32>,
        #[serde(default)]
        y: Option<f32>,
        #[serde(default)]
        delta_x: Option<f32>,
        #[serde(default)]
        delta_y: Option<f32>,
        #[serde(default)]
        button: Option<ButtonKind>,
    },
    Text {
        #[serde(default)]
        id: Option<u64>,
        text: String,
    },
    Render {
        #[serde(default)]
        id: Option<u64>,
        #[serde(default)]
        frames: Option<u32>,
        #[serde(default)]
        duration_ms: Option<u64>,
        #[serde(default)]
        out: Option<String>,
    },
    Snapshot {
        #[serde(default)]
        id: Option<u64>,
    },
    Resources {
        #[serde(default)]
        id: Option<u64>,
    },
    Resize {
        #[serde(default)]
        id: Option<u64>,
        width: u32,
        height: u32,
    },
    Shutdown {
        #[serde(default)]
        id: Option<u64>,
    },
}

/// Encodes tightly packed RGBA8 pixels as a PNG image.
///
/// Uses stored (uncompressed) DEFLATE blocks so no compression dependency is
/// required; the resulting file is larger than a compressed PNG but fully
/// valid and readable by any PNG consumer.
pub fn encode_png_rgba(width: u32, height: u32, pixels: &[u8]) -> Vec<u8> {
    let row_bytes = width as usize * 4;
    let mut raw = Vec::with_capacity((height as usize) * (1 + row_bytes));
    for row in 0..height as usize {
        raw.push(0);
        let start = row * row_bytes;
        raw.extend_from_slice(&pixels[start..start + row_bytes]);
    }

    let mut out = Vec::with_capacity(raw.len() + 1024);
    out.extend_from_slice(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]);

    let mut ihdr = Vec::with_capacity(13);
    ihdr.extend_from_slice(&width.to_be_bytes());
    ihdr.extend_from_slice(&height.to_be_bytes());
    ihdr.push(8); // bit depth
    ihdr.push(6); // color type: RGBA
    ihdr.push(0); // compression method
    ihdr.push(0); // filter method
    ihdr.push(0); // interlace method
    write_png_chunk(&mut out, b"IHDR", &ihdr);
    write_png_chunk(&mut out, b"IDAT", &zlib_store(&raw));
    write_png_chunk(&mut out, b"IEND", &[]);
    out
}

fn write_png_chunk(out: &mut Vec<u8>, kind: &[u8; 4], data: &[u8]) {
    out.extend_from_slice(&(data.len() as u32).to_be_bytes());
    out.extend_from_slice(kind);
    out.extend_from_slice(data);

    let mut crc = Crc32::new();
    crc.update(kind);
    crc.update(data);
    out.extend_from_slice(&crc.finish().to_be_bytes());
}

fn zlib_store(data: &[u8]) -> Vec<u8> {
    let mut out = Vec::with_capacity(data.len() + data.len() / 65_535 * 5 + 16);
    // zlib header: deflate, 32K window, default compression level.
    out.push(0x78);
    out.push(0x01);

    if data.is_empty() {
        out.extend_from_slice(&[0x01, 0x00, 0x00, 0xFF, 0xFF]);
    }

    let mut offset = 0;
    while offset < data.len() {
        let remaining = data.len() - offset;
        let block_len = remaining.min(65_535);
        let is_final = offset + block_len >= data.len();
        out.push(if is_final { 0x01 } else { 0x00 });
        let len = block_len as u16;
        out.extend_from_slice(&len.to_le_bytes());
        out.extend_from_slice(&(!len).to_le_bytes());
        out.extend_from_slice(&data[offset..offset + block_len]);
        offset += block_len;
    }

    out.extend_from_slice(&adler32(data).to_be_bytes());
    out
}

fn adler32(data: &[u8]) -> u32 {
    const MOD: u32 = 65_521;
    let mut a: u32 = 1;
    let mut b: u32 = 0;
    for &byte in data {
        a = (a + byte as u32) % MOD;
        b = (b + a) % MOD;
    }
    (b << 16) | a
}

struct Crc32 {
    table: [u32; 256],
    state: u32,
}

impl Crc32 {
    fn new() -> Self {
        let mut table = [0u32; 256];
        for (index, entry) in table.iter_mut().enumerate() {
            let mut value = index as u32;
            for _ in 0..8 {
                value = if value & 1 != 0 {
                    0xEDB8_8320 ^ (value >> 1)
                } else {
                    value >> 1
                };
            }
            *entry = value;
        }
        Self {
            table,
            state: 0xFFFF_FFFF,
        }
    }

    fn update(&mut self, data: &[u8]) {
        for &byte in data {
            let index = ((self.state ^ byte as u32) & 0xFF) as usize;
            self.state = self.table[index] ^ (self.state >> 8);
        }
    }

    fn finish(self) -> u32 {
        self.state ^ 0xFFFF_FFFF
    }
}

/// Writes a PNG file containing `pixels` and returns the byte length written.
pub fn write_png_file(
    path: impl AsRef<Path>,
    width: u32,
    height: u32,
    pixels: &[u8],
) -> Result<usize, HeadlessError> {
    let png = encode_png_rgba(width, height, pixels);
    std::fs::write(path, &png)?;
    Ok(png.len())
}

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

    #[test]
    fn adler32_matches_reference_values() {
        let _runtime_session = crate::RuntimeSession::new();
        let _runtime_scope = _runtime_session.enter();
        assert_eq!(adler32(b""), 1);
        assert_eq!(adler32(b"Wikipedia"), 0x11E6_0398);
    }

    #[test]
    fn crc32_matches_reference_value() {
        let _runtime_session = crate::RuntimeSession::new();
        let _runtime_scope = _runtime_session.enter();
        let mut crc = Crc32::new();
        crc.update(b"123456789");
        assert_eq!(crc.finish(), 0xCBF4_3926);
    }

    #[test]
    fn png_encoder_emits_valid_structure() {
        let _runtime_session = crate::RuntimeSession::new();
        let _runtime_scope = _runtime_session.enter();
        let width = 2;
        let height = 1;
        let pixels = vec![255, 0, 0, 255, 0, 255, 0, 255];
        let png = encode_png_rgba(width, height, &pixels);

        assert_eq!(&png[..8], &[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]);
        assert_eq!(&png[12..16], b"IHDR");
        assert_eq!(&png[16..20], &2u32.to_be_bytes());
        assert_eq!(&png[20..24], &1u32.to_be_bytes());
        assert_eq!(png[png.len() - 8..png.len() - 4], *b"IEND");
        assert!(png.windows(4).any(|window| window == b"IDAT"));
    }
}

#[cfg(test)]
#[path = "headless_protocol_tests.rs"]
mod protocol_tests;