document-session-api 0.1.0

Engine-facing document contracts: retained session traits, the accessibility projection, document capabilities, page capture, and the engine-id namespace. The half of inker an engine implements.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
// Copyright 2026 Mark Alan Boykin
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0

//! Accessibility contract — the invariant every content surface declares about
//! what it can expose to the accessibility tree, plus the renderer-neutral
//! document projection that carries those semantics to a host.
//!
//! Adopted from the donor `graphshell` `SUBSYSTEM_ACCESSIBILITY.md` (per the
//! [docs harvest](../../../../design_docs/mere_docs/research/2026-05-27_graphshell_docs_full_harvest.md)
//! §1 and the [adoption roadmap](../../../../design_docs/mere_docs/implementation_strategy/2026-05-27_adoption_roadmap.md)
//! R0). This is the **contract** (the rule), not the full a11y implementation;
//! the host's AccessKit bridge (platen domains → uxtree) consumes it when the
//! a11y slice lands.
//!
//! ## The three invariants
//!
//! 1. **Capability-declaration** — every engine/surface declares its
//!    [`A11yCapability`] in *one* place (`a11y_capability` /
//!    `a11y_capability`). The host never guesses a
//!    surface's accessibility from its kind; it reads the declaration.
//! 2. **Non-silent-degradation** — a surface that cannot expose its content
//!    *must* declare a lower capability ([`A11yCapability::Partial`] /
//!    [`A11yCapability::Opaque`]). It must never present as [`A11yCapability::Full`]
//!    while silently dropping semantics. Degradation is *declared*, never silent —
//!    so the host can surface "you can't inspect inside this" honestly (cf. the
//!    [scrying DOM-bridge brief](../../../../genet/docs/2026-05-26_scrying_dom_bridge.md),
//!    which lifts a WebView tile from `Opaque` toward `Partial`).
//! 3. **Cross-surface-parity** — every engine speaks this *one* vocabulary, so
//!    the host treats accessibility uniformly regardless of which engine backs a
//!    tile (a nematic document, a Genet page, a scrying WebView).

/// Optional platform spelling bridge; the default contract remains renderer-neutral.
#[cfg(feature = "accesskit")]
mod accesskit_roles;
#[cfg(feature = "accesskit")]
pub use accesskit_roles::{accesskit_aria_role, accesskit_role_token};

use serde::{Deserialize, Serialize};

/// Stable, document-local semantic identity.
///
/// An engine retains this identity for the same semantic object while a
/// session is live. Hosts must namespace it with their own tile/session
/// identity before lowering it into a global accessibility tree.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[repr(transparent)]
pub struct DocumentA11yNodeId(u64);

impl DocumentA11yNodeId {
    /// Creates an engine-local identity. The numeric value has no host-global
    /// meaning and is never an AccessKit node id.
    pub const fn new(value: u64) -> Self {
        Self(value)
    }

    /// Returns the engine-local identity for storage or deterministic tests.
    pub const fn get(self) -> u64 {
        self.0
    }
}

/// A point in the final, current document-session viewport coordinate space.
///
/// Engines apply their own document zoom before returning this value. Hosts
/// may place it directly in their viewport transform, but retain ownership of
/// any outer tile transform.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct DocumentA11yPoint {
    pub x: f32,
    pub y: f32,
}

/// Bounds in the final, current document-session viewport coordinate space.
///
/// Engines apply their own document zoom before returning these bounds.
/// Structural nodes may have no bounds. A host must not invent geometry for
/// those nodes from a differently timed paint frame.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct DocumentA11yBounds {
    pub x: f32,
    pub y: f32,
    pub width: f32,
    pub height: f32,
}

/// Semantic role vocabulary shared by retained document engines.
///
/// This deliberately describes document semantics rather than mirroring any
/// particular platform accessibility API. A host owns its platform lowering.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yRole {
    Window,
    Document,
    Article,
    Region,
    Group,
    Navigation,
    Main,
    Heading { level: u8 },
    Paragraph,
    StaticText,
    Link,
    Button,
    TextField,
    CheckBox,
    RadioButton,
    RadioGroup,
    Switch,
    ComboBox,
    List,
    ListItem,
    ListBox,
    ListBoxOption,
    Table,
    Row,
    Cell,
    Image,
    Form,
    Dialog,
    Alert,
    Menu,
    MenuBar,
    MenuItem,
    MenuItemCheckBox,
    MenuItemRadio,
    TabList,
    Tab,
    TabPanel,
    Tree,
    TreeItem,
    Slider,
    SpinButton,
    Splitter,
    Toolbar,
    ProgressIndicator,
    Label,
    Status,
    Log,
    Note,
    Unknown,
}

