Skip to main content

document_session_api/
capabilities.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//! Shared document-control capability vocabulary.
8//!
9//! Retained [`crate::DocumentSession`]s and hosted `WebSurface`s
10//! expose the same document-facing controls. Backend-specific surface features
11//! stay in `surface_engine`; this module deliberately names only the controls a
12//! browser can present uniformly for either kind of document.
13
14use serde::{Deserialize, Serialize};
15
16/// Availability of one capability.
17///
18/// `Partial` must describe the limit. `Unsupported` must say why a consumer
19/// cannot use the control. This keeps product UI from treating a merely present
20/// method as a working feature.
21#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
22pub enum CapabilityStatus {
23    Supported,
24    Unsupported { reason: String },
25    Partial { detail: String },
26}
27
28impl CapabilityStatus {
29    pub fn unsupported(reason: impl Into<String>) -> Self {
30        Self::Unsupported {
31            reason: reason.into(),
32        }
33    }
34}
35
36/// Document-facing controls available from a retained session or hosted page.
37#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
38pub struct DocumentCapabilities {
39    /// Text find, including stepping and clearing the current query.
40    pub find_in_page: CapabilityStatus,
41    /// Changing the page's own zoom, rather than scaling its host tile.
42    pub page_zoom: CapabilityStatus,
43    /// Capturing the current rendered page as an image.
44    pub page_capture: CapabilityStatus,
45    /// Reload/stop/history controls or their retained-session equivalent.
46    pub navigation: CapabilityStatus,
47}
48
49impl Default for DocumentCapabilities {
50    fn default() -> Self {
51        Self {
52            find_in_page: CapabilityStatus::unsupported("find in page is not wired"),
53            page_zoom: CapabilityStatus::unsupported("page zoom is not wired"),
54            page_capture: CapabilityStatus::unsupported("page capture is not wired"),
55            navigation: CapabilityStatus::unsupported("document navigation controls are not wired"),
56        }
57    }
58}
59
60/// Compatibility spelling for document-facing capability consumers.
61///
62/// New generic capability APIs should use [`CapabilityStatus`].
63pub type DocumentCapabilityStatus = CapabilityStatus;
64
65/// Compatibility spelling for existing web-surface capability consumers.
66pub type WebFeatureStatus = CapabilityStatus;
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71
72    #[test]
73    fn defaults_are_explicitly_unavailable() {
74        let caps = DocumentCapabilities::default();
75        assert!(matches!(
76            caps.find_in_page,
77            CapabilityStatus::Unsupported { .. }
78        ));
79        assert!(matches!(
80            caps.page_zoom,
81            CapabilityStatus::Unsupported { .. }
82        ));
83        assert!(matches!(
84            caps.page_capture,
85            CapabilityStatus::Unsupported { .. }
86        ));
87        assert!(matches!(
88            caps.navigation,
89            CapabilityStatus::Unsupported { .. }
90        ));
91    }
92
93    #[test]
94    fn legacy_web_status_spelling_is_the_shared_type() {
95        let status: WebFeatureStatus = CapabilityStatus::Supported;
96        assert_eq!(status, CapabilityStatus::Supported);
97    }
98}