Skip to main content

whisker_engine/
surface.rs

1//! Surface-level orchestration of retained scene and layout state.
2
3use std::{collections::HashMap, error::Error, fmt, rc::Rc};
4
5use whisker_layout::{IntrinsicMeasurer, LayoutError, LayoutSize, LayoutSnapshot, LayoutTree};
6use whisker_protocol::{
7    Accessibility, ApplyResult, BackgroundLayer, BoxPaint, CommandId, Cursor, CursorKeyword,
8    ElementTypeId, FramePacket, HitTestBehavior, InputPoint, LayoutGeometry, MeasurementMetrics,
9    MeasurementReady, MeasurementResponse, MeasurementSpec, NodeId, PointerId, PropertyId,
10    SurfaceId, TextContent, WhiskerValue,
11};
12use whisker_style::{
13    ComputedLayoutStyle, ComputedStyle, ComputedTransformStyle, CursorValue, PointerEventsValue,
14    PropertyImpactSet,
15};
16
17#[cfg(test)]
18use crate::radial_gradient::absolute_length;
19use crate::radial_gradient::{
20    RadialBackgroundSource, canonicalize as canonicalize_radial_backgrounds,
21    sources as radial_background_sources,
22};
23use crate::{
24    DeferredMeasurementApply, FrameSink, LayoutProgress, MeasurementApply, MeasurementError,
25    PlainTextInput, Scene, SceneError, SceneNode, lower_paint, lower_plain_text, lower_text_style,
26    lower_transform, measurement::MeasurementCoordinator,
27};
28
29const fn lower_hit_test(value: PointerEventsValue) -> HitTestBehavior {
30    match value {
31        PointerEventsValue::Auto => HitTestBehavior::Auto,
32        PointerEventsValue::None => HitTestBehavior::None,
33    }
34}
35
36fn lower_cursor(value: CursorValue) -> Cursor {
37    let fallback = match value {
38        CursorValue::Auto => CursorKeyword::Auto,
39        CursorValue::Default => CursorKeyword::Default,
40        CursorValue::None => CursorKeyword::None,
41        CursorValue::ContextMenu => CursorKeyword::ContextMenu,
42        CursorValue::Help => CursorKeyword::Help,
43        CursorValue::Pointer => CursorKeyword::Pointer,
44        CursorValue::Progress => CursorKeyword::Progress,
45        CursorValue::Wait => CursorKeyword::Wait,
46        CursorValue::Cell => CursorKeyword::Cell,
47        CursorValue::Crosshair => CursorKeyword::Crosshair,
48        CursorValue::Text => CursorKeyword::Text,
49        CursorValue::VerticalText => CursorKeyword::VerticalText,
50        CursorValue::Alias => CursorKeyword::Alias,
51        CursorValue::Copy => CursorKeyword::Copy,
52        CursorValue::Move => CursorKeyword::Move,
53        CursorValue::NoDrop => CursorKeyword::NoDrop,
54        CursorValue::NotAllowed => CursorKeyword::NotAllowed,
55        CursorValue::Grab => CursorKeyword::Grab,
56        CursorValue::Grabbing => CursorKeyword::Grabbing,
57        CursorValue::ColResize => CursorKeyword::ColResize,
58        CursorValue::RowResize => CursorKeyword::RowResize,
59        CursorValue::NResize => CursorKeyword::NResize,
60        CursorValue::EResize => CursorKeyword::EResize,
61        CursorValue::SResize => CursorKeyword::SResize,
62        CursorValue::WResize => CursorKeyword::WResize,
63        CursorValue::NeResize => CursorKeyword::NeResize,
64        CursorValue::NwResize => CursorKeyword::NwResize,
65        CursorValue::SeResize => CursorKeyword::SeResize,
66        CursorValue::SwResize => CursorKeyword::SwResize,
67        CursorValue::EwResize => CursorKeyword::EwResize,
68        CursorValue::NsResize => CursorKeyword::NsResize,
69        CursorValue::NeswResize => CursorKeyword::NeswResize,
70        CursorValue::NwseResize => CursorKeyword::NwseResize,
71        CursorValue::ZoomIn => CursorKeyword::ZoomIn,
72        CursorValue::ZoomOut => CursorKeyword::ZoomOut,
73    };
74    Cursor {
75        resources: Vec::new(),
76        fallback,
77    }
78}
79
80/// Result of requesting one layout pass.
81#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
82pub struct LayoutUpdate {
83    recomputed: bool,
84    changed_nodes: usize,
85}
86
87impl LayoutUpdate {
88    fn computed(changed_nodes: usize) -> Self {
89        Self {
90            recomputed: true,
91            changed_nodes,
92        }
93    }
94
95    /// Returns whether Taffy ran for this request.
96    pub const fn recomputed(self) -> bool {
97        self.recomputed
98    }
99
100    /// Returns how many scene nodes received changed geometry.
101    pub const fn changed_nodes(self) -> usize {
102        self.changed_nodes
103    }
104}
105
106/// Failure while coordinating retained layout and scene state.
107#[derive(Clone, Debug, PartialEq)]
108pub enum SurfaceError {
109    /// The retained scene rejected an operation.
110    Scene(SceneError),
111    /// The retained layout tree rejected an operation or computation.
112    Layout(LayoutError),
113    /// A layout snapshot named a node absent from the paired scene.
114    SceneLayoutMismatch {
115        /// Node present only in the layout result.
116        node: NodeId,
117    },
118    /// A layout backend produced non-finite geometry.
119    InvalidLayoutOutput {
120        /// Node whose rectangle was invalid.
121        node: NodeId,
122    },
123    /// A computed transform produced a non-finite matrix after box resolution.
124    InvalidTransformOutput {
125        /// Node whose transform could not be represented.
126        node: NodeId,
127    },
128    /// Intrinsic measurement state or a Host response was invalid.
129    Measurement(MeasurementError),
130}
131
132impl fmt::Display for SurfaceError {
133    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
134        write!(formatter, "Whisker surface error: {self:?}")
135    }
136}
137
138impl Error for SurfaceError {
139    fn source(&self) -> Option<&(dyn Error + 'static)> {
140        match self {
141            Self::Scene(error) => Some(error),
142            Self::Layout(error) => Some(error),
143            Self::Measurement(error) => Some(error),
144            Self::SceneLayoutMismatch { .. }
145            | Self::InvalidLayoutOutput { .. }
146            | Self::InvalidTransformOutput { .. } => None,
147        }
148    }
149}
150
151impl From<SceneError> for SurfaceError {
152    fn from(error: SceneError) -> Self {
153        Self::Scene(error)
154    }
155}
156
157impl From<LayoutError> for SurfaceError {
158    fn from(error: LayoutError) -> Self {
159        Self::Layout(error)
160    }
161}
162
163impl From<MeasurementError> for SurfaceError {
164    fn from(error: MeasurementError) -> Self {
165        Self::Measurement(error)
166    }
167}
168
169/// Failure while presenting one prepared transaction to a Host.
170#[derive(Clone, Debug, PartialEq)]
171pub enum SurfacePresentError<SinkError> {
172    /// Scene preparation or revision bookkeeping failed.
173    Surface(SurfaceError),
174    /// The Host rejected the call before accepting the transaction.
175    Sink(SinkError),
176}
177
178impl<SinkError: fmt::Debug> fmt::Display for SurfacePresentError<SinkError> {
179    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
180        write!(formatter, "Whisker surface presentation error: {self:?}")
181    }
182}
183
184impl<SinkError: Error + 'static> Error for SurfacePresentError<SinkError> {
185    fn source(&self) -> Option<&(dyn Error + 'static)> {
186        match self {
187            Self::Surface(error) => Some(error),
188            Self::Sink(error) => Some(error),
189        }
190    }
191}
192
193#[derive(Clone, Copy, Debug, PartialEq)]
194struct LayoutInputs {
195    root: NodeId,
196    viewport: LayoutSize,
197}
198
199/// Host-independent rendering pipeline for one Whisker surface.
200///
201/// This is the sole mutable owner of the paired [`Scene`] and [`LayoutTree`].
202/// Structural operations update both retained trees, while a successful layout
203/// pass projects only changed rectangles into the scene journal. Clones share
204/// unchanged state and copy each subsystem only when it is mutated.
205#[derive(Clone, Debug)]
206pub struct SurfaceEngine {
207    scene: Scene,
208    layout: Rc<LayoutTree>,
209    last_layout: Option<Rc<LayoutSnapshot>>,
210    last_inputs: Option<LayoutInputs>,
211    layout_dirty: bool,
212    layout_provisional: bool,
213    transforms: Rc<HashMap<NodeId, ComputedTransformStyle>>,
214    radial_backgrounds: Rc<HashMap<NodeId, Vec<RadialBackgroundSource>>>,
215    paragraph_visibility: Rc<crate::paragraph_visibility::ParagraphVisibility>,
216    measurements: Rc<MeasurementCoordinator>,
217}
218
219impl SurfaceEngine {
220    pub(crate) fn synchronize_prepared_content<P: crate::MeasurementProvider>(
221        &self,
222        provider: &mut P,
223    ) {
224        let (revision, mut retained) = self.measurements.retained_content();
225        provider.retain_prepared_content(self.surface(), revision, &mut retained);
226    }
227
228    /// Creates an empty surface pipeline.
229    pub fn new(surface: SurfaceId) -> Self {
230        Self::with_protocol(surface, whisker_protocol::ProtocolVersion::CURRENT)
231    }
232
233    /// Creates an empty pipeline using the protocol selected with its Host.
234    pub fn with_protocol(surface: SurfaceId, protocol: whisker_protocol::ProtocolVersion) -> Self {
235        Self {
236            scene: Scene::with_protocol(surface, protocol),
237            layout: Rc::new(LayoutTree::new()),
238            last_layout: None,
239            last_inputs: None,
240            layout_dirty: false,
241            layout_provisional: false,
242            transforms: Rc::new(HashMap::new()),
243            radial_backgrounds: Rc::new(HashMap::new()),
244            paragraph_visibility: Rc::default(),
245            measurements: Rc::new(MeasurementCoordinator::default()),
246        }
247    }
248
249    /// Returns this pipeline's surface identifier.
250    pub const fn surface(&self) -> SurfaceId {
251        self.scene.surface()
252    }
253
254    /// Returns the retained scene without allowing structural mutation.
255    pub const fn scene(&self) -> &Scene {
256        &self.scene
257    }
258
259    /// Returns the retained layout tree without allowing structural mutation.
260    pub fn layout_tree(&self) -> &LayoutTree {
261        &self.layout
262    }
263
264    /// Returns the most recent successful layout snapshot.
265    pub fn last_layout(&self) -> Option<&LayoutSnapshot> {
266        self.last_layout.as_deref()
267    }
268
269    /// Returns whether retained inputs require another layout pass.
270    pub const fn needs_layout(&self) -> bool {
271        self.layout_dirty
272    }
273
274    /// Returns whether the scene has a snapshot, mutation, command, or retry.
275    pub fn has_pending_work(&self) -> bool {
276        self.scene.has_pending_work()
277    }
278
279    /// Returns a retained scene node when it is live.
280    pub fn node(&self, node: NodeId) -> Option<&SceneNode> {
281        self.scene.node(node)
282    }
283
284    /// Finds the visually topmost retained node at a surface-space point.
285    pub fn hit_test(
286        &self,
287        root: NodeId,
288        point: InputPoint,
289    ) -> Result<Option<NodeId>, SurfaceError> {
290        self.scene
291            .hit_test(root, point)
292            .map_err(SurfaceError::Scene)
293    }
294
295    /// Synchronizes one native scroll container's transient logical offset.
296    ///
297    /// This state participates only in Rust hit testing. It does not dirty
298    /// layout or echo a frame operation back to the Host.
299    pub fn update_host_scroll_offset(
300        &mut self,
301        node: NodeId,
302        offset: [f32; 2],
303    ) -> Result<(), SurfaceError> {
304        self.scene
305            .update_host_scroll_offset(node, offset)
306            .map_err(SurfaceError::Scene)
307    }
308
309    /// Captures a pointer stream for a node.
310    pub fn set_pointer_capture(
311        &mut self,
312        node: NodeId,
313        pointer: PointerId,
314    ) -> Result<(), SurfaceError> {
315        self.scene
316            .set_pointer_capture(node, pointer)
317            .map_err(SurfaceError::Scene)
318    }
319
320    /// Releases a pointer stream previously captured by a node.
321    pub fn release_pointer_capture(
322        &mut self,
323        node: NodeId,
324        pointer: PointerId,
325    ) -> Result<(), SurfaceError> {
326        self.scene
327            .release_pointer_capture(node, pointer)
328            .map_err(SurfaceError::Scene)
329    }
330
331    /// Releases every captured pointer.
332    pub fn release_pointer_captures(&mut self) -> Result<(), SurfaceError> {
333        self.scene
334            .release_pointer_captures()
335            .map_err(SurfaceError::Scene)
336    }
337
338    /// Returns the node currently retaining one pointer capture.
339    pub fn pointer_capture_target(&self, pointer: PointerId) -> Option<NodeId> {
340        self.scene.pointer_capture_target(pointer)
341    }
342
343    /// Replaces one node's event subscription mask.
344    pub fn set_event_mask(&mut self, node: NodeId, mask: u64) -> Result<(), SurfaceError> {
345        self.scene
346            .set_event_mask(node, mask)
347            .map_err(SurfaceError::Scene)
348    }
349
350    /// Replaces one node's common accessibility semantics.
351    pub fn set_accessibility(
352        &mut self,
353        node: NodeId,
354        accessibility: Accessibility,
355    ) -> Result<(), SurfaceError> {
356        let accessibility = if self.paragraph_visibility.contains(node) {
357            Rc::make_mut(&mut self.paragraph_visibility).accessibility(node, accessibility)
358        } else {
359            accessibility
360        };
361        self.scene
362            .set_accessibility(node, accessibility)
363            .map_err(SurfaceError::Scene)
364    }
365
366    /// Sets one typed element property in the retained scene.
367    pub fn set_property(
368        &mut self,
369        node: NodeId,
370        property: PropertyId,
371        value: WhiskerValue,
372    ) -> Result<(), SurfaceError> {
373        self.scene
374            .set_property(node, property, value)
375            .map_err(SurfaceError::Scene)
376    }
377
378    /// Clears one typed element property in the retained scene.
379    pub fn clear_property(
380        &mut self,
381        node: NodeId,
382        property: PropertyId,
383    ) -> Result<(), SurfaceError> {
384        self.scene
385            .clear_property(node, property)
386            .map_err(SurfaceError::Scene)
387    }
388
389    /// Queues one typed element command after preceding visual mutations.
390    pub fn invoke_command(
391        &mut self,
392        node: NodeId,
393        command: CommandId,
394        arguments: WhiskerValue,
395    ) -> Result<(), SurfaceError> {
396        self.scene
397            .invoke_command(node, command, arguments)
398            .map_err(SurfaceError::Scene)
399    }
400
401    /// Replaces one node's hit-test participation.
402    pub fn set_hit_test(
403        &mut self,
404        node: NodeId,
405        behavior: HitTestBehavior,
406    ) -> Result<(), SurfaceError> {
407        self.scene
408            .set_hit_test(node, behavior)
409            .map_err(SurfaceError::Scene)
410    }
411
412    /// Replaces one node's resolved pointing-device cursor.
413    pub fn set_cursor(&mut self, node: NodeId, cursor: Cursor) -> Result<(), SurfaceError> {
414        self.scene
415            .set_cursor(node, cursor)
416            .map_err(SurfaceError::Scene)
417    }
418
419    /// Replaces one node's already-resolved group opacity.
420    pub fn set_opacity(&mut self, node: NodeId, opacity: f32) -> Result<(), SurfaceError> {
421        self.scene
422            .set_opacity(node, opacity)
423            .map_err(SurfaceError::Scene)
424    }
425
426    /// Replaces one node's resolved background, border, and radius paint.
427    pub fn set_box_paint(&mut self, node: NodeId, paint: BoxPaint) -> Result<(), SurfaceError> {
428        self.scene
429            .set_box_paint(node, paint)
430            .map_err(SurfaceError::Scene)
431    }
432
433    /// Replaces one node's already-lowered text presentation.
434    ///
435    /// Runtime-owned paint animation uses this after intrinsic measurement is
436    /// complete; callers must preserve the retained payload and prepared
437    /// content when changing paint-only fields.
438    pub fn set_text_content(
439        &mut self,
440        node: NodeId,
441        content: TextContent,
442    ) -> Result<(), SurfaceError> {
443        self.scene
444            .set_text(node, content)
445            .map_err(SurfaceError::Scene)
446    }
447
448    /// Delivers resolved inherited text style to a native text-capable
449    /// element independently from plain-text child content.
450    pub fn set_text_style(
451        &mut self,
452        node: NodeId,
453        style: &ComputedStyle,
454    ) -> Result<(), SurfaceError> {
455        self.scene
456            .set_text_style(node, lower_text_style(style))
457            .map_err(SurfaceError::Scene)
458    }
459
460    /// Replaces an already-lowered native text-style snapshot. Runtime-owned
461    /// paint animation uses this without re-resolving inherited values.
462    pub fn set_text_style_snapshot(
463        &mut self,
464        node: NodeId,
465        style: whisker_protocol::TextStyleSnapshot,
466    ) -> Result<(), SurfaceError> {
467        self.scene
468            .set_text_style(node, style)
469            .map_err(SurfaceError::Scene)
470    }
471
472    /// Replaces one node's already-resolved transform matrix without changing
473    /// its computed transform target.
474    pub fn set_transform(
475        &mut self,
476        node: NodeId,
477        transform: whisker_protocol::Transform,
478    ) -> Result<(), SurfaceError> {
479        self.scene
480            .set_transform(node, transform)
481            .map_err(SurfaceError::Scene)
482    }
483
484    /// Creates one unattached node in both retained trees.
485    pub fn create_node(
486        &mut self,
487        element_type: ElementTypeId,
488        style: ComputedLayoutStyle,
489    ) -> Result<NodeId, SurfaceError> {
490        LayoutTree::validate_style(&style)?;
491        let node = self.scene.create_node(element_type)?;
492        Rc::make_mut(&mut self.layout)
493            .create_node(node, style)
494            .expect("a validated style and fresh scene ID must enter layout");
495        self.layout_dirty = true;
496        Ok(node)
497    }
498
499    /// Deletes a node and its complete subtree from both retained trees.
500    pub fn delete_node(&mut self, node: NodeId) -> Result<(), SurfaceError> {
501        let mut removed = Vec::new();
502        collect_scene_subtree(&self.scene, node, &mut removed)?;
503        self.scene.delete_node(node)?;
504        Rc::make_mut(&mut self.layout)
505            .remove_subtree(node)
506            .expect("scene and layout trees remain structurally synchronized");
507        for removed in removed {
508            Rc::make_mut(&mut self.transforms).remove(&removed);
509            Rc::make_mut(&mut self.radial_backgrounds).remove(&removed);
510            Rc::make_mut(&mut self.measurements).remove_node(removed);
511            if self.paragraph_visibility.contains(removed) {
512                Rc::make_mut(&mut self.paragraph_visibility).remove(removed);
513            }
514        }
515        self.layout_dirty = true;
516        Ok(())
517    }
518
519    /// Attaches an unattached child at an index in both retained trees.
520    pub fn insert_child(
521        &mut self,
522        parent: NodeId,
523        child: NodeId,
524        index: u32,
525    ) -> Result<(), SurfaceError> {
526        self.scene.insert_child(parent, child, index)?;
527        Rc::make_mut(&mut self.layout)
528            .reparent(child, parent, index as usize)
529            .expect("scene and layout trees remain structurally synchronized");
530        self.layout_dirty = true;
531        Ok(())
532    }
533
534    /// Detaches a direct child without deleting it.
535    pub fn remove_child(&mut self, parent: NodeId, child: NodeId) -> Result<(), SurfaceError> {
536        self.scene.remove_child(parent, child)?;
537        let children = self
538            .scene
539            .node(parent)
540            .expect("validated parent remains live")
541            .children()
542            .to_vec();
543        Rc::make_mut(&mut self.layout)
544            .set_children(parent, &children)
545            .expect("scene and layout trees remain structurally synchronized");
546        self.layout_dirty = true;
547        Ok(())
548    }
549
550    /// Moves a direct child within its current parent.
551    pub fn move_child(
552        &mut self,
553        parent: NodeId,
554        child: NodeId,
555        index: u32,
556    ) -> Result<(), SurfaceError> {
557        self.scene.move_child(parent, child, index)?;
558        Rc::make_mut(&mut self.layout)
559            .reparent(child, parent, index as usize)
560            .expect("scene and layout trees remain structurally synchronized");
561        self.layout_dirty = true;
562        Ok(())
563    }
564
565    /// Replaces a node's computed layout input and reports its impact.
566    pub fn update_layout_style(
567        &mut self,
568        node: NodeId,
569        style: ComputedLayoutStyle,
570    ) -> Result<PropertyImpactSet, SurfaceError> {
571        self.ensure_mutable()?;
572        if self.layout.style(node) == Some(&style) {
573            return Ok(PropertyImpactSet::default());
574        }
575        let impact = Rc::make_mut(&mut self.layout).update_style(node, style)?;
576        self.layout_dirty = true;
577        Ok(impact)
578    }
579
580    /// Applies every currently supported computed layout and paint value.
581    pub fn update_computed_style(
582        &mut self,
583        node: NodeId,
584        style: &ComputedStyle,
585    ) -> Result<PropertyImpactSet, SurfaceError> {
586        self.ensure_mutable()?;
587        let lowered = lower_paint(style.paint(), style.layout());
588        let transform_changed = self.transforms.get(&node) != Some(&lowered.transform);
589        let projected_transform = self
590            .last_layout
591            .as_ref()
592            .and_then(|layout| layout.get(node))
593            .copied()
594            .map(|geometry| {
595                self.resolve_node_transform(
596                    node,
597                    &lowered.transform,
598                    geometry.border_box.width,
599                    geometry.border_box.height,
600                )
601            })
602            .transpose()?;
603        let paint_changed = {
604            let current = self
605                .scene
606                .node(node)
607                .ok_or(SceneError::UnknownNode { node })?;
608            current.box_paint() != Some(&lowered.box_paint)
609                || current.visual_effects() != &lowered.visual_effects
610                || current.clip() != Some(lowered.clip)
611                || current.opacity() != Some(lowered.opacity)
612                || current.visibility() != Some(lowered.visibility)
613                || current.z_order() != Some(lowered.z_order)
614                || transform_changed
615        };
616        let input_changed = {
617            let current = self
618                .scene
619                .node(node)
620                .expect("the retained scene node was validated above");
621            current.hit_test() != Some(lower_hit_test(style.pointer_events()))
622                || current.cursor() != Some(&lower_cursor(style.cursor()))
623        };
624        let mut impacts = self.update_layout_style(node, style.layout().clone())?;
625        self.scene
626            .set_box_paint(node, lowered.box_paint)
627            .expect("lowered paint is valid and the scene is mutable");
628        self.scene
629            .set_visual_effects(node, lowered.visual_effects)
630            .expect("lowered visual effects are valid and the scene is mutable");
631        self.scene
632            .set_clip(node, lowered.clip)
633            .expect("the retained scene node was validated above");
634        self.scene
635            .set_opacity(node, lowered.opacity)
636            .expect("computed opacity is valid and the scene node exists");
637        let visibility = if self.paragraph_visibility.contains(node) {
638            Rc::make_mut(&mut self.paragraph_visibility).visibility(node, lowered.visibility)
639        } else {
640            lowered.visibility
641        };
642        self.scene
643            .set_visibility(node, visibility)
644            .expect("the retained scene node was validated above");
645        self.scene
646            .set_z_order(node, lowered.z_order)
647            .expect("the retained scene node was validated above");
648        self.scene
649            .set_hit_test(node, lower_hit_test(style.pointer_events()))
650            .expect("the retained scene node was validated above");
651        self.scene
652            .set_cursor(node, lower_cursor(style.cursor()))
653            .expect("the retained scene node was validated above");
654        if transform_changed {
655            Rc::make_mut(&mut self.transforms).insert(node, lowered.transform);
656        }
657        if let Some(transform) = projected_transform.flatten() {
658            self.scene
659                .set_transform(node, transform)
660                .expect("the transform was validated before retained style mutation");
661        }
662        if paint_changed {
663            impacts |= PropertyImpactSet::PAINT;
664        }
665        if input_changed {
666            impacts |= PropertyImpactSet::INPUT;
667        }
668        Ok(impacts)
669    }
670
671    /// Updates retained background image layers independently from computed
672    /// box paint. Resource identity is assigned by the runtime boundary, not
673    /// by the layout/style engine.
674    pub fn set_background_layers(
675        &mut self,
676        node: NodeId,
677        mut layers: Vec<BackgroundLayer>,
678    ) -> Result<(), SurfaceError> {
679        self.ensure_mutable()?;
680        let sources = radial_background_sources(&layers);
681        if let Some(geometry) = self
682            .last_layout
683            .as_ref()
684            .and_then(|layout| layout.get(node))
685            .copied()
686        {
687            let paint = self.scene.node(node).and_then(SceneNode::box_paint);
688            canonicalize_radial_backgrounds(&mut layers, &sources, geometry, paint);
689        }
690        self.scene.set_background_layers(node, layers)?;
691        if sources.is_empty() {
692            if self.radial_backgrounds.contains_key(&node) {
693                Rc::make_mut(&mut self.radial_backgrounds).remove(&node);
694            }
695        } else if self.radial_backgrounds.get(&node) != Some(&sources) {
696            Rc::make_mut(&mut self.radial_backgrounds).insert(node, sources);
697        }
698        Ok(())
699    }
700
701    /// Marks or unmarks a leaf as requiring intrinsic Host measurement.
702    ///
703    /// Returns whether retained measurement behavior changed.
704    pub fn set_measurable(&mut self, node: NodeId, measurable: bool) -> Result<bool, SurfaceError> {
705        self.ensure_mutable()?;
706        if self.layout.is_measurable(node) == Some(measurable) {
707            return Ok(false);
708        }
709        let changed = Rc::make_mut(&mut self.layout).set_measurable(node, measurable)?;
710        self.layout_dirty |= changed;
711        Ok(changed)
712    }
713
714    /// Registers or clears Host-backed intrinsic measurement for one leaf.
715    ///
716    /// Element modules provide a semantic kind, complete content/style hashes,
717    /// a versioned payload, and an explicit pending policy. Ordinary boxes and
718    /// explicitly sized media should leave this unset.
719    pub fn set_measurement(
720        &mut self,
721        node: NodeId,
722        spec: Option<MeasurementSpec>,
723    ) -> Result<bool, SurfaceError> {
724        self.ensure_mutable()?;
725        let element_type = self
726            .scene
727            .node(node)
728            .ok_or(SceneError::UnknownNode { node })?
729            .element_type();
730        if !self.layout.contains(node) {
731            return Err(LayoutError::UnknownNode(node).into());
732        }
733        let measurable = spec.is_some();
734        let spec_changed = !self
735            .measurements
736            .matches_spec(node, element_type, spec.as_ref())
737            && Rc::make_mut(&mut self.measurements).set_spec(node, element_type, spec)?;
738        let behavior_changed = self
739            .set_measurable(node, measurable)
740            .expect("measurement node was validated on a mutable surface");
741        let changed = spec_changed || behavior_changed;
742        if changed {
743            Rc::make_mut(&mut self.layout)
744                .invalidate_measurement(node)
745                .expect("configured measurement node remains in synchronized layout");
746            self.layout_dirty = true;
747        }
748        Ok(changed)
749    }
750
751    /// Lowers and registers one plain UTF-8 Text v1 presentation.
752    ///
753    /// Metric-affecting values come from the already resolved computed text
754    /// context. The same payload is retained for final frame production and
755    /// registered with Taffy for Host intrinsic measurement.
756    pub fn set_plain_text(
757        &mut self,
758        node: NodeId,
759        input: &PlainTextInput,
760        style: &ComputedStyle,
761    ) -> Result<bool, SurfaceError> {
762        self.set_lowered_text(node, lower_plain_text(input, style))
763    }
764
765    /// Replaces a paragraph's inline content and intrinsic measurement inputs.
766    pub fn set_rich_text(
767        &mut self,
768        node: NodeId,
769        input: &PlainTextInput,
770        style: &ComputedStyle,
771        runs: &[crate::ResolvedTextRun],
772        attachments: &[crate::InlineAttachmentInput],
773    ) -> Result<bool, SurfaceError> {
774        let paragraph = !runs.is_empty() || !attachments.is_empty();
775        if self.layout.is_paragraph(node) != paragraph {
776            Rc::make_mut(&mut self.layout).set_paragraph(node, paragraph)?;
777        }
778        let changed = self.set_lowered_text(
779            node,
780            crate::lower_rich_text(input, style, runs, attachments),
781        )?;
782        if !self
783            .measurements
784            .inline_attachments_match(node, attachments)
785        {
786            Rc::make_mut(&mut self.measurements).set_inline_attachments(node, attachments);
787        }
788        Ok(changed)
789    }
790
791    fn set_lowered_text(
792        &mut self,
793        node: NodeId,
794        lowered: crate::LoweredPlainText,
795    ) -> Result<bool, SurfaceError> {
796        self.ensure_mutable()?;
797        let previous = self
798            .scene
799            .node(node)
800            .ok_or(SceneError::UnknownNode { node })?
801            .text()
802            .cloned();
803        let (mut content, measurement) = lowered.into_parts();
804        let measurement_changed = self.set_measurement(node, Some(measurement))?;
805        if !measurement_changed && let Some(previous) = &previous {
806            content.prepared_content = previous.prepared_content;
807            content.paragraph = previous.paragraph.clone();
808            content.payload = previous.payload.clone();
809        }
810        let content_changed = previous.as_ref() != Some(&content);
811        self.scene
812            .set_text(node, content)
813            .expect("validated synchronized text node remains mutable");
814        Ok(content_changed || measurement_changed)
815    }
816
817    /// Returns the last final Host metrics retained for a node.
818    ///
819    /// Baselines, overflow, and prepared-content handles remain available for
820    /// later text and paint lowering even though Taffy consumes only the size.
821    pub fn last_measurement(&self, node: NodeId) -> Option<&MeasurementMetrics> {
822        self.measurements.last_ready(node)
823    }
824
825    /// Applies invalidation categories for a changed node property.
826    ///
827    /// Paint-only changes do not schedule Taffy. Intrinsic-measure changes
828    /// invalidate the layout backend's cached measurement before scheduling.
829    /// Returns whether a layout pass is required by the supplied impacts.
830    pub fn invalidate_node(
831        &mut self,
832        node: NodeId,
833        impacts: PropertyImpactSet,
834    ) -> Result<bool, SurfaceError> {
835        self.ensure_mutable()?;
836        if self.scene.node(node).is_none() {
837            return Err(SceneError::UnknownNode { node }.into());
838        }
839        let intrinsic = impacts.contains(PropertyImpactSet::INTRINSIC_MEASURE);
840        if intrinsic {
841            Rc::make_mut(&mut self.layout).invalidate_measurement(node)?;
842        }
843        let requires_layout = intrinsic || impacts.contains(PropertyImpactSet::LAYOUT);
844        self.layout_dirty |= requires_layout;
845        Ok(requires_layout)
846    }
847
848    /// Computes layout when inputs are dirty and journals changed rectangles.
849    pub fn compute_layout(
850        &mut self,
851        root: NodeId,
852        viewport: LayoutSize,
853        measurer: &mut dyn IntrinsicMeasurer,
854    ) -> Result<LayoutUpdate, SurfaceError> {
855        self.ensure_mutable()?;
856        let inputs = LayoutInputs { root, viewport };
857        if !self.layout_dirty && self.last_inputs == Some(inputs) {
858            return Ok(LayoutUpdate::default());
859        }
860
861        let snapshot = Rc::make_mut(&mut self.layout).compute(root, viewport, measurer)?;
862        let update = self.project_layout(snapshot, inputs)?;
863        self.layout_provisional = false;
864        Ok(update)
865    }
866
867    /// Advances layout using retained, batched Host intrinsic measurement.
868    ///
869    /// A blocked result must not be presented. Provisional geometry is emitted
870    /// only when the element schema or provider supplied an explicit fallback.
871    /// Reinvoke after applying immediate or deferred responses until complete.
872    pub fn compute_layout_with_measurements(
873        &mut self,
874        root: NodeId,
875        viewport: LayoutSize,
876        environment_epoch: u64,
877    ) -> Result<LayoutProgress, SurfaceError> {
878        self.compute_layout_using(root, viewport, environment_epoch, None)
879    }
880
881    pub(crate) fn compute_layout_using(
882        &mut self,
883        root: NodeId,
884        viewport: LayoutSize,
885        environment_epoch: u64,
886        immediate: Option<&mut crate::measurement::ImmediateHost<'_>>,
887    ) -> Result<LayoutProgress, SurfaceError> {
888        self.ensure_mutable()?;
889        if self.measurements.environment_epoch() != Some(environment_epoch) {
890            for node in Rc::make_mut(&mut self.measurements).set_environment(environment_epoch) {
891                Rc::make_mut(&mut self.layout)
892                    .invalidate_measurement(node)
893                    .expect("measurement specs remain synchronized with layout nodes");
894                self.layout_dirty = true;
895            }
896        }
897        let inputs = LayoutInputs { root, viewport };
898        if !self.layout_dirty && self.last_inputs == Some(inputs) {
899            return if self.layout_provisional {
900                Ok(LayoutProgress::Provisional {
901                    update: LayoutUpdate::default(),
902                    requests: self.measurements.outstanding_requests(),
903                    pending: self.measurements.pending_count(),
904                })
905            } else {
906                Ok(LayoutProgress::Complete(LayoutUpdate::default()))
907            };
908        }
909
910        for node in self.measurements.unresolved_nodes() {
911            Rc::make_mut(&mut self.layout)
912                .invalidate_measurement(node)
913                .expect("measurement consumers remain synchronized with layout nodes");
914        }
915
916        Rc::make_mut(&mut self.measurements).begin_pass();
917        let layout = Rc::make_mut(&mut self.layout);
918        let coordinator = Rc::<MeasurementCoordinator>::make_mut(&mut self.measurements);
919        let snapshot = match immediate {
920            Some(host) => layout.compute(
921                root,
922                viewport,
923                &mut crate::measurement::ImmediateMeasurer { coordinator, host },
924            ),
925            None => layout.compute(root, viewport, coordinator),
926        }?;
927        let pass = Rc::make_mut(&mut self.measurements).finish_pass()?;
928        if pass.blocking {
929            self.layout_dirty = true;
930            return Ok(LayoutProgress::Blocked {
931                requests: pass.requests,
932                pending: pass.pending,
933            });
934        }
935
936        self.sync_text_presentations(&snapshot);
937        let update = self.project_layout(snapshot, inputs)?;
938        if pass.provisional || !pass.requests.is_empty() || pass.pending != 0 {
939            self.layout_provisional = true;
940            Ok(LayoutProgress::Provisional {
941                update,
942                requests: pass.requests,
943                pending: pass.pending,
944            })
945        } else {
946            self.layout_provisional = false;
947            Ok(LayoutProgress::Complete(update))
948        }
949    }
950
951    /// Applies synchronous results from one Host measurement batch.
952    ///
953    /// Unknown and wrong-epoch responses are counted as stale and ignored.
954    /// Accepted results invalidate only their current Taffy consumers.
955    pub fn apply_measurement_responses(
956        &mut self,
957        responses: &[MeasurementResponse],
958    ) -> Result<MeasurementApply, SurfaceError> {
959        self.ensure_mutable()?;
960        let apply = Rc::make_mut(&mut self.measurements).apply_batch(responses)?;
961        for node in apply.invalidated_nodes() {
962            Rc::make_mut(&mut self.layout)
963                .invalidate_measurement(*node)
964                .expect("response consumers remain synchronized with layout nodes");
965        }
966        self.layout_dirty |= !apply.invalidated_nodes().is_empty();
967        Ok(apply)
968    }
969
970    /// Applies a deferred Host-to-Rust measurement completion.
971    pub fn apply_measurement_ready(
972        &mut self,
973        ready: &MeasurementReady,
974    ) -> Result<DeferredMeasurementApply, SurfaceError> {
975        self.ensure_mutable()?;
976        let apply = Rc::make_mut(&mut self.measurements).apply_ready(ready)?;
977        for node in apply.invalidated_nodes() {
978            Rc::make_mut(&mut self.layout)
979                .invalidate_measurement(*node)
980                .expect("deferred consumers remain synchronized with layout nodes");
981        }
982        self.layout_dirty |= !apply.invalidated_nodes().is_empty();
983        Ok(apply)
984    }
985
986    /// Prepares the next scene snapshot or delta frame.
987    pub fn prepare_frame(
988        &mut self,
989        viewport_epoch: u32,
990    ) -> Result<Option<&FramePacket>, SurfaceError> {
991        self.scene.prepare_frame(viewport_epoch).map_err(Into::into)
992    }
993
994    /// Presents the next transaction and applies the Host acknowledgement.
995    ///
996    /// `NeedSnapshot`, a sink error, or an invalid acknowledgement rotates the
997    /// scene epoch and leaves a complete snapshot ready for the next call.
998    /// This repairs Hosts that may have applied part of a rejected packet.
999    pub fn present<Sink: FrameSink>(
1000        &mut self,
1001        viewport_epoch: u32,
1002        sink: &mut Sink,
1003    ) -> Result<Option<ApplyResult>, SurfacePresentError<Sink::Error>> {
1004        let packet = self
1005            .prepare_frame(viewport_epoch)
1006            .map_err(SurfacePresentError::Surface)?
1007            .cloned();
1008        let Some(packet) = packet else {
1009            return Ok(None);
1010        };
1011        let result = match sink.present(&packet) {
1012            Ok(result) => result,
1013            Err(error) => {
1014                self.require_snapshot()
1015                    .expect("a prepared frame can always be replaced by a snapshot");
1016                return Err(SurfacePresentError::Sink(error));
1017            }
1018        };
1019        match result {
1020            ApplyResult::Accepted { revision } => {
1021                if let Err(error) = self.accept_pending(revision) {
1022                    // An acknowledgement that does not match the prepared
1023                    // frame means sender and receiver no longer agree on the
1024                    // retained revision. Do not leave the rejected packet
1025                    // pending: the next frame must repair the receiver from a
1026                    // complete snapshot.
1027                    self.require_snapshot()
1028                        .expect("a prepared frame can always be replaced by a snapshot");
1029                    return Err(SurfacePresentError::Surface(error));
1030                }
1031            }
1032            ApplyResult::NeedSnapshot { .. } => self
1033                .require_snapshot()
1034                .map_err(SurfacePresentError::Surface)?,
1035        }
1036        Ok(Some(result))
1037    }
1038
1039    /// Commits the prepared frame after renderer acceptance.
1040    pub fn accept_pending(&mut self, revision: u64) -> Result<(), SurfaceError> {
1041        self.scene.accept_pending(revision).map_err(Into::into)
1042    }
1043
1044    /// Discards the prepared frame while retaining its semantic changes.
1045    pub fn discard_pending(&mut self) -> Result<(), SurfaceError> {
1046        self.scene.discard_pending().map_err(Into::into)
1047    }
1048
1049    /// Requires the next frame to rebuild the receiver from a full snapshot.
1050    pub fn require_snapshot(&mut self) -> Result<(), SurfaceError> {
1051        self.scene.require_snapshot().map_err(Into::into)
1052    }
1053
1054    fn ensure_mutable(&self) -> Result<(), SurfaceError> {
1055        if self.scene.has_prepared_frame() {
1056            Err(SceneError::FramePending.into())
1057        } else {
1058            Ok(())
1059        }
1060    }
1061
1062    fn project_layout(
1063        &mut self,
1064        snapshot: LayoutSnapshot,
1065        inputs: LayoutInputs,
1066    ) -> Result<LayoutUpdate, SurfaceError> {
1067        let entries = snapshot
1068            .iter()
1069            .map(|(node, rect)| (node, *rect))
1070            .collect::<Vec<_>>();
1071        validate_layout_entries(&self.scene, &entries)?;
1072        let changed = entries
1073            .iter()
1074            .copied()
1075            .filter(|(node, rect)| {
1076                self.last_layout
1077                    .as_ref()
1078                    .and_then(|previous| previous.get(*node))
1079                    != Some(rect)
1080            })
1081            .collect::<Vec<_>>();
1082        let transforms = changed
1083            .iter()
1084            .map(|(node, rect)| {
1085                self.transforms
1086                    .get(node)
1087                    .map(|style| {
1088                        self.resolve_node_transform(
1089                            *node,
1090                            style,
1091                            rect.border_box.width,
1092                            rect.border_box.height,
1093                        )
1094                    })
1095                    .transpose()
1096                    .map(Option::flatten)
1097            })
1098            .collect::<Result<Vec<_>, SurfaceError>>()?;
1099        let radial_backgrounds = if self.radial_backgrounds.is_empty() {
1100            Vec::new()
1101        } else {
1102            changed
1103                .iter()
1104                .filter_map(|(node, geometry)| {
1105                    let sources = self.radial_backgrounds.get(node)?;
1106                    let mut layers = self
1107                        .scene
1108                        .node(*node)
1109                        .expect("radial background owners remain live")
1110                        .background_layers()
1111                        .to_vec();
1112                    canonicalize_radial_backgrounds(
1113                        &mut layers,
1114                        sources,
1115                        *geometry,
1116                        self.scene.node(*node).and_then(SceneNode::box_paint),
1117                    );
1118                    Some((*node, layers))
1119                })
1120                .collect::<Vec<_>>()
1121        };
1122        for ((node, rect), transform) in changed.iter().zip(transforms) {
1123            self.scene
1124                .set_layout(*node, *rect)
1125                .expect("validated layout projection must enter a mutable synchronized scene");
1126            if let Some(transform) = transform {
1127                self.scene
1128                    .set_transform(*node, transform)
1129                    .expect("the transform was validated before layout projection");
1130            }
1131        }
1132        for (node, layers) in radial_backgrounds {
1133            self.scene
1134                .set_background_layers(node, layers)
1135                .expect("canonical radial backgrounds preserve protocol validity");
1136        }
1137        if snapshot.has_paragraph_suppression() || !self.paragraph_visibility.is_empty() {
1138            Rc::make_mut(&mut self.paragraph_visibility).project(&mut self.scene, &snapshot);
1139        }
1140        self.last_layout = Some(Rc::new(snapshot));
1141        self.last_inputs = Some(inputs);
1142        self.layout_dirty = false;
1143        Ok(LayoutUpdate::computed(changed.len()))
1144    }
1145
1146    fn resolve_node_transform(
1147        &self,
1148        node: NodeId,
1149        style: &ComputedTransformStyle,
1150        border_width: f32,
1151        border_height: f32,
1152    ) -> Result<Option<whisker_protocol::Transform>, SurfaceError> {
1153        if style.perspective.is_none()
1154            && matches!(
1155                style.offset_path,
1156                whisker_style::ComputedOffsetPathValue::None
1157            )
1158            && style.functions.is_empty()
1159            && self
1160                .scene
1161                .node(node)
1162                .and_then(SceneNode::transform)
1163                .is_none()
1164        {
1165            return Ok(None);
1166        }
1167        let transform = lower_transform(style, border_width, border_height)
1168            .ok_or(SurfaceError::InvalidTransformOutput { node })?;
1169        Ok(Some(transform))
1170    }
1171
1172    fn sync_text_presentations(&mut self, snapshot: &whisker_layout::LayoutSnapshot) {
1173        for (node, selection) in snapshot.selections() {
1174            let Some((whisker_protocol::MeasurementPayload::Text(payload), metrics)) =
1175                self.measurements.selected(node, selection)
1176            else {
1177                continue;
1178            };
1179            let Some(current) = self.scene.node(node).and_then(SceneNode::text) else {
1180                continue;
1181            };
1182            let mut content = current.clone();
1183            content.payload = payload.clone();
1184            content.prepared_content = metrics.prepared_content;
1185            content.paragraph = metrics.paragraph.clone();
1186            self.scene
1187                .set_text(node, content)
1188                .expect("selected text remains valid");
1189        }
1190    }
1191}
1192
1193fn collect_scene_subtree(
1194    scene: &Scene,
1195    node: NodeId,
1196    output: &mut Vec<NodeId>,
1197) -> Result<(), SurfaceError> {
1198    let retained = scene.node(node).ok_or(SceneError::UnknownNode { node })?;
1199    output.push(node);
1200    for child in retained.children() {
1201        collect_scene_subtree(scene, *child, output)
1202            .expect("retained scene children remain live while their parent is live");
1203    }
1204    Ok(())
1205}
1206
1207fn validate_layout_entries(
1208    scene: &Scene,
1209    entries: &[(NodeId, LayoutGeometry)],
1210) -> Result<(), SurfaceError> {
1211    for (node, geometry) in entries {
1212        if scene.node(*node).is_none() {
1213            return Err(SurfaceError::SceneLayoutMismatch { node: *node });
1214        }
1215        if !geometry.is_valid() {
1216            return Err(SurfaceError::InvalidLayoutOutput { node: *node });
1217        }
1218    }
1219    Ok(())
1220}
1221
1222#[cfg(test)]
1223mod tests {
1224    use std::cell::Cell;
1225
1226    use whisker_layout::{AvailableSpace, LayoutSize, MeasureRequest, UnsupportedLayoutFeature};
1227    use whisker_protocol::{
1228        ApplyResult, BackgroundAttachment, BackgroundLayer, BackgroundSize, BlendMode,
1229        CustomMeasurePayload, ElementTypeId, EmbeddedSurfaceMeasurePayload, FrameMode,
1230        HitTestBehavior, ImageRepeat, InputPoint, LayoutRect, MeasureFontFamily, MeasureFontStyle,
1231        MeasureLineHeight, MeasureTextDirection, MeasureTextOverflow, MeasureTextWrap,
1232        MeasuredSize, MeasurementKey, MeasurementKind, MeasurementMetrics, MeasurementPayload,
1233        MeasurementReady, MeasurementRequestId, MeasurementResponse, MeasurementSpec,
1234        NativeControlMeasurePayload, NodeId, Operation, PaintBox, PaintCoordinate, PaintImage,
1235        PaintLengthPercentage, PaintPosition, PendingMeasurePolicy, PointerId,
1236        RadialGradientExtent, RadialGradientShape, ReplacedContentMeasurePayload, ResourceId,
1237        SurfaceId, TextMeasurePayload, TextMeasureStyle, UnsupportedMeasurementReason,
1238    };
1239    use whisker_style::{
1240        Axes, ComputedLengthPercentage, ComputedSizeValue, ComputedTransformFunction,
1241        ComputedTransformStyle, LengthPercentageValue, PositionValue, SpecifiedStyle,
1242        StyleEnvironment, StyleNumber, StyleProperty, StyleValue, TransformFunctionValue,
1243        TransformValue, resolve_style,
1244    };
1245
1246    use super::*;
1247    use crate::{FrameSink, RecordingRenderer};
1248
1249    #[test]
1250    fn snapshots_share_unchanged_nodes_and_isolate_mutations() {
1251        let mut surface = SurfaceEngine::new(surface_id());
1252        let changed = surface
1253            .create_node(element_type(), sized(40.0, 20.0))
1254            .unwrap();
1255        let untouched = surface
1256            .create_node(element_type(), sized(10.0, 10.0))
1257            .unwrap();
1258        let snapshot = surface.clone();
1259        surface.set_opacity(changed, 0.5).unwrap();
1260        assert!(std::ptr::eq(
1261            surface.node(untouched).unwrap(),
1262            snapshot.node(untouched).unwrap()
1263        ));
1264        assert!(!std::ptr::eq(
1265            surface.node(changed).unwrap(),
1266            snapshot.node(changed).unwrap()
1267        ));
1268        assert_ne!(surface.node(changed), snapshot.node(changed));
1269    }
1270
1271    #[test]
1272    fn paint_updates_share_layout_and_measurement_snapshots() {
1273        let initial =
1274            resolve_style(&SpecifiedStyle::new(), None, StyleEnvironment::default()).unwrap();
1275        let painted = resolve_style(
1276            &SpecifiedStyle::new().push(
1277                StyleProperty::Opacity,
1278                StyleValue::Number(StyleNumber::new(0.5)),
1279            ),
1280            None,
1281            StyleEnvironment::default(),
1282        )
1283        .unwrap();
1284        let mut surface = SurfaceEngine::new(surface_id());
1285        let root = surface
1286            .create_node(element_type(), initial.computed().layout().clone())
1287            .unwrap();
1288        surface
1289            .update_computed_style(root, initial.computed())
1290            .unwrap();
1291        surface
1292            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
1293            .unwrap();
1294        let snapshot = surface.clone();
1295        surface
1296            .update_computed_style(root, painted.computed())
1297            .unwrap();
1298        surface.set_measurement(root, None).unwrap();
1299        surface.set_background_layers(root, Vec::new()).unwrap();
1300        assert!(std::ptr::eq(surface.layout_tree(), snapshot.layout_tree()));
1301        assert!(Rc::ptr_eq(&surface.measurements, &snapshot.measurements));
1302        assert!(Rc::ptr_eq(&surface.transforms, &snapshot.transforms));
1303        assert!(Rc::ptr_eq(
1304            &surface.radial_backgrounds,
1305            &snapshot.radial_backgrounds
1306        ));
1307        assert!(std::ptr::eq(
1308            surface.last_layout().unwrap(),
1309            snapshot.last_layout().unwrap()
1310        ));
1311        assert!(!surface.needs_layout());
1312        surface
1313            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
1314            .unwrap();
1315        assert!(Rc::ptr_eq(&surface.measurements, &snapshot.measurements));
1316        assert!(std::ptr::eq(surface.layout_tree(), snapshot.layout_tree()));
1317        surface
1318            .update_layout_style(root, sized(50.0, 50.0))
1319            .unwrap();
1320        assert!(!std::ptr::eq(surface.layout_tree(), snapshot.layout_tree()));
1321        assert_eq!(
1322            snapshot.layout_tree().style(root),
1323            Some(initial.computed().layout())
1324        );
1325        assert_ne!(surface.node(root), snapshot.node(root));
1326    }
1327
1328    fn surface_id() -> SurfaceId {
1329        SurfaceId::new(1).expect("test surface")
1330    }
1331
1332    fn element_type() -> ElementTypeId {
1333        ElementTypeId::new(1).expect("test element type")
1334    }
1335
1336    fn node_id(value: u64) -> NodeId {
1337        NodeId::new(value).expect("test node")
1338    }
1339
1340    fn sized(width: f32, height: f32) -> ComputedLayoutStyle {
1341        ComputedLayoutStyle {
1342            size: Axes {
1343                width: ComputedSizeValue::Value(ComputedLengthPercentage::new(width, 0.0)),
1344                height: ComputedSizeValue::Value(ComputedLengthPercentage::new(height, 0.0)),
1345            },
1346            ..ComputedLayoutStyle::default()
1347        }
1348    }
1349
1350    fn resource_background(resource: u64) -> BackgroundLayer {
1351        BackgroundLayer {
1352            image: PaintImage::Resource(ResourceId::new(resource).expect("test resource")),
1353            position: PaintPosition::default(),
1354            size: BackgroundSize::Auto,
1355            repeat_x: ImageRepeat::Repeat,
1356            repeat_y: ImageRepeat::Repeat,
1357            origin: PaintBox::Padding,
1358            clip: PaintBox::Border,
1359            attachment: BackgroundAttachment::Scroll,
1360            blend_mode: BlendMode::Normal,
1361        }
1362    }
1363
1364    fn radial_background(
1365        shape: RadialGradientShape,
1366        extent: RadialGradientExtent,
1367        radii: Option<(PaintLengthPercentage, PaintLengthPercentage)>,
1368    ) -> BackgroundLayer {
1369        BackgroundLayer {
1370            image: PaintImage::RadialGradient {
1371                shape,
1372                extent,
1373                center: PaintPosition {
1374                    x: PaintCoordinate {
1375                        length: 0.0,
1376                        fraction: 0.5,
1377                    },
1378                    y: PaintCoordinate {
1379                        length: 0.0,
1380                        fraction: 0.5,
1381                    },
1382                },
1383                radii,
1384                repeating: false,
1385                stops: vec![
1386                    whisker_protocol::GradientStop {
1387                        color: Default::default(),
1388                        position: Some(PaintCoordinate {
1389                            length: 0.0,
1390                            fraction: 0.0,
1391                        }),
1392                    },
1393                    whisker_protocol::GradientStop {
1394                        color: Default::default(),
1395                        position: Some(PaintCoordinate {
1396                            length: 25.0,
1397                            fraction: 0.0,
1398                        }),
1399                    },
1400                ],
1401            },
1402            position: PaintPosition::default(),
1403            size: BackgroundSize::Auto,
1404            repeat_x: ImageRepeat::Repeat,
1405            repeat_y: ImageRepeat::Repeat,
1406            origin: PaintBox::Border,
1407            clip: PaintBox::Border,
1408            attachment: BackgroundAttachment::Scroll,
1409            blend_mode: BlendMode::Normal,
1410        }
1411    }
1412
1413    type RadialParts<'a> = (
1414        RadialGradientShape,
1415        RadialGradientExtent,
1416        Option<(PaintLengthPercentage, PaintLengthPercentage)>,
1417        &'a [whisker_protocol::GradientStop],
1418    );
1419
1420    fn radial_parts(image: &PaintImage) -> Option<RadialParts<'_>> {
1421        match image {
1422            PaintImage::RadialGradient {
1423                shape,
1424                extent,
1425                radii,
1426                stops,
1427                ..
1428            } => Some((*shape, *extent, *radii, stops)),
1429            _ => None,
1430        }
1431    }
1432
1433    #[test]
1434    fn layout_canonicalizes_radial_keyword_geometry_and_absolute_stops() {
1435        assert!(radial_parts(&PaintImage::None).is_none());
1436        let mut surface = SurfaceEngine::new(surface_id());
1437        let root = surface
1438            .create_node(element_type(), sized(200.0, 100.0))
1439            .expect("root");
1440        let plain_child = surface
1441            .create_node(element_type(), sized(10.0, 10.0))
1442            .expect("plain child");
1443        surface.insert_child(root, plain_child, 0).expect("insert");
1444        surface
1445            .set_background_layers(
1446                root,
1447                vec![radial_background(
1448                    RadialGradientShape::Circle,
1449                    RadialGradientExtent::FarthestCorner,
1450                    None,
1451                )],
1452            )
1453            .expect("background");
1454        surface
1455            .compute_layout(root, LayoutSize::new(200.0, 100.0), &mut zero_measure)
1456            .expect("layout");
1457        surface
1458            .set_background_layers(
1459                root,
1460                vec![radial_background(
1461                    RadialGradientShape::Circle,
1462                    RadialGradientExtent::FarthestCorner,
1463                    None,
1464                )],
1465            )
1466            .expect("post-layout background");
1467
1468        let (shape, extent, radii, stops) =
1469            radial_parts(&surface.node(root).unwrap().background_layers()[0].image)
1470                .expect("canonical radial gradient");
1471        let (radius_x, radius_y) = radii.expect("canonical radii");
1472        let expected_radius = 100.0_f32.hypot(50.0);
1473        assert_eq!(shape, RadialGradientShape::Ellipse);
1474        assert_eq!(extent, RadialGradientExtent::Explicit);
1475        assert!((radius_x.length - expected_radius).abs() < 0.001);
1476        assert_eq!(radius_x, radius_y);
1477        assert_eq!(radius_x.fraction, 0.0);
1478        assert_eq!(stops[1].position.unwrap().length, 0.0);
1479        assert!((stops[1].position.unwrap().fraction - 25.0 / expected_radius).abs() < 0.0001);
1480
1481        surface
1482            .update_layout_style(root, sized(100.0, 100.0))
1483            .expect("resize style");
1484        surface
1485            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
1486            .expect("resized layout");
1487        let (_, _, resized_radii, resized_stops) =
1488            radial_parts(&surface.node(root).unwrap().background_layers()[0].image)
1489                .expect("resized radial gradient");
1490        let (resized_radius, _) = resized_radii.expect("resized radii");
1491        let resized_expected = 50.0_f32.hypot(50.0);
1492        assert!((resized_radius.length - resized_expected).abs() < 0.001);
1493        assert!(
1494            (resized_stops[1].position.unwrap().fraction - 25.0 / resized_expected).abs() < 0.0001
1495        );
1496    }
1497
1498    #[test]
1499    fn clearing_radial_backgrounds_drops_retained_geometry_sources() {
1500        let mut surface = SurfaceEngine::new(surface_id());
1501        let root = surface
1502            .create_node(element_type(), sized(200.0, 100.0))
1503            .unwrap();
1504        surface
1505            .set_background_layers(
1506                root,
1507                vec![radial_background(
1508                    RadialGradientShape::Circle,
1509                    RadialGradientExtent::FarthestCorner,
1510                    None,
1511                )],
1512            )
1513            .unwrap();
1514        surface
1515            .compute_layout(root, LayoutSize::new(200.0, 100.0), &mut zero_measure)
1516            .unwrap();
1517        let snapshot = surface.clone();
1518        surface.set_background_layers(root, Vec::new()).unwrap();
1519        surface
1520            .update_layout_style(root, sized(100.0, 100.0))
1521            .unwrap();
1522        surface
1523            .compute_layout(root, LayoutSize::new(200.0, 100.0), &mut zero_measure)
1524            .unwrap();
1525        assert!(surface.node(root).unwrap().background_layers().is_empty());
1526        assert_eq!(snapshot.node(root).unwrap().background_layers().len(), 1);
1527    }
1528
1529    #[test]
1530    fn radial_canonicalization_preserves_ellipse_aspect_ratio_and_circle_radius() {
1531        let geometry = LayoutGeometry::from(LayoutRect {
1532            width: 200.0,
1533            height: 100.0,
1534            ..LayoutRect::default()
1535        });
1536        let mut layers = vec![
1537            radial_background(
1538                RadialGradientShape::Ellipse,
1539                RadialGradientExtent::FarthestCorner,
1540                None,
1541            ),
1542            radial_background(
1543                RadialGradientShape::Circle,
1544                RadialGradientExtent::Explicit,
1545                Some((absolute_length(20.0), absolute_length(20.0))),
1546            ),
1547        ];
1548        let sources = radial_background_sources(&layers);
1549        canonicalize_radial_backgrounds(&mut layers, &sources, geometry, None);
1550
1551        let (_, _, ellipse_radii, _) = radial_parts(&layers[0].image).expect("ellipse");
1552        let (ellipse_x, ellipse_y) = ellipse_radii.expect("ellipse radii");
1553        assert!((ellipse_x.length - 100.0 * 2.0_f32.sqrt()).abs() < 0.001);
1554        assert!((ellipse_y.length - 50.0 * 2.0_f32.sqrt()).abs() < 0.001);
1555        let (shape, _, circle_radii, _) = radial_parts(&layers[1].image).expect("circle");
1556        let (circle_x, circle_y) = circle_radii.expect("circle radii");
1557        assert_eq!(shape, RadialGradientShape::Ellipse);
1558        assert_eq!(circle_x, absolute_length(20.0));
1559        assert_eq!(circle_y, absolute_length(20.0));
1560    }
1561
1562    fn zero_measure(_: NodeId, _: MeasureRequest) -> LayoutSize {
1563        LayoutSize::default()
1564    }
1565
1566    fn measurement_spec(
1567        kind: MeasurementKind,
1568        pending_policy: PendingMeasurePolicy,
1569    ) -> MeasurementSpec {
1570        MeasurementSpec {
1571            content_hash: 1,
1572            style_hash: 2,
1573            payload: measurement_payload(kind),
1574            pending_policy,
1575        }
1576    }
1577
1578    fn measurement_payload(kind: MeasurementKind) -> MeasurementPayload {
1579        match kind {
1580            MeasurementKind::Text => MeasurementPayload::Text(TextMeasurePayload {
1581                runs: Vec::new(),
1582                attachments: Vec::new(),
1583                text: "Hello, Whisker".into(),
1584                style: TextMeasureStyle {
1585                    font_families: vec![MeasureFontFamily::System],
1586                    font_size: 14.0,
1587                    font_weight: 400,
1588                    font_style: MeasureFontStyle::Normal,
1589                    line_height: MeasureLineHeight::Normal,
1590                    letter_spacing: 0.0,
1591                    ..TextMeasureStyle::default()
1592                },
1593                locale: Some("en-US".into()),
1594                direction: MeasureTextDirection::LeftToRight,
1595                alignment: whisker_protocol::MeasureTextAlignment::Start,
1596                indent: Default::default(),
1597                wrap: MeasureTextWrap::Wrap,
1598                word_break: Default::default(),
1599                max_lines: None,
1600                overflow: MeasureTextOverflow::Clip,
1601            }),
1602            MeasurementKind::ReplacedContent => {
1603                MeasurementPayload::ReplacedContent(ReplacedContentMeasurePayload::default())
1604            }
1605            MeasurementKind::NativeControl => {
1606                MeasurementPayload::NativeControl(NativeControlMeasurePayload {
1607                    control_type: 1,
1608                    version: 1,
1609                    state: Vec::new(),
1610                })
1611            }
1612            MeasurementKind::EmbeddedSurface => {
1613                MeasurementPayload::EmbeddedSurface(EmbeddedSurfaceMeasurePayload {
1614                    surface: SurfaceId::new(2).expect("child surface"),
1615                    preferred_size: None,
1616                })
1617            }
1618            MeasurementKind::Custom { version } => {
1619                MeasurementPayload::Custom(CustomMeasurePayload {
1620                    version,
1621                    data: whisker_protocol::WhiskerValue::Bytes(Vec::new()),
1622                })
1623            }
1624        }
1625    }
1626
1627    fn measurement_metrics(width: f32, height: f32) -> MeasurementMetrics {
1628        MeasurementMetrics::from_size(MeasuredSize::new(width, height))
1629    }
1630
1631    fn present_and_accept(
1632        surface: &mut SurfaceEngine,
1633        renderer: &mut RecordingRenderer,
1634        viewport_epoch: u32,
1635    ) -> FramePacket {
1636        let packet = surface
1637            .prepare_frame(viewport_epoch)
1638            .expect("prepare frame")
1639            .expect("pending work")
1640            .clone();
1641        let revision = packet.header.target_revision;
1642        assert_eq!(
1643            renderer.present(&packet),
1644            Ok(ApplyResult::Accepted { revision })
1645        );
1646        surface.accept_pending(revision).expect("accept frame");
1647        packet
1648    }
1649
1650    fn layout_operation_count(packet: &FramePacket) -> usize {
1651        packet
1652            .operations
1653            .iter()
1654            .filter(|operation| matches!(operation, Operation::SetLayout { .. }))
1655            .count()
1656    }
1657
1658    #[test]
1659    fn layout_snapshot_projects_only_changed_geometry_into_frames() {
1660        let mut surface = SurfaceEngine::new(surface_id());
1661        assert_eq!(surface.surface(), surface_id());
1662        assert!(surface.scene().has_pending_work());
1663        assert!(surface.has_pending_work());
1664        assert!(surface.layout_tree().is_empty());
1665        assert_eq!(surface.last_layout(), None);
1666        assert!(!surface.needs_layout());
1667        assert_eq!(LayoutUpdate::default().changed_nodes(), 0);
1668        assert!(!LayoutUpdate::default().recomputed());
1669        assert_eq!(
1670            zero_measure(
1671                node_id(1),
1672                MeasureRequest {
1673                    known_dimensions: [None, None],
1674                    available_space: [AvailableSpace::MaxContent; 2],
1675                },
1676            ),
1677            LayoutSize::default()
1678        );
1679
1680        let root = surface
1681            .create_node(element_type(), sized(100.0, 20.0))
1682            .unwrap();
1683        let left = surface
1684            .create_node(element_type(), sized(10.0, 10.0))
1685            .unwrap();
1686        let right = surface
1687            .create_node(element_type(), sized(10.0, 10.0))
1688            .unwrap();
1689        surface.insert_child(root, left, 0).unwrap();
1690        surface.insert_child(root, right, 1).unwrap();
1691        assert_eq!(surface.node(root).unwrap().children(), [left, right]);
1692        assert_eq!(surface.layout_tree().len(), 3);
1693        assert!(surface.needs_layout());
1694
1695        let first = surface
1696            .compute_layout(root, LayoutSize::new(100.0, 20.0), &mut zero_measure)
1697            .unwrap();
1698        assert!(first.recomputed());
1699        assert_eq!(first.changed_nodes(), 3);
1700        assert!(!surface.needs_layout());
1701        assert_eq!(surface.last_layout().unwrap().len(), 3);
1702
1703        let mut renderer = RecordingRenderer::new(surface_id());
1704        let snapshot = present_and_accept(&mut surface, &mut renderer, 1);
1705        assert_eq!(snapshot.header.mode, FrameMode::Snapshot);
1706        assert_eq!(layout_operation_count(&snapshot), 3);
1707        assert!(!surface.has_pending_work());
1708
1709        let idle = surface
1710            .compute_layout(root, LayoutSize::new(100.0, 20.0), &mut zero_measure)
1711            .unwrap();
1712        assert!(!idle.recomputed());
1713        assert_eq!(idle.changed_nodes(), 0);
1714        assert!(surface.prepare_frame(2).unwrap().is_none());
1715
1716        let impact = surface
1717            .update_layout_style(left, sized(20.0, 10.0))
1718            .unwrap();
1719        assert!(impact.contains(PropertyImpactSet::LAYOUT));
1720        let changed = surface
1721            .compute_layout(root, LayoutSize::new(100.0, 20.0), &mut zero_measure)
1722            .unwrap();
1723        assert!(changed.recomputed());
1724        assert_eq!(changed.changed_nodes(), 2);
1725        let delta = present_and_accept(&mut surface, &mut renderer, 2);
1726        assert_eq!(delta.header.mode, FrameMode::Delta);
1727        assert_eq!(layout_operation_count(&delta), 2);
1728    }
1729
1730    #[test]
1731    fn transform_style_projects_before_and_after_layout_and_rejects_invalid_matrices() {
1732        let resolved = |function| {
1733            resolve_style(
1734                &SpecifiedStyle::new().push(
1735                    StyleProperty::Transform,
1736                    StyleValue::Transform(TransformValue(vec![function])),
1737                ),
1738                None,
1739                StyleEnvironment::default(),
1740            )
1741            .unwrap()
1742        };
1743        let translated = resolved(TransformFunctionValue::TranslateX(
1744            LengthPercentageValue::Percentage(StyleNumber::new(50.0)),
1745        ));
1746        let mut surface = SurfaceEngine::new(surface_id());
1747        let root = surface
1748            .create_node(element_type(), translated.computed().layout().clone())
1749            .unwrap();
1750        surface
1751            .update_computed_style(root, translated.computed())
1752            .unwrap();
1753        assert_eq!(surface.node(root).unwrap().transform(), None);
1754        surface
1755            .compute_layout(root, LayoutSize::new(40.0, 20.0), &mut zero_measure)
1756            .unwrap();
1757        let projected = surface.node(root).unwrap().transform().unwrap();
1758        assert_eq!(projected.0[12], 20.0);
1759
1760        let rotated = resolved(TransformFunctionValue::Rotate(
1761            StyleNumber::new(90.0).into(),
1762        ));
1763        assert!(
1764            surface
1765                .update_computed_style(root, rotated.computed())
1766                .unwrap()
1767                .contains(PropertyImpactSet::PAINT)
1768        );
1769        assert_ne!(surface.node(root).unwrap().transform(), Some(projected));
1770
1771        let huge = resolved(TransformFunctionValue::Matrix([
1772            StyleNumber::new(f32::MAX),
1773            StyleNumber::new(0.0),
1774            StyleNumber::new(0.0),
1775            StyleNumber::new(1.0),
1776            StyleNumber::new(0.0),
1777            StyleNumber::new(0.0),
1778        ]));
1779        assert_eq!(
1780            surface.update_computed_style(root, huge.computed()),
1781            Err(SurfaceError::InvalidTransformOutput { node: root })
1782        );
1783
1784        let mut values = [StyleNumber::new(0.0); 16];
1785        values[0] = StyleNumber::new(f32::NAN);
1786        let invalid = ComputedTransformStyle {
1787            functions: vec![ComputedTransformFunction::Matrix(values)],
1788            ..ComputedTransformStyle::default()
1789        };
1790        assert_eq!(
1791            surface.resolve_node_transform(root, &invalid, 40.0, 20.0),
1792            Err(SurfaceError::InvalidTransformOutput { node: root })
1793        );
1794
1795        let mut invalid_projection = SurfaceEngine::new(surface_id());
1796        let invalid_root = invalid_projection
1797            .create_node(element_type(), sized(40.0, 20.0))
1798            .unwrap();
1799        Rc::make_mut(&mut invalid_projection.transforms).insert(invalid_root, invalid.clone());
1800        assert_eq!(
1801            invalid_projection.compute_layout(
1802                invalid_root,
1803                LayoutSize::new(40.0, 20.0),
1804                &mut zero_measure,
1805            ),
1806            Err(SurfaceError::InvalidTransformOutput { node: invalid_root })
1807        );
1808
1809        let mut empty_surface = SurfaceEngine::new(surface_id());
1810        let empty = empty_surface
1811            .create_node(element_type(), ComputedLayoutStyle::default())
1812            .unwrap();
1813        assert_eq!(
1814            empty_surface
1815                .resolve_node_transform(empty, &ComputedTransformStyle::default(), 1.0, 1.0)
1816                .unwrap(),
1817            None
1818        );
1819        empty_surface
1820            .set_transform(empty, whisker_protocol::Transform::IDENTITY)
1821            .unwrap();
1822        assert_eq!(
1823            empty_surface.set_transform(node_id(99), whisker_protocol::Transform::IDENTITY),
1824            Err(SurfaceError::Scene(SceneError::UnknownNode {
1825                node: node_id(99)
1826            }))
1827        );
1828        assert_eq!(
1829            empty_surface
1830                .resolve_node_transform(empty, &ComputedTransformStyle::default(), 1.0, 1.0)
1831                .unwrap(),
1832            Some(whisker_protocol::Transform::IDENTITY)
1833        );
1834
1835        let point = |x, y| whisker_style::MotionPathPointValue {
1836            x: StyleNumber::new(x),
1837            y: StyleNumber::new(y),
1838        };
1839        let motion = ComputedTransformStyle {
1840            offset_path: whisker_style::ComputedOffsetPathValue::Path(vec![
1841                whisker_style::MotionPathCommandValue::MoveTo(point(0.0, 0.0)),
1842                whisker_style::MotionPathCommandValue::LineTo(point(10.0, 0.0)),
1843            ]),
1844            offset_distance: StyleNumber::new(0.5),
1845            ..ComputedTransformStyle::default()
1846        };
1847        assert_eq!(
1848            empty_surface
1849                .resolve_node_transform(empty, &motion, 1.0, 1.0)
1850                .unwrap()
1851                .unwrap()
1852                .0[12],
1853            5.0
1854        );
1855    }
1856
1857    #[test]
1858    fn computed_paint_and_input_wrappers_share_the_retained_scene() {
1859        let resolved = resolve_style(
1860            &SpecifiedStyle::new(),
1861            None,
1862            StyleEnvironment::new(100.0, 100.0, 1.0, 14.0),
1863        )
1864        .unwrap();
1865        let style = resolved.computed();
1866        let mut surface = SurfaceEngine::new(surface_id());
1867        let root = surface
1868            .create_node(element_type(), style.layout().clone())
1869            .unwrap();
1870        let missing = node_id(99);
1871
1872        let background = resource_background(1);
1873        surface
1874            .set_background_layers(root, vec![background.clone()])
1875            .unwrap();
1876        assert_eq!(
1877            surface.node(root).unwrap().background_layers(),
1878            std::slice::from_ref(&background)
1879        );
1880        assert_eq!(
1881            surface.set_background_layers(missing, vec![background]),
1882            Err(SurfaceError::Scene(SceneError::UnknownNode {
1883                node: missing
1884            }))
1885        );
1886        let mut invalid_background = resource_background(2);
1887        invalid_background.position.x = PaintCoordinate {
1888            length: f32::NAN,
1889            fraction: 0.0,
1890        };
1891        assert_eq!(
1892            surface.set_background_layers(root, vec![invalid_background]),
1893            Err(SurfaceError::Scene(SceneError::InvalidBackgroundLayers))
1894        );
1895
1896        assert_eq!(
1897            surface.update_computed_style(missing, style),
1898            Err(SurfaceError::Scene(SceneError::UnknownNode {
1899                node: missing
1900            }))
1901        );
1902        let first = surface.update_computed_style(root, style).unwrap();
1903        assert!(first.contains(PropertyImpactSet::PAINT));
1904        let lowered = lower_paint(style.paint(), style.layout());
1905        let node = surface.node(root).unwrap();
1906        assert_eq!(node.box_paint(), Some(&lowered.box_paint));
1907        assert_eq!(node.clip(), Some(lowered.clip));
1908        assert_eq!(node.opacity(), Some(lowered.opacity));
1909        assert_eq!(node.visibility(), Some(lowered.visibility));
1910        assert_eq!(node.z_order(), Some(lowered.z_order));
1911        assert_eq!(node.hit_test(), Some(HitTestBehavior::Auto));
1912        assert_eq!(
1913            node.cursor().map(|cursor| cursor.fallback),
1914            Some(whisker_protocol::CursorKeyword::Auto)
1915        );
1916        surface.set_opacity(root, 0.5).unwrap();
1917        assert_eq!(surface.node(root).unwrap().opacity(), Some(0.5));
1918        assert_eq!(
1919            surface.set_opacity(missing, 0.5),
1920            Err(SurfaceError::Scene(SceneError::UnknownNode {
1921                node: missing
1922            }))
1923        );
1924        surface.set_opacity(root, lowered.opacity).unwrap();
1925        assert!(
1926            surface
1927                .update_computed_style(root, style)
1928                .unwrap()
1929                .is_empty()
1930        );
1931
1932        let mut different_box = lowered.box_paint.clone();
1933        different_box.background_color = whisker_protocol::PaintColor::Named("changed".into());
1934        surface.set_box_paint(root, different_box).unwrap();
1935        assert!(
1936            surface
1937                .update_computed_style(root, style)
1938                .unwrap()
1939                .contains(PropertyImpactSet::PAINT)
1940        );
1941        surface
1942            .set_plain_text(root, &PlainTextInput::new("animated"), style)
1943            .unwrap();
1944        surface.set_text_style(root, style).unwrap();
1945        let text_style = lower_text_style(style);
1946        assert_eq!(surface.node(root).unwrap().text_style(), Some(&text_style));
1947        surface
1948            .set_text_style_snapshot(root, text_style.clone())
1949            .unwrap();
1950        assert_eq!(
1951            surface.set_text_style(missing, style),
1952            Err(SurfaceError::Scene(SceneError::UnknownNode {
1953                node: missing
1954            }))
1955        );
1956        assert_eq!(
1957            surface.set_text_style_snapshot(missing, text_style),
1958            Err(SurfaceError::Scene(SceneError::UnknownNode {
1959                node: missing
1960            }))
1961        );
1962        let mut text = surface.node(root).unwrap().text().unwrap().clone();
1963        text.paint.foreground = whisker_protocol::PaintColor::Srgba {
1964            red: 255,
1965            green: 0,
1966            blue: 0,
1967            alpha: 1.0,
1968        };
1969        surface.set_text_content(root, text.clone()).unwrap();
1970        assert_eq!(surface.node(root).unwrap().text(), Some(&text));
1971        assert_eq!(
1972            surface.set_text_content(missing, text),
1973            Err(SurfaceError::Scene(SceneError::UnknownNode {
1974                node: missing
1975            }))
1976        );
1977        surface
1978            .scene
1979            .set_clip(
1980                root,
1981                whisker_protocol::BoxClip {
1982                    horizontal: whisker_protocol::OverflowClip::Hidden,
1983                    vertical: whisker_protocol::OverflowClip::Hidden,
1984                },
1985            )
1986            .unwrap();
1987        assert!(
1988            surface
1989                .update_computed_style(root, style)
1990                .unwrap()
1991                .contains(PropertyImpactSet::PAINT)
1992        );
1993        surface.scene.set_opacity(root, 0.25).unwrap();
1994        assert!(
1995            surface
1996                .update_computed_style(root, style)
1997                .unwrap()
1998                .contains(PropertyImpactSet::PAINT)
1999        );
2000        surface
2001            .scene
2002            .set_visibility(root, whisker_protocol::Visibility::Hidden)
2003            .unwrap();
2004        assert!(
2005            surface
2006                .update_computed_style(root, style)
2007                .unwrap()
2008                .contains(PropertyImpactSet::PAINT)
2009        );
2010        surface.scene.set_z_order(root, 7).unwrap();
2011        assert!(
2012            surface
2013                .update_computed_style(root, style)
2014                .unwrap()
2015                .contains(PropertyImpactSet::PAINT)
2016        );
2017
2018        let point = InputPoint { x: 5.0, y: 5.0 };
2019        assert_eq!(surface.hit_test(root, point), Ok(None));
2020        surface
2021            .scene
2022            .set_layout(
2023                root,
2024                whisker_protocol::LayoutRect {
2025                    x: 0.0,
2026                    y: 0.0,
2027                    width: 10.0,
2028                    height: 10.0,
2029                },
2030            )
2031            .unwrap();
2032        assert_eq!(surface.hit_test(root, point), Ok(Some(root)));
2033        assert_eq!(
2034            surface.hit_test(missing, point),
2035            Err(SurfaceError::Scene(SceneError::UnknownNode {
2036                node: missing
2037            }))
2038        );
2039        assert_eq!(surface.update_host_scroll_offset(root, [1.0, 2.0]), Ok(()));
2040        assert_eq!(
2041            surface.update_host_scroll_offset(root, [f32::NAN, 0.0]),
2042            Err(SurfaceError::Scene(SceneError::NonFiniteNumber))
2043        );
2044        assert_eq!(
2045            surface.update_host_scroll_offset(missing, [0.0, 0.0]),
2046            Err(SurfaceError::Scene(SceneError::UnknownNode {
2047                node: missing
2048            }))
2049        );
2050
2051        surface.set_event_mask(root, 5).unwrap();
2052        assert_eq!(surface.node(root).unwrap().event_mask(), Some(5));
2053        assert_eq!(
2054            surface.set_event_mask(missing, 1),
2055            Err(SurfaceError::Scene(SceneError::UnknownNode {
2056                node: missing
2057            }))
2058        );
2059
2060        let accessibility = Accessibility::new().label("Interactive content");
2061        surface
2062            .set_accessibility(root, accessibility.clone())
2063            .unwrap();
2064        assert_eq!(
2065            surface.node(root).unwrap().accessibility(),
2066            Some(&accessibility)
2067        );
2068        assert_eq!(
2069            surface.set_accessibility(missing, Accessibility::new()),
2070            Err(SurfaceError::Scene(SceneError::UnknownNode {
2071                node: missing
2072            }))
2073        );
2074
2075        let property = PropertyId::new(1).unwrap();
2076        assert_eq!(
2077            surface.set_property(root, property, WhiskerValue::Bool(true)),
2078            Ok(())
2079        );
2080        assert_eq!(
2081            surface.set_property(missing, property, WhiskerValue::Bool(false)),
2082            Err(SurfaceError::Scene(SceneError::UnknownNode {
2083                node: missing
2084            }))
2085        );
2086        assert_eq!(surface.clear_property(root, property), Ok(()));
2087        assert_eq!(
2088            surface.clear_property(missing, property),
2089            Err(SurfaceError::Scene(SceneError::UnknownNode {
2090                node: missing
2091            }))
2092        );
2093
2094        let command = CommandId::new(1).unwrap();
2095        assert_eq!(
2096            surface.invoke_command(root, command, WhiskerValue::Null),
2097            Ok(())
2098        );
2099        assert_eq!(
2100            surface.invoke_command(missing, command, WhiskerValue::Null),
2101            Err(SurfaceError::Scene(SceneError::UnknownNode {
2102                node: missing
2103            }))
2104        );
2105
2106        surface.set_hit_test(root, HitTestBehavior::None).unwrap();
2107        assert_eq!(surface.hit_test(root, point), Ok(None));
2108        assert_eq!(
2109            surface.set_hit_test(missing, HitTestBehavior::Auto),
2110            Err(SurfaceError::Scene(SceneError::UnknownNode {
2111                node: missing
2112            }))
2113        );
2114        let cursor = whisker_protocol::Cursor {
2115            resources: Vec::new(),
2116            fallback: whisker_protocol::CursorKeyword::Pointer,
2117        };
2118        surface.set_cursor(root, cursor.clone()).unwrap();
2119        assert_eq!(surface.node(root).unwrap().cursor(), Some(&cursor));
2120        assert_eq!(
2121            surface.set_cursor(missing, cursor),
2122            Err(SurfaceError::Scene(SceneError::UnknownNode {
2123                node: missing
2124            }))
2125        );
2126        let pointer = PointerId::new(1).unwrap();
2127        assert_eq!(surface.pointer_capture_target(pointer), None);
2128        surface.set_pointer_capture(root, pointer).unwrap();
2129        assert_eq!(surface.pointer_capture_target(pointer), Some(root));
2130        assert_eq!(
2131            surface.set_pointer_capture(missing, pointer),
2132            Err(SurfaceError::Scene(SceneError::UnknownNode {
2133                node: missing
2134            }))
2135        );
2136        assert_eq!(
2137            surface.release_pointer_capture(missing, pointer),
2138            Err(SurfaceError::Scene(SceneError::UnknownNode {
2139                node: missing
2140            }))
2141        );
2142        surface.release_pointer_capture(root, pointer).unwrap();
2143        assert_eq!(surface.pointer_capture_target(pointer), None);
2144        surface.set_pointer_capture(root, pointer).unwrap();
2145        surface.release_pointer_captures().unwrap();
2146        assert_eq!(surface.pointer_capture_target(pointer), None);
2147        surface.set_pointer_capture(root, pointer).unwrap();
2148
2149        let unsupported = resolve_style(
2150            &SpecifiedStyle::new().push(
2151                whisker_style::StyleProperty::Position,
2152                whisker_style::StyleValue::Position(PositionValue::Sticky),
2153            ),
2154            None,
2155            StyleEnvironment::default(),
2156        )
2157        .unwrap();
2158        assert_eq!(
2159            surface.update_computed_style(root, unsupported.computed()),
2160            Err(SurfaceError::Layout(LayoutError::UnsupportedStyle(
2161                UnsupportedLayoutFeature::StickyPosition
2162            )))
2163        );
2164    }
2165
2166    #[test]
2167    fn pointer_input_lowering_covers_every_retained_keyword() {
2168        assert_eq!(
2169            lower_hit_test(PointerEventsValue::Auto),
2170            HitTestBehavior::Auto
2171        );
2172        assert_eq!(
2173            lower_hit_test(PointerEventsValue::None),
2174            HitTestBehavior::None
2175        );
2176        for (value, expected) in [
2177            (CursorValue::Auto, CursorKeyword::Auto),
2178            (CursorValue::Default, CursorKeyword::Default),
2179            (CursorValue::None, CursorKeyword::None),
2180            (CursorValue::ContextMenu, CursorKeyword::ContextMenu),
2181            (CursorValue::Help, CursorKeyword::Help),
2182            (CursorValue::Pointer, CursorKeyword::Pointer),
2183            (CursorValue::Progress, CursorKeyword::Progress),
2184            (CursorValue::Wait, CursorKeyword::Wait),
2185            (CursorValue::Cell, CursorKeyword::Cell),
2186            (CursorValue::Crosshair, CursorKeyword::Crosshair),
2187            (CursorValue::Text, CursorKeyword::Text),
2188            (CursorValue::VerticalText, CursorKeyword::VerticalText),
2189            (CursorValue::Alias, CursorKeyword::Alias),
2190            (CursorValue::Copy, CursorKeyword::Copy),
2191            (CursorValue::Move, CursorKeyword::Move),
2192            (CursorValue::NoDrop, CursorKeyword::NoDrop),
2193            (CursorValue::NotAllowed, CursorKeyword::NotAllowed),
2194            (CursorValue::Grab, CursorKeyword::Grab),
2195            (CursorValue::Grabbing, CursorKeyword::Grabbing),
2196            (CursorValue::ColResize, CursorKeyword::ColResize),
2197            (CursorValue::RowResize, CursorKeyword::RowResize),
2198            (CursorValue::NResize, CursorKeyword::NResize),
2199            (CursorValue::EResize, CursorKeyword::EResize),
2200            (CursorValue::SResize, CursorKeyword::SResize),
2201            (CursorValue::WResize, CursorKeyword::WResize),
2202            (CursorValue::NeResize, CursorKeyword::NeResize),
2203            (CursorValue::NwResize, CursorKeyword::NwResize),
2204            (CursorValue::SeResize, CursorKeyword::SeResize),
2205            (CursorValue::SwResize, CursorKeyword::SwResize),
2206            (CursorValue::EwResize, CursorKeyword::EwResize),
2207            (CursorValue::NsResize, CursorKeyword::NsResize),
2208            (CursorValue::NeswResize, CursorKeyword::NeswResize),
2209            (CursorValue::NwseResize, CursorKeyword::NwseResize),
2210            (CursorValue::ZoomIn, CursorKeyword::ZoomIn),
2211            (CursorValue::ZoomOut, CursorKeyword::ZoomOut),
2212        ] {
2213            assert_eq!(
2214                lower_cursor(value),
2215                Cursor {
2216                    resources: Vec::new(),
2217                    fallback: expected,
2218                }
2219            );
2220        }
2221    }
2222
2223    #[test]
2224    fn structural_operations_keep_scene_and_layout_in_lockstep() {
2225        let mut surface = SurfaceEngine::new(surface_id());
2226        let unsupported = ComputedLayoutStyle {
2227            position: PositionValue::Fixed,
2228            ..ComputedLayoutStyle::default()
2229        };
2230        assert_eq!(
2231            surface.create_node(element_type(), unsupported),
2232            Err(SurfaceError::Layout(LayoutError::UnsupportedStyle(
2233                UnsupportedLayoutFeature::FixedPosition
2234            )))
2235        );
2236        assert_eq!(surface.scene().node_count(), 0);
2237        assert!(surface.layout_tree().is_empty());
2238
2239        let root = surface
2240            .create_node(element_type(), ComputedLayoutStyle::default())
2241            .unwrap();
2242        assert_eq!(root, node_id(1));
2243        let first = surface
2244            .create_node(element_type(), ComputedLayoutStyle::default())
2245            .unwrap();
2246        let second = surface
2247            .create_node(element_type(), ComputedLayoutStyle::default())
2248            .unwrap();
2249        let grandchild = surface
2250            .create_node(element_type(), ComputedLayoutStyle::default())
2251            .unwrap();
2252        let unknown = node_id(99);
2253
2254        assert_eq!(
2255            surface.insert_child(root, unknown, 0),
2256            Err(SurfaceError::Scene(SceneError::UnknownNode {
2257                node: unknown
2258            }))
2259        );
2260        assert_eq!(
2261            surface.remove_child(root, second),
2262            Err(SurfaceError::Scene(SceneError::NotDirectChild {
2263                parent: root,
2264                child: second,
2265            }))
2266        );
2267        surface.insert_child(root, first, 0).unwrap();
2268        surface.insert_child(root, second, 1).unwrap();
2269        surface.insert_child(first, grandchild, 0).unwrap();
2270        assert_eq!(
2271            surface.move_child(root, second, 2),
2272            Err(SurfaceError::Scene(SceneError::ChildIndexOutOfBounds {
2273                parent: root,
2274                index: 2,
2275                len: 1,
2276            }))
2277        );
2278        surface.move_child(root, second, 0).unwrap();
2279        assert_eq!(surface.node(root).unwrap().children(), [second, first]);
2280        surface.remove_child(root, second).unwrap();
2281        assert_eq!(surface.node(second).unwrap().parent(), None);
2282        surface.insert_child(first, second, 1).unwrap();
2283        assert_eq!(
2284            surface.node(first).unwrap().children(),
2285            [grandchild, second]
2286        );
2287
2288        surface.delete_node(first).unwrap();
2289        assert_eq!(surface.scene().node_count(), 1);
2290        assert_eq!(surface.layout_tree().len(), 1);
2291        assert!(!surface.layout_tree().contains(first));
2292        assert!(!surface.layout_tree().contains(second));
2293        assert!(!surface.layout_tree().contains(grandchild));
2294        assert_eq!(
2295            surface.delete_node(unknown),
2296            Err(SurfaceError::Scene(SceneError::UnknownNode {
2297                node: unknown
2298            }))
2299        );
2300        assert_eq!(
2301            surface.set_measurable(unknown, true),
2302            Err(SurfaceError::Layout(LayoutError::UnknownNode(unknown)))
2303        );
2304    }
2305
2306    #[test]
2307    fn measurement_and_impact_invalidation_schedule_only_required_layout() {
2308        let mut surface = SurfaceEngine::new(surface_id());
2309        let root = surface
2310            .create_node(element_type(), ComputedLayoutStyle::default())
2311            .unwrap();
2312        assert!(surface.set_measurable(root, true).unwrap());
2313        assert!(!surface.set_measurable(root, true).unwrap());
2314
2315        let calls = Cell::new(0);
2316        let mut measure = |_: NodeId, _: MeasureRequest| {
2317            calls.set(calls.get() + 1);
2318            LayoutSize::new(12.0, 8.0)
2319        };
2320        let first = surface
2321            .compute_layout(root, LayoutSize::new(100.0, 100.0), &mut measure)
2322            .unwrap();
2323        assert_eq!(first.changed_nodes(), 1);
2324        let first_pass_calls = calls.get();
2325        assert!(first_pass_calls > 0);
2326        let mut renderer = RecordingRenderer::new(surface_id());
2327        present_and_accept(&mut surface, &mut renderer, 1);
2328
2329        assert!(
2330            !surface
2331                .invalidate_node(root, PropertyImpactSet::PAINT)
2332                .unwrap()
2333        );
2334        assert!(!surface.needs_layout());
2335        let skipped = surface
2336            .compute_layout(root, LayoutSize::new(100.0, 100.0), &mut measure)
2337            .unwrap();
2338        assert!(!skipped.recomputed());
2339        assert_eq!(calls.get(), first_pass_calls);
2340
2341        assert!(
2342            surface
2343                .invalidate_node(root, PropertyImpactSet::TEXT_METRICS)
2344                .unwrap()
2345        );
2346        let measured = surface
2347            .compute_layout(root, LayoutSize::new(100.0, 100.0), &mut measure)
2348            .unwrap();
2349        assert!(measured.recomputed());
2350        assert_eq!(measured.changed_nodes(), 0);
2351        let invalidated_pass_calls = calls.get();
2352        assert!(invalidated_pass_calls > first_pass_calls);
2353        assert!(surface.prepare_frame(2).unwrap().is_none());
2354
2355        assert_eq!(
2356            surface.invalidate_node(node_id(99), PropertyImpactSet::LAYOUT),
2357            Err(SurfaceError::Scene(SceneError::UnknownNode {
2358                node: node_id(99)
2359            }))
2360        );
2361        surface
2362            .invalidate_node(root, PropertyImpactSet::TEXT_METRICS)
2363            .unwrap();
2364        assert_eq!(
2365            surface.compute_layout(root, LayoutSize::new(100.0, 100.0), &mut |_, _| {
2366                LayoutSize::new(f32::NAN, 1.0)
2367            },),
2368            Err(SurfaceError::Layout(LayoutError::InvalidMeasurement(root)))
2369        );
2370        assert!(surface.needs_layout());
2371        surface
2372            .compute_layout(root, LayoutSize::new(100.0, 100.0), &mut measure)
2373            .unwrap();
2374        assert!(calls.get() > invalidated_pass_calls);
2375
2376        let equal = surface
2377            .update_layout_style(root, ComputedLayoutStyle::default())
2378            .unwrap();
2379        assert!(equal.is_empty());
2380        assert!(!surface.needs_layout());
2381        let viewport_change = surface
2382            .compute_layout(root, LayoutSize::new(200.0, 100.0), &mut measure)
2383            .unwrap();
2384        assert!(viewport_change.recomputed());
2385
2386        let unsupported = ComputedLayoutStyle {
2387            position: PositionValue::Sticky,
2388            ..ComputedLayoutStyle::default()
2389        };
2390        assert_eq!(
2391            surface.update_layout_style(root, unsupported),
2392            Err(SurfaceError::Layout(LayoutError::UnsupportedStyle(
2393                UnsupportedLayoutFeature::StickyPosition
2394            )))
2395        );
2396        assert!(!surface.needs_layout());
2397        assert!(surface.set_measurable(root, false).unwrap());
2398    }
2399
2400    #[test]
2401    fn host_measurement_blocks_batches_caches_and_completes_layout() {
2402        let mut surface = SurfaceEngine::new(surface_id());
2403        let root = surface
2404            .create_node(element_type(), ComputedLayoutStyle::default())
2405            .unwrap();
2406        assert_eq!(surface.last_measurement(root), None);
2407        assert_eq!(
2408            surface.set_measurement(node_id(99), None),
2409            Err(SurfaceError::Scene(SceneError::UnknownNode {
2410                node: node_id(99)
2411            }))
2412        );
2413        assert!(
2414            surface
2415                .set_measurement(
2416                    root,
2417                    Some(measurement_spec(
2418                        MeasurementKind::Text,
2419                        PendingMeasurePolicy::Block,
2420                    )),
2421                )
2422                .unwrap()
2423        );
2424        assert!(
2425            !surface
2426                .set_measurement(
2427                    root,
2428                    Some(measurement_spec(
2429                        MeasurementKind::Text,
2430                        PendingMeasurePolicy::Block,
2431                    )),
2432                )
2433                .unwrap()
2434        );
2435
2436        let blocked = surface
2437            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2438            .unwrap();
2439        assert!(!blocked.has_layout());
2440        assert!(!blocked.requests().is_empty());
2441        assert_eq!(surface.last_layout(), None);
2442        let initial_requests = blocked.requests().to_vec();
2443
2444        let repeated = surface
2445            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2446            .unwrap();
2447        assert_eq!(repeated.requests(), initial_requests);
2448
2449        let stale = surface
2450            .apply_measurement_responses(&[MeasurementResponse::Ready {
2451                key: MeasurementKey::new(99).expect("stale key"),
2452                environment_epoch: 1,
2453                metrics: measurement_metrics(1.0, 1.0),
2454            }])
2455            .unwrap();
2456        assert_eq!(stale.applied(), 0);
2457        assert_eq!(stale.stale(), 1);
2458        assert!(surface.needs_layout());
2459
2460        let initial_responses = initial_requests
2461            .iter()
2462            .map(|request| MeasurementResponse::Ready {
2463                key: request.key,
2464                environment_epoch: 1,
2465                metrics: measurement_metrics(24.0, 12.0),
2466            })
2467            .collect::<Vec<_>>();
2468        let applied = surface
2469            .apply_measurement_responses(&initial_responses)
2470            .unwrap();
2471        assert_eq!(applied.applied(), initial_responses.len());
2472        let complete = loop {
2473            let progress = surface
2474                .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2475                .unwrap();
2476            if progress.requests().is_empty() {
2477                break progress;
2478            }
2479            let responses = progress
2480                .requests()
2481                .iter()
2482                .map(|request| MeasurementResponse::Ready {
2483                    key: request.key,
2484                    environment_epoch: 1,
2485                    metrics: measurement_metrics(24.0, 12.0),
2486                })
2487                .collect::<Vec<_>>();
2488            surface.apply_measurement_responses(&responses).unwrap();
2489        };
2490        assert!(complete.has_layout());
2491        assert!(complete.requests().is_empty());
2492        assert_eq!(
2493            complete,
2494            LayoutProgress::Complete(LayoutUpdate::computed(1))
2495        );
2496        assert_eq!(
2497            surface.last_measurement(root),
2498            Some(&measurement_metrics(24.0, 12.0))
2499        );
2500
2501        let idle = surface
2502            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2503            .unwrap();
2504        assert_eq!(idle, LayoutProgress::Complete(LayoutUpdate::default()));
2505        assert!(idle.requests().is_empty());
2506        assert!(surface.set_measurement(root, None).unwrap());
2507        assert!(!surface.set_measurement(root, None).unwrap());
2508        assert_eq!(surface.last_measurement(root), None);
2509    }
2510
2511    #[test]
2512    fn provisional_resource_measurement_relayouts_after_deferred_completion() {
2513        let mut surface = SurfaceEngine::new(surface_id());
2514        let root = surface
2515            .create_node(element_type(), ComputedLayoutStyle::default())
2516            .unwrap();
2517        surface
2518            .set_measurement(
2519                root,
2520                Some(measurement_spec(
2521                    MeasurementKind::ReplacedContent,
2522                    PendingMeasurePolicy::Placeholder(MeasuredSize::new(16.0, 9.0)),
2523                )),
2524            )
2525            .unwrap();
2526
2527        let provisional = surface
2528            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 7)
2529            .unwrap();
2530        assert!(provisional.has_layout());
2531        assert!(!provisional.requests().is_empty());
2532        let initial_requests = provisional.requests().to_vec();
2533        let idle = surface
2534            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 7)
2535            .unwrap();
2536        assert_eq!(idle.requests(), initial_requests);
2537
2538        let mut pending_measurements = Vec::new();
2539        let mut progress = provisional;
2540        let pending = loop {
2541            let requests = progress.requests().to_vec();
2542            if requests.is_empty() {
2543                break progress;
2544            }
2545            let responses = requests
2546                .iter()
2547                .map(|request| {
2548                    let request_id = MeasurementRequestId::new(100 + request.key.get())
2549                        .expect("pending request ID");
2550                    pending_measurements.push((request.key, request_id));
2551                    MeasurementResponse::Pending {
2552                        key: request.key,
2553                        environment_epoch: 7,
2554                        request_id,
2555                        provisional: Some(measurement_metrics(20.0, 10.0)),
2556                    }
2557                })
2558                .collect::<Vec<_>>();
2559            surface.apply_measurement_responses(&responses).unwrap();
2560            progress = surface
2561                .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 7)
2562                .unwrap();
2563        };
2564        assert!(matches!(
2565            pending,
2566            LayoutProgress::Provisional {
2567                update,
2568                requests,
2569                pending,
2570            } if update.recomputed() && requests.is_empty() && pending > 0
2571        ));
2572
2573        let idle_pending = surface
2574            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 7)
2575            .unwrap();
2576        assert!(matches!(
2577            idle_pending,
2578            LayoutProgress::Provisional {
2579                update,
2580                requests,
2581                pending,
2582            } if update == LayoutUpdate::default()
2583                && requests.is_empty()
2584                && pending > 0
2585        ));
2586
2587        let (key, request_id) = pending_measurements[0];
2588        let invalid_ready = MeasurementReady {
2589            key,
2590            request_id,
2591            environment_epoch: 7,
2592            metrics: measurement_metrics(f32::NAN, 1.0),
2593        };
2594        assert_eq!(
2595            surface.apply_measurement_ready(&invalid_ready),
2596            Err(SurfaceError::Measurement(
2597                MeasurementError::InvalidMetrics { key }
2598            ))
2599        );
2600
2601        let stale = MeasurementReady {
2602            key: MeasurementKey::new(key.get() + 10_000).expect("wrong key"),
2603            request_id,
2604            environment_epoch: 7,
2605            metrics: measurement_metrics(32.0, 18.0),
2606        };
2607        assert_eq!(
2608            surface.apply_measurement_ready(&stale).unwrap(),
2609            DeferredMeasurementApply::IgnoredStale
2610        );
2611        assert!(!surface.needs_layout());
2612
2613        let ready = MeasurementReady { key, ..stale };
2614        assert_eq!(
2615            surface.apply_measurement_ready(&ready).unwrap(),
2616            DeferredMeasurementApply::Applied {
2617                invalidated_nodes: vec![root]
2618            }
2619        );
2620        assert!(surface.needs_layout());
2621        for (key, request_id) in pending_measurements.into_iter().skip(1) {
2622            assert_eq!(
2623                surface
2624                    .apply_measurement_ready(&MeasurementReady {
2625                        key,
2626                        request_id,
2627                        environment_epoch: 7,
2628                        metrics: measurement_metrics(32.0, 18.0),
2629                    })
2630                    .unwrap(),
2631                DeferredMeasurementApply::Applied {
2632                    invalidated_nodes: vec![root]
2633                }
2634            );
2635        }
2636        let complete = loop {
2637            let progress = surface
2638                .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 7)
2639                .unwrap();
2640            if progress.requests().is_empty() {
2641                break progress;
2642            }
2643            let responses = progress
2644                .requests()
2645                .iter()
2646                .map(|request| MeasurementResponse::Ready {
2647                    key: request.key,
2648                    environment_epoch: 7,
2649                    metrics: measurement_metrics(32.0, 18.0),
2650                })
2651                .collect::<Vec<_>>();
2652            surface.apply_measurement_responses(&responses).unwrap();
2653        };
2654        assert!(matches!(complete, LayoutProgress::Complete(update) if update.recomputed()));
2655        assert_eq!(
2656            surface.last_measurement(root),
2657            Some(&measurement_metrics(32.0, 18.0))
2658        );
2659
2660        let new_environment = surface
2661            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 8)
2662            .unwrap();
2663        assert!(new_environment.has_layout());
2664        assert!(!new_environment.requests().is_empty());
2665    }
2666
2667    #[test]
2668    fn invalid_and_unsupported_measurement_surface_diagnostics() {
2669        assert_eq!(
2670            measurement_spec(
2671                MeasurementKind::EmbeddedSurface,
2672                PendingMeasurePolicy::Block
2673            )
2674            .payload
2675            .kind(),
2676            MeasurementKind::EmbeddedSurface
2677        );
2678        assert_eq!(
2679            measurement_spec(
2680                MeasurementKind::Custom { version: 1 },
2681                PendingMeasurePolicy::Block
2682            )
2683            .payload
2684            .kind(),
2685            MeasurementKind::Custom { version: 1 }
2686        );
2687        let mut surface = SurfaceEngine::new(surface_id());
2688        let root = surface
2689            .create_node(element_type(), ComputedLayoutStyle::default())
2690            .unwrap();
2691        let invalid = measurement_spec(
2692            MeasurementKind::NativeControl,
2693            PendingMeasurePolicy::Placeholder(MeasuredSize::new(f32::NAN, 1.0)),
2694        );
2695        assert_eq!(
2696            surface.set_measurement(root, Some(invalid)),
2697            Err(SurfaceError::Measurement(
2698                MeasurementError::InvalidPlaceholder { node: root }
2699            ))
2700        );
2701
2702        surface
2703            .set_measurement(
2704                root,
2705                Some(measurement_spec(
2706                    MeasurementKind::NativeControl,
2707                    PendingMeasurePolicy::Block,
2708                )),
2709            )
2710            .unwrap();
2711        let blocked = surface
2712            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2713            .unwrap();
2714        let request = blocked.requests()[0].clone();
2715        assert_eq!(
2716            surface.apply_measurement_responses(&[MeasurementResponse::Ready {
2717                key: request.key,
2718                environment_epoch: 1,
2719                metrics: measurement_metrics(f32::NAN, 1.0),
2720            }]),
2721            Err(SurfaceError::Measurement(
2722                MeasurementError::InvalidMetrics { key: request.key }
2723            ))
2724        );
2725        surface
2726            .apply_measurement_responses(&[MeasurementResponse::Unsupported {
2727                key: request.key,
2728                environment_epoch: 1,
2729                reason: UnsupportedMeasurementReason::Environment,
2730            }])
2731            .unwrap();
2732        let error = surface
2733            .compute_layout_with_measurements(root, LayoutSize::new(100.0, 100.0), 1)
2734            .unwrap_err();
2735        assert_eq!(
2736            error,
2737            SurfaceError::Measurement(MeasurementError::Unsupported {
2738                node: root,
2739                reason: UnsupportedMeasurementReason::Environment,
2740            })
2741        );
2742        assert!(error.source().is_some());
2743        assert_eq!(
2744            format!("{}", MeasurementError::KeyExhausted),
2745            "Whisker measurement error: KeyExhausted"
2746        );
2747    }
2748
2749    #[test]
2750    fn prepared_frame_blocks_every_layout_mutation_until_resolved() {
2751        let mut surface = SurfaceEngine::new(surface_id());
2752        let root = surface
2753            .create_node(element_type(), ComputedLayoutStyle::default())
2754            .unwrap();
2755        let computed =
2756            resolve_style(&SpecifiedStyle::new(), None, StyleEnvironment::default()).unwrap();
2757        let lowered = lower_paint(computed.computed().paint(), computed.computed().layout());
2758        let pending = surface.prepare_frame(1).unwrap().unwrap().clone();
2759        assert!(surface.scene().has_prepared_frame());
2760        assert_eq!(
2761            surface.create_node(element_type(), ComputedLayoutStyle::default()),
2762            Err(SurfaceError::Scene(SceneError::FramePending))
2763        );
2764        assert_eq!(
2765            surface.update_layout_style(root, ComputedLayoutStyle::default()),
2766            Err(SurfaceError::Scene(SceneError::FramePending))
2767        );
2768        assert_eq!(
2769            surface.update_computed_style(root, computed.computed()),
2770            Err(SurfaceError::Scene(SceneError::FramePending))
2771        );
2772        assert_eq!(
2773            surface.scene.set_box_paint(root, lowered.box_paint),
2774            Err(SceneError::FramePending)
2775        );
2776        assert_eq!(
2777            surface.set_background_layers(root, vec![resource_background(1)]),
2778            Err(SurfaceError::Scene(SceneError::FramePending))
2779        );
2780        assert_eq!(
2781            surface
2782                .scene
2783                .set_background_layers(root, vec![resource_background(1)]),
2784            Err(SceneError::FramePending)
2785        );
2786        assert_eq!(
2787            surface.scene.set_clip(root, lowered.clip),
2788            Err(SceneError::FramePending)
2789        );
2790        assert_eq!(
2791            surface.set_cursor(
2792                root,
2793                Cursor {
2794                    resources: Vec::new(),
2795                    fallback: CursorKeyword::Pointer,
2796                },
2797            ),
2798            Err(SurfaceError::Scene(SceneError::FramePending))
2799        );
2800        assert_eq!(
2801            surface.set_measurable(root, true),
2802            Err(SurfaceError::Scene(SceneError::FramePending))
2803        );
2804        assert_eq!(
2805            surface.set_measurement(root, None),
2806            Err(SurfaceError::Scene(SceneError::FramePending))
2807        );
2808        assert_eq!(
2809            surface.invalidate_node(root, PropertyImpactSet::LAYOUT),
2810            Err(SurfaceError::Scene(SceneError::FramePending))
2811        );
2812        assert_eq!(
2813            surface.compute_layout(root, LayoutSize::new(1.0, 1.0), &mut zero_measure),
2814            Err(SurfaceError::Scene(SceneError::FramePending))
2815        );
2816        assert_eq!(
2817            surface.compute_layout_with_measurements(root, LayoutSize::new(1.0, 1.0), 1),
2818            Err(SurfaceError::Scene(SceneError::FramePending))
2819        );
2820        assert_eq!(
2821            surface.apply_measurement_responses(&[]),
2822            Err(SurfaceError::Scene(SceneError::FramePending))
2823        );
2824        let fake_ready = MeasurementReady {
2825            key: MeasurementKey::new(1).expect("key"),
2826            request_id: MeasurementRequestId::new(1).expect("request"),
2827            environment_epoch: 1,
2828            metrics: measurement_metrics(1.0, 1.0),
2829        };
2830        assert_eq!(
2831            surface.apply_measurement_ready(&fake_ready),
2832            Err(SurfaceError::Scene(SceneError::FramePending))
2833        );
2834        assert_eq!(
2835            surface.delete_node(root),
2836            Err(SurfaceError::Scene(SceneError::FramePending))
2837        );
2838        assert_eq!(
2839            surface.prepare_frame(1),
2840            Err(SurfaceError::Scene(SceneError::FramePending))
2841        );
2842
2843        surface.discard_pending().unwrap();
2844        assert!(!surface.scene().has_prepared_frame());
2845        let retried = surface.prepare_frame(1).unwrap().unwrap().clone();
2846        assert!(retried.header.frame_id > pending.header.frame_id);
2847        surface.require_snapshot().unwrap();
2848        assert!(!surface.scene().has_prepared_frame());
2849
2850        let mut renderer = RecordingRenderer::new(surface_id());
2851        let snapshot = present_and_accept(&mut surface, &mut renderer, 1);
2852        assert_eq!(snapshot.header.mode, FrameMode::Snapshot);
2853        assert_eq!(
2854            surface.accept_pending(snapshot.header.target_revision),
2855            Err(SurfaceError::Scene(SceneError::NoPendingFrame))
2856        );
2857        assert_eq!(
2858            surface.discard_pending(),
2859            Err(SurfaceError::Scene(SceneError::NoPendingFrame))
2860        );
2861        surface.require_snapshot().unwrap();
2862        let recovery = present_and_accept(&mut surface, &mut renderer, 2);
2863        assert_eq!(recovery.header.mode, FrameMode::Snapshot);
2864    }
2865
2866    #[test]
2867    fn projection_validation_and_error_sources_are_diagnostic() {
2868        let mut scene = Scene::new(surface_id());
2869        let live = scene.create_node(element_type()).unwrap();
2870        let valid = LayoutRect {
2871            width: 1.0,
2872            height: 1.0,
2873            ..LayoutRect::default()
2874        };
2875        assert_eq!(
2876            validate_layout_entries(&scene, &[(live, valid.into())]),
2877            Ok(())
2878        );
2879        assert_eq!(
2880            validate_layout_entries(&scene, &[(node_id(99), valid.into())]),
2881            Err(SurfaceError::SceneLayoutMismatch { node: node_id(99) })
2882        );
2883        let invalid = LayoutRect {
2884            width: f32::INFINITY,
2885            ..valid
2886        };
2887        assert_eq!(
2888            validate_layout_entries(&scene, &[(live, invalid.into())]),
2889            Err(SurfaceError::InvalidLayoutOutput { node: live })
2890        );
2891
2892        let mut missing_layout = SurfaceEngine::new(surface_id());
2893        let scene_only = missing_layout.scene.create_node(element_type()).unwrap();
2894        assert_eq!(
2895            missing_layout.set_measurement(scene_only, None),
2896            Err(SurfaceError::Layout(LayoutError::UnknownNode(scene_only)))
2897        );
2898        assert_eq!(
2899            missing_layout.invalidate_node(scene_only, PropertyImpactSet::TEXT_METRICS),
2900            Err(SurfaceError::Layout(LayoutError::UnknownNode(scene_only)))
2901        );
2902
2903        let mut missing_scene = SurfaceEngine::new(surface_id());
2904        let layout_only = missing_scene
2905            .create_node(element_type(), ComputedLayoutStyle::default())
2906            .unwrap();
2907        missing_scene.scene.delete_node(layout_only).unwrap();
2908        assert_eq!(
2909            missing_scene
2910                .compute_layout(layout_only, LayoutSize::new(1.0, 1.0), &mut zero_measure,),
2911            Err(SurfaceError::SceneLayoutMismatch { node: layout_only })
2912        );
2913
2914        let mut missing_host_scene = SurfaceEngine::new(surface_id());
2915        let host_layout_only = missing_host_scene
2916            .create_node(element_type(), ComputedLayoutStyle::default())
2917            .unwrap();
2918        missing_host_scene
2919            .scene
2920            .delete_node(host_layout_only)
2921            .unwrap();
2922        assert_eq!(
2923            missing_host_scene.compute_layout_with_measurements(
2924                host_layout_only,
2925                LayoutSize::new(1.0, 1.0),
2926                1,
2927            ),
2928            Err(SurfaceError::SceneLayoutMismatch {
2929                node: host_layout_only
2930            })
2931        );
2932
2933        let mut invalid_host_layout = SurfaceEngine::new(surface_id());
2934        let host_root = invalid_host_layout
2935            .create_node(element_type(), ComputedLayoutStyle::default())
2936            .unwrap();
2937        assert_eq!(
2938            invalid_host_layout.compute_layout_with_measurements(
2939                host_root,
2940                LayoutSize::new(f32::NAN, 1.0),
2941                1,
2942            ),
2943            Err(SurfaceError::Layout(LayoutError::InvalidViewport))
2944        );
2945        assert_eq!(
2946            invalid_host_layout.compute_layout_with_measurements(
2947                node_id(99),
2948                LayoutSize::new(1.0, 1.0),
2949                1,
2950            ),
2951            Err(SurfaceError::Layout(LayoutError::UnknownNode(node_id(99))))
2952        );
2953
2954        let scene_error = SurfaceError::from(SceneError::NoPendingFrame);
2955        let layout_error = SurfaceError::from(LayoutError::InvalidViewport);
2956        assert!(scene_error.source().is_some());
2957        assert!(layout_error.source().is_some());
2958        assert!(
2959            SurfaceError::SceneLayoutMismatch { node: live }
2960                .source()
2961                .is_none()
2962        );
2963        assert!(
2964            SurfaceError::InvalidLayoutOutput { node: live }
2965                .source()
2966                .is_none()
2967        );
2968        assert_eq!(
2969            format!("{layout_error}"),
2970            "Whisker surface error: Layout(InvalidViewport)"
2971        );
2972    }
2973
2974    #[test]
2975    fn present_applies_acknowledgements_recovery_and_retry() {
2976        enum SinkBehavior {
2977            Record,
2978            Fail,
2979            WrongRevision,
2980            NeedSnapshot,
2981        }
2982
2983        struct TestSink {
2984            behavior: SinkBehavior,
2985            renderer: RecordingRenderer,
2986        }
2987
2988        impl TestSink {
2989            fn new(surface: SurfaceId) -> Self {
2990                Self {
2991                    behavior: SinkBehavior::Record,
2992                    renderer: RecordingRenderer::new(surface),
2993                }
2994            }
2995        }
2996
2997        impl FrameSink for TestSink {
2998            type Error = &'static str;
2999
3000            fn capabilities(&self) -> whisker_protocol::RenderCapabilities {
3001                self.renderer.capabilities()
3002            }
3003
3004            fn present(&mut self, packet: &FramePacket) -> Result<ApplyResult, Self::Error> {
3005                match self.behavior {
3006                    SinkBehavior::Record => self
3007                        .renderer
3008                        .present(packet)
3009                        .map_err(|_| "recording renderer rejected frame"),
3010                    SinkBehavior::Fail => Err("transport"),
3011                    SinkBehavior::WrongRevision => Ok(ApplyResult::Accepted {
3012                        revision: packet.header.target_revision + 1,
3013                    }),
3014                    SinkBehavior::NeedSnapshot => Ok(ApplyResult::NeedSnapshot {
3015                        receiver_revision: 0,
3016                    }),
3017                }
3018            }
3019        }
3020
3021        let mut surface = SurfaceEngine::new(surface_id());
3022        let root = surface
3023            .create_node(element_type(), ComputedLayoutStyle::default())
3024            .unwrap();
3025        let mut sink = TestSink::new(surface_id());
3026        assert_eq!(
3027            sink.capabilities(),
3028            whisker_protocol::RenderCapabilities::all_frame_native()
3029        );
3030        let already_prepared = surface.prepare_frame(1).unwrap().unwrap().clone();
3031        assert_eq!(
3032            surface.present(1, &mut sink),
3033            Err(SurfacePresentError::Surface(SurfaceError::Scene(
3034                SceneError::FramePending
3035            )))
3036        );
3037        surface
3038            .accept_pending(already_prepared.header.target_revision)
3039            .unwrap();
3040        assert_eq!(surface.present(1, &mut sink), Ok(None));
3041        assert_eq!(surface.scene().accepted_revision(), 1);
3042
3043        surface
3044            .scene
3045            .set_visibility(root, whisker_protocol::Visibility::Hidden)
3046            .unwrap();
3047        sink.renderer = RecordingRenderer::new(surface_id());
3048        assert_eq!(
3049            surface.present(1, &mut sink),
3050            Ok(Some(ApplyResult::NeedSnapshot {
3051                receiver_revision: 0
3052            }))
3053        );
3054        assert_eq!(surface.scene().accepted_revision(), 1);
3055        assert_eq!(
3056            surface.present(1, &mut sink),
3057            Ok(Some(ApplyResult::Accepted { revision: 2 }))
3058        );
3059        assert_eq!(
3060            sink.renderer.frames()[1].packet.header.mode,
3061            FrameMode::Snapshot
3062        );
3063
3064        surface.scene.set_z_order(root, 5).unwrap();
3065        sink.behavior = SinkBehavior::Fail;
3066        assert_eq!(
3067            surface.present(1, &mut sink),
3068            Err(SurfacePresentError::Sink("transport"))
3069        );
3070        assert!(surface.has_pending_work());
3071        sink.behavior = SinkBehavior::Record;
3072        assert_eq!(
3073            surface.present(1, &mut sink),
3074            Ok(Some(ApplyResult::Accepted { revision: 3 }))
3075        );
3076        assert_eq!(
3077            sink.renderer.frames().last().unwrap().packet.header.mode,
3078            FrameMode::Snapshot
3079        );
3080        assert_eq!(surface.present(1, &mut sink), Ok(None));
3081
3082        surface.scene.set_opacity(root, 0.4).unwrap();
3083        sink.behavior = SinkBehavior::WrongRevision;
3084        assert_eq!(
3085            surface.present(1, &mut sink),
3086            Err(SurfacePresentError::Surface(SurfaceError::Scene(
3087                SceneError::AcceptedRevisionMismatch {
3088                    expected: 4,
3089                    received: 5,
3090                }
3091            )))
3092        );
3093        assert!(surface.has_pending_work());
3094        sink.behavior = SinkBehavior::Record;
3095        assert_eq!(
3096            surface.present(1, &mut sink),
3097            Ok(Some(ApplyResult::Accepted { revision: 4 }))
3098        );
3099        assert_eq!(
3100            sink.renderer.frames().last().unwrap().packet.header.mode,
3101            FrameMode::Snapshot
3102        );
3103
3104        surface.scene.set_scene_epoch_for_tests(u32::MAX);
3105        surface.scene.set_opacity(root, 0.6).unwrap();
3106        sink.behavior = SinkBehavior::NeedSnapshot;
3107        assert_eq!(
3108            surface.present(1, &mut sink),
3109            Err(SurfacePresentError::Surface(SurfaceError::Scene(
3110                SceneError::SceneEpochExhausted
3111            )))
3112        );
3113
3114        let display = SurfacePresentError::<std::io::Error>::Surface(SurfaceError::Scene(
3115            SceneError::NoPendingFrame,
3116        ));
3117        assert!(display.source().is_some());
3118        assert!(format!("{display}").starts_with("Whisker surface presentation error:"));
3119        let sink = SurfacePresentError::Sink(std::io::Error::other("sink"));
3120        assert!(sink.source().is_some());
3121    }
3122}
3123
3124#[cfg(test)]
3125#[path = "surface_paragraph_tests.rs"]
3126mod paragraph_tests;