/// Announcement priority for live regions.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yLive {
    Off,
    Polite,
    Assertive,
}

/// The three-value state used by switch and toggle controls.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yToggled {
    Off,
    On,
    Mixed,
}

/// The primary direction of an oriented control or container.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yOrientation {
    Horizontal,
    Vertical,
}

/// The kind of popup a semantic node can present.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yHasPopup {
    Menu,
    ListBox,
    Tree,
    Grid,
    Dialog,
}

/// Platform-neutral state for one semantic node.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DocumentA11yState {
    pub disabled: bool,
    pub hidden: bool,
    pub selected: Option<bool>,
    pub expanded: Option<bool>,
    pub checked: Option<bool>,
    pub toggled: Option<DocumentA11yToggled>,
    pub focused: bool,
    pub editable: bool,
    pub multiline: bool,
    pub read_only: bool,
    pub required: bool,
    /// `None` preserves the absence of a live-region declaration; `Off` is
    /// an explicit declaration with distinct source semantics.
    pub live: Option<DocumentA11yLive>,
    pub orientation: Option<DocumentA11yOrientation>,
    pub has_popup: Option<DocumentA11yHasPopup>,
}

/// An action the engine advertises for a semantic node.
///
/// `Click` remains a pointer action: hosts obtain a fresh
/// [`DocumentA11yClickTarget`] and drive their ordinary pointer path. The
/// remaining actions dispatch through [`crate::DocumentSession`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yAction {
    Click,
    Focus,
    SetValue,
    ScrollIntoView,
    Increment,
    Decrement,
}

/// Data carried by an accessibility action request.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11yActionData {
    Value(String),
}

/// A host request addressed to one local semantic node.
///
/// Engines must revalidate `revision`, `target`, and that the requested
/// action is advertised by their current projection before mutating state.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DocumentA11yActionRequest {
    pub revision: u64,
    pub target: DocumentA11yNodeId,
    pub action: DocumentA11yAction,
    pub data: Option<DocumentA11yActionData>,
}

/// A current, revalidated point at which a host may issue its ordinary click
/// path. `revision` makes a stale geometry observation detectable.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct DocumentA11yClickTarget {
    pub revision: u64,
    pub point: DocumentA11yPoint,
}

/// One semantic node in a renderer-neutral document projection.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct DocumentA11yNode {
    pub id: DocumentA11yNodeId,
    pub parent: Option<DocumentA11yNodeId>,
    /// Ordered local child identities. This is authoritative for traversal;
    /// `parent` is retained for efficient reverse lookup and validation.
    pub children: Vec<DocumentA11yNodeId>,
    pub role: DocumentA11yRole,
    pub name: Option<String>,
    /// Supplemental text, separate from the control name and current value.
    #[serde(default)]
    pub description: Option<String>,
    pub value: Option<String>,
    pub numeric_value: Option<f64>,
    pub numeric_minimum: Option<f64>,
    pub numeric_maximum: Option<f64>,
    pub bounds: Option<DocumentA11yBounds>,
    pub state: DocumentA11yState,
    pub actions: Vec<DocumentA11yAction>,
}

/// Why a projection cannot claim complete semantic coverage.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum DocumentA11ySupportError {
    MissingLimitation { capability: A11yCapability },
}

impl std::fmt::Display for DocumentA11ySupportError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::MissingLimitation { capability } => {
                write!(
                    f,
                    "{capability:?} accessibility support requires a limitation"
                )
            },
        }
    }
}

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

/// Coverage and explicit limitations of an accessibility projection.
///
/// A partial projection cannot be constructed without a non-blank limitation,
/// so hosts can describe its aperture honestly. The projection's support is
/// the live source of truth; an engine's registration-time capability remains
/// only a pre-spawn declaration.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DocumentA11ySupport {
    capability: A11yCapability,
    limitations: Vec<String>,
}

impl DocumentA11ySupport {
    pub fn new(
        capability: A11yCapability,
        limitations: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, DocumentA11ySupportError> {
        let limitations = limitations
            .into_iter()
            .map(Into::into)
            .filter(|limitation: &String| !limitation.trim().is_empty())
            .collect::<Vec<_>>();
        if capability == A11yCapability::Partial && limitations.is_empty() {
            return Err(DocumentA11ySupportError::MissingLimitation { capability });
        }
        Ok(Self {
            capability,
            limitations,
        })
    }

    pub fn capability(&self) -> A11yCapability {
        self.capability
    }

    pub fn limitations(&self) -> &[String] {
        &self.limitations
    }
}

/// Renderer-neutral semantic snapshot of the current retained document.
///
/// `revision` increases whenever geometry, state, or actions observable
/// through this projection change. A semantic object's local ID remains stable
/// across revisions for the lifetime of that object; the revision instead
/// scopes an observation and its action requests, allowing an engine to reject
/// stale host observations.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct DocumentA11yProjection {
    revision: u64,
    support: DocumentA11ySupport,
    root: DocumentA11yNodeId,
    nodes: Vec<DocumentA11yNode>,
}

