Skip to main content

document_session_api/
page_capture.rs

1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! Host-owned requests and engine-reported results for page capture.
8//!
9//! A host mints the request id and records its own navigation, node, and
10//! requested-scale provenance beside it. Engines report only facts they
11//! actually know about the captured viewport and applied scale.
12
13use serde::{Deserialize, Serialize};
14
15/// A host-minted id for one capture request on one document surface.
16///
17/// The id is scoped to its surface. Hosts driving several surfaces retain the
18/// surface identity beside this value.
19#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
20pub struct PageCaptureRequestId(u64);
21
22impl PageCaptureRequestId {
23    pub const fn new(value: u64) -> Self {
24        Self(value)
25    }
26
27    pub const fn get(self) -> u64 {
28        self.0
29    }
30}
31
32/// The portion of a page an engine is asked to capture.
33#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
34pub enum PageCaptureScope {
35    /// The visible viewport at the instant the engine accepts the request.
36    Viewport,
37}
38
39/// A page-capture request. Its id is minted by the host, never the engine.
40#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
41pub struct PageCaptureRequest {
42    pub id: PageCaptureRequestId,
43    pub scope: PageCaptureScope,
44}
45
46impl PageCaptureRequest {
47    pub const fn viewport(id: PageCaptureRequestId) -> Self {
48        Self {
49            id,
50            scope: PageCaptureScope::Viewport,
51        }
52    }
53}
54
55/// Coordinates in the document's CSS-pixel space.
56#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
57pub struct CssPoint {
58    pub x: f32,
59    pub y: f32,
60}
61
62/// An extent in CSS pixels.
63#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
64pub struct CssExtent {
65    pub width: f32,
66    pub height: f32,
67}
68
69/// Facts about the captured viewport, as reported by the engine.
70///
71/// CSS facts are optional because a black-box engine may produce pixels
72/// without exposing its scroll position or CSS viewport. Output dimensions are
73/// always required and are physical pixels in the returned image.
74#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
75pub struct PageCaptureViewportFacts {
76    pub css_scroll_origin: Option<CssPoint>,
77    pub css_viewport_extent: Option<CssExtent>,
78    pub output_width_pixels: u32,
79    pub output_height_pixels: u32,
80}
81
82impl PageCaptureViewportFacts {
83    /// Builds an honest report for an engine that knows output dimensions but
84    /// cannot observe CSS scroll or viewport data.
85    pub const fn unknown_css(output_width_pixels: u32, output_height_pixels: u32) -> Self {
86        Self {
87            css_scroll_origin: None,
88            css_viewport_extent: None,
89            output_width_pixels,
90            output_height_pixels,
91        }
92    }
93}
94
95/// The admitted P1 image representations.
96#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
97pub enum PageCaptureImageArtifact {
98    Png(Vec<u8>),
99}
100
101/// A successful engine-reported page capture.
102#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
103pub struct PageCaptureOutput {
104    /// The scope the engine actually produced. It repeats the request instead
105    /// of asking hosts to infer result semantics from a pending record.
106    pub scope: PageCaptureScope,
107    pub image: PageCaptureImageArtifact,
108    pub viewport: PageCaptureViewportFacts,
109    /// The engine's actual page scale, when it can observe it. This is not the
110    /// host's requested scale, which belongs in host provenance.
111    pub applied_page_scale: Option<f32>,
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117
118    #[test]
119    fn viewport_facts_keep_unobserved_css_explicit() {
120        let facts = PageCaptureViewportFacts::unknown_css(1280, 720);
121        assert_eq!(facts.css_scroll_origin, None);
122        assert_eq!(facts.css_viewport_extent, None);
123        assert_eq!(facts.output_width_pixels, 1280);
124        assert_eq!(facts.output_height_pixels, 720);
125    }
126
127    #[test]
128    fn viewport_request_keeps_the_host_minted_id() {
129        let id = PageCaptureRequestId::new(42);
130        let request = PageCaptureRequest::viewport(id);
131        assert_eq!(request.id, id);
132        assert_eq!(request.scope, PageCaptureScope::Viewport);
133    }
134}