impl DocumentA11yProjection {
    pub fn new(
        revision: u64,
        support: DocumentA11ySupport,
        root: DocumentA11yNodeId,
        nodes: Vec<DocumentA11yNode>,
    ) -> Self {
        Self {
            revision,
            support,
            root,
            nodes,
        }
    }

    pub const fn revision(&self) -> u64 {
        self.revision
    }

    pub fn support(&self) -> &DocumentA11ySupport {
        &self.support
    }

    pub const fn root(&self) -> DocumentA11yNodeId {
        self.root
    }

    pub fn nodes(&self) -> &[DocumentA11yNode] {
        &self.nodes
    }

    pub fn node(&self, id: DocumentA11yNodeId) -> Option<&DocumentA11yNode> {
        self.nodes.iter().find(|node| node.id == id)
    }
}

/// What a content surface can expose to the accessibility tree. The single
/// vocabulary all engines/surfaces speak (invariant 3). Ordered worst-to-best
/// so capability can be compared / clamped.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub enum A11yCapability {
    /// No semantic content the host can expose — a raw GPU surface or an opaque
    /// system WebView. The host surfaces this honestly (a labelled region with
    /// "contents not inspectable"), never as if it were [`Self::Full`]. Default
    /// for `SurfaceEngine` (frame-streaming surfaces are opaque until
    /// they bridge their content).
    Opaque,
    /// Some structure available — e.g. a bridged WebView exposing a DOM
    /// projection (links / headings / text) but not full ARIA, or a
    /// partially-modelled document.
    Partial,
    /// A complete semantic tree (headings, links, roles, text). Default for
    /// document `Engine`s: their `EngineDocument` blocks *are*
    /// the semantic content, so they are accessible by construction.
    Full,
}

impl A11yCapability {
    /// Whether the host can build any semantic accessibility nodes from this
    /// surface (everything but [`Self::Opaque`]).
    pub fn is_inspectable(self) -> bool {
        self != Self::Opaque
    }
}

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

    fn document_node(id: u64) -> DocumentA11yNode {
        DocumentA11yNode {
            id: DocumentA11yNodeId::new(id),
            parent: None,
            children: Vec::new(),
            role: DocumentA11yRole::Document,
            description: None,
            name: Some("Example".into()),
            value: None,
            numeric_value: None,
            numeric_minimum: None,
            numeric_maximum: None,
            bounds: Some(DocumentA11yBounds {
                x: 0.0,
                y: 0.0,
                width: 800.0,
                height: 600.0,
            }),
            state: DocumentA11yState::default(),
            actions: vec![DocumentA11yAction::Focus],
        }
    }

    #[test]
    fn partial_support_requires_a_specific_limitation() {
        assert_eq!(
            DocumentA11ySupport::new(A11yCapability::Partial, ["", "   "])
                .expect_err("partial support must explain its aperture"),
            DocumentA11ySupportError::MissingLimitation {
                capability: A11yCapability::Partial
            }
        );

        let support = DocumentA11ySupport::new(
            A11yCapability::Partial,
            ["visible links are exposed; activation is unavailable"],
        )
        .expect("specific limitation makes partial support honest");
        assert_eq!(support.capability(), A11yCapability::Partial);
        assert_eq!(support.limitations().len(), 1);
    }

    #[test]
    fn projection_carries_stable_local_ids_revision_and_semantics() {
        let root = DocumentA11yNodeId::new(41);
        let projection = DocumentA11yProjection::new(
            9,
            DocumentA11ySupport::new(A11yCapability::Full, std::iter::empty::<String>())
                .expect("full support needs no limitation"),
            root,
            vec![document_node(root.get())],
        );

        assert_eq!(projection.revision(), 9);
        assert_eq!(projection.root(), root);
        let node = projection
            .node(root)
            .expect("local root remains addressable");
        assert_eq!(node.role, DocumentA11yRole::Document);
        assert_eq!(node.name.as_deref(), Some("Example"));
        assert_eq!(node.state.live, None, "absence differs from explicit Off");
        assert_eq!(node.actions, vec![DocumentA11yAction::Focus]);
        assert_eq!(projection.support().capability(), A11yCapability::Full);
    }
}